Documents that get a reader to a decision

Name the reader and the question they bring. The question picks the document's shape; the audience picks its voice; both sit on the same facts.

Six skills for documents, reports, diagrams, charts, decks and brand themes, on one set of design tokens. Writing lands as Markdown in your repository; designed HTML, when you ask for it, needs no JavaScript and prints.

/plugin marketplace add Avinava/document-design-system
/plugin install document-design-system@document-design-system

Claude Code plugin. Each skill also installs on its own with npx skills add Avinava/document-design-system.

The question picks the shape. The audience picks the voice.

Two independent choices, and neither may touch the facts. Every mapping below is a document from the story further down.

Reader's question → pattern

The pattern fixes reading order: where the answer sits, what repeats, what the reader does last. It is declared with data-pattern.

The other four patterns, and all thirty-four presets, start from the reader's question on the Patterns page. When no preset fits, the pattern alone is enough to compose one.

Audience → theme

The theme sets type, colour and density through tokens, declared with data-theme. Changing it never moves a section. Compare every theme.

One proposal body, three themes. The client brand was extracted with provenance, mapped to roles and contrast-audited; see how.

Both sit on the same facts

Every example draws on one ledger, and every claim carries its evidence state. A missing fact stays unresolved; it is never invented.

  • Four of the last six incidents trace to the shared queueVerifiedfrom incident tickets
  • Two independently recoverable queues reduce blast radiusRecommendedby RFC 014
  • Shed-and-alert rather than blockUnresolvedReliability owns the decision

Markdown is the canonical form. Designed HTML is built from the same title and facts, and a test fails when the two disagree.

One engagement, four acts

Northwind Ingestion runs every producer through one shared queue, and that queue keeps stopping all of them at once. RFC 014 splits it in two. Each act is a job readers are doing; each document is the shape their question needed.

Act 1: Understand. Something broke. What is actually true?

Before anyone proposes a fix, three readers need the facts in the shape of their own question.

  1. For Platform and Reliability

    What happened, why, and what stops it recurring?

    Incident pattern. Impact comes before narrative, then a timeline, the cause, and corrective actions with owners.

    Voice
    console-violet
    Incident

  2. For the platform review

    Where does the platform footprint sit, measured?

    Analytical report. A measured claim carries its denominator: 41% of the footprint is 1.84M of 2.50M units.

    Voice
    editorial-coral
    Data as of

  3. For Platform, before funding the build

    What did we learn, and should we proceed?

    Decision pattern. It ends on a next move: go, stop or reframe RFC 014, with the one-queue-down test that decides.

    Voice
    field-notes
    Window closed

Act 2: Decide. Should we do this, and what will it take?

One decision, due 2026-09-01, reaches the Platform director three ways: argued, sized and presented.

  1. For the Platform director, with Reliability and the producer teams reviewing

    Should we do this, and is the approach sound?

    Decision pattern. The ask and its deadline come first, then options on the same criteria and a change view of one queue becoming two.

    Voice
    field-notes
    Decide by

  2. For the Platform director

    What will this take, and how confident are we?

    Decision pattern. The number and its confidence lead; a waterfall adds up to 24 engineer-weeks and draws CR-003 without counting it.

    Voice
    executive-navy
    As of

  3. For the Platform director, in the room

    What are you asking me for, and by when?

    Deck. The same decision in another medium: one claim per slide, and the options compared on the same criteria.

    Voice
    executive-navy
    Presented

Act 3: Deliver. How do we get there without breaking producers?

