Imported from charlenopires/PhiaUI (SKILL.md). Install upstream with npx skills add charlenopires/PhiaUI. Copyright stays with the author.

PhiaUI Design System

Linguagem visual obrigatória para todos os componentes PhiaUI. Para padrões de código (API, cn/1, variants, testes, segurança) → ver phia-component/SKILL.md.

1. Filosofia & Referência

• shadcn/ui é a referência primária — consultar via Context7 (/shadcn-ui/ui) antes de implementar
• Tailwind CSS v4 — CSS-first config via @theme / @source / @utility (sem tailwind.config.js)
• OKLCH — paleta de cores em espaço perceptualmente uniforme (ampla gama, dark mode preciso)
• Zero libs externas de UI — sem Heroicons npm, sem Alpine, sem class-variance-authority
• Semantic tokens sempre — nunca usar cores Tailwind brutas (blue-500) em componentes

2. Sistema de Cores

Tokens Semânticos (todos mapeados em priv/static/theme.css)

Presets de Cor (8 temas em priv/static/themes/)

zinc (padrão), slate, blue, rose, orange, green, violet, neutral

Cada preset redefine apenas os tokens primary / primary-foreground — demais tokens são neutros.

Modificadores de Opacidade

<%# hover: reduz opacidade em vez de cor diferente %>
class="bg-primary hover:bg-primary/90"
class="bg-muted hover:bg-muted/80"
class="text-muted-foreground/70"

Usar /80, /90, /70 para estados de hover/active — nunca inventar nova cor.

Regra de Ouro

✅ bg-primary       ✅ bg-destructive     ✅ bg-muted
❌ bg-blue-500      ❌ bg-red-600         ❌ bg-gray-100

3. Tipografia

Famílias

/* priv/static/theme.css */
--font-sans: ui-sans-serif, system-ui, sans-serif   /* padrão absoluto */
--font-mono: ui-monospace, 'Cascadia Code', monospace /* código, kbd, OTP */

Nenhum componente deve importar Google Fonts ou fontes externas.

Escala de Tamanho (8 níveis)

Pesos

Line Height

• leading-none (1) — headings display
• leading-tight (1.25) — títulos compactos
• leading-normal (1.5) — padrão de corpo
• leading-relaxed (1.625) — texto longo / prose

4. Sistema de Espaçamento

Base: 4px (1 unidade Tailwind = 4px). Todo espaçamento é múltiplo de 4.

Padding por Tipo de Componente

Gap Patterns

<%# Stack vertical padrão %>
class="flex flex-col gap-4"
<%# Inline group de botões %>
class="flex items-center gap-2"
<%# Grid de cards %>
class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4"
<%# Formulário %>
class="space-y-4"

Margin

• Nunca usar m-* em componentes de biblioteca — responsabilidade do consumer
• Exceção: mt-1.5 para mensagens de erro abaixo de inputs

5. Raio de Borda

Escala baseada em --radius: 0.625rem (10px) definida no tema:

Regras Práticas

• rounded-md → tudo que o usuário digita ou clica (inputs, buttons)
• rounded-lg → containers que agrupam conteúdo (cards, dialogs)
• rounded-full → elementos circulares por natureza (avatar, badge de status, stepper dot)
• Nunca misturar rounded (4px Tailwind padrão) com os tokens semânticos acima

6. Sistema de Sombras

4 níveis para profundidade visual:

<%# Dropdown menu %>
class="shadow-md rounded-lg border border-border bg-popover"
<%# Dialog %>
class="shadow-lg rounded-lg border border-border bg-background"
<%# Toast / Sonner %>
class="shadow-lg rounded-md border border-border"

Nunca usar shadow-2xl ou drop-shadow em componentes — reservado para marketing/landing.

7. Sistema de Ícones

PhiaUI usa Heroicons via o componente nativo <.icon> (SVG inline, sem npm).

Tamanhos

Acessibilidade

<%# Decorativo: aria-hidden obrigatório %>
<.icon name="hero-check" class="h-4 w-4" aria-hidden="true" />

