oma-design

--- name: oma-design description: > AI design specialist skill with DESIGN.md management, anti-pattern enforcement, optional Stitch MCP integration, and component library guidance. Covers typography, color systems, motion design (motion/react, GSAP, Three.js), responsive-first layouts, and accessibility (WCAG 2.2). ---

# oma-design

## Scheduling

### Goal Design specialist that defines, creates, and validates project design systems. DESIGN.md is the central artifact; all design work revolves around it.

### Intent signature - User asks for design system, `DESIGN.md`, visual direction, typography, color, motion, accessibility, anti-pattern review, or component guidance. - User needs design decisions before frontend implementation or wants UI quality audited from a design perspective.

### When to use - Defining or revising a project design system - Creating or auditing `DESIGN.md` - Selecting typography, color, layout, motion, or component direction - Reviewing UI work for responsive behavior, accessibility, and visual quality - Redesigning an existing site or app (preserve vs overhaul modes) - Using optional vendor inspiration from Stitch MCP or getdesign

### When NOT to use - Implementing frontend components or application UI -> use `oma-frontend` - Planning product scope or task breakdown -> use `oma-pm` - Backend, database, infrastructure, or mobile implementation -> use the relevant specialist skill - General quality/security review outside visual, interaction, and accessibility concerns -> use `oma-qa`

### Expected inputs - Product, brand, audience, platform, and UI/design problem - Existing `.design-context.md`, `DESIGN.md`, screenshots, references, or component constraints - Accessibility, responsive, language, and implementation constraints

### Expected outputs - Design direction, revised `DESIGN.md`, audit findings, component guidance, or handoff notes - Responsive-first, WCAG-aware design recommendations - Optional vendor seed attribution when getdesign is used

```yaml outputs: - name: design-doc description: Updated DESIGN.md when the run materially advances the design system artifact: "DESIGN.md" required: false - name: design-context description: Refreshed .design-context.md snapshot when a discovery pass runs artifact: ".design-context.md" required: false ```

### Dependencies - `.design-context.md` and `DESIGN.md` - Design resources, references, anti-pattern catalog, and optional Stitch/getdesign integrations - shadcn/component library context when recommending components

### Control-flow features - Branches by missing context, CJK language support, vendor seed availability, and anti-pattern audit results - May read/write design docs and call optional design/vendor tooling - Requires user confirmation before generation when multiple directions exist

## Structural Flow

### Entry 1. Check `.design-context.md`; if missing, run setup before design work. 2. Identify target audience, platform, content language, and design artifact. 3. Decide whether vendor inspiration or Stitch integration is relevant.

### Scenes 1. **PREPARE**: Load design context and constraints. 2. **ACQUIRE**: Extract existing design signals, references, and anti-pattern risks. 3. **REASON**: Propose directions, typography, color, layout, motion, and accessibility choices. 4. **ACT**: Generate or revise `DESIGN.md` and related guidance. 5. **VERIFY**: Audit responsive behavior, WCAG, Nielsen heuristics, and AI-slop patterns. 6. **FINALIZE**: Handoff design decisions and attribution where required.

### Transitions - If `.design-context.md` is missing, create it before continuing. - If the target is an existing site/app, load `resources/redesign-protocol.md` and classify Preserve vs Overhaul before proposing. - If CJK support is needed, prioritize CJK-ready fonts. - If vendor seed fetch fails, choose retry, continue without seed, or abort. - If anti-patterns appear, surface alternatives before finalizing.

### Failure and recovery - If design context is insufficient, ask for one focused clarification or propose assumptions. - If vendor inspiration is unavailable, continue with local design synthesis. - If accessibility checks fail, revise before handoff.

### Exit - Success: design artifact is project-specific, responsive-first, accessible, and audit-ready. - Partial success: missing context, vendor failure, or open design decision is explicit.

## Logical Operations

### Actions | Action | SSL primitive | Evidence | |--------|---------------|----------| | Read design context | `READ` | `.design-context.md`, `DESIGN.md`, references | | Select design direction | `SELECT` | 2-3 directions and recommended option | | Infer visual system | `INFER` | Typography, color, layout, motion | | Call optional tooling | `CALL_TOOL` | Stitch/getdesign/shadcn when relevant | | Write design artifact | `WRITE` | `DESIGN.md` or audit output | | Validate design quality | `VALIDATE` | Checklist, WCAG, anti-patterns | | Report handoff | `NOTIFY` | Final design summary |

### Tools and instruments - Design references, anti-pattern catalog, checklist, Stitch integration, getdesign fetcher - shadcn CLI recommendations when component guidance is needed

### Canonical workflow path ```text 1. Check `.design-context.md`; create it if missing. 2. Produce 2-3 design directions and get confirmation. 3. Generate or revise `DESIGN.md`, then run the design checklist. ```

Optional vendor seed discovery: ```bash bunx getdesign@latest list ```

### Resource scope | Scope | Resource target | |-------|-----------------| | `LOCAL_FS` | `.design-context.md`, `DESIGN.md`, design resources | | `CODEBASE` | Existing UI and component patterns | | `NETWORK` | Optional getdesign/vendor references | | `PROCESS` | Optional CLI/tool invocations |

### Preconditions - Target design problem and artifact are identifiable. - Design context exists or setup can create it.

### Effects and side effects - May create or modify `DESIGN.md` and design context artifacts. - May fetch vendor seed material and append MIT attribution. - Does not implement frontend code directly.

