ns-proto-visual-guide — Claude Code skill for visual guides
The ns-proto-visual-guide Claude Code skill documents the required appearance of cards, forms, shells, and overlays. It activates for normative visual guides and visual QA checklists.
Apache-2.0 106 installs updated 2026-10-24
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a claude-codeWhat ns-proto-visual-guide does
The skill helps write a normative description of a specific UI surface, such as a card, form, shell, or overlay. It separates appearance requirements from business rules and layout calculations, and provides an ordered guide structure with tables for elements and states.
Before drafting, inspect the relevant components and sibling documents, then choose a matching specimen from examples/. The guide should link to related pages and the documentation index; checklist items must be verifiable in the rendered surface or DOM. The skill depends on ns-harness and ns-living-spec.
For guides covering behavioral UX, it invokes the appearance mode of ns-living-spec; polish-only work skips that step. When prototype/ exists, its components take precedence over legacy app trees unless the user points elsewhere.
What it helps with
- document the block order and states of a card
- separate visual requirements for a form and its shell
- write a visual QA checklist with verifiable items
- connect a guide to examples and related documentation
Example prompts for the agent
- Write a normative appearance guide for the settings form.
- Describe the card's visual states and add a checkable QA list.
- Separate the panel shell requirements from the form content.
How to install ns-proto-visual-guide
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a claude-code2Manually: put the files in place
~/.claude/skills/ns-proto-visual-guide/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ns-proto-visual-guide/
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a codex2Manually: put the files in place
.agents/skills/ns-proto-visual-guide/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a cursor2Manually: put the files in place
.cursor/skills/ns-proto-visual-guide/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install nextstage-brasil/skills skills/ns-proto-visual-guide2Manually: put the files in place
.github/skills/ns-proto-visual-guide/SKILL.md1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a gemini-cli2Platform CLI
gemini skills install https://github.com/nextstage-brasil/skills --path skills/ns-proto-visual-guideManually: put the files in place
.devin/skills/ns-proto-visual-guide/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ns-proto-visual-guide
How do I install ns-proto-visual-guide in Claude Code?
Run npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a claude-code. The skill file is located at ~/.claude/skills/ns-proto-visual-guide/SKILL.md.
What does ns-proto-visual-guide do?
It helps create normative appearance guides for individual UI surfaces, including cards, forms, shells, and overlays. Guides cover structure and states, with a visual checklist that can be checked against the rendered UI or DOM.
What does ns-proto-visual-guide require?
It depends on ns-harness and ns-living-spec. For guides that cover behavioral UX, it uses ns-living-spec in appearance mode.
Source text
SKILL.md · Apache-2.0
---
name: ns-proto-visual-guide
description: "(NS) Normative visual appearance guides (card/form/shell/overlay). MUST use for descrição normativa, guia visual, aparência, visual QA checklist, \"how this looks\", *-visual.md / *-painel-visual.md / *-appearance.md, or shell vs content / card vs form / carcaça vs formulário. Do NOT use for business rules, ERDs, layout math, API/auth, e2e, or ns-proto-creator."
license: Apache-2.0
metadata:
author: nextstage-brasil
version: "1.1"
depends:
- ns-harness
- ns-living-spec
---
# Normative visual description
Normative guides: **how UI surface must look** — not how implemented. Audience: design, product, visual QA. Need block order, hierarchy, states, sibling consistency.
Project-agnostic. Canonical specimens: [examples/](examples/README.md).
Guide language = project docs language (often English; follow repo). Section intent identical even when localizing headings.
When `prototype/` exists, prefer its components as **source of truth** over legacy app trees unless user points elsewhere. Cite `prototype/` paths in source-of-truth table.
## Instructions
1. **Name surface** — card / form / shell / overlay; match project doc language.
2. **Read before write** — open source components (prefer `prototype/`) + sibling docs same surface type. Invent absent UI → QA trust break.
3. **Load specimen** — one matching file under [examples/](examples/README.md); mirror tone, section density, table style.
4. **Boundary first** — write **Does not cover** (links to siblings) before body. Unscoped guides swallow business rules + layout math.
5. **Draft from template** — keep section order; prefer `Element | How it should appear` tables over long prose.
6. **Wire graph** — update docs index + cross-links (card ↔ form ↔ shell ↔ layout). Orphans never reviewed.
7. **Stay honest** — document what code shows today; desired look differs → say explicit.
8. **Living specs (when needed)** — guide documents product-visible behavioral UX (not pure chrome polish) → invoke `ns-living-spec` **appearance** mode with guide path + short behavioral delta. Skip polish-only.
### Why these constraints
| Constraint | Reason |
|------------|--------|
| Normative voice ("must" / "should") | Validation checklists need pass/fail, not narrative |
| Visual form only | Deep domain in product/spec docs; mix kills scanability |
| One file = one surface | Card and form answer different questions |
| Code as source of truth | Specs drift from components → decoration |
| Full states | Empty, overflow, disabled, warning, conditional visibility — where QA fails |
| Behavior as `Action \| What changes on screen` | Ties interaction to visible change; no hooks/state story |
## Output template
ALWAYS structure new guides like this (adapt titles; keep opening contract):
```markdown
# [Surface] — appearance [on the canvas / in the side panel / on screen]
Normative guide for **how [surface] must appear** in [context]: [short scope].
For design, product, and visual validation. **Does not describe** [explicit limits].
**Does not cover:**
- [Item] — see [sibling doc link]
**Source of truth in code:**
| File | Responsibility |
**Related documents:**
- [links]
---
## What it is
[1–3 short paragraphs: role, read-only vs editable, relation to siblings]
## What it [does not show / does not cover in the body] ← optional; useful for forms
| Absent section | Reason |
## Overview — block order
[ASCII of vertical/horizontal structure]
### [Modes / branches] ← when mutually exclusive modes exist
| State | Body shown |
[mermaid if it clarifies branching]
## [Block / section name]
| Element | How it should appear |
## Palette and style
| Element | Appearance |
## Expected visual behavior
| User action | What changes on screen |
## Quick visual checklist
- [ ] ...
```
**Checklist rule:** each item **verifiable** by inspecting rendered surface or DOM — no aesthetic judgement. Good: `Dismiss control present in header, aligned to trailing edge`. Bad: `Header looks balanced`.
### Optional sections (when surface needs)
- **What it does not show** — contrast sibling surface (e.g. child item vs top-level)
- **Modes** — normal/variant; edit vs follow-along
- **Selection and hover** — container states
- **Handles / anchors** — graph cards
## Surface types
| Type | Doc focus | Keep out |
|------|-----------|----------|
| Canvas card | Zones, RO content, badges, handles, create buttons | Panel form fields; layout formulas |
| Panel form | Field order, toggles, empty states, modes | Shell chrome; canvas card chrome |
| Shell | Fixed chrome (width, header, scroll) | Per-selection form bodies |
| Technical layout | Grid, gaps, resize | Visual appearance (sibling normative doc) |
One file = one surface.
## Anti-patterns
- Mix shell with content, or card with form — reviewers cannot tell which surface failed
- Paste long domain rules into visual guide — link; no dump
- Describe implementation (`useState`, class names as story) instead of appearance
- Skip empty states, warnings, conditional visibility
- Publish without index entry or cross-links
- Replace normative guide with summary matrix (matrix points *to* guide)
- Cite `vN/prototype/` as layout — product has one `prototype/` tree; versioning = git
## Examples
Before draft, open specimen for surface:
| Intent | Read first |
|--------|------------|
| Canvas card | [examples/card-canvas.md](examples/card-canvas.md) |
| Panel form | [examples/form-panel.md](examples/form-panel.md) |
| Panel chrome only | [examples/shell-panel.md](examples/shell-panel.md) |
Naming + publish checklist: [examples/README.md](examples/README.md).
## Related skills
- `ns-proto-creator` — capture live UI; create/evolve single `prototype/` tree
- `ns-living-spec` — **appearance** mode after behavioral UX documented
© nextstage-brasil · Apache-2.0 · nextstage-brasil/skills