CONTRIBUTING.md

Contributing

Editing the skill

skills/visualize/ is the single authored and installable skill. Edit it directly. Host installers consume this same directory; there are no mirrors to regenerate.

After editing the skill:

node dev-scripts/check-skill-package.mjs

CI checks the package in isolation, including its command metadata, routed references, and bundled helper dependencies. See HARNESSES.md for installation routes and verification limits.

Preserving design judgment

The skill should help the reader understand the source, not reward the agent for making more changes. When revising its procedures, preserve these distinctions:

• Requirements versus solutions. Feedback can expose a defect or change the brief; it does not automatically justify another local adjustment. Keep that decision in SKILL.md's Design judgment, and have verb-specific refusal and routing instructions defer to it.
• Artifact scope versus shared authority. Refinement permission covers the artifact, not its project's brand profile or token source. The authority boundary belongs in Universal laws.
• Evidence versus activity. Finding counts, diff size, and clean detector output do not establish design quality. Preserve bounded completion in polish and rendered comparison evidence in Artifact Explore.

Keep procedures in the linked skill sections; this guide explains what edits must preserve. Before adding another instruction, identify the demonstrated failure and whether it comes from routing, unclear guidance, conflicting rules, or a mechanical check. Change the responsible layer rather than adding a second policy to a reference.

Validate workflow changes with an independent agent using the changed skill on a representative artifact. Check both the failure and a nearby valid case: clean output should not provoke invented polish work; a bounded correction should not reopen the brief; unresolved structure should not trigger target edits; and a missing shared token should not authorize a design-system change. Keep test artifacts and screenshots under temp/. Inspect the actions and rendered evidence, not just the agent's explanation. Re-test after fixes; package and syntax checks do not establish behavioral correctness.

Adding a template

Drop a new directory under skills/visualize/templates/<slug>/ with one file: template.md. Required frontmatter is name and description; shell is optional and must resolve to skills/visualize/shells/<slug>/README.md. Keep the body focused on Use when, Do not use when, Structure, Creation guidance, Hierarchy contract, Mobile contract, and concrete failure modes. Do not add live template HTML or template-skill.md.

If the template needs shared creation guidance, mention pattern recipe slugs in body prose. Pattern recipes are not automatic dependencies and must not appear in template frontmatter.

Before opening a PR that changes templates, run:

node dev-scripts/inventory-template-composition.mjs --strict
dev-scripts/build-template-previews.sh --matrix dev-scripts/template-preview-matrix.json
find temp/template-previews -name '*.html' -print0 | xargs -0 node skills/visualize/scripts/detect.mjs --strict

Generated fixture previews live under temp/template-previews/ and are intentionally uncommitted.

Adding a design system

