| name | t1k:designer:base:diagram-authoring |
| description | Author game-design diagrams (quest trees, economy flows, narrative branches, level layouts) from copy-ready Mermaid templates. Authoring only — NOT an adapter. |
| effort | low |
| keywords | ["design diagram","quest tree","economy flow","narrative branch","level layout","game design diagram","mermaid template"] |
| version | 1.12.0 |
| origin | theonekit-designer |
| repository | The1Studio/theonekit-designer |
| module | base |
| protected | false |
Design Diagram Authoring
Copy-ready Mermaid templates and authoring guidance for the four most common game-design diagrams. This skill ships templates + reference docs, not code analysis. Rendering is delegated to /t1k:preview.
When This Skill Triggers
- Starting a new GDD section that needs a visual (quest tree, economy, narrative, level)
- Sketching design intent before implementation
- Updating a design diagram alongside a gameplay change
- Need a Mermaid starting snippet that's more than a blank canvas
What This Skill Is NOT
- Not an adapter — does not parse code, does not implement
detect(), does not register with the adapter-discovery scan
- Not a renderer —
/t1k:preview --from-file <template> handles that via mermaid-cli
- Not prescriptive — templates are starting points; edit freely
The Four Templates
| Template | Mermaid Type | Use For |
|---|
templates/quest-tree.mmd | flowchart TD | Branching quest progression, prerequisites, hub-and-spoke structures |
templates/economy-flow.mmd | flowchart LR | Currency sources (faucets) → sinks, conversion rates, inflation control |
templates/narrative-branch.mmd | classDiagram | Character relationships + branching narrative lanes by Act/chapter |
templates/level-spatial.mmd | flowchart LR | Level zones, gates (one-way vs two-way), spatial progression |
Usage
1. Copy a template into your project
cp .claude/modules/design-base/skills/design-diagram-authoring/templates/quest-tree.mmd \
docs/design/my-quest-tree.mmd
2. Edit the placeholders
Each template is heavily commented. Replace placeholder labels (Quest A, Gold, Act 1 Intro, Zone A) with your actual design.
3. Render with /t1k:preview
/t1k:preview --from-file docs/design/my-quest-tree.mmd
Or render inline:
/t1k:preview --diagram "quest tree for the prologue act"
4. Paste into your GDD
Render produces SVG/PNG. Embed in GDD markdown alongside the .mmd source so both are tracked in git.
Reference Docs (pattern guidance)
references/quest-trees.md — linear / branch / hub-and-spoke / Act-based patternsreferences/economy-flows.md — faucet/sink distinction, conversion nodes, inflation leaksreferences/narrative-branches.md — decision vs outcome nodes, character arcs, consequence layeringreferences/level-spatial.md — zones, gates, one-way edges, spatial vs logical adjacency
Scripts
scripts/list-templates.cjs — lists the four template names (used by /t1k:find-skill and doctor integrity checks)
Rendering prerequisite
Install mermaid-cli once via the base preset:
t1k diagram install
The install.json in this skill advertises the dependency (requires: ["mermaid-cli"]) with isAdapter: false, so the installer rolls it up without registering the skill in adapter discovery.
Authoring tips
- Keep diagrams under ~30 nodes. Mermaid rendering degrades and designers stop reading beyond that.
- One diagram per concern. Split quest prerequisites and narrative branches into two diagrams even when they touch the same NPCs.
- Source of truth is the
.mmd file. Never hand-edit rendered SVGs — edit the source and re-render.
- Comment intent, not mechanics.
%% Act 1 gate — player must have fire talisman not %% edge from A to B.
Gotchas
- Mermaid v11 ≠ v10 — quest tree templates use v11
subgraph direction; if your renderer is pinned to v10, edges go horizontal instead of vertical. Pin renderer or invoke /mermaidjs-v11 skill explicitly.
- Diagram density caps cognition at ~12 nodes — past that, split into sub-diagrams. A 30-node quest tree is unreadable on mobile review.
- Authoring is not adapting — this skill produces static design diagrams; if you want code-derived diagrams, use the engine adapter (e.g., rn-script-graph).
