moai-domain-uiux

Original source / Raw SKILL.md

---
name: moai-domain-uiux
aliases: [moai-foundation-uiux]
category: domain
description: Domain UI/UX Expert - Enterprise design systems, component architecture, accessibility, icons, and theming integration
version: 2.0.0
modularized: true
tags:
 - domain
 - uiux
 - design-systems
 - accessibility
 - components
 - icons
 - theming
updated: 2025-11-30
status: active
---

## Quick Reference (30 seconds)

# Core UI/UX Foundation

Enterprise-grade UI/UX foundation integrating design systems (W3C DTCG 2025.10), component architecture (React 19, Vue 3.5), accessibility (WCAG 2.2), icon libraries (200K+ icons), and theming systems.

Unified Capabilities:
- Design Systems: W3C DTCG 2025.10 tokens, Style Dictionary 4.0, Figma MCP workflows
- Component Architecture: Atomic Design, React 19, Vue 3.5, shadcn/ui, Radix UI primitives
- Accessibility: WCAG 2.2 AA/AAA compliance, keyboard navigation, screen reader optimization
- Icon Libraries: 10+ ecosystems (Lucide, React Icons 35K+, Tabler 5900+, Iconify 200K+)
- Theming: CSS variables, light/dark modes, theme provider, brand customization

When to Use:
- Building modern UI component libraries with design system foundations
- Implementing accessible, enterprise-grade user interfaces
- Setting up design token architecture for multi-platform projects
- Integrating comprehensive icon systems with optimal bundle sizes
- Creating customizable theming systems with dark mode support

Module Organization:
- Components: [Component Architecture](modules/component-architecture.md) (Atomic Design, component patterns, props APIs)
- Design Systems: [Design System Tokens](modules/design-system-tokens.md) (DTCG tokens, Style Dictionary, Figma MCP)
- Accessibility: [Accessibility WCAG](modules/accessibility-wcag.md) (WCAG 2.2 compliance, testing, navigation)
- Icons: [Icon Libraries](modules/icon-libraries.md) (10+ libraries, selection guide, performance optimization)
- Theming: [Theming System](modules/theming-system.md) (theme system, CSS variables, brand customization)
- Examples: [Examples](examples.md) (practical implementation examples)
- Reference: [Reference](reference.md) (external documentation links)

---

## Implementation Guide

### Foundation Stack (November 2025)

Core Technologies:
- React 19 (Server Components, Concurrent Rendering)
- TypeScript 5.5 (Full type safety, improved inference)
- Tailwind CSS 3.4 (JIT compilation, CSS variables, dark mode)
- Radix UI (Unstyled accessible primitives)
- W3C DTCG 2025.10 (Design token specification)
- Style Dictionary 4.0 (Token transformation)
- Figma MCP (Design-to-code automation)
- Storybook 8.x (Component documentation)

Quick Decision Matrix:
| Need | Module | Key Tools |
|------|--------|-----------|
| Design tokens | [Design System Tokens](modules/design-system-tokens.md) | DTCG 2025.10, Style Dictionary 4.0 |
| Component patterns | [Component Architecture](modules/component-architecture.md) | Atomic Design, React 19, shadcn/ui |
| Accessibility | [Accessibility WCAG](modules/accessibility-wcag.md) | WCAG 2.2, jest-axe, keyboard nav |
| Icons | [Icon Libraries](modules/icon-libraries.md) | Lucide, React Icons, Tabler, Iconify |
| Theming | [Theming System](modules/theming-system.md) | CSS variables, Theme Provider |
| Examples | [Examples](examples.md) | React/Vue implementations |

---

## Quick Start Workflows

### 1. Design System Setup (30 minutes)

Step 1: Initialize design tokens
```json
{
 "$schema": "https://tr.designtokens.org/format/",
 "$tokens": {
 "color": {
 "$type": "color",
 "primary": { "500": { "$value": "#3b82f6" } }
 },
 "spacing": {
 "$type": "dimension",
 "md": { "$value": "1rem" }
 }
 }
}
```

Step 2: Transform tokens with Style Dictionary
```bash
npm install --save-dev style-dictionary
npx style-dictionary build
```

Step 3: Integrate with components
```typescript
import { colors, spacing } from '@/tokens'
```

See: [Design System Tokens](modules/design-system-tokens.md) for complete token architecture

---

### 2. Component Library Setup (45 minutes)

Step 1: Initialize shadcn/ui
```bash
npx shadcn-ui@latest init
npx shadcn-ui@latest add button form dialog
```

Step 2: Setup Atomic Design structure
```
components/
 atoms/ (Button, Input, Label)
 molecules/ (FormGroup, Card)
 organisms/ (DataTable, Modal)
```

Step 3: Implement with accessibility
```typescript
<Button aria-label="Submit form" variant="primary">
 Submit
</Button>
```

See: [Component Architecture](modules/component-architecture.md) for patterns and examples

---

### 3. Icon System Integration (15 minutes)

Step 1: Choose icon library
```bash
# General purpose
npm install lucide-react

# Maximum variety
npm install @iconify/react

# Dashboard optimized
npm install @tabler/icons-react
```

Step 2: Implement type-safe icons
```typescript
import { Heart, Search } from 'lucide-react'

<Search className="w-5 h-5 text-gray-600" />
```

See: [Icon Libraries](modules/icon-libraries.md) for library comparison and optimization

---

### 4. Theme System Setup (30 minutes)

Step 1: Configure CSS variables
```css
:root {
 --primary: 222.2 47.4% 11.2%;
 --background: 0 0% 100%;
}

.dark {
 --primary: 210 40% 98%;
 --background: 222.2 84% 4.9%;
}
```

Step 2: Implement Theme Provider
```typescript
<ThemeProvider attribute="class" defaultTheme="system">
 <App />
</ThemeProvider>
```

See: [Theming System](modules/theming-system.md) for complete theme system

---

## Key Principles

1. Design Token First:
- Single source of truth for design decisions
- Semantic naming (`color.primary.500` not `blue-500`)
- Multi-theme support (light/dark)
- Platform-agnostic transformation

2. Accessibility by Default:
- WCAG 2.2 AA minimum (4.5:1 text contrast)
- Keyboard navigation for all interactive elements
- ARIA attributes for screen readers
- Focus management and visible indicators

3. Component Composition:
- Atomic Design hierarchy (Atoms → Molecules → Organisms)
- Props API for reusability
- Variant-based styling (not separate components)
- Type-safe with TypeScript

4. Performance Optimization:
- Tree-shaking for icons (import specific, not *)
- Lazy loading for large components
- React.memo for expensive renders
- Bundle size monitoring

---

## Tool Ecosystem

| Category | Tool | Version | Purpose |
|----------|------|---------|---------|
| Design Tokens | W3C DTCG | 2025.10 | Token specification |
| | Style Dictionary | 4.0+ | Token transformation |
| Components | React | 19 | UI framework |
| | shadcn/ui | Latest | Component library |
| | Radix UI | Latest | Accessible primitives |
| Icons | Lucide | Latest | 1000+ modern icons |
| | React Icons | Latest | 35K+ multi-library |
| | Iconify | Latest | 200K+ universal |
| Theming | Tailwind CSS | 3.4 | Utility-first CSS |
| | CSS Variables | Native | Theme tokens |
| Accessibility | axe DevTools | Latest | Accessibility testing |
| | jest-axe | Latest | Automated a11y tests |
| Documentation | Storybook | 8.x | Component docs |
| | Figma MCP | Latest | Design-to-code |

---

## Module Cross-Reference

### [Component Architecture](modules/component-architecture.md)
Focus: Component architecture and implementation patterns

Key Topics:
- Atomic Design (Atoms, Molecules, Organisms)
- React 19 + Server Components
- Vue 3.5 + Composition API
- shadcn/ui component patterns
- Props API design
- Storybook integration

When to Use: Building or architecting UI component libraries

---

### [Design System Tokens](modules/design-system-tokens.md)
Focus: Design token architecture and tooling

Key Topics:
- W3C DTCG 2025.10 token structure
- Style Dictionary configuration
- Multi-theme support
- Figma MCP workflow
- Semantic naming conventions

When to Use: Setting up design system foundations

---

### [Accessibility WCAG](modules/accessibility-wcag.md)
Focus: WCAG 2.2 compliance and accessibility testing

Key Topics:
- Color contrast validation (4.5:1 AA, 7:1 AAA)
- Keyboard navigation patterns
- Screen reader optimization (ARIA)
- Focus management
- Automated testing (jest-axe)

When to Use: Ensuring accessibility compliance

