oma-design · diff
git:20260909.093aa3d to git:20260912.7e4c0d1
21 added, 135 removed. Audit A to A.
---
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).
+ description: "Define or review a visual system, DESIGN.md, or redesign direction. Use for typography, layout, color, motion, and interaction design decisions."
---
# 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
+ - Asks about a direction only when a material choice is unresolved; otherwise follows the supplied brief
## Structural Flow
### Entry
- 1. Check `.design-context.md`; if missing, run setup before design work.
+ 1. Read relevant existing design context; gather missing context only when needed for the requested decision.
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.
+ - Create `.design-context.md` when a discovery pass materially informs a design-system decision.
- 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.
+ 1. Inspect relevant existing context; create `.design-context.md` only when substantive discovery is needed.
+ 2. Use the chosen direction. Offer alternatives only for requested exploration or a material unresolved design decision.
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.
+ 1. Inspect relevant existing context and tokens. Create `.design-context.md` for substantive discovery, not every visual edit.
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.
+ 10. Present directions when design exploration is requested or a material direction is unresolved; reuse an already chosen direction.
+ 11. State a material design assumption when it affects the outcome. Ask only about unresolved choices; no fixed opening phrase is required.
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.
-
- ### 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 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
+ - `resources/execution-protocol.md`: selected design operation and its phases
+ - `resources/redesign-protocol.md`: existing-site redesign
+ - `resources/design-md-spec.md`: creating or changing DESIGN.md
+ - `resources/checklist.md`: applicable visual verification checks
+ - `resources/anti-patterns.md`: affected visual or copy category
+ - `resources/getdesign-fetcher.md`: explicitly relevant vendor inspiration
+ - `resources/stitch-integration.md`: requested Stitch operation
+ - `resources/asset-strategy.md`: selecting visual assets
+ - `resources/design-tokens.md`: token export
+ - `resources/prompt-enhancement.md`: incomplete design brief
+ - `resources/error-playbook.md`: observed design-tool failure
- `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
+