ui-styling

Habilidade de Estilização de UI

Habilidade abrangente para criar interfaces de usuário bonitas e acessíveis, combinando componentes shadcn/ui, estilização utilitária do Tailwind CSS e sistemas de design visual baseados em canvas.

Referência

• shadcn/ui: https://ui.shadcn.com/llms.txt
• Tailwind CSS: https://tailwindcss.com/docs

Quando Usar Esta Habilidade

Use quando:

• Construir UI com frameworks baseados em React (Next.js, Vite, Remix, Astro)
• Implementar componentes acessíveis (diálogos, formulários, tabelas, navegação)
• Estilizar com abordagem CSS utilitária
• Criar layouts responsivos e mobile-first
• Implementar modo escuro e personalização de temas
• Construir sistemas de design com tokens consistentes
• Gerar designs visuais, pôsteres ou materiais de marca
• Prototipar rapidamente com feedback visual imediato
• Adicionar padrões de UI complexos (tabelas de dados, gráficos, paletas de comandos)

Stack Principal

Camada de Componentes: shadcn/ui

• Componentes acessíveis pré-construídos via primitivas Radix UI
• Modelo de distribuição copie-cole (os componentes residem no seu código)
• TypeScript-first com segurança total de tipos
• Primitivas combináveis para UIs complexas
• Instalação e gerenciamento via CLI

Camada de Estilização: Tailwind CSS

• Framework CSS utilitário
• Processamento em tempo de compilação sem sobrecarga em runtime
• Design responsivo mobile-first
• Tokens de design consistentes (cores, espaçamento, tipografia)
• Eliminação automática de código morto

Camada de Design Visual: Canvas

• Composições visuais com qualidade de museu
• Abordagem de design orientada por filosofia
• Comunicação visual sofisticada
• Mínimo texto, máximo impacto visual
• Padrões sistemáticos e estética refinada

Caminhos dos Scripts

Os caminhos dos scripts nesta habilidade e em suas references/ são relativos ao diretório que contém este SKILL.md, não ao projeto: scripts/<arquivo> é a pasta scripts/ desta habilidade, e ../<habilidade>/scripts/<arquivo> é uma sub-habilidade irmã instalada junto com ela. Construa o caminho completo a partir desse diretório (o Claude Code informa o diretório base da habilidade quando ela é carregada) e mantenha o diretório de trabalho na raiz do projeto — os scripts leem e escrevem arquivos do projeto, como docs/brand-guidelines.md, assets/design-tokens.json ou src/ relativos a ele.

Guia Rápido

Configuração de Componentes + Estilização

Instalar shadcn/ui com Tailwind:

npx shadcn@latest init

O CLI pergunta sobre framework, TypeScript, caminhos e preferências de tema. Isso configura tanto shadcn/ui quanto Tailwind CSS.

Adicionar componentes:

npx shadcn@latest add button card dialog form

Usar componentes com estilização utilitária:

import { Button } from "@/components/ui/button"
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"

export function Dashboard() {
  return (
    <div className="container mx-auto p-6 grid gap-6 md:grid-cols-2 lg:grid-cols-3">
      <Card className="hover:shadow-lg transition-shadow">
        <CardHeader>
          <CardTitle className="text-2xl font-bold">Analytics</CardTitle>
        </CardHeader>
        <CardContent className="space-y-4">
          <p className="text-muted-foreground">Veja suas métricas</p>
          <Button variant="default" className="w-full">
            Ver Detalhes
          </Button>
        </CardContent>
      </Card>
    </div>
  )
}

Alternativa: Configuração Apenas com Tailwind

Projetos Vite:

npm install -D tailwindcss @tailwindcss/vite

// vite.config.ts
import tailwindcss from '@tailwindcss/vite'
export default { plugins: [tailwindcss()] }

/* src/index.css */
@import "tailwindcss";

Guia da Biblioteca de Componentes

Catálogo abrangente de componentes com padrões de uso, instalação e exemplos de composição.

Veja: references/shadcn-components.md

Cobre:

• Componentes de formulário e entrada (Button, Input, Select, Checkbox, Date Picker, validação de Formulário)
• Layout e navegação (Card, Tabs, Accordion, Navigation Menu)
• Sobreposições e diálogos (Dialog, Drawer, Popover, Toast, Command)
• Feedback e status (Alert, Progress, Skeleton)
• Componentes de exibição (Table, Data Table, Avatar, Badge)

Tema e Personalização

Configuração de tema, variáveis CSS, implementação de modo escuro e personalização de componentes.

Veja: references/shadcn-theming.md

Cobre:

• Configuração de modo escuro com next-themes
• Sistema de variáveis CSS
• Personalização de cores e paletas
• Personalização de variantes de componentes
• Implementação de alternador de tema

Padrões de Acessibilidade

Padrões ARIA, navegação por teclado, suporte a leitores de tela e uso acessível de componentes.

Veja: references/shadcn-accessibility.md

Cobre:

• Recursos de acessibilidade do Radix UI
• Padrões de navegação por teclado
• Gerenciamento de foco
• Anúncios para leitores de tela
• Acessibilidade na validação de formulários

Utilitários Tailwind

Classes utilitárias principais para layout, espaçamento, tipografia, cores, bordas e sombras.

Veja: references/tailwind-utilities.md

Cobre:

