v10/skills/write-design-doc/references/structure.md

Design Doc Structure

When to use single-file vs multi-file Design Docs.

Decision Tree

Is this a single concept with straightforward trade-offs?
├─ Yes → Single file
└─ No → Multi-file (index.md + optional decisions.md)

Single File

Use when:

• One concept, one decision
• Trade-offs fit in one page
• Reader can absorb in one sitting

Structure: See templates/feature-single.md for the full template.

Example: A new utility function, a small API addition, an internal pattern.

Multi-File

Use when:

• Multiple related concepts that benefit from separate pages
• The API surface doc is long enough that decisions would overwhelm it

Structure:

internal/design/feature-name/
├── index.md          # Problem, API surface, state, accessibility
└── decisions.md      # Only when decisions are raised and debated

index.md is the design doc. It covers the API surface — what users interact with, what state it needs, and how accessibility works. Think of it as a proto-user-facing doc.

decisions.md is optional. Only create it when real debates happen — alternatives are weighed, trade-offs are discussed. Don't scaffold it upfront. Let the code and implementation speak for themselves.

What about implementation mechanics? Temporary file-by-file steps belong in .agents/plans/. Stable internal structure and data flow may belong in a design record when they explain constraints or rationale.

Example: A compound UI component, a multi-part feature with store integration.

index.md Contents

The entry point and primary document:

1. Frontmatter — Status, date
2. Problem — What pain exists
3. Solution overview — High-level approach
4. Quick Start — Minimal working example
5. API Surface — Props, data attributes, CSS custom properties, events
6. State & Store — Features/slices required, state shape
7. Accessibility — ARIA, keyboard, focus management
8. Open Questions — Unresolved items

For components, the API surface section can highlight important part-specific details inline — no need for a separate parts file.

Splitting Guidance

Signs you need multi-file:

• Several decisions were debated and deserve documented rationale
• The API surface doc alone is comprehensive; decisions would double it

Signs to keep as single file:

• Everything fits in one readable page
• Splitting would create tiny files
• No significant decisions were debated

File Naming

File	Purpose
index.md	API surface, state, accessibility
decisions.md	Rationale for debated decisions (optional)

Use lowercase with hyphens. Match existing patterns in internal/design/.

Cross-Linking

When using decisions.md, link from the main doc:

See [decisions.md](decisions.md#decision-title) for rationale.

Use section anchors for precise links. Keep links relative.