Visualize

visualize — beautiful, on-brand HTML artifacts

Generate self-contained HTML artifacts composed from templates/*/template.md contracts against the resolved visual context. The project's DESIGN.md, PRODUCT.md, and sidecar tokens.css provide the default; artifact themes below allow reference systems within the user's approved scope. Shared pattern recipes live in patterns/ and are read only when the selected template and user ask make them relevant; shell mechanics are loaded automatically only when a template declares shell: <slug>.

Design judgment

Find the artifact's organizing idea before choosing its visual treatment. Look for a relationship, contrast, sequence, decision, or object in the source that the composition itself can make easier to understand. Use that idea to shape the opening, section rhythm, and any explanatory primitive. When the source has no useful spatial or structural idea, prefer a restrained reading experience over manufacturing one.

Artifact mode describes how the reader consumes the information, not the aesthetic family it must use. A document can use product-native, application-like, spatial, editorial, or technical-drawing grammar when that grammar serves the source, reader, and brand. Do not equate document with editorial publishing, or canvas with diagram chrome.

Visual conviction can come from composition, typography, density, spatial rhythm, imagery, interaction, or color. Do not add hues, decoration, or components merely to make an artifact feel designed. A restrained palette can carry a strong point of view when another dimension does the expressive work.

Before responding to feedback, compare the observation with the artifact's reader, purpose, source, and approved brief where one exists. Distinguish an implementation defect, a design that fails its existing requirements, and evidence that a requirement or assumption has changed. The current composition is a solution, not a constraint.

Make authorized corrections within the existing brief directly. If feedback implies a change to established requirements that the user has not already approved, explain the proposed change and obtain agreement before editing. When several structural or visual directions remain plausible, recommend explore artifact within its supported scope. When the direction is established, use the ordinary creation or refinement workflow. Follow that workflow's approval requirements; a small correction does not need a new exploration.

Evaluate proposed fixes together against the reader's task. Do not turn every critique finding into an addition or treat a small diff as evidence that the direction is sound. Preserve decision-relevant deferred observations in existing review or task notes.

Commands

{{command_prefix}}visualize invokes the skill. The argument tells the agent what to do.

Default (no command, or the first argument is a topic): {{command_prefix}}visualize <topic-or-path> creates a new artifact. The agent picks a template from intent across all of templates/, composes against the resolved project or artifact-theme context, writes self-contained HTML. The flow is gated: preflight checklist + shape-gate before code, no self-authored briefs. See reference/create.md.

Named commands:

Invocation forms: {{command_prefix}}visualize teach, {{command_prefix}}visualize explore artifact ./report.html, {{command_prefix}}visualize polish ./report.html, {{command_prefix}}visualize publish ./diagram.html. On hosts without a slash-command form, the skill loads on intent-match from the description above; natural-language is the primary entry there.

Routing rules

1. No argument: render the Commands table above as the user-facing menu, grouped by category. Ask what they'd like to do.
2. First word matches a command: load its reference file before doing anything else. Non-negotiable — the table row + this section is insufficient; the procedure lives in the reference. Everything after the command name is the target.
3. Natural-language intent: requests to compare design alternatives load reference/explore.md; capturing or reconciling project identity loads reference/teach.md. Otherwise load reference/create.md for creation or an explicitly requested restyling of an existing artifact. A named theme follows Artifact themes below; it does not require an exploration round.
4. Relationship-diagram route during creation: when preflight first identifies a likely relationship diagram, load reference/diagram.md and the one tentative non-spatial type reference needed for that figure before presenting the shape gate. For multi-figure artifacts, load one reference for each distinct tentative family: reference/diagram-flow.md, reference/diagram-system.md, reference/diagram-sequence.md, reference/diagram-state.md, or reference/diagram-hierarchy.md. Spatial figures use reference/diagram.md alone. If approval changes a figure's type, load the replacement reference before authoring; do not load unrelated families.
5. Generated-image route during creation: when the approved shape requires generated bitmap imagery, load reference/image-generation.md before selecting or invoking a route. Use only the active callable inventory or an explicitly selected API adapter. Never infer a route from a key, executable, mount, or model claim, and never retry or fall back after an ambiguous attempt.
6. Explore scope: explore always loads reference/explore.md, which distinguishes artifact treatment from project-system creation or explicit replacement. Comparing treatments for one artifact does not require creating a project design system first. System Explore uses its opt-in authority classification instead of applying the render fallback as an incumbent identity.

Hand-off output shape

After a refine verb (simplify / bolder / quieter / animate) finishes its run, summarise to the user in plain markdown. Don't render the summary as a fenced code block — it's conversational output, not machine-readable. Vary phrasing across runs; pick wording per context (engineer reading detector output vs. designer iterating on a brand brief). polish has its own output shape — see reference/polish.md.

Every refine run's summary covers four facts:

• Which verb ran, against which artifact.
• What the verb actually did. Pull the verb-specific content from the per-verb reference's "what to surface" list (focal moment, cuts + audit trail, strategy, what stayed, hero moment, reduced-motion handling — depends on the verb).
• Diff size as a percent of the artifact.
• Which next action makes sense, if any. Polish is the default next step from a successful refine run.

Variant rules (behaviour, not surface text):

• Context source note. If the run cannot use a persisted DESIGN.md / PRODUCT.md, mention once which fallback source anchored the work: project instructions, README/docs, generated seed, or Clean defaults. Also nudge the user to run {{command_prefix}}visualize teach so that fallback can become a real brand profile. Clean defaults are the last resort after the Brand profile rules below find no usable project guidance.
• Diff exceeded the 40% guard. Stop refinement and report the affected scope. Apply Design judgment to recommend exploration when the structural direction remains unresolved, or a fresh creation pass when it is established. Do not continue into polish.
• Verb shouldn't have run (Absolute bans present, no decoration to remove, no focal moment, etc.). Skip the standard run summary entirely. Surface a short refusal that names the reason and routes to the right alternative verb. Each per-verb reference's "When <verb> is the right verb (and when it isn't)" section enumerates the verb's specific refusal conditions.

Tone is conversational. Lead with what changed, not with a banner. Don't capitalise words for emphasis. Don't print a <Verb> pass complete · header — the summary's content is the proof of completion.

For animate specifically: when the brand declares motion: none, a fifth variant applies — see reference/animate.md.

Absolute bans

Match-and-refuse. Apply on every command and the default creation flow. These ban specific patterns — not aesthetics, not registers. A brand can declare a font, a hue, or a layout that looks unusual; it cannot redeem any of these patterns by declaring them as identity. An explicit .visualize-detect.json skip can waive only a detector-backed ban with a concrete rule ID; it is project policy, not runtime brand suppression, and cannot waive a Layer-2 ban.

BAN 1 — Gradient text on metrics or headings
  PATTERN:   background-clip: text + gradient background on <h*>, [class*="metric"], [class*="kpi"]
  INCLUDES:  -webkit-background-clip: text; CSS `background-image: linear-gradient(…)` + `color: transparent`
  WHY:       AI-essay register tell; reads as 2023-template "make the number pop"
  REWRITE:   Solid `--primary` (or `--foreground`) at one weight up; emphasis through weight + size, not gradient

BAN 2 — Side-stripe callout (border-left as accent)
  PATTERN:   `.callout`, `.tldr`, `.note`, `.tip` with border-left ≥ 3px in --primary / --warning / --destructive
  INCLUDES:  border-inline-start, border-l-4 utility class, ::before pseudo with positioned bar
  WHY:       Notion / Confluence template tell; reads as productivity-app default
  REWRITE:   Full thin border (1px var(--border)), background tint at 4–8% chroma, or no chrome — just a label heading

BAN 3 — Triple-feature-card grid
  PATTERN:   3-column grid of <h3>adjective + noun</h3> + one paragraph + one icon each
  INCLUDES:  4-column variants, "Why us" sections with identical card-icon-heading-blurb shape
  WHY:       AI-landing canonical pattern; the surest "AI generated this" tell on the visualize corpus
  REWRITE:   Asymmetric — one hero claim with two supporting facts, OR a numbered list with body prose, OR a single comparison table

BAN 4 — Hero-metric template
  PATTERN:   Centered <h1 class="…huge…">N×</h1> + <p class="…small…">supporting label</p> + 3 stat tiles below
  INCLUDES:  "10× faster", "99.9% uptime", "1M requests/day" hero blocks with the same shape
  WHY:       SaaS-landing cliché; the most-copied AI-marketing-page shape in 2024-2026
  REWRITE:   Specific claim in body prose with the number inline; data tiles only when the artifact is actually a dashboard

BAN 5 — Icon-tile section markers
  PATTERN:   Every <h2> preceded by a rounded-square tile carrying a Lucide / Heroicons / Phosphor glyph
  INCLUDES:  Circle-icon variants, icon-on-coloured-pill variants, gradient-icon-tile variants
  WHY:       AI section-marker tell; reads as "every section needs visual chrome"
  REWRITE:   Heading alone, or heading + small accent rule above, or numbered sections — no per-heading iconography

BAN 6 — Imperative tricolon
  PATTERN:   Three short imperative sentences ending in periods, in the same paragraph or hero
  INCLUDES:  "Ship faster. Build smarter. Scale forever." / "Move fast. Stay safe. Be bold." (any topic)
  WHY:       AI-copywriting cliché — the structure is identical across thousands of generated landing pages
  REWRITE:   One specific claim with the verb in the right tense, OR a sentence that names the actor and the action

BAN 7 — Sycophant / AI-attribution footer
  PATTERN:   "I hope you find this useful", "Let me know if you have questions", "Best, Claude", "Generated by AI", "As an AI…"
  INCLUDES:  Footer-line variants, comment-line variants in the HTML source
  WHY:       The artifact is the work; the model is invisible. Sycophant footers contaminate the artifact register
  REWRITE:   No footer of this shape. A real footer carries metadata (date, version, source-of-truth link) or is absent

If you're about to author one of these patterns, stop and rewrite the element with the alternative. The list is shared across creation, every Refine verb, and polish.

Model-specific operating rules

These are not brand aesthetics; they are observed model reflexes with required corrective behavior. Apply them after the universal bans, especially during no-brand greenfield creation.

Codex-specific rules:

• Border plus big shadow: avoid pairing a 1px border with a large fuzzy drop shadow on the same card or button. Choose a crisp edge or a small elevation cue.
• Over-rounded containers: ordinary cards, sections, inputs, and panels should usually stay at 12-16px radius. Larger radii need an explicit brand reason.
• Decorative stripe backgrounds: do not use repeating-linear-gradient(...) as body or section filler. Use an intentional texture/rule system, or leave the background plain.
• Crude SVG fallback: do not draw rough SVG scenes because no real asset is available. Use generated bitmap imagery, a geometric diagram, or no illustration.
• Compressed display type: keep display heading letter-spacing ≥ -0.04em and clamp max ≤ 6rem unless the template is a slide/poster register that explicitly needs larger type.
• Meta-contrast copy: avoid "X theater", "actually X", and "not just X, it's Y" framing. Say what the artifact literally does.
• Color judgment: use reference/color.md to assess character, relationships, roles, distribution, and actual pairings. No hue, hue combination, neutral tint, or accent count is a universal taste gate. Preserve approved identity and explicit artifact exceptions.
• Palette as a substitute for composition: assign semantic color roles in the shape gate and use them consistently, but do not add accent tracks merely to manufacture visual interest. Neutral surfaces plus one accent are valid when composition, type, density, imagery, or interaction carries the point of view. Revise when the opening has no expressive dimension, not when it has too few hues.

Gemini-specific guard:

• Do not animate <img> elements on hover. If a card needs hover feedback, animate the card's border, background, or action affordance instead.

Metadata / TOC guard: static document context needs explicit labels, not anonymous rounded chips. In document mode, keep metadata close to the title/thesis inside the reading flow; a right rail, split-cover facts column, or standalone metadata panel usually turns context into competing chrome. TOC rails are allowed for genuinely long documents, but they should support navigation rather than dominate the opening. Mobile TOCs must remain navigable lists or deliberate grids, never free-wrapping word clouds. Read patterns/metadata.md or patterns/toc.md when those structures are part of creation.

Table guard: tables are reading instruments, not hero sections. Keep caption, header, body, row-key, and numeric roles distinct; scope monospace to fixed-width values. Read patterns/table.md when the artifact carries dense comparison or evidence.

Interactive-state route: when creation includes functional controls or changes state in place, read patterns/interactive-states.md.

AI slop test (two altitudes)

Run both. The second catches what the first misses.

First-order: if someone could guess the template + palette from the topic alone, you've hit the first training-data reflex. Topic stereotypes are prompts to inspect the brief, not color prohibitions: red, purple gradients, or navy-and-gold can fit a specific artifact. Rework unsupported defaults, not approved identity.

Second-order: if someone could guess the aesthetic family from topic-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic," "fintech that's not navy-and-gold → terminal-native dark mode"), the second-tier reflex isn't avoided. Currently-saturated families to watch for: editorial-Tufte clone (cream + Georgia + side-margin notes when the topic isn't editorial), brutalist-terminal clone (mono + grid + heavy borders when the topic isn't dev-tool), Swiss-poster clone (uppercase + grotesk + grid when the topic isn't presentation). Rework until both altitudes return "no, you couldn't have guessed."