@fabio.caffarello/react-design-system 1.7.0 → 1.8.0

package/src/docs/Accessibility.mdx

@@ -0,0 +1,402 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Design System/Accessibility" />
+
+# Accessibility Guide
+
+Este guia explica como usar o React Design System de forma acessível e como os componentes atendem aos padrões WCAG 2.1 AA.
+
+## Padrões de Acessibilidade
+
+Todos os componentes do design system são **WCAG 2.1 AA compliant**, garantindo:
+
+- ✅ Contraste de cores adequado (4.5:1 para texto normal, 3:1 para texto grande)
+- ✅ Navegação completa por teclado
+- ✅ Suporte a screen readers
+- ✅ ARIA attributes apropriados
+- ✅ Focus management correto
+
+## Uso Acessível de Componentes
+
+### Labels Sempre Obrigatórios
+
+```tsx
+// ✅ Correto: Label associado
+<Label htmlFor="email">Email</Label>
+<Input id="email" type="email" />
+
+// ❌ Incorreto: Sem label
+<Input placeholder="Email" /> // Não acessível para screen readers
+```
+
+### ARIA Labels para Ícones
+
+```tsx
+// ✅ Correto: ARIA label para botões com apenas ícones
+<Button aria-label="Close dialog" onClick={handleClose}>
+  <CloseIcon />
+</Button>
+
+// ❌ Incorreto: Sem contexto
+<Button onClick={handleClose}>
+  <CloseIcon />
+</Button>
+```
+
+### Descrições Adicionais
+
+```tsx
+// ✅ Correto: Descrição associada
+<Input
+  id="password"
+  type="password"
+  aria-describedby="password-help"
+/>
+<span id="password-help">Password must be at least 8 characters</span>
+
+// ❌ Incorreto: Sem descrição
+<Input type="password" />
+```
+
+## Navegação por Teclado
+
+Todos os componentes interativos suportam navegação por teclado:
+
+### Teclas Suportadas
+
+- **Tab**: Navegar entre elementos
+- **Enter/Space**: Ativar botões e links
+- **Arrow Keys**: Navegar em menus, tabs, selects
+- **Escape**: Fechar modais e popovers
+- **Home/End**: Navegar para início/fim em listas
+
+### Exemplo: Menu Acessível
+
+```tsx
+import { Dropdown, Button } from '@fabio.caffarello/react-design-system';
+
+function AccessibleMenu() {
+  return (
+    <Dropdown
+      trigger={<Button>Menu</Button>}
+      items={[
+        { label: 'Item 1', onClick: () => {} },
+        { label: 'Item 2', onClick: () => {} },
+      ]}
+    />
+  );
+}
+// Navegação por teclado já implementada
+```
+
+## Focus Management
+
+### Focus Trap em Modais
+
+```tsx
+import { Modal, Button } from '@fabio.caffarello/react-design-system';
+
+function AccessibleModal() {
+  return (
+    <Modal
+      isOpen={isOpen}
+      onClose={handleClose}
+      // Focus trap automático
+      // Focus retorna ao trigger ao fechar
+    >
+      <h2>Modal Title</h2>
+      <p>Modal content</p>
+      <Button onClick={handleClose}>Close</Button>
+    </Modal>
+  );
+}
+```
+
+### Focus Visible
+
+Todos os componentes têm estilos de focus visíveis:
+
+```css
+/* Automático em todos os componentes */
+button:focus-visible {
+  outline: 2px solid var(--color-primary-default);
+  outline-offset: 2px;
+}
+```
+
+## Screen Readers
+
+### Estrutura Semântica
+
+```tsx
+// ✅ Correto: HTML semântico
+import { Card, Text, Button } from '@fabio.caffarello/react-design-system';
+
+<Card>
+  <Text variant="heading">Title</Text>
+  <Text>Description</Text>
+  <Button>Action</Button>
+</Card>
+
+// ❌ Incorreto: Divs genéricas
+<div>
+  <div>Title</div>
+  <div>Description</div>
+  <div>Action</div>
+</div>
+```
+
+### ARIA Roles
+
+Componentes usam roles apropriados automaticamente:
+
+```tsx
+// Button usa role="button" automaticamente
+<Button>Click me</Button>
+
+// Input usa role apropriado baseado no type
+<Input type="email" role="textbox" />
+
+// Modal usa role="dialog" automaticamente
+<Modal>Content</Modal>
+```
+
+## Contraste de Cores
+
+### Verificação Automática
+
+O design system garante contraste adequado:
+
+```tsx
+// ✅ Correto: Cores do design system garantem contraste
+import { getColorClass } from '@fabio.caffarello/react-design-system';
+
+<div className={getColorClass('primary', 'DEFAULT', 'bg')}>
+  <Text className={getColorClass('primary', 'contrast', 'text')}>
+    Text with proper contrast
+  </Text>
+</div>
+
+// ❌ Evitar: Cores customizadas sem verificar contraste
+<div className="bg-blue-500 text-blue-200">
+  Text with poor contrast
+</div>
+```
+
+### Dark Mode
+
+O sistema de temas garante contraste adequado em ambos os modos:
+
+```tsx
+import { AdvancedThemeProvider } from '@fabio.caffarello/react-design-system';
+
+<AdvancedThemeProvider defaultTheme="dark">
+  {/* Contraste garantido automaticamente */}
+</AdvancedThemeProvider>
+```
+
+## Formulários Acessíveis
+
+### Estrutura Completa
+
+```tsx
+import { Form, Label, Input, ErrorMessage, Button } from '@fabio.caffarello/react-design-system';
+
+function AccessibleForm() {
+  return (
+    <Form onSubmit={handleSubmit}>
+      <Label htmlFor="email">Email</Label>
+      <Input
+        id="email"
+        type="email"
+        required
+        aria-required="true"
+        aria-invalid={errors.email ? 'true' : 'false'}
+        aria-describedby={errors.email ? 'email-error' : undefined}
+      />
+      {errors.email && (
+        <ErrorMessage id="email-error">
+          {errors.email}
+        </ErrorMessage>
+      )}
+
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
+```
+
+### Validação Acessível
+
+```tsx
+import { Input, ErrorMessage } from '@fabio.caffarello/react-design-system';
+
+function ValidatedInput({ error, ...props }) {
+  return (
+    <div>
+      <Input
+        {...props}
+        aria-invalid={error ? 'true' : 'false'}
+        aria-describedby={error ? `${props.id}-error` : undefined}
+      />
+      {error && (
+        <ErrorMessage id={`${props.id}-error`} role="alert">
+          {error}
+        </ErrorMessage>
+      )}
+    </div>
+  );
+}
+```
+
+## Listas e Tabelas
+
+### Tabelas Acessíveis
+
+```tsx
+import { Table } from '@fabio.caffarello/react-design-system';
+
+function AccessibleTable() {
+  return (
+    <Table
+      data={data}
+      columns={columns}
+      // Headers automáticos com scope="col"
+      // Caption opcional
+      caption="User data table"
+    />
+  );
+}
+```
+
+### Listas Acessíveis
+
+```tsx
+import { Card, Text } from '@fabio.caffarello/react-design-system';
+
+function AccessibleList({ items }) {
+  return (
+    <ul role="list">
+      {items.map((item) => (
+        <li key={item.id}>
+          <Card>
+            <Text>{item.name}</Text>
+          </Card>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Animações e Transições
+
+### Preferências de Movimento
+
+O design system respeita `prefers-reduced-motion`:
+
+```css
+/* Automático em todos os componentes */
+@media (prefers-reduced-motion: reduce) {
+  * {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+### Animações Não Essenciais
+
+Animações decorativas podem ser desabilitadas:
+
+```tsx
+// Animações são opcionais e podem ser desabilitadas
+<Spinner /> // Animação pode ser desabilitada via CSS
+```
+
+## Testes de Acessibilidade
+
+### Testes Automatizados
+
+Todos os componentes têm testes de acessibilidade:
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import { Button } from '@fabio.caffarello/react-design-system';
+
+expect.extend(toHaveNoViolations);
+
+test('Button is accessible', async () => {
+  const { container } = render(<Button>Click me</Button>);
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+});
+```
+
+### Testes Manuais
+
+Checklist para testes manuais:
+
+- [ ] Navegação completa por teclado
+- [ ] Screen reader anuncia corretamente
+- [ ] Contraste de cores adequado
+- [ ] Focus visível em todos os elementos
+- [ ] Labels associados corretamente
+- [ ] Erros anunciados apropriadamente
+
+## Ferramentas
+
+### axe DevTools
+
+Use o axe DevTools para verificar acessibilidade:
+
+1. Instale a extensão do navegador
+2. Abra a página
+3. Execute a verificação
+4. Corrija problemas encontrados
+
+### WAVE
+
+Use o WAVE para análise de acessibilidade:
+
+1. Acesse [wave.webaim.org](https://wave.webaim.org)
+2. Insira a URL ou código
+3. Analise os resultados
+
+### Lighthouse
+
+Use o Lighthouse para auditoria completa:
+
+1. Abra DevTools
+2. Vá para a aba Lighthouse
+3. Selecione "Accessibility"
+4. Execute a auditoria
+
+## Checklist de Acessibilidade
+
+Antes de publicar um componente ou página:
+
+- [ ] Todos os inputs têm labels associados
+- [ ] Botões com apenas ícones têm aria-label
+- [ ] Navegação por teclado funciona
+- [ ] Contraste de cores adequado (4.5:1 mínimo)
+- [ ] Focus visível em todos os elementos
+- [ ] Screen reader anuncia corretamente
+- [ ] Erros são anunciados apropriadamente
+- [ ] Animações respeitam prefers-reduced-motion
+
+## Recursos Adicionais
+
+- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
+- [WebAIM](https://webaim.org/)
+- [A11y Project](https://www.a11yproject.com/)
+
+## Suporte
+
+Se encontrar problemas de acessibilidade:
+
+1. Consulte a [documentação do componente](./Design%20System/Components)
+2. Verifique os [testes de acessibilidade](./Design%20System/Component%20Status)
+3. Abra uma [issue no GitHub](https://github.com/fabiocaffarello/react-design-system/issues)

package/src/docs/BestPractices.mdx

@@ -0,0 +1,315 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Design System/Best Practices" />
+
+# Best Practices
+
+Este guia apresenta as melhores práticas para usar o React Design System de forma eficiente e consistente.
+
+## Estrutura de Componentes
+
+### Atomic Design
+
+Sempre siga a hierarquia do Atomic Design:
+
+1. **Atoms** → Componentes básicos e indivisíveis
+2. **Molecules** → Combinações de atoms
+3. **Organisms** → Combinações de molecules e atoms
+
+```tsx
+// ✅ Correto: Usar atoms para construir molecules
+import { Input, Label, Button } from '@fabio.caffarello/react-design-system';
+
+function LoginForm() {
+  return (
+    <form>
+      <Label htmlFor="email">Email</Label>
+      <Input id="email" type="email" />
+      <Button type="submit">Login</Button>
+    </form>
+  );
+}
+
+// ❌ Incorreto: Não recriar atoms dentro de molecules
+function BadLoginForm() {
+  return (
+    <form>
+      <input type="email" /> {/* Use o componente Input do design system */}
+    </form>
+  );
+}
+```
+
+## Uso de Tokens
+
+### Sempre Use Design Tokens
+
+Use tokens em vez de valores hardcoded:
+
+```tsx
+// ✅ Correto: Usar tokens
+import { getSpacingClass, getColorClass } from '@fabio.caffarello/react-design-system';
+
+<div className={`${getSpacingClass('md', 'p')} ${getColorClass('primary', 'DEFAULT', 'bg')}`}>
+  Content
+</div>
+
+// ❌ Incorreto: Valores hardcoded
+<div className="p-4 bg-indigo-500">
+  Content
+</div>
+```
+
+### Tokens de Cores
+
+Use cores semânticas:
+
+```tsx
+// ✅ Correto: Cores semânticas
+getColorClass('primary', 'DEFAULT', 'bg')
+getColorClass('error', 'DEFAULT', 'text')
+getColorClass('success', 'DEFAULT', 'border')
+
+// ❌ Incorreto: Cores específicas
+'bg-indigo-500'
+'text-red-600'
+```
+
+## Acessibilidade
+
+### Sempre Forneça Labels
+
+```tsx
+// ✅ Correto
+<Label htmlFor="username">Username</Label>
+<Input id="username" />
+
+// ❌ Incorreto
+<Input placeholder="Username" /> // Sem label associado
+```
+
+### Use ARIA Attributes Quando Necessário
+
+```tsx
+// ✅ Correto: Componente com ARIA
+<Button aria-label="Close dialog" onClick={handleClose}>
+  <CloseIcon />
+</Button>
+
+// ✅ Correto: Componente com descrição
+<Input
+  id="password"
+  type="password"
+  aria-describedby="password-help"
+/>
+<span id="password-help">Password must be at least 8 characters</span>
+```
+
+### Navegação por Teclado
+
+Todos os componentes interativos já suportam navegação por teclado. Não desabilite isso:
+
+```tsx
+// ✅ Correto: Deixar navegação por teclado funcionar
+<Button onClick={handleClick}>Click me</Button>
+
+// ❌ Incorreto: Desabilitar navegação por teclado
+<Button onClick={handleClick} onKeyDown={(e) => e.preventDefault()}>
+  Click me
+</Button>
+```
+
+## Performance
+
+### Use Code Splitting
+
+Importe apenas o que você precisa:
+
+```tsx
+// ✅ Correto: Import específico
+import { Button, Input } from '@fabio.caffarello/react-design-system/atoms';
+
+// ⚠️ Aceitável mas menos otimizado
+import { Button, Input } from '@fabio.caffarello/react-design-system';
+```
+
+### Memoização
+
+Componentes já otimizados não precisam de memoização adicional:
+
+```tsx
+// ✅ Correto: Componentes já são memoizados
+import { Card } from '@fabio.caffarello/react-design-system';
+
+function MyComponent() {
+  return <Card>Content</Card>;
+}
+
+// ❌ Desnecessário: Componentes já são otimizados
+import { memo } from 'react';
+const MyCard = memo(Card);
+```
+
+## Temas
+
+### Use AdvancedThemeProvider
+
+```tsx
+// ✅ Correto: Usar AdvancedThemeProvider
+import { AdvancedThemeProvider } from '@fabio.caffarello/react-design-system';
+
+function App() {
+  return (
+    <AdvancedThemeProvider defaultTheme="light">
+      <YourApp />
+    </AdvancedThemeProvider>
+  );
+}
+```
+
+### Crie Temas Customizados
+
+```tsx
+// ✅ Correto: Criar tema customizado
+import { ThemeBuilder } from '@fabio.caffarello/react-design-system';
+
+const brandTheme = ThemeBuilder.create({
+  name: 'brand',
+  base: 'light',
+  colors: {
+    primary: {
+      DEFAULT: { hex: '#your-brand-color' },
+    },
+  },
+}).build();
+```
+
+## Composição de Componentes
+
+### Compose, Não Modifique
+
+```tsx
+// ✅ Correto: Compor componentes
+function CustomCard({ children, ...props }) {
+  return (
+    <Card padding="large" variant="hover" {...props}>
+      {children}
+    </Card>
+  );
+}
+
+// ❌ Incorreto: Modificar componentes diretamente
+// Não modifique os componentes do design system
+```
+
+### Use Variants
+
+```tsx
+// ✅ Correto: Usar variants
+<Button variant="primary" size="large">Submit</Button>
+<Button variant="secondary" size="small">Cancel</Button>
+
+// ❌ Incorreto: Criar componentes customizados para variantes
+function CustomButton() {
+  return <button className="custom-primary-large">Submit</button>;
+}
+```
+
+## Formulários
+
+### Use Form Component
+
+```tsx
+// ✅ Correto: Usar componente Form
+import { Form, Input, Button } from '@fabio.caffarello/react-design-system';
+
+function LoginForm() {
+  return (
+    <Form onSubmit={handleSubmit}>
+      <Input name="email" type="email" required />
+      <Input name="password" type="password" required />
+      <Button type="submit">Login</Button>
+    </Form>
+  );
+}
+```
+
+### Validação
+
+```tsx
+// ✅ Correto: Validação com react-hook-form
+import { useForm } from 'react-hook-form';
+import { Form, Input, Button } from '@fabio.caffarello/react-design-system';
+
+function ValidatedForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm();
+  
+  return (
+    <Form onSubmit={handleSubmit(onSubmit)}>
+      <Input
+        {...register('email', { required: true })}
+        error={errors.email ? 'Email is required' : undefined}
+      />
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
+```
+
+## Testes
+
+### Teste Componentes
+
+```tsx
+// ✅ Correto: Testar componentes
+import { render, screen } from '@testing-library/react';
+import { Button } from '@fabio.caffarello/react-design-system';
+
+test('renders button', () => {
+  render(<Button>Click me</Button>);
+  expect(screen.getByRole('button')).toBeInTheDocument();
+});
+```
+
+## TypeScript
+
+### Use Types do Design System
+
+```tsx
+// ✅ Correto: Usar tipos exportados
+import type { ButtonProps } from '@fabio.caffarello/react-design-system';
+
+function MyButton(props: ButtonProps) {
+  return <Button {...props} />;
+}
+
+// ❌ Incorreto: Criar tipos próprios
+interface MyButtonProps {
+  // ...
+}
+```
+
+## Erros Comuns
+
+### ❌ Não Faça Isso
+
+1. **Não modifique componentes diretamente**
+2. **Não use valores hardcoded em vez de tokens**
+3. **Não ignore acessibilidade**
+4. **Não importe tudo quando precisa de pouco**
+5. **Não crie componentes que já existem**
+
+### ✅ Faça Isso
+
+1. **Use componentes como estão**
+2. **Use design tokens**
+3. **Sempre considere acessibilidade**
+4. **Use code splitting**
+5. **Reutilize componentes existentes**
+
+## Recursos Adicionais
+
+- [Getting Started Guide](./Design%20System/Getting%20Started)
+- [Component Composition Guide](./Design%20System/Component%20Composition)
+- [Accessibility Guide](./Design%20System/Accessibility)
+- [Performance Guide](./Design%20System/Performance)