---

### [Icon Libraries](modules/icon-libraries.md)
Focus: Icon library selection and integration

Key Topics:
- 10+ library comparison (Lucide, React Icons, Tabler, Iconify)
- Bundle size optimization
- Tree-shaking strategies
- Type-safe icon components
- Performance patterns

When to Use: Integrating icon systems with optimal bundle sizes

---

### [Theming System](modules/theming-system.md)
Focus: Theme system implementation

Key Topics:
- CSS variable architecture
- Light/dark mode switching
- System preference detection
- Brand customization
- Tailwind CSS integration

When to Use: Implementing customizable theming

---

### [Examples](examples.md)
Focus: Practical code examples

Key Topics:
- Button component (React, Vue)
- Form validation (Zod + React Hook Form)
- Data table (TanStack Table)
- Modal dialog (focus trap)
- Theme provider
- Icon usage patterns

When to Use: Reference implementations

---

### [Reference](reference.md)
Focus: External documentation links

Key Topics:
- Official documentation (DTCG, WCAG, Figma, Storybook)
- Library references (React, Tailwind, Radix UI)
- Tool documentation (Style Dictionary, jest-axe)
- Best practice guides

When to Use: Finding official resources

---

## Best Practices

DO:
- Use semantic design tokens (`color.primary.500` not `blue-500`)
- Follow Atomic Design hierarchy (Atoms → Molecules → Organisms)
- Verify 4.5:1 contrast ratio for all text (WCAG AA)
- Implement keyboard navigation for all interactive elements
- Tree-shake icons (import specific, avoid `import *`)
- Use CSS variables for theme customization
- Document all props with TypeScript types
- Test components with jest-axe for accessibility

Required Practices:

[HARD] Use design tokens exclusively for all color, spacing, and typography values
WHY: Design tokens provide a single source of truth, enabling consistent theming, multi-platform support, and scalable design systems
IMPACT: Hardcoded values create maintenance debt, break theme switching, and violate design system principles

[HARD] Include ARIA labels on all icon-only interactive elements
WHY: Screen readers cannot interpret visual icons without text alternatives, making content inaccessible to users with visual impairments
IMPACT: Missing ARIA labels violate WCAG 2.2 AA compliance and exclude users who depend on assistive technologies

[HARD] Import icons individually rather than using namespace imports
WHY: Namespace imports (`import * from 'lucide-react'`) bundle entire libraries, defeating tree-shaking optimization
IMPACT: Bundle sizes increase by 500KB-2MB per icon library, degrading load performance and user experience

[HARD] Test all components in both light and dark modes
WHY: Theme switching affects color contrast, readability, and accessibility compliance across all UI states
IMPACT: Untested dark mode implementations may fail WCAG contrast requirements and create unusable interfaces

[HARD] Implement keyboard navigation for all interactive components
WHY: Keyboard-only users and assistive technology users require Tab, Enter, Escape, and Arrow key support
IMPACT: Missing keyboard support violates WCAG 2.2 AA and excludes users who cannot use pointing devices

[HARD] Provide visible focus indicators for all focusable elements
WHY: Focus indicators communicate current keyboard position, essential for navigation and accessibility
IMPACT: Invisible focus states create confusion, violate WCAG 2.2 AA, and make keyboard navigation unusable

[SOFT] Use Tailwind utility classes instead of inline styles
WHY: Tailwind provides consistent spacing scale, responsive design, and automatic purging for optimal bundle sizes
IMPACT: Inline styles bypass design system constraints, create inconsistent spacing, and increase CSS bundle size

[SOFT] Include loading states for all asynchronous operations
WHY: Loading states provide feedback during data fetching, preventing user uncertainty and duplicate actions
IMPACT: Missing loading states create poor user experience with unclear interface states and potential duplicate submissions

---

## Works Well With

Skills:
- `moai-lang-typescript` - TypeScript and JavaScript best practices
- `moai-foundation-core` - TRUST 5 quality validation
- `moai-library-nextra` - Documentation generation
- `moai-library-shadcn` - shadcn/ui specialized patterns (complementary)

Agents:
- `code-frontend` - Frontend component implementation
- `design-uiux` - Design system architecture
- `mcp-figma` - Figma integration workflows
- `core-quality` - Accessibility and quality validation

Commands:
- `/moai:2-run` - TDD implementation cycle
- `/moai:3-sync` - Documentation generation

---

## Migration from Legacy Skills

This skill consolidates 4 previous skills:

moai-component-designer → [Component Architecture](modules/component-architecture.md)
- Atomic Design patterns
- React 19 / Vue 3.5 examples
- Component architecture

moai-design-systems → [Design System Tokens](modules/design-system-tokens.md) + [Accessibility WCAG](modules/accessibility-wcag.md)
- DTCG token architecture
- Figma MCP workflows
- WCAG 2.2 compliance

moai-icons-vector → [Icon Libraries](modules/icon-libraries.md)
- Icon library comparison
- Performance optimization
- Integration patterns

moai-library-shadcn (partially) → [Component Architecture](modules/component-architecture.md) + [Theming System](modules/theming-system.md)
- shadcn/ui patterns
- Theme system
- Component composition

Note: `moai-library-shadcn` remains as a complementary skill for shadcn/ui-specific advanced patterns.

---

## Official Resources

- W3C DTCG: https://designtokens.org
- WCAG 2.2: https://www.w3.org/WAI/WCAG22/quickref/
- React 19: https://react.dev
- Tailwind CSS: https://tailwindcss.com
- Radix UI: https://www.radix-ui.com
- shadcn/ui: https://ui.shadcn.com
- Storybook: https://storybook.js.org
- Figma MCP: https://help.figma.com/hc/en-us/articles/32132100833559
- Style Dictionary: https://styledictionary.com
- Lucide Icons: https://lucide.dev
- Iconify: https://iconify.design

---

Last Updated: 2025-11-26
Status: Production Ready
Version: 1.0.0


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### modules/component-architecture.md

```markdown
name: moai-foundation-uiux-components
description: Atomic Design component patterns and implementation

## Atomic Design Component Structure

### Folder Hierarchy

```
src/design-system/
 tokens/ # Design tokens (DTCG format)
 color.json
 typography.json
 spacing.json
 components/
 atoms/ # Basic building blocks
 Button/
 Button.tsx
 Button.stories.tsx
 Button.test.tsx
 index.ts
 Input/
 Icon/
 molecules/ # Simple combinations
 FormField/
 SearchBar/
 Card/
 organisms/ # Complex sections
 Header/
 Footer/
 DataTable/
 templates/ # Page layouts
 DashboardLayout/
 AuthLayout/
 styles/
 global.css
 theme.css
```

### Component Props API Pattern

```typescript
// atoms/Button/Button.tsx
import { forwardRef } from 'react';
import { cva, type VariantProps } from 'class-variance-authority';

const buttonVariants = cva(
 'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50',
 {
 variants: {
 variant: {
 primary: 'bg-primary-500 text-white hover:bg-primary-600',
 secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300',
 outline: 'border border-gray-300 bg-transparent hover:bg-gray-100',
 ghost: 'hover:bg-gray-100',
 danger: 'bg-red-500 text-white hover:bg-red-600'
 },
 size: {
 sm: 'h-8 px-3 text-sm',
 md: 'h-10 px-4 text-base',
 lg: 'h-12 px-6 text-lg'
 }
 },
 defaultVariants: {
 variant: 'primary',
 size: 'md'
 }
 }
);

export interface ButtonProps
 extends React.ButtonHTMLAttributes<HTMLButtonElement>,
 VariantProps<typeof buttonVariants> {
 isLoading?: boolean;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
 ({ className, variant, size, isLoading, children, disabled, ...props }, ref) => {
 return (
 <button
 ref={ref}
 className={buttonVariants({ variant, size, className })}
 disabled={disabled || isLoading}
 aria-busy={isLoading}
 {...props}
 >
 {isLoading ? <Spinner /> : children}
 </button>
 );
 }
);

Button.displayName = 'Button';
```

### Storybook Documentation Setup

Installation & Configuration:

```bash
npx storybook@latest init
```

Storybook Configuration (v8.x):

```typescript
// .storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
 stories: ['../src//*.stories.@(js|jsx|ts|tsx|mdx)'],
 addons: [
 '@storybook/addon-links',
 '@storybook/addon-essentials',
 '@storybook/addon-interactions',
 '@storybook/addon-a11y', // Accessibility testing
 ],
 framework: {
 name: '@storybook/react-vite',
 options: {},
 },
 docs: {
 autodocs: 'tag', // Auto-generate docs
 },
};

