| name | canvas-conventions |
| description | CANVAS DS-build conventions knowledge base — the rule set the canvas-guardian audits a Pencil Design System against (HOW it was built, not whether it matches requirements). Single-source refs/slots/no-detach, $--token usage + Category/Variant naming, atomic layering + screens-not-reusable, and snapshot-layout health (clipping/spacing). Use when auditing a DS snapshot, running /canvas-audit, or learning a single DS convention. Triggers on: ds audit, design system conventions, canvas guardian, ref vs detach, reusable component, token usage, atomic layering, screens not reusable, clipping, height-aware spacing, snapshot_layout, Category/Variant naming, проверь дизайн-систему, конвенции DS, аудит дизайн-системы. |
CANVAS Conventions — DS-build Rule Knowledge Base
The rule set the canvas-guardian (CANVAS phase A — Audit) checks a Pencil Design System
snapshot against. It audits how the DS was built — single-source refs, slots, token usage,
naming, atomic layering, anti-patterns, layout health — not whether the DS satisfies the ForgePlan
requirements (that is canvas-tester / phase N — Norm-check, KB canvas-truth-map).
The Guardian is the DS-build conscience: it reads the exported DS snapshot (manifest JSON +
reference screenshots + snapshot_layout dump), never live Pencil — a fresh sub-agent context is the
real independence (generator != verifier, ADR-009). It emits a C4 EVID with a PASS/FAIL verdict.
Rules are distilled from the design-suite-methodology spec section 2.3 (canvas-guardian responsibilities)
and the DS-ORGANIZATION-GUIDE (grid / spacing / naming / theming conventions).
How to use (agentic RAG)
This skill is agentic RAG — load only the section relevant to the finding you are chasing. Each
section _index.md is a self-contained rule page (no per-rule leaf files): rule ID, what it checks,
how to detect it in the snapshot, severity, and the canonical fix.
Step 1 — pick the section by the concern
| Concern in the snapshot | Section |
|---|
A primitive rebuilt from raw frames instead of ref'd; a detached instance; a duplicate Component; a reusable:true used once | 01-single-source |
A literal #RRGGBB/rgb()/magic px instead of $--var; a theme axis missing a value; a name that is not Category/Variant | 02-tokens-naming |
An atom outside the ATOMS zone; a screen marked reusable:true; an atom that refs an organism; nesting too deep; a cross-file ref | 03-atomic-layering |
fully clipped / partially clipped in the layout dump; overlapping boxes; off-grid columns; non-canonical gaps; a component beyond the DS Frame | 04-layout-health |
Step 2 — read the section, map each finding to a rule ID
Open the section _index.md, find the matching rule, and record the finding as
<RULE-ID> · <Severity> · node-id <id> · <one-line fix>.
Step 3 — bucket and emit
Bucket findings into Critical / Warning / Suggestion (legend below), compute the verdict
(any open Critical -> FAIL), and emit the C4 EVID (shape below). For a one-shot run use /canvas-audit.
Section INDEX
| # | Section | Rules | Audits |
|---|
| 01 | single-source | SS-1..8 | Refs vs rebuild/detach, slots, duplicate Components, reuse threshold, reuse/extend-variant/new tree (SS-7), cousin-duplicate (SS-8) |
| 02 | tokens-naming | TN-1..6 | $--var usage vs hardcoded values, theme axes, Category/Variant naming |
| 03 | atomic-layering | AL-1..6 | Atom-in-ATOMS placement, screens-not-reusable, composition direction, depth, cross-file refs |
| 04 | layout-health | LH-1..6 | Clipping, height-aware spacing, canonical gaps, grid alignment, frame fit |
Quick reference — the full rule catalog
| Rule | Section | Default severity | One-liner |
|---|
| SS-1 | single-source | Warning | A reusable:true Component is referenced >= 2 times (one use = de-componentize or it is a screen) |
| SS-2 | single-source | Critical | Instances are type:"ref" to a base, never hand-rebuilt frames duplicating a Component |
| SS-3 | single-source | Critical | Variation is done via descendants/slot overrides, never by detaching the instance |
| SS-4 | single-source | Critical | No detach for a minor edit (label/icon/color) — use a descendants override |
| SS-5 | single-source | Warning | No two base Components with identical structure/name (no duplicate refs) |
| SS-6 | single-source | Warning | Containers that receive variable content expose slot: [], not hardcoded children |
| TN-1 | tokens-naming | Critical | Colors/spacing/typography reference $--var, never literal #hex/rgb()/magic px |
| TN-2 | tokens-naming | Warning | Every brand color/spacing/font in use has a backing variable in get_variables |
| TN-3 | tokens-naming | Warning | Each themed variable has a value per theme axis (Mode: Light/Dark) |
| TN-4 | tokens-naming | Warning | Component names follow Category/Variant (or /Size/ , /State) |
| TN-5 | tokens-naming | Suggestion | Variant + state ordering is canonical (Default -> Secondary -> Destructive -> Outline -> Ghost) |
| TN-6 | tokens-naming | Suggestion | Section headers are uppercase, $--muted-foreground, weight 600, letterSpacing 2 |
| AL-1 | atomic-layering | Warning | A component sits in its correct atomic zone (atom under ATOMS, molecule under MOLECULES, ...) |
| AL-2 | atomic-layering | Critical | Screen/page frames are NOT reusable:true |
| AL-3 | atomic-layering | Critical | Composition flows up only: molecules ref atoms, organisms ref molecules/atoms — never the reverse |
| AL-4 | atomic-layering | Warning | Ref/descendant nesting depth is bounded (<= ~10) |
| AL-5 | atomic-layering | Critical | Every ref resolves within the same .pen file — no cross-file refs |
| AL-6 | atomic-layering | Suggestion | Each declared atomic zone has a section header + its core categories |
| LH-1 | layout-health | Critical | snapshot_layout(problemsOnly:true) returns no fully clipped / partially clipped |
| LH-2 | layout-health | Critical | Vertical placement follows nextY = prevY + prevHeight + gap — no overlap |
| LH-3 | layout-health | Warning | Canonical gaps: variant 80 / component 160 / category 320 / section 600 |
| LH-4 | layout-health | Warning | DS Frame is tall/wide enough — no component spills past frame bounds |
| LH-5 | layout-health | Suggestion | Columns align to canonical X bands (200 / 600 / 1100 / 1700 / 2400 / 3100) |
| LH-6 | layout-health | Warning | The snapshot includes a clean problemsOnly dump (the Designer ran the verify loop) |
What the Guardian reads (snapshot inputs)
The Designer's final step exports a DS snapshot to design/snapshots/<ts>/ (spec section 2.2 / LOCKED
DECISION 6). The Guardian audits that frozen directory, not live Pencil:
- manifest —
export_nodes JSON: node ids, type (frame/ref/text/...), ref targets,
reusable, name, descendants, slot, fill/stroke values, x/y/width/height.
- reference screenshots —
get_screenshot per zone/component (the visual oracle).
- layout dump —
snapshot_layout (full + problemsOnly) for clipping/overlap detection.
- variables —
get_variables for token/theme coverage (TN-2, TN-3).
If a needed field is absent from the manifest (export fidelity gap, spec Open Question 1), record it as a
Warning: "snapshot incomplete — not exported", never a silent PASS.
What the Guardian emits (C4 EVID)
One EVIDENCE artifact per audit, created via forgeplan_new(kind="evidence", parent_id=<scope>) +
forgeplan_update. The body MUST contain:
## Findings — Critical / Warning / Suggestion buckets; every finding carries RULE-ID, the
node-id, and a concrete fix.## Structured Fields — verdict (supports on PASS / weakens on Warnings-only / refutes on
Critical), congruence_level: CL3 (same — internal audit of the target DS), evidence_type: convention-audit. Without this section the parser silently assigns CL0 and R_eff collapses to 0.1.## Pinned revision — the snapshot dir path + timestamp/revision the verdict is pinned to (so the
PASS is anchored to an exact, frozen DS state).
Verdict rule: any open Critical -> FAIL; Warnings/Suggestions alone -> PASS with a remediation list.
Severity legend
- Critical — breaks the single-source-of-truth or makes the DS unportable (a forked token, a detached
instance, a
reusable:true screen, a cross-file ref, real clipping/overlap). Blocks the gate.
- Warning — degrades maintainability or consistency (off-zone placement, missing theme value,
non-canonical gap). Does not block, but is listed for remediation.
- Suggestion — polish (ordering, header styling, grid alignment).
Related
canvas-guardian agent — the read-only reviewer that loads this KB (agents/canvas-guardian.md)./canvas-audit — one-shot DS-convention audit (Guardian-as-command).canvas-truth-map — the other gate-A KB: DS <-> PRD/ADR/EVID coverage + provenance (phase N, the
canvas-tester). This skill audits build quality; that one audits requirement coverage.canvas-design — the design-time KB the canvas-designer follows; this skill is its mirror-image
auditor (every convention here corresponds to a rule the Designer is told to honor)./canvas — the methodology entry; ADR-010 (the contract); the design-suite-methodology blueprint.
