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/.
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
- Name surface — card / form / shell / overlay; match project doc language.
- Read before write — open source components (prefer
prototype/) + sibling docs same surface type. Invent absent UI → QA trust break.
- Load specimen — one matching file under examples/; mirror tone, section density, table style.
- Boundary first — write Does not cover (links to siblings) before body. Unscoped guides swallow business rules + layout math.
- Draft from template — keep section order; prefer
Element | How it should appear tables over long prose.
- Wire graph — update docs index + cross-links (card ↔ form ↔ shell ↔ layout). Orphans never reviewed.
- Stay honest — document what code shows today; desired look differs → say explicit.
- 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):
# [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 |
| Panel form |
examples/form-panel.md |
| Panel chrome only |
examples/shell-panel.md |
Naming + publish checklist: examples/README.md.
Related skills
ns-proto-creator — capture live UI; create/evolve single prototype/ treens-living-spec — appearance mode after behavioral UX documented
1---2name: ns-proto-visual-guide3description: (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.4license: Apache-2.05---67# Normative visual description89Normative guides: **how UI surface must look** — not how implemented. Audience: design, product, visual QA. Need block order, hierarchy, states, sibling consistency.1011Project-agnostic. Canonical specimens: [examples/](examples/README.md).1213Guide language = project docs language (often English; follow repo). Section intent identical even when localizing headings.1415When `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.1617## Instructions18191. **Name surface** — card / form / shell / overlay; match project doc language.202. **Read before write** — open source components (prefer `prototype/`) + sibling docs same surface type. Invent absent UI → QA trust break.213. **Load specimen** — one matching file under [examples/](examples/README.md); mirror tone, section density, table style.224. **Boundary first** — write **Does not cover** (links to siblings) before body. Unscoped guides swallow business rules + layout math.235. **Draft from template** — keep section order; prefer `Element | How it should appear` tables over long prose.246. **Wire graph** — update docs index + cross-links (card ↔ form ↔ shell ↔ layout). Orphans never reviewed.257. **Stay honest** — document what code shows today; desired look differs → say explicit.268. **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.2728### Why these constraints2930| Constraint | Reason |31|------------|--------|32| Normative voice ("must" / "should") | Validation checklists need pass/fail, not narrative |33| Visual form only | Deep domain in product/spec docs; mix kills scanability |34| One file = one surface | Card and form answer different questions |35| Code as source of truth | Specs drift from components → decoration |36| Full states | Empty, overflow, disabled, warning, conditional visibility — where QA fails |37| Behavior as `Action \| What changes on screen` | Ties interaction to visible change; no hooks/state story |3839## Output template4041ALWAYS structure new guides like this (adapt titles; keep opening contract):4243```markdown44# [Surface] — appearance [on the canvas / in the side panel / on screen]4546Normative guide for **how [surface] must appear** in [context]: [short scope].4748For design, product, and visual validation. **Does not describe** [explicit limits].4950**Does not cover:**51- [Item] — see [sibling doc link]5253**Source of truth in code:**54| File | Responsibility |5556**Related documents:**57- [links]5859---6061## What it is62[1–3 short paragraphs: role, read-only vs editable, relation to siblings]6364## What it [does not show / does not cover in the body] ← optional; useful for forms65| Absent section | Reason |6667## Overview — block order68[ASCII of vertical/horizontal structure]6970### [Modes / branches] ← when mutually exclusive modes exist71| State | Body shown |72[mermaid if it clarifies branching]7374## [Block / section name]75| Element | How it should appear |7677## Palette and style78| Element | Appearance |7980## Expected visual behavior81| User action | What changes on screen |8283## Quick visual checklist84- [ ] ...85```8687**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`.8889### Optional sections (when surface needs)9091- **What it does not show** — contrast sibling surface (e.g. child item vs top-level)92- **Modes** — normal/variant; edit vs follow-along93- **Selection and hover** — container states94- **Handles / anchors** — graph cards9596## Surface types9798| Type | Doc focus | Keep out |99|------|-----------|----------|100| Canvas card | Zones, RO content, badges, handles, create buttons | Panel form fields; layout formulas |101| Panel form | Field order, toggles, empty states, modes | Shell chrome; canvas card chrome |102| Shell | Fixed chrome (width, header, scroll) | Per-selection form bodies |103| Technical layout | Grid, gaps, resize | Visual appearance (sibling normative doc) |104105One file = one surface.106107## Anti-patterns108109- Mix shell with content, or card with form — reviewers cannot tell which surface failed110- Paste long domain rules into visual guide — link; no dump111- Describe implementation (`useState`, class names as story) instead of appearance112- Skip empty states, warnings, conditional visibility113- Publish without index entry or cross-links114- Replace normative guide with summary matrix (matrix points *to* guide)115- Cite `vN/prototype/` as layout — product has one `prototype/` tree; versioning = git116117## Examples118119Before draft, open specimen for surface:120121| Intent | Read first |122|--------|------------|123| Canvas card | [examples/card-canvas.md](examples/card-canvas.md) |124| Panel form | [examples/form-panel.md](examples/form-panel.md) |125| Panel chrome only | [examples/shell-panel.md](examples/shell-panel.md) |126127Naming + publish checklist: [examples/README.md](examples/README.md).128129## Related skills130131- `ns-proto-creator` — capture live UI; create/evolve single `prototype/` tree132- `ns-living-spec` — **appearance** mode after behavioral UX documented
nextstage-brasil