export default config;
```

### Component Story with Accessibility Tests

```typescript
// components/atoms/Button/Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
 title: 'Atoms/Button',
 component: Button,
 tags: ['autodocs'],
 argTypes: {
 variant: {
 control: 'select',
 options: ['primary', 'secondary', 'outline', 'ghost', 'danger'],
 },
 size: {
 control: 'select',
 options: ['sm', 'md', 'lg'],
 },
 },
};

export default meta;
type Story = StoryObj<typeof Button>;

export const Primary: Story = {
 args: {
 children: 'Primary Button',
 variant: 'primary',
 },
};

export const AllVariants: Story = {
 render: () => (
 <div className="flex gap-4">
 <Button variant="primary">Primary</Button>
 <Button variant="secondary">Secondary</Button>
 <Button variant="outline">Outline</Button>
 <Button variant="ghost">Ghost</Button>
 <Button variant="danger">Danger</Button>
 </div>
 ),
};

export const Disabled: Story = {
 args: {
 children: 'Disabled Button',
 disabled: true,
 },
};

export const Loading: Story = {
 args: {
 children: 'Loading Button',
 isLoading: true,
 },
};
```

### Input Component with Accessibility

```typescript
// components/atoms/Input/Input.tsx
export const Input = forwardRef<HTMLInputElement, InputProps>(
 ({ label, error, required, ...props }, ref) => {
 const inputId = useId();
 const errorId = `${inputId}-error`;
 
 return (
 <div className="form-field">
 <label htmlFor={inputId} className="form-label">
 {label}
 {required && <span aria-label="required">*</span>}
 </label>
 
 <input
 ref={ref}
 id={inputId}
 aria-invalid={!!error}
 aria-describedby={error ? errorId : undefined}
 aria-required={required}
 {...props}
 />
 
 {error && (
 <span id={errorId} role="alert" className="error-message">
 {error}
 </span>
 )}
 </div>
 );
 }
);
```

---

Last Updated: 2025-11-26
Related: [Main Skill](../SKILL.md), [Accessibility WCAG](accessibility-wcag.md)

```

### modules/accessibility-wcag.md

```markdown
name: moai-foundation-uiux-accessibility
description: WCAG 2.2 compliance, testing, and keyboard navigation

## WCAG 2.2 Accessibility Implementation

### Color Contrast Validation

```typescript
// utils/a11y/contrast.ts
/
 * Calculate relative luminance for WCAG compliance
 * @see https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html
 */
function getLuminance(rgb: [number, number, number]): number {
 const [r, g, b] = rgb.map(val => {
 const sRGB = val / 255;
 return sRGB <= 0.03928
 ? sRGB / 12.92
 : Math.pow((sRGB + 0.055) / 1.055, 2.4);
 });
 return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}

/
 * Calculate contrast ratio between two colors
 * WCAG AA: 4.5:1 (normal text), 3:1 (large text)
 * WCAG AAA: 7:1 (normal text), 4.5:1 (large text)
 */
export function getContrastRatio(
 foreground: string,
 background: string
): number {
 const fgLum = getLuminance(hexToRgb(foreground));
 const bgLum = getLuminance(hexToRgb(background));
 const lighter = Math.max(fgLum, bgLum);
 const darker = Math.min(fgLum, bgLum);
 return (lighter + 0.05) / (darker + 0.05);
}

/
 * Check if color pair meets WCAG AA/AAA requirements
 */
export function meetsWCAG(
 foreground: string,
 background: string,
 level: 'AA' | 'AAA' = 'AA',
 isLargeText: boolean = false
): boolean {
 const ratio = getContrastRatio(foreground, background);
 
 if (level === 'AAA') {
 return isLargeText ? ratio >= 4.5 : ratio >= 7;
 }
 
 // AA level
 return isLargeText ? ratio >= 3 : ratio >= 4.5;
}
```

### Keyboard Navigation

```typescript
// hooks/useKeyboardNavigation.ts
import { useEffect, useRef } from 'react';

export function useKeyboardNavigation<T extends HTMLElement>(
 options: {
 onEscape?: () => void;
 onEnter?: () => void;
 trapFocus?: boolean;
 } = {}
) {
 const elementRef = useRef<T>(null);

 useEffect(() => {
 const element = elementRef.current;
 if (!element) return;

 const handleKeyDown = (e: KeyboardEvent) => {
 if (e.key === 'Escape') {
 options.onEscape?.();
 } else if (e.key === 'Enter') {
 options.onEnter?.();
 } else if (e.key === 'Tab' && options.trapFocus) {
 // Focus trap implementation
 const focusableElements = element.querySelectorAll<HTMLElement>(
 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
 );
 const firstElement = focusableElements[0];
 const lastElement = focusableElements[focusableElements.length - 1];

 if (e.shiftKey && document.activeElement === firstElement) {
 lastElement.focus();
 e.preventDefault();
 } else if (!e.shiftKey && document.activeElement === lastElement) {
 firstElement.focus();
 e.preventDefault();
 }
 }
 };

 element.addEventListener('keydown', handleKeyDown);
 return () => element.removeEventListener('keydown', handleKeyDown);
 }, [options]);

 return elementRef;
}
```

### Motion Accessibility (Reduced Motion)

```css
/* styles/motion.css */
@media (prefers-reduced-motion: reduce) {
 *,
 *::before,
 *::after {
 animation-duration: 0.01ms !important;
 animation-iteration-count: 1 !important;
 transition-duration: 0.01ms !important;
 scroll-behavior: auto !important;
 }
}

/* Safe animations for reduced motion users */
.fade-enter {
 opacity: 0;
}

.fade-enter-active {
 opacity: 1;
 transition: opacity 200ms ease-in;
}

@media (prefers-reduced-motion: reduce) {
 .fade-enter-active {
 transition: none;
 opacity: 1;
 }
}
```

### Accessibility Testing Automation

Jest + jest-axe Configuration:

```typescript
// tests/setup.ts
import '@testing-library/jest-dom';
import { toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);
```

Component Accessibility Tests:

```typescript
// components/atoms/Button/Button.test.tsx
import { render } from '@testing-library/react';
import { axe } from 'jest-axe';
import { Button } from './Button';

describe('Button Accessibility', () => {
 it('should have no accessibility violations', async () => {
 const { container } = render(<Button>Click me</Button>);
 const results = await axe(container);
 expect(results).toHaveNoViolations();
 });

 it('should have correct ARIA attributes when disabled', () => {
 const { getByRole } = render(<Button disabled>Disabled</Button>);
 const button = getByRole('button');
 expect(button).toHaveAttribute('aria-disabled', 'true');
 });

 it('should indicate loading state to screen readers', () => {
 const { getByRole } = render(<Button isLoading>Loading</Button>);
 const button = getByRole('button');
 expect(button).toHaveAttribute('aria-busy', 'true');
 });
});
```

### Screen Reader Best Practices

ARIA Labels and Descriptions:

```typescript
// Example: Accessible modal
export function Modal({ title, children, onClose }) {
 const titleId = useId();
 const descriptionId = useId();

 return (
 <div
 role="dialog"
 aria-modal="true"
 aria-labelledby={titleId}
 aria-describedby={descriptionId}
 >
 <h2 id={titleId}>{title}</h2>
 <div id={descriptionId}>{children}</div>
 <button onClick={onClose} aria-label="Close dialog">
 ×
 </button>
 </div>
 );
}
```

Live Regions for Dynamic Content:

```typescript
// Announce status updates
export function StatusAnnouncer({ message }: { message: string }) {
 return (
 <div
 role="status"
 aria-live="polite"
 aria-atomic="true"
 className="sr-only"
 >
 {message}
 </div>
 );
}

// Alert for critical updates
export function Alert({ message }: { message: string }) {
 return (
 <div
 role="alert"
 aria-live="assertive"
 aria-atomic="true"
 >
 {message}
 </div>
 );
}
```

### Testing Checklist

Manual Testing:
- [ ] Keyboard navigation (Tab, Shift+Tab, Enter, Escape)
- [ ] Screen reader testing (NVDA, JAWS, VoiceOver)
- [ ] Color contrast verification (4.5:1 minimum)
- [ ] Focus indicators visible and clear
- [ ] Reduced motion preference respected

Automated Testing:
- [ ] jest-axe for component accessibility
- [ ] Storybook a11y addon for visual testing
- [ ] Chromatic for visual regression
- [ ] CI/CD integration for continuous testing

---

Last Updated: 2025-11-26
Related: [Main Skill](../SKILL.md), [Component Architecture](component-architecture.md)

```

