Cycle 380: UI Design Skill — Research-First UI Workflow
Priority: MEDIUM Status: IMPLEMENTED Domain: Developer Experience (DX) Dependencies: None Issue: #380 PR: #373Objective
Build a project-local Claude Code skill (.claude/skills/ui-design/) that enforces a research-first, screenshot-driven UI design workflow for the Flux frontend. The skill fires when building new pages, views, or visually significant features — not for minor tweaks or bug fixes.
The skill ensures every significant UI decision is:
- Preceded by a delivery mode decision (standalone page vs generative UI vs hybrid)
- Backed by SOTA research (3-5 best-in-class references)
- Approved by the user before implementation begins
- Validated with real Playwright screenshots at mobile and desktop viewports
- Documented as durable artifacts in
docs/design/cycle-{N}/
Key Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Scope | Project-local skill | Deeply Flux-specific — embeds DDD, schema pipeline, component conventions, chat integration |
| Location | .claude/skills/ui-design/ | Committed with the repo, only fires in Flux |
| Trigger | Narrow | Research + screenshot loop is overkill for “add a tooltip” |
| Workflow | 4 phases with exit ramps | Phase 0 (delivery mode) → Phase 1 (research) → Phase 2 (build + iterate) → Phase 3 (finalize + artifact) |
| Preview route | Authenticated inside (protected) | No middleware auth holes — dev-only notFound() guard |
| API types | @/types/api barrel export | Never import from web/generated/api/ directly |
| Artifacts | Screenshots + design brief + component inventory | Full design spec in docs/design/, cycle doc just links to it |
Deliverables
Skill Files (.claude/skills/ui-design/)
| File | Purpose |
|---|---|
SKILL.md | 4-phase workflow with trigger rubric, exit ramps, completion checklist (220 lines) |
references/flux-stack.md | Next.js 15.5, React 19, shadcn/ui, Tailwind v4, route groups, schema pipeline |
references/component-conventions.md | DDD component organization, naming, file placement, loading states, data fetching |
references/design-system.md | Design tokens from globals.css — colors, radii, spacing, typography, dark mode |
references/chat-integration.md | Three-tier rich content (artifacts, inline visuals, client-side tools), usePageChatContext, generative UI registry (7 tools), session strategy |
templates/design-brief.md | Template for design brief artifacts |
templates/component-inventory.md | Template for component inventory checklist |
Infrastructure
| File | Purpose |
|---|---|
docs/design/.gitkeep | Output directory for design artifacts (one subdirectory per cycle) |
Phase 0 — UI Delivery Mode (New)
The key architectural addition. Before any visual design work, the skill forces a delivery mode decision:- Standalone page — route under
(protected)or(public), user navigates directly - Generative UI — rich content AI renders inside chat (artifacts, inline visuals, client-side tools)
- Sidebar enrichment — page context flows to chat sidebar via
usePageChatContext - Hybrid — most features: standalone page + enriched sidebar + generative UI
(protected) page has ChatContextProvider, ContextualChatSidebar, and AskAIButton. Building a “page” always means designing its chat integration.
Design Artifact Structure
## UI Design section:
Design Process Documentation
- Spec:
docs/superpowers/specs/2026-04-14-ui-design-skill-spec.md - Plan:
docs/superpowers/plans/2026-04-14-ui-design-skill.md
Verification
- Skill fires when asking to “build the candidate portal” (new page/view)
- Skill does NOT fire for “add a tooltip to the candidate card” (minor tweak)
- Phase 0 forces delivery mode decision before visual research
- References accurately reflect repo state (generative UI registry,
usePageChatContext, design tokens) - First real validation: use this skill for Cycle 206 (Candidate Portal)