Skip to content

Build a Deck

Build Loop

  1. Create or update a deck-design intent document in docs/decks/.
  2. Pick a base from src/deck-templates/ if useful.
  3. Assemble pages with page styles from src/page-templates/.
  4. Fill content using block styles from src/blocks/.
  5. Generate or update the deck app under src/decks/.
  6. Preview in local dev server.
  7. Refine the intent and repeat.

Local Commands

npm run build
npm run start
npm run build:update:deck -- <deck-id>
npm run serve:deck -- <deck-id>
npm run serve:local

Single-Deck Loop

Use a single deck as the unit of work.

  1. Update docs/decks/<deck-id>.md
  2. Run npm run build:update:deck -- <deck-id>
  3. Run npm run serve:local
  4. Review the rendered deck
  5. Refine the intent and repeat

Promotion Workflow

deck-demo is the canonical validation-and-reference deck.

Work there first when proving:

  • deck metadata conventions
  • company-wide visual base rules
  • page layout behavior
  • block designs

Use Promote <standard> with this exact meaning:

  1. Decide where the proven element should persist:
  2. system-wide design in src/shared/design-system/
  3. deck-wide standard in src/deck-templates/
  4. page layout standard in src/page-templates/
  5. block design standard in src/blocks/
  6. intent/default or workflow rule in docs/
  7. Codify the proven element in the correct reusable artifact so future decks can consume it.
  8. Remove the promoted element from one-off ownership in deck-demo, reapply the promoted standard from its new home, and verify the reproduced result matches the proven experiment.

Rule:

  • Do not leave a proven pattern living only inside deck-demo.
  • Do not promote an experiment until the rendered result is accepted.
  • After promotion, deck-demo should consume the standard instead of owning it.

Standard Precedence

When standards overlap, use this override precedence:

system > deck > page > block

Meaning:

  • system-wide standards define the baseline constraints for everything below them
  • deck-wide standards are subject to system-wide constraints
  • page standards are subject to system-wide and deck-wide constraints
  • block standards are subject to system-wide, deck-wide, and page-level constraints

If a rule belongs at a higher layer, promote it there instead of re-implementing it at a lower layer.

Rules

  • Treat docs/decks/*.md as the human-edited source of truth for deck intent.
  • Treat the React/Spectacle deck app as the primary generated product.
  • Keep export/rendering concerns out of the core deck/page prop model.
  • Prefer composition over custom slide code.
  • If a block is missing, add it to src/blocks/ and src/blocks/registry.ts.
  • If a layout is missing, add it to src/page-templates/ and src/page-templates/registry.ts.
  • Do not modify src/shared/ unless you are a designated maintainer.