Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/ns-proto-visual-guide/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ns-proto-visual-guide/

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

Similar skills

All skills for Design →

From the same set20

The whole set →
ns-autonomous ns-autonomous — a skill for Claude Code, Codex, Cursor, Copilot and Gemini CLI that takes a local plan or pasted text and runs it autonomously inside an isolated worktree. CX Codex +1 152installs ns-e2e-tests The ns-e2e-tests skill structures Cypress end-to-end work across devices and keeps tests in a separate project. Use it when adding or refactoring specs. CX Codex +1 151installs ns-backend-tests ns-backend-tests — a skill for writing and running PHPUnit unit and integration tests directly in your IDE. Runs only in Docker containers, helping you quickly test a new Laravel project or rewrite existing tests. CX Codex +1 151installs ns-docs-writer ns-docs-writer — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that produces human-facing project docs: README files, docs/ guides, runbooks, and contributor markdown. CX Codex +1 151installs ns-coder ns-coder handles focused code changes such as fixes, small refactors, scripts, and migrations. Use it for ad-hoc work outside a multi-stage SDD handoff. CX Codex +1 151installs ns-reviewer ns-reviewer grades code changes against SOLID principles, clean code patterns, performance, security, and testability. Approves only at score 10; score 9 triggers rejection. CX Codex +1 140installs ns-living-spec ns-living-spec maintains domain specifications in docs/specs/ after version releases or approved reviews. Turns diffs and release artifacts into functional truth. CX Codex +1 140installs ns-proto-creator ns-proto-creator — a Claude Code skill that captures live interfaces with Playwright and builds or updates a prototype. It runs for URL-based prototyping, screen reconstruction, and changes to an existing prototype/. CX Codex +1 106installs

Project sponsors

Companies that keep this analytics open