spinagram 0.1.0__py3-none-any.whl

spinagram/__init__.py

@@ -0,0 +1,11 @@
+"""spinagram — diagrams as code, rendered editable to SVG, PNG, PowerPoint and Figma."""
+from .api import render, scenes
+from .behavior import Activity, Flowchart, StateMachine
+from .layout import build_scene
+from .model import Diagram, Edge, Legend, Node, Table, Zone
+from .theme import Theme
+from .yaml_io import load
+
+__all__ = ["Activity", "Diagram", "Flowchart", "StateMachine", "Edge", "Legend", "Node", "Table", "Zone", "Theme", "build_scene", "load", "render",
+           "scenes"]
+__version__ = "0.1.0"

spinagram/agent_skills/spinagram/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: spinagram
+description: Author professional diagrams as code with spinagram (YAML or Python) and deliver them as SVG, PNG, editable PowerPoint and editable Figma. Use when asked to create, update or export flowcharts, decision trees, process/approval flows, swimlanes, today-vs-target comparisons, org/structure charts, matrices or tables-as-diagrams, especially for slide decks, studies or Figma. Covers layout grid, text fitting, edge routing, themes, icons, QA, and the Figma hand-off (through a Figma MCP server when the agent has one). For CSS styling use the spinagram-css skill. Not for data charts (bar/line) or auto-laid-out graphs of hundreds of nodes.
+---
+
+# spinagram: diagrams as code with editable outputs
+
+You write a **spec** (YAML or Python). A **theme** directory supplies the brand. spinagram resolves both into one scene and renders it through backends: `svg`, `png`, `pptx`, `figma`.
+
+```
+spec (YAML/.py) + theme dir ──► layout (fonts, wrap, anchors) ──► svg · png · pptx · figma
+```
+
+## Workflow
+
+1. **Message first.** State the single question the diagram answers. That becomes the `subtitle`, a full sentence with the conclusion. The `title` names the topic in 2–6 words.
+2. **Pick a pattern** (table below) and sketch the grid on paper: columns, rows, gaps.
+3. **Write the spec.** Prefer Python: `a >> b` arrows, `with d.group(...)` zones, loops for repetition, and automatic layout when no node has coordinates. Use YAML when another tool generates the diagram.
+4. **`spinagram check`** must report 0 issues (text overflow).
+5. **Render PNG and look at it.** Check overlaps, arrows crossing text, label pills on borders, and empty zones. Fix the spec, never the output.
+6. **Deliver.** Use `-f svg,png,pptx` for decks. Add `figma` and follow the Figma hand-off below.
+
+```bash
+spinagram render specs/ -t <theme-dir> -f svg,png,pptx,figma -o out/
+spinagram check  specs/ -t <theme-dir>
+spinagram render specs/ --only D04 -f png      # iterate on one
+```
+
+## Patterns
+
+| Need | Pattern | Building blocks |
+|---|---|---|
+| Linear process | Row of 4–6 boxes and `chain` | `row()`, `chain()` |
+| Decision | Diamonds with `yes`/`no` labels; branches leave from different sides | `kind: diamond`, side anchors |
+| Today vs target | Two zones, paired cards, one arrow per pair | `zones`, mirrored `x` |
+| Process + per-context detail | Row on top, table below | `tables` with an `icons` column |
+| Lifecycle / loop | Clockwise ring; the dashed return arrow carries the loop condition | `dashed: true`, `via` |
+| Org / governance | Tree top-down: global body on top, one row per level | `column()` per branch, `"a.bottom -> b.top"` |
+| Approval scenario | Request → engine → policy box → parallel approvers → outcomes | `style` = semantic state |
+
+## Diagram or UI mockup?
+
+spinagram draws **diagrams**. For **product UI** such as an e-mail, a chat, a card or a screen, a diagram looks fake. Use an HTML page instead:
+
+1. Build it with Tailwind at the slide size (1920×1080). Use the same header and footer as the diagram slides, and the theme's tokens, fonts and icons.
+2. Screenshot it at 2x with Playwright.
+3. Add the screenshot to the deck as a full-bleed picture slide.
+
+Keep the real, implementable template (an e-mail HTML with inline CSS, or an Adaptive Card) next to it, so the mockup is never the only artifact.
+
+## Layout rules
+
+- **Canvas** is 1920×1080 with an 80 px side margin. Content goes in `y` 170–1000, between the header and the footer rule.
+- **Use a grid.** Gaps between boxes are 28–40 in dense rows, 60–100 between steps and 40 between rows. Equal sizes inside a row.
+- **Size boxes for text.** Allow at most 3 body lines. If `check` reports `overflow-y`, enlarge the box or cut text. Do not shrink the font below the theme default.
+- **Icons** scale with box height (theme `icon_scale`, `icon_max`). Use `icon_size` only to make one emphasis node larger. Every box in a row has an icon, or none does.
+- **One reading direction:** left→right for flows, top→bottom for hierarchies. Return arrows go dashed.
+- **Layered landscape:** put the layer name in a left column (free `label`) and shift the boxes right. A zone label at the top collides with vertical arrows between layers.
+- **Short vertical gaps:** put the edge label beside the line (`label_at` offset in x), not on it. Otherwise the pill hides the arrowhead.
+- **Don't let tall boxes float text:** a 590 px box holding 8 lines reads as empty. Split the content into several boxes (one per source or route), or shrink the box to fit its text.
+- **Leave white space.** If a zone is half empty, shrink it. Do not stretch cards to fill it.
+
+## Text rules
+
+- **One idea per box.** Titles have 1–4 words. The body is a short phrase, not a sentence list.
+- **Numbers** in a diagram must come from the study/report sources. Put the source in `source:` (footer).
+- **Same vocabulary across all diagrams in a set:** one term per concept.
+- Edge labels are 1–2 words (`yes`, `no`, `affects`, `rejected`).
+
+## Edges
+
+- Prefer `"a -> b"` (sides auto-picked) or `"a.right -> b.left"`. Use `@0.3` to spread several edges leaving one side.
+- Side-centre anchors become **bound connectors in PowerPoint**: moving a box drags the arrow. Off-centre (`@frac`), `via` and `curve` edges are drawn exactly but stay unbound.
+- Route around boxes with `via: [[x, y], ...]`. Do not cross text. Place labels with `label_at` when the midpoint lands on a box.
+- Colours are semantic: default = normal flow, alert/orange = risk path, gray = alternative or neutral.
+
+## Styles (semantic, theme-mapped)
+
+| Style | Use |
+|---|---|
+| `default` | Normal step |
+| `dark` | Engine / central decision maker (one or two per diagram) |
+| `soft` | Background grouping, decision diamonds |
+| `warning` | Needs review / attention |
+| `alert` | Risk, problem, blocking body (review board, incident) |
+| `neutral` | Outcome or side note |
+
+## Numbers are facts
+
+Never type a number from data into a spec. Write `{{fact_id}}` and declare `facts:` (plus `locale:`) in `_defaults.yaml`. Each fact must carry its `query` or `formula` and its `computed_at`.
+
+- Forecasts are derived facts whose formula states the assumption, e.g. `0.3*critical_changes`.
+- `spinagram facts` lists every fact used; the generated `fontes.md` (sources) is the reviewer's document.
+- Use `|raw` to get a plain number for CSS widths in HTML bar charts.
+
+## Story decks
+
+**HTML deck** (`spinagram deck deck.yaml -t <theme> [-o out.html]`): one self-contained page — cover
+(title, subtitle, date, authors with photo and role), a full-colour divider per section, then one slide
+per diagram (title band + one-line message + the diagram at full width). Fonts, logos, photos and
+diagrams are embedded; printing gives one slide per page. `deck.yaml` lists `specs:` (dirs, relative to
+the file), `authors:` and `sections: [{title, subtitle, slides: [{diagram: <id>, title, message}]}]`;
+`image: svg` (vector, default) or `png` (smaller with many fonts). Colours and logos come from the
+theme's `deck:` block (`accent`, `strong`, `deep`, `page`, `logo`, `logo_negative`).
+
+For PowerPoint decks:
+
+When the diagrams form a presentation:
+
+- Keep a `deck.yaml` with sections, slide order and a `talk` line per slide; it becomes the speaker notes.
+- Open with a cover and a roadmap. Close with a case exercise, the benefits and the asks.
+- Slides not listed go to an appendix.
+
+## YAML pitfalls
+
+- **Quote values in flow mappings** (`{...}`) that contain `,`, `:`, `?` or `#`. For example, `text: "a, b, c"` or `title: ["Any", "trigger?"]`. Unquoted commas silently split the value; the loader now rejects the resulting unknown keys.
+- `yes`, `no`, `on` and `off` are booleans in YAML; never use them unquoted as ids (the loader rejects them).
+- `at: [x, y, w, h]` is shorthand for the four keys.
+- A `_defaults.yaml` in the specs folder supplies keys every diagram shares (`kicker`, `source`).
+
+## Live preview
+
+While iterating, run `spinagram serve <specs> --theme <theme>` (extra `ui`): the browser re-renders on every
+save, shows load/render errors inline, the theme token sheet (colour token names, styles) and the icon packs
+(search names, fetch missing packs). Use it to pick tokens and icon names instead of guessing.
+
+## Icon packs
+
+Use `icon: "<pack>:<name>"` for vendor icons: `aws`, `gcp`, `azure`, `k8s`, `oci`, `openstack`, `terrastruct`,
+`selfhosted` (Proxmox, OPNsense, VMware ESXi, TrueNAS, UniFi… for homelabs and private clouds) and `network`
+(router, switch, firewall… as `network:router`, `-green`, `-circle`, `-plain`) are built in
+and download on first use (`spinagram icons fetch`). Find names with `spinagram icons search <words>`;
+short aliases exist for common services (`aws:s3`, `aws:alb`, `aws:kms`, `gcp:gke`, `azure:aks`, `k8s:pod`).
+For general software architecture (languages, databases, caches, queues) use `terrastruct`:
+`terrastruct:java|python|go|nodejs|react`, `terrastruct:postgres|mysql|mongo|redis|oracle`,
+`terrastruct:kafka|sqs|sns|service-bus|pubsub`, `terrastruct:tech-server`, `terrastruct:db`. It has no
+native Kafka/RabbitMQ logo: `kafka` maps to the AWS MSK icon.
+Register a brand or extra set with `spinagram icons add <name> --dir|--zip|--npm|--github …`
+(`--project` writes `./spinagram-icons.yaml`, shareable with the repo). Prefer SVG packs; PNG packs
+(oci, openstack) carry a dark variant used automatically on dark fills.
+
+**PNG → SVG:** with the `vector` extra, PNG icons (theme, spec paths, packs) become traced SVG when a
+fidelity gate passes — crisper output and editable vectors in Figma (no PNG uploads). Check a set with
+`spinagram vectorize <dir>`; disable with `SPINAGRAM_VECTORIZE=0` or `icons: {vectorize: false}`.
+
+## Automatic layout (no coordinates)
+
+For architecture views (Region › VPC › AZ) and flows, prefer `layout:` and `groups:` over hand-placed
+coordinates. spinagram sizes and places everything, and each group is drawn as a zone.
+
+- **Engine:**
+  - `dot` for ranked flows and AWS views; it gives clean orthogonal routes.
+  - `elk` for many edges crossing group borders.
+  - `flex` (no dependencies) for grids of cards; add `route: ortho` for elbowed edges.
+  - `d2` when you need D2's layouts.
+- **Compare engines** before choosing: `spinagram render spec.yaml --layout dot|elk|flex|d2`.
+- **Group hints for flex:** `direction` (row|column), `columns`, `gap`, `padding`, `align`. Sibling groups stretch to equal size.
+- **Leave edges unanchored** (`a -> b`) so the engine routes them. An anchor (`a.right`) or `via` opts that edge out.
+- **Mixed slides:** a legend or note with explicit `at:` stays where you put it; the auto content fills `layout.area`.
+- **Hand-tuning:** `spinagram layout spec.yaml -o frozen.yaml` freezes the result; edit the frozen spec.
+- `check` reports `layout: overflow` when the content does not fit. Change the direction, split the diagram or shorten titles.
+
+## Groups with outlines (AWS-style)
+
+Zone styles may declare `stroke`, `dashed`, `icon`, `radius`, `upper` and `fill: none`, which draws
+cloud-provider groups the way AWS Architecture Icons do: an outline, no fill, the group icon flush in
+the top-left corner and the label beside it (`d.zone("AZ 1a", ..., color="aws-az")`). Nest them
+Account › Region › VPC › AZ; regional services (S3, KMS) sit inside the Region but outside the VPC.
+Keep AZ labels short (`AZ 1a`) so arrows entering the boxes below do not cross them.
+
+## Python DSL
+
+Automatic layout (no coordinates anywhere: the diagram is laid out with `flex`):
+
+```python
+from spinagram import Diagram
+d = Diagram("Q01", "Web app on AWS")
+users = d.box("Users", icon="aws:users")
+with d.group("VPC", style="aws-vpc", direction="right"):
+    api = d.box("API", text="FastAPI", icon="terrastruct:python")
+    db, cache = d.box("Orders DB", icon="terrastruct:postgres"), d.box("Cache", icon="terrastruct:redis")
+users.to(api, "HTTPS") >> [db, cache]   # a >> b, a << b, a - b (no head); lists fan out/in
+diagram = d
+```
+
+Fixed coordinates:
+
+```python
+from spinagram import Diagram
+d = Diagram("D01", "Release flow", subtitle="Evidence decides the path")
+a, b, c = d.row(["Build", "Stress & chaos", "Risk gate"], x=80, y=220, w=440, h=220, gap=100,
+                styles=[None, None, "dark"])
+d.chain(a, b, c)
+d.edge(c.bottom, d.box("Deploy", x=700, y=560, w=500, h=150).top, label="green")
+diagram = d          # the CLI picks up `diagram`, `diagrams` or `build()`
+```
+
+Annotate with `d.add_legend()`, `a.to(b, step="…")`, `d.callout(node, "…", kind=...)` and
+`d.note(..., variant="card"|"quote")`; see the spinagram-css skill.
+
+Give diagrams a `category=` and `tags=` (YAML `category:`, `tags:`) so `spinagram serve` groups them and
+`--tag`/`--category` filter them; vendor icons already add `aws`, `gcp`, `kubernetes`… tags.
+
+Helpers next to the spec are importable (`from _layout import spread`); files starting with `_`
+are not loaded as specs.
+
+## Outputs
+
+- **PowerPoint:** one slide per diagram, with native shapes and the text inside each shape. Tables are native, and the diagram `source` goes into the speaker notes. Viewers need the theme fonts installed.
+- **Figma:**
+  - **Scripts:** `out/figma/<slug>-NN.js` (run in order) and `<slug>.assets.json`. They run through the
+    Figma MCP server's `use_figma` tool. Without that server, hand the scripts to the user.
+    1. If the agent has Figma's `figma-use` skill, load it.
+    2. Run each script with `use_figma` (`fileKey` from the URL).
+  - **Container:** the diagram becomes a frame (Design file), a slide (Slides file) or a section (FigJam board, `figma.com/board/...`) named `spinagram:<id>`. Re-running it rebuilds the content in place.
+  - **FigJam:** edges whose both ends sit on box sides become native connectors attached to the boxes (they follow when a box moves); free edges stay vectors. Load the `figma-use-figjam` skill too, when available.
+  - **SVG icons** are rebuilt as editable vectors inside the script (`createNodeFromSvg`) — no upload. Only raster icons (PNG) need `upload_assets`.
+  - **FigJam in one step:** `-f figjam` writes library-mode scripts, `figma/icons/` (every icon used),
+    `icon-library.js` (finds the uploaded layers by file name) and a `README.md` with the order of calls.
+  - **Icon library (recommended for many diagrams):** upload every distinct icon once with `upload_assets` (multipart, the file name becomes the layer name), run `icon_library_js({file: nodeId})` to rename them `dk-icon:<file>` inside a section `spinagram:icons`, then generate scripts with `FigmaBackend(library=True)` / `to_figma_js(scene, library=True)`: icons are cloned from the library — exact bytes, much smaller scripts (≈30 KB instead of 45 KB+ with inline SVG).
+  - **FigJam gotchas:** connector endpoints use `magnet` (TOP/BOTTOM/LEFT/RIGHT) for side centres; `position` is in **pixels** from the node's top-left, not 0–1. Elbow routes are auto-computed — if one crosses a box, re-anchor that end to another side. `setPluginData` is not available in `use_figma` (placeholders carry ` · asset:<file>` in the layer name instead).
+  - **Images:**
+    - The script returns `imageTargets`.
+    - Call `upload_assets(fileKey, count=n, nodeIds=[...])`.
+    - POST each file listed in `assets.json` to its URL.
+  - **Edges (Design/Slides):** drawn as vectors, because the connector node is FigJam-only.
+- **SVG** is self-contained (fonts and images embedded). **PNG** is rendered at 2x (3840×2160) for slides.
+
+## CSS styling
+
+Stylesheets restyle any diagram without touching its code: `d.stylesheet("brand.css")`, `class_="critical"`,
+`edge.async { stroke-dasharray: 6 4 }`. For anything beyond a rule or two, load the **spinagram-css**
+skill: selectors, properties, recipes, layout hints for dense architecture slides and the debugging loop.
+
+## Themes
+
+Use `extends: default` and override `colors` (tokens may alias tokens), `fonts` (with files, for metrics and embedding), `icons` (`dir` + `pattern` `{name}-{variant}.png`, variants per background tone), `styles.*` and `chrome` (bar, title, kicker template, footer logo). Keep brand themes **outside** the engine repository.
+
+## Done when
+
+- `check` reports 0 issues.
+- The PNG has been reviewed: no overlap, no clipped text, and arrows do not cross labels.
+- Requested formats are written. PPTX opens.
+- The Figma scripts ran, or the hand-off steps were given to the user.