<%# Funcional (sem label de texto): aria-label obrigatório %>
<button aria-label="Fechar diálogo">
  <.icon name="hero-x-mark" class="h-4 w-4" aria-hidden="true" />
</button>

<%# Nunca: ícone funcional sem label %>
<button><.icon name="hero-x-mark" class="h-4 w-4" /></button>

Naming Convention

• Usar hero-* (outline, 24px) para ações e navegação
• Usar hero-*-solid para estados ativos ou filled indicators
• Usar hero-*-mini (20px) raramente — preferir h-4 w-4 no ícone outline

8. Animação & Motion

Durações

Nunca usar > 500ms para transições de UI (exceto animações explicitamente decorativas).

Classes Tailwind de Animação

<%# Transições de cor/opacidade (micro) %>
class="transition-colors duration-100"
class="transition-opacity duration-150"

<%# Transições de transform (default) %>
class="transition-transform duration-200 ease-out"

<%# Entrada de overlay (medium) %>
class="transition-all duration-300 ease-out data-[state=open]:animate-in data-[state=closed]:animate-out"

<%# Loading states %>
class="animate-spin"    <%# spinner %>
class="animate-pulse"   <%# skeleton %>
class="animate-bounce"  <%# indicador de digitação %>

Easing

• ease-out → entradas (elemento aparecendo na tela)
• ease-in → saídas (elemento desaparecendo)
• ease-in-out → movimentos de reposicionamento
• linear → apenas animate-spin

prefers-reduced-motion (obrigatório)

<%# Toda animação de duração > 100ms deve respeitar: %>
class="motion-safe:transition-transform motion-safe:duration-300"

<%# Para skeletons e spinners: usar variante Tailwind %>
class="animate-pulse motion-reduce:animate-none"

9. Layout & Posicionamento

Padrões Flexbox

<%# Row com alinhamento central (botão com ícone) %>
class="inline-flex items-center gap-2"

<%# Stack vertical (formulário) %>
class="flex flex-col gap-4"

<%# Row com espaço entre (header de card) %>
class="flex items-center justify-between"

<%# Centralizado absoluto (empty state) %>
class="flex flex-col items-center justify-center text-center gap-4"

Grid Patterns

<%# Metric grid responsivo %>
class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4"

<%# Form de 2 colunas %>
class="grid grid-cols-1 md:grid-cols-2 gap-4"

<%# Layout 70/30 %>
class="grid grid-cols-1 lg:grid-cols-[2fr_1fr] gap-6"

Z-Index (camadas fixas)

PhiaUI usa z-50 como camada única de overlay. A ordem no DOM (renderizado depois) resolve conflitos. Nunca usar z-[9999] ou valores arbitrários.

10. Responsividade

Breakpoints (mobile-first)

Container Queries (Tailwind v4 built-in)

<%# Preferir container queries para componentes internamente responsivos %>
<div class="@container">
  <div class="grid grid-cols-1 @md:grid-cols-2">...</div>
</div>

Touch Targets

• Mínimo absoluto: h-10 w-10 (40px × 40px)
• Ideal mobile: h-11 (44px) para qualquer ação primária
• Itens em lista clicável: py-3 mínimo (evitar py-1 em mobile)
• Usar @media (pointer: coarse) via Tailwind quando necessário

11. Modo Escuro

Mecanismo

/* priv/static/theme.css — troca automática via .dark no <html> */
:root { --background: oklch(1 0 0); }
.dark { --background: oklch(0.145 0 0); }

O ThemeProvider adiciona/remove .dark no <html> via localStorage['phia-mode'].

Anti-FOUC

O script de restauração deve ser o primeiro script no <head>, antes de qualquer CSS:

<script>
  (function(){
    var m = localStorage.getItem('phia-mode');
    if (m === 'dark') document.documentElement.classList.add('dark');
  })();
</script>

Boas Práticas

<%# Correto: tokens semânticos trocam automaticamente %>
class="bg-background text-foreground border-border"