### modules/icon-libraries.md

```markdown
---
name: moai-foundation-uiux
description: Vector icon libraries ecosystem guide covering 10+ major libraries with 200K+ icons, including React Icons (35K+), Lucide (1000+), Tabler Icons (5900+), Iconify (200K+), Heroicons, Phosphor, and Radix Icons with implementation patterns, decision trees, and best practices.
version: 1.0.0
modularized: false
tags:
 - enterprise
 - development
 - vector
updated: 2025-11-24
status: active
---

## Quick Reference (30 seconds)

# Icon Libraries

Vector Icon Libraries: Enterprise Guide (10+ Libraries, 200K+ Icons)

> Primary Agent: frontend-expert
> Secondary Agent: ui-ux-expert
> Version: 4.0.0 (Lucide v0.4+, React Icons 35K+, Tabler v2.0+, Phosphor v1.4+)
> Keywords: icons, vector icons, lucide, react icons, iconify, svg icons, accessibility

## Level 1: Quick Reference

### Library Selection Guide

Ecosystem Leaders (1000+ icons):
- Lucide (1000+): General UI, modern design, ~30KB
- React Icons (35K+): Multi-library support, modular bundles
- Tabler Icons (5900+): Dashboard optimized, ~22KB
- Ionicons (1300+): Mobile + web compatibility

Specialist Libraries (300-800 icons):
- Heroicons (300+): Official Tailwind CSS icons
- Phosphor (800+): 6 weights + duotone variations
- Material Design (900+): Google design system
- Bootstrap Icons (2000+): Bootstrap ecosystem

Compact & Specialized:
- Radix Icons (150+): Precise 15x15px, ~5KB
- Simple Icons (3300+): Brand logos only
- Iconify (200K+): Universal framework, CDN-based

### Quick Decision Matrix

| Scenario | Best Choice | Why |
|----------|-------------|-----|
| Want maximum icons | Iconify | 200K+ icons from 150+ sets |
| Dashboard application | Tabler Icons | 5900 optimized icons, 24px |
| Tailwind CSS project | Heroicons | Official integration |
| Flexible styling needed | Phosphor | 6 weights + duotone |
| Minimal bundle size | Radix Icons | 5KB, precise 15x15px |
| Brand logos | Simple Icons | 3300+ company logos |
| General purpose UI | Lucide | 1000+ modern, well-designed |

### Bundle Size Comparison

```
Radix Icons: ~5KB (150 icons)
Heroicons: ~10KB (300 icons)
Tabler Icons: ~22KB (5900 icons)
Ionicons: ~25KB (1300 icons)
Phosphor: ~25KB (800 icons with weights)
Lucide: ~30KB (1000 icons)
Simple Icons: ~50KB (3300+ brand icons)
React Icons: Modular (varies by library)
```

## Quick Installation Commands

```bash
# Core libraries
npm install lucide-react
npm install @heroicons/react
npm install @phosphor-icons/react
npm install @tabler/icons-react
npm install @radix-ui/react-icons

# Multi-library support
npm install react-icons
npm install @iconify/react

# Brand icons
npm install simple-icons
```

Version: 4.0.0 Enterprise
Last Updated: 2025-11-13
Status: Production Ready
Enterprise Grade: Full Enterprise Support

## Implementation Guide

## Level 2: Practical Implementation

### Core Library Patterns

#### Lucide React - General Purpose (1000+ icons)

```tsx
import { Heart, Search, Settings, ChevronRight } from 'lucide-react'

export function LucideExample() {
 return (
 <div className="space-y-4">
 {/* Basic usage (24px default) */}
 <div className="flex items-center gap-2">
 <Search />
 <span>Search</span>
 </div>

 {/* Custom styling */}
 <Heart size={32} color="#ff0000" fill="#ff0000" />

 {/* Tailwind integration */}
 <Settings className="w-6 h-6 text-gray-500 hover:text-gray-900" />

 {/* Icon button */}
 <button className="p-2 rounded-lg hover:bg-gray-100">
 <ChevronRight size={20} />
 </button>
 </div>
 )
}
```

#### React Icons - Multi-Library (35K+ icons)

```tsx
import { FaHome } from "react-icons/fa" // Font Awesome
import { MdHome } from "react-icons/md" // Material Design
import { BsHouse } from "react-icons/bs" // Bootstrap
import { FiHome } from "react-icons/fi" // Feather
import { SiReact } from "react-icons/si" // Brand logos

export function MultiLibraryExample() {
 return (
 <div className="flex gap-4">
 <FaHome size={32} className="text-blue-600" />
 <MdHome size={32} className="text-green-600" />
 <BsHouse size={32} className="text-purple-600" />
 <FiHome size={32} className="text-orange-600" />
 <SiReact size={32} className="text-cyan-500" />
 </div>
 )
}
```

#### Phosphor Icons - Weight Variations (800+ icons)

```tsx
import { Heart, Star } from "@phosphor-icons/react"

export function PhosphorExample() {
 const [rating, setRating] = React.useState(3)

 return (
 <div className="space-y-4">
 {/* Weight variations */}
 <div className="flex gap-2">
 <Heart weight="thin" />
 <Heart weight="light" />
 <Heart weight="regular" />
 <Heart weight="bold" />
 <Heart weight="fill" />
 </div>

 {/* Interactive rating */}
 <div className="flex gap-1">
 {[1, 2, 3, 4, 5].map((star) => (
 <button key={star}>
 <Star
 weight={star <= rating ? "fill" : "regular"}
 size={24}
 color={star <= rating ? "#fbbf24" : "#d1d5db"}
 />
 </button>
 ))}
 </div>
 </div>
 )
}
```

#### Iconify - Universal Framework (200K+ icons)

```tsx
import { Icon } from "@iconify/react"

export function IconifyExample() {
 return (
 <div className="space-y-4">
 {/* String-based (CDN loaded) */}
 <Icon icon="fa:home" width="32" height="32" />
 <Icon icon="mdi:account" width="32" height="32" />
 <Icon icon="bi:house" width="32" height="32" />

 {/* Custom styling */}
 <Icon
 icon="heroicons:heart"
 width="48"
 height="48"
 style={{ color: "#ef4444" }}
 />
 </div>
 )
}
```

### Type-Safe Icon Button

```tsx
import { FC, SVGProps } from 'react'

type IconType = FC<SVGProps<SVGSVGElement>>

interface IconButtonProps {
 icon: IconType
 label: string
 variant?: 'primary' | 'secondary' | 'ghost'
 size?: 'sm' | 'md' | 'lg'
 onClick?: () => void
}

const sizeMap = {
 sm: 'w-4 h-4',
 md: 'w-5 h-5',
 lg: 'w-6 h-6',
}

const variantMap = {
 primary: 'bg-blue-500 text-white hover:bg-blue-600',
 secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300',
 ghost: 'text-gray-600 hover:text-gray-900 hover:bg-gray-100',
}

export function IconButton({
 icon: Icon,
 label,
 variant = 'ghost',
 size = 'md',
 onClick,
}: IconButtonProps) {
 return (
 <button
 onClick={onClick}
 aria-label={label}
 title={label}
 className={`
 p-2 rounded-lg transition-all
 ${variantMap[variant]}
 `}
 >
 <Icon className={sizeMap[size]} />
 </button>
 )
}
```

## Performance & Best Practices

### Performance Optimization

```tsx
// Good: Tree-shake specific icons
import { Heart, Star } from 'lucide-react'

// Bad: Import entire library
import * as Icons from 'lucide-react'
const Icon = Icons[iconName]

// Good: Dynamic imports for large sets
const LazyIcon = React.lazy(() => import('lucide-react').then(module => ({
 default: module[iconName]
})))

// Good: Memoize components
const MemoHeart = React.memo(Heart)
```

### Bundle Optimization Strategies

1. Choose right library size: Use Radix Icons for minimal bundles
2. Import specific icons: Avoid `import *` patterns
3. Dynamic loading: Load icons on-demand for large sets
4. Icon subsets: Create custom bundles per feature
5. Tree-shaking: Use ES modules and bundler optimization

### Accessibility Essentials

- Use `aria-label` for icon-only buttons
- Ensure 4.5:1 color contrast ratio
- Support high contrast mode with `currentColor`
- Don't rely on color alone for meaning
- Use semantic HTML structure
- Test with screen readers

## Library Comparison Summary

| Library | Icons | Bundle Size | Best For |
|---------|-------|-------------|----------|
| Lucide | 1000+ | ~30KB | General purpose UI |
| Heroicons | 300+ | ~10KB | Tailwind CSS projects |
| Phosphor | 800+ | ~25KB | Weight flexibility needed |
| Tabler | 5900+ | ~22KB | Dashboard applications |
| Radix | 150+ | ~5KB | Minimal bundle size |
| React Icons | 35K+ | Modular | Multi-library support |
| Iconify | 200K+ | CDN | Maximum icon variety |

## Advanced Patterns

## Level 3: Advanced Integration

### Custom Icon Component

```tsx
import { forwardRef, SVGProps } from 'react'

