Reference document format

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 links to the five sections.

• 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.

Keep one file per foundation subject in foundations/; each renders as one subject page, in the order of the section index. 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 explains naming, choosing and overriding tokens in ordinary Markdown. A subject page without tokens or classes, such as document defaults, contains guidance only. A DS page can show specimens under a section heading, by its anchor; renaming that heading requires updating the page.

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.

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 documents these conventions. Rendered pages and agent-readable sources use these same canonical files rather than separately maintained prose.