Skip to content

Playbook

The documentation on this site is created and edited by a variety of contributors. If you would like to contribute to the documentation, follow the steps below.

  1. Request access to GitHub.

  2. Learn about using Markdown basic syntax.

  3. Create or edit any .md (or .mdx) files in src/content/docs/ directory. All files within are mapped to a filename based URL structure.

    Eg. the content at src/content/docs/start/contribute.mdx is available at /start/contribute as you can see in the current URL.

    Any documentation nested within directories will be automatically included in the sidebar navigation. For advanced use-cases you can configure sidebar in astro.config.js.

  4. Additional reading for more advanced content.

Tabbed component pages

Section titled “Tabbed component pages”

Components under cds/components/ use a tabbed layout — Design / Develop / Accessibility — driven by per-tab MDX files. The leaf page sits next to a <name>-pages/ folder; each MDX inside becomes a tab.

cds/components/
├── <name>.mdx                # overview paragraph + <SubpageTabs />
└── <name>-pages/
    ├── _meta.yml             # hidden: true, tabs: true
    ├── design.mdx
    ├── develop.mdx
    └── accessibility.mdx

What each tab carries:

  • Design — anatomy, when to use it, properties, states, modes, styling tokens, usage guidelines. Sourced from Figma.
  • Develop — <DxpContent.Code> snippets for the canonical markup, variants, sizes, and states. Snippets include ARIA wiring so they are copy-pasteable.
  • Accessibility — ## For designers and ## For developers sections covering canonical markup, keyboard interactions, and the relevant WAI-ARIA APG pattern.

<DxpLayout.*> and <DxpContent.*> helpers

Section titled “<DxpLayout.*> and <DxpContent.*> helpers”

Design tab MDX files use a small set of helpers. The card / grid primitives live in ~/components/layout/; the anatomy + token-table helpers live in ~/components/content/:

import * as DxpContent from '~/components/content/index.astro';
import * as DxpLayout from '~/components/layout/index.astro';

The alias names must be DxpContent and DxpLayout, not Content or Layout — Astro’s MDX integration appends Content[Symbol.for('mdx-component')] = true to every compiled MDX, and a user-side import * as Content shadows that and crashes the build (module-namespace objects are non-extensible).

Helpers for the Design tab template:

Component Purpose
<DxpLayout.CardGrid hasHero? min?> Responsive auto-fit grid. hasHero spans the first child; min controls the auto-fit floor (default 280px).
<DxpLayout.CardStack> Single-column stack of cards. Used for the Properties section.
<DxpLayout.TitleCard title tile? placeholder?> The everyday content card — <h3> title + body slot. tile="…" inlines an SVG from src/content/; frame slot accepts custom media; default placeholder is a tng-slot wireframe.
<DxpLayout.Card> Pure layout primitive. Two children: a .tng-frame element + a single caption. Container-query horizontal/vertical at ≥ 600px. Use directly only when TitleCard’s shape doesn’t fit.
<DxpContent.Anatomy> + <DxpContent.AnatomyPin number> Anatomy hero (component demo or wireframe) + numbered pin list.
<DxpContent.TokenList name?, type?, numeric?> Vertical token swatch list. Canonical for cds/foundations/tokens/*.mdx and fundamentals/{color,typography}.mdx; don’t use it in design.mdx.

The legacy helpers — <DxpContent.Guidance>, <DxpContent.Card> + <DxpContent.PropertyGroup> + <DxpContent.Property>, <DxpContent.TokenValue>, <DxpContent.VariablesTable> + <DxpContent.VariablesRow> + <DxpContent.VariablesTextStyleRow> — were removed in the consolidation that introduced these primitives. The old Figma.Grid and Figma.ImageBlock went with them.

For the longer reference (per-tab content shape, SubpageTabs internals), see playbook/CONTRIBUTING.md and the repo-level AGENTS.md.