name	moai-foundation-uiux
description	Core UI/UX Foundation - Enterprise design systems, component architecture, accessibility, icons, and theming integration
version	2.0.0
modularized	true
last_updated	Sun Nov 30 2025 00:00:00 GMT+0000 (Coordinated Universal Time)
compliance_score	80
auto_trigger_keywords	foundation, testing, uiux
color	red

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 (Atomic Design, component patterns, props APIs)
Design Systems: Design System Tokens (DTCG tokens, Style Dictionary, Figma MCP)
Accessibility: Accessibility WCAG (WCAG 2.2 compliance, testing, navigation)
Icons: Icon Libraries (10+ libraries, selection guide, performance optimization)
Theming: Theming System (theme system, CSS variables, brand customization)
Examples: Examples (practical implementation examples)
Reference: Reference (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	DTCG 2025.10, Style Dictionary 4.0
Component patterns	Component Architecture	Atomic Design, React 19, shadcn/ui
Accessibility	Accessibility WCAG	WCAG 2.2, jest-axe, keyboard nav
Icons	Icon Libraries	Lucide, React Icons, Tabler, Iconify
Theming	Theming System	CSS variables, Theme Provider
Examples	Examples	React/Vue implementations

Quick Start Workflows

1. Design System Setup (30 minutes)

Step 1: Initialize design tokens

{
  "$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

npm install --save-dev style-dictionary
npx style-dictionary build

Step 3: Integrate with components

import { colors, spacing } from '@/tokens'

See: Design System Tokens for complete token architecture

2. Component Library Setup (45 minutes)

Step 1: Initialize shadcn/ui

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

<Button aria-label="Submit form" variant="primary">
  Submit
</Button>

See: Component Architecture for patterns and examples

3. Icon System Integration (15 minutes)

Step 1: Choose icon library

# 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

import { Heart, Search } from 'lucide-react'

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

See: Icon Libraries for library comparison and optimization

4. Theme System Setup (30 minutes)

Step 1: Configure CSS variables

: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

<ThemeProvider attribute="class" defaultTheme="system">
  <App />
</ThemeProvider>

See: Theming System 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

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

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

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

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

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

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

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

DON'T:

❌ Hardcode colors (use design tokens)
❌ Skip ARIA labels on icon-only buttons
❌ Import entire icon libraries (import * from 'lucide-react')
❌ Forget to test dark mode
❌ Ignore keyboard navigation
❌ Skip focus indicators
❌ Use inline styles (use Tailwind classes)
❌ Forget loading states

Works Well With

Skills:

moai-lang-unified - 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

Atomic Design patterns
React 19 / Vue 3.5 examples
Component architecture

moai-design-systems → Design System Tokens + Accessibility WCAG

DTCG token architecture
Figma MCP workflows
WCAG 2.2 compliance

moai-icons-vector → Icon Libraries

Icon library comparison
Performance optimization
Integration patterns

moai-library-shadcn (partially) → Component Architecture + Theming System

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

moai-foundation-uiux

Install Skill

SKILL.md

Quick Reference (30 seconds)

Core UI/UX Foundation

Implementation Guide

Foundation Stack (November 2025)

Quick Start Workflows

1. Design System Setup (30 minutes)

2. Component Library Setup (45 minutes)

3. Icon System Integration (15 minutes)

4. Theme System Setup (30 minutes)

Key Principles

Tool Ecosystem

Module Cross-Reference

Component Architecture

Design System Tokens

Accessibility WCAG

Icon Libraries

Theming System

Examples

Reference

Best Practices

Works Well With

Migration from Legacy Skills

Official Resources