---
title: "Directives"
description: "The directives this theme adds to what an author can write, and the document field."
canonical: directives.html
navigation-title: "Directives"
---
# Directives
- [layout](#layout)
- [hero](#hero)
- [band](#band)
- [grid](#grid)
- [split](#split)
- [half](#half)
- [card](#card)
- [stat](#stat)
- [swatch](#swatch)
- [surface](#surface)
- [quote](#quote)
- [button](#button)
- [button-bar](#button-bar)
- [directory-tree](#directory-tree)
- [accordion](#accordion)
- [accordion-item](#accordion-item)
- [facts](#facts)
- [register](#register)
- [entry](#entry)
- [steps](#steps)
- [step](#step)
- [example](#example)
- [specimen](#specimen)
The directives this theme adds to what an author can write, and the document
field. The extension registers them, so a project with the theme can use
them at once. There is nothing to add to `guides.xml` and no template to
copy.
| Written | What it is for | Draws |
| --- | --- | --- |
| `:layout:` | a field, not a directive: which of the two shapes the page takes | — |
| `hero` | the opening claim of a landing page, beside one image | `.sds-split` and `sds-figure` |
| `band` | a full-bleed section of a landing page, and everything after it | `.sds-band` |
| `grid` | a set read side by side, reflowed by its own minimum width | `sds-grid` |
| `split` | two of anything, side by side until there is no room for two | `.sds-split` |
| `half` | one side of a split, where that side is several blocks | `.sds-stack` |
| `card` | a way into something: a title that goes somewhere, and what is behind it | `sds-card` |
| `stat` | one number as a fact | `sds-stat` |
| `surface` | one filled plane, with a statement in place | `sds-surface` |
| `quote` | a sentence from somewhere else, with its source | `sds-quote` |
| `button` | one press, and where it goes | `sds-button` |
| `button-bar` | the presses of a page, in one row | `.sds-actions` |
| `accordion`, `accordion-item` | questions with their answers folded behind them | `sds-accordion` |
| `steps`, `step` | an instruction read from the top, numbered down one rail | `sds-steps` |
| `facts` | a block of facts, scanned down the terms | `sds-facts` |
| `register`, `entry` | a list a reader cites: numbered, addressed, and the work it asks for | `sds-register` |
| `example` | a piece of markup and, under it, what it renders as | `sds-code` in `.sds-example` |
| `specimen` | a rendered card, at the size of its measurement | `sds-embed` |
Each of them draws an element of this system and takes that element's own
options, spelt the way the element spells them. So `href` links and
`src` takes a file here as everywhere else, and what a component gains,
the directive gains with it. Every section below names the element it
draws, and [Components](../frontend/components/index.md) is that element's reference.
Every example on this page stands once: the block is the body that drew
the thing under it, which is what `example` is for.
## layout
Not a directive. A field at the top of a document, beside the navigation
title, and it decides which shape the page takes.
```text
:navigation-title: Overview
:layout: marketing
================
What this is for
================
```
**`layout`**
- Type: string
- Default: "default"
`marketing` renders the page as a run of full-bleed bands with no rail.
Anything else, and a page with no such field, is the manual shape. The
toctree in a rail on the left, the trail above the title, the text held
to sixty-six characters.
Both shapes carry the same bar and the same footer, because a reader must
never have to work out which site they are on. The body changes.
> [!NOTE]
> A field is invisible only because something claimed it. One nobody
> claims renders as a definition list in the body, which is what a
> misspelt field looks like. `:laoyut: marketing` prints the word and the
> value above the title of a page that is still a manual.
## hero
The opening claim of a marketing page, beside one decorative image. It goes
right after the document title, so the title stays the page's real heading,
browser title and source for navigation.
The opening summary belongs inside the directive.
The document title stands above it in the source and is not part of it. The
argument is the image source. The theme composes the split, the stack and
the figure it already has. At a narrow viewport that split becomes a column
by the rule of every other split in the system. Content after the hero and
before the next band stays part of the opening section.
**`alt`**
- Type: string
- Default: ""
What the image shows, when it adds a meaning the copy lacks. Leave it out
for a decorative illustration whose subject already has its name beside
it.
## band
A full-bleed section of a landing page. The ground runs edge to edge, and
the content inside keeps the page measure.
## This heading is a band, on a manual page
And the paragraph after it, beside the section
rather than inside it. What follows a band
belongs to it on a page built out of bands.
This page is not one.
On a page whose layout is not `marketing`, that is the whole of it: a
section inside the column, not a ground edge to edge. The page decides the
shape a band takes, not the band.
**A band does not wrap a page in itself. It opens one.** What follows belongs
to it until the next band starts. What stands before the first one is a
band as well: a page opens on the canvas. That is the whole syntax, and it
has a reason beyond a tidy source.
A band is full-bleed and takes the page inset itself. So a band inside another indents its text by a gutter nobody
asked for, and stops at the width of its parent.
```text
.. band:: What it costs
:quiet:
:id: pricing
Everything from here, up to the next band.
.. band::
And this is back on the canvas.
```
That one is a print, not a render, and it is the only source on this page
that is. What a band does with the content after it happens where the page
is bands. Here it renders as two sections with the text loose between them,
which is what the example above shows.
A page with no band at all is the single band it looks like.
**`quiet`**
- Type: flag
The second ground. Quiet and plain in turn make a run of bands read as a
sequence, not as a wall. Two bands in a row share one hairline.
**`id`**
- Type: string
An anchor, so a link elsewhere on the site can land on this section.
**`the heading`**
- Type: string
The band's argument. It is an option and not a section heading, because
a section heading inside a directive is not one. reStructuredText parses
sections at document level. A line with `====` under it, written in
here, ships both the line and the equals signs as text.
The landing page of [the example project](example.md) is the same
directive at home, with the run of them at work.
## grid
A set read side by side, reflowed by its own minimum width.
**[What it is](index.md)**
A badge above the title, and the whole
card lit at the top of its frame under
the pointer. A paragraph long enough to
decide how tall this row is. That is the
only thing the card beside it has to
agree with.
**[What it costs](installation.md)**
One Composer package.
No column count, and that is the design. Three across on a desk, two on a
tablet, one on a phone, from how narrow an item can get, not from a
breakpoint. It holds cards, figures, or anything else read as a set. Each
item draws itself, and the grid decides how many stand in a row.
The two above differ in length on purpose. A set whose items say the same
amount cannot show what the wall does. The short one draws to the row, not
to its own sentence. The element is `sds-grid` in
[Content](../frontend/components/content.md).
**`the argument`**
- Type: default | wide | dense | flush
How much room one item needs, said as what the items hold, not as a
number. `wide` for a card with a picture and a paragraph, `dense` for
a figure or a name and a glyph. `flush` takes the gutter out, so the
set shares a hairline and reads as one wall. Without it the set gets the
width every set gets. A name the element does not define falls back, and
does not pass through. `:variant:` says the same thing as an option.
**`class`**
- Type: string
Carried onto the element. An author who wrote it meant it for their own
stylesheet, and a theme must not drop what it does not understand.
## split
Two of anything, side by side until there is no room for two.
A paragraph and a picture are two blocks,
so they stand as two columns and nothing
here says which is which.
**Every block in it is a column.** That is the whole rule, and why the
example above needs nothing to mark its halves. A paragraph is one block,
and a figure is another. The moment a side is a heading, its paragraph and
a press, those are three columns, unless something says where the side
ends. `half` is that something.
No width and no count anywhere. The halves fold under each other by their
own minimum, the way every set in this system reflows. The class is
`.sds-split` in [Page layout](../frontend/layout.md).
**`align`**
- Type: start | center | end
Where the shorter half stands against the taller one: at the top, level
with it, or at the foot. `start` is the default, and `center` is what
a line beside a picture usually wants.
**`leads`**
- Type: start | end
Which half comes first once the two have stacked. `start` is the
written order. `end` puts the second half above the first. A picture at
the end of the line on a page, and above the sentence it illustrates on a
phone. It changes nothing while the two fit side by side. The order a
reader reads is not the source order at every width, and the layout
cannot work that one out itself.
**`class`**
- Type: string
Carried onto the split, for the reason the grid's is.
## half
One side of a split: the blocks that stand together as one column.
## Two paragraphs, one side
This is the first of them, and it is not a
column.
This is the second. Without the `half`
around both, it is one.
It takes no position of its own. The split decides where a half stands,
because the other half is what it stands against. Anywhere else it is the
blocks it holds, in the rhythm a page keeps between them. Its optional
argument becomes an `h2` inside the column. Use it when the heading names
that side, not both sides of the split. A reStructuredText section heading
has no place inside a directive.
**`class`**
- Type: string
Carried onto the column, for the reason `split` carries it.
## card
One card: a title that goes somewhere, and what is behind it.
**[Installation](installation.md)**
What the package needs, and the commands that
render a project with it.
For a desk
**`href`**
- Type: string
A document, as a `:doc:` reference spells it, resolved per page. It is
the same thing the title's own reference says, for a card whose title is
plain text. Where both stand, this one wins.
**`label`**
- Type: string
The tracked-out line over the title. The name or number of a set of
cards, `CHAPTER 02`, `FOR EDITORS`, or the date of an entry. The same
register and the same line.
**`tag`**
- Type: string
What kind of thing the card is, in the badge beside the label. A fact
about the card, not a result, so it carries no tone and no glyph. The
row drops where neither this nor the label stands.
**`icon`**
- Type: string
A glyph above the label, for a set a reader tells apart before a read.
The name is an icon of this system; see [Icons](../design-system/icons.md).
**`src`**
- Type: string
The picture, flush at the top of the card. The render copies a path in
the documentation source into the output and resolves it per page. A URL
somewhere else stays as it is. Either way it is one ``, so a
drawing arrives in the colours its file declares.
[Artwork](../design-system/artwork.md) says why, and what the file has to be ready
for.
The name is `src` here and on the element, because everything in this
system that takes a file has that name.
**`alt`**
- Type: string
What the picture shows, for a reader who cannot see it. Written and
empty says decorative, a card whose art only repeats the title. Left out
entirely says nobody decided, which reads very differently.
**`footer`**
- Type: string
One line under a hairline at the foot of the card: what the reader gets
there, who it is for, what state it is in.
**`action`**
- Type: string
The call to action, in words: `Read it`. Not a button and not a second
link. The whole card already goes there, so this is the line that says
so, and the arrow after it leans out under the pointer. Drawn only where
the card has somewhere to go.
**`class`**
- Type: string
Carried onto the element, for the reason the grid's is.
**The title carries the target.** \``.. card:: :ref:`Introduction
\\`\`\` is how a TYPO3 manual writes a card. The words of the
reference become the heading, and the reference becomes where the card
goes. A plain title with `:href:` says the same thing the other way round.
**The whole card is the link, and there is exactly one.** The title's anchor
stretches over the frame. So a screen reader announces the title, while a
pointer hits the card. A second anchor inside it is a second destination
under one frame, which is why there is no option for a button. A link in
the prose of a card still works, and is a card that asks to be two cards.
**The options are \`\`sds-card\`\`'s properties, all of them, spelt the way the
element spells them.** A directive that draws a component and answers for
half of it sends the author to their own stylesheet for the other half.
That is the one thing this system exists to prevent.
One that renames what it carries makes them translate a card they have
already read. `href` links and
`src` takes a file here for the reason they do everywhere else. What the
element gains, this gains. Its reference is `sds-card` in
[Content](../frontend/components/content.md).
The node is `sds-card` itself and not a `div` with its classes. The
element is the front door here as everywhere else. So the card draws in one
file, and a rendered page cannot drift from one a product wrote. The template
writes none of the card. It sets the options above and lets the element
draw its own markup, which is what makes the card the component's to
change.
A reader with no JavaScript gets the whole of it anyway. Every element in
the site renders before the publish. So the picture, the row, the title and
the summary are in the document with no script. In a browser the element
upgrades over that rendering. This is the theme-wide arrangement,
not the card's own; see [Core markup, and what it becomes](markup.md).
## stat
One number as a fact: the figure, what the count is of, and the line that
bounds it.
**240 ms** — median answer
Measured over the last release, on a warm index.
**2 of 3** — sources answering
One is slow and one is unreachable from the checker.
**`the argument`**
- Type: string
- Required
The figure, `5`, `240`, `12.4+`, never "many". It is the argument
and not an option because it is what the line is about.
**`unit`**
- Type: string
What the figure is in: `ms`, `%`, `kB`. The element sets it a step
down. It joins it to the number with the narrow no-break space a figure
must not split from, so no page has to know that character.
**`label`**
- Type: string
What the count is of, under the figure and in the label register.
**`of`**
- Type: string
The whole the figure is a part of, after it: `2 of 3`. Only where the
figure is a part. A measurement is out of nothing. It is words and not a
bar, so every figure in a set keeps the same shape and their notes start
on one line.
**`icon`**
- Type: string
A glyph on the figure's line, before the number. Muted and never in a
status colour, for the reason a card's is. A figure is a subject, not a
result.
**`class`**
- Type: string
Carried onto the element, for the reason the grid's is.
**The body is the bound, and in practice it is mandatory.** "5 sources" says
nothing until it says which five. A figure with no bound is a claim, not a
fact, which is the whole reason `sds-stat` is a component. It stands
between the tags, not as an option, because out of a document that line
carries links.
**A set of figures is a set**, so it goes in `grid` like any other. At
`dense`, the width a number and the line under it hold. `flush` works
too. There the figures share a hairline, and the wall gives each its ground.
The frame in a wall is the wall's. So a figure anywhere else stays bare, and
a row of numbers on a page is not a row of boxes. The element is
`sds-stat` in [Content](../frontend/components/content.md), beside its grid.
## 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(#1C1A17, #EDE9E2)`
- **--border-subtle** `var(--border-subtle)` — `light-dark(#E3DFD6, #2B2823)`
**`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.
**`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, #171614)`.
**`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.
**`class`**
- Type: string
Carried onto the element, for the reason the grid's is.
**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).
## surface
One filled plane, with a statement in place.
The tool reads every source. It writes nothing back.
**Rule 02**
Their origins tell two answers that disagree
apart.
**`the argument`**
- Type: string
- Required
The title of the plane, in the quieter register. This is not a
destination, and a title that looks like one is a promise the box does
not keep.
**`plane`**
- Type: string
The fill. `raised` sits on the canvas and reads as a plane. `sunken`
is machine output: code, logs, structured content. Named for the fill,
because in a system with no shadows that is what tells two planes apart.
`raised` is the default.
**`label`**
- Type: string
The tracked-out line over the title, where a set has numbers or sources:
`AUDIENCE 01`, `SOURCE`, `STEP 02`. Over the title, not in it. A
title with its own number reads as part of the sentence.
**`icon`**
- Type: string
A glyph above the label, where a reader tells a set apart before a read.
It stands beside the plane's own title, never alone, and takes the muted
ink for the reason a card's does. A plane is a subject, not a result.
**`class`**
- Type: string
Carried onto the element, for the reason the grid's is.
**A plane states, a card goes somewhere.** That is the whole line between
the two, and it decides which one a page wants. A card's frame is the link
and its title is the anchor, so a set of planes claims nothing to click.
Neither is what `.. topic::` is. A digression in the reading flow that the
outline does not list stays an `