From c879b76da81a55ccb6f1e333b9163ca58d91cfa1 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 17 Jul 2026 20:00:01 +0000 Subject: [PATCH 1/2] docs(demo): add "what it is / when to use" captions to demo section groups MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 62 of 122 narrative

groups in demo/index.html lacked a one-line description saying what the group demonstrates and when to reach for it. Add a muted caption paragraph under each group that was missing one (65 groups), matching the existing caption style already used by the layout sections. Wording is grounded in the per-entry descriptions from docs/api-index.json. Two

s that are demo content rather than group headings (the "h3 — The quick brown fox" type specimen and the "Lists Are Restored" heading inside the .sf-prose sample) are intentionally left untouched. No token/class coverage change; coverage.test.js and the demo-visual e2e suite stay green. --- demo/index.html | 65 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/demo/index.html b/demo/index.html index b269f8f2..1c34337e 100644 --- a/demo/index.html +++ b/demo/index.html @@ -681,6 +681,7 @@

Theme Customizer

Light mode

+

Source brand and status colors for light mode — the full palette, surfaces and text contrasts are derived from these live.

Brand @@ -736,6 +737,7 @@

Light mode

Dark mode

+

The same source colors for dark mode — set independently so dark mode isn't just an inversion of light.

Brand @@ -810,6 +812,7 @@

Accessibility report The core brand roles every component pulls from — set these first; most other colors are derived from them.

primary
secondary
@@ -820,6 +823,7 @@

Brand — light mode (base values)

Semantic Surfaces

+

Background layers for elevation — page bg, raised cards, insets and overlays. Use to separate depth, not for decoration.

bg
surface
@@ -830,6 +834,7 @@

Semantic Surfaces

Status Colors

+

Feedback hues for success, warning, info and danger states. Use for alerts, badges and validation — not general accents.

success
warning
@@ -838,6 +843,7 @@

Status Colors

Status Triplets

+

Each status ships a subtle / base / strong trio — subtle for fills, base for text and icons, strong for emphasis or borders.

Success
Warning
@@ -846,6 +852,7 @@

Status Triplets

Text Hierarchy

+

Text-color roles from primary body down to disabled — use to signal importance, never to hardcode a grey.

--sf-color-text (primary)

--sf-color-text--secondary

@@ -856,6 +863,7 @@

Text Hierarchy

Borders

+

Border-color roles from subtle to strong — pick by how much separation the edge should carry.

--sf-color-border
--sf-color-border--subtle
@@ -864,6 +872,7 @@

Borders

Gradients

+

Ready-made brand gradients for hero fills, accents and text clipping. Pair with .sf-text-gradient for headline effects.

gradient-primary
gradient-secondary
@@ -873,6 +882,7 @@

Gradients

Palette Numeric Scale 50–950 (core/tokens.css)

+

The raw stepped palette behind the semantic roles — reach for a specific step only when no semantic token fits.

50
100
@@ -888,6 +898,7 @@

Palette Numeric Scale 50–950 Translucent neutrals (5–80% alpha) for overlays, hovers and dividers that tint whatever sits behind them.

a5
a10
@@ -897,6 +908,7 @@

Alpha Scale a5–a80

Semantic & Functional Aliases

+

Named shortcuts (link, focus, selection, code…) mapped to the palette — use these in components so a re-theme flows through.

superlight
xlight
@@ -924,6 +936,7 @@

Scoped Themes

Dark section data-theme="dark"

+

Any subtree can pin its own theme with data-theme — colors recompute from the scoped source, no utility classes needed.

primary
@@ -949,6 +962,7 @@

Light section (nested) data-theme="light"

+

Themes nest — a light island inside a dark section just works, each level resolving its own palette.

primary
@@ -1020,6 +1034,7 @@

Named background surface Typography

Heading Scale (base.css)

+

Default h1–h6 sizes, weights and leading applied to bare heading tags — the classless baseline for document typography.

h1 — The quick brown fox

h2 — The quick brown fox

@@ -1047,6 +1062,7 @@

Fluid Text Scale (--sf-text-*)

Font Weights — base weights + semantic roles

+

The weight ramp plus semantic aliases (body, heading, strong) — reference the role, not the number, so a font swap stays consistent.

300 light — The quick brown fox 400 normal — The quick brown fox @@ -1064,6 +1080,7 @@

Font Weights — base weights + semantic roles

Semantic Weight Aliases & Font Stacks

+

Font-family and weight roles (body, heading, mono) — the single place to retarget typefaces across the system.