With the work under way, the questions turn to sequence, current state and proof.

  1. For Platform, Reliability and the producer teams

    How will the agreed outcome be delivered and governed?

    Plan pattern. Baseline, workstreams, dependencies, then five gates; the critical path is the one accent in the dependency graph.

    Voice
    executive-navy
    Baseline from

  2. For the Platform director, Platform and Reliability

    Where are we now, and what needs attention?

    Brief pattern. Amber first, then what moved, then the one action each reader owns before the next report.

    Voice
    executive-navy
    Period ending

  3. For Reliability, which approves the gate

    Is this change ready for production?

    Assurance pattern. The verdict comes first with its evidence beside it: conditional go until chaos and rollback evidence close.

    Voice
    console-violet
    Review

  4. For Platform, running the cutover

    How do we move safely and back out?

    Plan pattern. Rehearsal, sequence and gates, one partition at a time, with the original queue kept until hypercare closes.

    Voice
    console-violet
    Cutover

Act 4: Run and hand on. Who keeps it alive, and how does the next engineer learn it?

The last readers are the ones who stay, and the last question is one no preset answers.

  1. For on-call, while the lag alert is firing

    What do I do right now?

    Procedure pattern. Safety before steps, a checkpoint after each, and a deployment map of cluster, namespace and replicas.

    Voice
    console-violet
    Reviewed

  2. For an engineer joining from batch and warehouse work

    Can I reuse what I know from batch loads here?

    Learning pattern, composed. No preset answers it. The question picks the learning pattern, and the page is composed from that pattern's modules: a scope strip, a learning goal, a crosswalk and takeaways.

    Voice
    field-notes

Twelve documents, seven patterns, four voices, one ledger of facts. A shape composed three times becomes a preset; that is the only way the catalog grows.

Figures that stay true

Diagrams and charts are SVG drawn on the page's own tokens. These four are inlined, so they follow this page's theme and its dark mode. The waterfall refuses to render if a total is not the sum of its steps.

RFC 014 change view: one queue becomes two Today, producers reach the warehouse through the gateway, the single ingest queue, and one consumer group. RFC 014 adds a stateless dispatcher after the gateway that hashes the event ID to one of two queues, ingest-a and ingest-b, each with its own consumer group. The accent marks the dispatcher. A change ledger lists each change by node id: dispatcher added, ingest-a and ingest-b added, consumer group changed, ingest removed once the shadow week closes; producers, gateway and warehouse are unchanged. TODAY removed RFC 014 · PROPOSED added added changed Producers Gateway Queue ingest Consumers 3 replicas Warehouse Producers Gateway Dispatcher by event ID Queue ingest-a Queue ingest-b Consumers group a Consumers group b Warehouse CHANGE LEDGER dispatcher added Stateless; hashes the event ID to exactly one queue. ingest-a, ingest-b added Independently recoverable; 24-hour retention unchanged. consumer group changed One group per queue; each scales and recovers alone. ingest removed Stays recoverable until the shadow week closes. Unchanged: producer API, authentication, payload, warehouse schema, batch path.
Change view. What changes, and what stays the same? In the design doc and migration plan.
Where ingestion runs: prod-ingest and stage-ingest In the prod-ingest cluster, namespace ingest runs the gateway and the ingest-consumer deployment. The gateway enqueues to the queue ingest, the consumers read from it and write to the warehouse; the queue and warehouse are dependencies whose hosting this map does not show. The accent marks the consumer deployment: three replicas run, operators add one at a time, and never more than six without Reliability. The stage-ingest cluster runs the same namespace and is where release candidate sha-8132c3 was tested and where dual-write begins. CLUSTER prod-ingest NAMESPACE ingest CLUSTER stage-ingest DEPENDENCIES Namespace ingest: gateway and ingest-consumer. sha-8132c3 tested 2026-08-12 · dual-write from 2026-10-12 enqueue read Gateway POST /events Consumer group deploy/ingest-consumer +1 · max 6 Queue ingest Warehouse replica running the one replica to add next dependency; hosting not shown
Deployment map. Where does each part run? In the architecture guide and runbook.
RFC 014 delivery dependencies and the critical path Work runs left to right from the RFC 014 decision on 2026-09-01 to production and handoff from 2026-11-02 to 2026-11-20. The decision unblocks the chaos environment and the dispatcher work. The dispatcher feeds staging dual-write and the chaos tests; the chaos environment also feeds the chaos tests. Dual-write, chaos tests, and producer retry fixtures all gate the readiness decision on 2026-10-28, which gates production. The accent marks the critical path through the chaos environment, RAID-01, whose owner has not confirmed the 2026-09-18 date. RFC 014 decision 09-01 Dispatcher + two queues Environment chaos · 09-18 Dual-write staging 10-12 Chaos tests one queue down Retry fixtures producers 10-16 Readiness decision 10-28 Production 11-02 → 11-20 RAID-01:owner unconfirmed accent: critical path — a slip here moves production Dates are 2026, month-day.
Dependency graph. What blocks what, and which path sets the date? In the delivery plan.
Four work packages build the 24 engineer-week estimate Dispatcher and queues add 9 engineer-weeks, consumers and observability 6, testing and readiness 5, and cutover and handoff 4, for an expected 24 engineer-weeks within a 22 to 28 range. CR-003 would add 3 more but is excluded until approved.051015202530Engineer-weeks →Dispatcher and queuesConsumers and observabilityTesting and readinessCutover and handoffExpectedCR-003 history panel+9+6+5+4+3 · not approved24 (range 22–28)
Waterfall bridge. How do the parts add up to the total? In the estimate.

