Estilização

Só tokens semânticos

Os componentes tiram todas as cores dos tokens do shadcn, então o modo claro, o escuro e um tema novo funcionam sem mexer no código deles. Faça o mesmo na sua própria marcação.

<%# Wrong: hardcoded colours and a hand-written dark override %>
<%= ui_card(class: "bg-white text-gray-900 dark:bg-gray-900 dark:text-white") do %>

<%# Right: the tokens already cover both modes %>
<%= ui_card do %>

Os tokens vêm em pares, <superfície> e <superfície>-foreground: bg-primary text-primary-foreground, bg-muted text-muted-foreground, bg-destructive text-destructive-foreground. A lista completa está na página Theming.

Não use dark: para definir cores. Deixe o prefixo para diferenças que não são de cor, como mostrar outra imagem no modo escuro.

class: e class_name: são a mesma coisa

As duas vão para o mesmo lugar. Use a que preferir; class: é a forma mais comum em código Rails.

<%= ui_button(class: "w-full") { "Save" } %>
<%= ui_button(class_name: "w-full") { "Save" } %>

As suas classes têm prioridade

As classes são combinadas nesta ordem, com as suas por último:

base_classes → variant_classes → size_classes → your class

Quando duas classes definem a mesma propriedade, como o w-full do componente e o seu w-80, a primeira é descartada, do mesmo jeito que o cn() faz no shadcn/ui. Sem isso, as duas iriam para o elemento e valeria a que o Tailwind gerasse por último. Isso funciona para os utilitários mais comuns: cor, texto, tamanho, espaçamento, raio, sombra, display, posição e alinhamento. Para o resto, termine a sua classe com ! para forçá-la.

Então o class: consegue sobrescrever as classes do próprio componente. Mesmo assim, não use isso para mudar o visual dele:

<%# Wrong: fighting the design system %>
<%= ui_button(class: "bg-red-600 hover:bg-red-700") { "Delete" } %>

<%# Right: the variant already exists %>
<%= ui_button(variant: :destructive) { "Delete" } %>

Use class: para layout, como largura, margem e posição no grid.

<%= ui_button(variant: :outline, class: "w-full sm:w-auto") { "Save" } %>

Atributos HTML são repassados

Qualquer argumento que o componente não reconhece vai para o elemento renderizado como atributo HTML, e os hashes aninhados do Rails, como data: { … }, também funcionam.

<%= ui_button(id: "save", data: { turbo: false, controller: "form" },
              "aria-describedby": "hint") { "Save" } %>

<%= ui_button(tag: :a, href: post_path(post), data: { turbo_method: :delete }) { "Delete" } %>

Use tag: para trocar o elemento, nos componentes que permitem. button renderiza um <button> por padrão e um <a> com tag: :a.

Prefira variantes e tamanhos a utilitários

Veja quais variantes e tamanhos já existem antes de escrever as suas classes:

$ bin/shadwire info button
  variants: default | destructive | outline | secondary | ghost | link
  sizes:    default | sm | lg | icon

<%# Wrong %>
<%= ui_button(class: "h-8 px-3 text-xs border") { "Small" } %>

<%# Right %>
<%= ui_button(variant: :outline, size: :sm) { "Small" } %>

Convenções de utilitários

Siga as mesmas convenções dos componentes, para o seu código ficar parecido com o que a CLI instalou:

• size-9 em vez de h-9 w-9, quando largura e altura coincidem.
• gap-* com flex ou grid, em vez de space-x-* / space-y-*.
• truncate em vez de overflow-hidden text-ellipsis whitespace-nowrap.
• sem z-index manual em overlays: dialog, sheet, popover e dropdown-menu já cuidam do próprio empilhamento.