Documentation

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.

   Tip

   If you are not comfortable using git you can easily edit files directly on GitHub by clicking the ‘Edit page’ link at the bottom of each page.

   Make sure to create a Pull Request when doing this, so all changes can be team reviewed.

   

4. Additional reading for more advanced content.

   Note

   The previous steps are more than enough to make meaningful contributions to the documentation.

   However if you have a technical basis, continue with these resources to create more advanced content.

   • CommonMark Spec
   • What is MDX
   • Astro & Markdown
   • Starlight & Markdown
   • Starlight Components

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

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 documentation/CONTRIBUTING.md and the repo-level AGENTS.md.