interface CustomIconProps extends SVGProps<SVGSVGElement> {
 isActive?: boolean
 tooltip?: string
}

export const CustomIcon = forwardRef<SVGSVGElement, CustomIconProps>(
 ({ isActive, tooltip, className = '', ...props }, ref) => (
 <svg
 ref={ref}
 viewBox="0 0 24 24"
 width="24"
 height="24"
 className={`
 ${isActive ? 'text-blue-500' : 'text-gray-400'}
 ${tooltip ? 'cursor-help' : ''}
 ${className}
 transition-colors duration-200
 `}
 title={tooltip}
 {...props}
 >
 <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2z" />
 </svg>
 )
)
```

### Icon Theme System

```tsx
import { Heart, Settings } from 'lucide-react'

type IconTheme = 'light' | 'dark' | 'accent'

interface IconThemeConfig {
 color: string
 strokeWidth: number
 opacity: number
}

const themeConfig: Record<IconTheme, IconThemeConfig> = {
 light: { color: '#e5e7eb', strokeWidth: 2, opacity: 1 },
 dark: { color: '#1f2937', strokeWidth: 2, opacity: 1 },
 accent: { color: '#0ea5e9', strokeWidth: 2.5, opacity: 1 },
}

export function ThemedIcon({ theme, size = 24 }: { theme: IconTheme; size?: number }) {
 const config = themeConfig[theme]

 return (
 <div className="flex gap-4">
 <Heart size={size} color={config.color} strokeWidth={config.strokeWidth} />
 <Settings size={size} color={config.color} strokeWidth={config.strokeWidth} />
 </div>
 )
}
```

### Icon Animation

```tsx
import { Heart } from 'lucide-react'
import { useState } from 'react'

export function AnimatedIcon() {
 const [isActive, setIsActive] = useState(false)

 return (
 <button onClick={() => setIsActive(!isActive)} className="p-4">
 <Heart
 size={32}
 className={`
 text-red-500 transition-all duration-300
 ${isActive ? 'scale-125 animate-pulse' : 'scale-100'}
 `}
 fill={isActive ? '#ff0000' : 'none'}
 />
 </button>
 )
}
```

```

### modules/theming-system.md

```markdown
name: moai-library-shadcn-theming
description: shadcn/ui theme system and design token customization

## Theme System Implementation

### Advanced Theme Provider

```typescript
// Advanced theme system with CSS variables and dark mode
import { createContext, useContext, useEffect, useState } from "react";

type Theme = "dark" | "light" | "system";

interface ThemeProviderProps {
 children: React.ReactNode;
 defaultTheme?: Theme;
 storageKey?: string;
 attribute?: string;
 enableSystem?: boolean;
}

interface ThemeProviderState {
 theme: Theme;
 setTheme: (theme: Theme) => void;
}

const ThemeProviderContext = createContext<ThemeProviderState | undefined>(undefined);

export function ThemeProvider({
 children,
 defaultTheme = "system",
 storageKey = "ui-theme",
 attribute = "class",
 enableSystem = true,
 ...props
}: ThemeProviderProps) {
 const [theme, setTheme] = useState<Theme>(() => {
 if (typeof window !== "undefined") {
 return (localStorage.getItem(storageKey) as Theme) || defaultTheme;
 }
 return defaultTheme;
 });

 useEffect(() => {
 const root = window.document.documentElement;

 root.classList.remove("light", "dark");

 if (theme === "system" && enableSystem) {
 const systemTheme = window.matchMedia("(prefers-color-scheme: dark)")
 .matches
 ? "dark"
 : "light";

 root.classList.add(systemTheme);
 return;
 }

 root.classList.add(theme);
 }, [theme, enableSystem, attribute]);

 const value = {
 theme,
 setTheme: (theme: Theme) => {
 localStorage.setItem(storageKey, theme);
 setTheme(theme);
 },
 };

 return (
 <ThemeProviderContext.Provider {...props} value={value}>
 {children}
 </ThemeProviderContext.Provider>
 );
}

export const useTheme = () => {
 const context = useContext(ThemeProviderContext);

 if (context === undefined)
 throw new Error("useTheme must be used within a ThemeProvider");

 return context;
};
```

### Design Token Configuration

```typescript
// Theme configuration with design tokens
export const theme = {
 light: {
 background: "hsl(0 0% 100%)",
 foreground: "hsl(240 10% 3.9%)",
 card: "hsl(0 0% 100%)",
 cardForeground: "hsl(240 10% 3.9%)",
 popover: "hsl(0 0% 100%)",
 popoverForeground: "hsl(240 10% 3.9%)",
 primary: "hsl(240 9% 10%)",
 primaryForeground: "hsl(0 0% 98%)",
 secondary: "hsl(240 4.8% 95.9%)",
 secondaryForeground: "hsl(240 3.8% 46.1%)",
 muted: "hsl(240 4.8% 95.9%)",
 mutedForeground: "hsl(240 3.8% 46.1%)",
 accent: "hsl(240 4.8% 95.9%)",
 accentForeground: "hsl(240 5.9% 10%)",
 destructive: "hsl(0 72.22% 50.59%)",
 destructiveForeground: "hsl(0 0% 98%)",
 border: "hsl(240 5.9% 90%)",
 input: "hsl(240 5.9% 90%)",
 ring: "hsl(240 5.9% 10%)",
 },
 dark: {
 background: "hsl(240 10% 3.9%)",
 foreground: "hsl(0 0% 98%)",
 card: "hsl(240 10% 3.9%)",
 cardForeground: "hsl(0 0% 98%)",
 popover: "hsl(240 10% 3.9%)",
 popoverForeground: "hsl(0 0% 98%)",
 primary: "hsl(0 0% 98%)",
 primaryForeground: "hsl(240 9% 10%)",
 secondary: "hsl(240 3.7% 15.9%)",
 secondaryForeground: "hsl(0 0% 98%)",
 muted: "hsl(240 3.7% 15.9%)",
 mutedForeground: "hsl(240 5% 64.9%)",
 accent: "hsl(240 3.7% 15.9%)",
 accentForeground: "hsl(0 0% 98%)",
 destructive: "hsl(0 62.8% 30.6%)",
 destructiveForeground: "hsl(0 0% 98%)",
 border: "hsl(240 3.7% 15.9%)",
 input: "hsl(240 3.7% 15.9%)",
 ring: "hsl(240 4.9% 83.9%)",
 },
};

// Apply theme CSS variables
export function applyThemeCSS() {
 const root = document.documentElement;
 
 Object.entries(theme.light).forEach(([key, value]) => {
 root.style.setProperty(`--${key}`, value);
 });
}
```

### CSS Variables in globals.css

```css
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
 :root {
 --background: 0 0% 100%;
 --foreground: 240 10% 3.9%;
 --card: 0 0% 100%;
 --card-foreground: 240 10% 3.9%;
 --popover: 0 0% 100%;
 --popover-foreground: 240 10% 3.9%;
 --primary: 240 9% 10%;
 --primary-foreground: 0 0% 98%;
 --secondary: 240 4.8% 95.9%;
 --secondary-foreground: 240 3.8% 46.1%;
 --muted: 240 4.8% 95.9%;
 --muted-foreground: 240 3.8% 46.1%;
 --accent: 240 4.8% 95.9%;
 --accent-foreground: 240 5.9% 10%;
 --destructive: 0 72.22% 50.59%;
 --destructive-foreground: 0 0% 98%;
 --border: 240 5.9% 90%;
 --input: 240 5.9% 90%;
 --ring: 240 5.9% 10%;
 --radius: 0.5rem;
 }

 .dark {
 --background: 240 10% 3.9%;
 --foreground: 0 0% 98%;
 --card: 240 10% 3.9%;
 --card-foreground: 0 0% 98%;
 --popover: 240 10% 3.9%;
 --popover-foreground: 0 0% 98%;
 --primary: 0 0% 98%;
 --primary-foreground: 240 9% 10%;
 --secondary: 240 3.7% 15.9%;
 --secondary-foreground: 0 0% 98%;
 --muted: 240 3.7% 15.9%;
 --muted-foreground: 240 5% 64.9%;
 --accent: 240 3.7% 15.9%;
 --accent-foreground: 0 0% 98%;
 --destructive: 0 62.8% 30.6%;
 --destructive-foreground: 0 0% 98%;
 --border: 240 3.7% 15.9%;
 --input: 240 3.7% 15.9%;
 --ring: 240 4.9% 83.9%;
 }
}

