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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fabio.caffarello/react-design-system",
   "private": false,
-  "version": "1.7.0",
+  "version": "1.9.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -14,6 +14,54 @@
         "default": "./dist/index.js"
       },
       "require": "./dist/index.cjs"
+    },
+    "./atoms": {
+      "types": "./dist/ui/atoms/index.d.ts",
+      "import": {
+        "development": "./src/ui/atoms/index.ts",
+        "default": "./dist/atoms/index.js"
+      },
+      "require": "./dist/atoms/index.cjs"
+    },
+    "./molecules": {
+      "types": "./dist/ui/molecules/index.d.ts",
+      "import": {
+        "development": "./src/ui/molecules/index.ts",
+        "default": "./dist/molecules/index.js"
+      },
+      "require": "./dist/molecules/index.cjs"
+    },
+    "./organisms": {
+      "types": "./dist/ui/organisms/index.d.ts",
+      "import": {
+        "development": "./src/ui/organisms/index.ts",
+        "default": "./dist/organisms/index.js"
+      },
+      "require": "./dist/organisms/index.cjs"
+    },
+    "./tokens": {
+      "types": "./dist/ui/tokens/index.d.ts",
+      "import": {
+        "development": "./src/ui/tokens/index.ts",
+        "default": "./dist/tokens/index.js"
+      },
+      "require": "./dist/tokens/index.cjs"
+    },
+    "./extensions": {
+      "types": "./dist/ui/extensions/index.d.ts",
+      "import": {
+        "development": "./src/ui/extensions/index.ts",
+        "default": "./dist/extensions/index.js"
+      },
+      "require": "./dist/extensions/index.cjs"
+    },
+    "./extensions/flow": {
+      "types": "./dist/ui/extensions/flow/index.d.ts",
+      "import": {
+        "development": "./src/ui/extensions/flow/index.ts",
+        "default": "./dist/extensions/flow/index.js"
+      },
+      "require": "./dist/extensions/flow/index.cjs"
     }
   },
   "files": [
@@ -25,32 +73,94 @@
   },
   "scripts": {
     "dev": "vite",
+    "dev:playground": "VITE_APP_MODE=true vite",
     "build": "npx tsc --project tsconfig.app.json --declaration --emitDeclarationOnly --outDir dist && vite build",
-    "lint": "eslint .",
+    "build:playground": "VITE_APP_MODE=true vite build",
     "preview": "vite preview",
+    "preview:playground": "VITE_APP_MODE=true vite preview",
+    "lint": "eslint .",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "plop": "plop",
     "postplop": "prettier -w './src/ui/**/*.{ts,tsx}'",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest watch",
+    "audit:tokens": "node scripts/audit-tokens.js",
+    "audit:storybook": "tsx scripts/audit-storybook.ts",
+    "check:duplicates": "tsx scripts/check-duplicates.ts",
+    "validate-stories": "tsx scripts/validate-stories.ts",
+    "validate-stories-enhanced": "tsx scripts/validate-stories-enhanced.ts",
+    "generate-stories": "tsx scripts/generate-stories.ts",
+    "update-stories": "tsx scripts/update-stories.ts",
+    "generate-insights": "tsx scripts/generate-insights.ts",
+    "visual-regression": "tsx scripts/visual-regression.ts",
+    "analyze-bundle-size": "tsx scripts/analyze-bundle-size.ts",
+    "validate-architecture": "tsx scripts/validate-architecture.ts",
+    "validate-a11y": "tsx scripts/validate-a11y.ts",
+    "validate-themes": "tsx scripts/validate-themes.ts",
+    "generate-story-index": "tsx scripts/generate-story-index.ts",
+    "generate-context-diagram": "tsx scripts/generate-context-diagram.ts",
+    "generate-component-registry": "tsx scripts/generate-component-registry.ts",
+    "analyze-component": "tsx scripts/analyze-component.ts",
+    "validate:all": "npm run validate-stories && npm run validate-architecture && npm run validate-a11y && npm run validate-themes",
+    "mcp:health-check": "tsx scripts/mcp-health-check.ts",
+    "mcp:generate-docs": "tsx scripts/mcp-generate-docs.ts",
+    "mcp:figma-sync-tokens": "tsx scripts/mcp-figma-sync-tokens.ts",
+    "mcp:validate-architecture": "tsx scripts/mcp-validate-architecture.ts",
+    "mcp:extract-metadata": "tsx scripts/mcp-extract-metadata.ts",
+    "mcp:sync-all": "tsx scripts/mcp-sync-all.ts",
+    "mcp:validate-all": "tsx scripts/mcp-validate-all.ts",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:debug": "playwright test --debug",
+    "test:e2e:report": "playwright show-report",
+    "chromatic": "npx chromatic --project-token=${CHROMATIC_PROJECT_TOKEN:-}",
+    "chromatic:ci": "npx chromatic --exit-zero-on-changes --project-token=${CHROMATIC_PROJECT_TOKEN:-}",
+    "test:visual": "npm run build-storybook && npm run chromatic"
   },
   "peerDependencies": {
+    "@hookform/resolvers": "^3.0.0",
+    "@xyflow/react": "^12.0.0",
+    "lucide-react": "^0.552.0",
     "react": ">=19",
     "react-dom": ">=19",
-    "lucide-react": "^0.552.0"
+    "react-hook-form": "^7.71.0",
+    "zod": "^3.0.0"
   },
   "dependencies": {
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
     "@tailwindcss/postcss": "^4.1.16",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1"
+    "@types/d3-force": "^3.0.10",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "d3-force": "^3.0.0",
+    "dagre": "^0.8.5",
+    "elkjs": "^0.11.0",
+    "react": ">=19",
+    "react-dom": ">=19",
+    "tailwind-merge": "^3.4.0",
+    "web-worker": "^1.5.0"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.10.0",
     "@chromatic-com/storybook": "^4.1.2",
     "@eslint/js": "^9.36.0",
+    "@hookform/resolvers": "^3.0.0",
+    "@playwright/test": "^1.56.1",
     "@storybook/addon-a11y": "^10.0.3",
+    "@storybook/addon-coverage": "^3.0.0",
+    "@storybook/addon-designs": "^11.1.1",
     "@storybook/addon-docs": "^10.0.3",
+    "@storybook/addon-mcp": "^0.1.8",
+    "@storybook/addon-measure": "^9.0.8",
+    "@storybook/addon-outline": "^9.0.8",
     "@storybook/addon-vitest": "^10.0.3",
     "@storybook/react-vite": "^10.0.3",
+    "@storybook/test": "^8.6.15",
+    "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
     "@types/node": "^24.6.0",
@@ -59,28 +169,35 @@
     "@vitejs/plugin-react": "^5.0.4",
     "@vitest/browser-playwright": "^4.0.6",
     "@vitest/coverage-v8": "^4.0.6",
+    "@xyflow/react": "^12.0.0",
     "autoprefixer": "^10.4.21",
+    "baseline-browser-mapping": "^2.9.14",
     "eslint": "^9.36.0",
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-react-refresh": "^0.4.22",
     "eslint-plugin-storybook": "^10.0.3",
     "globals": "^16.4.0",
     "jsdom": "^27.0.1",
+    "lucide-react": "^0.552.0",
     "playwright": "^1.56.1",
     "plop": "^4.0.4",
     "postcss": "^8.5.6",
     "prettier": "^3.6.2",
+    "react-hook-form": "^7.71.0",
     "storybook": "^10.0.3",
+    "storybook-addon-performance": "^0.17.3",
     "tailwindcss": "^4.1.16",
+    "tsx": "^4.19.2",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.45.0",
     "vite": "^7.1.7",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^4.0.6"
+    "vitest": "^4.0.6",
+    "zod": "^3.0.0"
   },
   "eslintConfig": {
     "extends": [
       "plugin:storybook/recommended"
     ]
   }
