jarvis-ai-framework 2.1.0 → 2.1.1

package/skills/eng-frontend-design-system/references/2-tokens.md

@@ -0,0 +1,116 @@
+# Sistema de Tokens
+
+> Parte do skill `eng-frontend-design-system`. Leia este arquivo quando a tarefa envolver tokens (primitivos, semânticos, Tailwind).
+
+## Sistema de Tokens
+
+### Dois níveis: primitivos e semânticos
+
+```typescript
+// src/tokens/colors.ts
+
+// Nível 1 — Primitivos (paleta completa — não usar diretamente nas aplicações)
+export const colorPrimitives = {
+  blue50:  '#eff6ff',
+  blue100: '#dbeafe',
+  blue500: '#3b82f6',
+  blue600: '#2563eb',
+  blue900: '#1e3a8a',
+  gray50:  '#f9fafb',
+  gray100: '#f3f4f6',
+  gray500: '#6b7280',
+  gray900: '#111827',
+  red500:  '#ef4444',
+  green500:'#22c55e',
+  // ...
+} as const
+
+// Nível 2 — Semânticos (significado, não cor) — o que as aplicações usam
+export const colorTokens = {
+  // Interação
+  interactive: {
+    primary:        colorPrimitives.blue500,
+    primaryHover:   colorPrimitives.blue600,
+    primaryFocus:   colorPrimitives.blue500,  // + ring
+    destructive:    colorPrimitives.red500,
+  },
+  // Conteúdo
+  content: {
+    primary:        colorPrimitives.gray900,
+    secondary:      colorPrimitives.gray500,
+    disabled:       colorPrimitives.gray300,
+    inverse:        '#ffffff',
+  },
+  // Background
+  background: {
+    page:           '#ffffff',
+    subtle:         colorPrimitives.gray50,
+    overlay:        'rgba(0, 0, 0, 0.5)',
+  },
+  // Feedback
+  feedback: {
+    success:        colorPrimitives.green500,
+    error:          colorPrimitives.red500,
+    warning:        '#f59e0b',
+    info:           colorPrimitives.blue500,
+  },
+} as const
+```
+
+### Tokens em Tailwind (CSS custom properties)
+
+```typescript
+// tailwind.config.ts
+import type { Config } from 'tailwindcss'
+import { colorPrimitives } from './src/tokens/colors'
+
+export default {
+  content: ['./src/**/*.{ts,tsx}'],
+  theme: {
+    extend: {
+      colors: {
+        // Expor semânticos como classes Tailwind
+        interactive: {
+          primary: 'var(--color-interactive-primary)',
+          'primary-hover': 'var(--color-interactive-primary-hover)',
+        },
+        content: {
+          primary: 'var(--color-content-primary)',
+          secondary: 'var(--color-content-secondary)',
+        },
+        feedback: {
+          success: 'var(--color-feedback-success)',
+          error: 'var(--color-feedback-error)',
+        },
+      },
+      spacing: {
+        // Escala de 4px
+        1: '4px',
+        2: '8px',
+        3: '12px',
+        4: '16px',
+        6: '24px',
+        8: '32px',
+        10: '40px',
+        12: '48px',
+        16: '64px',
+      },
+      fontFamily: {
+        sans: ['var(--font-sans)', 'system-ui', 'sans-serif'],
+        mono: ['var(--font-mono)', 'monospace'],
+      },
+      fontSize: {
+        xs:   ['12px', { lineHeight: '16px' }],
+        sm:   ['14px', { lineHeight: '20px' }],
+        base: ['16px', { lineHeight: '24px' }],
+        lg:   ['18px', { lineHeight: '28px' }],
+        xl:   ['20px', { lineHeight: '28px' }],
+        '2xl':['24px', { lineHeight: '32px' }],
+        '3xl':['30px', { lineHeight: '36px' }],
+      },
+    },
+  },
+} satisfies Config
+```
+
+---

package/skills/eng-frontend-design-system/references/3-componentes.md

