/ijfw-ui-spec
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
$ npx -y skills add FerroxLabs/ijfw --skill ijfw-ui-spec --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/ijfw-ui-spec
Context preview
The summary Claude sees to decide when to auto-load this skill.
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
SKILL.md
ijfw-ui-spec.SKILL.mdname: 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
Read more
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
IJFW — It Just F*cking Works. Ferrox Labs' local-first infrastructure for AI coding agents: shared memory, smart routing, multi-AI cross-audits, disciplined workflow.
Repo: FerroxLabs/ijfw
Other skills on ijfw.
- /ijfw-agents-md
Maintain canonical AGENTS.md (open spec). Trigger: 'agents.md', 'update AGENTS.md', or auto-fired by ijfw-team after agent generation.
Open skill - /ijfw-auto-memorize
Session-end auto-extraction of lessons, errors, fixes, and user feedback into structured memory. Fires at session end. Requires consent on first run.
Open skill - /ijfw-commit
Terse conventional commits. Trigger: commit, git commit, /ijfw-commit
Open skill - /ijfw-complete-milestone
Use when a milestone is shipping and you need to archive its artifacts, generate a summary, and seed the next milestone. Trigger: 'milestone complete', 'ship milestone', 'wrap milestone', 'complete milestone <id>', /ijfw-complete-milestone.
Open skill - /ijfw-compress
Compress memory/context files into terse form. Trigger: /compress, compress file
Open skill - /ijfw-compute
Use when the user says: 'compute', 'crunch this', 'analyze logs', 'aggregate the data', 'run a script', 'dedupe', 'count by', 'top N', or any data-shaping ask. Replaces dumping raw data into context with sandboxed script execution.
Open skill