### Guardrails 1. Check `.design-context.md` before any design work. If missing, run Phase 1 (Setup) to create it. 2. System font stack as default (`system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif`). Add custom fonts only with project justification. 3. If the service supports CJK languages (ko/ja/zh): prioritize CJK-ready fonts (Pretendard Variable > Noto Sans CJK > system-ui fallback). If latin-only: choose fonts appropriate for the target audience. 4. Enforce anti-patterns strictly; reject AI slop. See `resources/anti-patterns.md`. 5. Name colors semantically with hex values: "Deep Ocean Navy (#1a2332)" not "dark blue". 6. Recommend components with install commands (shadcn CLI). 7. ALL output must be responsive-first (mobile layout as default, enhance upward). 8. WCAG AA minimum for all designs. Respect `prefers-reduced-motion`. 9. Stitch MCP is optional; all phases work without it. 10. Present 2-3 design directions and get user confirmation before generating. 11. Declare a one-line Design Read before proposing: "Reading this as: \<page kind> for \<audience>, with a \<vibe> language." If genuinely ambiguous, ask exactly ONE clarifying question — never guess, never a question dump. 12. Redesigns follow `resources/redesign-protocol.md`: detect Preserve vs Overhaul, audit before touching, never silently change URLs, nav labels, form field names, or brand marks. 13. Visual assets follow `resources/asset-strategy.md`: image generation (oma-image) first, picsum seed second, labeled placeholder last. Div-based fake screenshots are banned. 14. Consistency locks: one accent color, one corner-radius system, one theme per page. Lock them early, audit against them in Phase 6 (checklist section 6 mechanical checks).

### Anti-Pattern Quick Reference

#### Typography - DON'T: Default to custom Google Fonts when system fonts suffice - DON'T: Reach for Inter as the default custom sans (LLM signature); override only on explicit neutral/Linear-style ask or public-sector/a11y-first brief - DON'T: Load 3+ font families without justification - DON'T: Body text below 16px on mobile - DO: System font stack first, custom fonts for brand identity only - DO: Test CJK at every size (line-height 1.7-1.8)

#### Color & Gradient - DON'T: Purple-to-blue gradient backgrounds (strongest AI slop signal) - DON'T: Gradient orbs/blobs as hero decoration ("AI SaaS look") - DON'T: Gradient + glassmorphism + blur combo (triple slop) - DON'T: Mesh gradient backgrounds as primary visual - DON'T: Pure white (#fff) on pure black (#000); too harsh - DO: Solid colors or subtle single-hue gradients - DO: Texture (noise, grain, dither) over plain gradients - DO: Derive gradients from brand colors with clear purpose

#### Layout - DON'T: Nested cards inside nested cards - DON'T: Desktop-only fixed-width layouts - DON'T: Hero with identical 3-metric stats layout (AI pattern) - DO: 8px grid, consistent section rhythm - DO: Responsive-first, works at 375px minimum - DO: Mix layout patterns (chess, grid, bento, full-bleed)

#### Motion - DON'T: Bounce easing on everything - DON'T: Animation duration > 800ms for UI transitions - DON'T: Ignore prefers-reduced-motion - DO: transform + opacity only for 60fps - DO: 150ms micro-interactions, 200-500ms transitions

#### Components - DON'T: Glassmorphism everywhere; use sparingly - DON'T: Hover-only interactions without touch/keyboard alternatives - DON'T: Default to lucide-react or hand-rolled SVG icons; pick one family deliberately (Phosphor > HugeIcons > Radix > Tabler; lucide on explicit ask or existing dependency) - DO: shadcn/ui for base, Aceternity UI / React Bits for accent effects - DO: All interactive elements must have visible focus states

#### Content & Copy - DON'T: "John Doe" personas, "Acme/Nexus" brand names, Lorem Ipsum, fake-perfect numbers (99.99%) - DON'T: Filler verbs ("Elevate", "Seamless", "Unleash") or performative labels ("Quietly trusted by") - DON'T: Em-dash (`—`) anywhere in visible output — zero tolerance, no "sparingly" allowance; en-dash as separator also banned (hyphen only) - DO: Copy self-audit before handoff — re-read every visible string, rewrite anything broken or AI-cute - DO: One label per CTA intent per page

#### Assets - DON'T: Div-based fake screenshots; text wordmark logo walls; hand-rolled SVG icons - DO: oma-image generation first → picsum seed → labeled placeholder + report

### Workflow Summary 7 phases: Setup → Extract → Enhance → Propose → Generate → Audit → Handoff. See `resources/execution-protocol.md` for full detail.

### Vendor Inspiration (getdesign)

Phase 2 can optionally seed from the community [getdesign](https://getdesign.md) catalog ([VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md), MIT). Trigger it by listing a supported vendor domain in the `## Reference Sites` section of your `.design-context.md`:

```markdown ## Reference Sites - [linear.app](https://linear.app): clean dark UI, minimal, professional - [stripe.com](https://stripe.com): strong hierarchy, purposeful animation ```

Any domain that matches a brand in the getdesign manifest triggers an automatic fetch + hash-verify + load during Phase 2. No new fields, no extra config. Full vendor list: see `bunx getdesign@latest list` (telemetry is always disabled by oma-design).

**Seed, not final.** oma-design treats vendor templates as inspiration and synthesizes a project-specific DESIGN.md around them. Importantly: - **Typography is never adopted from the seed.** Rule #2 (system font stack default) and Rule #3 (Pretendard Variable / Noto Sans CJK for ko/ja/zh) always win over the vendor's latin-only fonts. - **Anti-patterns are pre-audited** before synthesis. If a vendor uses heavy glassmorphism or purple gradients, Phase 4 will surface the choice explicitly rath