Skip to content
TYPO3Soul Design System

Reference

What a reader looks up and cites.

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.

The facts of a change
text 
.. facts::

   :Change: `1482 <https://example.org/c/1482>`__ · patch set 2
   :Target: ``main`` · ``2.4``
   :Read: 2026-09-11, in a worktree of its own
Change

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.

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.

What a project renders from, and what it gets back
text 
.. directory-tree::
   :level: 2

   * ``docs/`` the sources, as a project already writes them

     * ``Index.rst``
     * ``guides.xml`` the theme, the mark and the versions

   * ``site/`` what the render writes, and what is published

     * ``index.html``
     * ``styles/`` the drop-in, copied there by the finishing step

       * ``soul.css``
       * ``soul.js``
  • docs/the sources, as a project already writes them
    • Index.rst
    • guides.xmlthe theme, the mark and the versions
  • site/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.

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.

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.

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 names its statements. The directive takes the body raw, so the parser of reStructuredText never reads it. It draws sds-diagram, and the finishing step renders the drawing before the page ships.

A drawing from the text under the directive
text 
.. diagram::

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

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.

name #
type
string

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

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.

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.

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.

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.

margin #
type
number

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

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.

swatch#

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

A palette, at the width a colour holds
text 
.. grid:: wide

   .. swatch:: var(--accent)
      :name: --accent
      :resolved: #FF8700

   .. swatch:: var(--text-primary)
      :name: --text-primary
      :resolved: light-dark(#18181B, #FAFAFA)

   .. swatch:: var(--border-subtle)
      :name: --border-subtle
      :resolved: light-dark(#E4E4E7, #27272A)
      :kind: line
--accent #FF8700
--text-primary light-dark(#18181B, #FAFAFA)
--border-subtle light-dark(#E4E4E7, #27272A)
the argument required #
type
string

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.

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.

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

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.

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.

A review's findings, two of them
text 
.. register::
   :name: findings
   :prefix: F
   :todo-prefix: T
   :findings:

   .. entry:: The unit suite for the lookup fails
      :group: blocks
      :origin: introduced by this change
      :todo: Adapt the four tests that expect the second read.

      Every case that resolves one key twice fails.

   .. entry:: The key stays the file's own identifier
      :group: ok

      Checked against a catalogue with a dotted key.
Entry Kind Origin
F1.1 The unit suite for the lookup fails blocks introduced by this change
F4.1 The key stays the file&#039;s own identifier checked —

To do

To do Kind
T1.1 Adapt the four tests that expect the second read. blocks

Blocks submission

F1.1

The unit suite for the lookup fails

blocks introduced by this change

Every case that resolves one key twice fails.

T1.1Adapt the four tests that expect the second read.

Checked and correct

F4.1

The key stays the file&#039;s own identifier

checked

Checked against a catalogue with a dotted key.
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.

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.

todo-prefix #
type
string

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

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.

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, which says how it numbers and what it draws.

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.

One entry, on its own
text 
.. entry:: The reader is a new instance per call
   :group: change
   :origin: older than the change
   :todo: Construct the reader once, in the constructor.

   The service is a singleton, so one reader in the constructor is the
   same object with one construction fewer per label.

The reader is a new instance per call

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.

Construct the reader once, in the constructor.

group #
type
string

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

origin #
type
string

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

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.

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.