Skip to content

Deck Designs

oves-decks uses MkDocs as the intent layer for deck creation.

Each real deck should start with a deck-design document under docs/decks/. That document explains the purpose of the deck and points to the generated deck app.

Runtime Model

  • oves-decks is a React/Spectacle-centric system.
  • The generated deck app is the primary product.
  • Exports such as PDF, PPT, HTML, or XML are downstream renderings, not the core design object.
  • Export/transmission concerns should not shape the deck-design prop model.

Rule

  • Edit the intent document first.
  • Treat the deck app in src/decks/ as generated or scaffolded output.
  • Do not hand-edit deck app code unless you are changing shared primitives or generator behavior.

Standard Override Order

Intent and implementation should respect this precedence:

system > deck > page > block

A deck intent may choose deck, page, and block standards, but it should not attempt to override rules that belong to a higher layer.

In practical terms:

  • a deck is subject to system-wide constraints
  • a page is subject to system-wide and deck-wide constraints
  • a block is subject to system-wide, deck-wide, and page-level constraints

Minimal deck-design Contract

Each deck intent document should define:

  • deck_id
  • title
  • summary
  • author
  • status
  • visibility
  • source_system
  • owner
  • updated_at
  • tags
  • pages

Page intents should define:

  • page_id
  • page_style
  • title
  • variant
  • description
  • page-scoped blocks where needed

Required Sections

Each document should include:

  1. Purpose
  2. Audience
  3. Narrative shape
  4. Design direction
  5. Output link or runtime reference

Location

  • Intent docs: docs/decks/
  • Generated deck apps: src/decks/
  • Catalog registry: content/catalog/decks.json

Page And Block Addressing

  • Page intent ids use the form P1.<ABC>.
  • Blocks are always scoped to a page.
  • Blocks use matrix addressing from the upper-left: 1/1, 1/2, 2/1, 2/2.
  • A block cannot exist without being explicitly specified on a page.
  • Some page styles may define additional named block regions when the layout requires them.
  • two-column-callout currently supports footer as a named block address in addition to 1/1 and 1/2.

Supported Page Styles

  • hero
  • single-block
  • two-column
  • two-column-callout
  • four-block-matrix

Use the simplest page style that faithfully represents the deck intent.

If the intent cannot be expressed with an existing page style, promote a new reusable page primitive before encoding deck-specific one-off layout logic.

Supported Block Styles

  • bullet-list
  • numbered-list
  • callout
  • stat-cards
  • key-value-table
  • comparison-table
  • image-gallery
  • media-bullet-list
  • flow-diagram
  • venn-chart

Prefer these reusable block styles over bespoke slide code.

If a repeated content pattern is missing, add it as a reusable block and update the generator rather than embedding one-off JSX in a generated deck.

Minimal Tag Model

Keep tags simple and prefixed:

  • audience:*
  • use:*
  • product:*
  • market:*
  • collection:*
  • state:*

Metadata Questionnaire

Use npm run init:deck to start a new deck intent with a simple metadata questionnaire.

The script asks a series of prompts in the form:

  • Input <Deck ID>:
  • Input <Title>:
  • Input <Summary>:

If you press Enter without typing a value, the script uses a default.

See Deck Intent Defaults for the current default deck/page prop set.

Scaffold Command

Use npm run build:update:deck -- <deck-id> to work on one deck at a time.

This command:

  • reads the target deck intent from docs/decks/<deck-id>.md
  • scaffolds or updates the React/Spectacle deck code
  • switches local preview to that deck in src/App.tsx

Use npm run serve:deck -- <deck-id> to restart the local React app for that same deck and verify that it is serving on the local preview port.