coco-diagram

# CoCo Diagram Create visual diagrams as self-contained HTML files with inline SVG and CSS, following an opinionated editorial design system. Twenty-seven visual types. Semantic patterns describe behavior independently; type references describe layout. Details load from `references/` only when selected. --- ## 0. First-time setup — style guide gate **Before generating your first diagram in a new project, verify the style guide has been customized.** Don't silently ship default-skinned diagrams into a branded project. Open [`references/style-guide.md`](references/style-guide.md) and check the default tokens. If they're still the shipped defaults (paper `#f5f5f5`, ink `#2d3142`, accent `#BE185D` coco-magenta), **pause and ask the user**: > *"This is your first Schematic in this project. The style guide is still at the default (neutral white-smoke + coco-magenta). Do you want to customize it to match your brand first? Options: (a) pull from your website URL, (b) extract from an installed skill, (c) extract from a local folder / design-system directory, (d) paste tokens manually, (e) proceed with the default for now."* Then branch: - **(a)** → follow [`references/onboarding.md § URL`](references/onboarding.md) to fetch the site, extract palette + fonts, propose a diff, and write `style-guide.md`. - **(b)** → follow [`references/onboarding.md § Skill`](references/onboarding.md) — ask which skill, read its SKILL.md / CSS / token files, map to semantic roles, propose diff. - **(c)** → follow [`references/onboarding.md § Folder`](references/onboarding.md) — ask for the path, glob for CSS/JSON/MD token files, map to semantic roles, propose diff. - **(d)** → accept the user's tokens and write them into `style-guide.md` under a new "Custom tokens" section. - **(e)** → proceed; optionally remind the user they can run onboarding later. **Once the style guide has been customized** (or the user explicitly opted for default), skip this gate on subsequent runs. A simple way to detect customization: if the `accent` value in `style-guide.md` differs from `#BE185D`, assume custom. --- ## 1. Philosophy **The highest-quality move is usually deletion.** Applied to schematics: - Every node represents a distinct idea. Two nodes that always travel together are one node. - Every connection carries information. If the relationship is obvious from layout, remove the line. - Accent is **editorial, not a flag.** 1–2 focal nodes per diagram. Using it on 5 nodes erases the signal. - The schematic isn't done when everything is added. It's done when nothing can be removed. **Target density: 4/10.** Enough to be technically complete. Not so dense it needs a guide. Above 9 nodes, it's probably two diagrams. --- ## 2. When to Use Use for any of the 27 visual types (§3) when a reader will learn more from a visual than from prose, a table, or a bulleted list. **Don't use for:** - Quick unicode diagrams → use **wiretext**. - Lists of things → table or bullets. - Simple before/after → table. - One-shape "diagrams" → just write the sentence. Before drawing, ask: *Would the reader learn more from this than from a well-written paragraph?* If no, don't draw. --- ## 3. Selection: semantic pattern, then visual type When behavior, state, enforcement, or risk carries the meaning, first load [`references/semantic-patterns.md`](references/semantic-patterns.md) and choose one primary pattern. Then choose the nearest visual type for layout. If no pattern matches, choose the type directly. | Behavioral trigger | Semantic pattern → nearest type | |---|---| | Fan-in, queue depth, finite capacity, bottleneck | **Fan-in queue / bottleneck** → Data flow | | Repeated Question / Input / Governance / Output slots across stages | **Stage framework with semantic slots** → Process | | Conversation or loose input becomes a structured durable artifact | **Unstructured input → structured artifact** → Data flow | | Two rule traces need pass/fail/skipped/not-reached and first divergence | **Paired policy-evaluation traces** → Flowchart | | Trust boundaries plus permitted/forbidden ingress or deploy paths | **Secure paved road** → Architecture | | Controls grouped by where they are enforced | **Governance / control catalog** → Layer stack | | Defenses compensate for prior gaps and residual risk propagates | **Compensating security layers** → Layer stack | The pattern owns semantic primitives and its tighter budget; the type owns layout grammar. Use [`references/animation.md`](references/animation.md) only when motion is requested or materially clarifies ordered change; static remains the default. ### Visual-type guide (27) | If you're showing… | Use | Reference | |---|---|---| | Components + connections in a system | **Architecture** | [type-architecture.md](references/type-architecture.md) | | Legacy IT landscape grouped by phase/department; documents the *before* state in modernization proposals | **IT current-state** | [type-it-state.md](references/type-it-state.md) | | Decision logic with branches | **Flowchart** | [type-flowchart.md](references/type-flowchart.md) | | Time-ordered messages between actors | **Sequence** | [type-sequence.md](references/type-sequence.md) | | States + transitions + guards | **State machine** | [type-state.md](references/type-state.md) | | Entities + fields + relationships | **ER / data model** | [type-er.md](references/type-er.md) | | Events positioned in time | **Timeline** | [type-timeline.md](references/type-timeline.md) | | Cross-functional process with handoffs | **Swimlane** | [type-swimlane.md](references/type-swimlane.md) | | Two-axis positioning / prioritization | **Quadrant** | [type-quadrant.md](references/type-quadrant.md) | | Multiple entities scored across 3–5 quantitative criteria | **Radar / Spider** | [type-radar.md](references/type-radar.md) | | Reinforcing cycle / flywheel where the last step feeds the first and a shared hub accumulates state | **Loop** | [type-loop.md](references/type-loop.md) | | Hierarchy through containment / scope | **Nested** | [type-nested.md](references/type-nested.md) | | Parent → children relationships | **Tree** | [type-tree.md](references/type-tree.md) | | Human/agent/team ownership, reporting, routing, escalation | **Org chart** | [type-org-chart.md](references/type-org-chart.md) | | Stacked abstraction levels | **Layer stack** | [type-layers.md](references/type-layers.md) | | Overlap between sets | **Venn** | [type-venn.md](references/type-venn.md) | | Ranked hierarchy or conversion drop-off | **Pyramid / funnel** | [type-pyramid.md](references/type-pyramid.md) | | Quantitative comparison across categories | **Bar chart** | [type-bar.md](references/type-bar.md) | | Continuous trends over time | **Line chart** | [type-line.md](references/type-line.md) | | Tasks and phases on a timeline | **Gantt** | [type-gantt.md](references/type-gantt.md) | | Distribution and correlation between two variables | **Scatter plot** | [type-scatter.md](references/type-scatter.md) | | End-to-end data stack on a container cluster | **High-Level** | [type-high-level.md](references/type-high-level.md) | | Multi-actor sequential process with data handoffs | **Process** | [type-process.md](references/type-process.md) | | Multi-tier data storage with quality levels and access policies | **Medallion** | [type-medallion.md](references/type-medallion.md) | | Role-scoped data flow: who does what at each pipeline step | **Data flow** | [type-data-flow.md](references/type-data-flow.md) | | Integration topology of a data platform — sources → core → consumers | **DP integration** | [type-dp-integration.md](references/type-dp-integration.md) | | Per-role / per-component access permissions matrix | **DP security matrix** | [type-dp-security-matrix.md](references/type-dp-security-matrix.md) | Rules of thumb: - If a 3-column table communicates the same thing, pick the table. - If two types seem useful, pick the dominant axis; a semantic pattern may add behavior-specific primitives, not a second layout grammar. - If you're past the complexity budget (§7), split into an overview + detail. **Always load the chosen `references/type-*.md` before drawing.** When routed above, also load `semantic-patterns.md`; when animation is chosen, load `animation.md`. ### Confirm before drawing Before rendering, state the plan in one short message: the chosen visual type (and semantic pattern, if routed), the size preset, and anything the complexity budget (§7) will force out. If the user is reachable, let them redirect before you draw; if not, proceed and note the assumptions beside the deliverable. Skip the pause only when the request already pins type, size, and content exactly. --- ## 4. Universal Anti-patterns These mark "AI slop" schematics of any type: | Anti-pattern | Why it fails | |---|---| | Dark mode + cyan/purple glow | Looks "technical" without design decisions | | JetBrains Mono as blanket "dev" font | Mono is for *technical* content — ports, commands, URLs. Names go in Geist sans. | | Identical boxes for every node | Erases hierarchy | | Legend floating inside the diagram area | Collides with nodes | | Arrow labels with no masking rect | Bleeds through the line | | Vertical `writing-mode` text on arrows | Unreadable | | 3 equal-width summary cards as default | Generic grid — vary widths | | Shadow on any element | Shadows are out. Borders are in. | | `rounded-2xl` on boxes | Max radius 6–10px or none | | Accent on every "important" node | Accent is 1–2 editorial accents, not a signaling system | | Reproducing Mermaid's renderer layout | Imports automatic spacing and routing instead of making an editorial layout | | Diagonal / slanted connectors between off-axis nodes | Rounded right-angle (orthogonal) elbows are mandatory — see §6 Mandatory connector rules | | Arrow label sitting on or touching its connector | Label must have a 6–10px gap above the line so the connector stays visible | | Arrow label mask overlapping a node box | Nodes paint after labels — the fill clips the text into a fragment on the border. See §6 rule 6 | | Two connectors overlapping or running on the same path | Each connection must be independently traceable — bridge crossings, offset parallels | | Two connectors sharing a single attach point on a box | Fan attach points along the edge (≥12px apart) so every arrow is clearly distinct — see §6 rule 4 | | Connector routed behind a non-endpoint box without need | Reroute around intervening boxes; the dashed-transit exception (§6 rule 5) only applies when an unavoidable intervening box sits on the direct path | Type-specific anti-patterns live in each `references/type-*.md`. --- ## 5. Design System **The design system is skinnable.** All colors, typography, and tokens live in a single source of truth — [`references/style-guide.md`](references/style-guide.md). This file describes semantic roles (`paper`, `ink`, `muted`, `accent`, `link`, …). The default skin is a cool editorial palette (white-smoke paper, jet-black ink, coco-magenta accent, blue-slate muted, silver hairlines); to apply your own brand, either edit `style-guide.md` directly or run the URL-based flow described in [`references/onboarding.md`](references/onboarding.md). > When specs below or in type references mention "ink", "accent", "muted", etc., look up the current hex value in `style-guide.md`. ### Semantic roles (at a glance) | Role | Purpose | |---|---| | `paper`, `paper-2` | Page bg and container bg | | `ink` | Primary text / stroke | | `muted`, `soft` | Secondary text, default arrows, sublabels | | `rule`, `rule-solid` | Hairline borders | | `accent`, `accent-tint` | 1–2 focal elements per diagram | | `link` | HTTP/API calls, external arrows | **Focal rule:** `accent` goes on 1–2 elements max. Everything else is `ink` / `muted` / `soft`. If you're tempted to accent 4 things, you haven't decided what's focal yet. ### Node type → treatment | Type | Fill | Stroke | |---|---|---| | **Focal** (1–2 max) | `accent-tint` | `accent` | | **Backend / API / Step** | white | `ink` | | **Store / State** | `ink @ 0.05` | `muted` | | **External / Cloud** | `ink @ 0.03` | `ink @ 0.30` | | **Input / User** | `muted @ 0.10` | `soft` | | **Optional / Async** | `ink @ 0.02` | `ink @ 0.20` dashed `4,3` | | **Security / Boundary** | `accent @ 0.05` | `accent @ 0.50` dashed `4,4` | ### Typography (summary — full spec in style-guide.md) - **Title** — Instrument Serif, 1.75rem, 400 — H1 only - **Node name** — Geist (sans), 12px, 600 — human-readable labels - **Sublabel** — Geist Mono, 9px — ports, URLs, field types - **Eyebrow / tag** — Geist Mono, 7–8px, uppercase, tracked — type tags, axis labels - **Arrow label** — Geist Mono, 8px — annotation on arrows - **Editorial aside** — Instrument Serif *italic*, 14px — callouts only **Mono is for technical content.** Names are Geist sans. Page title is Instrument Serif. Italic Instrument Serif is reserved for annotation callouts. Never JetBrains Mono as a blanket "dev" font. ```html <link href="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" rel="stylesheet"> ``` --- ## 6. Core SVG Primitives Universal building blocks. Type-specialized primitives (lifeline, activation bar, region) live in the relevant `references/type-*.md`. Optional primitives: - Editorial callouts → [primitive-annotation.md](references/primitive-annotation.md) - Hand-drawn variant → [primitive-sketchy.md](references/primitive-sketchy.md) - Icon set (laptop, server, DB, K8s, Docker, AWS, …) → [primitive-icons.md](references/primitive-icons.md). Browse the gallery at [`assets/icons.html`](assets/icons.html). - Terminal / CLI-window variant → [primitive-terminal.md](references/primitive-terminal.md) - Optional explanatory motion → [animation.md](references/animation.md) ### Background **Default: clean paper, no dot pattern.** Single `<rect>` filled with `paper`. Don't wrap the diagram in a secondary container background — the diagram sits directly on the page. ```svg <rect width="100%" height="100%" fill="#f5f5f5"/> ``` **Optional: dotted paper variant.** When a long-form editorial diagram benefits from textured ground (essays, hero diagrams on a dedicated page), opt in by adding the `dots` pattern and a second rect: ```svg <defs> <pattern id="dots" width="22" height="22" patternUnits="userSpaceOnUse"> <circle cx="1" cy="1" r="0.9" fill="rgba(45,49,66,0.10)"/> </pattern> </defs> <rect width="100%" height="100%" fill="#f5f5f5"/>