---
title: "Reference"
description: "What a reader looks up and cites."
canonical: reference.html
navigation-title: "Reference"
---

<a id="reference"></a>

# Reference

- [facts](#facts)
- [directory-tree](#directory-tree)
- [diagram](#diagram)
- [swatch](#swatch)
- [register](#register)
- [entry](#entry)

What a reader looks up and cites.

<a id="directive-facts"></a>

<a id="facts"></a>

## facts

A block of facts, scanned down the terms. The body is a field list, which
is the shape a name-and-value pair already has in the source.

- **Change:** [1482](https://example.org/c/1482) · patch set 2
- **Target:** `main` · `2.4`
- **Read:** 2026-09-11, in a worktree of its own

The field's name is the term and its body the value, and a value carries a
link, a literal or a badge. The element is `sds-facts` in
[Data & machine output](../../frontend/components/data.md).

<a id="directive-directory-tree"></a>

<a id="directory-tree"></a>

## directory-tree

A directory, in the shape it has on disk, in the spelling a TYPO3 manual
already uses. So a page written for the other theme renders here as it is.

A nested list, because that is what a tree is. **The name is the first
literal in an item, and the rest of the line is what it is for.** A filename
is a literal anyway, and prose after it is prose about it, so there is no
syntax of this directive's own to learn. An item with no literal is a name
and nothing else.

```
docs/  — the sources, as a project already writes them  Index.rst  guides.xml  — the theme, the mark and the versionssite/  — what the render writes, and what is published  index.html  styles/  — the drop-in, copied there by the finishing step    soul.css    soul.js
```

The fold is `<details>`, so it works before a script runs and
find-in-page opens the directory it lands in. This replaces the tree as a
text block with its notes lined up with spaces. That alignment goes wrong
the moment one name changes by a character, and a reader with a narrow
window never sees it straight.

<a id="confval-directory-tree-level"></a>

**`level`**

- Type: integer
- Default: 2

How deep it stands **open**. Nothing drops below it. What is deeper
folds, which a reader can undo. A level past the depth of the tree opens
the whole of it.

The theme this spelling comes from stops the *draw* below the level
instead. That takes away what a reader came for and gives them no way to
ask for it. A page that set it for that reason still renders here, with
the deep part folded, not gone.

<a id="confval-directory-tree-show-file-icons"></a>

**`show-file-icons`**

- Type: flag

Mark a directory and a file as such. Off by default. The fold says which
is which wherever there is anything to fold, and a wall of glyphs down a
short tree is decoration. The slash in its name tells an empty directory
apart.

<a id="directive-diagram"></a>

<a id="diagram"></a>

## diagram

A drawing, written as the text that describes it. The body is the text of a
`.diagram` file as it is, one statement per line, and
[Diagrams](../../design-system/brand-and-imagery/diagrams/index.md) names its statements. The directive takes
the body raw, so the parser of reStructuredText never reads it. It draws
[sds-diagram](../../frontend/components/media.md#component-sds-diagram), and the finishing step renders
the drawing before the page ships.

```diagram
tiles
title "Needs met and open"
description "Two counts of needs."
tile "9" "met"
tile "23" "open" emphasis
```

A text the grammar refuses draws the refusal in the place of the drawing.
The message names the line or the part, so the author sees it on the page
they wrote. The finishing step then fails, so the page does not ship. The
Markdown twin holds the text in a fenced block. The drawing
has no caption and no frame of its own: the text of the document around it
says what it claims.

<a id="confval-diagram-name"></a>

**`name`**

- Type: string

The prefix of the ids inside the drawing. Two drawings with the same text
on one page need two names.

<a id="confval-diagram-caption"></a>

**`caption`**

- Type: string

The claim of the drawing. With it, the drawing stands in
`sds-figure`, with the caption under it. The frame and the caption are
the figure's.

<a id="confval-diagram-label"></a>

**`label`**

- Type: string

On a slide of the `row` layout, the word over the drawing: what it
shows, such as the product of a comparison.

<a id="confval-diagram-file"></a>

**`file`**

- Type: string

A `.diagram` file to read the text from, relative to the document,
or to the documentation root with a leading `/`. The directive then
has no body. A path that leads nowhere stops the render.

<a id="confval-diagram-canvas"></a>

**`canvas`**

- Type: string

The size of the drawing: `940` for the width of its column, `940,480` for
a height too. It stands over the size in the text.

<a id="confval-diagram-margin"></a>

**`margin`**

- Type: number

The free space on every side of the drawing. It stands over the margin in the
text.

<a id="confval-diagram-zoomable"></a>

**`zoomable`**

- Type: flag

A press on the drawing opens it at the size of the window, in the
page's tokens. For a drawing too dense to read in the column.

<a id="directive-swatch"></a>

<a id="swatch"></a>

## swatch

One colour of a palette: the chip, its name, and what it resolves to.

- **--accent** `var(--accent)` — `#FF8700`

- **--text-primary** `var(--text-primary)` — `light-dark(#18181B, #FAFAFA)`

- **--border-subtle** `var(--border-subtle)` — `light-dark(#E4E4E7, #27272A)`

<a id="confval-swatch-value"></a>

**`the argument`**

- Type: string
- Required

What paints the chip: a token as written, `var(--accent)`, or a literal
where the value belongs to a mode the page is not in. It is the argument
because it is what the line is about. **Anything that is not a colour
drops out, and nothing paints it.** The value arrives from a document,
and a style attribute is not where a theme finds out what it is.

<a id="confval-swatch-name"></a>

**`name`**

- Type: string

The name of the colour. The token where there is one, because that is
the name a design writes. The human name where the palette has no
tokens.

<a id="confval-swatch-resolved"></a>

**`resolved`**

- Type: string

What that name resolves to, in full. A token alone documents half the
system. The value is the half that says what the mode did with it, and a
pair stands as the pair: `light-dark(#FFFFFF, #141414)`.

<a id="confval-swatch-kind"></a>

**`kind`**

- Type: string

`fill` (the default) or `line`. A hairline is a colour too and cannot
show as a fill. At one pixel a value is invisible, and as a fill it is a
different job by the same number. `line` makes the chip its own edge,
with the page's ground inside it.

**There is no body.** A colour that needs a paragraph carries a rule about
where it can appear. That rule is prose beside the palette, not inside one
entry of it.

**A palette is a set**, so it goes in `grid` like any other. At `wide`,
the width a name and a `light-dark()` pair under it hold. The element is
`sds-swatch` in [Content](../../frontend/components/content.md).

<a id="directive-register"></a>

<a id="register"></a>

## register

A list a reader cites: numbered, addressed, and scanned at a glance first.
The entries stand in the body in any order. The register numbers them when
the page renders, sorts them into their groups, and writes every one into
one table first. Every entry with a `:todo:` goes into a second table, the
work the list asks for. No line of the document says a number.

**The unit suite for the lookup fails** (blocks, introduced by this change)
Every case that resolves one key twice fails.

To do: Adapt the four tests that expect the second read.

**The key stays the file's own identifier** (ok)
Checked against a catalogue with a dotted key.

<a id="confval-register-name"></a>

**`name`**

- Type: string
- Default: "register"

What the group sections and the entries' addresses start with,
`findings-blocks` and `findings-1-1`, so two registers on one page
keep apart.

<a id="confval-register-prefix"></a>

**`prefix`**

- Type: string

What stands before every entry's number, `F` for findings. Nothing
unless the register says so: an entry is `1.1` by itself.

<a id="confval-register-todo-prefix"></a>

**`todo-prefix`**

- Type: string

What stands before the number of what is to do, `T` for the work a
finding asks for.

<a id="confval-register-findings"></a>

**`findings`**

- Type: flag

The four groups of a review's findings, in the order a review reads
them: *Blocks submission*, *Sent back*, *Worth a change*, *Checked and
correct*. Their keys are `blocks`, `back`, `change` and `ok`.

<a id="confval-register-groups"></a>

**`groups`**

- Type: string

Any other set of groups, as the JSON the element takes:
`[{ "key": "…", "heading": "…", "label": "…", "tone": "…" }]`. An
entry whose group the register does not name stands last, in the order
written. Without groups the entries count up as written.

The element is `sds-register` in [Content](../../frontend/components/content.md),
which says how it numbers and what it draws.

<a id="directive-entry"></a>

<a id="entry"></a>

## entry

One entry of a register. Its title is the argument, what it holds the
body, and everything that fits in a string an option.

**The reader is a new instance per call** (change, older than the change)
The service is a singleton, so one reader in the constructor is the
same object with one construction fewer per label.

To do: Construct the reader once, in the constructor.

<a id="confval-entry-group"></a>

**`group`**

- Type: string

The key of the group it belongs to, for the register that groups.

<a id="confval-entry-origin"></a>

**`origin`**

- Type: string

Where it came from, in a few words: `introduced by this change`,
`older than the change`.

<a id="confval-entry-todo"></a>

**`todo`**

- Type: string

What is to do about it, in one sentence. It stands as the entry's last
line, and the register lists it with the work of the other entries.

<a id="confval-entry-name"></a>

**`name`**

- Type: string

The address of this one entry, where the register's own, made from the
number, is not the one a page wants to cite.