Skip to content
Documentation

ADR-019: Draft & Deprecation State

Decision

Draft state is signalled by tags: ['draft'] alone, never by title or heading text. Deprecated stories move to a single quarantine root, ZZ - Deprecated/, with diagnostics nested beneath it. Lifecycle state lives in tags and tree placement, never in manually written title strings.

Key rules

  • Signal draft state with tags: ['draft'] in the story meta — this is the only draft mechanism.
  • Never add “Draft”, “(Draft)”, “WIP”, or similar text to a story title, MDX frontmatter heading, or document heading.
  • The draft tag drives Storybook badge display and filters; title pollution defeats that purpose.
  • When a component reaches Beta or Stable, remove the draft tag — do not add a replacement state tag in its place.
  • The only allowed deprecated root is ZZ - Deprecated/ (exact case and spacing).
  • Diagnostic stories go under ZZ - Deprecated/Diagnostics/ — never a separate ZZ - Diagnostics/ root.
  • Banned root names: zz-deprecated/, ZZ - Deprecation/, ZZ - Diagnostics/. Any of these in a meta.title is a violation.
  • Do not create a second deprecated quarantine root — keep deprecation consolidated under the one root.
  • Follow the ADR-010 deprecation checklist before moving any story into ZZ - Deprecated/.
  • “Move” to deprecated status means changing meta.title, never moving files on the filesystem.

Why

Encoding lifecycle state in tags and tree placement — not in free-text titles — lets Storybook’s badges, filters, and root allowlist do their job, since a single typo-prone string can no longer drift out of sync with the actual state. One quarantine root keeps deprecated and diagnostic stories out of the active component tree without fragmenting where reviewers must look. This record reconciles the sources to current dmwd-io practice on one point: deprecating a story is a meta.title change, never a filesystem move, matching the global Storybook hard rule (the original ADR-019 wording said only “moving a story,” which read as ambiguous).

Applies when

You are marking a story or component as work in progress, promoting it past draft, deprecating a component, or reviewing a PR that touches draft tags or the ZZ - Deprecated/ section.

  • ADR-010 — component maturity versioning (label system and deprecation checklist).
  • ADR-016 — Storybook IA & navigation (root allowlist and status:* tags).
  • ADR-016 — sidebar collapse governance.