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

```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,