@layer base {
 * {
 @apply border-border;
 }
 body {
 @apply bg-background text-foreground;
 }
}
```

### Custom Brand Theme

```typescript
// Create custom brand theme
export function createBrandTheme(brandColors: {
 primary: string;
 secondary: string;
 accent: string;
}) {
 return {
 light: {
 ...theme.light,
 primary: brandColors.primary,
 secondary: brandColors.secondary,
 accent: brandColors.accent,
 },
 dark: {
 ...theme.dark,
 primary: brandColors.primary,
 secondary: brandColors.secondary,
 accent: brandColors.accent,
 },
 };
}

// Apply custom brand theme
export function applyBrandTheme(brandTheme: typeof theme) {
 const root = document.documentElement;
 const currentTheme = root.classList.contains("dark") ? "dark" : "light";
 
 Object.entries(brandTheme[currentTheme]).forEach(([key, value]) => {
 root.style.setProperty(`--${key}`, value);
 });
}
```

### Theme Toggle Component

```typescript
// Theme toggle component
import { Moon, Sun } from "lucide-react";
import { Button } from "@/components/ui/button";
import {
 DropdownMenu,
 DropdownMenuContent,
 DropdownMenuItem,
 DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";
import { useTheme } from "@/components/theme-provider";

export function ThemeToggle() {
 const { setTheme } = useTheme();

 return (
 <DropdownMenu>
 <DropdownMenuTrigger asChild>
 <Button variant="outline" size="icon">
 <Sun className="h-[1.2rem] w-[1.2rem] rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
 <Moon className="absolute h-[1.2rem] w-[1.2rem] rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
 <span className="sr-only">Toggle theme</span>
 </Button>
 </DropdownMenuTrigger>
 <DropdownMenuContent align="end">
 <DropdownMenuItem onClick={() => setTheme("light")}>
 Light
 </DropdownMenuItem>
 <DropdownMenuItem onClick={() => setTheme("dark")}>
 Dark
 </DropdownMenuItem>
 <DropdownMenuItem onClick={() => setTheme("system")}>
 System
 </DropdownMenuItem>
 </DropdownMenuContent>
 </DropdownMenu>
 );
}
```

### Tailwind Configuration

```javascript
// tailwind.config.js
/ @type {import('tailwindcss').Config} */
module.exports = {
 darkMode: ["class"],
 content: [
 './pages//*.{ts,tsx}',
 './components//*.{ts,tsx}',
 './app//*.{ts,tsx}',
 './src//*.{ts,tsx}',
 ],
 theme: {
 container: {
 center: true,
 padding: "2rem",
 screens: {
 "2xl": "1400px",
 },
 },
 extend: {
 colors: {
 border: "hsl(var(--border))",
 input: "hsl(var(--input))",
 ring: "hsl(var(--ring))",
 background: "hsl(var(--background))",
 foreground: "hsl(var(--foreground))",
 primary: {
 DEFAULT: "hsl(var(--primary))",
 foreground: "hsl(var(--primary-foreground))",
 },
 secondary: {
 DEFAULT: "hsl(var(--secondary))",
 foreground: "hsl(var(--secondary-foreground))",
 },
 destructive: {
 DEFAULT: "hsl(var(--destructive))",
 foreground: "hsl(var(--destructive-foreground))",
 },
 muted: {
 DEFAULT: "hsl(var(--muted))",
 foreground: "hsl(var(--muted-foreground))",
 },
 accent: {
 DEFAULT: "hsl(var(--accent))",
 foreground: "hsl(var(--accent-foreground))",
 },
 popover: {
 DEFAULT: "hsl(var(--popover))",
 foreground: "hsl(var(--popover-foreground))",
 },
 card: {
 DEFAULT: "hsl(var(--card))",
 foreground: "hsl(var(--card-foreground))",
 },
 },
 borderRadius: {
 lg: "var(--radius)",
 md: "calc(var(--radius) - 2px)",
 sm: "calc(var(--radius) - 4px)",
 },
 keyframes: {
 "accordion-down": {
 from: { height: 0 },
 to: { height: "var(--radix-accordion-content-height)" },
 },
 "accordion-up": {
 from: { height: "var(--radix-accordion-content-height)" },
 to: { height: 0 },
 },
 },
 animation: {
 "accordion-down": "accordion-down 0.2s ease-out",
 "accordion-up": "accordion-up 0.2s ease-out",
 },
 },
 },
 plugins: [require("tailwindcss-animate")],
}
```

---

Last Updated: 2025-11-26
Related: [Main Skill](../SKILL.md), [Component Architecture](component-architecture.md)

```

### examples.md

```markdown
# UI/UX Implementation Examples

Practical code examples demonstrating core UI/UX patterns across React 19, Vue 3.5, design tokens, and accessibility.

---

## 1. Button Component (React 19)

### Basic Implementation

```typescript
import { forwardRef } from 'react'
import { cva, type VariantProps } from 'class-variance-authority'

const buttonVariants = cva(
 // Base styles
 'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
 {
 variants: {
 variant: {
 default: 'bg-primary text-primary-foreground hover:bg-primary/90',
 destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
 outline: 'border border-input bg-background hover:bg-accent',
 ghost: 'hover:bg-accent hover:text-accent-foreground',
 link: 'text-primary underline-offset-4 hover:underline',
 },
 size: {
 default: 'h-10 px-4 py-2',
 sm: 'h-9 rounded-md px-3',
 lg: 'h-11 rounded-md px-8',
 icon: 'h-10 w-10',
 },
 },
 defaultVariants: {
 variant: 'default',
 size: 'default',
 },
 }
)

export interface ButtonProps
 extends React.ButtonHTMLAttributes<HTMLButtonElement>,
 VariantProps<typeof buttonVariants> {
 asChild?: boolean
}

const Button = forwardRef<HTMLButtonElement, ButtonProps>(
 ({ className, variant, size, ...props }, ref) => {
 return (
 <button
 className={buttonVariants({ variant, size, className })}
 ref={ref}
 {...props}
 />
 )
 }
)
Button.displayName = 'Button'

export { Button, buttonVariants }
```

### Usage Examples

```tsx
import { Button } from '@/components/ui/button'

<Button>Default Button</Button>
<Button variant="destructive">Delete</Button>
<Button variant="outline" size="sm">Small Outline</Button>
<Button variant="ghost" size="icon">
 <SearchIcon className="h-4 w-4" />
</Button>
```

---

## 2. Form with Validation (React Hook Form + Zod)

```typescript
import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import * as z from 'zod'
import { Button } from '@/components/ui/button'
import {
 Form,
 FormControl,
 FormDescription,
 FormField,
 FormItem,
 FormLabel,
 FormMessage,
} from '@/components/ui/form'
import { Input } from '@/components/ui/input'

// Schema definition
const formSchema = z.object({
 username: z.string().min(2, {
 message: 'Username must be at least 2 characters.',
 }),
 email: z.string().email({
 message: 'Please enter a valid email address.',
 }),
 password: z.string().min(8, {
 message: 'Password must be at least 8 characters.',
 }),
})

type FormValues = z.infer<typeof formSchema>

export function SignupForm() {
 const form = useForm<FormValues>({
 resolver: zodResolver(formSchema),
 defaultValues: {
 username: '',
 email: '',
 password: '',
 },
 })

 function onSubmit(values: FormValues) {
 console.log(values)
 }

 return (
 <Form {...form}>
 <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-8">
 <FormField
 control={form.control}
 name="username"
 render={({ field }) => (
 <FormItem>
 <FormLabel>Username</FormLabel>
 <FormControl>
 <Input placeholder="johndoe" {...field} />
 </FormControl>
 <FormDescription>
 This is your public display name.
 </FormDescription>
 <FormMessage />
 </FormItem>
 )}
 />

 <FormField
 control={form.control}
 name="email"
 render={({ field }) => (
 <FormItem>
 <FormLabel>Email</FormLabel>
 <FormControl>
 <Input type="email" placeholder="[email protected]" {...field} />
 </FormControl>
 <FormMessage />
 </FormItem>
 )}
 />

 <FormField
 control={form.control}
 name="password"
 render={({ field }) => (
 <FormItem>
 <FormLabel>Password</FormLabel>
 <FormControl>
 <Input type="password" placeholder="••••••••" {...field} />
 </FormControl>
 <FormMessage />
 </FormItem>
 )}
 />

 <Button type="submit">Submit</Button>
 </form>
 </Form>
 )
}
```

---

## 3. Data Table (TanStack Table)

```typescript
import { useState } from 'react'
import {
 useReactTable,
 getCoreRowModel,
 getSortedRowModel,
 getFilteredRowModel,
 getPaginationRowModel,
 flexRender,
 type ColumnDef,
 type SortingState,
 type ColumnFiltersState,
} from '@tanstack/react-table'

// Define data type
type Payment = {
 id: string
 amount: number
 status: 'pending' | 'processing' | 'success' | 'failed'
 email: string
}

// Define columns
export const columns: ColumnDef<Payment>[] = [
 {
 accessorKey: 'status',
 header: 'Status',
 },
 {
 accessorKey: 'email',
 header: 'Email',
 },
 {
 accessorKey: 'amount',
 header: () => <div className="text-right">Amount</div>,
 cell: ({ row }) => {
 const amount = parseFloat(row.getValue('amount'))
 const formatted = new Intl.NumberFormat('en-US', {
 style: 'currency',
 currency: 'USD',
 }).format(amount)
 return <div className="text-right font-medium">{formatted}</div>
 },
 },
]

export function DataTableDemo() {
 const [data] = useState<Payment[]>([
 {
 id: '728ed52f',
 amount: 100,
 status: 'pending',
 email: '[email protected]',
 },
 // ... more data
 ])

 const [sorting, setSorting] = useState<SortingState>([])
 const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])

 const table = useReactTable({
 data,
 columns,
 getCoreRowModel: getCoreRowModel(),
 getSortedRowModel: getSortedRowModel(),
 getFilteredRowModel: getFilteredRowModel(),
 getPaginationRowModel: getPaginationRowModel(),
 onSortingChange: setSorting,
 onColumnFiltersChange: setColumnFilters,
 state: {
 sorting,
 columnFilters,
 },
 })

 return (
 <div className="rounded-md border">
 <table className="min-w-full divide-y divide-gray-200">
 <thead>
 {table.getHeaderGroups().map((headerGroup) => (
 <tr key={headerGroup.id}>
 {headerGroup.headers.map((header) => (
 <th key={header.id} className="px-6 py-3 text-left">
 {header.isPlaceholder
 ? null
 : flexRender(
 header.column.columnDef.header,
 header.getContext()
 )}
 </th>
 ))}
 </tr>
 ))}
 </thead>
 <tbody>
 {table.getRowModel().rows.map((row) => (
 <tr key={row.id}>
 {row.getVisibleCells().map((cell) => (
 <td key={cell.id} className="px-6 py-4">
 {flexRender(cell.column.columnDef.cell, cell.getContext())}
 </td>
 ))}
 </tr>
 ))}
 </tbody>
 </table>
 </div>
 )
}
```

---

## 4. Theme Provider (Light/Dark Mode)

```typescript
import { createContext, useContext, useEffect, useState } from 'react'

