moai-adk 0.15.0__py3-none-any.whl → 0.25.4__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-design-systems/SKILL.md

@@ -1,802 +0,0 @@
----
-skill_name: moai-design-systems
-description: Design system patterns, W3C DTCG 2025.10 token architecture, WCAG 2.2 accessibility standards, and Figma MCP workflows for consistent, accessible UI development
-allowed_tools: [Read, Write, WebFetch, WebSearch]
-freedom_level: medium
-version: 1.0.0
-last_updated: 2025-11-04
-tags: [design-systems, design-tokens, accessibility, wcag, figma-mcp, dtcg]
----
-
-# Design Systems Development Skill
-
-**Purpose**: Guide implementation of production-ready design systems using W3C DTCG 2025.10 token standards, WCAG 2.2 accessibility compliance, and Figma MCP automation workflows.
-
-**When to use this Skill**:
-- Setting up design token architecture for multi-platform projects
-- Implementing accessible component libraries (WCAG 2.2 AA/AAA)
-- Automating design-to-code workflows with Figma MCP
-- Building maintainable design systems with Storybook
-- Ensuring color contrast compliance and semantic token naming
-
-**Latest Standards** (as of November 2025):
-- **DTCG Specification**: 2025.10 (first stable version)
-- **WCAG Guidelines**: 2.2 (AA: 4.5:1 text, AAA: 7:1 text)
-- **Figma MCP**: Desktop + Remote server support
-- **Style Dictionary**: 4.0 (DTCG-compatible)
-- **Storybook**: 8.x (with Docs addon)
-
----
-
-## Progressive Disclosure Structure
-
-### Level 1: Quick Start Overview (Read This First)
-
-**Design System Foundation** - Three Pillars:
-
-1. **Design Tokens** (Single Source of Truth)
-   - Color, typography, spacing, borders, shadows
-   - Semantic naming: `color.primary.500`, `spacing.md`, `font.heading.lg`
-   - Multi-theme support (light/dark modes)
-   - Format: W3C DTCG 2025.10 JSON or Style Dictionary 4.0
-
-2. **Component Library** (Atomic Design Pattern)
-   - Atoms → Molecules → Organisms → Templates → Pages
-   - Props API for reusability and composition
-   - Variant states: default, hover, active, disabled, error, loading
-   - Documentation: Storybook with auto-generated props/usage
-
-3. **Accessibility Standards** (WCAG 2.2 Compliance)
-   - Color contrast: 4.5:1 (AA), 7:1 (AAA) for text
-   - Keyboard navigation: Tab order, focus management
-   - Screen readers: ARIA roles, labels, live regions
-   - Motion: `prefers-reduced-motion` support
-
-**Tool Ecosystem Quick Reference**:
-
-| Tool | Version | Purpose | Official Link |
-|------|---------|---------|---------------|
-| **W3C DTCG** | 2025.10 | Design token specification | https://designtokens.org |
-| **Style Dictionary** | 4.0+ | Token transformation engine | https://styledictionary.com |
-| **Figma MCP** | Latest | Design-to-code automation | https://help.figma.com/hc/en-us/articles/32132100833559 |
-| **Storybook** | 8.x | Component documentation | https://storybook.js.org |
-| **axe DevTools** | Latest | Accessibility testing | https://www.deque.com/axe/devtools/ |
-| **Chromatic** | Latest | Visual regression testing | https://chromatic.com |
-
-**Decision Points Checklist**:
-
-- [ ] Choose token format: DTCG 2025.10 or Style Dictionary 4.0 (both compatible)
-- [ ] Target WCAG level: AA (4.5:1) or AAA (7:1) contrast
-- [ ] Component pattern: Atomic Design or alternative structure
-- [ ] Documentation tool: Storybook, zeroheight, or custom
-- [ ] Figma integration: MCP server (desktop vs remote)
-- [ ] Testing strategy: Visual regression + accessibility + interaction
-
----
-
-### Level 2: Implementation Patterns (How to Build)
-
-#### Pattern 1: Design Token Architecture (DTCG 2025.10)
-
-**Token Structure** - Semantic Naming Convention:
-
-```json
-{
-  "$schema": "https://tr.designtokens.org/format/",
-  "$tokens": {
-    "color": {
-      "$type": "color",
-      "primary": {
-        "50": { "$value": "#eff6ff" },
-        "100": { "$value": "#dbeafe" },
-        "500": { "$value": "#3b82f6" },
-        "900": { "$value": "#1e3a8a" }
-      },
-      "semantic": {
-        "text": {
-          "primary": { "$value": "{color.gray.900}" },
-          "secondary": { "$value": "{color.gray.600}" },
-          "disabled": { "$value": "{color.gray.400}" }
-        },
-        "background": {
-          "default": { "$value": "{color.white}" },
-          "elevated": { "$value": "{color.gray.50}" }
-        }
-      }
-    },
-    "spacing": {
-      "$type": "dimension",
-      "xs": { "$value": "0.25rem" },
-      "sm": { "$value": "0.5rem" },
-      "md": { "$value": "1rem" },
-      "lg": { "$value": "1.5rem" },
-      "xl": { "$value": "2rem" }
-    },
-    "typography": {
-      "$type": "fontFamily",
-      "sans": { "$value": ["Inter", "system-ui", "sans-serif"] },
-      "mono": { "$value": ["JetBrains Mono", "monospace"] }
-    },
-    "fontSize": {
-      "$type": "dimension",
-      "sm": { "$value": "0.875rem" },
-      "base": { "$value": "1rem" },
-      "lg": { "$value": "1.125rem" },
-      "xl": { "$value": "1.25rem" }
-    }
-  }
-}
-```
-
-**Multi-Theme Support** (Light/Dark Mode):
-
-```json
-{
-  "color": {
-    "semantic": {
-      "background": {
-        "$type": "color",
-        "default": {
-          "$value": "{color.white}",
-          "$extensions": {
-            "mode": {
-              "dark": "{color.gray.900}"
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-**Style Dictionary Configuration** (v4.0+):
-
-```javascript
-// style-dictionary.config.js
-export default {
-  source: ['tokens/**/*.json'],
-  platforms: {
-    css: {
-      transformGroup: 'css',
-      buildPath: 'build/css/',
-      files: [{
-        destination: 'variables.css',
-        format: 'css/variables'
-      }]
-    },
-    js: {
-      transformGroup: 'js',
-      buildPath: 'build/js/',
-      files: [{
-        destination: 'tokens.js',
-        format: 'javascript/es6'
-      }]
-    }
-  }
-};
-```
-
-#### Pattern 2: 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** (Reusability 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';
-```
-
-#### Pattern 3: WCAG 2.2 Accessibility Implementation
-
-**Color Contrast Validation** (Automated Check):
-
-```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** (Focus Management):
-
-```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;
-}
-```
-
-**ARIA Labels & Roles** (Screen Reader Support):
-
-```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>
-    );
-  }
-);
-```
-
-**Motion Accessibility** (Reduced Motion Support):
-
-```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;
-  }
-}
-```
-
-#### Pattern 4: Figma MCP Integration Workflow
-
-**Setup** (Desktop Server):
-
-```bash
-# Install Figma desktop app
-# Enable MCP server in settings
-# Desktop server runs at http://127.0.0.1:3845/mcp
-```
-
-**MCP Configuration** (Claude Desktop):
-
-```json
-{
-  "mcpServers": {
-    "figma": {
-      "command": "figma-mcp",
-      "args": [],
-      "env": {
-        "FIGMA_ACCESS_TOKEN": "your-figma-token"
-      }
-    }
-  }
-}
-```
-
-**Extracting Design Tokens from Figma**:
-
-1. **Create Figma Variables** (Color, Typography, Spacing)
-2. **Use MCP Server** to extract variables:
-   - Select frame in Figma
-   - Prompt: "Extract all design tokens from this frame"
-   - MCP returns DTCG-compatible JSON
-3. **Transform to Code** using Style Dictionary
-
-**Component Code Generation**:
-
-```
-User Workflow:
-1. Select component frame in Figma
-2. Prompt: "Generate React component from this design"
-3. MCP extracts:
-   - Component structure
-   - Applied design tokens
-   - Layout properties (flex, grid)
-   - Typography and spacing
-4. Output: TypeScript React component with props
-```
-
-**Automation Pattern** (Link-based workflow):
-
-```typescript
-// scripts/sync-figma-tokens.ts
-import { exec } from 'child_process';
-import { promisify } from 'util';
-
-const execAsync = promisify(exec);
-
-async function syncFigmaTokens(figmaFileUrl: string) {
-  // Use Figma MCP to extract tokens
-  const { stdout } = await execAsync(
-    `figma-mcp extract-tokens --url="${figmaFileUrl}"`
-  );
-  
-  const tokens = JSON.parse(stdout);
-  
-  // Write to tokens directory
-  await writeFile('tokens/color.json', JSON.stringify(tokens.color, null, 2));
-  await writeFile('tokens/spacing.json', JSON.stringify(tokens.spacing, null, 2));
-  
-  // Run Style Dictionary build
-  await execAsync('npm run tokens:build');
-  
-  console.log('✅ Design tokens synchronized from Figma');
-}
-```
-
-#### Pattern 5: 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,
-  },
-};
-```
-
----
-
-### Level 3: Advanced Topics (Deep Expertise)
-
-#### Advanced 1: Type-Safe Design Tokens (TypeScript)
-
-**Generate TypeScript Types from DTCG Tokens**:
-
-```typescript
-// scripts/generate-token-types.ts
-import { readFileSync, writeFileSync } from 'fs';
-
-interface DTCGToken {
-  $value: string | number | string[];
-  $type?: string;
-  [key: string]: any;
-}
-
-function generateTypes(tokens: Record<string, any>, prefix = ''): string {
-  let types = '';
-  
-  for (const [key, value] of Object.entries(tokens)) {
-    if (value.$value !== undefined) {
-      const tokenPath = `${prefix}${key}`.replace(/\./g, '-');
-      types += `export const ${tokenPath} = '${value.$value}';\n`;
-    } else {
-      types += generateTypes(value, `${prefix}${key}.`);
-    }
-  }
-  
-  return types;
-}
-
-const colorTokens = JSON.parse(readFileSync('tokens/color.json', 'utf-8'));
-const types = generateTypes(colorTokens.$tokens);
-writeFileSync('src/tokens/colors.ts', types);
-```
-
-#### Advanced 2: Visual Regression Testing (Chromatic)
-
-```bash
-# Install Chromatic
-npm install --save-dev chromatic
-
-# Configure in package.json
-{
-  "scripts": {
-    "chromatic": "chromatic --project-token=<your-token>"
-  }
-}
-```
-
-**CI/CD Integration**:
-
-```yaml
-# .github/workflows/chromatic.yml
-name: Chromatic
-
-on: [push]
-
-jobs:
-  chromatic:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-      
-      - name: Install dependencies
-        run: npm ci
-      
-      - name: Run Chromatic
-        uses: chromaui/action@v1
-        with:
-          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
-```
-
-#### Advanced 3: 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');
-  });
-});
-```
-
----
-
-## Best Practices Checklist
-
-Design Token Architecture:
-- [ ] Use semantic naming (`color.primary.500` not `color.blue`)
-- [ ] Implement aliasing for themes (`{color.white}` references)
-- [ ] Validate DTCG 2025.10 spec compliance
-- [ ] Version tokens with semantic versioning
-- [ ] Document token usage in Storybook
-
-Component Development:
-- [ ] Follow Atomic Design hierarchy (Atoms → Molecules → Organisms)
-- [ ] Create variant-based props APIs (not separate components)
-- [ ] Document all props with TypeScript types
-- [ ] Write Storybook stories for all variants
-- [ ] Test component accessibility with jest-axe
-
-Accessibility:
-- [ ] Verify 4.5:1 contrast for all text (WCAG AA)
-- [ ] Implement keyboard navigation for all interactive elements
-- [ ] Add ARIA labels to form fields and buttons
-- [ ] Test with screen readers (NVDA, JAWS, VoiceOver)
-- [ ] Support `prefers-reduced-motion`
-
-Testing:
-- [ ] Visual regression tests for all components (Chromatic)
-- [ ] Accessibility tests with axe-core
-- [ ] Interaction tests with Testing Library
-- [ ] Cross-browser compatibility checks
-
-Figma Integration:
-- [ ] Set up Figma MCP server (desktop or remote)
-- [ ] Extract design tokens from Figma variables
-- [ ] Automate component code generation
-- [ ] Sync design changes with codebase
-
----
-
-## When NOT to Use This Skill
-
-- **Simple static sites**: Overkill for projects without complex UI requirements
-- **Rapid prototyping**: Design systems add overhead during early exploration
-- **Single-use projects**: Token architecture benefits long-term maintenance
-- **Non-web platforms**: This Skill focuses on web (React/Vue/TypeScript)
-
-For these cases, consider:
-- Plain CSS/Tailwind for static sites
-- Component libraries (Material-UI, shadcn/ui) for rapid development
-- Platform-specific design systems (iOS HIG, Material Design for Android)
-
----
-
-**Related Skills**:
-- `moai-domain-frontend` - Frontend architecture patterns
-- `moai-lang-typescript` - TypeScript best practices
-- `moai-foundation-testing` - Testing strategies
-
-**Official Resources**:
-- W3C DTCG: https://designtokens.org
-- WCAG 2.2: https://www.w3.org/WAI/WCAG22/quickref/
-- Figma MCP: https://help.figma.com/hc/en-us/articles/32132100833559
-- Style Dictionary: https://styledictionary.com
-- Storybook: https://storybook.js.org