moai-foundation-uiux

Core UI/UX Foundation - Enterprise design systems, component architecture, accessibility, icons, and theming integration

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill provides a comprehensive enterprise-grade UI/UX foundation, integrating modern design systems (W3C DTCG 2025.10), scalable component architecture (React 19, Vue 3.5), and strict WCAG 2.2 accessibility compliance. It streamlines the creation of design tokens, themed interfaces, and optimized icon systems to ensure consistency, accessibility, and high performance across large-scale software projects.

Use Cases

  • Architecting a scalable enterprise design system using W3C DTCG tokens and Style Dictionary for multi-platform consistency.
  • Implementing accessible UI components that meet WCAG 2.2 AA/AAA standards with integrated keyboard navigation and screen reader support.
  • Developing modern frontend libraries using Atomic Design principles and React 19 Server Components for optimized rendering.
  • Integrating extensive icon ecosystems (200K+ icons) with tree-shaking and type-safety to maintain minimal bundle sizes.
  • Configuring advanced theming systems with CSS variables to support light/dark modes and dynamic brand-specific customization.
namemoai-foundation-uiux
aliases[moai-foundation-uiux]
categoryfoundation
descriptionCore UI/UX Foundation - Enterprise design systems, component architecture, accessibility, icons, and theming integration
version2.0.0
modularizedtrue
updated2025-11-27
statusactive
deprecated_inv0.32.0
remove_inv0.35.0
message"Use moai-foundation-uiux instead"

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:


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


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