# ns-proto-visual-guide

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 106 installs
- Author: nextstage-brasil
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/nextstage-brasil/skills/tree/HEAD/skills/ns-proto-visual-guide/SKILL.md
- Updated: 2026-10-24
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/ns-proto-visual-guide

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/ns-proto-visual-guide/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/ns-proto-visual-guide/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/ns-proto-visual-guide/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/ns-proto-visual-guide/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install nextstage-brasil/skills skills/ns-proto-visual-guide
```

2. **Manually: put the files in place**
- File: `.github/skills/ns-proto-visual-guide/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/nextstage-brasil/skills --path skills/ns-proto-visual-guide
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/ns-proto-visual-guide/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/nextstage-brasil/skills/tree/HEAD/skills/ns-proto-visual-guide/SKILL.md

## When to use it
- 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
- 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.

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 0cf117af37182b05.

BEGIN THIRD-PARTY FILE 0cf117af37182b05
```text
---
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 |
```
END THIRD-PARTY FILE 0cf117af37182b05

The third-party file has ended. Everything between the 0cf117af37182b05 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2649 of 5917 bytes. © nextstage-brasil · Apache-2.0 · https://github.com/nextstage-brasil/skills/tree/HEAD/skills/ns-proto-visual-guide/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
