# Story UI Spec

> Creates ui-spec.md for complex UI. Use after story-plan before story-tasks for multi-state or interactive work.

- Skill: `telum-ai/story-ui-spec` (Agent Skill)
- Install (CLI): `npx skillmds@latest add telum-ai/story-ui-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/telum-ai/story-ui-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: telum-ai (https://skillmd.com/u/telum-ai)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/telum-ai/story-ui-spec

---


# story-ui-spec

## Step 0: Read Template First

**Before any other action** — read this template now using the Read tool:
```
.speck/templates/story/ui-spec-template.md
```
The template defines required sections and formatting for `ui-spec.md`, including **PROFILE surface impact**, component hierarchy, state matrix, design token usage, and interaction spec.

**Checkpoint**: After reading, note the top-level sections from the template. Then continue to Step 1.

Generate precise UI specifications that developers can implement directly.

**When to use this command**:
-  **REQUIRED** for stories that include UI components (forms, pages, interactive elements)
- **REQUIRED** for stories with multiple component states, variants, or animations
- **OPTIONAL** for simple, single-state UI elements that follow existing patterns

If `/story-plan` detected UI requirements, you MUST run this command before `/story-tasks`.

## Context Requirements

1. Locate the active story directory (STORY_DIR):
   - Preferred: user is already in the story directory (or a subfolder like `contracts/`)
   - Determine STORY_DIR by walking up from current directory until you find `spec.md`
   - If no `spec.md` found: instruct the user to `cd` into the story directory or return to root and let AGENTS route the request
   - Define:
     - SPEC_PATH = `{STORY_DIR}/spec.md`
     - UI_SPEC_PATH = `{STORY_DIR}/ui-spec.md`

Load context:
- Design system tokens
- Epic wireframes
- Story requirements

## Interactive UI Specification Process

### Step 1: Understand Component Context

**Determine PROJECT_ID** from story path (e.g., `specs/projects/001-myproject/epics/...`).

**Load required design context**:
- `specs/projects/[PROJECT_ID]/design-system.md` → Design tokens, components, patterns
  - Extract: Color tokens, typography scale, spacing system, component library
  - If missing: WARN "No design system found. Run `/project-design-system` for consistent UI."
  
- `specs/projects/[PROJECT_ID]/ux-strategy.md` → UX principles, voice/tone
  - Extract: Design principles, voice attributes, accessibility standards
  - If missing: WARN "No UX strategy found. Run `/project-ux` for UX guidelines."

**Load story context**:
- Story specification (what needs to be built)
- Epic wireframes (where it fits) - `{EPIC_DIR}/wireframes.md` if exists
- Epic user journey (user flow context) - `{EPIC_DIR}/user-journey.md` if exists

**Load recipe visual testing config** (tight feedback loop):
- Read `specs/projects/[PROJECT_ID]/project.md` frontmatter for `_active_recipe:`
- If present, load `.speck/recipes/[recipe-name]/recipe.yaml`
- Extract `visual_testing:` (platform/strategy/pattern_file/breakpoints/devices/window_sizes)
- Use this config to make the UI spec *testable* and *verifiable*:
  - Populate **Responsive Behavior** with the actual breakpoints/devices we will validate
  - Populate **Testing Checklist** coverage matrix (web browsers vs mobile devices vs desktop OS)
  - Add **stability requirements** for automation (e.g. `data-testid`/`testID`/Flutter keys for critical elements)
  - Reference `.cursor/skills/visual-testing/references/web.md (or platform-specific skill per visual_testing.pattern_file)` so implementers know the expected visual test approach

### Step 2: Component Discovery

The UI spec template needs specific details. Ask only what's missing:

**If component type unclear:**
- "What UI element does this story focus on?"
- "Is this modifying an existing component or creating new?"

**If variants unknown:**
- "Does this need multiple sizes or states?"
- "Any theme variations (light/dark)?"

**If behavior undefined:**
- "What happens when users interact with this?"
- "Any special animations or transitions?"

### Step 3: Gather Specifications

Work with the user to define:
- Visual properties (using design tokens)
- Interactive states and transitions (including required Form-Level States & Safeguards like Submit Pending, Double-Submit Protection, and Aria-Live status announcements)
- Form Validation Matrix (if forms/inputs are present, map each field to its rules, specific inline error messages, marked states, and ARIA attributes)
- Responsive behavior
- Accessibility requirements
- Implementation approach

### Step 4: Create UI Specification

**CRITICAL**: Load and follow the template exactly:
```
.speck/templates/story/ui-spec-template.md
```

Write output to UI_SPEC_PATH (`{STORY_DIR}/ui-spec.md`)

The template is self-documenting - follow all sections and guidelines within it.

### Step 5: Validate and continue

Check required states, variants, responsive behavior, and testability against the completed artifact. Then resume the canonical story flow in root `AGENTS.md`.

The template contains comprehensive sections for all UI specification needs.