@@ -0,0 +1,165 @@
+# Criando um Componente e Acessibilidade
+
+> Parte do skill `eng-frontend-design-system`. Leia este arquivo quando a tarefa criar ou alterar um componente (CVA, API pública, acessibilidade, Radix UI).
+
+## Criando um Componente
+
+### Checklist antes de criar
+
+- [ ] Verificar se já existe componente similar (`ls src/components/`)
+- [ ] Verificar se o Radix UI tem primitive para este componente
+- [ ] Confirmar variantes necessárias com design
+- [ ] Definir API de props antes de implementar
+
+### Padrão com CVA (class-variance-authority)
+
+```typescript
+// src/components/Button/Button.tsx
+import { cva, type VariantProps } from 'class-variance-authority'
+import { cn } from '../../utils/cn'
+import type { ButtonHTMLAttributes } from 'react'
+
+const buttonVariants = cva(
+  // Base — aplicado a todas as variantes
+  [
+    'inline-flex items-center justify-center gap-2',
+    'rounded font-medium transition-colors',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2',
+    'disabled:opacity-50 disabled:pointer-events-none',
+  ],
+  {
+    variants: {
+      variant: {
+        primary:     'bg-interactive-primary text-white hover:bg-interactive-primary-hover',
+        secondary:   'border border-gray-300 bg-white text-content-primary hover:bg-gray-50',
+        ghost:       'text-content-primary hover:bg-gray-100',
+        destructive: 'bg-feedback-error text-white hover:bg-red-600',
+        link:        'text-interactive-primary underline-offset-4 hover:underline p-0 h-auto',
+      },
+      size: {
+        sm: 'h-8 px-3 text-sm',
+        md: 'h-10 px-4 text-base',
+        lg: 'h-12 px-6 text-lg',
+        icon: 'h-10 w-10',
+      },
+    },
+    defaultVariants: {
+      variant: 'primary',
+      size: 'md',
+    },
+  }
+)
+
+export interface ButtonProps
+  extends ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  loading?: boolean
+}
+
+export function Button({
+  className,
+  variant,
+  size,
+  loading,
+  disabled,
+  children,
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      className={cn(buttonVariants({ variant, size }), className)}
+      disabled={disabled || loading}
+      aria-busy={loading}
+      {...props}
+    >
+      {loading && <span className="sr-only">Carregando...</span>}
+      {children}
+    </button>
+  )
+}
+
+// Exportar variantes para uso externo (ex: estender em outro componente)
+export { buttonVariants }
+```
+
+### Utilitário `cn` (obrigatório)
+
+```typescript
+// src/utils/cn.ts
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+```
+
+### Ponto de entrada do componente
+
+```typescript
+// src/components/Button/index.ts
+export { Button, buttonVariants } from './Button'
+export type { ButtonProps } from './Button'
+```
+
+### Regras de API pública
+
+- Props que o consumidor pode precisar sobrescrever: exportar o tipo
+- Nunca expor detalhes de implementação interna nas props
+- `className` sempre aceito para extensibilidade
+- `ref` sempre passado via `forwardRef` em elementos DOM
+
+```typescript
+// Padrão com forwardRef (obrigatório para componentes com elemento DOM)
+import { forwardRef } from 'react'
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(
+  function Input({ className, ...props }, ref) {
+    return (
+      <input
+        ref={ref}
+        className={cn(inputVariants(), className)}
+        {...props}
+      />
+    )
+  }
+)
+Input.displayName = 'Input'
+```
+
+---
+
+## Acessibilidade em Componentes
+
+### Componentes compostos com Radix UI
+
+```typescript
+// ✅ Dialog com Radix — acessibilidade built-in
+import * as Dialog from '@radix-ui/react-dialog'
+
+export function Modal({ title, description, trigger, children }: ModalProps) {
+  return (
+    <Dialog.Root>
+      <Dialog.Trigger asChild>{trigger}</Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Overlay className="fixed inset-0 bg-background-overlay" />
+        <Dialog.Content
+          className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 ..."
+          aria-describedby={description ? 'modal-description' : undefined}
+        >
+          <Dialog.Title>{title}</Dialog.Title>
+          {description && (
+            <Dialog.Description id="modal-description">{description}</Dialog.Description>
+          )}
+          {children}
+          <Dialog.Close asChild>
+            <button aria-label="Fechar">✕</button>
+          </Dialog.Close>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog.Root>
+  )
+}
+```
+
+---

package/skills/eng-frontend-design-system/references/4-storybook.md