-}
+}

package/src/app.tsx

@@ -0,0 +1,48 @@
+/**
+ * Flow Playground Application
+ * 
+ * Standalone Vite application for developing and testing flow components.
+ * This app provides a dedicated environment for building and improving the graph layer.
+ */
+
+import React from 'react';
+import { PlaygroundLayout } from './ui/extensions/flow/components/PlaygroundLayout';
+import { treeTemplate } from './ui/extensions/flow/utils/playgroundTemplates';
+import type { Node, Edge } from '@xyflow/react';
+import type { FlowNodeData, FlowEdgeData } from './ui/extensions/flow/organisms/FlowTypes';
+import { generateNodeId } from './ui/extensions/flow/utils/playgroundHelpers';
+
+// Prepare initial nodes and edges from tree template
+const initialNodes: Node<FlowNodeData>[] = treeTemplate.nodes.map((node) => ({
+  ...node,
+  id: generateNodeId(),
+}));
+
+const nodeIdMap = new Map(treeTemplate.nodes.map((n, i) => [n.id, initialNodes[i].id]));
+
+const initialEdges: Edge<FlowEdgeData>[] = treeTemplate.edges.map((edge) => ({
+  ...edge,
+  id: `edge-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`,
+  source: nodeIdMap.get(edge.source) || edge.source,
+  target: nodeIdMap.get(edge.target) || edge.target,
+}));
+
+/**
+ * Main Application Component
+ * 
+ * This is the entry point for the Flow Playground standalone application.
+ * It provides a full-screen playground environment for developing and testing
+ * flow components, which helps improve both the components themselves and the Storybook.
+ */
+export function App() {
+  return (
+    <div style={{ width: '100vw', height: '100vh', margin: 0, padding: 0, overflow: 'hidden' }}>
+      <PlaygroundLayout
+        initialState={{
+          nodes: initialNodes,
+          edges: initialEdges,
+        }}
+      />
+    </div>
+  );
+}

