# Reference document format

Component pages use GitHub-flavored Markdown. Pages under `getting-started/`, `guides/` and `maintain/` use ordinary Markdown and are not parsed as component or foundation tables. Keep one file per component in `components/`, with a lowercase kebab-case filename. No frontmatter, Svelte template markup or executable documentation directives are required.

## Sections

Each folder is a section: `getting-started/`, `foundations/`, `components/`, `guides/` and `maintain/`. Its `README.md` introduces the section and lists every page of the folder exactly once, in reading order: a list item that opens with a link to a page of the folder lists that page. Level-two headings group the list, as in the component categories; a list before the first level-two heading forms one group. The DS builds its navigation from these lists and fails when a page is missing or listed twice. The root [index](../README.md) links to the five sections.

## Components

- Start with one level-one heading containing the exact exported component name.
- Follow it with one introductory paragraph stating the component's purpose. The rendered reference preserves its Markdown formatting.
- Order the sections as they are read: Usage, Notes, Parameters, Overrides, Methods, Accessibility. The DS renders every document in file order.
- `## Parameters` contains one table with the exact columns `Name`, `Type`, `Default`, `Description`. Use `Required` for mandatory inputs and `undefined` for an omitted optional value; cells must not be empty. Names must be unique.
- For a component with no props, `## Parameters` contains exactly `None.` instead of a table.
- Optional `## Overrides` contains a table with `Name`, `Type`, `Default`, `Description` for public CSS overrides.
- Optional `## Methods` contains one table with the columns `Name`, `Description`.
- Optional `## Notes` contains one list of concise API notes, including forwarded attributes or behavior not captured by a parameter row. Keep these readable outside interactive examples.
- `## Usage` contains prose and at least one fenced `svelte` example. Examples include their imports and any state they use. Code fences display source; they do not execute it.
- `## Accessibility` describes names, keyboard interaction, disabled behavior and other relevant constraints.

Section names form the extraction contract. Duplicate, unknown or missing required sections fail the DS build with the component name. API coverage compares documented parameters and methods with the source, checks declared JSDoc types and verifies defaults, including bindable and explicitly covered computed defaults. Extend this contract deliberately before introducing a new section; do not silently invent a different format for one component.

## Foundations

Keep one file per foundation subject in `foundations/`; each renders as one subject page, in the order of the [section index](../foundations/README.md). Start with the title and at least one introductory paragraph; the first paragraph is the subject's description in navigation and search. Then use level-two sections in reading order.

A subject section that documents tokens begins with a paragraph and contains one table with the exact columns `Token`, `Role`. Use the full CSS name with `--`. Rows define token membership and order; do not copy CSS values into Markdown. Prose, lists, level-three headings and fenced examples after the table provide detailed usage guidance. Sections without tokens, such as theme selection or native forms, contain guidance only.

A subject with shared classes adds a class reference after its token sections:

- `## Classes`: one table with the columns `Name`, `Description`; list exact class names and explain their effect.
- Optional `## Overrides`: one table with `Name`, `Type`, `Default`, `Description`; include public CSS settings needed for this topic.
- Optional `## Notes`: one list covering combinations, inheritance, semantics and constraints.
- `## Usage`: at least one fenced `html` or `svelte` example. Svelte examples include their imports.

Every token in `tokens.css` and every custom media name in `breakpoints.css` has exactly one documented role across the foundation pages. The DS loader rejects missing, unknown or duplicate token names, empty roles, malformed token or class tables, duplicate sections and raw HTML. New CSS tokens must receive a documented role in the same change. The first table row naming a token or class owns its anchor; a later mention, such as an override, does not repeat it.

The [section index](../foundations/README.md) explains naming, choosing and overriding tokens in ordinary Markdown. A subject page without tokens or classes, such as [document defaults](../foundations/document.md), contains guidance only. A DS page can show specimens under a section heading, by its anchor; renaming that heading requires updating the page.

## Markdown conventions

Use code spans for signatures, defaults and identifiers. Escape a literal pipe as `\|` inside a table cell, including inside a code span: `string \| false \| Snippet`. The Markdown parser resolves it to a literal pipe in the rendered reference.

Use ordinary paragraphs, emphasis, lists and fenced code in Usage and Accessibility. Raw HTML is rejected; keep Svelte examples inside code fences. These documents are trusted repository content, not a user-uploaded Markdown input. The demo renders the parsed prose but never evaluates its examples as code.

Use relative links between documentation files, including heading anchors when needed. The DS renders these as links to the page URLs and validates document destinations and anchors. The heading anchor `main` becomes `document-main` to preserve the app's unique main landmark and skip-link destination. Links outside `docs/` open the repository source. Check those file destinations locally as well.

## Rendering

The DS application owns extraction and rendering: page URLs, raw Markdown endpoints, framed tables, CSS definitions beside token tables and the specimens a page adds under its section headings. Its [README](../../../../apps/ds/README.md) documents these conventions. Rendered pages and agent-readable sources use these same canonical files rather than separately maintained prose.