body heading @@ -1077,6 +1094,7 @@

Semantic Weight Aliases & Font Stacks

Line Heights (--sf-leading-*)

+

Leading scale from tight (headings) to loose (long-form) — pick by line length and text size for comfortable reading.

--sf-leading-tight (1.1) @@ -1097,6 +1115,7 @@

Line Heights (--sf-leading-*)

Letter Spacing (--sf-tracking-*)

+

Tracking scale — tighten large display text, open up all-caps or small labels. Body copy stays at normal (0).

tracking-tight — THE QUICK BROWN FOX JUMPS OVER
tracking-normal — THE QUICK BROWN FOX JUMPS OVER
@@ -1130,6 +1149,7 @@

Semantic Elements (base.css)

Link States

+

Default, hover, visited and active link colors on bare — a consistent affordance with no utility class.

default link hover state @@ -1194,6 +1214,7 @@

Spacing

Spacing Aliases

+

Semantic gap names (gap, content-gap…) that resolve to the space scale — use these in layout so rhythm stays uniform.

--sf-gap → --sf-space-m --sf-content-gap → --sf-space-s @@ -1223,6 +1244,7 @@

Shadows

Text Shadows

+

Text-shadow scale for legibility over busy backgrounds or subtle heading depth — keep it restrained on body copy.

text-shadow-xs text-shadow-s @@ -1232,6 +1254,7 @@

Text Shadows

Drop Shadows (filter — follows alpha edges)

+

filter: drop-shadow that hugs an element's actual alpha shape — for icons, cut-outs and PNGs where box-shadow would look wrong.

@@ -1241,6 +1264,7 @@

Drop Shadows Perspective and transform tokens for depth — tilt cards or build 3D hovers without hand-tuning matrices.

@@ -1294,6 +1318,7 @@

Transitions (motion.css — hover these)

Easing Curves

+

The easing vocabulary (out, in-out, spring…) — match the curve to the gesture: ease-out for entrances, in-out for moves.

ease-linear @@ -1330,6 +1355,7 @@

Easing Curves

Animation Presets (motion.css — click to replay)

+

Drop-in entrance and attention animations — add one class to play. All respect prefers-reduced-motion.

@@ -1340,6 +1366,7 @@

