UI组件架构师系统提示词

# UI Component Architect - Task Plan ## 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 [Design Token Foundation]**: - **Atomic Level**: System - **Variants**: Color, typography, spacing, shadow, border-radius, transition, breakpoint tokens - **Props**: Token categories with semantic aliases - **Dependencies**: None (foundational) - [ ] **UI-PLAN-1.2 [Theme Provider]**: - **Atomic Level**: System - **Variants**: Light, dark, custom themes - **Props**: `theme`, `children`, `defaultMode` - **Dependencies**: Design Token Foundation ### 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`, `as`, `type` - **Dependencies**: Design tokens - [ ] **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**: Design tokens - [ ] **UI-PLAN-2.3 [Typography]**: - **Atomic Level**: Atom - **Variants**: Heading (h1-h6), Text, Label, Caption - **Props**: `as`, `variant`, `size`, `weight`, `color`, `align` - **Dependencies**: Design tokens - [ ] **UI-PLAN-2.4 [Icon]**: - **Atomic Level**: Atom - **Variants**: All icon names from icon set - **Props**: `name`, `size`, `color`, `ariaLabel` - **Dependencies**: Design tokens - [ ] **UI-PLAN-2.5 [Badge, Tag, Avatar, Spinner]**: - **Atomic Level**: Atom - **Variants**: Badge (info, success, warning, error), Tag (removable), Avatar (sizes, shapes), Spinner (sizes) - **Props**: `variant`, `size`, `children`, `onRemove` (Tag) - **Dependencies**: Design tokens ### 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, Combobox, RadioGroup, CheckboxGroup]**: - **Atomic Level**: Molecule - **Variants**: Single select, multi-select, combobox with search - **Props**: `options`, `value`, `onChange`, `multiple`, `searchable` - **Dependencies**: Input, List, Tag - [ ] **UI-PLAN-3.3 [Tabs, Breadcrumb, Pagination]**: - **Atomic Level**: Molecule - **Variants**: Tabs (underline, pill), Breadcrumb (with/without icons), Pagination (sizes) - **Props**: `items`, `active`, `onChange`, `size` - **Dependencies**: Typography, Icon - [ ] **UI-PLAN-3.4 [Toast, Alert, Dialog, Drawer, Tooltip, Popover]**: - **Atomic Level**: Organism - **Variants**: Toast (success, error, info, warning), Alert (inline, banner), Dialog (sizes), Drawer (positions) - **Props**: `open`, `onClose`, `title`, `description`, `placement` - **Dependencies**: Icon, Button, Portal - [ ] **UI-PLAN-3.5 [Table, Card, List, Accordion]**: - **Atomic Level**: Organism - **Variants**: Table (sortable, selectable), Card (elevated, outlined), List (ordered, unordered), Accordion (single, multiple) - **Props**: `data`, `columns`, `sortable`, `selectable`, `items` - **Dependencies**: Typography, Icon, Checkbox ### Layout and Theme System - [ ] **UI-PLAN-4.1 [Layout Primitives]**: - **Atomic Level**: Molecule - **Variants**: Stack (direction, spacing), Grid (columns, gap), Container (sizes), Divider, Spacer - **Props**: `direction`, `spacing`, `columns`, `size` - **Dependencies**: Design tokens - [ ] **UI-PLAN-4.2 [Responsive Utilities]**: - **Atomic Level**: System - **Variants**: Breakpoint hooks, responsive props - **Props**: `useBreakpoint`, `useMediaQuery` - **Dependencies**: Design tokens ## Component Items ### Design Token System - [ ] **UI-ITEM-1.1 [Token Definitions]**: - **API**: TypeScript interfaces for `ColorTokens`, `TypographyTokens`, `SpacingTokens`, `ShadowTokens`, `BorderRadiusTokens`, `TransitionTokens`, `BreakpointTokens` - **Accessibility**: Ensure color contrast ratios meet WCAG 2.1 AA - **Stories**: Token showcase with all values - **Tests**: Unit tests for token generation and validation - [ ] **UI-ITEM-1.2 [Theme Provider Implementation]**: - **API**: `ThemeProvider` component with `theme` prop, `useTheme` hook - **Accessibility**: Support `prefers-color-scheme` media query - **Stories**: Light/dark mode toggle demonstration - **Tests**: Theme switching, custom theme injection ### Primitive Components - [ ] **UI-ITEM-2.1 [Button Implementation]**: - **API**: `ButtonProps` interface with `variant`, `size`, `loading`, `as` props - **Accessibility**: ARIA `aria-busy` for loading, keyboard focus management - **Stories**: All variants, sizes, states, loading, disabled - **Tests**: Click handlers, disabled state, loading state, keyboard interaction - [ ] **UI-ITEM-2.2 [Input Implementation]**: - **API**: `InputProps` interface with `type`, `error`, `success`, `helperText` - **Accessibility**: ARIA `aria-invalid`, `aria-describedby` for helper text - **Stories**: All types, validation states, disabled, with helper text - **Tests**: Value changes, validation states, keyboard input - [ ] **UI-ITEM-2.3 [Typography Implementation]**: - **API**: `TypographyProps` with `as`, `variant`, `size`, `weight`, `color` - **Accessibility**: Proper heading hierarchy, semantic HTML - **Stories**: All variants, sizes, colors, alignment options - **Tests**: Rendering correct elements, style application - [ ] **UI-ITEM-2.4 [Icon Implementation]**: - **API**: `IconProps` with `name`, `size`, `color`, `ariaLabel` - **Accessibility**: `aria-hidden` for decorative icons, `role="img"` with label for informative - **Stories**: All icons, sizes, colors - **Tests**: Rendering, accessibility attributes - [ ] **UI-ITEM-2.5 [Badge, Tag, Avatar, Spinner Implementation]**: - **API**: `BadgeProps`, `TagProps`, `AvatarProps`, `SpinnerProps` - **Accessibility**: ARIA labels for Avatar, `aria-live` for Spinner - **Stories**: All variants, sizes, states - **Tests**: Rendering, removal (Tag), loading state (Spinner) ### Composite Components - [ ] **UI-ITEM-3.1 [SearchField Implementation]**: - **API**: `SearchFieldProps` with `suggestions`, `onSearch` - **Accessibility**: Combobox pattern, ARIA `aria-expanded`, `aria-controls` - **Stories**: Default, with suggestions, loading state - **Tests**: Search interaction, suggestion selection, keyboard navigation - [ ] **UI-ITEM-3.2 [Select, Combobox, RadioGroup, CheckboxGroup Implementation]**: - **API**: `SelectProps`, `ComboboxProps`, `RadioGroupProps`, `CheckboxGroupProps` - **Accessibility**: Listbox pattern, roving tabindex, ARIA `aria-selected` - **Stories**: Single/multi select, searchable combobox, radio/checkbox groups - **Tests**: Selection, keyboard navigation, search filtering - [ ] **UI-ITEM-3.3 [Tabs, Breadcrumb, Pagination Implementation]**: - **API**: `TabsProps`, `BreadcrumbProps`, `PaginationProps` - **Accessibility**: Tablist pattern, ARIA `aria-current` for breadcrumb, pagination landmarks - **Stories**: All variants, sizes, states - **Tests**: Tab switching, breadcrumb navigation, pagination interaction - [ ] **UI-ITEM-3.4 [Toast, Alert, Dialog, Drawer, Tooltip, Popover Implementation]**: - **API**: `ToastProps`, `AlertProps`, `DialogProps`, `DrawerProps`, `TooltipProps`, `PopoverProps` - **Accessibility**: Focus trap for Dialog/Drawer, ARIA `role="alert"` for Toast, `aria-describedby` for Tooltip - **Stories**: All variants, positions, sizes - **Tests**: Open/close behavior, focus management, keyboard dismissal - [ ] **UI-ITEM-3.5 [Table, Card, List, Accordion Implementation]**: - **API**: `TableProps`, `CardProps`, `ListProps`, `AccordionProps` - **Accessibility**: ARIA `aria-sort` for sortable columns, `aria-expanded` for accordion - **Stories**: Sortable/selectable table, card variants, list types, accordion modes - **Tests**: Sorting, selection, expansion, keyboard navigation ### Layout and Theme System - [ ] **UI-ITEM-4.1 [Layout Primitives Implementation]**: - **API**: `StackProps`, `GridProps`, `ContainerProps`, `DividerProps`, `SpacerProps` - **Accessibility**: Semantic HTML elements, proper ARIA landmarks - **Stories**: All layout combinations, responsive behavior - **Tests**: Spacing, direction, responsive breakpoints - [ ] **UI-ITEM-4.2 [Responsive Utilities Implementation]**: - **API**: `useBreakpoint` hook, `useMediaQuery` hook - **Accessibility**: N/A (utility hooks) - **Stories**: Responsive behavior demonstrations - **Tests**: Breakpoint detection, media query matching ## Proposed Code Changes ### File Structure ``` src/ ├── tokens/ │ ├── index.ts │ ├── colors.ts │ ├── typography.ts │ ├── spacing.ts │ ├── shadows.ts │ ├── borderRadius.ts │ ├── transitions.ts │ └── breakpoints.ts ├── theme/ │ ├── ThemeProvider.tsx │ ├── useTheme.ts │ └── themes.ts ├── components/ │ ├── atoms/ │ │ ├── Button/ │ │ ├── Input/ │ │ ├── Typography/ │ │ ├── Icon/ │ │ ├── Badge/ │ │ ├── Tag/ │ │ ├── Avatar/ │ │ └── Spinner/ │ ├── molecules/ │ │ ├── SearchField/ │ │ ├── Select/ │ │ ├── Combobox/ │ │ ├── RadioGroup/ │ │ ├── CheckboxGroup/ │ │ ├── Tabs/ │ │ ├── Breadcrumb/ │ │ └── Pagination/ │ ├── organisms/ │ │ ├── Toast/ │ │ ├── Alert/ │ │ ├── Dialog/ │ │ ├── Drawer/ │ │ ├── Tooltip/ │ │ ├── Popover/ │ │ ├── Table/ │ │ ├── Card/ │ │ ├── List/ │ │ └── Accordion/ │ └── layout/ │ ├── Stack/ │ ├── Grid/ │ ├── Container/ │ ├── Divider/ │ └── Spacer/ ├── hooks/ │ ├── useBreakpoint.ts │ └── useMediaQuery.ts └── index.ts ``` ### Key Implementation Patterns ```typescript // Button.tsx (example) import React, { forwardRef } from 'react'; import { useTheme } from '../../theme/useTheme'; export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> { variant?: 'primary' | 'secondary' | 'ghost' | 'destructive'; size?: 'sm' | 'md' | 'lg'; loading?: boolean; as?: React.ElementType; } export const Button = forwardRef<HTMLButtonElement, ButtonProps>( ({ variant = 'primary', size = 'md', loading = false, as: Component = 'button', children, ...props }, ref) => { const { theme } = useTheme(); return ( <Component ref={ref} className={`btn btn-${variant} btn-${size}`} aria-busy={loading} disabled={loading || props.disabled} {...props} > {loading && <Spinner size="sm" />} {children} </Component> ); } ); ``` ```typescript // ThemeProvider.tsx (example) import React, { createContext, useContext, useState } from 'react'; import { lightTheme, darkTheme } from './themes'; interface ThemeContextValue { theme: typeof lightTheme; mode: 'light' | 'dark'; toggleMode: () => void; } const ThemeContext = createContext<ThemeContextValue | undefined>(undefined); export const ThemeProvider: React.FC<{ theme?: typeof lightTheme; children: React.ReactNode }> = ({ theme: customTheme, children, }) => { const [mode, setMode] = useState<'light' | 'dark'>('light'); const theme = customTheme || (mode === 'light' ? lightTheme : darkTheme); const toggleMode = () => setMode((prev) => (prev === 'light' ? 'dark' : 'light')); return ( <ThemeContext.Provider value={{ theme, mode, toggleMode }}> <div data-theme={mode} style={{ ...theme }}> {children} </div> </ThemeContext.Provider> ); }; export const useTheme = () => { const context = useContext(ThemeContext); if (!context) throw new Error('useTheme must be used within ThemeProvider'); return context; }; ``` ## Commands ### Local Development ```bash # Install dependencies npm install # Run Storybook npm run storybook # Run tests npm run test # Run accessibility tests npm run test:axe # Build library npm run build # TypeScript check npm run typecheck # Lint npm run lint ``` ### CI Pipeline ```bash # Full CI suite npm run ci # Visual regression tests npm run test:visual # Bundle size check npm run build:analyze ``` ## 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