@lovehlmmm/primekit 1.0.0

package/skills/diagram/assets/tokens.css

@@ -0,0 +1,116 @@
+/*
+ * ak:diagram design tokens
+ * Editorial contract: 1 accent color, restrained palette, density 4/10.
+ * Every template imports this file; do not fork per-type.
+ */
+
+:root {
+  /* Neutrals — 4-step scale */
+  --ak-diag-ink: #0f172a;
+  --ak-diag-ink-muted: #475569;
+  --ak-diag-ink-subtle: #94a3b8;
+  --ak-diag-paper: #ffffff;
+  --ak-diag-paper-soft: #f8fafc;
+  --ak-diag-rule: #e2e8f0;
+
+  /* Accent — reserved for 1–2 focal points per diagram */
+  --ak-diag-accent: #2563eb;
+  --ak-diag-accent-soft: #dbeafe;
+  --ak-diag-accent-ink: #1e40af;
+
+  /* Semantic — sparse use only */
+  --ak-diag-ok: #059669;
+  --ak-diag-warn: #d97706;
+  --ak-diag-risk: #dc2626;
+
+  /* Type scale */
+  --ak-diag-font: -apple-system, BlinkMacSystemFont, "Segoe UI", "Inter",
+    Roboto, "Helvetica Neue", Arial, sans-serif;
+  --ak-diag-font-mono: ui-monospace, "SF Mono", "Cascadia Mono", "Roboto Mono",
+    Menlo, Consolas, monospace;
+  --ak-diag-size-xs: 11px;
+  --ak-diag-size-sm: 13px;
+  --ak-diag-size-base: 15px;
+  --ak-diag-size-lg: 18px;
+  --ak-diag-size-xl: 24px;
+  --ak-diag-size-2xl: 32px;
+
+  /* Spacing */
+  --ak-diag-space-1: 4px;
+  --ak-diag-space-2: 8px;
+  --ak-diag-space-3: 12px;
+  --ak-diag-space-4: 16px;
+  --ak-diag-space-6: 24px;
+  --ak-diag-space-8: 32px;
+  --ak-diag-space-12: 48px;
+  --ak-diag-space-16: 64px;
+
+  /* Stroke */
+  --ak-diag-stroke-hair: 1px;
+  --ak-diag-stroke-line: 1.5px;
+  --ak-diag-stroke-bold: 2.5px;
+
+  /* Radius */
+  --ak-diag-radius-none: 0;
+  --ak-diag-radius-sm: 2px;
+  --ak-diag-radius-md: 6px;
+}
+
+[data-theme="dark"] {
+  --ak-diag-ink: #f1f5f9;
+  --ak-diag-ink-muted: #94a3b8;
+  --ak-diag-ink-subtle: #64748b;
+  --ak-diag-paper: #0b1120;
+  --ak-diag-paper-soft: #111827;
+  --ak-diag-rule: #1e293b;
+  --ak-diag-accent: #60a5fa;
+  --ak-diag-accent-soft: #172554;
+  --ak-diag-accent-ink: #bfdbfe;
+}
+
+/* Base surface */
+.ak-diag {
+  font-family: var(--ak-diag-font);
+  font-size: var(--ak-diag-size-base);
+  color: var(--ak-diag-ink);
+  background: var(--ak-diag-paper);
+  line-height: 1.5;
+  padding: var(--ak-diag-space-8);
+}
+
+/* Editorial frame chrome */
+.ak-diag__title {
+  font-size: var(--ak-diag-size-xl);
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  margin: 0 0 var(--ak-diag-space-2);
+}
+
+.ak-diag__caption {
+  font-size: var(--ak-diag-size-sm);
+  color: var(--ak-diag-ink-muted);
+  margin: 0 0 var(--ak-diag-space-6);
+  max-width: 60ch;
+}
+
+.ak-diag__footnote {
+  font-size: var(--ak-diag-size-xs);
+  color: var(--ak-diag-ink-subtle);
+  border-top: var(--ak-diag-stroke-hair) solid var(--ak-diag-rule);
+  padding-top: var(--ak-diag-space-3);
+  margin-top: var(--ak-diag-space-8);
+}
+
+/* Focal-point utility — apply to the 1–2 elements the reader should notice first */
+.ak-diag__focal {
+  color: var(--ak-diag-accent-ink);
+  border-color: var(--ak-diag-accent);
+}
+
+/* Reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  .ak-diag * {
+    animation: none !important;
+    transition: none !important;
+  }
+}

package/skills/diagram/references/animation-effects.md

@@ -0,0 +1,142 @@
+# pk:diagram — animation effects catalog
+
+All eight effects are pure CSS living in `assets/connector-effects.css`.
+Apply via `data-fx="<name>"` on any SVG `<path>` (or on an `<svg>` for
+container-scope). No JS runtime, no external animation library.
+
+CSS custom properties tune each effect. Set them inline
+(`style="--primekit-fx-speed: 3s"`) or in a scoped stylesheet.
+
+Reduced-motion is respected globally — every keyframed effect freezes
+under `@media (prefers-reduced-motion: reduce)`.
+
+## Effect reference
+
+### marching-ants — `data-fx="marching-ants"`
+Dashed stroke slides continuously along the path. Classic "flowing"
+connector.
+
+| CSS var | Default | Meaning |
+|---------|---------|---------|
+| `--primekit-fx-dash` | `10 8` | dasharray length pair |
+| `--primekit-fx-speed` | `2.4s` | full cycle duration |
+
+Best on: architecture connectors, data-flow arrows.
+
+---
+
+### comet — `data-fx="comet"`
+A single bright dash-segment travels the length of the path, leaving
+a faint trail (opacity-tapered stroke).
+
+| CSS var | Default | Meaning |
+|---------|---------|---------|
+| `--primekit-fx-length` | `28` | segment length (path units) |
+| `--primekit-fx-speed` | `3.2s` | traversal duration |
+| `--primekit-fx-color` | `var(--primekit-diag-accent)` | comet head color |
+
+Best on: focal-point flows, "this is the important edge".
+
+---
+
+### wave — `data-fx="wave"`
+Stroke width breathes with a sine wave; effect stays in place, only
+thickness modulates.
+
+| CSS var | Default | Meaning |
+|---------|---------|---------|
+| `--primekit-fx-min` | `1.2px` | minimum stroke width |
+| `--primekit-fx-max` | `3.4px` | maximum stroke width |
+| `--primekit-fx-speed` | `2.0s` | full wave cycle |
+
+Best on: async / event-driven links.
+
+---
+
+### morse — `data-fx="morse"`
+Long-short dot/dash pattern travels along the path.
+
+| CSS var | Default | Meaning |
+|---------|---------|---------|
+| `--primekit-fx-dash` | `12 6 3 6` | Morse dasharray |
+| `--primekit-fx-speed` | `3.0s` | cycle |
+
+Best on: intermittent / batched flows.
+
+---
+
+### glow — `data-fx="glow"`
+Drop-shadow pulses on the stroke. No geometric motion — purely a
+soft halo.
+
+| CSS var | Default | Meaning |
+|---------|---------|---------|
+| `--primekit-fx-glow` | `var(--primekit-diag-accent)` | glow color |
+| `--primekit-fx-blur-max` | `10px` | peak blur radius |
+| `--primekit-fx-speed` | `2.4s` | pulse cycle |
+
+Best on: alert / anomaly connectors.
+
+---
+
+### silhouette — `data-fx="silhouette"`
+A tiny SVG shape (default: filled circle sibling) rides the path
+via `offset-path: path(...)`. Requires the shape to declare
+`--primekit-fx-path` matching the parent stroke's `d`.
+
+| CSS var | Default | Meaning |
+|---------|---------|---------|
+| `--primekit-fx-speed` | `3.6s` | traversal cycle |
+| `--primekit-fx-shape-size` | `10px` | rider dimensions |
+| `--primekit-fx-path` | *(required)* | path spec for offset-path |
+
+Best on: "packet in transit" visuals.
+
+---
+
+### pulse — `data-fx="pulse"`
+Stroke width + opacity breathe together. Combines wave + glow into a
+single subtle beat.
+
+| CSS var | Default | Meaning |
+|---------|---------|---------|
+| `--primekit-fx-speed` | `1.8s` | cycle |
+| `--primekit-fx-min-op` | `0.55` | minimum opacity |
+
+Best on: heartbeat / health indicators.
+
+---
+
+### dashed-flow — `data-fx="dashed-flow"`
+Slow ambient dash-drift for background structure. Lower contrast,
+longer cycle than marching-ants.
+
+| CSS var | Default | Meaning |
+|---------|---------|---------|
+| `--primekit-fx-dash` | `4 8` | dasharray |
+| `--primekit-fx-speed` | `6.0s` | cycle |
+
+Best on: secondary connectors that should feel alive but not compete.
+
+## Composition rules
+
+- **One accent color per diagram.** Effects using `--primekit-diag-accent`
+  should be reserved for the one edge that carries the argument.
+- **Never stack effects on the same path.** Pick one; layered effects
+  read as noise.
+- **Freeze before screenshot.** The pipeline applies `.primekit-fx-frozen`
+  to every SVG before `page.screenshot()` so the golden PNG is
+  determined solely by the path geometry + final-frame state.
+- **Reduced motion:** effects auto-freeze under
+  `@media (prefers-reduced-motion: reduce)` — verify by toggling your OS
+  reduce-motion preference or by emulating in DevTools.
+
+## Adding a new effect
+
+1. Define keyframes + selector in `assets/connector-effects.css`,
+   scoped to `svg:not(.primekit-fx-frozen) path[data-fx="<name>"]`.
+2. Add a `.primekit-fx-frozen path[data-fx="<name>"]` rule that pins the
+   effect to its resting state.
+3. Add a row to this file with the CSS var API.
+4. Add a demo entry to `assets/effects-demo.html`.
+5. Run `scripts/snapshot_test.py --update-goldens` after visual review.

package/skills/diagram/references/mermaid-input.md

@@ -0,0 +1,62 @@
+# pk:diagram — Mermaid input notes
+
+Pinned to vendored `assets/mermaid.min.js` v11.4.1. Do not rely on
+Mermaid features shipped after that release.
+
+## Supported diagram kinds
+
+Tier 1 wraps `.mmd` source into an editorial frame and runs
+mermaid.initialize with `theme: 'base'`. All standard Mermaid
+diagram kinds work: `flowchart`, `sequenceDiagram`, `classDiagram`,
+`stateDiagram-v2`, `erDiagram`, `journey`, `gantt`, `pie`, `mindmap`,
+`timeline`, `quadrantChart`, `requirementDiagram`, `xychart-beta`.
+
+## Editorial framing
+
+Every Mermaid render inherits the token palette from `assets/tokens.css`:
+
+- `--primekit-diag-paper` background
+- `--primekit-diag-ink` foreground / stroke
+- `--primekit-diag-accent` reserved for focal elements (do not overuse)
+- `--primekit-diag-font` type family
+
+Pass `--title` and `--caption` to `render.py` to add editorial
+headings above the diagram — Mermaid's own `title:` directive is
+ignored so we can control typography.
+
+## Animation
+
+Native Mermaid has no animation primitives. To animate connectors on
+a Mermaid-rendered SVG:
+
+1. Render once to HTML (`render.py --input diagram.mmd --no-png --no-svg`)
+2. Post-process the emitted SVG: add `data-fx="<name>"` to the paths
+   you want to animate (typically identifiable by their id/class).
+3. Re-open the modified HTML and re-render or record.
+
+For animation-heavy work, an editorial template from Tier 2 is usually
+the better choice — templates ship with `data-fx` slots already wired.
+
+## Deterministic rendering caveats
+
+- Mermaid auto-layout can vary slightly between minor versions. The
+  pinned version + vendored `mermaid.min.js` prevents drift.
+- Font metrics: rendering uses the token font stack. If a system
+  font is unavailable, fallback to the next in the stack may shift a
+  few pixels. `--font-render-hinting=none` reduces but does not
+  eliminate this.
+- Long labels wrap at the browser default; use `<br/>` in labels for
+  intentional breaks so the wrap point is reproducible.
+
+## Golden hash coverage
+
+Mermaid-native diagrams are not part of the golden snapshot suite —
+their layout depends on label content and is expected to drift with
+input changes. Templates (Tier 2) are the deterministic surface.
+
+## Escape hatch: mmdc
+
+If `mmdc` (mermaid-cli) is on PATH, `render.py` will not shortcut to
+it — the HTML pipeline is used uniformly so editorial framing and
+token overrides always apply. Use `mmdc` directly if you want the
+un-framed Mermaid default.

package/skills/diagram/references/per-type-schemas/README.md

@@ -0,0 +1,60 @@
+# Per-type JSON schemas
+
+Each schema describes the **intended** shape of a JSON spec passed to
+`render.py --input <spec>.json --type <slug>`. The slot filler
+replaces `{{key}}` tokens in the template with `str(spec[key])`.
+
+## Status: aspirational
+
+Upstream templates ship as finished exemplars with **no `{{key}}` slots
+declared yet**. The `_fill_template` code path in `render.py` is fully
+wired, but until a template opts in by placing slots in its HTML, a JSON
+spec's structured keys (arrays / nested objects) do not render.
+
+The intended progression per template is:
+1. Author identifies a piece of content in the exemplar HTML that should
+   be user-driven (e.g. the four labels of a `loop`).
+2. Author replaces that content with `{{key}}` matching a schema property.
+3. Author records the change in `references/vendoring-metadata.yaml`
+   (a `slots:` list per template) so re-vendoring won't blow it away.
+
+Until then, treat these schemas as documentation of the eventual API and
+use the raw HTML editing path (Tier 3 in `SKILL.md`).
+
+## Common keys (every type)
+
+| Key | Type | Purpose |
+|-----|------|---------|
+| `variant` | string | `"light"`, `"dark"`, or `"full"` (chooses template file) |
+| `title` | string | Rendered as `<h1 class="primekit-diag__title">` when the template supports it |
+| `caption` | string | Optional editorial subtitle |
+| `accent` | string | CSS color override for `--primekit-diag-accent` |
+
+## Schemas provided
+
+Not every template requires a schema — mermaid-native ones
+(`flowchart`, `sequence`, `state`, `gantt`) accept plain Mermaid
+source instead. Their schemas are intentionally omitted. The 20
+schemas here cover the 20 editorial types where the JSON slot-filler
+flow is the primary input path (19 base editorial types + `loop.json`
+that also demonstrates the shape as a canonical example):
+
+- `architecture.json`, `high-level.json`, `layers.json`,
+  `medallion.json`, `dp-integration.json`, `dp-security-matrix.json`,
+  `data-flow.json` — architecture cluster
+- `swimlane.json`, `process.json`, `org-chart.json` — flow cluster
+- `loop.json`, `pyramid.json`, `quadrant.json`, `radar.json`,
+  `timeline.json`, `nested.json`, `it-state.json` — storytelling cluster
+- `bar.json`, `line.json`, `scatter.json` — data-viz cluster
+
+The template HTML is the ground truth for supported keys. When in
+doubt, `grep -o '{{[a-z_]*}}' assets/templates/<type>/light.html`
+lists every slot the template expects.
+
+## Validation
+
+Schemas are drafted as
+[JSON Schema draft-07](https://json-schema.org/draft-07/schema).
+`render.py` does not validate against them at runtime — they exist
+for documentation and IDE completion. If you want strict validation,
+run `jsonschema` externally before calling render.

package/skills/diagram/references/per-type-schemas/architecture.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "pk:diagram architecture spec",
+  "type": "object",
+  "required": [
+    "layers"
+  ],
+  "properties": {
+    "variant": {
+      "type": "string",
+      "enum": [
+        "light",
+        "dark",
+        "full"
+      ],
+      "default": "light"
+    },
+    "title": {
+      "type": "string"
+    },
+    "caption": {
+      "type": "string"
+    },
+    "accent": {
+      "type": "string"
+    },
+    "layers": {
+      "type": "array",
+      "minItems": 2,
+      "items": {
+        "type": "object",
+        "required": [
+          "label",
+          "components"
+        ],
+        "properties": {
+          "label": {
+            "type": "string"
+          },
+          "components": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/skills/diagram/references/per-type-schemas/bar.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "pk:diagram bar spec",
+  "type": "object",
+  "required": [
+    "categories",
+    "values"
+  ],
+  "properties": {
+    "variant": {
+      "type": "string",
+      "enum": [
+        "light",
+        "dark",
+        "full"
+      ],
+      "default": "light"
+    },
+    "title": {
+      "type": "string"
+    },
+    "caption": {
+      "type": "string"
+    },
+    "accent": {
+      "type": "string"
+    },
+    "categories": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "values": {
+      "type": "array",
+      "items": {
+        "type": "number"
+      }
+    },
+    "y_label": {
+      "type": "string"
+    }
+  }
+}

package/skills/diagram/references/per-type-schemas/data-flow.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "pk:diagram data-flow spec",
+  "type": "object",
+  "required": [
+    "nodes",
+    "edges"
+  ],
+  "properties": {
+    "variant": {
+      "type": "string",
+      "enum": [
+        "light",
+        "dark",
+        "full"
+      ],
+      "default": "light"
+    },
+    "title": {
+      "type": "string"
+    },
+    "caption": {
+      "type": "string"
+    },
+    "accent": {
+      "type": "string"
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "label"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "from",
+          "to"
+        ],
+        "properties": {
+          "from": {
+            "type": "string"
+          },
+          "to": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "fx": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/skills/diagram/references/per-type-schemas/dp-integration.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "pk:diagram dp-integration spec",
+  "type": "object",
+  "required": [
+    "sources",
+    "sinks"
+  ],
+  "properties": {
+    "variant": {
+      "type": "string",
+      "enum": [
+        "light",
+        "dark",
+        "full"
+      ],
+      "default": "light"
+    },
+    "title": {
+      "type": "string"
+    },
+    "caption": {
+      "type": "string"
+    },
+    "accent": {
+      "type": "string"
+    },
+    "sources": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "processors": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "sinks": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

package/skills/diagram/references/per-type-schemas/dp-security-matrix.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "pk:diagram dp-security-matrix spec",
+  "type": "object",
+  "required": [
+    "rows",
+    "cols",
+    "cells"
+  ],
+  "properties": {
+    "variant": {
+      "type": "string",
+      "enum": [
+        "light",
+        "dark",
+        "full"
+      ],
+      "default": "light"
+    },
+    "title": {
+      "type": "string"
+    },
+    "caption": {
+      "type": "string"
+    },
+    "accent": {
+      "type": "string"
+    },
+    "rows": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "cols": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "cells": {
+      "type": "array",
+      "items": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/skills/diagram/references/per-type-schemas/high-level.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "pk:diagram high-level spec",
+  "type": "object",
+  "required": [
+    "blocks"
+  ],
+  "properties": {
+    "variant": {
+      "type": "string",
+      "enum": [
+        "light",
+        "dark",
+        "full"
+      ],
+      "default": "light"
+    },
+    "title": {
+      "type": "string"
+    },
+    "caption": {
+      "type": "string"
+    },
+    "accent": {
+      "type": "string"
+    },
+    "blocks": {
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 9,
+      "items": {
+        "type": "object",
+        "required": [
+          "label"
+        ],
+        "properties": {
+          "label": {
+            "type": "string"
+          },
+          "sub": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}