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 --   /  /  /  /  / >
  
  


  
  
  
  


  
  
  


  
  
  
  


  default / hover / focus /
  active / disabled / loading / error / empty
  
  


| Surface | Mockup | What the auditor MUST check |
|---|---|---|
|  |  |  |


  
   copy>
   copy>


| Block | Registry | Reviewed? |
|---|---|---|
|  |  |  |


 


 DESIGN.md
 SPEC.md ()
 CONTEXT.md ()

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 ijfw-ui-auditor

Once implementation commits land for this slice (executor reports DONE), dispatch the auditor as the final visual gate:

Task: ijfw-ui-auditor
Args:
  phase: $PHASE
  ui_spec_path: $PHASE_DIR/UI-SPEC.md
  source_scope: <comma-separated dirs, e.g. src,app,components>
  dev_server_url: <optional, e.g. http://localhost:3000>

Wait for the auditor. It writes $PHASE_DIR/UI-REVIEW.md with per-pillar PASS / FLAG / BLOCK verdicts. Surface its top-level verdict to the user:

• PASS -- ship is unblocked.
• FLAG -- ship may proceed; record follow-ups in CONTEXT.md.
• BLOCK -- ship is blocked; fix and re-dispatch the auditor.

Anti-patterns (do not do)

• Do NOT write UI-SPEC.md without DESIGN.md tokens -- the contract has nothing to enforce.
• Do NOT produce ASCII wireframes as the critical-surface mockups; they defeat the auditor's evidence loop.
• Do NOT skip dispatching ijfw-ui-auditor after build -- the contract without the gate is half-shipped.
• Do NOT include implementation details (component code, framework choices); those belong to plan-phase output.

Success criteria

• UI-SPEC.md exists at .planning/<milestone>/<phase>/UI-SPEC.md.
• All 6 pillars populated with concrete values (no TBDs).
• At least one critical-surface HTML mockup written under mockups/.
• Contract commit landed on the active branch.
• ijfw-ui-auditor dispatched after the build commit and verdict surfaced to the user.