@@ -0,0 +1,85 @@
+# Storybook
+
+> Parte do skill `eng-frontend-design-system`. Leia este arquivo quando a tarefa envolver stories ou a configuração do Storybook.
+
+## Storybook
+
+### Configuração base
+
+```typescript
+// .storybook/main.ts
+import type { StorybookConfig } from '@storybook/react-vite'
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(ts|tsx)'],
+  addons: [
+    '@storybook/addon-essentials',
+    '@storybook/addon-a11y',        // auditoria de acessibilidade
+    '@storybook/addon-interactions', // testes interativos
+  ],
+  framework: '@storybook/react-vite',
+}
+export default config
+```
+
+### Story padrão
+
+```typescript
+// src/components/Button/Button.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react'
+import { Button } from './Button'
+
+const meta: Meta<typeof Button> = {
+  title: 'Components/Button',
+  component: Button,
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'ghost', 'destructive', 'link'],
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg', 'icon'],
+    },
+    loading: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+  },
+}
+export default meta
+type Story = StoryObj<typeof Button>
+
+// Story principal — estado padrão
+export const Default: Story = {
+  args: {
+    children: 'Botão',
+    variant: 'primary',
+    size: 'md',
+  },
+}
+
+// Todas as variantes juntas
+export const AllVariants: Story = {
+  render: () => (
+    <div className="flex flex-wrap gap-3">
+      <Button variant="primary">Primary</Button>
+      <Button variant="secondary">Secondary</Button>
+      <Button variant="ghost">Ghost</Button>
+      <Button variant="destructive">Destructive</Button>
+    </div>
+  ),
+}
+
+// Estados especiais
+export const Loading: Story = { args: { children: 'Salvando...', loading: true } }
+export const Disabled: Story = { args: { children: 'Desabilitado', disabled: true } }
+```
+
+### Checklist de story
+- [ ] Autodocs ativo (`tags: ['autodocs']`)
+- [ ] ArgTypes com `control` para cada prop variável
+- [ ] Story para cada estado relevante (loading, disabled, erro)
+- [ ] Story `AllVariants` para overview visual
+- [ ] Addon `a11y` habilitado (verificar violations na aba Accessibility)
+
+---

package/skills/eng-frontend-design-system/references/5-auditoria-versionamento.md

@@ -0,0 +1,76 @@
+# Auditoria de Consistência e Versionamento
+
+> Parte do skill `eng-frontend-design-system`. Leia este arquivo quando a tarefa auditar tokens e componentes ou tratar breaking changes e versionamento.
+
+## Auditoria de Consistência
+
+### Detectar tokens hardcodados (proibido)
+
+```bash
+# Cores hardcodadas no código (deve retornar zero resultados)
+grep -r "#[0-9a-fA-F]\{3,6\}\b" src/components/ --include="*.tsx" --include="*.ts"
+grep -r "rgb(\|rgba(\|hsl(" src/components/ --include="*.tsx"
+
+# Valores de espaçamento hardcodados
+grep -r "style={{" src/components/ --include="*.tsx" | grep -v "className"
+
+# Fontes hardcodadas
+grep -r "fontFamily\|fontSize" src/components/ --include="*.tsx" | grep -v "var(--font"
+```
+
+### Verificar componentes sem story
+
+```bash
+# Componentes sem arquivo de story correspondente
+for f in src/components/**/*.tsx; do
+  base="${f%.tsx}"
+  [ ! -f "${base}.stories.tsx" ] && echo "SEM STORY: $f"
+done
+```
+
+### Verificar componentes sem teste
+
+```bash
+for f in src/components/**/*.tsx; do
+  base="${f%.tsx}"
+  [ ! -f "${base}.test.tsx" ] && echo "SEM TESTE: $f"
+done
+```
+
+---
+
+## Versionamento e Breaking Changes
+
+### O que é uma breaking change?
+
+```
+Breaking change (bump MAJOR):
+- Remover uma prop
+- Renomear uma prop sem alias de retrocompatibilidade
+- Alterar o tipo de uma prop (ex: string → enum)
+- Remover uma variante existente
+- Alterar comportamento padrão visível
+
+Non-breaking (bump MINOR ou PATCH):
+- Adicionar nova prop opcional
+- Adicionar nova variante
+- Corrigir bug visual
+- Melhorar acessibilidade
+- Atualizar documentação
+```
+
+### Processo para breaking change
+
+```markdown
+1. Criar deprecation notice na versão atual (adicionar `@deprecated` no JSDoc)
+2. Documentar no CHANGELOG.md com seção "Migration Guide"
+3. Dar prazo de 1 sprint para os consumidores migrarem (comunicar no canal do time)
+4. Lançar major version com a mudança
+5. Atualizar todos os remotes que consomem o componente
+```
+
+```typescript
+// Deprecation notice
+/** @deprecated Use `variant="destructive"` em vez de `danger`. Será removido em v2.0. */
+export type LegacyButtonVariant = 'danger'
+```