lifi-ds-docs skill, rendered at real size; each card follows the rule it documents. When you add or migrate a component, use these shapes instead of inventing new ones.Skill & Workflow
Authoring guide
How to add or migrate a component. The full procedure is in the lifi-ds-docs skill.
python3 .claude/skills/lifi-ds-docs/scripts/validate-doc.py
Three-places rule. A component is in the design system only when all three carry it:
styles.css: the implementationdesign/components/: the written spec- A catalog page in
design-system/: the card with a live preview
Workflow (detail in the skill's references/procedure.md):
- Read the writing-style guide. A caption is one sentence of at most 140 characters, or none when it would repeat the label.
- Copy the template from
references/component-template.htmlinto the right place. - Fill the slots in order: label → caption → preview → markup → specs → rules → source. If the card is the section's only one and the section title names it, drop the card head and put the class chip in the title.
- Verify the three-places rule.
- Run
python3 .claude/skills/lifi-ds-docs/scripts/validate-doc.py; exit code 0 is clean. - Reload the page and click through every tab.
Skill: .claude/skills/lifi-ds-docs/ (SKILL.md, references/component-template.html, writing-style.md, procedure.md, scripts/validate-doc.py).
Primitive CSS: styles.css → .ds-doc-card.
JS: shared.js → initDsCompDoc(): tabs and deep links (#section:panel).
Audience & Why
Audience priority
When the three readers' needs conflict, the designer's scanning speed wins.
- Designers scan it visually and recognise components by label and preview.
- Engineers arrive with a component name and open Markup, Specs or Source for code.
- Marketing uses it as a brand reference: real previews in the live palette.
- The label leads: larger, sans 600, primary colour. Designers read it first.
- The caption supports: body size, weight 400, secondary colour.
- Preview is the default tab.
- Engineering content is one click away, behind tabs, never on a separate page.
- Inactive panes use the
hiddenattribute, neverdisplay: nonein markup, so agents and search still read them. - Don't flip the hierarchy. A label set as a small eyebrow over a body-size caption makes cards hard to tell apart.
Skill: .claude/skills/lifi-ds-docs/SKILL.md → Audience priority.
Repo rule: CLAUDE.md → Audience priority.
Typography
Label .ds-doc-card__label
The heading at the top of a card, sized so designers can tell cards apart at a glance.
Brand button .btn-primary
Variant matrix
Text prefix & suffix .field-prefix · .field-suffix
<!-- Shape A: name + 1 class (most common) -->
<h3 class="ds-doc-card__label">Brand button <code>.btn-primary</code></h3>
<!-- Shape B: name only (reference / aggregate) -->
<h3 class="ds-doc-card__label">Variant matrix</h3>
<!-- Shape C: name + 2-3 classes (family) -->
<h3 class="ds-doc-card__label">Text prefix & suffix <code>.field-prefix</code> · <code>.field-suffix</code></h3>
| Property | Value | Token / Notes |
|---|---|---|
| font-family | Sans | var(--font-sans) |
| font-size | 20 px | var(--text-body-xl) on DS pages |
| font-weight | 600 | — |
| color | Primary text | var(--text-primary) |
| line-height | 28 px | var(--lh-body-lg) |
| letter-spacing | -0.015em | var(--tracking-snug) |
Inline <code> | 0.72em · weight 500 · 70% ink | A quieter chip on .ds-doc-card__label code, so the name leads |
- Three shapes: A (name + 1 class), B (name only), C (name + 2–3 classes joined by ` · `).
- Lead with a plain noun phrase. A class-only label fails W005.
- Sentence case. All caps fails W007.
- Separate classes with ` · `, never `/`, which reads as "or" (W006).
- At most 3 classes. If the card needs more, split it.
- A section's only card can drop its head when the section title names it. Put the class chip in the title:
<div class="section-title">Action bar <code>.action-bar</code></div>. In a section with several cards, every card keeps its label.
CSS: styles.css → .ds-doc-card__label; DS-page sizes in doc-shared.css.
Skill: .claude/skills/lifi-ds-docs/references/writing-style.md → The label rule.
Validator: scripts/validate-doc.py, codes W005 (class-only), W006 (slash separator), W007 (all-caps).
Caption .ds-doc-card__caption
One plain sentence under 140 characters that adds what the label doesn't say.
Brand button .btn-primary
Brand action button. Three sizes; .btn-lg in heroes, .btn-sm in dense rails.
Brand button
Powerful and beautiful action buttons that elevate your CTAs and seamlessly delight users.
<!-- One sentence, ≤140 chars; omit it if it repeats the label -->
<p class="ds-doc-card__caption">
Brand action button. Three sizes; <code>.btn-lg</code> in heroes, <code>.btn-sm</code> in dense rails.
</p>
| Property | Value | Token / Validator |
|---|---|---|
| font-size | 16 px | var(--text-body) |
| font-weight | 400 | — |
| color | Secondary text | var(--text-secondary) |
| line-height | 24 px | var(--lh-body) on DS pages |
| max-width | 72ch | On DS pages |
| Max length | 140 chars | Validator E004 |
| Sentences | 1 (2 max) | Validator W002 warns at 3+ |
| Forbidden words | 12 listed | Validator E010 · marketing voice |
- One sentence. Two only if both are needed; three or more triggers W002.
- Omit the caption when it would only repeat the label. A head with a label and no caption is valid.
- Don't repeat the section description. Say each thing once, in the description or the caption.
- Lead with the noun phrase, not an instruction: "Brand button", not "Use this button when…".
- Name examples in code:
.btn-lg, not "large variant". - No marketing voice, no history or dates, no em dashes. The validator holds the forbidden-words list.
- 140 characters at most. A longer caption usually means two cards merged into one.
CSS: styles.css → .ds-doc-card__caption.
Skill: .claude/skills/lifi-ds-docs/references/writing-style.md → The caption rule.
Validator: E004 (length), E010 (forbidden words), W002 (sentence count).
Pane Primitives
Pane primitives .ds-doc-*
Containers, prose, labels, inline, layout and demo blocks for panes. Use these instead of inline style.
Section heading
Standard .ds-doc-text paragraph. Inline <code> like .btn-primary auto-renders as a chip via the .code-chip universal rule. Multiple paragraphs auto-space.
Use <strong> for emphasis — it darkens to --text-secondary automatically.
.ds-doc-list— body-size text, tight item spacing.- Bold leads — start an item with
<strong>for "X — does Y" pairs. - Inline
.classeschip the same way as in paragraphs.
.ds-doc-aside — default brand-emphasis aside. Use when the note matters to the surrounding decision.
--note — informational. Background context, links to deeper docs, "by the way" footnotes that aren't decisions.
--success — confirmed-good practice. Use when calling out the recommended path or a working pattern.
--warn — caution. Authoring choice that breaks a downstream contract or has a known foot-gun.
--danger — don't. Anti-patterns and forbidden moves; the variant signals that the rule is non-negotiable.
--muted — quiet footnote. Background-less; reads as a side-note inside busier panes.
// .ds-doc-codeblock — drops chrome inside a pane, keeps it standalone.
const chip = "foundations";
| Class | Use |
|---|---|
| .btn-primary | Primary action — the dominant CTA |
| .btn-secondary | Paired secondary on dual-action surfaces |
Default
.ds-doc-eyebrow
Active
--accent
Lower
--ghost
Family · caption
.ds-doc-caption: sans, left-aligned, muted; quieter than .ds-doc-text. Three modifiers set its placement.
Default · 8 px top
Caption follows the demo with the default 8 px top gap.
--lead · 12 px top
Bigger top gap when the default 8 px feels cramped against the demo above.
--label · acts as label above
Default — caption labels the demo below it.
--centered · figcaption
.brand-tile · 240 pxFamily · demo
A headline below an eyebrow, a framed sample box, a right-pinned mono detail, and smaller body text.
Priority 1
Designers
Body-lg / weight 600 — the canonical demo headline. Quieter than a card label so it doesn't compete with the card's own heading.
A
Brand button .btn-primary
The --sm modifier drops to body size for tighter rows where the headline sits on one line beside an inline class chip.
Sunk
default
Raised
--raised
Elevated
--elevated
Alpha
--alpha
- Card primitive surfacestyles.css:14092
- Brand buttonv4.2 · 12 specs
- Spot iconjust shipped
Default .ds-doc-text — body size (16px), text-secondary, generous line height. The standard for documentation paragraphs.
The --sm modifier drops to 14px while keeping the same colour and line-height. Use under a headline or caption for context that's quieter than body prose — typical at "Why" / "When to use" notes.
<!-- ═══ CONTAINERS — chrome owners ═══ -->
<!-- Codeblock · standalone has chrome, in a pane it drops -->
<pre class="ds-doc-codeblock"><code>const x = 1;</code></pre>
<!-- Table · always wrapped in .ds-doc-table-wrap -->
<div class="ds-doc-table-wrap">
<table class="data-table">…</table>
</div>
<!-- Aside · semantic note · default / note / success / warn / danger / muted -->
<p class="ds-doc-aside">Brand-emphasis note.</p>
<p class="ds-doc-aside ds-doc-aside--note">Informational.</p>
<p class="ds-doc-aside ds-doc-aside--success">Recommended path.</p>
<p class="ds-doc-aside ds-doc-aside--warn">Caution — downstream contract.</p>
<p class="ds-doc-aside ds-doc-aside--danger">Don’t — anti-pattern.</p>
<p class="ds-doc-aside ds-doc-aside--muted">Quiet footnote.</p>
<!-- ═══ PROSE — running text ═══ -->
<p class="ds-doc-text">Body prose with auto-styled <code>.classes</code>.</p>
<ul class="ds-doc-list"><li>Item</li></ul>
<!-- ═══ LABELS — eyebrows + captions ═══ -->
<p class="ds-doc-eyebrow">Default kicker</p>
<p class="ds-doc-eyebrow ds-doc-eyebrow--accent">Active</p>
<p class="ds-doc-eyebrow ds-doc-eyebrow--ghost">Lower</p>
<p class="ds-doc-caption">Default — sans, left, 8 px top</p>
<p class="ds-doc-caption ds-doc-caption--lead">--lead — 12 px top gap</p>
<p class="ds-doc-caption ds-doc-caption--label">--label — labels the demo below</p>
<figcaption class="ds-doc-caption ds-doc-caption--centered">--centered — under a centered demo</figcaption>
<p class="ds-doc-swatch-label">--accent-primary</p>
<!-- ═══ INLINE — code chip is auto-applied on every <code> ═══ -->
<code>.btn-primary</code> <!-- bare <code> auto-chips site-wide -->
<span class="code-chip">.btn-primary</span> <!-- explicit for non-<code> hosts -->
<!-- ═══ LAYOUT — grids + dividers ═══ -->
<div class="ds-doc-grid ds-doc-grid--cols-2">
<div>Left</div>
<div>Right</div>
</div>
<div class="ds-doc-grid ds-doc-grid--cols-3">…</div>
<div class="ds-doc-grid ds-doc-grid--cols-4">…</div>
<hr class="ds-doc-divider">
<hr class="ds-doc-divider ds-doc-divider--tight">
<hr class="ds-doc-divider ds-doc-divider--loose">
<!-- ═══ DEMO — headline / well / detail / text--sm ═══ -->
<!-- Headline · pairs below an eyebrow · default body-lg, --sm body -->
<h4 class="ds-doc-headline">Designers</h4>
<h4 class="ds-doc-headline ds-doc-headline--sm">Brand button</h4>
<!-- Well · headerless framed surface · sunk default -->
<div class="ds-doc-well">…</div>
<div class="ds-doc-well ds-doc-well--raised">…</div>
<div class="ds-doc-well ds-doc-well--elevated">…</div>
<div class="ds-doc-well ds-doc-well--alpha">…</div>
<!-- Detail · right-pinned mono annotation in a row -->
<li><strong>Brand button</strong><span class="ds-doc-detail">v4.2</span></li>
<!-- Smaller body modifier · 14px supporting prose -->
<p class="ds-doc-text ds-doc-text--sm">Quieter context.</p>
Containers
| Primitive | Recipe | Pane-aware behaviour |
|---|---|---|
.ds-doc-codeblock | border + bg + radius · mono · 8 token spans | Drops border, bg and radius |
.ds-doc-table-wrap | border + radius · horizontal scroll on narrow viewports | Drops both |
.data-table | uppercase headers · hover rows · code-style numeric cells | Same in and out of a pane |
.ds-doc-aside | 3px accent left-border · italic · text-secondary · line-height 1.55 | Identical in/out · variants: --muted, --warn |
Prose
| Primitive | Recipe | Notes |
|---|---|---|
.ds-doc-text | body · text-secondary · line-height 1.6 · 640px max-width | Auto-spaces siblings · drops max-width inside pane |
.ds-doc-list | body · text-secondary · 8px item spacing · works on <ul> / <ol> | Identical in/out |
Labels
| Primitive | Recipe | When to use |
|---|---|---|
.ds-doc-eyebrow | 11px · mono · 700 · text-faint · uppercase · tracking-wider · mb-6 | Sub-headings inside a pane, labels above a demo, state markers ("Default", "Active"). Variants: --accent, --ghost. |
.ds-doc-caption· --lead· --label· --centered | caption · sans · text-muted · left · mt-8 | Annotation under a demo. Modifiers: --lead (12 px top), --label (labels the demo below), --centered (figcaption under a centered demo). |
.ds-doc-swatch-label | caption · mono · text-muted | Mono label on visual demos (swatches, dimensions, samples) · variant: --on-alpha |
Inline
| Primitive | Recipe | Notes |
|---|---|---|
.code-chip | 0.85em · mono · 600 · primary · 7% currentColor bg · no border · 5px radius | Applied to every <code> on the site; use the class on other elements. Off inside .ds-doc-codeblock. Used on every surface. |
Layout
| Primitive | Recipe | Notes |
|---|---|---|
.ds-doc-grid | display:grid · 16px gap · align-items:start · mt-12 | Modifiers: --cols-2, --cols-3, --cols-4, --tight (8px), --loose (24px). Auto-stacks at ≤720px |
.ds-doc-divider | 1px hairline · 6% currentColor · my-20 | Modifiers: --tight (12px), --loose (32px). Use <hr> |
Demo
| Primitive | Recipe | When to use |
|---|---|---|
.ds-doc-headline | body-lg · 600 · text-primary · margin:0 | Bigger label below an eyebrow, inside a pane. Variant: --sm (body size for tighter rows). Pairs with .ds-doc-eyebrow. |
.ds-doc-well | padding:24 · radius:lg · surface-sunk + 6%-ink hairline | The framed preview surface for component, product and material demos; leave atoms and text specimens bare. Variants: --sunk (default) / --raised / --elevated / --alpha. Spacing: --tight (12) / --loose (32). |
.ds-doc-detail | margin-left:auto · mono · caption · text-muted · nowrap | Right-pinned mono annotation in a row (path, version, dimension). Variant: --accent. |
.ds-doc-text--sm | modifier on .ds-doc-text: font-size sm (14px) | Smaller supporting prose under a headline or caption. |
If a pane needs a label, divider, grid, aside, headline, well or pinned detail, use one of the 16 primitives. Never inline-style your own.
Picking the right label
.ds-doc-eyebrowfor a sub-heading above a group of demos or a label above one demo. Name the variant in a few words ("Default", "Stacked"), sentence case, no em dash..ds-doc-captionfor annotation around a demo. Use--lead,--labelor--centered, never an inlinestyle="margin-..."..ds-doc-swatch-labelfor a mono label beside a swatch or sample.
Layout & containers
- Never author your own container. No
<div style="background:…">around a snippet and no radius wrapper around a table. - Containers adapt to panes.
.ds-doc-codeblockand.ds-doc-table-wrapdrop their chrome inside.ds-doc-viewport-paneon their own. - Code blocks use
.ds-doc-codeblock, never a raw<pre>. Tables use.ds-doc-table-wrap > .data-table, which scrolls on narrow screens. - Use
.ds-doc-gridinstead of an inline grid, such as.ds-doc-grid.ds-doc-grid--cols-2for two columns. - For emphasis, use
.ds-doc-aside; never recolour.ds-doc-textinline.
Demo annotations
.ds-doc-headlinefor a larger label below a.ds-doc-eyebrow. Use--smto fit one line beside a class chip..ds-doc-wellfor a small framed sample with no header:--sunkby default,--raised/--elevatedfor elevation demos,--alphafor state-layer demos..ds-doc-detailfor a right-pinned mono note in a flex row: a path, dimension or version..ds-doc-text--smfor quieter prose under a headline or caption, with a body paragraph above it.- A well is for small samples. For labelled demo rows, use
.ds-doc-viewport.ds-doc-viewport--stack.
Extending the system
- Register a new pattern here before it spreads.
- Promote an inline pattern to a primitive once it appears five or more times: CSS next to the
.ds-doc-*block instyles.css, and a demo in this card. - Don't hand-tune tokens. If a primitive feels wrong, pick another or add a modifier (
--tight,--accent).
CSS: styles.css, search .ds-doc-codeblock (containers) and .ds-doc-eyebrow (labels and layout).
Spec: design.md §13 → Inside-pane vocabulary.
Skill: .claude/skills/lifi-ds-docs/SKILL.md → Pane content primitives.
Validator: E008 flags an inline style="background:#…" container.
Syntax-highlight tokens
Eight spans colour HTML, CSS, JS, JSON and shell snippets.
// Eight spans cover every language we ship — HTML, CSS, JS, JSON, shell.
const chip = "foundations"; // keyword + string
if (chip === true) {
fetch("/api/scopes"); // path
}
<button class="btn-primary" disabled>
Click, when ready
</button>
<!-- Wrap each token in its span -->
<pre class="ds-doc-codeblock"><code>
<span class="comment">// comment</span>
<span class="keyword">const</span> x = <span class="string">"value"</span>;
</code></pre>
| Span | Use for | Sample | Token |
|---|---|---|---|
<span class="comment"> | Comments | // muted, italic | --text-faint |
<span class="string"> | String literals | "value" | --accent-secondary |
<span class="tag"> | HTML tags | button | --accent-primary |
<span class="attr"> | HTML attributes | class | --accent-tertiary |
<span class="value"> | Numeric / boolean | true | --accent-secondary |
<span class="keyword"> | Keywords (JS / CSS / shell) | const | --accent-primary bold |
<span class="path"> | Paths / URLs | /api/x | --accent-tertiary |
<span class="punct"> | Punctuation, brackets | { } | --text-faint |
Primary for tags and keywords, secondary for strings and values, tertiary for attributes and paths. Comments and punctuation share --text-faint.
- Don't invent new spans. If a snippet doesn't fit, use
commentor leave it monochrome. - Tokens only. Each span maps to a
var(--*)token, so the palette recolours every snippet. - On mobile, code blocks wrap (
pre-wrap,word-break: break-word). The CSS handles it. - Escape HTML inside a code block:
<,>,&. The validator doesn't check this.
CSS: styles.css → .ds-doc-codeblock .comment and the seven rules after it.
Eyebrow-labelled row .ds-doc-eyebrow-row
Pairs a .ds-doc-eyebrow with a demo. Stack three to seven in a Preview pane.
Rows are 32 px apart; the eyebrow sits 12 px above its demo.
Default
Tertiary
Destructive
<div class="ds-doc-eyebrow-row">
<p class="ds-doc-eyebrow">Variant A · default</p>
<!-- demo -->
</div>
<div class="ds-doc-eyebrow-row">
<p class="ds-doc-eyebrow">Variant B · ghost</p>
<!-- demo -->
</div>
| Selector | Effect |
|---|---|
.ds-doc-eyebrow-row | One label and demo. No padding or border of its own. |
.ds-doc-eyebrow-row + .ds-doc-eyebrow-row | margin-top: var(--space-32) |
.ds-doc-eyebrow-row > .ds-doc-eyebrow:first-child | margin: 0 0 var(--space-12) |
- Stack labelled variants in one Preview pane. Don't split a Preview into nested
.ds-doc-viewportframes. - No
style="margin: ..."on the eyebrow. The row sets the spacing. - The eyebrow names the variant in a few words on one line. Explanation goes in Rules or Anatomy.
- Aim for three to seven rows. With one or two, show the demo alone; with eight or more, the card may be two components.
- A row's demo can be a grid. If every row needs a different layout, the variants aren't peers and shouldn't share a pane.
Colors tab pattern data-tab="colors"
An optional pane for state colours, overrides and key highlights, always second after Preview.
Source flags
Each swatch carries a flag saying where its colour comes from: the system, a deliberate divergence, or a value locked to this widget.
var(--accent-primary)
.btn-primary · .chip-accent1 · .status-dot
color-mix(...) · --slot remap
.checkbox input:checked · .btn-destructive · .tile.is-active
color-mix(…) blend, a remapped slot or a component shadow.oklch(100% 0 0 / 0.05) · #FFFFFF · brand pair
.fab:hover halo · .btn-neutral · .brand-tile
Tab order
Preview / Colors / Markup / Specs / Anatomy / Rules / Source. Colors sits second when present; E016 errors on any other position.
Designers read Preview, then Colors; engineers start at Markup.
One .ds-doc-text lead and a .swatch-grid with one .swatch.swatch--state per key colour.
<!-- Second, after Preview -->
<button class="ds-doc-viewport-tab" data-tab="colors">Colors</button>
<!-- Pane order matches tab order -->
<div class="ds-doc-viewport-pane" data-pane="colors" hidden>
<p class="ds-doc-text" style="margin-bottom: var(--space-20);">
<strong>[Card-specific lead title].</strong> [One sentence on how
the tone system works for this component.]
</p>
<div class="swatch-grid">
<figure class="swatch swatch--state"
style="--swatch-color: var(--TOKEN);">
<div class="swatch-tile"></div>
<figcaption class="swatch-meta">
<span class="swatch-flag swatch-flag--inherited">Inherited</span>
<div class="swatch-name">[State or tone name]</div>
<code class="swatch-token">var(--TOKEN)</code>
<code class="swatch-selector">.scoped-selector</code>
<div class="swatch-rationale">[Short purpose sentence]</div>
</figcaption>
</figure>
<!-- one .swatch--state per critical colour -->
</div>
</div>
Flag modifier classes: .swatch-flag--inherited (neutral) · .swatch-flag--override (pink) · .swatch-flag--convention (blue). Apply exactly one per swatch.
When to add a Colors tab
- Interactive state colours: hover, active, selected, focus, disabled, pinned. Example:
.list-item. - Overrides of a system default, with the reason. Example:
.alert's four semantic tones. - Highlight colours that identify the component, such as an accent card's tone or a hero KPI's gradient. Example:
.accent-card.
When to skip
- Only system defaults apply (
--overlay-hover,--accent-primary,--ink-*). A line in Rules is enough. - No states, overrides or highlights, as with a divider or a static label.
- The component is itself a colour primitive, such as a swatch or palette card.
- A sibling card already shows the recipe. All
.stepsvariants, for example, point to the Simple card.
Content contract
- States, overrides and highlights only, not every token the component uses.
- Usually two to six swatches; eight at most, as in Content tile, Accents.
- Surfaces, type sizes and spacing go in Specs or Anatomy.
Enforcement
- Validator E016 errors when
data-tab="colors"is not the second tab. - Pane order matches tab order. Move both when reordering, so the source reads in the same order.
- Most cards skip it, because they use only system defaults.
Structure & Spacing
Section + card spacing
The CSS spaces sections, subsections and cards. Don't add dividers, <hr> or spacers.
My section
Section description. Sets context for the cards below.
PRIMARY VARIANTS
Card 1 — first variant
Caption.
Card 2 — second variant
Caption.
- ↑ 240px section padding
- ← .ds-doc-subsection · hairline + 80px above
- ↓ 80px card-to-card gap + 1px hairline
<!-- Section shell — eyebrow + title + desc + cards -->
<section class="section" id="my-section">
<div class="container">
<div class="eyebrow-code">02 — My Section</div>
<div class="section-title">My section</div>
<div class="section-desc">Section description.</div>
<!-- Optional subsection eyebrow — groups cards into named clusters -->
<h2 class="ds-doc-subsection">Primary variants</h2>
<!-- Adjacent .ds-doc-card cards auto-gap (80px) + auto-hairline (1px) -->
<div class="comp-section ds-doc-card" data-scope="ui marketing">…</div>
<div class="comp-section ds-doc-card" data-scope="ui marketing">…</div>
</div>
</section>
| Layer | Spacing | Selector |
|---|---|---|
| Section padding | 240 px (mobile 96 px) | .section |
| Section title gap | 64 px below desc | .section-desc + * |
| Subsection eyebrow | 80 px above + 1 px hairline | .ds-doc-subsection |
| Card-to-card gap | 80 px (mobile 48 px · print 32 px) | .ds-doc-card + .ds-doc-card |
| Card-to-card hairline | 1 px @ text-primary 6% alpha | same selector, border-top |
- No
<hr>between cards and no empty spacer<div>s. The gap and hairline are automatic. - Use
.ds-doc-subsectionto split a section into named groups. Most sections don't need it. - If two cards look merged, check that they are direct siblings with no wrapper between them.
CSS: styles.css → .ds-doc-card + .ds-doc-card (search for the visual-separation comment block).
Skill: .claude/skills/lifi-ds-docs/SKILL.md → Visual separation between cards — explains why it's automatic, not author-able.
Variant grouping
Group variants by axis and stack the groups, with .ds-doc-divider--loose between them.
The same variants twice. Grouped by axis, they show at a glance that the component varies in three ways.
Don't: mixed wrap-grid
Content A
Shape A
Content B
Position A
Shape B
Content C
Reader has to parse every eyebrow to figure out what axes the component varies on. The grid optimizes for vertical density, not for cognitive grouping.
Do: zones and dividers
Content A
Content B
Content C
Shape A
Shape B
Position A
Three zones visible at a glance: the component varies on content, shape, and position. Hairlines tell the reader "this is a different axis."
<!-- In a Preview pane with variants on two or more axes -->
<!-- Zone 1 — first concern (e.g., "Panel content") -->
<div class="ds-doc-eyebrow-row">
<p class="ds-doc-eyebrow">Variant A</p>
<!-- demo -->
</div>
<div class="ds-doc-eyebrow-row">
<p class="ds-doc-eyebrow">Variant B</p>
<!-- demo -->
</div>
<hr class="ds-doc-divider ds-doc-divider--loose">
<!-- Zone 2 — second concern (e.g., "Trigger shape") -->
<div class="ds-doc-eyebrow-row">
<p class="ds-doc-eyebrow">Variant C</p>
<!-- demo -->
</div>
- List the axes the component varies on before you start. One axis: a flat stack of
.ds-doc-eyebrow-rows. Two or more: one zone per axis, with.ds-doc-divider--loosebetween. - Stack vertically. A wrap-grid is only for cells on the same axis, such as swatches, icons or font samples.
- Use the existing spacing. The row gives 12 px eyebrow to demo and 32 px between cells; the divider gives 32 + 1 + 32 px between zones.
- Each zone needs two or more variants. Otherwise drop the divider. If an axis has one variant now, note it in Specs or Anatomy instead of a one-cell zone.
- Don't mix a grid and rows in one pane.
- With three or more zones, one short
.ds-doc-textat the top can say how the variants are grouped.
Source of truth: CLAUDE.md → "Preview-pane variant grouping".
Reference implementation: #dropdown-default — Dropdown card, 6 variants grouped into 3 zones (Panel content / Trigger shape / Panel positioning).
Companion rule: Pane Breathing Room (Tier 1–4 spacing) — this card carries the ORGANIZATION principle; that one carries the SPACING math.
Primitives: .ds-doc-eyebrow-row (cells) + .ds-doc-divider--loose (zone breaks).
Chapter strip .ds-doc-section-toc
A chapter nav at the top of any section with two or more chapter markers. You write the markers; the JS draws the strip.
A simulated strip. Live ones are at the top of #inputs, #hero, #badges and this Authoring Guide.
The active link follows the chapter in view (IntersectionObserver, rootMargin: -80px 0px -55% 0px).
Write h2.ds-doc-subsection[id] markers in the section; with two or more, the JS prepends a .ds-doc-section-toc.
<!-- inside <section id="inputs"> → <div class="container"> -->
<h2 class="ds-doc-subsection" id="inputs-text">Text & numeric</h2>
<div class="comp-section ds-doc-card">…</div> <!-- card -->
<div class="comp-section ds-doc-card">…</div> <!-- card -->
<h2 class="ds-doc-subsection" id="inputs-sizes">Sizes & label positions</h2>
<div class="comp-section ds-doc-card">…</div>
…
What the JS adds (don't write it):
<nav class="ds-doc-section-toc ds-doc-tab-nav" aria-label="Inputs contents">
<a href="#inputs-text" class="ds-doc-tab-nav-item is-active">Text & numeric</a>
<a href="#inputs-sizes" class="ds-doc-tab-nav-item">Sizes & label positions</a>
…
</nav>
- Two or more markers, or no strip renders.
- Markers are direct children of the section's
.container(:scope > h2.ds-doc-subsection[id]), so a heading inside a pane doesn't count. - Chapter ids are
<section>-<chapter>in kebab case, such asinputs-text. They are URL anchors, so keep them stable. W008 warns on drift. - Chapter titles are Title Case, one to three words: "Text & numeric", not "Text and numeric inputs grouped together".
- Aim for three to six chapters; eight or more suggests splitting the section. W009 warns when a section has 7+ cards and no chapters.
- No chapter for a single card. Fit the card into an existing chapter until a second card shares its theme.
- CSS:
styles.css, search.ds-doc-section-toc. Composes.ds-doc-tab-nav. - JS:
shared.js → initDsSectionTocs(). - Spec:
design.md §13, "Section chaptering & auto-TOC". - Skill:
lifi-ds-docs,references/procedure.md→ "Adding chapters to a growing section". - Validator:
scripts/validate-doc.py, W008 and W009.
Page Chrome
Tab nav .tab-nav
A sticky row of section links in three sizes; the page's JS marks the active link.
.tab-nav-sm · 40 px tall · 13 px text · dense surfaces, sub-section navs
Default · 56 px tall · 14 px text · most pages
.tab-nav-lg · base: 72 px tall · 16 px text · section nav on long pages
Used on the Brand Books, Brand Guide and Competitive Landscape pages, with page-local styles for 14 px pill tabs.
Only the active tab uses the accent, on both label and underline.
var(--text-secondary)
.tab-nav-list a
color-mix(in oklch, var(--accent-primary) 50%, transparent)
.tab-nav-list a:hover
--text-primary.var(--accent-primary)
.tab-nav-list a.is-active
color-mix(in oklch, var(--accent-primary) 50%, transparent)
.tab-nav-list a:focus-visible
-4px so it doesn't cover the bar's hairline.<!-- Page JS toggles .is-active on the link in view -->
<nav class="tab-nav tab-nav-lg" aria-label="Page sections">
<div class="container">
<div class="tab-nav-list">
<a href="#overview">Overview</a>
<a href="#tokens" class="is-active">Tokens</a>
<a href="#components">Components</a>
</div>
</div>
</nav>
| Size modifier | Height | Font size | Padding (h) | Underline | Use |
|---|---|---|---|---|---|
.tab-nav-sm | 40 px | 13 px | 12 px | 2 px | Dense surfaces, sub-section navs inside a panel |
| (default) | 56 px | 14 px | 16 px | 2 px | Most pages |
.tab-nav-lg | 72 px | 16 px | 20 px | 3 px | Section nav on long pages |
Tokens. Backdrop color-mix(in oklch, var(--surface-page) 92%, transparent) with blur(12px). Border 1 px at --text-primary 8%. Link --text-secondary at rest, --text-primary on hover and active. Underline transitions to --accent-primary over 0.18 s ease.
Mobile. At ≤720 px, -lg drops to the default size. Overflow scrolls sideways with no visible scrollbar.
| Class | Role | Notes |
|---|---|---|
.tab-nav | Outer rail | Sticky, frosted, hairline bottom border. Sets the size properties. |
.tab-nav > .container | Width-clamped row | The system .container, so widths match the page. |
.tab-nav-list | Flex row of links | overflow-x: auto; scrollbar hidden. Each direct child <a> renders as a tab. |
.tab-nav-list a | Tab link | Underline on hover, accent when active. |
.tab-nav-list a.is-active | Current section | Set by the page's JS. |
.tab-nav-logo | Optional left slot | Logo and a vertical hairline before the links, as on the brand guide. |
.tab-nav-sm / .tab-nav-lg | Size modifiers | Override --tab-nav-h, --tab-nav-fs, --tab-nav-pad-x, and --tab-nav-underline. |
- One
.tab-navper page. For a sub-nav, use.tab-nav-sminside a panel. - Always set
aria-label, such as "Page sections". - In-page anchors only. On docs pages, links to other pages belong in the sidebar from
ds-nav.js. - Set the active state with an IntersectionObserver, not
:targetor the hash, which don't update on scroll. - Don't change the underline colour per page.
.tab-nav-lgfor primary page nav, the default for most surfaces,.tab-nav-smonly inside a denser context such as a panel header.- No glow under the active underline. The same holds for the marketing navbar's
.nav-link-item.active.
CSS: styles.css → .tab-nav. Custom properties: --tab-nav-h, --tab-nav-fs, --tab-nav-pad-x, --tab-nav-underline.
Live on: design-system/brand-books.html · design-system/brand-guide.html · design-system/competitors.html.
.ds-doc-viewport, not .ds-doc-card-demo, .ds-doc-tile-demo or an inline <div style="background:…">; move old ones when you touch them.Tabbed viewport .ds-doc-viewport--tabbed
A tab strip switches between named panes. Every catalog card uses it.
Click the tabs to switch panes.
Related views share one frame, and the tab strip swaps the body.
Inactive panes stay in the DOM with hidden, so search and screen readers still find them.
| Metric | Value | Trend |
|---|---|---|
| Active tabs | 3 | stable |
| Panes in DOM | 3 | stable |
| Switch latency | <1 ms | — |
Every data-tab needs a matching data-pane in the same frame. validate-doc.py flags orphans either way.
Sub-components
| Class | Role | Notes |
|---|---|---|
| .ds-doc-viewport--tabbed | Modifier on the outer viewport | Removes the padding so the tab strip sits flush. |
| .ds-doc-viewport-tabs | Tab strip container | Flex row; scrolls sideways on overflow. |
| .ds-doc-viewport-tab | Individual tab button | .is-active on the open tab; data-tab="key" matches a pane. |
| .ds-doc-viewport-pane | Pane content wrapper | One per tab, data-pane="key", hidden when inactive. |
ARIA. The JS sets the tab and tabpanel roles and links. You write only the aria-label on .ds-doc-viewport-tabs.
Wiring. shared.js → initDsCompDoc() wires every tabbed viewport. #section-id:pane-key opens that pane on load.
- Use the standard pane names:
preview · markup · specs · anatomy · rules · source, plus the optionalcolors. The validator warns on others. - Every card gets a Preview pane, even reference and matrix cards.
- Hide inactive panes with
hidden, notdisplay: nonefrom a class, so agents can read every pane. - One tabbed viewport may sit inside a pane. The "no nested viewports" rule still holds for what is visible.
- Not for product navigation. Use
.tab-navor the product's own tabs. - Always label
.ds-doc-viewport-tabs. "Component documentation" is fine for catalog cards; be specific elsewhere.
- CSS:
styles.css, search.ds-doc-viewport--tabbed. - JS:
shared.js → initDsCompDoc(), inside or outside a.ds-doc-card. - Validator:
.claude/skills/lifi-ds-docs/scripts/validate-doc.py, for pairing, missing panes and pane names. - Skill:
.claude/skills/lifi-ds-docs/.
Viewport reference
Surfaces, anatomy and modifiers of .ds-doc-viewport.
Default surface: transparent, with padding and no chrome, so demos sit on the page. --tabbed adds a frame for the tab strip; --showcase adds a brand-gradient backdrop.
Showcase surface: a brand-gradient backdrop like a deck or hero. Use it to show how a material reads on a tinted background, such as glass.
Layout, size and height modifiers combine freely; see Anatomy.
Sub-components
| Class | Role | Notes |
|---|---|---|
| .ds-doc-viewport | Outer surface + padding | Override per instance with --vp-pad, --vp-radius, --vp-border |
| .ds-doc-viewport-controls | Extensible controls slot (top-right of viewport) | Flex row, 2px gap. Takes .ds-doc-viewport-control, .btn-*, .ds-doc-seg-control |
| .ds-doc-viewport-control | Canonical 28×28 icon button | Transparent bg · hover tint · .is-active state · 14×14 SVG slot |
| .ds-doc-viewport-body | Inner content wrapper | No box model. Layout modifiers (--center, --row, --stack) target this when present, else the viewport itself. |
Modifiers (combine freely)
| Axis | Values | Use |
|---|---|---|
| Surface | default · --showcase | Default is transparent. --showcase adds a brand-gradient backdrop for material demos. |
| Size | --sm · default · --lg | Tighter for control racks, larger for hero showcases |
| Layout | --center · --stack · --stack-lg · --row | Applies to .ds-doc-viewport-body when present, else the viewport |
| Height | --tall | min-height: 400px for demos with dynamic content |
- Use
.ds-doc-viewportfor every new preview: catalog, dashboard, brand guide, skill output. - Prefer stacked, full-width
--lgviewports. Use side-by-side only when the comparison is the point. - Demo in the base palette: a
.chip.chip-neutral, a neutral label or one.btn-tertiary. Use accents only when the accent is the component's purpose. - No raw hex or rgb in demos. Use tokens (
var(--text-primary),var(--accent-primary),var(--series-N)). - No inline
backgroundon the viewport. Use a surface modifier or--vp-border. - Not for product UI. Use
.cardor.accent-card. - Don't nest viewports. For a grid of previews, put flat viewports in a
display: gridparent.
Asset cells .ds-doc-avatar-cell · .ds-doc-icon-cell
The figure-and-caption cells of the Assets page grids. Avatar, portrait, icon and partner-logo cells show a download button on hover. Catalog only; never use them on product or marketing surfaces.
Hover or tab to a cell to show its download button. Avatar and portrait cells save the largest srcset file; icon cells save the file named by data-icon. Partner-logo cells also have a top-left toggle that previews the other mode, and the download saves the version shown.
Three cell shapes, one button: a 40px avatar (SVG), a 24px Lucide icon (SVG), and a 96px portrait whose download resolves the 1024px master (PNG).
<!-- Write the figure only; the page script adds .ds-doc-cell-dl -->
<div class="ds-doc-avatar-grid">
<figure class="ds-doc-avatar-cell">
<img class="avatar avatar--rounded" src="../avatars/chains/ethereum.svg" alt="ethereum" loading="lazy">
<figcaption>ethereum</figcaption>
</figure>
</div>
<!-- data-icon names /icons/<name>.svg for the glyph and the download -->
<figure class="ds-doc-icon-cell" data-icon="activity">
<span class="ds-doc-icon-ph" aria-hidden="true"></span>
<figcaption>activity</figcaption>
</figure>
<!-- Added by the script; never write it by hand -->
<a class="btn-primary btn-icon btn-xs btn-circle ds-doc-cell-dl"
href="../avatars/chains/ethereum.svg" download="ethereum.svg"
aria-label="Download ethereum.svg">
<svg>…</svg>
</a>
| Property | Value | Token / Notes |
|---|---|---|
| Grid | repeat(auto-fill, minmax(112px, 1fr)) | gap var(--space-8) |
| Cell padding | 16 / 8 | var(--space-16) / var(--space-8) |
| Icon glyph | 24px · stroke 1.5 | Marketing / Catalog stroke tier |
| Avatar | 40px · 96px portraits | .avatar default · .avatar--2xl |
| Download button | 24 × 24 · 12px glyph | .btn-primary .btn-icon .btn-xs .btn-circle |
| Reveal | opacity 0 → 1 · 0.15s ease | :hover / :focus-within on the cell |
| Mode flip | 24 × 24 · 12px glyph | .btn-neutral .btn-icon .btn-xs .btn-circle; top-left, partner cells only |
| Class | Role | Notes |
|---|---|---|
| .ds-doc-avatar-grid / .ds-doc-icon-grid | Auto-fill grid wrapper | 112px minimum cells |
| .ds-doc-avatar-cell | Image figure | img.avatar and figcaption; avatars and portraits |
| .ds-doc-icon-cell | Icon figure | data-icon names the library file; the glyph loads lazily |
| figcaption | Filename caption | Mono, muted; the file name |
| .ds-doc-cell-dl | Injected download anchor | A 24px circular primary icon button; the class adds only position and reveal |
| .ds-doc-cell-flip | Injected mode-flip toggle | Partner-logo cells only. Toggles .is-flipped, showing the other mode's plate and logo |
- Partner-logo downloads save the version the cell shows: the theme's version by default, the other one while flipped. Brand lockups have their own export toolbar (
initBrandLockupExport) instead. - The mode flip is a preview, not a setting. Changing the page theme clears every flipped cell. The toggle is
.btn-neutral, so the download stays the one primary action; its glyph shows the mode a click switches to, like the header toggle. - Never write
.ds-doc-cell-dlby hand. The script adds it from the cell'ssrcordata-icon. .ds-doc-cell-dlsets only position and reveal. Don't override its fill, type or padding.- It's an icon button, not a chip. Chips stay labelled tone pills.
- Downloads give the full file:
/icons/<name>.svgfor icons and the largestsrcsetfile for images, so a portrait saves the 1024px master.
CSS: styles.css, search .ds-doc-cell-dl and .ds-doc-icon-cell.
JS: design-system/assets.html, the Per-asset download script and the lazy icon loader beside it.
Icon: icons/download.svg (Lucide v1.8.0).
Lightbox .lightbox
Click an asset to see it full size and step through the set with the arrows, ←/→ keys, scroll or swipe. A grid opts in with data-lightbox; marketing and product galleries can use it too.
Click a chain mark to open it. The Isometric Illustrations grid on the Assets page uses the ink frame; this gallery uses the default surface frame.
One overlay serves every gallery on the page. ink is for white-on-ink assets; surface is the default.
<!-- Items are direct <figure> children or [data-lightbox-item] -->
<div class="ds-iso-grid" data-lightbox="iso" data-lightbox-frame="ink">
<figure class="ds-iso-tile">
<svg class="bb-iso" viewBox="…">…</svg>
<figcaption class="ds-iso-cap">
<span class="ds-iso-name">Mac Studio</span>
<span class="ds-iso-meta">front</span>
</figcaption>
</figure>
</div>
<!-- Surface frame, caption from data attributes -->
<div data-lightbox="chains">
<figure data-lightbox-name="Ethereum" data-lightbox-meta="chainId 1">
<img src="../avatars/chains/ethereum.svg" alt="Ethereum">
</figure>
</div>
// Programmatic open (optional):
window.LifiLightbox.open(items, index, { trigger, frame: 'ink' });
| Part | Class / hook | Role |
|---|---|---|
| Scrim | .modal-overlay.lightbox | The modal overlay. A click on the bare scrim closes. |
| Viewer | .lightbox__viewer | Centered column: the framed asset over the caption. |
| Frame | .lightbox__frame · [data-frame="ink"] | Holds the cloned asset; surface by default, ink (--text-primary) for white-on-ink assets. |
| Caption | .lightbox__name · __meta · __counter | Name, mono meta and N / M (hidden for one item). |
| Chrome | .lightbox__close · .lightbox__nav--prev/next | .btn-icon.btn-borderless.btn-circle.btn-lg, white on the scrim in either theme. |
| Item | .is-lightbox-item | Added to each item: cursor: zoom-in, role="button", tabindex; opens on click, Enter or Space. |
| Controller | initLightbox() · window.LifiLightbox | Wires every [data-lightbox] on load; exposes open / close. |
- Opt in with
data-lightboxon the gallery; adddata-lightbox-frame="ink"for white-on-ink assets. No JS call needed. - Items are figures with an
<svg>or<img>. The asset is cloned, so CSS animations keep looping. - Navigate with the buttons, ←/→ keys, scroll or swipe; the set wraps around. Close with ✕, Esc or a click on the scrim.
- The caption comes from
data-lightbox-name/-meta, else the figcaption (.ds-iso-name/.ds-iso-meta, plain text, or its first two children), else<img alt>. - Download and flip buttons in a cell still work. Clicks on them don't open the lightbox, and the enlarged asset is the first visible one, so a partner logo shows in the right mode.
- Accessible. Items are keyboard buttons with an enlarge label; the overlay is
role="dialog" aria-modal="true"; the page doesn't scroll while it is open; focus returns to the tile on close. - Don't build a second viewer. Opt the grid into this one.
- CSS:
styles.css, search.lightbox — enlarge + navigate. - JS:
shared.js → initLightbox(); API onwindow.LifiLightbox. - Consumers:
design-system/assets.html: Isometric Illustrations ([data-lightbox="iso"], ink frame), Partner Logos ([data-lightbox="partner-logos"]), Portraits ([data-lightbox="portraits-personas"]/="portraits-team"). - Spec:
design/components/feedback.md→ Lightbox.