Prompt système d'architecte de composants d'interface utilisateur

# UI Component Architect ## Context - **Target Framework**: React 18 (with TypeScript) - **Existing Design System**: None (greenfield) - **Design Token Source**: JSON-based token definitions with CSS custom property output - **Theming**: Light/dark mode support with runtime theme switching ## Component Plan ### Design Token System - [ ] **UI-PLAN-1.1 [Color Tokens]**: - **Atomic Level**: Foundation - **Variants**: Semantic color scales (primary, secondary, error, success, neutral) - **Props**: Token name, value, CSS custom property mapping - **Dependencies**: None - [ ] **UI-PLAN-1.2 [Typography Tokens]**: - **Atomic Level**: Foundation - **Variants**: Font families, sizes, weights, line heights - **Props**: Token name, value, CSS custom property mapping - **Dependencies**: None - [ ] **UI-PLAN-1.3 [Spacing Tokens]**: - **Atomic Level**: Foundation - **Variants**: 4px-based scale (xs, sm, md, lg, xl, 2xl) - **Props**: Token name, value, CSS custom property mapping - **Dependencies**: None ### Primitive Components (Atoms) - [ ] **UI-PLAN-2.1 [Button]**: - **Atomic Level**: Atom - **Variants**: Primary, secondary, ghost, destructive - **Props**: variant, size, disabled, loading, icon, iconPosition - **Dependencies**: Spinner, Icon - [ ] **UI-PLAN-2.2 [Input]**: - **Atomic Level**: Atom - **Variants**: Text, number, email, password - **Props**: type, value, onChange, error, helperText, label, disabled - **Dependencies**: None - [ ] **UI-PLAN-2.3 [Typography]**: - **Atomic Level**: Atom - **Variants**: Heading (h1-h6), Text, Label, Caption - **Props**: as, variant, color, align, truncate - **Dependencies**: None - [ ] **UI-PLAN-2.4 [Icon]**: - **Atomic Level**: Atom - **Variants**: All icon names from icon set - **Props**: name, size, color, ariaLabel - **Dependencies**: None - [ ] **UI-PLAN-2.5 [Badge]**: - **Atomic Level**: Atom - **Variants**: Default, primary, success, warning, error - **Props**: variant, size, children, icon - **Dependencies**: Icon - [ ] **UI-PLAN-2.6 [Spinner]**: - **Atomic Level**: Atom - **Variants**: Small, medium, large - **Props**: size, color, label - **Dependencies**: None ### Composite Components (Molecules and Organisms) - [ ] **UI-PLAN-3.1 [SearchField]**: - **Atomic Level**: Molecule - **Variants**: Default, with suggestions - **Props**: value, onChange, onSearch, placeholder, suggestions - **Dependencies**: Input, Icon, List - [ ] **UI-PLAN-3.2 [Select]**: - **Atomic Level**: Molecule - **Variants**: Single, multiple, searchable - **Props**: options, value, onChange, multiple, searchable, disabled - **Dependencies**: Input, List, Icon - [ ] **UI-PLAN-3.3 [Tabs]**: - **Atomic Level**: Molecule - **Variants**: Default, underline, pills - **Props**: tabs, activeTab, onChange, orientation - **Dependencies**: None - [ ] **UI-PLAN-3.4 [Dialog]**: - **Atomic Level**: Organism - **Variants**: Modal, non-modal, confirm - **Props**: open, onClose, title, children, footer, size - **Dependencies**: Button, Icon, FocusTrap - [ ] **UI-PLAN-3.5 [Toast]**: - **Atomic Level**: Organism - **Variants**: Success, error, warning, info - **Props**: open, type, message, duration, onClose - **Dependencies**: Icon, Button - [ ] **UI-PLAN-3.6 [DataTable]**: - **Atomic Level**: Organism - **Variants**: Sortable, selectable, paginated - **Props**: columns, data, sortable, selectable, pagination - **Dependencies**: Checkbox, Button, Pagination ## Component Items ### Design Token System - [ ] **UI-ITEM-1.1 [Color Token Implementation]**: - **API**: TypeScript interface `ColorToken { name: string; value: string; cssVar: string; }` - **Accessibility**: Ensure WCAG 2.1 AA contrast ratios for text/background combinations - **Stories**: Storybook showing color palette with contrast checker - **Tests**: Unit tests for token generation and contrast validation - [ ] **UI-ITEM-1.2 [Typography Token Implementation]**: - **API**: TypeScript interface `TypographyToken { name: string; fontFamily: string; fontSize: string; fontWeight: number; lineHeight: number; }` - **Accessibility**: Minimum 16px base font size, adequate line heights - **Stories**: Storybook showing type scale with responsive behavior - **Tests**: Unit tests for token generation and responsive breakpoints - [ ] **UI-ITEM-1.3 [Spacing Token Implementation]**: - **API**: TypeScript interface `SpacingToken { name: string; value: number; cssVar: string; }` - **Accessibility**: N/A (non-visual) - **Stories**: Storybook showing spacing scale visualization - **Tests**: Unit tests for token generation and consistency ### Primitive Components (Atoms) - [ ] **UI-ITEM-2.1 [Button Implementation]**: - **API**: TypeScript interface with `variant: 'primary' | 'secondary' | 'ghost' | 'destructive'`, `size: 'sm' | 'md' | 'lg'`, `loading?: boolean`, `disabled?: boolean` - **Accessibility**: ARIA `aria-busy` for loading, `aria-disabled` for disabled, keyboard focusable, visible focus ring - **Stories**: All variants, sizes, loading/disabled states, with/without icons - **Tests**: Unit tests for click handlers, loading state, disabled state; visual regression for all variants - [ ] **UI-ITEM-2.2 [Input Implementation]**: - **API**: TypeScript interface with `type: 'text' | 'number' | 'email' | 'password'`, `error?: string`, `helperText?: string`, `label?: string` - **Accessibility**: ARIA `aria-invalid` for error, `aria-describedby` for helper/error text, visible focus ring - **Stories**: All types, validation states, with/without labels, disabled state - **Tests**: Unit tests for value changes, validation states, keyboard interaction; visual regression for all states - [ ] **UI-ITEM-2.3 [Typography Implementation]**: - **API**: TypeScript interface with `as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span'`, `variant?: 'heading' | 'text' | 'label' | 'caption'` - **Accessibility**: Proper heading hierarchy, semantic HTML elements - **Stories**: All variants, sizes, colors, alignment options - **Tests**: Unit tests for element rendering, semantic HTML; visual regression for type scale - [ ] **UI-ITEM-2.4 [Icon Implementation]**: - **API**: TypeScript interface with `name: string`, `size?: 'sm' | 'md' | 'lg'`, `color?: string`, `ariaLabel?: string` - **Accessibility**: `aria-hidden` for decorative icons, `role="img"` with `aria-label` for informative icons - **Stories**: All icons, sizes, colors, with/without labels - **Tests**: Unit tests for rendering, accessibility attributes; visual regression for icon set - [ ] **UI-ITEM-2.5 [Badge Implementation]**: - **API**: TypeScript interface with `variant: 'default' | 'primary' | 'success' | 'warning' | 'error'`, `size?: 'sm' | 'md' | 'lg'` - **Accessibility**: Ensure contrast ratios meet WCAG AA, `aria-label` if icon-only - **Stories**: All variants, sizes, with/without icons - **Tests**: Unit tests for rendering, variants; visual regression for all states - [ ] **UI-ITEM-2.6 [Spinner Implementation]**: - **API**: TypeScript interface with `size?: 'sm' | 'md' | 'lg'`, `color?: string`, `label?: string` - **Accessibility**: `role="status"` with `aria-live="polite"` for screen readers - **Stories**: All sizes, colors, with/without labels - **Tests**: Unit tests for rendering, accessibility attributes; visual regression for sizes ### Composite Components (Molecules and Organisms) - [ ] **UI-ITEM-3.1 [SearchField Implementation]**: - **API**: TypeScript interface with `value: string`, `onChange: (value: string) => void`, `onSearch?: () => void`, `suggestions?: string[]` - **Accessibility**: ARIA combobox pattern, `aria-expanded` for suggestions, keyboard navigation - **Stories**: Default, with suggestions, loading state, disabled state - **Tests**: Unit tests for search behavior, suggestion selection, keyboard interaction; visual regression for all states - [ ] **UI-ITEM-3.2 [Select Implementation]**: - **API**: TypeScript interface with `options: SelectOption[]`, `value: string | string[]`, `onChange: (value: string | string[]) => void`, `multiple?: boolean`, `searchable?: boolean` - **Accessibility**: ARIA listbox pattern, `aria-selected` for options, keyboard navigation - **Stories**: Single, multiple, searchable, disabled states - **Tests**: Unit tests for selection, search filtering, keyboard interaction; visual regression for all states - [ ] **UI-ITEM-3.3 [Tabs Implementation]**: - **API**: TypeScript interface with `tabs: TabItem[]`, `activeTab: string`, `onChange: (tabId: string) => void`, `orientation?: 'horizontal' | 'vertical'` - **Accessibility**: ARIA tabs pattern, roving tabindex, `aria-selected` for active tab - **Stories**: All variants, orientations, disabled tabs - **Tests**: Unit tests for tab switching, keyboard navigation, focus management; visual regression for all states - [ ] **UI-ITEM-3.4 [Dialog Implementation]**: - **API**: TypeScript interface with `open: boolean`, `onClose: () => void`, `title?: string`, `size?: 'sm' | 'md' | 'lg' | 'xl'` - **Accessibility**: ARIA dialog pattern, focus trap, `aria-modal="true"`, escape key to close - **Stories**: Modal, non-modal, confirm dialog, all sizes - **Tests**: Unit tests for open/close behavior, focus management, escape key; visual regression for all sizes - [ ] **UI-ITEM-3.5 [Toast Implementation]**: - **API**: TypeScript interface with `open: boolean`, `type: 'success' | 'error' | 'warning' | 'info'`, `message: string`, `duration?: number`, `onClose: () => void` - **Accessibility**: ARIA live region, `role="alert"` for errors, `role="status"` for others - **Stories**: All types, with/without actions, auto-dismiss - **Tests**: Unit tests for display, auto-dismiss, close behavior; visual regression for all types - [ ] **UI-ITEM-3.6 [DataTable Implementation]**: - **API**: TypeScript interface with `columns: Column[]`, `data: Record<string, unknown>[]`, `sortable?: boolean`, `selectable?: boolean`, `pagination?: PaginationConfig` - **Accessibility**: ARIA table roles, `aria-sort` for sortable columns, keyboard navigation for selection - **Stories**: Sortable, selectable, paginated, empty state - **Tests**: Unit tests for sorting, selection, pagination; visual regression for all states ## Proposed Code Changes ### Design Token System ```json // tokens/colors.json { "color": { "primary": { "50": "#eff6ff", "100": "#dbeafe", "200": "#bfdbfe", "300": "#93c5fd", "400": "#60a5fa", "500": "#3b82f6", "600": "#2563eb", "700": "#1d4ed8", "800": "#1e40af", "900": "#1e3a8a" }, "neutral": { "50": "#f9fafb", "100": "#f3f4f6", "200": "#e5e7eb", "300": "#d1d5db", "400": "#9ca3af", "500": "#6b7280", "600": "#4b5563", "700": "#374151", "800": "#1f2937", "900": "#111827" } } } ``` ```typescript // src/tokens/generateTokens.ts export interface ColorToken { name: string; value: string; cssVar: string; } export function generateColorTokens(colors: Record<string, Record<string, string>>): ColorToken[] { const tokens: ColorToken[] = []; for (const [colorName, shades] of Object.entries(colors)) { for (const [shade, value] of Object.entries(shades)) { tokens.push({ name: `color.${colorName}.${shade}`, value, cssVar: `--color-${colorName}-${shade}` }); } } return tokens; } ``` ### Button Component ```typescript // src/components/Button/Button.tsx import React, { forwardRef } from 'react'; export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> { variant?: 'primary' | 'secondary' | 'ghost' | 'destructive'; size?: 'sm' | 'md' | 'lg'; loading?: boolean; icon?: React.ReactNode; iconPosition?: 'left' | 'right'; } export const Button = forwardRef<HTMLButtonElement, ButtonProps>( ({ variant = 'primary', size = 'md', loading = false, icon, iconPosition = 'left', children, disabled, ...props }, ref) => { const isDisabled = disabled || loading; return ( <button ref={ref} className={`btn btn-${variant} btn-${size}`} disabled={isDisabled} aria-busy={loading} aria-disabled={isDisabled} {...props} > {loading && <span className="btn-spinner" aria-hidden="true" />} {icon && iconPosition === 'left' && <span className="btn-icon-left">{icon}</span>} <span className="btn-content">{children}</span> {icon && iconPosition === 'right' && <span className="btn-icon-right">{icon}</span>} </button> ); } ); Button.displayName = 'Button'; ``` ### Dialog Component ```typescript // src/components/Dialog/Dialog.tsx import React, { useEffect, useRef } from 'react'; import { createPortal } from 'react-dom'; export interface DialogProps { open: boolean; onClose: () => void; title?: string; size?: 'sm' | 'md' | 'lg' | 'xl'; children: React.ReactNode; footer?: React.ReactNode; } export const Dialog: React.FC<DialogProps> = ({ open, onClose, title, size = 'md', children, footer }) => { const dialogRef = useRef<HTMLDivElement>(null); useEffect(() => { if (open) { const previousFocus = document.activeElement as HTMLElement; dialogRef.current?.focus(); const handleKeyDown = (event: KeyboardEvent) => { if (event.key === 'Escape') { onClose(); } }; document.addEventListener('keydown', handleKeyDown); document.body.style.overflow = 'hidden'; return () => { document.removeEventListener('keydown', handleKeyDown); document.body.style.overflow = ''; previousFocus?.focus(); }; } }, [open, onClose]); if (!open) return null; return createPortal( <div className="dialog-overlay" onClick={onClose}> <div ref={dialogRef} className={`dialog dialog-${size}`} role="dialog" aria-modal="true" aria-labelledby={title ? 'dialog-title' : undefined} tabIndex={-1} onClick={(e) => e.stopPropagation()} > {title && <h2 id="dialog-title" className="dialog-title">{title}</h2>} <div className="dialog-content">{children}</div> {footer && <div className="dialog-footer">{footer}</div>} </div> </div>, document.body ); }; ``` ## Commands ### Local Development ```bash # Install dependencies npm install # Start Storybook npm run storybook # Run unit tests npm run test # Run accessibility tests npm run test:axe # Run visual regression tests npm run test:visual # Build the library npm run build # TypeScript type checking npm run typecheck ``` ### CI Pipeline ```bash # Install dependencies npm ci # Run all tests npm run test:ci # Build and verify npm run build:ci # Check bundle size npm run size-check ``` ## 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