ux-planner

ux-researcher-skill

A Claude Code skill that turns a loose product description (in any language) into a structured English UX Spec ready to hand off to a visual-design agent like huashu-design.

The technical skill identifier (in SKILL.md frontmatter) is ux-planner. The repo is named ux-researcher-skill because the skill's job is closer to UX research / product framing than visual planning.

---

What it does

You describe what you want to build:

"Хочу приложение для трекинга привычек"

"I need a SaaS dashboard for screening resumes"

The skill runs an 8-phase workflow:

1. Phase 0 — detects product archetype (1 of 7), creates a TaskCreate plan to track progress
2. Phase 1 — asks a single batch of 5 framing questions (audience, JTBD, platform, design context). Skipped automatically if the project already has context-map.md / CLAUDE.md / project memory describing the product
3. Phase 2 — drafts features, flows, and screens from archetype defaults so you edit instead of answering 30 atomic questions
4. Phase 2.5 — single yes/no question: do you want a mobile/responsive UX track? If yes, a dedicated §10 Mobile Block is added to the spec with per-screen mobile adaptation, touch interactions, and mobile-only states
5. Phase 3 — adaptive follow-ups about gaps (auth, monetization, empty states, notifications, etc.). Hard-capped at 5 questions per round, max 2 rounds, ≤8 total
6. Phase 4–5 — synthesizes per-screen briefs (information hierarchy, key elements, states, position-4 answers for huashu)
7. Phase 6 — generates the spec, runs a mandatory self-review checklist (sequential IDs, brief-count match, density type set, etc.)
8. Phase 7 — outputs a hand-off code block ready to paste into huashu, and saves an auto-memory pointer so the next session keeps context

When the description is too vague, the skill switches into advisor mode and proposes 2–3 differentiated archetypes with tradeoffs.

---

Why it exists

Without this skill, every time you go to a visual-design agent like huashu you re-answer its 10 standard questions (design context, variations, fidelity, scope, tweaks, position-4 per screen, density type, brand assets). The spec produced by ux-planner pre-answers all of them in §8 "Hand-off to huashu-design" — so huashu skips its interview and goes straight to design.

It also forces you to think about edge states (empty / loading / error / success) per screen — the most common gap in AI-assisted product design.

---

Output

A markdown file at <project>/ux-spec-<YYYY-MM-DD>-<slug>.md with 9–10 sections:

1. Product Framing
2. Functional Scope
3. User Flows
4. Screen Inventory
5. Per-Screen Briefs
6. Constraints & Context (with per-breakpoint feature parity table)
7. Design Context (for huashu)
8. Hand-off to huashu-design (the critical section)
9. Open Questions & Assumptions (with §9.4 Product Risks)
10. Mobile / Responsive Design Block (conditional, only if confirmed in Phase 2.5)

Plus a hand-off message — a fenced code block — you paste into a fresh huashu-design session.

---

Scope

✅ Mobile apps (utility, content) ✅ Web apps (productivity, dashboards) ✅ Internal tools / admin panels ✅ Landing / marketing sites ✅ Browser extensions ✅ Redesigning existing products (reads context-map.md / CLAUDE.md / memory and skips Phase 1)

❌ Slide decks, animations, infographics — those go directly to huashu-design ❌ PRDs, business cases, market sizing — out of scope ❌ Visual design execution — that's huashu's job

---

Installation

Global (recommended)

Clone into ~/.claude/skills/:

git clone https://github.com/kyzdes/ux-researcher-skill.git ~/.claude/skills/ux-planner

The folder name on disk should be ux-planner (matching the skill identifier in SKILL.md frontmatter), even though the repo is named ux-researcher-skill.

Per-project

Drop the folder into a project's local skills directory if your harness supports it.

---

Trigger phrases

The skill triggers on (Russian): хочу приложение, нужен dashboard, сделай UX, помоги придумать, продумай интерфейс, сделай app, разработать продукт.

The skill triggers on (English): design a, build me, I want an app for, need a dashboard, make a SaaS, feature spec for, UX spec, user flows for.

---

Test it

In a fresh Claude Code session (with the skill installed):

Хочу сделать сервис записи к врачу онлайн

Expected behavior: detect mobile/web borderline archetype → issue 5-question batch → draft features/flows/screens → ask the mobile-track question → adaptive follow-ups → save English spec → output hand-off code block.