@mohammadhprp/system-prompt 0.10.1

package/framework/skills/diagram-design/references/export.md

@@ -0,0 +1,107 @@
+# Export to PNG / SVG
+
+Convert a generated diagram HTML file into a portable `.svg` and/or `.png` next to it. **Manual only — never run unprompted.**
+
+## Trigger
+
+Load this file when:
+
+- The user invokes `/diagram-design:export <html-file>` (the plugin's slash command — defined in `commands/export.md` at the repo root).
+- The user asks in natural language to export, save, rasterize, convert, or download a diagram in `.svg` or `.png` form. Typical phrasings:
+  - "export this as PNG"
+  - "save as SVG"
+  - "give me a PNG of that diagram"
+  - "rasterize it"
+  - "convert to png and svg"
+
+The slash command is a thin wrapper that delegates here — both paths run the same procedure below.
+
+## Scope
+
+Both formats are **diagram-only** — just the `<svg>` node. Editorial wrappers (header, summary cards, footer in `-full` variants) are intentionally dropped: the export deliverable is the diagram itself, suitable for Figma, slides, social cards, or blog images.
+
+If the user explicitly asks for "a screenshot of the whole page including the cards", that's a different request — fall back to a normal full-page screenshot via the user's OS or browser.
+
+## SVG export procedure
+
+1. Read the source HTML file.
+2. Extract the **first** `<svg ...>...</svg>` block. Use a multiline regex anchored on `<svg` and `</svg>`. Most generated diagrams have only one SVG; if there are multiple, the first is the diagram (gallery files are an exception — see *Edge cases*).
+3. Make it standalone:
+   - Ensure the opening tag has `xmlns="http://www.w3.org/2000/svg"`. Add it if missing.
+   - Ensure a `viewBox` is present. The skill's templates always include one; warn the user if absent rather than guessing.
+   - Inject Google Fonts `@import` so the SVG renders with correct typography in a browser:
+     ```svg
+     <defs>
+       <style>@import url('https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=Geist:wght@400;500;600&family=Geist+Mono:wght@400;500;600&display=swap');</style>
+     </defs>
+     ```
+     If the SVG already contains a `<defs>` block, **merge** the `<style>` into it (don't add a second `<defs>`).
+4. Prepend `<?xml version="1.0" encoding="UTF-8"?>\n` so the file is well-formed XML.
+5. Write to `<basename>.svg` next to the source (e.g. `example-architecture.html` → `example-architecture.svg`). Honour an explicit output path if the user provides one.
+
+### Caveat to surface to the user
+
+Tools that don't fetch remote fonts at import time (offline Illustrator, some Figma import paths, older SVG viewers) will substitute typography. The SVG renders correctly in any modern browser. For pixel-perfect portability, recommend the PNG export.
+
+## PNG export procedure
+
+Render **the original HTML** (not the extracted SVG) and screenshot only the `<svg>` element's bounding box. This keeps font loading reliable (already wired in the source HTML) while satisfying the "diagram only" rule. The PNG always has a **transparent background** (`omit_background=True`) so it can be placed on any slide or doc colour without a white halo.
+
+### Detection
+
+Before running anything, verify Playwright is installed:
+
+```
+python -c "import playwright" 2>NUL || python -c "import playwright"
+```
+
+If the import fails, surface this exact instruction to the user and stop:
+
+> Playwright isn't installed. To enable PNG export, run:
+> ```
+> pip install playwright
+> playwright install chromium
+> ```
+> Then ask me to export again.
+
+Don't auto-install. The user asked for one feature, not a system change.
+
+### Rasterize
+
+Write the snippet below to a temp file and run it with `python <tmp.py> <src.html> <out.png>`:
+
+```python
+from playwright.sync_api import sync_playwright
+import sys, pathlib
+
+src, out = sys.argv[1], sys.argv[2]
+scale = int(sys.argv[3]) if len(sys.argv) > 3 else 2
+
+with sync_playwright() as p:
+    browser = p.chromium.launch()
+    page = browser.new_page(device_scale_factor=scale)
+    page.goto(f"file://{pathlib.Path(src).resolve()}")
+    page.wait_for_load_state("networkidle")
+    page.locator("svg").first.screenshot(path=out, omit_background=True)
+    browser.close()
+```
+
+Default `device_scale_factor=2` for crisp output. Accept `1` for compact assets or `3` for print/retina hero use, passed as a third CLI arg.
+
+### Output naming
+
+`example-architecture.html` → `example-architecture.png`, written next to the source. Honour explicit user-provided paths.
+
+## Edge cases
+
+- **Source is `assets/index.html`** (the gallery, multiple SVGs in one file): refuse the export and ask the user which specific diagram file they meant. Don't guess.
+- **No `<svg>` block found**: the source isn't a diagram file. Tell the user; don't write anything.
+- **Surrounding HTML matters to the user**: they want cards/header in the image. Tell them this skill exports diagrams only, and recommend a browser-based full-page screenshot (or a separate PDF print).
+- **Source is missing fonts at runtime**: Playwright will substitute, the screenshot will look off. Check that the source HTML has the `<link href="...fonts.googleapis.com...">` tag in `<head>`. If absent, the file isn't from a current template — fix the source rather than working around it in export.
+
+## What this command never does
+
+- Modifies the source HTML.
+- Adds export buttons or `<script>` tags to generated diagrams (the "no JS in deliverables" rule in §11 still stands).
+- Auto-emits `.svg` or `.png` alongside HTML generation. Manual on every call.
+- Embeds an HTML wrapper (cards, headers) into the SVG via `foreignObject`. Too fragile across renderers.

package/framework/skills/diagram-design/references/onboarding.md

@@ -0,0 +1,268 @@
+# Onboarding — generate your skin from a design source
+
+**Goal:** point the skill at a design source — a website, an installed skill, or a local folder — and have it extract the palette + typography, then rewrite `style-guide.md` so every future diagram inherits that skin.
+
+Takes about 60 seconds.
+
+Three source methods are supported. Jump to the relevant section:
+
+- [§ URL](#url) — fetch a live website
+- [§ Skill](#skill) — read an installed Claude Code skill that carries design tokens
+- [§ Folder](#folder) — read a local design-system directory (CSS, JSON, Markdown)
+
+---
+
+## The flow (all methods)
+
+```
+Source you provide (URL / skill name / folder path)
+      ↓
+[1] read / fetch the source
+      ↓
+[2] extract dominant colors + fonts
+      ↓
+[3] map to semantic roles (paper, ink, muted, accent, …)
+      ↓
+[4] propose a style-guide.md diff
+      ↓
+[5] write the diff (with your approval)
+      ↓
+future diagrams use your tokens
+```
+
+---
+
+---
+
+## § URL
+
+### Invocation
+
+> *"Onboard Schematic to my site — `https://example.com`"*
+
+---
+
+### Step 1 — fetch the page
+
+Use `agent-browser` (preferred) or a plain `fetch`. If the site has multiple pages worth sampling (landing + blog + product), fetch 2–3 and merge the palette signals.
+
+```bash
+agent-browser navigate https://example.com --screenshot out.png --html out.html
+```
+
+---
+
+## Step 2 — extract colors and fonts
+
+### Colors
+
+Parse the rendered CSS and screenshot:
+
+- **Background color** of `<body>` or the dominant large region → `paper`
+- **Primary text color** (body text) → `ink`
+- **Secondary text color** (captions, meta) → `muted`
+- **Most-used brand color** (CTA button, link, heading accent) → `accent`
+- **Container / card background** slightly darker than paper → `paper-2`
+- **Border / hairline color** → `rule` (convert to rgba of ink at ~0.12 opacity)
+
+Prefer CSS custom properties when the site exposes them (`:root { --accent: …; }`). Otherwise pull via rendered `getComputedStyle` samples or a color-histogram pass over the screenshot.
+
+### Fonts
+
+Read the rendered `font-family` stack of:
+
+- `<h1>` → `title` family
+- `<body>` → `node-name` family  
+- `<code>`, `<pre>`, or any mono-styled element → `sublabel` family
+
+If the site has only one family, keep the schematic defaults for the missing roles (Instrument Serif for title, Geist Mono for mono). Don't force-pick a mono font that isn't on the site.
+
+---
+
+## Step 3 — map to semantic roles
+
+Propose a diff by filling this table:
+
+| Role | Detected | Confidence |
+|---|---|---|
+| paper | `#f8f6f0` | high |
+| ink | `#111111` | high |
+| muted | `#6b6b68` | medium |
+| accent | `#c73a2b` | high |
+| … | … | … |
+
+Flag low-confidence guesses so the user can correct before applying.
+
+### Constraint checks
+
+Before writing, validate:
+
+- **AA contrast**: `ink` on `paper` ≥ 4.5:1. `muted` on `paper` ≥ 4.5:1 for body text.
+- **Accent is the most saturated color**: not muted-ish, not near-grey.
+- **paper ≠ pure white**: if the site uses `#ffffff`, fall back to `#fafaf7` to preserve Schematic's warm-neutral feel — or ask the user to confirm pure-white is intentional.
+
+If any check fails, propose an adjusted value and explain why.
+
+---
+
+## Step 4 — preview the diff
+
+Show the user what will change in `style-guide.md`. Only the tokens table — everything else stays the same.
+
+```diff
+-| `paper`  | `#f5f4ed` | `#1c1a17` |
+-| `ink`    | `#0b0d0b` | `#f1efe7` |
+-| `accent` | `#f7591f` | `#ff6a30` |
++| `paper`  | `#f8f6f0` | `#1a1815` |
++| `ink`    | `#111111` | `#efeee7` |
++| `accent` | `#c73a2b` | `#e05440` |
+```
+
+Also regenerate the dark variant via the inversion rule (`rgba(11,13,11, X)` → `rgba(ink-rgb, X)`).
+
+---
+
+## Step 5 — apply
+
+Write the new tokens to `style-guide.md`. Suggest running the `/regenerate-examples` flow (if it exists) or rebuilding one example to verify the new skin reads cleanly.
+
+After onboarding, the user should:
+
+1. Open `assets/index.html` (gallery) and confirm the new palette feels coherent across all 26 types.
+2. If any type looks off, they usually need to tune `muted` (often too dark or too light against the new `paper`).
+
+---
+
+## When URL onboarding fails
+
+- **Site uses webfonts you can't replicate** (custom-hosted, paid): keep the schematic defaults for typography and skin only the colors.
+- **Brand has 6+ colors** and you can't identify a clear hierarchy: pick one as `accent`, demote the rest to `muted` variants or ignore them. The schematic grammar only uses 5–7 roles.
+- **Site is dark-mode first**: flip the inversion — treat their dark paper as the default `paper`, and generate a light variant via inversion.
+- **Homepage is all imagery, no text**: ask for a blog or docs URL instead — text-heavy pages expose the type hierarchy.
+
+---
+
+## § Skill
+
+Extract tokens from an installed Claude Code skill that carries its own design system (e.g. a `brand-design` or `ui-kit` skill).
+
+### Invocation
+
+> *"Onboard Schematic from my `acme-design` skill"*
+
+Or the gate offers this as option (b) and the user names the skill.
+
+### Step 1 — locate the skill
+
+Search for the skill in order:
+
+1. `~/.claude/skills/<skill-name>/` (user install)
+2. `.claude/skills/<skill-name>/` (project install)
+3. Any path the user provides explicitly
+
+If not found, ask the user to confirm the skill name or provide the path.
+
+### Step 2 — read token sources
+
+Glob the skill directory for any of these files and read them all:
+
+| Priority | Pattern | What to look for |
+|---|---|---|
+| 1 | `*.css`, `colors*.css`, `tokens.css` | CSS custom properties in `:root { --color-*: …; }` |
+| 2 | `tokens.json`, `design-tokens.json`, `*.tokens.json` | Style Dictionary / Figma token JSON |
+| 3 | `SKILL.md`, `README.md` | Markdown tables listing colors, fonts, hex values |
+| 4 | `style-guide.md`, `*design*.md` | Any narrative design documentation |
+| 5 | `*.html` (preview/example files) | Inline `<style>` blocks — scan `:root` and `body` rules |
+
+Read all matches and merge — CSS custom properties take priority over inferred values from HTML.
+
+### Step 3 — extract colors and fonts
+
+**From CSS custom properties:**
+Map variable names to semantic roles using name-heuristics:
+
+| If the variable name contains… | Map to role |
+|---|---|
+| `background`, `bg`, `paper`, `surface`, `canvas` | `paper` |
+| `foreground`, `text`, `body`, `ink`, `on-surface` | `ink` |
+| `muted`, `subtle`, `secondary`, `caption` | `muted` |
+| `accent`, `brand`, `primary`, `cta`, `highlight` | `accent` |
+| `border`, `rule`, `divider`, `outline` | `rule` |
+| `mono`, `code`, `pre` | `sublabel` font |
+
+**From JSON tokens:** follow the same heuristics on key names. If the JSON follows Style Dictionary format (`{ "color": { "brand": { "value": "#…" } } }`), flatten the path and apply heuristics to the leaf key.
+
+**From Markdown tables:** look for rows with hex values (`#rrggbb`) adjacent to role-like words. A row like `| accent | #eb6c36 |` maps directly.
+
+**Fonts:** look for `font-family` rules, `@import` or `@font-face` declarations, and Markdown mentions of font names alongside size/weight.
+
+### Step 4 — map, validate, propose diff
+
+Same as the URL method: fill the role table, run contrast checks, show the diff, ask for approval before writing.
+
+### When skill extraction is ambiguous
+
+- **Skill has no CSS or token files**: fall back to reading all `.md` files and look for hex values mentioned in prose. Surface what you found and ask the user to confirm mappings before applying.
+- **Multiple accent candidates**: list them and ask the user to pick one. Don't guess.
+- **Skill is dark-mode first**: ask whether to treat the dark values as the `paper`/`ink` defaults or to invert.
+
+---
+
+## § Folder
+
+Extract tokens from a local directory — a checked-out design system repo, a Figma export, or any folder the user points you at.
+
+### Invocation
+
+> *"Onboard Schematic from my design system at `~/projects/brand/design-tokens/`"*
+
+Or the gate offers this as option (c) and the user provides the path.
+
+### Step 1 — discover files
+
+Glob the folder (recursively, up to 3 levels deep) for:
+
+```
+**/*.css
+**/*.scss        (read @forward / $variable declarations)
+**/tokens.json
+**/*.tokens.json
+**/design-tokens.json
+**/colors.json
+**/*style-guide*.md
+**/*design-system*.md
+**/README.md
+**/*.html        (scan <style> blocks only)
+```
+
+If the result set is large (>20 files), prefer files in the root and files whose names contain `color`, `token`, `brand`, `palette`, `style`, or `theme`.
+
+### Step 2 — read and merge
+
+Read every discovered file. Apply the same extraction logic as the Skill method (§ Skill → Step 3). CSS custom properties and JSON tokens take priority over inferred values from prose.
+
+**SCSS variables:** treat `$variable-name: value;` the same as a CSS custom property — apply name heuristics to `$variable-name`.
+
+**Figma token JSON** (Figma Tokens Plugin format):
+
+```json
+{ "colors": { "brand": { "primary": { "value": "#eb6c36", "type": "color" } } } }
+```
+
+Walk the tree; the leaf `value` fields are the colors, the path segments supply the role heuristic.
+
+### Step 3 — map, validate, propose diff
+
+Same as the URL method: run contrast checks, show the full diff against current `style-guide.md`, and write only after the user approves.
+
+### When folder extraction is ambiguous
+
+- **No structured token files, only prose docs**: read every `.md` in the root and extract hex values found near role-like words. Show the user a table of what you inferred — don't silently apply uncertain mappings.
+- **Multiple themes / color schemes found**: list them, ask the user which one to use as the diagram skin.
+- **Folder has zero readable files**: tell the user and ask for a more specific path or switch to manual token entry.
+
+---
+
+## Future: per-project skins
+
+If the user wants multiple skins (one per project), duplicate `style-guide.md` as `style-guides/<project>.md` and add a header comment pointing the build to the active one. That's a v5.2 feature — for now, one skin per skill install.

package/framework/skills/diagram-design/references/primitive-annotation.md

@@ -0,0 +1,36 @@
+# Annotation Callout (italic-serif aside)
+
+Use for editorial asides — the "italic pointer" that marks a detail without competing with the primary diagram grammar. Think marginalia: *"structure IS the index"*, *"no imports, no configuration"*.
+
+## Grammar
+
+```svg
+<!-- 1. Italic Instrument Serif text -->
+<text x="904" y="36" fill="#2d3142" font-size="14" font-style="italic"
+      font-family="'Instrument Serif', serif" text-anchor="end">no imports, no configuration</text>
+<!-- 2. Dashed Bézier leader -->
+<path d="M 820 44 Q 700 84 520 216" fill="none"
+      stroke="rgba(45,49,66,0.40)" stroke-width="1" stroke-dasharray="4,3"/>
+<!-- 3. Landing dot -->
+<circle cx="520" cy="216" r="2" fill="#2d3142"/>
+```
+
+## Rules
+- Italic + serif together signal "editorial voice" against the diagram's sans/mono body. Don't substitute italic sans or italic mono — the combination is load-bearing.
+- Dashed path (`stroke-dasharray="4,3"`) distinguishes the callout leader from primary arrows (which are solid).
+- Place callouts in margins (top-right, bottom-left). Never inside the active diagram area.
+- Max 2 callouts per diagram. More becomes commentary, not signal.
+
+## Colors
+
+| Intent | Text | Leader |
+|---|---|---|
+| Neutral aside | ink `#2d3142` | `rgba(45,49,66,0.40)` |
+| Focal / accent | coral `#eb6c36` | `rgba(235,108,54,0.50)` |
+| Tertiary (muted) | muted `#4f5d75` | `rgba(45,49,66,0.30)` |
+
+## Anti-patterns
+- Solid arrow leader (reads as a flow arrow).
+- Italic sans or italic mono — the serif is load-bearing.
+- Callouts crossing primary arrows / lifelines — offset to a clear margin.
+- Using a callout to label something the diagram should label directly — put the label on the element.