type Theme = 'dark' | 'light' | 'system'

type ThemeProviderProps = {
 children: React.ReactNode
 defaultTheme?: Theme
 storageKey?: string
}

type ThemeProviderState = {
 theme: Theme
 setTheme: (theme: Theme) => void
}

const ThemeProviderContext = createContext<ThemeProviderState | undefined>(
 undefined
)

export function ThemeProvider({
 children,
 defaultTheme = 'system',
 storageKey = 'ui-theme',
 ...props
}: ThemeProviderProps) {
 const [theme, setTheme] = useState<Theme>(
 () => (localStorage.getItem(storageKey) as Theme) || defaultTheme
 )

 useEffect(() => {
 const root = window.document.documentElement
 root.classList.remove('light', 'dark')

 if (theme === 'system') {
 const systemTheme = window.matchMedia('(prefers-color-scheme: dark)')
 .matches
 ? 'dark'
 : 'light'
 root.classList.add(systemTheme)
 return
 }

 root.classList.add(theme)
 }, [theme])

 const value = {
 theme,
 setTheme: (theme: Theme) => {
 localStorage.setItem(storageKey, theme)
 setTheme(theme)
 },
 }

 return (
 <ThemeProviderContext.Provider {...props} value={value}>
 {children}
 </ThemeProviderContext.Provider>
 )
}

export const useTheme = () => {
 const context = useContext(ThemeProviderContext)
 if (context === undefined)
 throw new Error('useTheme must be used within a ThemeProvider')
 return context
}

// Usage
function ThemeToggle() {
 const { setTheme } = useTheme()

 return (
 <div>
 <button onClick={() => setTheme('light')}>Light</button>
 <button onClick={() => setTheme('dark')}>Dark</button>
 <button onClick={() => setTheme('system')}>System</button>
 </div>
 )
}
```

---

## 5. Icon Usage Patterns

```typescript
import { Heart, Search, Settings } from 'lucide-react'
import { FC, SVGProps } from 'react'

// Type-safe icon button
type IconType = FC<SVGProps<SVGSVGElement>>

interface IconButtonProps {
 icon: IconType
 label: string
 onClick?: () => void
}

function IconButton({ icon: Icon, label, onClick }: IconButtonProps) {
 return (
 <button
 onClick={onClick}
 aria-label={label}
 className="p-2 rounded-lg hover:bg-gray-100"
 >
 <Icon className="w-5 h-5" />
 </button>
 )
}

// Usage examples
export function IconExamples() {
 return (
 <div className="flex gap-2">
 {/* Basic icons */}
 <Heart size={24} color="#ef4444" />
 <Search className="w-6 h-6 text-gray-500" />
 <Settings size={20} />

 {/* Icon buttons */}
 <IconButton icon={Heart} label="Like" onClick={() => console.log('Liked')} />
 <IconButton icon={Search} label="Search" />
 <IconButton icon={Settings} label="Settings" />
 </div>
 )
}
```

---

## 6. Accessible Modal Dialog

```typescript
import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui/dialog'
import { Button } from '@/components/ui/button'

export function AccessibleDialog() {
 return (
 <Dialog>
 <DialogTrigger asChild>
 <Button>Open Dialog</Button>
 </DialogTrigger>
 <DialogContent>
 <DialogHeader>
 <DialogTitle>Delete Account</DialogTitle>
 </DialogHeader>
 <p className="text-sm text-muted-foreground">
 Are you sure you want to delete your account? This action cannot be undone.
 </p>
 <div className="flex justify-end gap-2">
 <Button variant="outline">Cancel</Button>
 <Button variant="destructive">Delete</Button>
 </div>
 </DialogContent>
 </Dialog>
 )
}
```

---

## 7. Vue 3.5 Composition API Example

```vue
<script setup lang="ts">
import { ref, computed } from 'vue'
import { useForm } from 'vee-validate'
import { toTypedSchema } from '@vee-validate/zod'
import * as z from 'zod'

const schema = toTypedSchema(
 z.object({
 email: z.string().email('Invalid email address'),
 password: z.string().min(8, 'Password must be at least 8 characters'),
 })
)

const { defineComponentBinds, handleSubmit, errors } = useForm({
 validationSchema: schema,
})

const email = defineComponentBinds('email')
const password = defineComponentBinds('password')

const onSubmit = handleSubmit((values) => {
 console.log('Form submitted:', values)
})
</script>

<template>
 <form @submit="onSubmit" class="space-y-4">
 <div>
 <label for="email">Email</label>
 <input
 id="email"
 v-bind="email"
 type="email"
 class="border rounded px-3 py-2 w-full"
 />
 <span v-if="errors.email" class="text-red-500 text-sm">
 {{ errors.email }}
 </span>
 </div>

 <div>
 <label for="password">Password</label>
 <input
 id="password"
 v-bind="password"
 type="password"
 class="border rounded px-3 py-2 w-full"
 />
 <span v-if="errors.password" class="text-red-500 text-sm">
 {{ errors.password }}
 </span>
 </div>

 <button type="submit" class="bg-blue-500 text-white px-4 py-2 rounded">
 Submit
 </button>
 </form>
</template>
```

---

## 8. Design Token Implementation

```typescript
// tokens/colors.ts
export const colors = {
 primary: {
 50: '#eff6ff',
 100: '#dbeafe',
 500: '#3b82f6',
 900: '#1e3a8a',
 },
 semantic: {
 text: {
 primary: 'var(--color-text-primary)',
 secondary: 'var(--color-text-secondary)',
 },
 background: {
 default: 'var(--color-bg-default)',
 elevated: 'var(--color-bg-elevated)',
 },
 },
} as const

