t1k:designer:base:diagram-authoring

Field	Value
Module	`base`
Version	`1.13.2`
Effort	`low`
Tools	—

Keywords: design diagram, economy flow, game design diagram, level layout, mermaid template, narrative branch, quest tree

How to invoke

/t1k:designer:base:diagram-authoring

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 patterns
references/economy-flows.md — faucet/sink distinction, conversion nodes, inflation leaks
references/narrative-branches.md — decision vs outcome nodes, character arcs, consequence layering
references/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).