ns-proto-visual-guide — скилл для Claude Code: визуальные гайды
Скилл ns-proto-visual-guide для Claude Code помогает описывать внешний вид карточек, форм, оболочек и оверлеев. Включается для нормативного визуального гайда или чек-листа визуальной проверки.
Apache-2.0 106 установок обновлён 2026-10-24
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a claude-codeЧто делает ns-proto-visual-guide
Скилл помогает составить нормативный гайд о том, как должна выглядеть конкретная поверхность интерфейса: карточка, форма, оболочка или оверлей. Он отделяет визуальное описание от бизнес-правил и расчётов раскладки, задаёт порядок разделов и предлагает таблицы для элементов и их состояний.
Перед подготовкой гайда нужно изучить исходные компоненты и соседние документы того же типа, затем выбрать подходящий пример из examples/. Гайд связывается с индексом документации и родственными страницами; чек-лист должен содержать пункты, проверяемые по отрисованному интерфейсу или DOM. Скилл зависит от ns-harness и ns-living-spec.
Если гайд описывает поведенческий UX, скилл подключает режим appearance у ns-living-spec; для одной лишь визуальной полировки этот шаг пропускается. При наличии prototype/ он служит источником правды вместо старых деревьев приложения, если пользователь не указал другое.
Какие задачи решает
- описать порядок блоков и состояния карточки
- разделить визуальные требования к форме и оболочке
- составить проверяемый чек-лист визуального QA
- связать гайд с примерами и соседней документацией
Примеры запросов агенту
- Составь нормативный визуальный гайд для формы настроек.
- Опиши, как должна выглядеть карточка, и добавь проверяемый чек-лист.
- Раздели требования к оболочке панели и содержимому формы.
Как установить ns-proto-visual-guide
1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a claude-code2Вручную: положить файлы
~/.claude/skills/ns-proto-visual-guide/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/ns-proto-visual-guide/
1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a codex2Вручную: положить файлы
.agents/skills/ns-proto-visual-guide/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a cursor2Вручную: положить файлы
.cursor/skills/ns-proto-visual-guide/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install nextstage-brasil/skills skills/ns-proto-visual-guide2Вручную: положить файлы
.github/skills/ns-proto-visual-guide/SKILL.md1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a gemini-cli2Командой платформы
gemini skills install https://github.com/nextstage-brasil/skills --path skills/ns-proto-visual-guideВручную: положить файлы
.devin/skills/ns-proto-visual-guide/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о ns-proto-visual-guide
Как установить ns-proto-visual-guide в Claude Code?
Выполни npx skills add nextstage-brasil/skills --skill ns-proto-visual-guide -a claude-code. Файл скилла находится по пути ~/.claude/skills/ns-proto-visual-guide/SKILL.md.
Что делает ns-proto-visual-guide?
Он помогает создавать нормативные описания внешнего вида отдельных поверхностей интерфейса: карточек, форм, оболочек и оверлеев. Гайд включает структуру, состояния и проверяемый визуальный чек-лист.
Что нужно для работы ns-proto-visual-guide?
Скилл зависит от ns-harness и ns-living-spec. Для описания поведенческого UX он использует режим appearance у ns-living-spec.
Исходный текст
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