// Usage in components
import { colors } from '@/tokens/colors'

<div style={{ color: colors.semantic.text.primary }}>
 Text with semantic token
</div>
```

---

Last Updated: 2025-11-26
Status: Production Ready

```

### reference.md

```markdown
# External Documentation References

Comprehensive collection of official documentation, specifications, and resources for UI/UX development.

---

## Design Systems & Tokens

### W3C Design Tokens Community Group (DTCG)
- Specification: https://designtokens.org
- GitHub: https://github.com/design-tokens/community-group
- Format Spec: https://tr.designtokens.org/format/
- Latest Version: 2025.10 (first stable release)
- Use Case: Design token architecture, multi-platform theming

### Style Dictionary
- Documentation: https://styledictionary.com
- GitHub: https://github.com/amzn/style-dictionary
- Version: 4.0+ (DTCG-compatible)
- Use Case: Token transformation, platform-specific output

---

## Accessibility Standards

### WCAG 2.2 (Web Content Accessibility Guidelines)
- Quick Reference: https://www.w3.org/WAI/WCAG22/quickref/
- Full Specification: https://www.w3.org/TR/WCAG22/
- Understanding WCAG: https://www.w3.org/WAI/WCAG22/Understanding/
- Level AA Requirements: https://www.w3.org/WAI/WCAG22/quickref/?currentsidebar=%23col_overview&levels=aaa
- Use Case: Accessibility compliance, ARIA patterns, contrast ratios

### axe DevTools
- Website: https://www.deque.com/axe/devtools/
- Documentation: https://www.deque.com/axe/devtools/documentation/
- Chrome Extension: https://chrome.google.com/webstore/detail/axe-devtools/lhdoppojpmngadmnindnejefpokejbdd
- Use Case: Automated accessibility testing

### jest-axe
- GitHub: https://github.com/nickcolley/jest-axe
- npm: https://www.npmjs.com/package/jest-axe
- Use Case: Accessibility testing in unit tests

---

## Component Libraries & Frameworks

### React 19
- Official Docs: https://react.dev
- API Reference: https://react.dev/reference/react
- Server Components: https://react.dev/reference/react/use-server
- Latest Features: https://react.dev/blog
- Use Case: Modern React patterns, Server Components, Suspense

### Vue 3.5
- Official Docs: https://vuejs.org
- Composition API: https://vuejs.org/guide/extras/composition-api-faq.html
- TypeScript: https://vuejs.org/guide/typescript/overview.html
- Use Case: Vue component development, Composition API

### shadcn/ui
- Documentation: https://ui.shadcn.com/docs
- Components: https://ui.shadcn.com/docs/components
- Installation: https://ui.shadcn.com/docs/installation
- GitHub: https://github.com/shadcn-ui/ui
- Use Case: Copy-paste component library, Radix UI + Tailwind

### Radix UI
- Documentation: https://www.radix-ui.com
- Primitives: https://www.radix-ui.com/primitives/docs/overview/introduction
- Themes: https://www.radix-ui.com/themes/docs/overview/getting-started
- Use Case: Unstyled accessible component primitives

---

## Styling & Theming

### Tailwind CSS 3.4
- Documentation: https://tailwindcss.com/docs
- Configuration: https://tailwindcss.com/docs/configuration
- Dark Mode: https://tailwindcss.com/docs/dark-mode
- Customization: https://tailwindcss.com/docs/theme
- Use Case: Utility-first CSS, design token integration

### CSS Variables
- MDN Reference: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
- Browser Support: https://caniuse.com/css-variables
- Use Case: Dynamic theming, design token implementation

---

## Icon Libraries

### Lucide Icons
- Website: https://lucide.dev
- React: https://lucide.dev/guide/packages/lucide-react
- Icons: https://lucide.dev/icons/
- GitHub: https://github.com/lucide-icons/lucide
- Bundle Size: ~30KB (1000+ icons)

### React Icons
- Website: https://react-icons.github.io/react-icons/
- GitHub: https://github.com/react-icons/react-icons
- Icons: 35,000+ icons from multiple libraries
- Use Case: Multi-library support, modular imports

### Tabler Icons
- Website: https://tabler-icons.io
- React: https://tabler-icons.io/docs/icons/react
- GitHub: https://github.com/tabler/tabler-icons
- Icons: 5900+ icons (dashboard optimized)

### Iconify
- Website: https://iconify.design
- React: https://docs.iconify.design/icon-components/react/
- Icon Sets: https://icon-sets.iconify.design
- Icons: 200,000+ icons (CDN-based)

### Heroicons
- Website: https://heroicons.com
- GitHub: https://github.com/tailwindlabs/heroicons
- React: https://github.com/tailwindlabs/heroicons#react
- Icons: 300+ icons (official Tailwind CSS icons)

### Phosphor Icons
- Website: https://phosphoricons.com
- React: https://github.com/phosphor-icons/react
- Icons: 800+ icons with 6 weight variations
- Use Case: Weight flexibility (thin, light, regular, bold, fill, duotone)

### Radix Icons
- Website: https://www.radix-ui.com/icons
- GitHub: https://github.com/radix-ui/icons
- Icons: 150+ icons (precise 15x15px)
- Bundle Size: ~5KB (minimal footprint)

---

## Design-to-Code Tools

### Figma MCP
- Documentation: https://help.figma.com/hc/en-us/articles/32132100833559
- Server Setup: Desktop + Remote server modes
- Use Case: Design token extraction, component code generation

### Storybook 8.x
- Documentation: https://storybook.js.org/docs
- React: https://storybook.js.org/docs/react/get-started/introduction
- Addons: https://storybook.js.org/docs/react/essentials/introduction
- Use Case: Component documentation, visual testing

### Chromatic
- Website: https://www.chromatic.com
- Documentation: https://www.chromatic.com/docs/
- GitHub Action: https://github.com/chromaui/action
- Use Case: Visual regression testing, Storybook integration

---

## Form Validation & State Management

### React Hook Form
- Documentation: https://react-hook-form.com
- API: https://react-hook-form.com/api
- Examples: https://react-hook-form.com/get-started
- Use Case: Form state management, validation

### Zod
- Documentation: https://zod.dev
- GitHub: https://github.com/colinhacks/zod
- TypeScript Integration: https://zod.dev/?id=typescript
- Use Case: Schema validation, type inference

### TanStack Table
- Documentation: https://tanstack.com/table/latest
- React: https://tanstack.com/table/latest/docs/framework/react/react-table
- Examples: https://tanstack.com/table/latest/docs/framework/react/examples
- Use Case: Data tables, sorting, filtering, pagination

---

## TypeScript & Tooling

### TypeScript 5.5
- Documentation: https://www.typescriptlang.org/docs/
- Handbook: https://www.typescriptlang.org/docs/handbook/intro.html
- Release Notes: https://www.typescriptlang.org/docs/handbook/release-notes/overview.html
- Use Case: Type safety, improved developer experience

### class-variance-authority (CVA)
- GitHub: https://github.com/joe-bell/cva
- Documentation: https://cva.style/docs
- Use Case: Variant management for components

---

## Testing

### React Testing Library
- Documentation: https://testing-library.com/docs/react-testing-library/intro/
- API: https://testing-library.com/docs/react-testing-library/api
- Examples: https://testing-library.com/docs/react-testing-library/example-intro
- Use Case: Component testing, user-centric tests

### Vitest
- Documentation: https://vitest.dev
- API: https://vitest.dev/api/
- Configuration: https://vitest.dev/config/
- Use Case: Fast unit testing, Vite integration

---

## Animation Libraries

### Framer Motion
- Documentation: https://www.framer.com/motion/
- API: https://www.framer.com/motion/component/
- Examples: https://www.framer.com/motion/examples/
- Use Case: React animations, gestures

---

## Official Specifications

- HTML Living Standard: https://html.spec.whatwg.org/multipage/
- CSS Specifications: https://www.w3.org/Style/CSS/specs.en.html
- WAI-ARIA: https://www.w3.org/TR/wai-aria-1.2/
- ARIA Authoring Practices: https://www.w3.org/WAI/ARIA/apg/

---

## Community Resources

- MDN Web Docs: https://developer.mozilla.org
- Can I Use: https://caniuse.com
- WebAIM: https://webaim.org
- A11y Project: https://www.a11yproject.com
- Inclusive Components: https://inclusive-components.design

---

Last Updated: 2025-11-26
Status: Production Ready

```