moai-adk 0.35.1__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-domain-uiux/SKILL.md

@@ -0,0 +1,455 @@
+---
+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