• Utilitários de layout (Flexbox, Grid, posicionamento)
• Sistema de espaçamento (padding, margin, gap)
• Tipografia (tamanhos de fonte, pesos, alinhamento, altura da linha)
• Cores e fundos
• Bordas e sombras
• Valores arbitrários para estilização personalizada

Design Responsivo

Breakpoints mobile-first, utilitários responsivos e layouts adaptativos.

Veja: references/tailwind-responsive.md

Cobre:

• Abordagem mobile-first
• Sistema de breakpoints (sm, md, lg, xl, 2xl)
• Padrões de utilitários responsivos
• Consultas de contêiner
• Consultas de largura máxima
• Breakpoints personalizados

Personalização do Tailwind

Estrutura do arquivo de configuração, utilitários personalizados, plugins e extensões de tema.

Veja: references/tailwind-customization.md

Cobre:

• Diretiva @theme para tokens personalizados
• Cores e fontes personalizadas
• Extensões de espaçamento e breakpoints
• Criação de utilitários personalizados
• Variantes personalizadas
• Organização de camadas (@layer base, components, utilities)
• Diretiva Apply para extração de componentes

Sistema de Design Visual

Filosofia de design baseada em canvas, princípios de comunicação visual e composições sofisticadas.

Veja: references/canvas-design-system.md

Cobre:

• Abordagem da filosofia de design
• Comunicação visual em vez de texto
• Padrões sistemáticos e composição
• Design de cor, forma e espaço
• Integração mínima de texto
• Execução com qualidade de museu
• Sistemas de design com várias páginas

Scripts Utilitários

Automação Python para instalação de componentes e geração de configuração.

shadcn_add.py

Adicionar componentes shadcn/ui com gerenciamento de dependências:

python scripts/shadcn_add.py button card dialog

tailwind_config_gen.py

Gerar tailwind.config.js com tema personalizado:

python scripts/tailwind_config_gen.py --colors brand:blue --fonts display:Inter

O gerador se recusa a criar ou substituir uma configuração quando qualquer arquivo irmão tailwind.config.js, .cjs, .mjs ou .ts já existir. Revise a configuração relatada primeiro e passe --force apenas quando a saída concorrente for intencional:

python scripts/tailwind_config_gen.py --colors brand:blue --force

Melhores Práticas

1. Composição de Componentes: Construa UIs complexas a partir de primitivas simples e combináveis
2. Estilização Utilitária: Use classes Tailwind diretamente; extraia componentes apenas para repetição verdadeira
3. Responsivo Mobile-First: Comece com estilos mobile, adicione variantes responsivas
4. Acessibilidade em Primeiro Lugar: Aproveite as primitivas Radix UI, adicione estados de foco, use HTML semântico
5. Tokens de Design: Use escala de espaçamento consistente, paletas de cores, sistema tipográfico
6. Consistência do Modo Escuro: Aplique variantes escuras a todos os elementos com tema
7. Desempenho: Aproveite a eliminação automática de CSS, evite nomes de classe dinâmicos
8. TypeScript: Use segurança total de tipos para melhor experiência do desenvolvedor
9. Hierarquia Visual: Deixe a composição guiar a atenção, use espaçamento e cor intencionalmente
10. Artesanato Especializado: Cada detalhe importa - trate a UI como um ofício

Navegação pelas Referências

Biblioteca de Componentes

• references/shadcn-components.md - Catálogo completo de componentes
• references/shadcn-theming.md - Temas e personalização
• references/shadcn-accessibility.md - Padrões de acessibilidade

Sistema de Estilização

• references/tailwind-utilities.md - Classes utilitárias principais
• references/tailwind-responsive.md - Design responsivo
• references/tailwind-customization.md - Configuração e extensões

Design Visual

• references/canvas-design-system.md - Filosofia de design e fluxos de trabalho em canvas

Automação

• scripts/shadcn_add.py - Instalação de componentes
• scripts/tailwind_config_gen.py - Geração de configuração

Padrões Comuns

Formulário com validação:

import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import * as z from "zod"
import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "@/components/ui/form"
import { Input } from "@/components/ui/input"
import { Button } from "@/components/ui/button"

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8)
})

export function LoginForm() {
  const form = useForm({
    resolver: zodResolver(schema),
    defaultValues: { email: "", password: "" }
  })

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(console.log)} className="space-y-6">
        <FormField control={form.control} name="email" render={({ field }) => (
          <FormItem>
            <FormLabel>Email</FormLabel>
            <FormControl>
              <Input type="email" {...field} />
            </FormControl>
            <FormMessage />
          </FormItem>
        )} />
        <Button type="submit" className="w-full">Entrar</Button>
      </form>
    </Form>
  )
}

Layout responsivo com modo escuro:

<div className="min-h-screen bg-white dark:bg-gray-900">
  <div className="container mx-auto px-4 py-8">
    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
      <Card className="bg-white dark:bg-gray-800 border-gray-200 dark:border-gray-700">
        <CardContent className="p-6">
          <h3 className="text-xl font-semibold text-gray-900 dark:text-white">
            Conteúdo
          </h3>
        </CardContent>
      </Card>
    </div>
  </div>
</div>

Recursos

• shadcn/ui Docs: https://ui.shadcn.com
• Tailwind CSS Docs: https://tailwindcss.com
• Radix UI: https://radix-ui.com
• Tailwind UI: https://tailwindui.com
• Headless UI: https://headlessui.com
• v0 (Gerador de UI com IA): https://v0.dev