Mermaid and draw.io files are inputs: their structure is imported and redrawn. SVG on tokens is the output. Open every figure.

Checked, not eyeballed

Each row is a check that fails the build when it finds a problem. The counts are read from the repository when this page is built.

CountWhat is checkedCheck
34PresetsEach type file declares its pattern and theme; the catalog is derived from them, never copied.validate_repository.py
11PatternsEvery pattern's characteristic modules are used by one of its examples.validate_repository.py
51ModulesEach has CSS, the stylesheet styles nothing unregistered, and no body uses a module its pattern does not allow.validate_repository.py
18Diagram rulesShell, colour by token, 4px grid, overlap, bounds, label clearance, one accent family.check_diagrams.py
6Themes auditedContrast for every text pair, one accent, hue separation from status colours, dark print.audit_theme.py --all
690Page renders46 pages at 1280px, 390px and print, under five themes: no sideways scroll, no clipped figure text.check_render.py

The skills

Each row links to a committed example, not a description of intent.

SkillOwnsDoes not own
analytical-document-designEvidence models, metric semantics, denominators, report architectureProse-first documents, slides, standalone charts
diagram-designWhen a diagram earns its place; fifteen forms; Mermaid and draw.io structure imported and redrawn as token SVG; geometry checksQuantitative charts, UI mockups, editable diagram files as output
chart-designChart selection, axis honesty, token palettes, a waterfall that checks its totalsNarrative structure, dashboards as applications
presentation-design16:9 HTML slides, claim titles, one idea per slide, PDFDocuments meant to be read; editable slide files
writing-documentsThirty-four presets across eleven patterns, and composition when none fits; Markdown by defaultMetric-led reports; casual edits to existing Markdown
brand-theme-designBrand to theme: extraction, semantic mapping, contrast auditChoosing between shipped themes; restyling one document

What's new in 0.5.0

Built on

Readers need nothing installed: a delivered document is HTML and SVG. These run only on the machine that writes it, pinned to exact versions.

PackageRegistryVersionLicence
@observablehq/plotnpm0.6.17ISC — Observable, Inc.
beautiful-mermaidnpm1.1.3MIT — Craft Docs (Lukilabs)
jsdomnpm30.1.2MIT
playwrightnpm1.63.0Apache-2.0 — Microsoft
pillowPyPI12.3.0MIT-CMU (historical PIL licence, also listed as HPND)
playwrightPyPI1.63.0Apache-2.0 — Microsoft

Design influence. The diagram skill's editorial standard is adapted from diagram-design by Cathryn Lavery (MIT): deletion as the best edit, one accent, geometry on a grid, and diagram files as structure to redraw. No code is used. Full notices are in THIRD_PARTY_LICENSES.md.