package/src/docs/ComponentStatus.mdx

@@ -0,0 +1,192 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+import { ComponentStatusTable } from './components/ComponentStatusTable';
+
+<Meta title="Design System/Component Status" />
+
+# Component Status Matrix
+
+Esta página mostra o status de todos os componentes do design system, incluindo estabilidade, acessibilidade e cobertura de testes.
+
+## Legenda
+
+<div style={{ display: 'flex', gap: '24px', marginBottom: '32px', flexWrap: 'wrap' }}>
+  <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+    <span style={{ fontSize: '20px' }}>✅</span>
+    <strong>Stable</strong>: Componente estável e pronto para produção
+  </div>
+  <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+    <span style={{ fontSize: '20px' }}>🟡</span>
+    <strong>Beta</strong>: Componente em beta, pode ter mudanças
+  </div>
+  <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+    <span style={{ fontSize: '20px' }}>🔴</span>
+    <strong>Deprecated</strong>: Componente descontinuado, não use em novos projetos
+  </div>
+  <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+    <span style={{ fontSize: '20px' }}>⚠️</span>
+    <strong>Experimental</strong>: Componente experimental, use com cautela
+  </div>
+</div>
+
+## Atoms
+
+<ComponentStatusTable
+  components={[
+    { name: 'Accordion', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Avatar', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Badge', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'BoxWrapper', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Button', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Checkbox', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Collapsible', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'ErrorMessage', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Info', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Input', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Label', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'NavLink', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Popover', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Progress', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Radio', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Select', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Separator', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'SidebarItem', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Skeleton', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Slider', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Spinner', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Switch', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Text', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Textarea', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Tooltip', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+  ]}
+/>
+
+## Molecules
+
+<ComponentStatusTable
+  components={[
+    { name: 'Breadcrumb', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Card', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'DatePicker', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Dropdown', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'EmptyState', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'FileUpload', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Form', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'NavbarGroup', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Pagination', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Rating', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'SearchInput', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'SidebarGroup', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'SidebarHeader', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'TableActions', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'TableFilters', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'TablePagination', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Tabs', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'TimePicker', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'ColorPicker', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+  ]}
+/>
+
+## Organisms
+
+<ComponentStatusTable
+  components={[
+    { name: 'CommandPalette', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'DataGrid', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Dialog', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Modal', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Sidebar', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Stepper', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Table', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Timeline', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+    { name: 'Toast', status: 'Stable', accessibility: 'WCAG 2.1 AA', tests: '>80%', docs: true },
+  ]}
+/>
+
+### Melhorias Recentes nos Organisms
+
+Os seguintes organisms foram auditados e melhorados com stories interativas, documentação de eventos e estados:
+
+- **CommandPalette**: Stories com testes de interação, navegação por teclado, busca em tempo real, e documentação completa de eventos e estados
+- **Toast**: Stories para todas as variantes, ações, durações customizadas, toasts persistentes, e gerenciamento de múltiplos toasts
+- **Timeline**: Stories interativas, suporte a muitos itens, e documentação de estados e orientações
+- **Stepper**: Stories com validação, workflows complexos, e testes de interação completos
+
+Todos esses components agora têm:
+- ✅ ArgTypes completos e documentados
+- ✅ Testes de interação com `play` functions
+- ✅ Eventos documentados no [Event Catalog](./EventCatalog.mdx)
+- ✅ Estados documentados no [State Catalog](./StateCatalog.mdx)
+- ✅ Stories que demonstram comportamento real (não apenas args)
+
+## Estatísticas Gerais
+
+<div style={{
+  display: 'grid',
+  gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))',
+  gap: '16px',
+  marginTop: '32px',
+  marginBottom: '32px'
+}}>
+  <div style={{
+    padding: '16px',
+    border: '1px solid #e5e7eb',
+    borderRadius: '8px',
+    backgroundColor: '#f9fafb'
+  }}>
+    <div style={{ fontSize: '24px', fontWeight: 'bold', color: '#1f2937' }}>58</div>
+    <div style={{ fontSize: '14px', color: '#6b7280', marginTop: '4px' }}>Total de Componentes</div>
+  </div>
+  <div style={{
+    padding: '16px',
+    border: '1px solid #e5e7eb',
+    borderRadius: '8px',
+    backgroundColor: '#f9fafb'
+  }}>
+    <div style={{ fontSize: '24px', fontWeight: 'bold', color: '#10b981' }}>58</div>
+    <div style={{ fontSize: '14px', color: '#6b7280', marginTop: '4px' }}>Componentes Estáveis</div>
+  </div>
+  <div style={{
+    padding: '16px',
+    border: '1px solid #e5e7eb',
+    borderRadius: '8px',
+    backgroundColor: '#f9fafb'
+  }}>
+    <div style={{ fontSize: '24px', fontWeight: 'bold', color: '#10b981' }}>>80%</div>
+    <div style={{ fontSize: '14px', color: '#6b7280', marginTop: '4px' }}>Cobertura de Testes</div>
+  </div>
+  <div style={{
+    padding: '16px',
+    border: '1px solid #e5e7eb',
+    borderRadius: '8px',
+    backgroundColor: '#f9fafb'
+  }}>
+    <div style={{ fontSize: '24px', fontWeight: 'bold', color: '#10b981' }}>100%</div>
+    <div style={{ fontSize: '14px', color: '#6b7280', marginTop: '4px' }}>WCAG 2.1 AA</div>
+  </div>
+</div>
+
+## Roadmap
+
+### Próximos Componentes
+- [ ] Calendar
+- [ ] TreeView
+- [ ] Carousel
+- [ ] Drawer
+- [ ] Menu
+
+### Melhorias Planejadas
+- [ ] Melhorias de performance em componentes grandes
+- [ ] Suporte a RTL (Right-to-Left)
+- [ ] Mais variantes de temas
+- [ ] Componentes de data visualization
+
+## Notas
+
+- Todos os componentes seguem os padrões de Atomic Design
+- Todos os componentes são totalmente tipados com TypeScript
+- Todos os componentes têm documentação no Storybook
+- Todos os componentes têm testes automatizados
+
+## Reportar Problemas
+
+Se encontrar problemas com algum componente, por favor abra uma issue no [GitHub](https://github.com/fabiocaffarello/react-design-system/issues).

package/src/docs/DesignSystem.mdx

@@ -0,0 +1,121 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Design System/Overview" />
+
+# React Design System
+
+Bem-vindo ao React Design System! Este é um sistema de design moderno, escalável e flexível construído com React, TypeScript e Vite.
+
+## Visão Geral
+
+O React Design System fornece uma base sólida para construir componentes de UI consistentes, acessíveis e reutilizáveis em múltiplos projetos frontend.
+
+### Características Principais
+
+- **Atomic Design**: Organizado em Atoms, Molecules e Organisms para máxima reutilização
+- **Type-Safe**: Totalmente tipado com TypeScript
+- **Acessível**: WCAG 2.1 AA compliant
+- **Testado**: >80% de cobertura de testes
+- **Documentado**: Storybook com exemplos interativos
+- **Performático**: Otimizado com code splitting e React.memo
+- **Temático**: Sistema de temas avançado com suporte a múltiplos temas
+
+## Estrutura
+
+### Atoms
+Componentes básicos e indivisíveis que formam a base do sistema.
+
+**Exemplos**: Button, Input, Text, Badge, Avatar, Spinner
+
+### Molecules
+Combinações de atoms que formam componentes mais complexos.
+
+**Exemplos**: Card, SearchInput, Rating, FileUpload
+
+### Organisms
+Componentes complexos que combinam molecules e atoms.
+
+**Exemplos**: Table, DataGrid, Stepper, Timeline, CommandPalette
+
+## Design Tokens
+
+O sistema utiliza design tokens para garantir consistência:
+
+- **Cores**: Sistema semântico com suporte a light/dark themes
+- **Espaçamento**: Baseado em unidades de 4px
+- **Tipografia**: Escala tipográfica consistente
+- **Sombras**: Sistema de elevação
+- **Raio**: Bordas arredondadas padronizadas
+- **Animações**: Durações e easing functions consistentes
+
+Veja a [documentação completa de tokens](./Design%20System/Tokens).
+
+## Temas
+
+O sistema suporta temas avançados:
+
+- **Temas Built-in**: Light e Dark
+- **Temas Customizados**: Crie seus próprios temas
+- **CSS Variables**: Geração automática de variáveis CSS
+- **Theme Inheritance**: Herde de temas base
+- **Múltiplos Temas**: Use vários temas simultaneamente
+
+Veja a [documentação de temas](./Design%20System/Themes).
+
+## Instalação
+
+```bash
+npm install @fabio.caffarello/react-design-system
+```
+
+## Uso Básico
+
+```tsx
+import { Button, Input, Card } from '@fabio.caffarello/react-design-system';
+import { AdvancedThemeProvider } from '@fabio.caffarello/react-design-system';
+
+function App() {
+  return (
+    <AdvancedThemeProvider defaultTheme="light">
+      <Card padding="large">
+        <Input placeholder="Enter your name" />
+        <Button variant="primary">Submit</Button>
+      </Card>
+    </AdvancedThemeProvider>
+  );
+}
+```
+
+## Recursos
+
+### Acessibilidade
+- WCAG 2.1 AA compliant
+- Navegação por teclado completa
+- Suporte a screen readers
+- ARIA attributes apropriados
+
+### Performance
+- Code splitting por categoria
+- React.memo em componentes otimizados
+- Tree shaking automático
+- Bundle size otimizado
+
+### Testes
+- >80% de cobertura de testes
+- Testes de acessibilidade automatizados
+- Testes de regressão visual no Storybook
+
+## Próximos Passos
+
+1. Explore os [componentes disponíveis](./Design%20System/Components)
+2. Veja a [matriz de status dos componentes](./Design%20System/Component%20Status)
+3. Leia o [guia de getting started](./Design%20System/Getting%20Started)
+4. Consulte as [melhores práticas](./Design%20System/Best%20Practices)
+
+## Contribuindo
+
+Contribuições são bem-vindas! Veja nosso [guia de contribuição](https://github.com/fabiocaffarello/react-design-system/blob/main/CONTRIBUTING.md).
+
+## Licença
+
+MIT License - veja o arquivo LICENSE para detalhes.