<%# Evitar: dark: modifier só quando token semântico não existe %>
class="bg-white dark:bg-zinc-900"  <%# ❌ só se não houver token %>
class="bg-background"               <%# ✅ preferir sempre %>

12. Acessibilidade (WCAG 2.2 AA)

Detalhes de implementação (ARIA roles, focus trap, live regions, keyboard nav) → ver phia-component/SKILL.md seção "Accessibility Checklist".

Contraste de Cores (obrigatório)

• Texto normal: mínimo 4.5:1 contra fundo
• Texto grande (≥18pt bold ou ≥24pt): mínimo 3:1
• Componentes UI (borders de input, ícones funcionais): mínimo 3:1
• Os tokens OKLCH do PhiaUI foram calibrados para WCAG AA — não alterar os valores OKLCH

Focus Ring (universal)

<%# Padrão obrigatório em TODO elemento focável %>
class="focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"

Reduced Motion (em animações)

class="transition-transform motion-reduce:transition-none"
class="animate-pulse motion-reduce:animate-none"

13. Agnosticismo

O componente não deve assumir contexto externo nem depender de ordem de filhos.

Tokens em vez de Cores

# ✅ Agnóstico: funciona em qualquer tema
"bg-primary text-primary-foreground"

# ❌ Acoplado a um preset
"bg-blue-600 text-white"

:rest Attrs (transparência total)

# Permite data-*, phx-*, hx-*, x-*, qualquer attr HTML válida
attr :rest, :global, doc: "HTML attrs forwarded to root element"

Slots > Props de Conteúdo

<%# ✅ Agnóstico: consumer decide o conteúdo %>
<.card_header><h2>Título custom</h2></.card_header>

<%# ❌ Acoplado: header só aceita string %>
<.card header="Título" />

14. Modularidade

Atomic Design Adaptado

Famílias Composable

Componentes com estrutura interna devem ser famílias:

<%# Card family %>
<.card>
  <.card_header>
    <.card_title>Título</.card_title>
    <.card_description>Desc</.card_description>
  </.card_header>
  <.card_content>Conteúdo</.card_content>
  <.card_footer class="justify-end">
    <.button>Ação</.button>
  </.card_footer>
</.card>

Cada membro da família: attr :class, :string, default: nil + attr :rest, :global.

Sub-componentes Independentes

Cada sub-componente deve funcionar standalone:

<%# Válido fora do contexto pai %>
<.card_header>
  <.card_title>Só o header</.card_title>
</.card_header>

15. Extensibilidade

cn/1 Override (último ganha)

defp classes(assigns) do
  cn([
    "base-class-1 base-class-2",   # base
    variant_class(assigns.variant), # variant
    size_class(assigns.size),       # size
    assigns.class                   # override do consumer — sempre último
  ])
end

Named Slots com :let Context

slot :item, doc: "Cada item da lista" do
  attr :disabled, :boolean, default: false
  attr :value, :string, required: true
end

<.select :let={item}>
  <:item value="a" disabled={true}>Opção A</:item>
</.select>

Tema via CSS Variables

Consumers podem sobrescrever tokens por escopo:

/* Em um componente customizado do consumer */
[data-phia-theme="brand"] {
  --primary: oklch(0.55 0.25 280); /* roxo da marca */
}

16. Estados de Componente

Todo componente interativo deve ter estilo para todos os 6 estados:

Padrão para Botão (referência)

defp base_classes do
  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium " <>
  "transition-colors duration-100 " <>
  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 " <>
  "disabled:pointer-events-none disabled:opacity-50"
end

17. Anti-Patterns Visuais

Referências Rápidas

• priv/static/theme.css — todos os tokens OKLCH com valores
• priv/static/themes/ — 8 presets de cor
• lib/phia_ui/class_merger.ex — cn/1 implementation
• lib/phia_ui/components/ — componentes existentes como referência
• phia-component/SKILL.md — padrões de código (API, testes, segurança)
• Context7 /shadcn-ui/ui — referência shadcn/ui atualizada