MoAI Design System Specialist

Unified design expertise covering three domains: Intent-First craft (design direction and critique), UI/UX foundations (accessibility, tokens, components), and Pencil MCP integration.

---

Design Craft (absorbed from moai-design-craft)

Core Philosophy: Intent-First

Before any visual or component decision, establish why — the domain, the user, the interaction contract, and the craft principles that apply.

Design Direction Workflow:

1. Domain Exploration: Name the domain, list key entities, establish vocabulary
2. Design Memory: Load .moai/design/system.md for existing design decisions
3. Intent Statement: Write "This interface should feel [adjective] because [reason]"
4. Principle Derivation: Extract 3-5 craft principles from the intent statement
5. Apply and Critique: Evaluate implementation against each principle

Post-Build Critique Checklist:

• Does the visual hierarchy match the domain vocabulary?
• Does every animation serve an interaction contract?
• Is web copy free of AI-generic phrases ("elevate", "seamless", "leverage")?
• Does the information density match the user's cognitive load?

Anti-AI Slop Writing Rules for UI Copy:

• Replace "Unlock" → use specific action ("Publish", "Deploy", "Launch")
• Replace "Seamless" → describe the actual experience ("One-step setup")
• Replace "Leverage" → use direct verbs ("Use", "Apply", "Run")
• Headlines must state what happens, not how it feels

---

UI/UX Foundations (absorbed from moai-domain-uiux)

Design Token Architecture

W3C DTCG 2025.10 standard. Use Style Dictionary 4.0 for multi-platform output.

Token hierarchy: {category}.{concept}.{property}.{variant}.{state}

• Primitive tokens: raw values (colors, spacing scales)
• Semantic tokens: context-bound references (color.surface.primary)
• Component tokens: component-specific mappings (button.background.default)

CSS custom properties for runtime theming. Dark mode via [data-theme="dark"] selector.

Component Architecture

Atomic Design hierarchy: Atoms → Molecules → Organisms → Templates → Pages. Use shadcn/ui with Radix UI primitives for accessible, unstyled base components. Extend with Tailwind CSS utility classes. Never override Radix accessibility attributes.

Accessibility Standards

WCAG 2.2 AA minimum. AAA for text-heavy and public-facing interfaces.

Required patterns:

• All interactive elements: keyboard navigable, visible focus ring
• Images: descriptive alt text or aria-hidden="true" for decorative
• Forms: label association via htmlFor or aria-labelledby
• Color contrast: 4.5:1 for normal text, 3:1 for large text and UI components
• Reduced motion: prefers-reduced-motion media query for animations

Icon Library Selection

Library	Count	Use Case
Lucide	1500+	Default, clean, consistent stroke
Hugeicons	27K+	Rich product iconography
Iconify	200K+	Multi-library access layer
Tabler	5900+	Technical / developer tools

---

Pencil MCP Integration (absorbed from moai-design-tools, Pencil portion)

Core Pencil Tools

Tool	Purpose
mcp__pencil__get_editor_state	Load current design canvas state
mcp__pencil__batch_get	Fetch multiple design elements
mcp__pencil__get_screenshot	Capture rendered preview
mcp__pencil__snapshot_layout	Snapshot layout structure
mcp__pencil__get_style_guide	Load design tokens and style guide
mcp__pencil__batch_design	Apply design changes in batch
mcp__pencil__set_variables	Update design token variables

Pencil Workflow

1. Load editor state (get_editor_state) to understand current canvas
2. Fetch style guide (get_style_guide) to align with existing tokens
3. Apply batch changes (batch_design) for multi-element updates
4. Capture screenshot (get_screenshot) for visual verification
5. Export via moai-workflow-design-import for Pencil-to-code flow

Pencil-to-Code Export

Pencil designs export to React + Tailwind via moai-workflow-design-import. The import workflow reads the exported .pen file and generates component code using the project's shadcn/ui configuration.

For Figma MCP integration (fetching Figma design context), see moai-design-tools full skill.

Verification

• Design intent documented before any visual implementation begins
• Design tokens follow W3C DTCG hierarchy (primitive → semantic → component)
• All interactive elements pass WCAG 2.2 keyboard navigation test
• Color contrast ratios verified (4.5:1 normal text, 3:1 UI components)
• Web copy free of AI-generic filler phrases
• Pencil MCP tools used via batch operations (not individual calls) for performance