Foundations

Documenting what your system owns

A derived design system inherits almost everything from Dessau. Now and then it builds its own — a component like Neon's site header, a pattern of its own, a writing rule the inherited standard does not cover. That page has to live in the reference too. This is the blank page it starts from, and the two head markers that put it in the navigation without editing a list.

When a system owns a page

Most of a derived system's reference is inherited unchanged. The exception is anything it builds itself — a component, a pattern, or a writing rule — which it now owns, along with the reference for it.

Do

Give the owned thing its own reference page, built from the blank page below. It carries the shell every inherited page has — the header navigation, the on-this-page list, the width switcher wiring, the script tags — so there is nothing to rebuild.

Don't

Wedge it into an inherited page next to things the system did not touch, or hand-copy an inherited page and strip it out. The first misfiles it; the second has every derived system reinventing the same shell, which is the job the reference tooling already exists to do once.

Products, too

A product that ships a genuinely different component under its own namespace is in the same position. It uses the same page, with dds-reference-owner set to product. See agent/recipes/override-a-component.md.

The blank page

One empty section, ready to fill. It is the same ref-section shape every inherited page uses: a heading and a short description, a specimen with a width switcher, do / don't guidance, and a note for the narrow state.

<section class="ref-section" id="siteheader">
  <div class="ref-section-head">
    <h2>Site header</h2>
    <p class="dds-text-subtle dds-measure-default dds-mbs-xs">
      One sentence on what this is and the one decision it makes.
    </p>
  </div>

  <div class="ref-specimen" data-ref-bp>
    <!-- your real markup, exactly as an author writes it -->
  </div>

  <div class="ref-guidance">
    <div class="ref-do">
      <h3>Do</h3>
      <p class="dds-text-sm">What to reach for, and why.</p>
    </div>
    <div class="ref-dont">
      <h3>Don't</h3>
      <p class="dds-text-sm">The tempting wrong turn, named.</p>
    </div>
  </div>

  <p class="ref-note">
    <svg class="dds-icon" aria-hidden="true"><use href="#dds-icon-info"/></svg>
    What the layout does below its container's narrow breakpoint.
  </p>
</section>

Information: Filling it in

Copy this file into your own reference/, renamed for the thing you own.
Set the <title>, the description, and the intro heading.
Point dds-reference-group at the navigation group it belongs in.
Replace the example section with one ref-section per variant you need to show.
Run sync-reference-nav.mjs, sync-reference-toc.mjs and sync-icons.mjs. The navigation, the on-this-page list and the icon sprite fill themselves in.

The head markers

Two <meta> tags in the document head are what make the page a first-class part of the reference rather than an orphan. They are read by sync-reference-nav.mjs before it renders anything.

The dds-reference-* head markers, whether each is required, and what it does
Marker	Required	What it does
`dds-reference-owner`	Yes	`derived` or `product`. Marks the page as owning what it documents, so the checks do not expect a matching entry in `agent/index.json`.
`dds-reference-group`	Yes	The label of the top-level navigation group the page joins — `Foundations`, `Components`, `Patterns`, `Writing`. A value that names no group is a build error, not a silent drop.
`dds-reference-nav-label`	No	The text for the navigation link. Falls back to the first part of the `<title>`.
`dds-reference-nav-order`	No	A number ordering this page among other owned pages in the same group. Unordered pages sort after ordered ones, by filename.

Any group, including the single-page ones

Components and Foundations already show a second row of pages, so an owned page is appended to it. Patterns and Writing are single pages today and have no second row — the first owned page pointed at one of them grows the row, with the inherited page as its first entry.

This page carries those markers itself. It is placed in the Foundations group by the markers alone — remove them and the build fails, which is the guarantee that the mechanism still works.

Doing it in a derived system

The steps are the same as for any reference page, plus the two markers. Everything downstream is generated.

Copy libs/dessau/reference/owned-pages.html into your own reference/.
Replace the example section with the component, pattern or rule you own, in your own markup and class names.
Set dds-reference-group to the group it belongs in.
Run your copied sync-reference-nav.mjs and sync-reference-toc.mjs. The page now appears in every other page's navigation, in the right group, with no edit to the STRUCTURE list.

Where this is written up

agent/recipes/derive-a-standalone-system.md, step 6, in the section on your own reference. Neon (ma6/neon#5) is the first derived system to do this — its own site header and footer, documented on a page built exactly this way.