spinagram/agent_skills/spinagram-css/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: spinagram-css
+description: Style spinagram diagrams with CSS (selectors, cascade, custom properties, shadows, dashes, markers) and lay out dense cloud architecture slides (AWS, Google Cloud, Azure, Kubernetes) that fit one 1920×1080 canvas. Use when asked to make spinagram diagrams look polished or on-brand, write or debug a stylesheet, build a dark or vendor-coloured architecture diagram, or explain why an element looks the way it does. Includes recipes, worked examples and layout hints. Requires the spinagram CLI.
+---
+
+# Style spinagram diagrams with CSS
+
+A stylesheet restyles a diagram without touching its code. The same rules render in SVG, PNG,
+PowerPoint and Figma. This skill covers the CSS subset, the recipes that look good, and the layout
+habits that make dense architecture diagrams fit one slide. For general spinagram authoring, see
+the `spinagram` skill.
+
+Files next to this one:
+
+- `references/recipes.css`: tested rules to copy (base cards, dark canvas, tiers, edge semantics,
+  vendor accents).
+- `examples/`: six complete diagrams with their stylesheets: AWS three-tier and hub-and-spoke networking
+  (legends, numbered steps), Kubernetes workload and service networking and a Google Cloud global app
+  (legends, callouts), and an architecture-decisions slide of designed notes.
+  Render them with `spinagram render examples/ -f png -o out/`.
+
+## Workflow
+
+1. **Structure first, style second.** Write the diagram with groups and edges; give elements
+   semantic classes (`class_="security"`, `class_="async"`), never colours.
+2. **One base sheet plus one accent sheet.** The base sets cards, type and edges for every diagram
+   in the set. The accent sheet adds the vendor or brand palette. Attach both in cascade order:
+   `d.stylesheet("base.css")` then `d.stylesheet("aws.css")`.
+3. **`spinagram check <spec>`** must report 0 issues. `info: unused selector` lines are hints,
+   not failures.
+4. **Render a PNG and look at it** if you can view images; otherwise ask the user to. Check that
+   edges don't cross boxes, labels don't cover text and nothing is clipped.
+5. **Explain a value** with `spinagram check --styles <spec> --select "#api"`, or press **Inspect**
+   in `spinagram serve <specs>`, which reloads on every save of a spec or stylesheet.
+
+## Attaching styles
+
+| Where | Python | YAML |
+|---|---|---|
+| Diagram | `d.stylesheet("brand.css")`, `Diagram(..., css="...")` | `stylesheets: [brand.css]`, `css:` |
+| Element | `class_="critical"`, `css="stroke-width: 6"` | `class:`, `css:` |
+| Folder | — | `stylesheets:` in `_defaults.yaml` |
+| Theme | `theme.css` next to `theme.yaml` | same |
+
+Paths are relative to the spec. Later sheets win at equal specificity; inline `css=` beats every
+sheet rule and `!important` beats inline. Classes work on nodes, edges and groups
+(`d.group("VPC", style="aws-vpc", class_="private")` keeps the AWS outline and icon and adds the class).
+
+## Selectors
+
+| Selector | Matches |
+|---|---|
+| `node`, `edge`, `group`, `region`, `lane`, `diagram` | elements by type |
+| `box`, `data`, `state`, `decision`, … | nodes of that kind |
+| `.critical`, `#api`, `*` | class, id, anything |
+| `[icon]`, `[kind=data]`, `edge[from=api]`, `edge[to=db]`, `[label="yes"]` | attributes |
+| `group.vpc node`, `region > state` | descendant, child |
+| `:first-child`, `:last-child`, `:not(.x)`, `:root` | pseudo-classes |
+| `node::title`, `node::body`, `edge::label`, `group::label` | text parts |
+
+Node ids come from titles (`"Orders DB"` → `#orders-db`) unless you pass `id=`.
+
+## Properties
+
+| Applies to | Properties |
+|---|---|
+| Nodes, groups | `fill`, `fill-opacity`, `stroke`, `stroke-width`, `stroke-dasharray`, `border-radius`, `opacity`, `box-shadow` (one: `x y blur colour`) |
+| Text (`::title`, `::body`, `::label`) | `color`, `font-size`, `font-weight`, `font-style`; inherited from groups |
+| Edges | `stroke`, `stroke-width`, `stroke-dasharray`, `opacity`, `marker-start`, `marker-end` (`none`, `arrow`, `open-arrow`, `diamond`, `open-diamond`, `circle`, `bar`) |
+
+Colours: hex, `rgb()`/`rgba()`, CSS names, theme tokens (`fill: primary-soft`) and `var(--x)`, which
+falls back to the theme token `x`. Lengths are canvas pixels (`4` or `4px`).
+
+## Recipes
+
+All are in `references/recipes.css`.
+
+- **Layout-only group.** `fill: none` is rejected. A group that only arranges its children uses
+  `group.bare { fill-opacity: 0; stroke-width: 0; box-shadow: none; }`.
+- **Dark canvas.** Zones are translucent by default, so a dark group looks grey until it sets
+  `opacity: 1; fill-opacity: 1`. Restyle what sits inside with descendant selectors:
+  `group.night node::title { color: #F8FAFC }`.
+- **Hero element.** One glow per diagram: `box-shadow: 0 0 22px rgba(140, 79, 255, 0.45)` with a
+  thicker stroke. More than one and nothing stands out.
+- **External actors.** Dashed outline and no shadow (`.external`), so they read as outside the system.
+- **Edge semantics.** Solid for requests, dashed for async or control (`edge.async`, `edge.control`),
+  a colour for one special path (`edge.hot`), `marker-start` for two-way flows (`edge.replication`).
+- **Tiers.** Tint subnets or zones by tier (`group.public`, `group.private`, `group.data`) and colour
+  their labels to match.
+- **Vendor palettes.** AWS colours by service category (compute orange, network purple, database
+  magenta, storage green); Google Cloud uses its four brand colours; Kubernetes uses `#326CE5`.
+
+## Annotations
+
+Legends, numbered steps, callouts and notes make a reference architecture explain itself; all are styled
+by CSS and native in every output.
+
+- **Legend**: `d.add_legend()` lists the classes and styles in use, labelled from their names, so name
+  classes for meaning (`.web-tier` → "Web tier", `edge.backup-path` → "Backup path"). Pass
+  `{".class": "Label", "edge.class": ..., "style:dark": ..., "aws:s3": ...}` to choose entries.
+- **Steps**: `a.to(b, "HTTPS", step="Users call the API")`, `d.step("…", on=node)`. Badges sit beside edge
+  labels or on node corners; the Steps panel lists them in order. Keep each step to one line (~38 chars).
+- **Callouts**: `d.callout(node, "text", title=..., kind="info|tip|warning|risk")`. Auto placement needs
+  ~360 px of clear space beside the node; if `check` reports `callout: overlap`, target a node with room
+  around it.
+- **Notes**: `d.note(..., variant="card" | "quote")` for decision cards and quotes on narrative slides.
+- **Legend from CSS**: `legend { placement: bottom; columns: 4 }` moves and reshapes it (also `width`, `gap`,
+  `padding`, `swatch-width`, `swatch-height`, `display: none`, `legend::body { font-size }`); an explicit
+  `add_legend(position=...)` wins.
+- **Band budget**: legend and steps take a 392 px band on the right. Plan content for about 1416 px of width
+  (with `layout.area` set to `[56, 176, 1808, 830]`), or put the legend at the bottom.
+- **Style**: `legend`, `legend::title`, `legend::body`, `step`, `step::label`, `callout.warning`,
+  `callout::body`, `note.card`. A dark legend matches a dark cluster (see `examples/k8s.css`).
+- **Specificity**: a rule like `group.cluster node` (0,1,2) beats `.networking` (0,1,0); write
+  `group.cluster .networking` so class colours, and with them the legend, still show.
+
+## Fitting dense diagrams on one slide
+
+The canvas is fixed at 1920×1080 and content is not scaled down. `check` reports
+`layout: overflow` with the excess in pixels.
+
+- **Size cards yourself.** Automatic nodes are at least 220 px wide. Pass a size to every node,
+  `N = {"w": 210, "h": 84}` then `d.box(..., **N)`, and widen only the few that need it.
+- **Text room with an icon** is about `w − 102` px. A single word longer than that is reported as
+  `overflow-x`: widen that node or pick a shorter word. Titles wrap onto two lines; bodies keep to one.
+- **Smaller type shrinks boxes**: `node::title { font-size: 19px }` and `node::body { font-size: 14px }`.
+- **Tighten spacing** with group hints (`gap=24`, `padding=0`) and the root `"gap"` in `layout`.
+- **Use the margins** when needed: `layout={"area": [56, 176, 1808, 830]}` (x, y, w, h).
+- **Turn a row into a column.** When the width overflows and there is room below, stack: AZs as rows
+  of tier subnets, regions stacked, the control plane as a top row.
+
+## Edges that don't cross boxes
+
+- `flex` with `"route": "ortho"` draws elbowed edges but does **not** route around boxes. Connect
+  neighbours only: arrange columns so every edge goes to the next column or the next box in a stack.
+- An edge that would skip over a box: reorder (chain `users → dns → cdn` rather than fanning out),
+  move one end to another column, or drop the edge and show the relationship with text or a class
+  (a `.blocked` pod instead of a "deny" arrow).
+- Anchored edges (`d.edge(a.left, b.left)`) are drawn straight, not routed. Use them only between
+  boxes that face each other.
+- `elk` routes around boxes but lays out wider and ignores group `direction`. Compare with
+  `spinagram render spec.py --layout elk` before switching.
+
+## Backends
+
+SVG and PNG draw everything exactly. In PowerPoint and Figma, `open-diamond` becomes a filled
+diamond and `bar` is dropped, each with a warning; `opacity` blends the fill only. `font-family` is
+checked but not applied: text keeps the theme font. PowerPoint may warn that a PNG fallback for some
+Kubernetes SVG icons could not be made; recent PowerPoint versions show the SVG anyway.
+
+## Done when
+
+- `spinagram check` reports 0 issues.
+- The PNG shows no overlaps, clipped text or edges crossing boxes.
+- Classes describe meaning (`security`, `async`), and colours live only in stylesheets.

