OpenParable
Skip to content
← Back to skills

Ijfw UI Spec

Design
ijfw-ui-spec

Ijfw UI Spec is an Agent Skill for design published in the FerroxLabs/ijfw repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/FerroxLabs/ijfw/blob/HEAD/claude/skills/ijfw-ui-spec/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/ijfw-ui-spec, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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