@lovehlmmm/primekit 1.0.0

package/skills/preview/references/html-design-guidelines.md

@@ -0,0 +1,393 @@
+# HTML Design Guidelines
+
+Guidelines for generating distinctive, high-quality HTML pages. Read this before generating any HTML output.
+
+---
+
+## Anti-Slop: Forbidden Patterns
+
+These patterns are explicitly forbidden — they signal "AI-generated template" and undermine quality. Check every page against this list before delivering.
+
+### Typography — Forbidden Fonts as Primary `--font-body`
+
+- **Inter** — the single most overused AI default
+- **Roboto, Arial, Helvetica** — generic system fallbacks promoted to primary
+- **system-ui, sans-serif alone** — no character, no intent
+
+**Required:** Pick from the font pairings in `html-libraries.md`. Every generation should use a different pairing from the last.
+
+### Color Palette — Forbidden Accents
+
+- `#8b5cf6`, `#7c3aed`, `#a78bfa` — Tailwind's indigo/violet defaults
+- `#d946ef` — fuchsia
+- `#06b6d4` + `#d946ef` + `#f472b6` — the cyan + magenta + pink neon gradient combination
+- Any palette describable as "Tailwind defaults with purple/pink/cyan accents"
+
+**Forbidden color effects:**
+- Gradient text on headings (`background: linear-gradient(...); background-clip: text;`) — screams AI-generated
+- Animated glowing box-shadows (`@keyframes glow { box-shadow: 0 0 20px... }`) — always produces AI slop
+- Multiple overlapping radial glows in accent colors creating a "neon haze"
+- Pulsing/breathing effects on static content
+- Continuous animations that run after page load (except progress indicators)
+
+**Required accents (use these):**
+- Terracotta + sage (`#c2410c`, `#65a30d`) — warm, earthy
+- Teal + slate (`#0891b2`, `#0369a1`) — technical, precise
+- Rose + cranberry (`#be123c`, `#881337`) — editorial, refined
+- Amber + emerald (`#d97706`, `#059669`) — data-focused
+- Deep blue + gold (`#1e3a5f`, `#d4a73a`) — premium, sophisticated
+
+### Section Headers — Forbidden
+
+- Emoji icons in section headers (🏗️ ⚙️ 📁 💻 📅 🔗 ⚡ 🔧 📦 🚀, etc.)
+- Section headers that all use the same icon-in-rounded-box pattern
+
+**Required:** Use styled monospace labels with colored dot indicators (`.section-label` + `.ve-card__label` pattern), numbered badges, or asymmetric section dividers. If an icon is genuinely needed, use inline SVG matching the palette.
+
+### Layout — Forbidden
+
+- Perfectly centered everything with uniform padding
+- All cards styled identically with the same border-radius, shadow, and spacing
+- Every section getting equal visual treatment — no hero/primary vs. secondary distinction
+- Symmetric layouts where left and right halves mirror each other
+
+### Template Clichés — Forbidden
+
+- Three-dot window chrome (red/yellow/green dots) on code blocks
+- KPI cards where every metric has identical gradient text treatment
+- "Neon Dashboard" aesthetic
+- Gradient meshes with pink/purple/cyan blobs in the background
+
+### The Slop Test
+
+Before delivering, check: **Would a developer immediately think "AI generated this"?**
+
+Signs of slop:
+1. Inter or Roboto font with purple/violet gradient accents
+2. Every heading has `background-clip: text` gradient
+3. Emoji icons leading every section
+4. Glowing cards with animated shadows
+5. Cyan-magenta-pink color scheme on dark background
+6. Perfectly uniform card grid with no visual hierarchy
+7. Three-dot code block chrome
+
+If two or more are present: regenerate with Blueprint, Editorial, Paper/ink, or a specific IDE theme.
+
+---
+
+## Palette Cohesion Principles
+
+**Every generated page must feel like one intentional color story.** This is the single most important readability rule.
+
+1. **Background warmth must match accent warmth.** Terracotta accents need warm cream backgrounds (`#faf7f5`), not cool gray (`#f8f9fa`). Teal accents need cool-tinted backgrounds (`#f0fdfa`). Mixing warm accents on cool backgrounds (or vice versa) creates visual dissonance that makes pages feel generic.
+
+2. **Text-dim must belong to the same family.** On warm backgrounds, use warm grays (`#8a7e72`, `#a69889`). On cool backgrounds, use cool grays (`#5f8a85`, `#8b949e`). Never use GitHub-style `#6b7280` on warm cream.
+
+3. **Borders should be tinted, not neutral.** Use `rgba(0, 0, 0, 0.07)` or palette-tinted borders instead of flat `#e5e7eb`. Borders should be barely visible — felt, not seen.
+
+4. **Surface layers create depth without fighting.** Define `--surface`, `--surface2`, and `--surface-elevated` as gradations of the same hue, not different colors.
+
+5. **Extend every palette with semantic colors.** Every preset below should also define `--green`, `--red`, `--amber`, `--sage`, `--teal`, `--plum` (and their `*-dim` variants) that harmonize with the base palette. Richer semantic sets prevent monotony without clashing.
+
+---
+
+## 6 Curated Style Presets
+
+Pick one and commit. The constrained presets (Blueprint, Editorial, Paper/Ink, Terminal Mono) are safer — they have specific requirements that prevent defaulting to generic patterns.
+
+**IMPORTANT:** After choosing a preset, extend it with semantic colors (`--green`, `--red`, `--amber`, `--sage`, `--teal`, `--plum` + `*-dim` variants) that harmonize with the base palette. The default palette in `html-css-patterns.md` shows the full semantic structure — replicate that structure for whichever preset you choose.
+
+### Blueprint
+
+Technical drawing feel. Subtle grid background, deep slate/blue palette, monospace labels, precise borders.
+
+```css
+:root {
+  --font-body: 'DM Sans', system-ui, sans-serif;
+  --font-mono: 'Fira Code', 'SF Mono', monospace;
+  --bg: #0d1421;
+  --surface: #111d2e;
+  --surface-elevated: #162438;
+  --border: rgba(100, 160, 220, 0.12);
+  --border-bright: rgba(100, 160, 220, 0.22);
+  --text: #c8d8e8;
+  --text-dim: #607080;
+  --accent: #4a90d9;
+  --accent-dim: rgba(74, 144, 217, 0.1);
+}
+@media (prefers-color-scheme: light) {
+  :root {
+    --bg: #f0f4f8;
+    --surface: #ffffff;
+    --surface-elevated: #e8eef4;
+    --border: rgba(30, 60, 100, 0.1);
+    --text: #1a2a3a;
+    --text-dim: #5a7090;
+    --accent: #1a5fa8;
+    --accent-dim: rgba(26, 95, 168, 0.08);
+  }
+}
+```
+
+Background: faint dot grid (`background-image: radial-gradient(circle, var(--border) 1px, transparent 1px); background-size: 24px 24px`). Monospace labels throughout.
+
+### Editorial
+
+Serif headlines (Instrument Serif or Crimson Pro), generous whitespace, muted earth tones or deep navy + gold.
+
+```css
+:root {
+  --font-body: 'Instrument Serif', Georgia, serif;
+  --font-mono: 'JetBrains Mono', 'SF Mono', monospace;
+  --bg: #0f1729;
+  --surface: #162040;
+  --surface-elevated: #1d2b52;
+  --border: rgba(200, 180, 140, 0.08);
+  --text: #e8e4d8;
+  --text-dim: #9a9484;
+  --accent: #d4a73a;
+  --accent-dim: rgba(212, 167, 58, 0.1);
+}
+@media (prefers-color-scheme: light) {
+  :root {
+    --bg: #faf8f2;
+    --surface: #ffffff;
+    --surface-elevated: #f5f0e6;
+    --border: rgba(30, 30, 50, 0.08);
+    --text: #1a1814;
+    --text-dim: #7a7468;
+    --accent: #b8860b;
+    --accent-dim: rgba(184, 134, 11, 0.08);
+  }
+}
+```
+
+### Paper/Ink
+
+Warm cream `#faf7f5` background, terracotta/sage accents, informal feel.
+
+```css
+:root {
+  --font-body: 'Plus Jakarta Sans', system-ui, sans-serif;
+  --font-mono: 'Azeret Mono', 'SF Mono', monospace;
+  --bg: #faf6f0;
+  --surface: #ffffff;
+  --surface-elevated: #fffdf5;
+  --border: rgba(60, 40, 20, 0.08);
+  --text: #2c2a25;
+  --text-dim: #7c756a;
+  --accent: #c2410c;
+  --accent-dim: rgba(194, 65, 12, 0.08);
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #1c1916;
+    --surface: #262220;
+    --surface-elevated: #3a3430;
+    --border: rgba(200, 180, 160, 0.08);
+    --text: #f0e8dc;
+    --text-dim: #a09888;
+    --accent: #e85d2a;
+    --accent-dim: rgba(232, 93, 42, 0.1);
+  }
+}
+```
+
+### Terminal Mono
+
+Green/amber on near-black, monospace everything. Developer-native.
+
+```css
+:root {
+  --font-body: 'Geist Mono', 'SF Mono', Consolas, monospace;
+  --font-mono: 'Geist Mono', 'SF Mono', Consolas, monospace;
+  --bg: #0a0e14;
+  --surface: #12161e;
+  --surface-elevated: #222836;
+  --border: rgba(80, 250, 123, 0.06);
+  --text: #c8d6e5;
+  --text-dim: #5a6a7a;
+  --accent: #50fa7b;
+  --accent-dim: rgba(80, 250, 123, 0.08);
+}
+@media (prefers-color-scheme: light) {
+  :root {
+    --bg: #f4f6f8;
+    --surface: #ffffff;
+    --border: rgba(0, 80, 40, 0.08);
+    --text: #1a2332;
+    --text-dim: #5a6a7a;
+    --accent: #0d7a3e;
+    --accent-dim: rgba(13, 122, 62, 0.08);
+  }
+}
+```
+
+Background: faint dot grid. Everything monospace. CRT glow optional (CSS only, no animation).
+
+### Swiss Clean
+
+White, geometric sans, single bold accent, visible grid. Minimal and precise.
+
+```css
+:root {
+  --font-body: 'DM Sans', system-ui, sans-serif;
+  --font-mono: 'Fira Code', 'SF Mono', monospace;
+  --bg: #ffffff;
+  --surface: #f8f8f8;
+  --surface-elevated: #ffffff;
+  --border: rgba(0, 0, 0, 0.08);
+  --text: #111111;
+  --text-dim: #666666;
+  --accent: #0055ff;
+  --accent-dim: rgba(0, 85, 255, 0.06);
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #111111;
+    --surface: #1a1a1a;
+    --surface-elevated: #2a2a2a;
+    --border: rgba(255, 255, 255, 0.08);
+    --text: #f0f0f0;
+    --text-dim: #888888;
+    --accent: #3b82f6;
+    --accent-dim: rgba(59, 130, 246, 0.08);
+  }
+}
+```
+
+### Warm Signal
+
+Cream paper, bold sans, terracotta accents. Confident, modern. Same as Paper/Ink but bolder.
+
+Uses Plus Jakarta Sans + Azeret Mono, terracotta `#c2410c` accent. See Paper/Ink preset above — Warm Signal is the same palette with higher contrast headings and stronger section dividers.
+
+---
+
+## Typography Rules
+
+### Font Pairings (12 options — rotate, never repeat consecutively)
+
+| Body / Headings | Mono / Labels | Feel | Use for |
+|---|---|---|---|
+| DM Sans | Fira Code | Friendly, developer | Blueprint, technical docs |
+| Instrument Serif | JetBrains Mono | Editorial, refined | Plan reviews, decision logs |
+| IBM Plex Sans | IBM Plex Mono | Reliable, readable | Architecture diagrams |
+| Bricolage Grotesque | Fragment Mono | Bold, characterful | Data tables, dashboards |
+| Plus Jakarta Sans | Azeret Mono | Rounded, approachable | Status reports, audits |
+| Outfit | Space Mono | Clean geometric, modern | Flowcharts, pipelines |
+| Sora | IBM Plex Mono | Technical, precise | ER diagrams, schemas |
+| Crimson Pro | Noto Sans Mono | Scholarly, serious | RFC reviews, specs |
+| Fraunces | Source Code Pro | Warm, distinctive | Project recaps |
+| Geist | Geist Mono | Vercel-inspired, sharp | Modern API docs |
+| Red Hat Display | Red Hat Mono | Cohesive family | System overviews |
+| Libre Franklin | Inconsolata | Classic, reliable | Data-dense tables |
+
+The first 5 pairings are recommended for most use cases.
+
+### Load via Google Fonts
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=Fira+Code:wght@400;500&display=swap" rel="stylesheet">
+```
+
+Always use `display=swap` for fast rendering. Include system font fallback in `font-family` stack.
+
+### Typography by Content Voice
+
+For prose-heavy pages, match fonts to content voice:
+
+| Voice | Fonts | Best For |
+|-------|-------|----------|
+| Literary / Thoughtful | Literata, Lora, Newsreader, Merriweather | Essays, personal posts, long-form |
+| Technical / Precise | IBM Plex Sans + Mono, Geist + Geist Mono | Documentation, READMEs, API refs |
+| Bold / Contemporary | Bricolage Grotesque, Space Grotesk, DM Sans | Product pages, announcements |
+| Minimal / Focused | Source Serif 4 + Source Sans 3, Karla + Inconsolata | Tutorials, focused reading |
+
+---
+
+## Quality Checklist
+
+Before delivering any HTML page:
+
+- **Squint test**: Blur your eyes. Can you still perceive hierarchy? Are sections visually distinct?
+- **Swap test**: Would replacing fonts and colors with a generic dark theme make this indistinguishable? If yes, push the aesthetic further.
+- **Theme toggle (MANDATORY)**: Toggle button MUST be present (first child of `<body>`). Switch between light and dark using the button. Both themes should look intentional, not broken. See `html-css-patterns.md` → "Theme Toggle Button".
+- **Information completeness**: Does the page actually convey what was asked? Pretty but incomplete is a failure.
+- **No overflow**: Resize the browser. No content should clip or escape its container. Every grid/flex child needs `min-width: 0`. Side-by-side panels need `overflow-wrap: break-word`.
+- **Mermaid zoom controls**: Every `.mermaid-wrap` must have zoom controls (+/−/reset/expand), Ctrl/Cmd+scroll zoom, click-and-drag panning, and click-to-expand. See `html-css-patterns.md`.
+- **File opens cleanly**: No console errors, no broken font loads, no layout shifts.
+
+---
+
+## Depth Tier System
+
+Vary card depth to signal importance. Hero sections dominate; reference sections stay compact.
+
+```css
+/* Default — flat, no shadow */
+.ve-card {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  padding: 16px 20px;
+}
+
+/* Elevated — KPIs, key sections */
+.ve-card--elevated {
+  background: var(--surface-elevated);
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08), 0 1px 2px rgba(0, 0, 0, 0.04);
+}
+
+/* Recessed — code blocks, secondary content */
+.ve-card--recessed {
+  background: color-mix(in srgb, var(--bg) 70%, var(--surface) 30%);
+  box-shadow: inset 0 1px 3px rgba(0, 0, 0, 0.06);
+}
+
+/* Hero — executive summaries, focal elements */
+.ve-card--hero {
+  background: color-mix(in srgb, var(--surface) 92%, var(--accent) 8%);
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.08), 0 1px 3px rgba(0, 0, 0, 0.04);
+  border-color: color-mix(in srgb, var(--border) 50%, var(--accent) 50%);
+}
+```
+
+Rule: Don't make everything elevated — when everything pops, nothing does.
+
+---
+
+## Content-Type Routing
+
+When deciding how to render content:
+
+| Content type | Approach | Why |
+|---|---|---|
+| Architecture (text-heavy) | CSS Grid cards + flow arrows | Rich card content needs CSS control |
+| Architecture (topology-focused) | **Mermaid** | Visible connections need automatic edge routing |
+| Flowchart / pipeline | **Mermaid** | Automatic node positioning |
+| Sequence diagram | **Mermaid** | Lifelines need automatic layout |
+| Data flow | **Mermaid** with edge labels | Connections need auto-routing |
+| ER / schema diagram | **Mermaid** | Relationship lines between entities |
+| State machine | **Mermaid** | State transitions with labeled edges |
+| Mind map | **Mermaid** | Hierarchical branching |
+| Class diagram | **Mermaid** | Inheritance lines with auto-routing |
+| C4 architecture | **Mermaid** `graph TD` + `subgraph` | Native C4 hardcodes its own styles |
+| Data table | HTML `<table>` | Semantic markup, accessibility, copy-paste |
+| Timeline | CSS (central line + cards) | Simple linear layout |
+| Dashboard | CSS Grid + Chart.js | Card grid with embedded charts |
+| Simple A→B→C flows in slides | CSS Pipeline cards | Mermaid renders too small for simple linear flows |
+
+---
+
+## AI Image Generation
+
+If `/pk:ai-multimodal` skill is available and image generation is appropriate, it can be used for hero banners, conceptual illustrations, and decorative accents that establish the page's visual tone.
+
+**When to use:** Hero banners, conceptual illustrations for abstract systems, educational diagrams benefiting from artistic rendering, decorative accents reinforcing the aesthetic.
+
+**When to skip:** Anything Mermaid or CSS handles well. Generic decoration that doesn't convey meaning. Data-heavy pages where images would distract. Always degrade gracefully — the page should stand on its own with CSS and typography alone.
+
+For `--slides` presentation-grade output, consider invoking `/pk:ui-ux-pro-max` for richer style selection and distinctive font/palette pairing.

package/skills/preview/references/html-diagram-design.md

@@ -0,0 +1,156 @@
+# diagram-design — Editorial visual layer
+
+Zero-JS, self-contained HTML+SVG diagrams in an opinionated editorial style. Author templates by hand or via LLM; validate with the pinned Python scripts. Complements Mermaid (auto-layout) and AntV Infographic (KPI panels); does not replace either.
+
+**License:** MIT · **Pinned upstream:** `cathrynlavery/diagram-design@09df49d8d1a1c7fb2efdfcdc7a2a0713534350a6` · **Deps at runtime:** none
+
+## When to use
+
+Use for architecture, semantic patterns, ordered process, timeline, quadrant, radar, layers, medallion, DP integration, DP security matrix — anywhere the layout is intentional and the frame reads as editorial. Prefer Mermaid when node positioning should be automatic; prefer AntV when the panel is data-heavy KPI tiling.
+
+## Type index (22 layout types + 4 primitives)
+
+Load a per-type file lazily only when the skill routes to that type. Each per-type file gives viewBox spec, connector patterns, and one minimal SVG example. Ship-critical types have local copies under `html-diagram-design-types/`; the rest follow upstream at the pinned SHA.
+
+| Type | Local | Upstream reference path |
+|---|:---:|---|
+| architecture | ✓ | `skills/diagram-design/references/type-architecture.md` |
+| quadrant | ✓ | `skills/diagram-design/references/type-quadrant.md` |
+| timeline (gantt) | ✓ | `skills/diagram-design/references/type-gantt.md` |
+| flowchart | | `.../type-flowchart.md` |
+| sequence | | `.../type-sequence.md` |
+| dp-security-matrix | | `.../type-dp-security-matrix.md` |
+| dp-integration | | `.../type-dp-integration.md` |
+| medallion | | `.../type-medallion.md` |
+| high-level | | `.../type-high-level.md` |
+| process | | `.../type-process.md` |
+| data-flow | | `.../type-data-flow.md` |
+| radar | | `.../type-radar.md` |
+| loop | | `.../type-loop.md` |
+| nested | | `.../type-nested.md` |
+| org-chart | | `.../type-org-chart.md` |
+| layers | | `.../type-layers.md` |
+| pyramid | | `.../type-pyramid.md` |
+| er | | `.../type-er.md` |
+| bar / line / scatter | | `.../type-bar.md`, `type-line.md`, `type-scatter.md` (prefer Chart.js for these) |
+| it-state | | `.../type-it-state.md` |
+
+Primitives (`primitive-annotation.md`, `primitive-icons.md`, `primitive-sketchy.md`, `primitive-terminal.md`) apply across types and are always upstream-only.
+
+## Editorial design tokens (override for PrimeKit)
+
+Upstream defaults ship atomic-tangerine `#eb6c36` as accent. PrimeKit overrides to the wine-red editorial contract:
+
+```css
+:root {
+  --paper:  #faf7f2;                                            /* warm cream */
+  --ink:    #0f0e0d;                                            /* near-black */
+  --accent: #b8232c;                                            /* wine-red — override, was #eb6c36 */
+  --taupe:  #8a7f74;                                            /* secondary text */
+  --rule:   #d8d1c4;                                            /* hairline dividers */
+  --moss:   #4a6b3f;                                            /* success/complete */
+  --ochre:  #c89a3c;                                            /* warning/P1 */
+  --font-serif: "Instrument Serif", "Iowan Old Style", "Palatino Linotype", Palatino, Georgia, serif;
+  --font-sans:  Geist, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  --font-mono:  "Geist Mono", "SF Mono", Menlo, Consolas, monospace;
+}
+
+:root:not([data-theme="light"]) {
+  @media (prefers-color-scheme: dark) {
+    --paper: #12100e; --ink: #f2ece0; --accent: #e14a53;
+    --taupe: #a89e94; --rule: #2f2a24;
+  }
+}
+:root[data-theme="dark"] {
+  --paper: #12100e; --ink: #f2ece0; --accent: #e14a53;
+  --taupe: #a89e94; --rule: #2f2a24;
+}
+```
+
+Font pairing is #14 in `html-libraries.md` ("Editorial serif — Instrument Serif + Geist + Geist Mono").
+
+## 6 connector rules (verbatim from upstream style-guide)
+
+1. **Horizontal or vertical only**; diagonals are reserved for `primitive-sketchy` explicit hand-drawn types.
+2. **Right-angle bends** land on rule grid coordinates; never rounded.
+3. **Arrowheads** are the same stroke as the line, filled black at ink color; solid = primary flow, dashed = optional / async.
+4. **Line weight** matches text weight of its endpoint labels; heavier lines belong on the critical path only.
+5. **Junctions are dots**, not crossings — where two connectors meet, drop a filled circle at ink; where they only cross, one uses a small break to visually pass under.
+6. **Never label mid-arrow**; place the label above the horizontal run or beside the vertical run, aligned to the same baseline.
+
+Every generated SVG must satisfy these. `verify-geometry.py` (see below) catches most violations.
+
+## Motion contract
+
+Three motion tiers (default is `none`); set via `visual.diagram_design.motion` in `ckprefs`:
+
+- `none` — no motion at all; static SVG. **Default for docs / plans.**
+- `reveal` — staggered fade-in on first paint via CSS `animation-delay`, respects `prefers-reduced-motion`.
+- `step` — user-driven step-through with `<button>` cycling `data-active-step`.
+- `loop` — subtle repeating animation for background / status indicators.
+
+`verify-motion.py` asserts the class markers match the declared tier and that `prefers-reduced-motion` rules exist for anything non-`none`.
+
+## Template skeleton (minimum viable file)
+
+```html
+<!doctype html>
+<html lang="en" data-diagram-type="architecture" data-motion="none">
+<head>
+<meta charset="utf-8">
+<title>[Diagram title]</title>
+<style>
+  :root { /* tokens from section above */ }
+  body { margin: 0; background: var(--paper); color: var(--ink); font-family: var(--font-sans); }
+  .frame { padding: 32px; }
+  .frame svg { display: block; width: 100%; max-width: 1080px; margin: 0 auto; }
+  text.dd-label { font-size: 12px; fill: var(--ink); }
+  text.dd-caption { font-family: var(--font-mono); font-size: 10px; letter-spacing: 0.14em;
+                    text-transform: uppercase; fill: var(--taupe); }
+  .dd-ink    { stroke: var(--ink);    fill: none; stroke-width: 1.4; }
+  .dd-accent { stroke: var(--accent); fill: none; stroke-width: 1.6; }
+  .dd-paper2 { fill: color-mix(in oklab, var(--paper) 88%, var(--ink) 12%); }
+  @media (prefers-reduced-motion: reduce) { * { animation: none !important; } }
+</style>
+</head>
+<body>
+<div class="frame">
+  <svg viewBox="0 0 1080 600" role="img" aria-label="[Alt text]">
+    <!-- Per-type content per html-diagram-design-types/type-<name>.md -->
+  </svg>
+</div>
+</body>
+</html>
+```
+
+The 5 style hooks (`dd-ink`, `dd-accent`, `dd-paper2`, `dd-label`, `dd-caption`) are the entire style contract — every per-type file uses only these.
+
+## Validators (advisory in v1)
+
+Scripts vendored under `references/vendor/diagram-design-scripts/` at pinned SHA `09df49d8d1a1c7fb2efdfcdc7a2a0713534350a6`. **All three are advisory-only** — they warn on stderr and return the artifact anyway. Skill guides never gate rendering on validator exit code in v1.
+
+```bash
+python3 references/vendor/diagram-design-scripts/self_check.py       out.html
+python3 references/vendor/diagram-design-scripts/verify-geometry.py  out.html
+python3 references/vendor/diagram-design-scripts/verify-motion.py    out.html
+```
+
+Graceful skip: the vendor directory ships a `run-validators.sh` that detects `python3`; if absent it prints one line (`[diagram-design] python3 not found, skipping validators`) and exits 0. Skill guides call the shell wrapper, not `python3` directly, so users without Python are never blocked.
+
+## Fallback rules
+
+1. If a per-type file is not present locally and the artifact must be air-tight, either (a) hand-author the SVG from the upstream reference, or (b) fall back to Mermaid for that panel and note the substitution in the artifact colophon.
+2. If `verify-geometry.py` fails after 1 retry with a corrective prompt, drop to Mermaid.
+3. Never crash the artifact on validator failure — validators are advisory in v1.
+
+## Do not
+
+- Do not install the upstream Claude Code plugin (`/plugin marketplace add cathrynlavery/diagram-design`). PrimeKit vendors the references to avoid dual-install routing conflicts. If the plugin is already installed, defer to its routing and skip the PrimeKit variant.
+- Do not import `mermaid_extract.py` or `drawio_extract.py` unless the artifact origin is a `.mmd` or `.drawio` file — those are conversion tools, not generators.
+- Do not use `primitive-sketchy` on plan/retro/CTI artifacts — reserved for `pk:brainstorm --html` and `pk:advise --html` where hand-drawn intent is on-brand.
+
+## References
+
+- Upstream repo: `github.com/cathrynlavery/diagram-design` (MIT)
+- Pinned commit: `09df49d8d1a1c7fb2efdfcdc7a2a0713534350a6`
+- Editorial contract in `html-libraries.md` "Editorial visual layer" section (font pairing #14)