FerroxLabs 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
- User explicitly asks: "ui spec", "design contract", "ui audit setup",
"lock the design", or invokes
/ijfw-ui-spec. - ijfw-workflow Deep path enters a frontend or visual-artifact build with no UI-SPEC.md present.
- plan-phase is requested for a slice tagged
ui:*orvisual:*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:
.ijfw/memory/brief.md-- the original askDESIGN.md-- existing design contract (root).planning/<milestone>/<phase>/SPEC.md-- locked WHAT for this slice.planning/<milestone>/<phase>/CONTEXT.md-- discuss-phase decisions- Any prior
UI-SPEC.mdin earlier slices of this milestone .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 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.mdexists 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-auditordispatched after the build commit and verdict surfaced to the user.