Animation Presets .sf-stagger (motion.css — parent choreographs children's animation-delay; click to replay)

+

Put on a parent so its children's entrance animations play in sequence — choreography only; each child still brings its own animation.

  • 1
  • 2
    • @@ -1392,6 +1419,7 @@

    Duration Tokens

States (states.css)

+

The .sf-is-* state vocabulary — a shared, framework-wide way to mark active/open/valid/busy so CSS and JS agree.

.sf-is-loading

@@ -1425,6 +1453,7 @@

States — Full Coverage

Every .sf-is-* class from states.css. Grouped by category.

Navigation & Toggling

+

States for nav and toggles — .sf-is-active / -current / -selected mark where the user is and what they picked.

.sf-is-active (--sf-is-active: 1) .sf-is-current (bold) @@ -1433,6 +1462,7 @@

Navigation & Toggling

Disclosure

+

Open/closed states for accordions, menus and expandable panels — pair .sf-is-open with your reveal logic.

.sf-is-open .sf-is-expanded @@ -1440,6 +1470,7 @@

Disclosure

Validation / Feedback

+

Form-field states — .sf-is-valid / -invalid / -required drive inline validation styling.

.sf-is-valid .sf-is-invalid @@ -1451,6 +1482,7 @@

Validation / Feedback

Drag & Drop

+

Drag-and-drop states — mark the dragged item and valid drop targets while a drag is in progress.

.sf-is-dragging .sf-is-drop-target @@ -1458,11 +1490,13 @@

Drag & Drop

Overlay

+

States for overlay UI — .sf-is-open / -dismissed for modals, drawers and popovers.

.sf-overlay

Interactivity

+

Busy and loading states — signal that an element is working or temporarily inert.

.sf-is-busy .sf-is-readonly @@ -1476,6 +1510,7 @@

Interactivity

Empty State

+

.sf-is-empty styles a zero-content region — for empty lists, search results and blank slates.

.sf-is-empty:empty → display:none (the empty div above is gone) @@ -1578,6 +1613,7 @@

.sf-grid--dense

.sf-cover modifiers

+

Padding variants for the cover primitive — tune the breathing room around a hero's centered content.

.sf-cover--min @@ -1600,6 +1636,7 @@

.sf-cover modifiers

.sf-cluster--no-wrap / .sf-switcher--no-wrap / .sf-switcher--vertical

+

Opt out of wrapping/switching — keep a cluster or switcher on one row when scrolling beats reflow.

.sf-cluster--no-wrap @@ -1713,11 +1750,13 @@

.sf-equal — fixed N-column grid

.sf-scale-down (motion.css)

+

One-shot shrink-in animation for de-emphasis or dismissal — respects reduced-motion.

.sf-center / .sf-center--intrinsic

+

Flex-center children on both axes; add --intrinsic to shrink the box to its content instead of filling the parent.

.sf-center (max 20rem, auto margins) @@ -1730,6 +1769,7 @@

.sf-center / .sf-center--intrinsic

.sf-box

+

The simplest primitive — even padding on all sides via --sf-box-padding. Reach for it when you just need breathing room.

.sf-box — padding + outline border (no box-model disturbance) @@ -1826,6 +1866,7 @@

.sf-grid-flex — flex alternative for uneven item counts

.sf-sidebar--narrow / .sf-sidebar--wide

+

Preset sidebar widths — pick one without hand-setting --sf-sidebar-width.

.sf-sidebar--narrow (12rem sidebar) @@ -1844,6 +1885,7 @@

.sf-sidebar--narrow / .sf-sidebar--wide

.sf-container--full / .sf-container--wide

+

Wider container caps for dashboards and media-heavy pages that need more than the default reading width.

.sf-container--wide (90rem) @@ -1856,6 +1898,7 @@

.sf-container--full / .sf-container--wide

.sf-section--xs / .sf-section--l / .sf-section--xl / .sf-section--2xl

+

Vertical-padding sizes for content bands — set section rhythm from tight to airy.

.sf-section--xs (small vertical padding) @@ -1882,6 +1925,7 @@

.sf-header--xs / .sf-header--s / .sf-header--m / .sf-header--l / .sf-header-

.sf-frame--3-2 / .sf-frame--4-3 / .sf-frame--golden

+

Named aspect-ratio presets for media frames — common photo ratios without an inline --sf-frame-ratio.

.sf-frame--3-2 @@ -1904,6 +1948,7 @@

.sf-frame--3-2 / .sf-frame--4-3 / .sf-frame--golden

.sf-stack alignment: --center / --end / --stretch

+

Cross-axis alignment for a stack — center, end-align or stretch children without leaving the primitive.

.sf-stack--s --center @@ -2043,6 +2088,7 @@

.sf-cluster alignment: --center / --end / --between

.sf-cover--padding-l

+

Large-padding cover variant — more generous framing for spacious heroes.

padding-l (4xl)
@@ -2086,6 +2132,7 @@

.sr-only

Hidden from sighted users but available to screen readers: [THIS TEXT IS SCREEN-READER ONLY — not visible] (check with DevTools or a screen reader)

Disabled States

+

How disabled controls render — reduced contrast and no pointer affordance, while staying perceivable to assistive tech.

@@ -2461,6 +2508,7 @@

Layout — Pancake

Reset & Base

Form Elements (reset.css + base.css)

+

Bare inputs, selects and textareas styled by reset + base alone — consistent, themeable fields with zero classes.

@@ -2499,6 +2547,7 @@

Form Elements (reset.css + base.css)

Table (reset: border-collapse)

+

Default table styling — collapsed borders and padded cells straight from the reset, ready for data without a wrapper.

@@ -2539,6 +2588,7 @@

List Reset

HR & Separator

+

The default

— a themed divider using border-color tokens; spacing follows the surrounding rhythm.

Above: standard <hr> with border token. High-contrast mode thickens it automatically.

@@ -2570,11 +2620,13 @@

.no-print — vanishes from print

.print-color-exact — force colour preservation

+

Force backgrounds and colors to print exactly — for charts, badges and status fills that must survive on paper.

Colour-coded callouts that lose meaning when a browser flattens them. print-color-adjust: exact guarantees the tinted background reaches paper.

.print-no-color — opt back into ink-on-paper

+

Opt a region back into plain ink-on-paper for print — saves toner on decorative fills.

On screen this matches the callout above. In print preview the background goes transparent and text falls back to system colour. Use where ink-saving is the contract (corporate boilerplate forms, append-to-existing-document templates).
@@ -2632,6 +2684,7 @@

.sf-tabular-nums

.sf-flow — equal vertical rhythm

+

Adds uniform top-margin to every child after the first — prose-like vertical rhythm from one --sf-flow-space knob.

First child has no top margin (only siblings get the rhythm).

Second child gets margin-block-start: var(--sf-flow-space).

@@ -2639,12 +2692,14 @@

.sf-flow — equa

.sf-truncate — single-line ellipsis

+

Clips text to one line with an ellipsis — needs a finite width to bite. Use for labels and tight table cells.

This sentence is intentionally too long for the container so the ellipsis will appear — text-overflow ellipsis on a single line.

.sf-line-clamp-2 / -3 / -N

+

Clamp text to N lines with an ellipsis — fixed 2/3 variants or --sf-line-clamp for a custom count. Great for card previews.

2 lines: Lorem ipsum dolor sit amet, consectetur adipiscing @@ -2665,6 +2720,7 @@

.sf-line-clamp-2

.sf-aspect — generic ratio container

+

Holds any aspect-ratio from an inline --sf-aspect — content-agnostic, unlike .sf-frame which is media-specific.

@@ -2672,6 +2728,7 @@

.sf-aspect — ge

.sf-equal-height — children stretch to tallest

+

Makes flex children share the tallest one's height — even card rows without a grid.

Short.
Two
lines.
@@ -2679,6 +2736,7 @@

.sf-equal-height

.sf-scroll-shadow — top + bottom mask gradient

+

Fades content at the top and bottom of a scroll area to hint at hidden overflow — pure CSS, no scroll listener.

Scroll inside this box.

The mask gradient fades the top and bottom of the content.

@@ -2691,6 +2749,7 @@

.sf-scroll-shadow

.sf-scroll-snap — vertical scroll-snap container

+

Snaps each child into place as you scroll — for full-height section decks; use .sf-reel for horizontal snap.

Slide A
Slide B
@@ -2698,6 +2757,7 @@

.sf-scroll-snap

.sf-overflow-fade — end-edge mask

+

Fades the overflowing edge to hint at more content — drop on reels, tag rows and scroll containers.

tag-one @@ -2709,6 +2769,7 @@

.sf-overflow-fade

.sf-overflow-fade--* — directional variants

+

Pick which edge(s) fade — right, left, top, bottom, or a whole axis.

right: tag-one tag-two tag-three tag-four tag-five
left: tag-one tag-two tag-three tag-four tag-five
@@ -2719,6 +2780,7 @@

.sf-overflow-fade--*

.sf-no-tap-highlight — suppress mobile tap overlay

+

Removes the grey mobile tap flash on custom-styled interactive elements that supply their own active state.

@@ -2764,6 +2826,7 @@

Pri

.sf-surface--* — auto-flipped foreground

+

Paint an element in a brand or status family and get an auto-contrasting foreground and matching contextual tokens for free.

primary
secondary
@@ -2778,6 +2841,7 @@

.sf-surface--*

.sf-text-gradient — gradient-clipped text

+

Clips a brand gradient to the text itself — for headlines and hero words. Keep body copy solid for contrast.

Headline gradient

.sf-link-external — external-link indicator

@@ -2870,6 +2934,7 @@

.sf-focus-shadow

.sf-section--collapse — adjacent sections share padding

+

Removes a section's vertical padding so two same-color bands sit flush — avoids doubled gaps between stacked sections.

Section A — primary surface

From fd53af09515f27c0fc38287baf0344a29a20b9d1 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 17 Jul 2026 20:48:56 +0000 Subject: [PATCH 2/2] fix(demo): escape and
tag names in two captions Two of the new captions wrote HTML element names as raw tags in text: "bare " (Link States) and "default
" (HR & Separator). Because

cannot contain a block-level

, the browser closed the paragraph early and orphaned the trailing text; the raw wrapped the rest of the sentence in an empty anchor. Escape both to <a> / <hr>, matching the convention already used elsewhere in the file. Flagged by Greptile review on PR #630. --- demo/index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/demo/index.html b/demo/index.html index 1c34337e..3cda6ec9 100644 --- a/demo/index.html +++ b/demo/index.html @@ -1149,7 +1149,7 @@

Semantic Elements (base.css)

Link States

-

Default, hover, visited and active link colors on bare — a consistent affordance with no utility class.

+

Default, hover, visited and active link colors on bare <a> — a consistent affordance with no utility class.

default link hover state @@ -2588,7 +2588,7 @@

List Reset

HR & Separator

-

The default

— a themed divider using border-color tokens; spacing follows the surrounding rhythm.

+

The default <hr> — a themed divider using border-color tokens; spacing follows the surrounding rhythm.

Above: standard <hr> with border token. High-contrast mode thickens it automatically.