Drop a new directory under catalog/design-systems/<slug>/ with DESIGN.md (Google Stitch's canonical format — YAML frontmatter carrying design tokens + a six-section markdown body: Overview / Colors / Typography / Elevation / Components / Do's and Don'ts) and tokens.css (sidecar with CSS custom properties for the :root + .dark blocks). The worked exemplar is catalog/design-systems/clean/DESIGN.md — match its overall shape (YAML structure, evocative subtitles, Named Rules pattern) and adapt the content for the new register.

Then add <slug> to the DESIGN_SYSTEMS array in dev-scripts/build-previews.sh (alphabetical) and regenerate the previews:

dev-scripts/build-previews.sh

Commit the generated preview.html + preview-dark.html alongside DESIGN.md + tokens.css. CI runs build-previews.sh --check and fails the build if the committed previews drift from regenerated output.

A package may also include a short README.md linking its design guidance, tokens, and previews, with an example of theme usage; see Editorial. Keep system-specific identity and adaptation rules in DESIGN.md, and application/override procedure in SKILL.md's Artifact themes section. Do not duplicate the shared workflow across package READMEs.

Catalog distribution

The installed catalog resources are the generated selection index, Clean fallback, and catalog source pin. catalog/design-systems/ is their single authoring source. Run node dev-scripts/catalog-index.mjs to regenerate those bundled files in skills/visualize/design-systems/. CI checks generation. Authoring metadata is validated from the working catalog; bundled files are generated from the pinned Git snapshot, so a catalog-only PR leaves the installed selection unchanged. Fetch that commit locally first if needed (git fetch --no-tags --depth=1 origin <revision>).

Shared motion guidance stays runtime-owned at skills/visualize/design-systems/animation-patterns.md. Edit it directly; it serves both animate and catalog preview authors and does not require catalog publication or repinning.

Other references are read from the immutable public commit and catalog root recorded in catalog/source.json. To distribute catalog changes, first merge/publish the catalog source and previews; then, in a follow-up distribution change, set revision to that reachable full commit SHA and root to catalog/design-systems, and regenerate. Do not point at an unpublished commit, branch, or tag. The initial pin uses the previously published visualize/design-systems snapshot; that historical path is unchanged by the current skill directory. New entries or changed reference guidance must be published and pinned before distributing their updated selection index.

Verify a changed pin with a cold cache by resolving each changed package (including --previews) and comparing the returned bytes with the published catalog. node --test dev-scripts/catalog.test.mjs covers cache and failure behavior.

Bundled Clean's README rebases shared-workflow links from ../../../skills/visualize/ (or legacy ../../../visualize/) to ../../. Compare that README after applying only this rewrite, or compare its --previews copy with the published package; catalog-index.mjs --check enforces the bundled form.

Adding a per-system preview-template

A design system can ship its own preview-template.html that overrides the generic dev-scripts/preview-kit/template.html shell. Most design systems carry one so the preview can show their signature moves; systems without an override fall back to the preview-kit shell with only their tokens applied.

Drop preview-template.html in catalog/design-systems/<slug>/. The file must carry four placeholders verbatim: __ROOT_ATTR__ on the <html> tag, __DESIGN_SYSTEM_NAME__ wherever the slug should appear, and /* __TOKENS_PLACEHOLDER__ */ + the legacy marker /* __COMPONENTS_PLACEHOLDER__ */ each inside a <style> block on a whitespace-only line. The latter now injects preview-only fixture styles from dev-scripts/preview-kit/fixture-styles/. dev-scripts/build-previews.sh auto-detects the override. Per-system templates don't inherit dev-scripts/preview-kit/template.html, so declare any required Google Fonts inside the per-system <head>.

If the brand's synthesised dark mode reads wrong (low contrast or wrong-temperature surfaces), hand-edit the [data-theme="dark"] block in tokens.css to the brand's actual dark surface. See catalog/design-systems/AUTHORING.md for pattern references, the dark-mode strategy decision table, and the detect-clean checklist.

After editing:

bash dev-scripts/build-previews.sh
node skills/visualize/scripts/detect.mjs --strict catalog/design-systems/<slug>/preview.html
node dev-scripts/check-skill-package.mjs

Preview kit

dev-scripts/preview-kit/ carries the canonical token-surface preview page. Each design system gets two generated files at design-systems/<slug>/preview.html (light) and preview-dark.html (dark).

Do not hand-edit the generated previews. When you change dev-scripts/preview-kit/template.html, fixture styles under dev-scripts/preview-kit/fixture-styles/, or a design system's tokens.css, regenerate via dev-scripts/build-previews.sh. See dev-scripts/preview-kit/README.md for the placeholder contract and extension notes.

For targeted fixture previews, use dev-scripts/build-template-previews.sh. It renders fixture files from skills/visualize/fixtures/manifest.json against any design-system tokens.css and writes standalone HTML to temp/template-previews/:

dev-scripts/build-template-previews.sh --fixture patterns/table.html --design-system swiss --mode light
dev-scripts/build-template-previews.sh --manifest --design-system clean
dev-scripts/build-template-previews.sh --matrix dev-scripts/template-preview-matrix.json

The README template collage is generated from the same composed previews:

dev-scripts/build-templates-showcase.sh --screenshot

Anti-slop detector

Fixture HTML and generated fixture previews must pass the deterministic detector:

node skills/visualize/scripts/detect.mjs --strict path/to/artifact.html

Rules across 6 categories — all mechanical patterns regex or node-html-parser can identify reliably, plus WCAG contrast computed via the vendored culori library. Run node skills/visualize/scripts/detect.mjs --list-rules for the authoritative current set; the categories below survive rule-set churn:

• fossil — lorem-ipsum, citation artifacts (turn0search0 / <!-- claude: / 【N†source】 / ASSISTANT:), AI-attribution disclaimers ("Generated by Claude / with AI assistance")
• slop — gradient text, dark glow (text-shadow with high blur + chroma), glassmorphism (backdrop-filter + translucent), emoji headings, monotonous spacing, bounce easing, side-tab, system-default fonts (when brand-aware)
• a11y — missing alt (including lazy alts like alt="image" / alt="DSC_0042"), missing/empty lang, empty links, WCAG-AA contrast, heading structure (missing h1, multiple h1, skipped levels)
• meta — missing title, missing favicon, missing OG / Twitter card, external script outside the library-policy allowlist
• perf — layout-thrash (transition on width/height/top/left, plus transition: all), img without width/height (CLS risk)
• diagram — semantic figure shape, node/edge/group integrity, delivered connector geometry, and unrendered diagram source

CI runs node detect.mjs --strict <file> against fixture HTML and generated fixture previews; any error-severity finding fails the build.

Rules deliberately NOT in detect.mjs — vocab-unbounded fossils (mock identity beyond the obvious / slop openers / sycophant footers / imperative-tricolon), brand-and-register-dependent slop (ai-color-palette / icon-tile-stack / center-everything / uppercase-body), and structural-pattern slop the detector can't distinguish from legitimate design (triple-feature-card / trust-signal slop / scroll-jacking / responsive overflow). Those live in the /visualize:review LLM-judge prompt in SKILL.md § "Review verb procedure" — the agent reads them when reviewing an artifact and applies judgment the detector can't.

The split is deliberate: mechanical patterns get detector rules (cheap, deterministic, CI-enforced); judgment-shaped patterns get prompt instructions (require register awareness, brand context, semantic understanding).

CLI

• Output: human-readable default; --json for NDJSON.
• --strict — exit 2 on any error finding.
• --skip slop/emoji-heading,a11y/missing-alt — comma-separated rule IDs to skip.
• --config .visualize-detect.json — config file (severity overrides + skip list).
• --brand DESIGN.md — explicit brand profile path (auto-loaded from any ancestor of the artifact otherwise).

Programmatic

import { detect } from './skills/visualize/scripts/detect.mjs';
const findings = await detect({ path: './artifact.html', skip: ['slop/emoji-heading'], brandProfile: { fonts: ['sohne'] } });

Vendored dependencies

detect.mjs imports two libraries from skills/visualize/scripts/vendor/: node-html-parser (real DOM walking) and culori (WCAG contrast). Both bundled inline (no npm install required after npx skills add display-dev/visualize). See skills/visualize/scripts/vendor/README.md for re-bundle instructions when upstream releases.

Library / CDN policy

Every template the skill emits is meant to be self-contained HTML — inlined CSS, no build step, no asset pipeline. Third-party libraries are the carve-out, and the policy is tight:

CDN allowlist (CI-enforced):

• cdn.jsdelivr.net/npm/chart.js@<version> — for Dashboard charts

Forbidden:

• Any <script src> reference outside the allowlist above. Adding a library requires updating dev-scripts/check-library-policy.mjs AND the policy appendix in the spec in the same change. CI runs node dev-scripts/check-library-policy.mjs --quiet and fails the build on violation.
• ECharts (too large; Chart.js covers current chart needs).
• jQuery / Lodash / utility libraries (templates don't need them; the agent writes the JS each template ships inline).

Syntax highlighting: templates that show code (tutorial, runbook, diff-review, slide-deck) use the agent-hand-classed + CSS tokens approach — no library. The agent adds <span class="kw"> / .str / .cmt etc. classes; --syntax-* CSS tokens style them per design system. This is brand-aware and zero-maintenance. If a future template's code volumes outgrow hand-classing, vendor a highlight.js subset (~30KB) inline.

Mermaid is an authoring tool, not a delivery dependency. Render Mermaid locally, normalize the result to the semantic inline-SVG contract in reference/diagram.md, and remove Mermaid source, runtime scripts, and network dependencies from the delivered artifact.

Releasing

SKILL_VERSION in skills/visualize/scripts/_common.sh requires a manual bump. Edit it in lockstep with every git tag so the client_source analytics attribution stays accurate — the value travels on X-Client-Source: visualize-skill@<version> on every request the skill makes.

For local testing without editing the file, set SKILL_VERSION_OVERRIDE in your environment.