/ijfw-ui-spec

name: ijfw-ui-spec
description: "Use when the user says: 'ui spec', 'design contract', 'ui audit setup', 'lock the design', 'visual contract', 'ui review setup', or '/ijfw-ui-spec'. Produces UI-SPEC.md as the visual design contract before any frontend or visual-artifact build, and dispatches ijfw-ui-auditor as the final 6-pillar gate."
since: '1.5.0'
allowed-tools: Read, Write, Bash, Grep, Glob, AskUserQuestion, Agent

IJFW UI-Spec -- lock the visual contract before build

Produce `.planning/<milestone>/<phase>/UI-SPEC.md` as the design contract for the active slice, then dispatch `ijfw-ui-auditor` as the final 6-pillar gate after implementation lands.

Domain-agnostic. Same flow for: a web UI slice ("settings page"), a book chapter layout ("Ch4 spread + typography"), a campaign deck ("launch deck 8 slides"), a brand system ("v2 token refresh"). UI-SPEC.md is the visual counterpart to SPEC.md.

When to fire

1. User explicitly asks: "ui spec", "design contract", "ui audit setup", "lock the design", or invokes `/ijfw-ui-spec`. 2. ijfw-workflow Deep path enters a frontend or visual-artifact build with no UI-SPEC.md present. 3. plan-phase is requested for a slice tagged `ui:*` or `visual:*` and no UI-SPEC.md exists.

Process

1. Locate the active slice

MILESTONE=$(cat .ijfw/state/active-milestone 2>/dev/null \
  || ls -1 .planning/ | grep -E '^[0-9]' | tail -1)
PHASE=$(cat .ijfw/state/active-phase 2>/dev/null || echo "$1")
PHASE_DIR=".planning/${MILESTONE}/${PHASE}"
MOCKUP_DIR="${PHASE_DIR}/mockups"
mkdir -p "$PHASE_DIR" "$MOCKUP_DIR"

If `$PHASE` is unset and no argument supplied, ASK which slice to spec. Never guess.

2. Load context

Read in order, skipping any that don't exist:

1. `.ijfw/memory/brief.md` -- the original ask 2. `DESIGN.md` -- existing design contract (root) 3. `.planning/<milestone>/<phase>/SPEC.md` -- locked WHAT for this slice 4. `.planning/<milestone>/<phase>/CONTEXT.md` -- discuss-phase decisions 5. Any prior `UI-SPEC.md` in earlier slices of this milestone 6. `.planning/PROJECT.md` -- non-negotiables

Extract: brand direction, declared surfaces, prior token decisions, the critical surfaces that must visualise.

3. Trigger ijfw-design if no design contract exists

If neither `DESIGN.md` nor a prior `UI-SPEC.md` lives in the repo, defer to the `ijfw-design` skill to pick a direction (brand / template / blank slate) and persist `DESIGN.md`. Resume from Step 4 once design pass landed.

4. Generate critical-surface HTML mockups

Identify 1-3 critical surfaces from SPEC.md acceptance criteria (e.g. the empty dashboard, the destructive-confirm modal, the cover spread, the opening slide). For each, write a standalone HTML file to:

$MOCKUP_DIR/<surface-name>/index.html

Use real tokens from `DESIGN.md` -- real colors, real type scale, real spacing, real content. ASCII wireframes are not acceptable here; this is the contract the auditor will grade against.

If the `ijfw-design` skill is available, invoke it via the skill router and pass the surface list. Otherwise produce mockups inline using DESIGN.md tokens.

Optional live preview:

ijfw design start --no-open 2>/dev/null && \
  ijfw design push "$MOCKUP_DIR"/*/index.html

5. Write UI-SPEC.md

Write to `$PHASE_DIR/UI-SPEC.md`:

# UI-SPEC -- <milestone> / <phase>
**Locked:** <ISO date>  **Status:** Ready for build  **Auditor:** ijfw-ui-auditor

## 1. Layout & Hierarchy
- **Primary surfaces:** <list>
- **Focal point per surface:** <where the eye lands first>
- **Breakpoints:** <e.g. 375 / 768 / 1440 -- or N/A for print>
- **Grid / column structure:** <12-col, asymmetric, single-column, etc>

## 2. Typography & Reading Flow
- **Font stack:** <heading / body / mono>
- **Type scale:** <list of allowed sizes -- e.g. 12 / 14 / 16 / 20 / 28 / 40>
- **Weights:** <list of allowed weights -- e.g. 400 / 600>
- **Line-height + measure:** <body line-height, max line length>

## 3. Color & Contrast (WCAG AA, 4.5:1 body / 3:1 large)
- **Tokens:** <fg / bg / accent / muted / destructive -- hex values>
- **60 / 30 / 10 distribution:** <dominant / secondary / accent>
- **Contrast pairs:** <list each pair with measured ratio>
- **Dark mode policy:** <required / optional / N/A>

## 4. Spacing & Rhythm
- **Spacing scale:** <e.g. 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64>
- **Arbitrary values policy:** <forbidden | exceptions list>
- **Vertical rhythm:** <baseline grid, section spacing>

## 5. Component Consistency
- **Design system / registry:** <shadcn | custom | next-forge | none>
- **Components in use:** <button, modal, table, etc -- the closed set>
- **Variants per component:** <e.g. button: primary / secondary / ghost / destructive>
- **Tokens applied:** <how components consume the token set>

## 6. Interaction & Motion
- **States covered per interactive element:** default / hover / focus /
  active / disabled / loading / error / empty
- **Motion budget:** <duration cap, easing, reduced-motion fallback>
- **Destructive-action pattern:** <confirm modal | undo | type-to-confirm>

## Critical Surfaces (Auditor evidence targets)
| Surface | Mockup | What the auditor MUST check |
|---|---|---|
| <name> | `mockups/<name>/index.html` | <one-line check> |

## Copywriting Contract
- **CTAs:** <exact strings -- "Save changes" not "Submit">
- **Empty states:** <surface -> copy>
- **Error states:** <surface -> copy>

## Registry Safety (if shadcn or third-party blocks in use)
| Block | Registry | Reviewed? |
|---|---|---|
| <block> | <url> | <yes/no> |

## Out of Scope (Deferred to later slice)
- <intentionally not addressed this slice>

## Canonical References
- DESIGN.md
- SPEC.md (`<path>`)
- CONTEXT.md (`<path>`)

6. Commit the contract

git add "$PHASE_DIR/UI-SPEC.md" "$MOCKUP_DIR"
git commit -m "ui-spec($PHASE): lock visual contract before build"

7. After build lands -- dispatch