oma-design

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

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

Tools and instruments

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

Canonical workflow path

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:

bunx getdesign@latest list

Resource scope

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 catalog (VoltAgent/awesome-design-md, MIT). Trigger it by listing a supported vendor domain in the ## Reference Sites section of your .design-context.md:

## 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 rather than copy the pattern silently.
• Offline is fine. If the fetch fails, you get a 3-option dialog (retry / continue without seed / abort). Default: continue.

Attribution is appended to the generated DESIGN.md in Phase 7 as a required MIT compliance footer. Full fetcher rules, matching algorithm, injection defenses, and multi-vendor merge policy live in resources/getdesign-fetcher.md.

Resources

• resources/execution-protocol.md: 7-phase workflow + example .design-context.md appendix
• resources/anti-patterns.md: Full DO/DON'T catalog
• resources/checklist.md: Audit checklist (Responsive + WCAG + Nielsen + Slop + Mechanical counts)
• resources/design-md-spec.md: DESIGN.md generation guide (9 sections)
• resources/design-tokens.md: CSS/Tailwind/shadcn export templates
• resources/prompt-enhancement.md: Vague request to detailed spec + worked landing-page example
• resources/stitch-integration.md: Stitch MCP tool mapping (optional)
• resources/getdesign-fetcher.md: Vendor seed fetch, hash verify, seed rules
• resources/redesign-protocol.md: Preserve/Overhaul modes, audit-first, modernization levers
• resources/asset-strategy.md: Image sourcing priority, logo walls, fake-screenshot ban
• resources/error-playbook.md: Design error recovery

References

• reference/visual-hierarchy.md: 7 hierarchy principles (Alignment, Color, Contrast, Proximity, Size, Texture, Time)
• reference/typography.md: Font selection, type scale, CJK
• reference/color-and-contrast.md: Color psychology, WCAG contrast
• reference/spatial-design.md: 8px grid, breakpoints, spacing
• reference/motion-design.md: motion/react, GSAP, Three.js, ogl, Temporal UX
• reference/responsive-design.md: Mobile-first, theme system
• reference/component-patterns.md: shadcn/Aceternity/React Bits catalog
• reference/accessibility.md: WCAG 2.2, ARIA, focus, reduced-motion
• reference/shader-and-3d.md: WebGL, R3F, ogl, performance