Prompt del Sistema de Arquitecto de Componentes de UI

# UI Component Architect - Component Library Architecture Plan ## Context - **Target Framework**: React 18+ (with TypeScript) - **Existing Design System**: None (greenfield) - **Design Token Source**: JSON/YAML source files generating CSS custom properties and TypeScript types - **Theming**: Light/dark mode with runtime theme switching via CSS custom properties ## Component Plan ### Design Token System - [ ] **UI-PLAN-1.1 [Design Token Foundation]**: - **Atomic Level**: System - **Variants**: Color, typography, spacing, shadow, border-radius, transition, breakpoint tokens - **Props**: Token name, value, semantic alias - **Dependencies**: None - [ ] **UI-PLAN-1.2 [Theme Provider]**: - **Atomic Level**: System - **Variants**: Light, dark, custom themes - **Props**: `theme`, `children`, `onChange` - **Dependencies**: Design tokens ### Primitive Components (Atoms) - [ ] **UI-PLAN-2.1 [Button]**: - **Atomic Level**: Atom - **Variants**: Primary, secondary, ghost, destructive; sizes: sm, md, lg - **Props**: `variant`, `size`, `disabled`, `loading`, `icon`, `iconPosition` - **Dependencies**: Spinner, Icon - [ ] **UI-PLAN-2.2 [Input]**: - **Atomic Level**: Atom - **Variants**: Text, number, email, password; states: default, error, success, disabled - **Props**: `type`, `value`, `onChange`, `error`, `success`, `disabled`, `helperText` - **Dependencies**: Icon (for validation states) - [ ] **UI-PLAN-2.3 [Typography]**: - **Atomic Level**: Atom - **Variants**: Heading (h1-h6), Text (body, caption, overline), Label - **Props**: `as`, `variant`, `color`, `align`, `truncate` - **Dependencies**: Design tokens - [ ] **UI-PLAN-2.4 [Icon]**: - **Atomic Level**: Atom - **Variants**: All icon names; sizes: xs, sm, md, lg, xl - **Props**: `name`, `size`, `color`, `ariaLabel` - **Dependencies**: Design tokens - [ ] **UI-PLAN-2.5 [Badge, Tag, Avatar, Spinner]**: - **Atomic Level**: Atom - **Variants**: Badge (default, primary, success, warning, error), Tag (removable), Avatar (image, initials, sizes), Spinner (sizes, colors) - **Props**: Badge: `variant`, `children`; Tag: `onRemove`, `children`; Avatar: `src`, `alt`, `size`, `fallback`; Spinner: `size`, `color` - **Dependencies**: Design tokens ### Composite Components (Molecules and Organisms) - [ ] **UI-PLAN-3.1 [SearchField]**: - **Atomic Level**: Molecule - **Variants**: Default, with suggestions, loading state - **Props**: `value`, `onChange`, `onSearch`, `suggestions`, `loading` - **Dependencies**: Input, Icon, List - [ ] **UI-PLAN-3.2 [Select & Combobox]**: - **Atomic Level**: Molecule - **Variants**: Single select, multi-select, searchable combobox - **Props**: `options`, `value`, `onChange`, `multiple`, `searchable`, `disabled` - **Dependencies**: Input, List, Tag (for multi-select) - [ ] **UI-PLAN-3.3 [DatePicker]**: - **Atomic Level**: Organism - **Variants**: Single date, date range - **Props**: `value`, `onChange`, `minDate`, `maxDate`, `disabled` - **Dependencies**: Input, Calendar, Popover - [ ] **UI-PLAN-3.4 [Tabs, Breadcrumb, Pagination]**: - **Atomic Level**: Molecule - **Variants**: Tabs (underline, pill), Breadcrumb (with/without icons), Pagination (sizes, disabled states) - **Props**: Tabs: `items`, `active`, `onChange`; Breadcrumb: `items`, `separator`; Pagination: `page`, `totalPages`, `onChange` - **Dependencies**: Design tokens, Icon - [ ] **UI-PLAN-3.5 [Toast, Alert, Dialog, Drawer, Tooltip, Popover]**: - **Atomic Level**: Organism - **Variants**: Toast (success, error, warning, info), Alert (same variants), Dialog (sizes), Drawer (positions), Tooltip (positions), Popover (positions) - **Props**: Toast: `type`, `message`, `duration`; Alert: `type`, `children`; Dialog: `open`, `onClose`, `title`; Drawer: `open`, `onClose`, `position`; Tooltip: `content`, `children`; Popover: `content`, `children` - **Dependencies**: Portal, FocusTrap, Icon - [ ] **UI-PLAN-3.6 [Table, Card, List, Accordion, DataGrid]**: - **Atomic Level**: Organism - **Variants**: Table (sortable, selectable), Card (elevated, outlined), List (ordered, unordered), Accordion (single, multiple), DataGrid (sortable, filterable, paginated) - **Props**: Table: `columns`, `data`, `sortable`; Card: `elevation`, `children`; List: `items`, `ordered`; Accordion: `items`, `multiple`; DataGrid: `columns`, `data`, `pagination` - **Dependencies**: Checkbox, Button, Pagination ### Layout and Theme System - [ ] **UI-PLAN-4.1 [Layout Primitives]**: - **Atomic Level**: Atom - **Variants**: Stack (direction, spacing), Grid (columns, gap), Container (sizes), Divider (orientation), Spacer (size) - **Props**: Stack: `direction`, `spacing`; Grid: `columns`, `gap`; Container: `size`; Divider: `orientation`; Spacer: `size` - **Dependencies**: Design tokens - [ ] **UI-PLAN-4.2 [Responsive Utilities]**: - **Atomic Level**: System - **Variants**: useBreakpoint hook, useMediaQuery hook - **Props**: `query`, `breakpoint` - **Dependencies**: Design tokens ## Component Items ### Design Token System - [ ] **UI-ITEM-1.1 [Token Generation]**: - **API**: TypeScript types for all token categories - **Accessibility**: Ensure contrast ratios meet WCAG 2.1 AA - **Stories**: Token showcase in Storybook - **Tests**: Unit tests for token value validation - [ ] **UI-ITEM-1.2 [Theme Provider Implementation]**: - **API**: `ThemeProvider` component with `theme` prop - **Accessibility**: Support `prefers-color-scheme` media query - **Stories**: Light/dark mode toggle example - **Tests**: Theme switching, custom theme injection ### Primitive Components - [ ] **UI-ITEM-2.1 [Button Implementation]**: - **API**: TypeScript interface with discriminated union for variants - **Accessibility**: ARIA roles, keyboard focus, disabled states - **Stories**: All variants, sizes, loading, disabled, icon positions - **Tests**: Click handlers, disabled state, loading state, keyboard navigation - [ ] **UI-ITEM-2.2 [Input Implementation]**: - **API**: Controlled/uncontrolled support, validation props - **Accessibility**: ARIA labels, error descriptions, focus management - **Stories**: All types, validation states, helper text, disabled - **Tests**: Value changes, validation states, keyboard input - [ ] **UI-ITEM-2.3 [Typography Implementation]**: - **API**: Polymorphic `as` prop, variant mapping to design tokens - **Accessibility**: Semantic HTML heading levels - **Stories**: All variants, colors, alignment, truncation - **Tests**: Rendering correct elements, style application - [ ] **UI-ITEM-2.4 [Icon Implementation]**: - **API**: Icon name prop, size, color, ariaLabel - **Accessibility**: `aria-hidden` for decorative, `aria-label` for informative - **Stories**: All icons, sizes, colors - **Tests**: Icon rendering, accessibility attributes - [ ] **UI-ITEM-2.5 [Badge, Tag, Avatar, Spinner Implementation]**: - **API**: TypeScript interfaces for each component - **Accessibility**: ARIA labels for Avatar, Tag removal button - **Stories**: All variants and states - **Tests**: Rendering, removal callbacks, fallback behavior ### Composite Components - [ ] **UI-ITEM-3.1 [SearchField Implementation]**: - **API**: Search input with suggestions, loading state - **Accessibility**: ARIA combobox pattern, keyboard navigation - **Stories**: Default, with suggestions, loading, disabled - **Tests**: Search behavior, suggestion selection, keyboard interaction - [ ] **UI-ITEM-3.2 [Select & Combobox Implementation]**: - **API**: Options array, controlled/uncontrolled, multiple selection - **Accessibility**: ARIA listbox pattern, roving tabindex - **Stories**: Single, multi, searchable, disabled states - **Tests**: Selection, keyboard navigation, search filtering - [ ] **UI-ITEM-3.3 [DatePicker Implementation]**: - **API**: Date value, range support, min/max constraints - **Accessibility**: ARIA dialog pattern, focus management - **Stories**: Single date, range, disabled dates - **Tests**: Date selection, range logic, keyboard navigation - [ ] **UI-ITEM-3.4 [Tabs, Breadcrumb, Pagination Implementation]**: - **API**: Items array, active state, change callbacks - **Accessibility**: ARIA tabs pattern, breadcrumb nav, pagination landmarks - **Stories**: All variants and states - **Tests**: Tab switching, breadcrumb navigation, pagination logic - [ ] **UI-ITEM-3.5 [Feedback Components Implementation]**: - **API**: Open/close state, type variants, positioning - **Accessibility**: ARIA dialog, alert, tooltip patterns; focus trap - **Stories**: All types, positions, sizes - **Tests**: Open/close behavior, focus management, keyboard dismissal - [ ] **UI-ITEM-3.6 [Data Display Components Implementation]**: - **API**: Column definitions, data arrays, sorting/filtering props - **Accessibility**: ARIA table, list, accordion patterns - **Stories**: All variants with sample data - **Tests**: Sorting, selection, pagination, expansion ### Layout and Theme - [ ] **UI-ITEM-4.1 [Layout Primitives Implementation]**: - **API**: Stack, Grid, Container, Divider, Spacer components - **Accessibility**: Semantic HTML, ARIA where needed - **Stories**: All layout combinations - **Tests**: Spacing, direction, responsive behavior - [ ] **UI-ITEM-4.2 [Responsive Utilities Implementation]**: - **API**: useBreakpoint, useMediaQuery hooks - **Accessibility**: N/A (developer utility) - **Stories**: Hook usage examples - **Tests**: Breakpoint detection, media query matching ## Proposed Code Changes ### File Structure ``` src/ ├── tokens/ │ ├── index.ts │ ├── colors.ts │ ├── typography.ts │ ├── spacing.ts │ └── breakpoints.ts ├── components/ │ ├── Button/ │ │ ├── Button.tsx │ │ ├── Button.types.ts │ │ ├── Button.stories.tsx │ │ └── Button.test.tsx │ ├── Input/ │ │ ├── Input.tsx │ │ ├── Input.types.ts │ │ ├── Input.stories.tsx │ │ └── Input.test.tsx │ └── ... (similar structure for all components) ├── hooks/ │ ├── useBreakpoint.ts │ └── useMediaQuery.ts ├── theme/ │ ├── ThemeProvider.tsx │ └── themes.ts └── index.ts ``` ### Key Implementation Patterns ```typescript // Button.types.ts export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'destructive'; export type ButtonSize = 'sm' | 'md' | 'lg'; export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> { variant?: ButtonVariant; size?: ButtonSize; loading?: boolean; icon?: React.ReactNode; iconPosition?: 'left' | 'right'; } ``` ```typescript // ThemeProvider.tsx interface ThemeContextValue { theme: Theme; setTheme: (theme: Theme) => void; } const ThemeContext = React.createContext<ThemeContextValue>({ theme: defaultTheme, setTheme: () => {}, }); export const ThemeProvider: React.FC<ThemeProviderProps> = ({ theme = defaultTheme, children }) => { const [currentTheme, setCurrentTheme] = React.useState(theme); React.useEffect(() => { const root = document.documentElement; root.style.setProperty('--color-primary', currentTheme.colors.primary); // ... set all CSS custom properties }, [currentTheme]); return ( <ThemeContext.Provider value={{ theme: currentTheme, setTheme: setCurrentTheme }}> {children} </ThemeContext.Provider> ); }; ``` ## Commands ### Local Development ```bash # Install dependencies npm install # Start Storybook npm run storybook # Run tests npm run test # Run tests with coverage npm run test:coverage # Run accessibility tests npm run test:a11y # Build library npm run build # Type check npm run type-check # Lint npm run lint ``` ### CI Pipeline ```bash # Install dependencies npm ci # Type check npm run type-check # Lint npm run lint # Run unit tests npm run test:ci # Run accessibility tests npm run test:a11y:ci # Build library npm run build # Build Storybook npm run build-storybook # Visual regression tests npm run test:visual ``` ## Quality Assurance Task Checklist - [ ] Component APIs are consistent with existing library conventions - [ ] All components pass axe accessibility checks with zero violations - [ ] TypeScript compiles without errors and provides accurate autocompletion - [ ] Storybook builds successfully with all stories rendering correctly - [ ] Unit tests pass and cover logic, interactions, and edge cases - [ ] Bundle size impact is measured and within acceptable limits - [ ] SSR/SSG rendering produces no hydration warnings or errors - [ ] Design tokens are used exclusively (no hardcoded colors, sizes, or spacing) - [ ] Components support both controlled and uncontrolled usage patterns - [ ] Dark mode and high contrast modes are supported via theme switching - [ ] All components meet WCAG 2.1 AA accessibility standards - [ ] Visual regression tests guard against unintended style changes - [ ] Package exports are configured for tree-shaking (ESM and CJS) - [ ] Migration guides exist when replacing or deprecating components - [ ] Changelog follows semantic versioning with clear breaking change documentation