spinagram/agent_skills/spinagram-css/examples/aws.css

@@ -0,0 +1,46 @@
+/* AWS accents, layered on showcase.css. Colours follow the AWS architecture icon categories.
+   Class names double as legend labels: `d.add_legend()` turns `.web-tier` into "Web tier". */
+:root { --compute: #ED7100; --network: #8C4FFF; --database: #C925D1; --storage: #7AA116; --hybrid: #0EA5E9; }
+
+.external      { fill: #F8FAFC; stroke: #94A3B8; stroke-dasharray: 6 4; box-shadow: none; }
+.edge-service  { stroke: var(--network); }
+.security      { stroke: var(--sec); fill: #FFF5F5; }
+.load-balancer { stroke: var(--network); fill: #F5F3FF; }
+.web-tier      { stroke: var(--compute); }
+.app-tier      { stroke: var(--compute); fill: #FFF7ED; }
+.database      { stroke: var(--database); fill: #FDF4FF; }
+.storage       { stroke: var(--storage); fill: #F7FEE7; }
+
+group.edge        { fill: #F8FAFC; stroke: var(--card-stroke); border-radius: 16px; }
+group.edge::label { color: var(--muted); }
+group.bare        { fill-opacity: 0; stroke-width: 0; box-shadow: none; }
+group.public      { fill: #F0FDF4; stroke: var(--storage); }
+group.public::label  { color: #3F6212; }
+group.private     { fill: #EFF6FF; stroke: #147EBA; }
+group.private::label { color: #1E40AF; }
+group.data        { fill: #FAF5FF; stroke: var(--database); }
+group.data::label { color: #86198F; }
+
+edge.replication  { stroke: var(--database); stroke-dasharray: 6 4; marker-start: arrow; }
+edge.replication::label { color: #86198F; }
+
+/* Networking */
+group.onprem        { fill: #F8FAFC; stroke: #475569; stroke-dasharray: 2 4; border-radius: 0; }
+group.onprem::label { color: #334155; }
+.on-premises  { stroke: #475569; }
+.hybrid-link  { stroke: var(--hybrid); fill: #F0F9FF; }
+.transit-hub  { stroke: var(--network); stroke-width: 3; fill: #F5F3FF; box-shadow: 0 0 22px rgba(140, 79, 255, 0.45); }
+.transit-hub::title { color: #5B21B6; }
+.egress       { stroke: var(--network); }
+.workload     { border-radius: 6px; stroke: #16A34A; fill: #F0FDF4; }
+#staging-vpc  { stroke: #D97706; fill: #FFFBEB; }
+#shared-services { stroke: #0891B2; fill: #ECFEFF; }
+edge.private-circuit { stroke: var(--hybrid); stroke-width: 3; }
+edge.backup-path     { stroke: var(--hybrid); stroke-width: 3; stroke-dasharray: 8 5; }
+edge.inspection      { stroke: var(--sec); stroke-width: 3; }
+edge.inspection::label { color: var(--sec); }
+
+/* Annotations */
+step { fill: #232F3E; stroke: #FFFFFF; }
+step::label { color: #FF9900; }
+legend::title { color: #232F3E; }

spinagram/agent_skills/spinagram-css/examples/aws_network_hub.py

@@ -0,0 +1,51 @@
+"""AWS hub-and-spoke network: Transit Gateway with centralized inspection and egress, after the AWS
+reference architecture for multi-VPC networking, with an automatic legend and numbered traffic steps."""
+from spinagram import Diagram
+
+N = {"w": 200, "h": 80}  # compact cards: the whole network fits one slide
+
+d = Diagram("AWS02", "Hub-and-spoke networking on AWS",
+            subtitle="Transit Gateway hub · centralized inspection and egress · hybrid connectivity",
+            layout={"engine": "flex", "direction": "right", "gap": 32, "route": "ortho",
+                    "area": [56, 176, 1808, 830]})
+d.stylesheet("showcase.css")
+d.stylesheet("aws.css")
+
+with d.group(id="hybrid", class_="bare", direction="right", gap=32, align="center"):
+    with d.group("Corporate data center", id="dc", class_="onprem", direction="down", gap=24,
+                 icon="aws:group-corporatedatacenter"):
+        office = d.box("Branch offices", text="SD-WAN", icon="aws:officebuilding", class_="external", **N)
+        cgw = d.box("Customer gateway", text="BGP ASN 65010", icon="aws:vpc-customer-gateway",
+                    class_="on-premises", **N)
+    with d.group(id="links", class_="bare", direction="down", gap=24):
+        dx = d.box("Direct Connect", text="2 × 10 Gbps", icon="aws:direct-connect", class_="hybrid-link", **N)
+        vpn = d.box("VPN", text="IPsec backup", icon="aws:aws-siteto-site-vpn", class_="hybrid-link", **N)
+with d.group("us-east-1 · network account", style="aws-region", direction="down", gap=28, padding=16):
+    with d.group(id="services", class_="bare", direction="right", gap=24):
+        with d.group("Inspection VPC", style="aws-vpc"):
+            nfw = d.box("Network Firewall", text="stateful IPS", icon="aws:network-firewall", class_="security", **N)
+        with d.group("Egress VPC", style="aws-vpc", direction="down", gap=20):
+            nat = d.box("NAT gateway", text="per AZ", icon="aws:vpcnat-gateway", class_="egress", **N)
+            igw = d.box("Internet gateway", text="to 0.0.0.0/0", icon="aws:vpc-internet-gateway", class_="egress", **N)
+    with d.group(id="core", class_="bare", direction="right", gap=60, align="center"):
+        tgw = d.box("Transit Gateway", text="routing hub", icon="aws:aws-transit-gateway",
+                    class_="transit-hub", **N)
+        with d.group(id="spokes", class_="bare", direction="down", gap=14):
+            spokes = [d.box(name, text=cidr, icon="aws:group-virtualprivatecloud-vpc", class_="workload", **N)
+                      for name, cidr, env in (("Prod VPC", "10.1.0.0/16", "prod"),
+                                              ("Staging VPC", "10.2.0.0/16", "staging"),
+                                              ("Shared services", "10.3.0.0/16", "shared"))]
+
+office >> cgw
+cgw.to(dx, "primary", class_="private-circuit")
+cgw.to(vpn, "backup", class_="backup-path")
+dx.to(tgw, "DX gateway", class_="private-circuit", step="Branch traffic reaches AWS over DX")
+vpn.to(tgw, class_="backup-path")
+for s in spokes:
+    tgw.to(s, arrow="both")
+tgw.to(nfw, "inspect", class_="inspection", step="TGW sends traffic to inspection")
+nfw.to(nat, step="Allowed flows leave via NAT")
+nat.to(igw, step="The internet gateway egresses")
+d.add_legend()
+
+diagram = d

spinagram/agent_skills/spinagram-css/examples/aws_three_tier.py

@@ -0,0 +1,53 @@
+"""AWS three-tier web application, after the AWS reference architecture: an automatic legend from the CSS
+classes and numbered steps along the request path."""
+from spinagram import Diagram
+
+N = {"w": 196, "h": 80}  # compact cards: diagram, legend and steps share one slide
+
+d = Diagram("AWS01", "Three-tier web application on AWS",
+            subtitle="Edge, web, app and data tiers across two Availability Zones",
+            layout={"engine": "flex", "direction": "right", "gap": 32, "route": "ortho",
+                    "area": [56, 176, 1808, 830]})
+d.stylesheet("showcase.css")
+d.stylesheet("aws.css")
+
+with d.group("Internet edge", id="edge", class_="edge", direction="down", gap=22, padding=16):
+    users = d.box("Users", text="web, mobile", icon="aws:users", class_="external", **N)
+    dns = d.box("Route 53", text="latency DNS", icon="aws:amazon-route53", class_="edge-service", **N)
+    cdn = d.box("CloudFront", text="CDN, TLS", icon="aws:cloudfront", class_="edge-service", w=216, h=80)
+    waf = d.box("AWS WAF", text="managed rules", icon="aws:awswaf", class_="security", **N)
+    s3 = d.box("S3", text="static origin", icon="aws:s3", class_="storage", **N)
+with d.group("us-east-1", style="aws-region", padding=16):
+    with d.group("VPC 10.0.0.0/16", style="aws-vpc", direction="right", align="center", gap=12, padding=16):
+        alb = d.box("ALB", text="HTTPS :443", icon="aws:alb", class_="load-balancer", **N)
+        with d.group(id="azs", class_="bare", direction="down", gap=20, padding=0):
+            tiers = {}
+            for az, n in (("a", 0), ("b", 1)):
+                with d.group(f"Availability Zone {az.upper()}", style="aws-az", direction="right", gap=12, padding=16):
+                    with d.group(f"Public 10.0.{n}.0/24", style="aws-subnet", class_="public", padding=14):
+                        web = d.box("Web", text="Nginx · ASG", icon="aws:amazon-ec2", class_="web-tier",
+                                    id=f"web-{az}", **N)
+                    with d.group(f"Private 10.0.1{n}.0/24", style="aws-subnet", class_="private", padding=14):
+                        app = d.box("App", text="ECS Fargate", icon="aws:amazon-elastic-container-service",
+                                    class_="app-tier", id=f"app-{az}", **N)
+                    with d.group(f"Data 10.0.2{n}.0/24", style="aws-subnet", class_="data", padding=14):
+                        db = d.box("Aurora " + ("writer" if az == "a" else "reader"), text="PostgreSQL",
+                                   icon="aws:amazon-aurora", class_="database", id=f"db-{az}", **N)
+                tiers[az] = (web, app, db)
+
+users.to(dns, "resolve", step="Users resolve the domain")
+dns.to(cdn, "alias", step="Route 53 aliases to CloudFront")
+cdn.to(waf, step="AWS WAF filters each request")
+waf.to(alb, step="The ALB balances across zones")
+for az, (web, app, db) in tiers.items():
+    alb >> web
+    if az == "a":
+        web.to(app, step="Web tier calls the app tier")
+        app.to(db, "SQL", step="App tier writes to Aurora")
+    else:
+        web >> app
+        app.to(db, "SQL")
+d.edge(tiers["a"][2], tiers["b"][2], "replication", class_="replication")
+d.add_legend()
+
+diagram = d

spinagram/agent_skills/spinagram-css/examples/campus.css

@@ -0,0 +1,19 @@
+/* Campus network: clean tiers, network symbols carry the colour. */
+group.tier         { fill: #F8FAFC; stroke: #E2E8F0; border-radius: 16px; }
+group.tier::label  { color: #64748B; }
+group.bare         { fill-opacity: 0; stroke-width: 0; box-shadow: none; }
+
+.internet   { fill: #F8FAFC; stroke: #94A3B8; stroke-dasharray: 6 4; box-shadow: none; }
+.edge-gear  { stroke: #DC2626; }
+.core       { stroke: #16A34A; stroke-width: 2.5; }
+.access     { stroke: #2563EB; }
+.endpoint   { border-radius: 40px; stroke: #94A3B8; }
+
+edge                { stroke: #94A3B8; stroke-width: 2.5; }
+edge.uplink         { stroke: #16A34A; stroke-width: 3; }
+edge.redundant-link { stroke: #16A34A; stroke-width: 3; stroke-dasharray: 8 6; marker-start: arrow; }
+
+/* The legend is placed and laid out here, not in the diagram code. */
+legend        { placement: bottom; columns: 7; padding: 18; swatch-width: 64; swatch-height: 24; fill: #F8FAFC; box-shadow: none; }
+legend::title { font-size: 16px; color: #475569; }
+legend::body  { font-size: 15px; }

spinagram/agent_skills/spinagram-css/examples/campus_network.py

@@ -0,0 +1,45 @@
+"""A campus network in three tiers: WAN edge, a redundant core and access switches serving Wi-Fi, phones and
+desks, drawn with the Affinity symbols of the `network` pack in their colour and circle variants."""
+from spinagram import Diagram
+
+N = {"w": 220, "h": 92}
+E = {"w": 210, "h": 80}
+
+d = Diagram("NET01", "Campus network", subtitle="Redundant core, access layer and endpoints, left to right",
+            layout={"engine": "flex", "direction": "right", "rank_gap": 64, "route": "ortho",
+                    "area": [56, 176, 1808, 830]})
+d.stylesheet("showcase.css")
+d.stylesheet("campus.css")
+
+with d.group("WAN edge", id="edge", class_="tier", direction="down", gap=40, align="center"):
+    isp = d.box("ISP", text="2 × 10 Gb/s", icon="network:internet", class_="internet", **N)
+    router = d.box("Edge router", text="BGP, NAT", icon="network:router-red", class_="edge-gear", **N)
+    fw = d.box("Firewall", text="HA pair", icon="network:firewall-red", class_="edge-gear", **N)
+with d.group("Core", id="core", class_="tier", direction="down", gap=72, align="center"):
+    core_a = d.box("Core A", text="L3, 100 Gb/s", icon="network:switch-multilayer-green", class_="core", **N)
+    core_b = d.box("Core B", text="L3, 100 Gb/s", icon="network:switch-multilayer-green", class_="core", **N)
+with d.group("Access", id="access", class_="tier", direction="down", gap=24, align="center"):
+    floors = [d.box(f"Floor {i}", text="48 × 2.5 Gb/s", icon="network:switch", class_="access", id=f"floor-{i}",
+                    **N) for i in (1, 2, 3)]
+    wlc = d.box("Wireless LAN", text="controller", icon="network:wlc", class_="access", **N)
+with d.group("Endpoints", id="endpoints", class_="tier", direction="down", gap=24, align="center"):
+    ap = d.box("Access points", text="Wi-Fi 7", icon="network:wifi-plain", class_="endpoint", **E)
+    phone = d.box("IP phones", text="PoE", icon="network:ip-phone-circle", class_="endpoint", **E)
+    desk = d.box("Desks", text="1 Gb/s", icon="network:client-circle", class_="endpoint", **E)
+    printer = d.box("Printers", text="VLAN 40", icon="network:printer-circle", class_="endpoint", **E)
+
+isp >> router >> fw
+fw.to(core_a, class_="uplink")
+fw.to(core_b, class_="uplink")
+d.edge(core_a, core_b, "VSS", class_="redundant-link")
+core_a.to([floors[0], floors[1]], class_="uplink")
+core_b.to([floors[2], wlc], class_="uplink")
+floors[0] >> ap
+floors[1] >> phone
+floors[2] >> desk
+wlc.to(printer, "Wi-Fi")
+d.callout(core_b, "Either core carries the whole campus: links and supervisors are redundant.",
+          title="No single point of failure", kind="info")
+d.add_legend()
+
+diagram = d