Feature request: UI doc review skill — review UI description docs from naive user perspective
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
## Summary
Before generating production HTML with `/design-html`, there's a critical missing step: **validating that the UI description document is clear enough for both AI and end users to understand**.
I'd like to propose a new skill (`/ui-doc-review`) that reviews UI/interaction/product design documents from the perspective of a **completely non-technical target user** — someone who doesn't know what APIs, CSS, components, or breakpoints are. They only care about: *what does this page look like? what can I do? what happens when I click?*
## Problem
When AI generates HTML from a UI description doc, garbage in = garbage out. If the doc is ambiguous, has missing interaction states, or is full of technical jargon, the AI will guess — and guess wrong. Currently there's no quality gate between "write a UI doc" and "generate HTML from it."
## Proposed Workflow
1. User writes a UI description doc (markdown)
2. **`/ui-doc-review docs/my-page-design.md`** ← this new skill
3. AI role-plays as the most naive target user, reads the doc section by section
4. Outputs a structured review report with:
- **Scores across 6 dimensions** (1-10 scale):
- Visualizability — can I picture this page in my head?
- Interaction Completeness — what happens when I click/tap/hover?
- User Journey Coverage — are all my scenarios covered?
- Ambiguity & Contradiction — does the doc contradict itself?
- Information Density — too much jargon or filler?
- AI Actionability — can an AI build this without guessing?
- **Prioritized problem list** (P0/P1/P2)
- **Naive user questions** — "what if I want to see yesterday's data?"
- **AI-consumable fix instructions** — concrete find-and-replace or insert directives that another AI can execute to fix the doc automatically
5. User (or AI) fixes the doc based on the report
6. Then proceed to `/design-html`
## Why This Matters
This fits naturally into the gstack design pipeline:
- `/design-consultation` → establish design system
- `/design-shotgun` → explore visual variants
- **`/ui-doc-review`** → validate the doc is clear ← **NEW**
- `/design-html` → generate production HTML
The review report format is deliberately structured for AI consumption, so it can be piped into an automated doc-fix step.
## Example: What It Catches
Given a doc like:
```markdown
## User Management
Adopt React Hook Form + Zod validation with TanStack Query for data fetching.
Component tree: UserTable (AG Grid, server-side row model) → UserEditDrawer → RoleSelector (RBAC, hierarchical)
```
The skill would flag:
- **P0 [Visualizability]**: "I have no idea what this page looks like. What's AG Grid? What does 'server-side row model' mean? I just want to see a list of users."
- **P0 [Interaction]**: "What happens when I click on a user? Does a drawer open? From which side? How do I save changes?"
- **P1 [Ambiguity]**: "Is 'RoleSelector (RBAC, hierarchical)' a dropdown? A tree? A modal?"
## I've Built a Prototype
I have a working local implementation of this skill with the full SKILL.md definition, test docs (intentionally bad doc for testing), and evaluation framework. Happy to contribute it as a PR if there's interest.
---
*This would pair especially well with `/design-html` and `/plan-design-review` — catch doc quality issues before they become design implementation issues.*
Contributor guide
Assessment
This issue has not been assessed yet.