The layouts
Every layout is a live page under Slides in the sidebar, in the order a deck runs, and a static screen the documentation embeds. A story opens on a stage, the slide fitted to the window with air around it. The static file is its own viewport.
Under each picture stands the markup an author writes for it. It shows
the slide as a deck holds it: the deck says the lockup and the count
once. make cards writes it from the same story as the picture, so the
two never disagree.
The frame#
<sds-slide kind="cover" ground="terminal">
<span slot="eyebrow">Design system · 2026</span>
<h2 slot="heading">One system, every surface</h2>
<p slot="lead">Custom elements, tokens and the class layer they emit. For pages, for documentation, and for a deck.</p>
</sds-slide>
Cover, as a deck holds it
html
<sds-slide kind="cover" ground="terminal">
<span slot="eyebrow">Design system · 2026</span>
<h2 slot="heading">One system, every surface</h2>
<p slot="lead">Custom elements, tokens and the class layer they emit. For pages, for documentation, and for a deck.</p>
</sds-slide>
<sds-slide kind="speaker">
<span slot="eyebrow">01 · Why one system</span>
<h2 slot="heading">Benjamin Kott</h2>
<p slot="lead">Maintainer · Soul Design System</p>
<p>Answers for the tokens, the elements and the gate that holds them together.</p>
<sds-image slot="portrait" src="assets/portraits/benjamin-kott.webp" alt="Benjamin Kott, drawn: cap, beard, hands in the pockets"></sds-image>
</sds-slide>
Speaker, as a deck holds it
html
<sds-slide kind="speaker">
<span slot="eyebrow">01 · Why one system</span>
<h2 slot="heading">Benjamin Kott</h2>
<p slot="lead">Maintainer · Soul Design System</p>
<p>Answers for the tokens, the elements and the gate that holds them together.</p>
<sds-image slot="portrait" src="assets/portraits/benjamin-kott.webp" alt="Benjamin Kott, drawn: cap, beard, hands in the pockets"></sds-image>
</sds-slide>
<sds-slide>
<span slot="eyebrow">01 · Why one system</span>
<h2 slot="heading">Who is speaking</h2>
<sds-grid>
<sds-surface plane="plain">
<span slot="label">Speaker 01</span>
<sds-byline name="Benjamin Kott" initials="BK" as="maintainer" meta="Soul Design System"></sds-byline>
<p>Answers for the tokens, the elements and the gate that holds them together.</p>
</sds-surface>
<sds-surface plane="plain">
<span slot="label">Speaker 02</span>
<sds-byline name="Jonas Riis" initials="JR" as="lead integrator" meta="Nordlys Digital"></sds-byline>
<p>Answers for the first project that shipped on it, and for what it lacked.</p>
</sds-surface>
</sds-grid>
</sds-slide>
Speakers, as a deck holds it
html
<sds-slide>
<span slot="eyebrow">01 · Why one system</span>
<h2 slot="heading">Who is speaking</h2>
<sds-grid>
<sds-surface plane="plain">
<span slot="label">Speaker 01</span>
<sds-byline name="Benjamin Kott" initials="BK" as="maintainer" meta="Soul Design System"></sds-byline>
<p>Answers for the tokens, the elements and the gate that holds them together.</p>
</sds-surface>
<sds-surface plane="plain">
<span slot="label">Speaker 02</span>
<sds-byline name="Jonas Riis" initials="JR" as="lead integrator" meta="Nordlys Digital"></sds-byline>
<p>Answers for the first project that shipped on it, and for what it lacked.</p>
</sds-surface>
</sds-grid>
</sds-slide>
<sds-slide kind="section" sections="["Why one system","What it consists of","How to build a slide","Where to start"]" current="1">
<span slot="eyebrow">Section 02 of 04</span>
<h2 slot="heading">What it consists of</h2>
</sds-slide>
Section, as a deck holds it
html
<sds-slide kind="section" sections="["Why one system","What it consists of","How to build a slide","Where to start"]" current="1">
<span slot="eyebrow">Section 02 of 04</span>
<h2 slot="heading">What it consists of</h2>
</sds-slide>
<sds-slide kind="statement">
<span slot="eyebrow">02 · What it consists of</span>
<h2 slot="heading">A shadow says a surface has left the page, and nothing else says it.</h2>
<p slot="note">Non-negotiable · docs/design-system/index.rst</p>
</sds-slide>
Statement, as a deck holds it
html
<sds-slide kind="statement">
<span slot="eyebrow">02 · What it consists of</span>
<h2 slot="heading">A shadow says a surface has left the page, and nothing else says it.</h2>
<p slot="note">Non-negotiable · docs/design-system/index.rst</p>
</sds-slide>
<sds-slide kind="closing">
<span slot="eyebrow">04 · Where to start</span>
<h2 slot="heading">Start from a layout</h2>
<p slot="lead">Open the one nearest the job and keep its shell. An element answers what one part looks like.</p>
</sds-slide>
Closing, as a deck holds it
html
<sds-slide kind="closing">
<span slot="eyebrow">04 · Where to start</span>
<h2 slot="heading">Start from a layout</h2>
<p slot="lead">Open the one nearest the job and keep its shell. An element answers what one part looks like.</p>
</sds-slide>
The content#
<sds-slide>
<span slot="eyebrow">02 · What it consists of</span>
<h2 slot="heading">Three places for every component</h2>
<sds-grid>
<sds-surface>
<span slot="label">Story</span>
<span slot="heading">Every element has one</span>
The source of every specimen card. Edit the story, never the card.
</sds-surface>
<sds-surface>
<span slot="label">Specimen</span>
<span slot="heading">Something draws every class</span>
A card or an element draws each class, so a rule and its rendering cannot drift apart.
</sds-surface>
<sds-surface>
<span slot="label">Rendered page</span>
<span slot="heading">The Guides renderer made it</span>
A page built on the system follows the layouts and invents no class.
</sds-surface>
</sds-grid>
</sds-slide>
Cards, as a deck holds it
html
<sds-slide>
<span slot="eyebrow">02 · What it consists of</span>
<h2 slot="heading">Three places for every component</h2>
<sds-grid>
<sds-surface>
<span slot="label">Story</span>
<span slot="heading">Every element has one</span>
The source of every specimen card. Edit the story, never the card.
</sds-surface>
<sds-surface>
<span slot="label">Specimen</span>
<span slot="heading">Something draws every class</span>
A card or an element draws each class, so a rule and its rendering cannot drift apart.
</sds-surface>
<sds-surface>
<span slot="label">Rendered page</span>
<span slot="heading">The Guides renderer made it</span>
A page built on the system follows the layouts and invents no class.
</sds-surface>
</sds-grid>
</sds-slide>
<sds-slide>
<span slot="eyebrow">02 · What it consists of</span>
<h2 slot="heading">Three rules the system keeps</h2>
<sds-grid variant="default" columns="3" data-sds-prop="0"></sds-grid>
</sds-slide>
Columns, as a deck holds it
html
<sds-slide>
<span slot="eyebrow">02 · What it consists of</span>
<h2 slot="heading">Three rules the system keeps</h2>
<sds-grid variant="default" columns="3" data-sds-prop="0"></sds-grid>
</sds-slide>
<sds-slide>
<span slot="eyebrow">02 · What it consists of</span>
<h2 slot="heading">Truth runs story → card → page</h2>
<sds-steps>
<sds-step heading="The story">Under stories/. The one place somebody writes a specimen.</sds-step>
<sds-step heading="The card">Under specimens/. A task generates it, and the next generate reverts an edit by hand.</sds-step>
<sds-step heading="The page">Under docs/. It embeds the same card the design system photographs into its sections.</sds-step>
</sds-steps>
</sds-slide>
Flow, as a deck holds it
html
<sds-slide>
<span slot="eyebrow">02 · What it consists of</span>
<h2 slot="heading">Truth runs story → card → page</h2>
<sds-steps>
<sds-step heading="The story">Under stories/. The one place somebody writes a specimen.</sds-step>
<sds-step heading="The card">Under specimens/. A task generates it, and the next generate reverts an edit by hand.</sds-step>
<sds-step heading="The page">Under docs/. It embeds the same card the design system photographs into its sections.</sds-step>
</sds-steps>
</sds-slide>
<sds-slide>
<span slot="eyebrow">02 · What it consists of</span>
<h2 slot="heading">Address a component, never rebuild one</h2>
<sds-grid>
<sds-code code-lang="html" source="<sds-code code-lang="bash"> <code>make verify ARGS=classes</code> </sds-code>"></sds-code>
<sds-surface plane="plain">
<span slot="heading">The element first</span>
The classes are the fallback for a surface with no JavaScript, not the front door. What a component says goes between its tags, each part in its region.
</sds-surface>
</sds-grid>
</sds-slide>
Code, as a deck holds it
html
<sds-slide>
<span slot="eyebrow">02 · What it consists of</span>
<h2 slot="heading">Address a component, never rebuild one</h2>
<sds-grid>
<sds-code code-lang="html" source="<sds-code code-lang="bash"> <code>make verify ARGS=classes</code> </sds-code>"></sds-code>
<sds-surface plane="plain">
<span slot="heading">The element first</span>
The classes are the fallback for a surface with no JavaScript, not the front door. What a component says goes between its tags, each part in its region.
</sds-surface>
</sds-grid>
</sds-slide>
<sds-slide>
<span slot="eyebrow">02 · What it consists of</span>
<h2 slot="heading">What the gate holds</h2>
<sds-table>
<table>
<thead>
<tr>
<th>Check</th>
<th>What it holds</th>
</tr>
</thead>
<tbody>
<tr>
<td class="sds-td-name">classes</td>
<td>every class in use has a definition in the layer that can load it</td>
</tr>
<tr>
<td class="sds-td-name">values</td>
<td>every figure beside a token is that token’s</td>
</tr>
<tr>
<td class="sds-td-name">names</td>
<td>every sds- name a document writes exists</td>
</tr>
<tr>
<td class="sds-td-name">ssr</td>
<td>every element renders outside a browser</td>
</tr>
<tr>
<td class="sds-td-name">prose</td>
<td>every text against ASD-STE100 and the terse rule</td>
</tr>
</tbody>
</table>
</sds-table>
</sds-slide>
Table, as a deck holds it
html
<sds-slide>
<span slot="eyebrow">02 · What it consists of</span>
<h2 slot="heading">What the gate holds</h2>
<sds-table>
<table>
<thead>
<tr>
<th>Check</th>
<th>What it holds</th>
</tr>
</thead>
<tbody>
<tr>
<td class="sds-td-name">classes</td>
<td>every class in use has a definition in the layer that can load it</td>
</tr>
<tr>
<td class="sds-td-name">values</td>
<td>every figure beside a token is that token’s</td>
</tr>
<tr>
<td class="sds-td-name">names</td>
<td>every sds- name a document writes exists</td>
</tr>
<tr>
<td class="sds-td-name">ssr</td>
<td>every element renders outside a browser</td>
</tr>
<tr>
<td class="sds-td-name">prose</td>
<td>every text against ASD-STE100 and the terse rule</td>
</tr>
</tbody>
</table>
</sds-table>
</sds-slide>
<sds-slide>
<span slot="eyebrow">02 · What it consists of</span>
<h2 slot="heading">Where each product edits what</h2>
<p slot="note">Text in place is common. A preview link is not.</p>
<sds-table>
<table>
<caption><sds-icon name="actions-check" tone="ok"></sds-icon>available <sds-icon name="actions-circle" tone="warn"></sds-icon>partly, see the notes <sds-icon name="actions-minus" tone="error"></sds-icon>not available <sds-icon name="actions-question"></sds-icon>not documented</caption>
<thead>
<tr>
<th>Product</th>
<th class="sds-td-sign">Text in place</th>
<th class="sds-td-sign">Media</th>
<th class="sds-td-sign">Layout</th>
<th class="sds-td-sign">Preview link</th>
<th class="sds-td-sign">Undo</th>
</tr>
</thead>
<tbody>
<tr>
<td class="sds-td-name">Product A</td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-circle" tone="warn" label="Partly"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-minus" tone="error" label="No"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
</tr>
<tr>
<td class="sds-td-name">Product B</td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-circle" tone="warn" label="Partly"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-question" label="Not known"></sds-icon></td>
</tr>
<tr>
<td class="sds-td-name">Product C</td>
<td class="sds-td-sign"><sds-icon name="actions-circle" tone="warn" label="Partly"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-minus" tone="error" label="No"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-minus" tone="error" label="No"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
</tr>
<tr>
<td class="sds-td-name">Product D</td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-circle" tone="warn" label="Partly"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-minus" tone="error" label="No"></sds-icon></td>
</tr>
</tbody>
</table>
</sds-table>
</sds-slide>
Matrix, as a deck holds it
html
<sds-slide>
<span slot="eyebrow">02 · What it consists of</span>
<h2 slot="heading">Where each product edits what</h2>
<p slot="note">Text in place is common. A preview link is not.</p>
<sds-table>
<table>
<caption><sds-icon name="actions-check" tone="ok"></sds-icon>available <sds-icon name="actions-circle" tone="warn"></sds-icon>partly, see the notes <sds-icon name="actions-minus" tone="error"></sds-icon>not available <sds-icon name="actions-question"></sds-icon>not documented</caption>
<thead>
<tr>
<th>Product</th>
<th class="sds-td-sign">Text in place</th>
<th class="sds-td-sign">Media</th>
<th class="sds-td-sign">Layout</th>
<th class="sds-td-sign">Preview link</th>
<th class="sds-td-sign">Undo</th>
</tr>
</thead>
<tbody>
<tr>
<td class="sds-td-name">Product A</td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-circle" tone="warn" label="Partly"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-minus" tone="error" label="No"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
</tr>
<tr>
<td class="sds-td-name">Product B</td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-circle" tone="warn" label="Partly"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-question" label="Not known"></sds-icon></td>
</tr>
<tr>
<td class="sds-td-name">Product C</td>
<td class="sds-td-sign"><sds-icon name="actions-circle" tone="warn" label="Partly"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-minus" tone="error" label="No"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-minus" tone="error" label="No"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
</tr>
<tr>
<td class="sds-td-name">Product D</td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-check" tone="ok" label="Yes"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-circle" tone="warn" label="Partly"></sds-icon></td>
<td class="sds-td-sign"><sds-icon name="actions-minus" tone="error" label="No"></sds-icon></td>
</tr>
</tbody>
</table>
</sds-table>
</sds-slide>
<sds-slide>
<span slot="eyebrow">02 · What it consists of</span>
<h2 slot="heading">The values the design rests on</h2>
<sds-grid>
<sds-stat value="16" unit="px" label="Floor" note="The floor for the signet and the icons."></sds-stat>
<sds-stat value="4" unit="px" label="Radius" note="One radius for everything interactive."></sds-stat>
<sds-stat value="1" unit="px" label="Hairline" note="Hairlines do the structural work."></sds-stat>
</sds-grid>
</sds-slide>
Numbers, as a deck holds it
html
<sds-slide>
<span slot="eyebrow">02 · What it consists of</span>
<h2 slot="heading">The values the design rests on</h2>
<sds-grid>
<sds-stat value="16" unit="px" label="Floor" note="The floor for the signet and the icons."></sds-stat>
<sds-stat value="4" unit="px" label="Radius" note="One radius for everything interactive."></sds-stat>
<sds-stat value="1" unit="px" label="Hairline" note="Hairlines do the structural work."></sds-stat>
</sds-grid>
</sds-slide>
<sds-slide kind="statement">
<span slot="eyebrow">02 · What it consists of</span>
<sds-quote body="Comments carry the reason, not the story. No changelog, no anecdote, and never the name of another project." by="AGENTS.md" as="what fails review"></sds-quote>
</sds-slide>
Quote, as a deck holds it
html
<sds-slide kind="statement">
<span slot="eyebrow">02 · What it consists of</span>
<sds-quote body="Comments carry the reason, not the story. No changelog, no anecdote, and never the name of another project." by="AGENTS.md" as="what fails review"></sds-quote>
</sds-slide>