tddworks/claude-skills/domain-design

Domain Design

Generate domain-modelling artifacts as self-contained HTML files with inline SVG and CSS. One opinionated editorial design system, a first-run style-guide gate, six diagram types purpose-built for Domain-Driven Design conversations, and a taste gate that keeps output honest.

What this skill is for. Helping a user think through and document their business domain: what the aggregates are, where the bounded contexts sit, which events move through the system, which terms live in the ubiquitous language. It is a thinking and communication tool — every output is meant to be read by a human stakeholder, not executed.

What it is not. Not an architecture or technical diagram skill — reach for diagram-design if the user wants sequence diagrams, layered architecture, ER, flowcharts, or any of the 13 technical types there. These two skills share a style guide so they render as siblings when used in the same project.

0. First-time setup — style guide gate

Before generating your first domain artifact in a new project, verify the style guide has been customized.

Open `references/style-guide.md` and check the default tokens. If they're still the shipped defaults (paper #faf7f2, ink #1c1917, accent #b5523a rust), pause and ask the user:

"This is your first domain-design artifact in this project. The style guide is still at the default (neutral stone + rust). Do you want to customize it to match your brand first? Options: (a) run onboarding — I'll pull colors and fonts from your website, (b) paste your tokens manually, (c) proceed with the default for now."

Then branch:

• (a) → follow `references/onboarding.md` to fetch the site, extract palette + fonts, propose a diff, and write style-guide.md.
• (b) → accept the user's tokens and write them into style-guide.md under a new "Custom tokens" section.
• (c) → proceed; optionally remind the user they can run onboarding later.

If diagram-design has already been onboarded in this project, style-guide.md will already be branded — detect this and skip the gate. The two skills intentionally share the same skin.

1. Philosophy

The domain is the thing. Everything else is scaffolding.

A good domain artifact does three jobs at once: it forces you to name things, it surfaces what you don't yet understand, and it leaves a trace a non-technical stakeholder can read. Anything that doesn't serve one of those jobs is clutter.

Applied to this skill:

• Use the user's words, not yours. If the user says "subscription", don't rename it "plan". Ubiquitous language is load-bearing — respect it. If the term is ambiguous, stop and ask.
• Names before shapes. The hardest part of domain modelling is naming. Resist the urge to draw 20 boxes and call them Order1, Order2, OrderItem. If you can't name it, don't box it.
• One concept, one box. Two boxes that always move together are one aggregate. Two value objects that share every field are one value object.
• Coral is editorial, not a flag. 1–2 focal elements per diagram — the aggregate root, the critical event, the core domain. Using it on 5 boxes erases the signal.
• Density 4/10. If it's over 9 boxes, it's probably two diagrams. Overview + detail, not one big chart.

The diagram is done when nothing can be removed.

2. When to use

Use when a reader will learn more about the business from a visual than from prose.

Don't use for:

• Technical architecture, sequence, ER, state machines, flowcharts → `diagram-design`.
• UI wireframes → ios-ux-prototype / app-design-concept.
• Runtime flow of code (not business flow) → diagram-design sequence/architecture.
• "Just a list of terms with no structure" → write a markdown table; a diagram adds no value.

First question to answer before drawing anything: Would the reader learn more from this visual than from a short prose paragraph, a markdown table, or a bullet list? If no — don't draw.

3. Diagram types

Selection guide

Rules of thumb:

• If a markdown table communicates the same thing, use the table.
• If two types overlap (domain model + aggregate), produce both: overview first, then one or two aggregate blow-ups.
• If the user is mid-event-storming, produce an Event Storm first; convert to Aggregate / Domain Model only after stickies stabilize.
• Don't hybridize grammars — an Event Storm with Context Map boundaries is confusing. Pick a dominant axis.

Always load the relevant `references/type-*.md` before drawing — it contains layout conventions, DDD semantics, anti-patterns, and example files.

4. Universal anti-patterns

These mark low-quality domain artifacts:

Type-specific anti-patterns live in each references/type-*.md.

5. Design system

Skinnable. All colors, typography, and tokens live in `references/style-guide.md` as semantic roles (paper, ink, muted, accent, link, …). This file is shared with diagram-design — a project's technical and domain diagrams render as siblings.

When specs below or in type references mention "ink" / "accent" / "muted", look up the current hex in style-guide.md.

Semantic roles at a glance

Focal rule: accent goes on 1–2 elements max — the aggregate root, the focal event, the core bounded context. Everything else is ink / muted / soft.

Domain-role → treatment

Domain-design extends the node vocabulary with DDD-specific roles. These compose with the base style.

Using these roles consistently across an Event Storm, a Domain Model, and an Aggregate diagram makes them instantly cross-readable.

Typography (summary — full spec in style-guide.md)

• Title — Instrument Serif, 1.75rem, 400 — H1 only
• Node name — Geist (sans), 12px, 600 — human-readable nouns (aggregate names, entity names)
• Ubiquitous term — Geist (sans), 13px, 600, accent — glossary entry headwords
• Sublabel — Geist Mono, 9px — IDs, types, version numbers
• Eyebrow / tag — Geist Mono, 7–8px, uppercase, tracked — role tags (AGG ROOT, EVENT, VO)
• Arrow label — Geist Mono, 8px — integration pattern, cardinality
• Editorial aside — Instrument Serif italic, 14px — callouts only