Shadcn Component Authoring

Skill: Shadcn Component Authoring 2.1 🚀

Visão Geral

Esta skill descreve o processo de criação de componentes com CSS pré-compilado, foco em modularidade, performance e experiência do desenvolvedor.

🎯 Objetivos Atualizados

• 🧩 Criar componentes totalmente modulares
• 🎨 Garantir consistência de design
• 🚀 Otimizar performance de renderização
• 🔒 Simplificar consumo de componentes

📂 Estrutura de Componente

Anatomia Padrão

packages/ui/src/components/<componente>/
├── index.ts            # Exportações principais
├── <componente>.tsx    # Implementação
└── (opcional) types.ts # Definições avançadas

🔧 Padrões de Implementação

1. Definição de Props

interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  // Propriedades específicas
}

2. Variantes com CVA

const buttonVariants = cva("base-button", {
  variants: {
    variant: {
      primary: "bg-primary text-white",
      secondary: "bg-secondary text-gray-800",
    },
    size: {
      sm: "text-sm px-2",
      md: "text-base px-4",
    },
  },
  defaultVariants: {
    variant: "primary",
    size: "md",
  },
});

3. Implementação com Forward Ref

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, ...props }, ref) => (
    <button
      ref={ref}
      className={cn(buttonVariants({ variant, size }), className)}
      {...props}
    />
  ),
);
Button.displayName = "Button";

🛠️ Ferramentas e Dependências

• React: Biblioteca base
• class-variance-authority (cva): Variantes
• tailwind-merge: Mesclagem de classes
• Tailwind CSS: Sistema de design
• shadcn CLI: Instalação de componentes base (opcional)

🔄 Fluxo de Criação

Opção 1: Instalar via shadcn CLI (Recomendado)

Para componentes que existem no registry shadcn:

1. Consultar componente via MCP (ver skill shadcn-mcp-integration)
2. Instalar base: npx shadcn@latest add <componente> --cwd packages/ui -p src/components/<componente> -y
3. Customizar conforme design system (ajustar variantes, cores, tokens)

Vantagens:

• ✅ Componente base já implementado
• ✅ Acessibilidade incluída
• ✅ Padrões shadcn seguidos
• ✅ Mais rápido

Opção 2: Criar do Zero

Para componentes customizados não disponíveis no registry:

1. Definir contrato de props
2. Implementar variantes com cva
3. Criar componente com forwardRef
4. Adicionar ao barrel index.ts
5. Documentar no Storybook

🎨 Personalização e CSS

Tokens de Design

:root {
  --primary: hsl(210, 100%, 50%);
  --secondary: hsl(260, 100%, 50%);
}

Geração de CSS

• Build automatizado gera styles.css
• CSS pré-compilado com todas variantes
• Suporte a temas via variáveis CSS

⚠️ Anti-Padrões

• Evitar lógica de negócio em componentes
• Não acoplar estado global
• Não criar componentes muito específicos

🚦 Validação

npm run build:ui     # Compilar biblioteca
npm run test:ui      # Testes
npm run storybook    # Documentação

🔍 Consumo Simplificado

import "@juscash/ui/styles.css";
import { Button } from "@juscash/ui";

function App() {
  return <Button variant="primary">Clique aqui</Button>;
}

📦 Decisões de Arquitetura

🚀 Próximos Passos

• Documentação detalhada
• Testes abrangentes
• Exemplos em diferentes contextos

📚 Referências

• Tailwind CSS
• class-variance-authority
• React Docs
• Skill: shadcn-mcp-integration - Instalação via CLI