Documentation

How to write a catalog card, and the .ds-doc-* primitives cards are built from.

Start Here
Documentation
The rules of the 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

Audience & Why

Audience priority

When the three readers' needs conflict, the designer's scanning speed wins.

  1. Designers scan it visually and recognise components by label and preview.
  2. Engineers arrive with a component name and open Markup, Specs or Source for code.
  3. Marketing uses it as a brand reference: real previews in the live palette.

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

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.

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 .classes chip 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";
ClassUse
.btn-primaryPrimary action — the dominant CTA
.btn-secondaryPaired 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 px

Family · 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.

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>

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

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.

Inherited
Foundation token via slot
var(--accent-primary) .btn-primary · .chip-accent1 · .status-dot
From a foundation token (accent, semantic state, surface, text) with no scoped remap. The most common flag.
Override
Scoped recipe or remap
color-mix(...) · --slot remap .checkbox input:checked · .btn-destructive · .tile.is-active
A new recipe that diverges from the system default, such as a color-mix(…) blend, a remapped slot or a component shadow.
Convention
Locked per-widget literal
oklch(100% 0 0 / 0.05) · #FFFFFF · brand pair .fab:hover halo · .btn-neutral · .brand-tile
A fixed value locked to this widget, such as brand-tile colours, alpha-overlay buttons, the FAB hover ring or the modal scrim. Don't reuse it elsewhere.

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.

Structure & Spacing

Section + card spacing

The CSS spaces sections, subsections and cards. Don't add dividers, <hr> or spacers.

// 02 — My Section

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

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

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

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.

Resources
Viewport
The preview surface for components, extended with sub-components and modifiers. New demos use .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.

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.

badge

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.

Paper
Solid card
Glass
Translucent + blur
Halo
Brand wash
Gradient
Brand fill

Layout, size and height modifiers combine freely; see Anatomy.

Authoring

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.

ethereum
ethereum
activity
kim
kim

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