Genui — sketch UIs in conversation
Generate
files in
for the developer to render live in the Genui VS Code extension.
Throwaway by design — the answer to "what should this look like" is what matters, not the sketch.
For how to author OpenUI Lang syntax, read the bundled openui-lang reference (positional-arg rules, component signatures, validator script). This skill is about when/where/why — not syntax.
When to invoke
Trigger phrases (from the user, in conversation):
- "sketch a [page / screen / layout]"
- "mock up a [thing]"
- "let me see a few options for X"
- "draft a UI for X"
- "genui this"
- "prototype this design"
- "what should this look like"
Do not invoke for: state-machine sanity checks, business-logic exploration, terminal apps.
The 6-step workflow
1. State the question — one line
What design is being prototyped? Write it as the first comment in the
file:
openui
# PROTOTYPE — A settings page with notification toggles, plan selector, and account deletion
# Generated: 2026-05-16
# Status: open
These
-prefixed lines are comments and stripped by the parser. They survive the file so a casual reader knows what's being explored and why.
If the question isn't crisp, ask. A vague question produces a vague sketch.
2. Decide: single design or variants?
Default: single design. Generate one file.
Variants (2-3, max 3): only when the user explicitly wants to compare. Triggers: "show me a few options", "different layouts", "I want to choose between approaches".
When generating variants, hold them to: structurally different, not colour tweaks. Different layouts, different information hierarchy, different primary affordance. Three slightly-tweaked card grids isn't a variant set, it's wallpaper. If two drafts come out similar, redo one with a "do not reuse this pattern" constraint.
3. Pick location and filename
Folder: at the workspace root. Create if missing.
Filenames (kebab-case slug):
- Single:
docs/prototype/<slug>.openui
- Variants:
docs/prototype/<slug>-a.openui
If re-prototyping the same area in a new session, version it:
. Don't overwrite previous prototypes silently.
4. Generate
Use the
REFERENCE.md for correct component signatures.
Validate before handing off:bash
node .claude/skills/genui/openui-lang/scripts/validate.mjs docs/prototype/<slug>.openui
The validator catches parse-level errors only. Component prop-schema errors only surface in the renderer (red error banner in the Genui preview). Treat that banner as ground truth.
5. Hand off to the developer
Tell the user, in one sentence:
"Created
docs/prototype/settings-page.openui
. Open it from the Explorer and run
Genui: Open Preview (
→ Genui)."
For variants: list all paths and suggest opening them side-by-side. The Genui extension keys panels by URI, so each file gets its own preview tab.
If the preview shows a red error banner, paste the error text — the user reports it back and you fix the
file. The watcher re-renders on save automatically; the developer doesn't need to reload.
6. Capture the answer and clean up
A prototype that lingers is a prototype that lies. Pick exactly one outcome:
A — Answer absorbed into real code. The design choice gets implemented as a real component / page / flow.
Delete the
file. The commit message references the prototype:
"feat: settings page (from docs/prototype/settings-page.openui
.
B — Exploration closed, nothing changed. Delete the
file. No record needed.
C — Exploration produced learning worth keeping. Write a short
(5-15 lines):
markdown
## settings-page (2026-05-16)
**Question:** Three layouts for the settings page.
**Outcome:** Variant B (sidebar nav) won. Picked because the deeper integration list needs vertical real estate. ADR-0017 covers the decision.
**Files were:** settings-page-{a,b,c}.openui — all deleted post-decision.
Then delete the
files. The learning is the artifact, not the sketch.
File-header convention
Every
generated by this skill starts with:
openui
# PROTOTYPE — <one-line question>
# Generated: <YYYY-MM-DD>
# Status: open | answered | abandoned
Status changes through the prototype's life:
- open — fresh sketch, no decision yet
- answered — design choice made, ready to delete and absorb
- abandoned — exploration didn't produce anything, delete without absorbing
Anti-patterns
- Don't put files in , , or the source tree. Sketches aren't code. is where they belong.
- Don't generate 5+ variants. 2-3 is the sweet spot. Beyond that, variants stop being radically different.
- Don't make colour-only variants. "Same layout, different palette" is a tweak, not a prototype.
- Don't leave prototype files lingering across sessions. If the design was answered, delete. If not, status it as or and revisit explicitly.
- Don't reuse a slug silently. Re-prototyping the same area? Version it (). Old prototypes stay readable in git history.
- Don't promote the directly to production. The renderer is a preview tool. To ship the design, write the real React (or other framework) component the prototype suggested.
What this skill is NOT
- Not the syntax reference — that's the bundled openui-lang.
- Not a code generator that turns a prototype into React. The developer or another agent does that translation.
- Not a UI library — is. We just render their components from text.
- Not for production UI. Always throwaway.
See also
- openui-lang — how to write files correctly. Required reading before this skill generates any code.
- The Genui VS Code extension — open any file, run "Genui: Open Preview" to render. Live re-renders on save. Its folder has 9 worked fixtures (landing, dashboard, form, settings, onboarding, callouts, accordion FAQ, conditional rendering, hello) to crib from.