@monospaced/set-skills 0.0.0

package/README.md

@@ -0,0 +1,39 @@
+## @monospaced/set-skills
+
+Markdown guardrails for AI coding agents (and humans) building sites and apps with Set.
+
+Each skill is a folder containing a `SKILL.md` (with `name` and `description` frontmatter) plus optional sibling `examples/`, `references/`, and `assets/` folders. The shape is shared by Claude Code and OpenAI Codex, so authoring vendor-neutral skills works in both.
+
+## About Set
+
+These skills are companion content for the Set design system: `@monospaced/set-{core,assets,config,tokens}` (and `@monospaced/set-react` for React projects), serving the **Monospaced** brand.
+
+- **Compositional** — components encode design choices in their props; consumers compose UI from the system's vocabulary rather than authoring custom CSS.
+- **Multi-context** — tokens resolve under theme (light / dark), brand, and surface context automatically.
+- **Brand contexts**:
+  - `mnsp` — the public-facing Monospaced brand.
+  - `wrfr` — a stripped-back wireframe expression of the same brand (monochrome, no rounding, no motion). Use for wireframes, sketches, and internal tools.
+  - `base` — structural foundation layer. Not a brand; consumers don't pick it.
+- **Voice (for content, copy, and naming decisions)** — calm, business-like, time-less; organised and precise.
+
+The operational skills below cover _how_ to use the system; this section is just orientation.
+
+## Install
+
+```sh
+pnpm add -D @monospaced/set-skills
+```
+
+## Use
+
+Copy or symlink the skill folders this package ships into your agent's discovery directory:
+
+- **Claude Code** → `.claude/skills/`
+- **OpenAI Codex** → `.agents/skills/`
+
+```sh
+# Example: install all skills for Claude Code
+cp -r node_modules/@monospaced/set-skills/src/* .claude/skills/
+```
+
+Refer to your agent's documentation for the canonical discovery paths.

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@monospaced/set-skills",
+  "version": "0.0.0",
+  "description": "Markdown guardrails for AI coding agents (and humans) building sites and apps with Set.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/monospaced/set.git",
+    "directory": "packages/skills"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    "./*": "./src/*"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ]
+}

package/src/compose-first/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: compose-first
+description: Use Set's components to build pages and sections, before authoring custom CSS. Read this when generating markup with @monospaced/set-core or @monospaced/set-react.
+---
+
+# Compose first
+
+Set is a compositional system. The fastest path to a correct, accessible, on-brand UI is to build out of the system's components and let their props express your intent — essentially no custom CSS, only tokens for minor edge-case tweaks. Anything beyond that belongs to the next layer.
+
+Inline code in this skill is shown in JSX for compactness. See `@monospaced/set-skills/compose-first/examples/core/` for template-string equivalents and `@monospaced/set-skills/compose-first/examples/react/` for the parallel JSX.
+
+## Root is required
+
+Every Set app must be wrapped in `Root`. It emits the `.set` scoping class that every component's CSS targets, sets the brand and (optional) theme, and carries language / direction attributes. Without it, components render unstyled.
+
+For a top-level app, set `appRoot`:
+
+```tsx
+<Root appRoot>{/* page composition here */}</Root>
+```
+
+For embedded use (e.g. injecting Set into a portion of a non-Set page), omit `appRoot`. `Root` still scopes its subtree.
+
+## Surface (color context)
+
+`Surface` sets a color context for nested content. Wrap a region in `Surface` to apply a different context — e.g. a brand-coloured strip inside an otherwise-default page:
+
+```tsx
+<Surface variant="brand">
+  {/* content renders against the brand surface */}
+</Surface>
+```
+
+`Surface` can scope context across any region — a single strip, a section, or the whole page.
+
+Several components (`Box`, `Card`, `Panel`, etc.) also accept a `surface` prop — switch context at the component level without a separate wrapper:
+
+```tsx
+<Box surface="brand" paddingBlock="xl">
+  {/* ... */}
+</Box>
+```
+
+## Layout primitives
+
+Reach for these first:
+
+- `Page` — top-level shell with `banner`, `header`, `children` (main), `footer` slots.
+- `Container` — wraps page-level content with a bounded inline width.
+- `Grid` + `GridItem` — 12-column responsive layout. The primary chassis for main content beyond a single column.
+- `Stack` — vertical group with consistent `gap` (token-driven flex wrapper).
+- `Inline` — horizontal group with consistent `gap` (token-driven flex wrapper).
+- `Box` — a low-level boundary and inset primitive with optional light containment.
+
+The canonical main-content chain is `Root` → `Page` → `Container` → `Grid` → `GridItem` → `Stack` / `Inline`. `Box` is a low-level primitive with no fixed position — wrap any step where padding, background, or border is needed (commonly around `Grid` for section padding, around `Stack`/`Inline` inside a `GridItem`, or around individual children). Site furniture (headers, footers, navigation) typically nests more simply — `Container` → `Inline` / `Stack` — with `Box` where padding rhythm is needed.
+
+`Stack` and `Inline` hold a single fixed arrangement — `Inline` wraps when it runs out of room, but neither _switches_ arrangement at a breakpoint (e.g. stacked when narrow, side-by-side when wide). Responsive layout change lives in `Grid` / `GridItem`, and that is page-level. A self-contained block that needs its own breakpoint-driven layout switch is a genuine gap — handle it in the custom-with-tokens layer (a local component with container- or media-query CSS), not by forcing `Stack` / `Inline`.
+
+## Decision flow
+
+When asked to build a page or section:
+
+1. **Pages** → use `Page`. Assemble `header` / `children` / `footer` slots from compositions, not custom HTML. The optional `banner` slot expects a `Banner` component (site-wide dismissible announcement).
+2. **Bounded content** → use `Container`. Don't author custom max-width wrappers.
+3. **Main content layout** → use `Grid` + `GridItem`. The 12-column responsive system is the primary chassis for page bodies. `GridItem` is a wrapper around the CSS grid-item layout surface — column/row placement, spans, alignment — configured per-item via props (not via classes on the parent).
+4. **Vertical groups** → use `Stack` with `gap`. Not margins.
+5. **Horizontal groups** → use `Inline` with `gap`. Not flex.
+6. **Insetting content or applying a boundary** → use `Box` (low-level primitive). For higher-level contained content (a styled container as a unit), reach for `Panel`.
+7. **Structural patterns** → use the matching component (cards, navigation, posters, sidebars, etc.) rather than re-rolling. Check the References below for components you may not know about.
+8. **Headings** → use `Heading`. `level` and `size` are deliberately decoupled — pick `level` for semantic hierarchy (no skipped levels), `size` for visual treatment.
+9. **Inline copy or authored paragraphs** → use `Text`. Supports inline (`as: "span"`) and paragraph (`as: "p"`) form, and accepts inline markup (`<em>`, `<strong>`, `<a>`, `<code>`, etc.) as children for emphasis, links, and code.
+10. **Rich text** (raw block markup, typically from markdown or CMS HTML) → use `Prose`. It styles `<h1>`–`<h6>`, `<p>`, lists, tables, etc. per the system's typography. For paragraphs you compose directly in your layout, use `Text` instead.
+11. **Other leaves** (image, icon, link, button, divider, etc.) → use the matching content component instead of raw HTML. Check the References below for components you may not know about.
+
+## Smell tests
+
+Custom CSS at this layer is at most a one-off, token-based tweak (e.g. nudging a single property by a small amount). If you're about to write more than that, stop. One of two things is true:
+
+- You missed a compositional path — re-read the decision flow above, and check the References for components you may not know about.
+- The system doesn't cover this case, so you've left compose-first — move to the next layer (custom with tokens).
+
+## When composition isn't enough
+
+If a layout genuinely can't be expressed with the existing components, the next layer is custom markup with design tokens. That layer has its own guidance.
+
+## Examples
+
+Worked examples live alongside this skill:
+
+- `@monospaced/set-skills/compose-first/examples/core/` — for `@monospaced/set-core` consumers (SSR / web components / template strings).
+- `@monospaced/set-skills/compose-first/examples/react/` — for `@monospaced/set-react` consumers.
+
+Pick the flavor matching your project.
+
+## References
+
+- Component catalog (live): [Storybook](https://set.monospaced.com/storybook).
+- Component SPECs: imported from `@monospaced/set-core` (e.g. `SET_STACK_SPEC`) — runtime values with top-level `description` and per-prop documentation. Confirms what each component does before you reach for raw HTML.
+- Token catalog (CSS, browseable in your editor): `@monospaced/set-config/set.catalog.css`.
+- Token data (JSON, for agents and tooling): `@monospaced/set-tokens/mnsp`, `@monospaced/set-tokens/base`.

package/src/compose-first/examples/core/full-page.md

@@ -0,0 +1,130 @@
+# Full page (core)
+
+A complete page composition: branded header with nav, a content intro section laid on the 12-column responsive grid, footer. Built entirely from Set components — no custom CSS.
+
+```ts
+import {
+  defineSetNav,
+  renderSetBox,
+  renderSetButton,
+  renderSetContainer,
+  renderSetDivider,
+  renderSetGrid,
+  renderSetGridItem,
+  renderSetHeading,
+  renderSetInline,
+  renderSetLogo,
+  renderSetNav,
+  renderSetPage,
+  renderSetRoot,
+  renderSetStack,
+  renderSetText,
+} from "@monospaced/set-core";
+
+defineSetNav();
+
+const page = renderSetPage({
+  headerBorder: "scroll",
+  headerSize: "lg",
+  stickyHeader: "always",
+  header: renderSetContainer({
+    gutter: "narrow",
+    maxInlineSize: "wide",
+    children: renderSetBox({
+      paddingBlock: "sm",
+      paddingInline: "none",
+      responsive: true,
+      children: renderSetInline({
+        gap: "sm",
+        justify: "between",
+        children: [
+          `<a href="/">${renderSetLogo({ label: "Brand", variant: "secondary" })}</a>`,
+          renderSetNav({
+            collapsible: "belowTablet",
+            contentId: "site-nav",
+            expanderPosition: "end",
+            items: [
+              { current: true, href: "/", label: "Home" },
+              { href: "/work", label: "Work" },
+              { href: "/about", label: "About" },
+            ],
+          }),
+        ].join(""),
+      }),
+    }),
+  }),
+  children: renderSetContainer({
+    children: renderSetBox({
+      paddingBlock: "2xl",
+      paddingInline: "none",
+      children: renderSetGrid({
+        children: renderSetGridItem({
+          colSpan: 6,
+          colSpanNarrow: 12,
+          children: renderSetStack({
+            align: "start",
+            gap: "lg",
+            children: [
+              renderSetHeading({
+                level: 1,
+                responsive: true,
+                size: "4xl",
+                text: "A heading that anchors the section",
+              }),
+              renderSetText({
+                as: "p",
+                children:
+                  "Supporting copy that introduces the topic. Set's Text component handles the type scale and measure so this paragraph reads well at any viewport.",
+              }),
+              renderSetButton({
+                appearance: "solid",
+                label: "Get started",
+                size: "lg",
+              }),
+            ].join(""),
+          }),
+        }),
+      }),
+    }),
+  }),
+  footer: renderSetContainer({
+    gutter: "narrow",
+    maxInlineSize: "wide",
+    children: [
+      renderSetDivider({ tone: "brand" }),
+      renderSetBox({
+        paddingBlock: "sm",
+        paddingInline: "none",
+        responsive: true,
+        children: renderSetText({
+          as: "p",
+          tone: "muted",
+          children: "© 2026 Brand",
+        }),
+      }),
+    ].join(""),
+  }),
+});
+
+const html = renderSetRoot({
+  appOverscrollBehavior: "none",
+  appRoot: true,
+  children: page,
+});
+```
+
+## What's compositional here
+
+- **Root** wraps the app, emitting the `.set` scoping class every component's CSS targets. `appRoot` marks this as the owning app root.
+- **Page** owns the shell layout. Header is sticky.
+- **Container** bounds the header, main, and footer. The header / footer use a wider `gutter` and `maxInlineSize`; main keeps the default reading width.
+- **Box** carries vertical padding rhythm — `sm` for header, `2xl` for main, `md` for footer.
+- **Inline** lays out the logo and nav with `justify: "between"`.
+- **Nav** is a structural component that handles collapse / expander wiring at narrow viewports.
+- **Grid** + **GridItem** lay the main content on the 12-column responsive system. The item spans 6 columns at the default container threshold and falls back to all 12 at narrow viewports — the breakpoint behavior is built into the primitive.
+- **Stack** stacks the heading, copy, and CTA inside the grid item with a consistent `gap`. No margins.
+- **Heading**, **Text**, **Button**, **Logo**, **Divider** are content leaves.
+
+Main content runs the canonical chassis — **Root → Page → Container → Grid → GridItem → Stack → leaves** — with **Box** providing the section padding around the Grid (Box is a flexible primitive, applied wherever padding / background / border is needed; it has no fixed position in the chain). Site furniture (header, footer) rarely needs the column system, so it nests more simply: **Container → Inline → leaves**, again with Box where padding rhythm is needed.
+
+No custom CSS.

package/src/compose-first/examples/react/full-page.md

@@ -0,0 +1,104 @@
+# Full page (react)
+
+A complete page composition: branded header with nav, a content intro section laid on the 12-column responsive grid, footer. Built entirely from Set components — no custom CSS.
+
+```tsx
+import {
+  Box,
+  Button,
+  Container,
+  Divider,
+  Grid,
+  GridItem,
+  Heading,
+  Inline,
+  Logo,
+  Nav,
+  Page,
+  Root,
+  Stack,
+  Text,
+} from "@monospaced/set-react";
+
+export function App() {
+  return (
+    <Root appOverscrollBehavior="none" appRoot>
+      <Page
+        headerBorder="scroll"
+        headerSize="lg"
+        stickyHeader="always"
+        header={
+          <Container gutter="narrow" maxInlineSize="wide">
+            <Box paddingBlock="sm" paddingInline="none" responsive>
+              <Inline gap="sm" justify="between">
+                <a href="/">
+                  <Logo label="Brand" variant="secondary" />
+                </a>
+                <Nav
+                  collapsible="belowTablet"
+                  contentId="site-nav"
+                  expanderPosition="end"
+                  items={[
+                    { current: true, href: "/", label: "Home" },
+                    { href: "/work", label: "Work" },
+                    { href: "/about", label: "About" },
+                  ]}
+                />
+              </Inline>
+            </Box>
+          </Container>
+        }
+        footer={
+          <Container gutter="narrow" maxInlineSize="wide">
+            <Divider tone="brand" />
+            <Box paddingBlock="sm" paddingInline="none" responsive>
+              <Text as="p" tone="muted">
+                © 2026 Brand
+              </Text>
+            </Box>
+          </Container>
+        }
+      >
+        <Container>
+          <Box paddingBlock="2xl" paddingInline="none">
+            <Grid>
+              <GridItem colSpan={6} colSpanNarrow={12}>
+                <Stack align="start" gap="lg">
+                  <Heading
+                    level={1}
+                    responsive
+                    size="4xl"
+                    text="A heading that anchors the section"
+                  />
+                  <Text as="p">
+                    Supporting copy that introduces the topic. Set's Text
+                    component handles the type scale and measure so this
+                    paragraph reads well at any viewport.
+                  </Text>
+                  <Button appearance="solid" label="Get started" size="lg" />
+                </Stack>
+              </GridItem>
+            </Grid>
+          </Box>
+        </Container>
+      </Page>
+    </Root>
+  );
+}
+```
+
+## What's compositional here
+
+- **Root** wraps the app, emitting the `.set` scoping class every component's CSS targets. `appRoot` marks this as the owning app root.
+- **Page** owns the shell layout. Header is sticky.
+- **Container** bounds the header, main, and footer. The header / footer use a wider `gutter` and `maxInlineSize`; main keeps the default reading width.
+- **Box** carries vertical padding rhythm — `sm` for header, `2xl` for main, `md` for footer.
+- **Inline** lays out the logo and nav with `justify="between"`.
+- **Nav** is a structural component that handles collapse / expander wiring at narrow viewports.
+- **Grid** + **GridItem** lay the main content on the 12-column responsive system. The item spans 6 columns at the default container threshold and falls back to all 12 at narrow viewports — the breakpoint behavior is built into the primitive.
+- **Stack** stacks the heading, copy, and CTA inside the grid item with a consistent `gap`. No margins.
+- **Heading**, **Text**, **Button**, **Logo**, **Divider** are content leaves.
+
+Main content runs the canonical chassis — **Root → Page → Container → Grid → GridItem → Stack → leaves** — with **Box** providing the section padding around the Grid (Box is a flexible primitive, applied wherever padding / background / border is needed; it has no fixed position in the chain). Site furniture (header, footer) rarely needs the column system, so it nests more simply: **Container → Inline → leaves**, again with Box where padding rhythm is needed.
+
+No custom CSS.

package/src/custom-with-tokens/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: custom-with-tokens
+description: When the system has a gap — a missing component, variant, or pattern — fill it using Set's existing components for everything that fits, and tokens for any residual CSS values. Read this when compose-first has run out and you're about to author custom markup.
+---
+
+# Custom with tokens
+
+The fastest path through a gap is _with_ the system, not around it.
+
+## When this applies
+
+You've worked through the compose-first decision flow and one of two things is true:
+
+- The system genuinely doesn't cover the case (e.g. a Stepper — see the worked example below).
+- The case wants a visual treatment outside any existing component's prop surface.
+- A self-contained block needs breakpoint-driven layout that no prop exposes — `Stack` / `Inline` hold one arrangement (`Inline` only wraps) and `Grid` / `GridItem` responsiveness is page-level, so component-local layout switching is a genuine gap.
+
+If you haven't checked compose-first first, do that. Many "I need custom markup/CSS" intuitions evaporate once you find the right component.
+
+## The layered model
+
+When you fill a gap:
+
+1. **Reuse existing components.** Inside your custom markup, reach for Set components wherever they apply — `Icon`, `Button`, `Heading`, `Text`, `Link`, `Divider`, `Image`, etc. Many leaves you'd reach for in plain HTML have a Set equivalent that handles a11y, sizing, and brand defaults for free. Check the References below for components you may not know about.
+2. **Write custom markup + CSS** for the parts no component covers — the structure, the wiring, the bespoke piece.
+3. **Reference tokens for design values.** Colors, spacing, dimensions, typography, motion, shadows, opacity, etc. — reach for `var(--set-*)` whenever the system has a token. Tokens resolve under theme (light / dark), brand, and surface context automatically; responsive variants (typography, layout spacing) carry breakpoint scale baked in. Raw values lose all of that. See the References below for the catalog.
+
+The order matters. Tokens won't backfill what a component would have given you (a11y, sizing, brand defaults). Reach for the component first; only diverge when the design genuinely needs something outside its prop surface.
+
+## Picking the right token
+
+The published token catalog ships at `@monospaced/set-config/set.catalog.css` — a `:root` block listing every `--set-*` token with its resolved value and `$description`. The same data ships as DTCG JSON via `@monospaced/set-tokens/{mnsp,base}` if your tooling wants tokens as data.
+
+Tokens are organised by category prefix (e.g. `--set-color-*`, `--set-spacing-*`, `--set-radius-*`). The category narrows the search; the `$description` on each token confirms semantic intent — read it before reaching for a token whose name sounds right.
+
+If the right token feels missing for your case, that may signal a system gap worth surfacing as an issue rather than an opportunity to reach for a literal value.
+
+## Accessibility
+
+All UI built with Set must meet [WCAG 2.2 AA](https://www.w3.org/TR/WCAG22/) — the same bar the system holds itself to internally. A few points specific to Set worth highlighting:
+
+- **Color contrast follows from tokens.** Set's color tokens are tuned to meet WCAG AA contrast minimums for their _intended pairings_. Each token's `$description` names its role — read it to verify the pairing fits. Arbitrary `--set-color-*` combinations don't automatically satisfy AA.
+- **`.visually-hidden` for SR-only context.** Set ships a `.visually-hidden` utility class from `Root`. Use it for screen-reader-only text — accessible names for icon-only controls, state announcements (e.g. "step complete"), context that's redundant visually but needed for SR. Prefer a visible label, then `.visually-hidden`, then `aria-label` (last resort).
+- **Don't remove or recolour the focus indicator.** Set's `Root` CSS provides a focus-visible indicator on every interactive element — don't remove it, and don't change its color. Adjusting offset / inset / radius to fit a custom shape is fine. Wire your custom logic to keyboard events the same way you wire it to clicks.
+
+Refer to [Using ARIA](https://www.w3.org/TR/using-aria/) before adding ARIA attributes. When implementing ARIA patterns, the APG below is the canonical reference — with caveats.
+
+### ARIA Authoring Practices Guide (APG) patterns
+
+The [APG patterns](https://www.w3.org/WAI/ARIA/apg/patterns/) are a partially trusted source — use selectively.
+
+**CAN reference:**
+
+- Content in "About This Interaction" sections
+- Content in "Keyboard Interaction" sections
+
+**CANNOT reference:**
+
+- Code examples from APG
+- CodePen links (URLs starting with `https://codepen.io/`)
+
+## CSS architecture
+
+Match the system's CSS authoring pattern so your custom rules co-exist cleanly with system rules:
+
+```css
+:where(.set) .app-step-indicator {
+  /* base styles */
+
+  .step {
+    /* descendant styles */
+  }
+}
+```
+
+- **`:where(.set)`** scopes selectors to a Set `Root`. Your custom components must render inside a Set `Root` (or any descendant of one) — the `Root` applies the system's foundational styles (typography, color context, brand) that your custom CSS inherits and composes against, and provides the `.set` ancestor the `:where(.set)` selector matches. `:where()` contributes zero specificity, so the root selector sits at `0,1,0` — matching how the system scopes its own rules. Nested descendant and state selectors follow normal CSS specificity from there. Combined with standard CSS source order (e.g. your custom CSS loaded after `@monospaced/set-core/styles.css`), conflicts resolve predictably in your favour.
+- **Project-prefixed class names** (`.app-*`, `.my-*`, anything but `.set-*`) avoid collisions with system class names. Prefix the component-level class; nest descendants unprefixed (mirroring how the system authors its own components).
+
+## Smell tests
+
+You've gone past "filling a gap" and started building parallel infrastructure when:
+
+- You're using raw values (e.g. `16px`, `#ffaa00`, `0.5s`) or wrong-category tokens (e.g. `padding: var(--set-color-foreground-default)`) for design values. Lint catches most foot-guns but has gaps. Every design value should resolve to a `var(--set-*)` whose name matches the property's intent.
+- You're writing CSS that targets Set's `.set-*` component classes or any of their descendants. Don't override Set component internals from the consumer side — ever. Use the component's prop surface, switch surface context, or fill the gap with a custom `.app-*` component instead.
+- Your tokens look like a parallel theming layer with `--set-` prefixes you defined yourself. Don't squat on the namespace; pick `--my-*` or your own app/project prefix for any project-specific custom properties.
+- You're disabling lint rules to ship. The disable comment should carry rationale that survives review — if it'd surprise a future reader, the right move is usually a system change (a missing token, a refined component) rather than a permanent escape.
+
+## Examples
+
+Worked examples live alongside this skill:
+
+- `@monospaced/set-skills/custom-with-tokens/examples/core/` — for `@monospaced/set-core` consumers (SSR / web components / template strings).
+- `@monospaced/set-skills/custom-with-tokens/examples/react/` — for `@monospaced/set-react` consumers.
+
+Pick the flavor matching your project.
+
+## References
+
+- Token catalog (CSS, browseable in your editor): `@monospaced/set-config/set.catalog.css`.
+- Token data (JSON, for agents and tooling): `@monospaced/set-tokens/mnsp`, `@monospaced/set-tokens/base`.
+- Component catalog (live): [Storybook](https://set.monospaced.com/storybook).
+- Component SPECs: imported from `@monospaced/set-core` (e.g. `SET_BUTTON_SPEC`) — runtime values with top-level `description` and per-prop documentation. Confirms what each component does before you reach for raw HTML.

package/src/custom-with-tokens/examples/core/stepper.md

@@ -0,0 +1,215 @@
+# Stepper (core)
+
+Multi-step process indicator (onboarding, checkout, multi-page form). A row of numbered steps with `done`, `current`, and `upcoming` visual states, connected by a baseline. Set doesn't ship one, so it's a clear gap to fill.
+
+The example exercises the layered model end-to-end: a leaf component for the done-state checkmark, custom markup for the structural pattern, tokens for every design value (with one component-scoped custom property composed from tokens), and `@keyframes` driving state transitions through motion tokens.
+
+```ts
+import { renderSetIcon, renderSetRoot } from "@monospaced/set-core";
+
+type Step = { label: string; number: number };
+type StepState = "current" | "done" | "upcoming";
+
+const steps: Step[] = [
+  { number: 1, label: "Plan" },
+  { number: 2, label: "Build" },
+  { number: 3, label: "Ship" },
+];
+
+function getStepState(index: number, currentStep: number): StepState {
+  if (currentStep >= steps.length) return "done";
+  if (index < currentStep) return "done";
+  if (index === currentStep) return "current";
+  return "upcoming";
+}
+
+function renderStateLabel(state: StepState): string {
+  if (state === "done")
+    return '<span class="visually-hidden">, completed</span>';
+  if (state === "current")
+    return '<span class="visually-hidden">, current step</span>';
+  return "";
+}
+
+function renderStepper({ currentStep }: { currentStep: number }): string {
+  const items = steps
+    .map(({ number, label }, index) => {
+      const state = getStepState(index, currentStep);
+      const ariaCurrent = state === "current" ? ' aria-current="step"' : "";
+
+      return `
+        <li class="step" data-state="${state}"${ariaCurrent}>
+          <span class="bubble" aria-hidden="true">
+            <span class="bubble-number">${number}</span>
+            <span class="bubble-icon">${renderSetIcon({
+              ariaHidden: true,
+              name: "check",
+              size: "xs",
+            })}</span>
+          </span>
+          <span class="label">${label}${renderStateLabel(state)}</span>
+        </li>
+      `;
+    })
+    .join("");
+
+  return `<ol class="app-stepper">${items}</ol>`;
+}
+
+// Render inside a Set Root — the `.set` ancestor scopes both system
+// CSS and your `:where(.set) .app-stepper` selector.
+const html = renderSetRoot({
+  appRoot: true,
+  children: renderStepper({ currentStep: 1 }),
+});
+```
+
+```css
+@keyframes app-stepper-check-in {
+  from {
+    opacity: 0;
+    scale: 0.7;
+  }
+
+  to {
+    opacity: 1;
+    scale: 1;
+  }
+}
+
+:where(.set) .app-stepper {
+  --app-stepper-size: var(--set-spacing-vertical-800);
+
+  display: flex;
+  list-style: none;
+  margin: 0;
+  padding-inline: 0;
+
+  .bubble {
+    background-color: var(--set-color-background-subtle);
+    block-size: var(--app-stepper-size);
+    border-radius: calc(var(--app-stepper-size) * var(--set-radius-ratio-lg));
+    color: var(--set-color-foreground-muted-text);
+    display: grid;
+    font: var(--set-typography-text-body-xs);
+    font-variant-numeric: tabular-nums;
+    font-weight: var(--set-typography-font-weight-bold);
+    inline-size: var(--app-stepper-size);
+    place-items: center;
+    position: relative;
+    transition:
+      background-color var(--set-motion-duration-200)
+        var(--set-motion-easing-ease-in-out),
+      color var(--set-motion-duration-200) var(--set-motion-easing-ease-in-out);
+  }
+
+  .bubble-icon,
+  .bubble-number {
+    grid-area: 1 / 1;
+  }
+
+  .bubble-icon {
+    opacity: 0;
+    scale: 0.7;
+  }
+
+  .label {
+    color: var(--set-color-foreground-muted-text);
+    font: var(--set-typography-text-body-xs);
+    font-weight: var(--set-typography-font-weight-medium);
+  }
+
+  .step {
+    display: grid;
+    flex: 1;
+    gap: var(--set-spacing-vertical-400);
+    isolation: isolate;
+    justify-items: center;
+    position: relative;
+    text-align: center;
+
+    &::after {
+      background-color: var(--set-color-border-subtle);
+      block-size: var(--set-layout-border-width-thick);
+      content: "";
+      inline-size: 100%;
+      inset-block-start: calc(
+        (var(--app-stepper-size) / 2) -
+          (var(--set-layout-border-width-thick) / 2)
+      );
+      inset-inline-start: 50%;
+      position: absolute;
+      z-index: -1;
+    }
+
+    &:first-child {
+      justify-items: start;
+    }
+
+    &:first-child::after {
+      inline-size: calc(150% - (var(--app-stepper-size) / 2));
+      inset-inline-start: calc(var(--app-stepper-size) / 2);
+    }
+
+    &:first-child .label {
+      translate: calc((var(--app-stepper-size) - 100%) / 2) 0;
+    }
+
+    &:nth-last-child(2)::after {
+      inline-size: calc(150% - (var(--app-stepper-size) / 2));
+    }
+
+    &:last-child {
+      justify-items: end;
+    }
+
+    &:last-child::after {
+      display: none;
+    }
+
+    &:last-child .label {
+      translate: calc((100% - var(--app-stepper-size)) / 2) 0;
+    }
+
+    &[data-state="done"]::after {
+      background-color: var(--set-color-foreground-default);
+    }
+  }
+
+  .step[data-state="current"] .bubble,
+  .step[data-state="done"] .bubble {
+    background-color: var(--set-color-foreground-default);
+    color: var(--set-color-foreground-contrast);
+  }
+
+  .step[data-state="done"] .bubble-icon {
+    animation: app-stepper-check-in var(--set-motion-duration-200)
+      var(--set-motion-easing-ease-out);
+    opacity: 1;
+    scale: 1;
+  }
+
+  .step[data-state="done"] .bubble-number {
+    opacity: 0;
+  }
+
+  .step[data-state="current"] .label,
+  .step[data-state="done"] .label {
+    color: var(--set-color-foreground-default);
+  }
+}
+```
+
+What sits where:
+
+- **Leaf component for the content node.** `renderSetIcon` for the done-state checkmark — Set handles its sizing, color inheritance, and a11y. The number and the icon both render unconditionally; CSS reveals the right one for the state via `opacity` + `@keyframes`.
+- **Custom markup expresses the structural pattern.** The `<ol>` / `<li>` / `<span>` skeleton captures "row of state-driven circles connected by a baseline." `aria-current="step"` carries the active-step semantics for screen readers; the bubble is `aria-hidden` because state is conveyed by both `aria-current` and the `.visually-hidden` text appended to the label (`, completed` / `, current step`). `.visually-hidden` is a Set utility class shipped from Root — no need to redefine.
+- **Why not `renderSetText` for numbers and labels?** Text's prop surface doesn't expose `font-weight` or `font-variant-numeric`, and the design needs specific weights (bold for numbers, medium for labels) and tabular figures for the bubble's number to align across states. This is exactly the second branch the skill names in "When this applies" — _the case wants a visual treatment outside any existing component's prop surface_. Drop to a plain `<span>` and reach for typography composites + targeted overrides instead.
+- **Composite typography token + targeted overrides.** `font: var(--set-typography-text-body-xs)` carries the system's full body-xs spec (size, family, line-height) in one declaration. Specific properties then override only the deviations: `font-weight` switches per role (`bold` / `medium`); `font-variant-numeric: tabular-nums` is a CSS keyword (no token surface) that aligns digits across states. Reaching for the composite first keeps you on the system's typography path; overrides surface only the genuine deviations.
+- **Custom CSS, structural.** `display: grid` / `display: flex`, `position: relative` / `absolute`, `place-items: center`, `isolation: isolate` (creates a stacking context so the connector line's `z-index: -1` doesn't escape), edge-aware `:first-child` / `:last-child` rules for row alignment, `border-radius` derived through `calc()`.
+- **Tokens for every design value.** Spacing (`--set-spacing-vertical-{400,800}`), colors (`--set-color-{foreground,background,border}-*`), border (`--set-layout-border-width-thick`), radius via `--set-radius-ratio-lg` composed against the component-scoped size, typography (`--set-typography-text-body-xs` composite, `--set-typography-font-weight-{bold,medium}` overrides), motion (`--set-motion-duration-200`, `--set-motion-easing-ease-{in-out,out}`).
+- **Component-scoped custom property.** `--app-stepper-size` is defined at the component-level selector and consumed by descendants in the same file. The same-file scope keeps it local to the component (the `set/set-known-tokens` lint rule accepts same-file definitions). Tokens still drive the value (`var(--set-spacing-vertical-800)`); the custom property just gives the component one knob to compose around.
+- **Animation through motion tokens.** `@keyframes app-stepper-check-in` defines the entrance transition; `animation: app-stepper-check-in var(--set-motion-duration-200) var(--set-motion-easing-ease-out)` runs it with the system's motion timing.
+- **CSS architecture.** Selector wrapped in `:where(.set)` so the root sits at `0,1,0` (matching system rules); top-level class is project-prefixed (`.app-stepper`); descendants are nested unprefixed.
+
+The `data-state` attribute is the seam between markup and styling. State semantics live on the element; state visuals are CSS rules keyed off the attribute. Adding a fourth state (e.g. `error`) is one CSS block referencing `--set-color-status-error-*` and one new value in the data.

package/src/custom-with-tokens/examples/react/stepper.md

@@ -0,0 +1,220 @@
+# Stepper (React)
+
+Multi-step process indicator (onboarding, checkout, multi-page form). A row of numbered steps with `done`, `current`, and `upcoming` visual states, connected by a baseline. Set doesn't ship one, so it's a clear gap to fill.
+
+The example exercises the layered model end-to-end: a leaf component for the done-state checkmark, custom markup for the structural pattern, tokens for every design value (with one component-scoped custom property composed from tokens), and `@keyframes` driving state transitions through motion tokens.
+
+```tsx
+import { Icon, Root } from "@monospaced/set-react";
+
+type Step = { label: string; number: number };
+type StepState = "current" | "done" | "upcoming";
+
+const steps: Step[] = [
+  { number: 1, label: "Plan" },
+  { number: 2, label: "Build" },
+  { number: 3, label: "Ship" },
+];
+
+function getStepState(index: number, currentStep: number): StepState {
+  if (currentStep >= steps.length) return "done";
+  if (index < currentStep) return "done";
+  if (index === currentStep) return "current";
+  return "upcoming";
+}
+
+function Stepper({ currentStep }: { currentStep: number }) {
+  return (
+    <ol className="app-stepper">
+      {steps.map(({ number, label }, index) => {
+        const state = getStepState(index, currentStep);
+
+        return (
+          <li
+            key={number}
+            className="step"
+            data-state={state}
+            {...(state === "current" ? { "aria-current": "step" } : {})}
+          >
+            <span className="bubble" aria-hidden="true">
+              <span className="bubble-number">{number}</span>
+              <span className="bubble-icon">
+                <Icon name="check" size="xs" />
+              </span>
+            </span>
+            <span className="label">
+              {label}
+              {state === "done" ? (
+                <span className="visually-hidden">, completed</span>
+              ) : null}
+              {state === "current" ? (
+                <span className="visually-hidden">, current step</span>
+              ) : null}
+            </span>
+          </li>
+        );
+      })}
+    </ol>
+  );
+}
+
+// Render inside a Set Root — the `.set` ancestor scopes both system
+// CSS and your `:where(.set) .app-stepper` selector.
+function App() {
+  return (
+    <Root appRoot>
+      <Stepper currentStep={1} />
+    </Root>
+  );
+}
+```
+
+```css
+@keyframes app-stepper-check-in {
+  from {
+    opacity: 0;
+    scale: 0.7;
+  }
+
+  to {
+    opacity: 1;
+    scale: 1;
+  }
+}
+
+:where(.set) .app-stepper {
+  --app-stepper-size: var(--set-spacing-vertical-800);
+
+  display: flex;
+  list-style: none;
+  margin: 0;
+  padding-inline: 0;
+
+  .bubble {
+    background-color: var(--set-color-background-subtle);
+    block-size: var(--app-stepper-size);
+    border-radius: calc(var(--app-stepper-size) * var(--set-radius-ratio-lg));
+    color: var(--set-color-foreground-muted-text);
+    display: grid;
+    font: var(--set-typography-text-body-xs);
+    font-variant-numeric: tabular-nums;
+    font-weight: var(--set-typography-font-weight-bold);
+    inline-size: var(--app-stepper-size);
+    place-items: center;
+    position: relative;
+    transition:
+      background-color var(--set-motion-duration-200)
+        var(--set-motion-easing-ease-in-out),
+      color var(--set-motion-duration-200) var(--set-motion-easing-ease-in-out);
+  }
+
+  .bubble-icon,
+  .bubble-number {
+    grid-area: 1 / 1;
+  }
+
+  .bubble-icon {
+    opacity: 0;
+    scale: 0.7;
+  }
+
+  .label {
+    color: var(--set-color-foreground-muted-text);
+    font: var(--set-typography-text-body-xs);
+    font-weight: var(--set-typography-font-weight-medium);
+  }
+
+  .step {
+    display: grid;
+    flex: 1;
+    gap: var(--set-spacing-vertical-400);
+    isolation: isolate;
+    justify-items: center;
+    position: relative;
+    text-align: center;
+
+    &::after {
+      background-color: var(--set-color-border-subtle);
+      block-size: var(--set-layout-border-width-thick);
+      content: "";
+      inline-size: 100%;
+      inset-block-start: calc(
+        (var(--app-stepper-size) / 2) -
+          (var(--set-layout-border-width-thick) / 2)
+      );
+      inset-inline-start: 50%;
+      position: absolute;
+      z-index: -1;
+    }
+
+    &:first-child {
+      justify-items: start;
+    }
+
+    &:first-child::after {
+      inline-size: calc(150% - (var(--app-stepper-size) / 2));
+      inset-inline-start: calc(var(--app-stepper-size) / 2);
+    }
+
+    &:first-child .label {
+      translate: calc((var(--app-stepper-size) - 100%) / 2) 0;
+    }
+
+    &:nth-last-child(2)::after {
+      inline-size: calc(150% - (var(--app-stepper-size) / 2));
+    }
+
+    &:last-child {
+      justify-items: end;
+    }
+
+    &:last-child::after {
+      display: none;
+    }
+
+    &:last-child .label {
+      translate: calc((100% - var(--app-stepper-size)) / 2) 0;
+    }
+
+    &[data-state="done"]::after {
+      background-color: var(--set-color-foreground-default);
+    }
+  }
+
+  .step[data-state="current"] .bubble,
+  .step[data-state="done"] .bubble {
+    background-color: var(--set-color-foreground-default);
+    color: var(--set-color-foreground-contrast);
+  }
+
+  .step[data-state="done"] .bubble-icon {
+    animation: app-stepper-check-in var(--set-motion-duration-200)
+      var(--set-motion-easing-ease-out);
+    opacity: 1;
+    scale: 1;
+  }
+
+  .step[data-state="done"] .bubble-number {
+    opacity: 0;
+  }
+
+  .step[data-state="current"] .label,
+  .step[data-state="done"] .label {
+    color: var(--set-color-foreground-default);
+  }
+}
+```
+
+What sits where:
+
+- **Leaf component for the content node.** `Icon` for the done-state checkmark — Set handles its sizing, color inheritance, and a11y. The number and the icon both render unconditionally; CSS reveals the right one for the state via `opacity` + `@keyframes`.
+- **Custom markup expresses the structural pattern.** The `ol` / `li` / `span` skeleton captures "row of state-driven circles connected by a baseline." `aria-current="step"` carries the active-step semantics for screen readers; the bubble is `aria-hidden` because state is conveyed by both `aria-current` and the `.visually-hidden` text appended to the label (`, completed` / `, current step`). `.visually-hidden` is a Set utility class shipped from Root — no need to redefine.
+- **Why not `Text` for numbers and labels?** Text's prop surface doesn't expose `font-weight` or `font-variant-numeric`, and the design needs specific weights (bold for numbers, medium for labels) and tabular figures for the bubble's number to align across states. This is exactly the second branch the skill names in "When this applies" — _the case wants a visual treatment outside any existing component's prop surface_. Drop to a plain `<span>` and reach for typography composites + targeted overrides instead.
+- **Composite typography token + targeted overrides.** `font: var(--set-typography-text-body-xs)` carries the system's full body-xs spec (size, family, line-height) in one declaration. Specific properties then override only the deviations: `font-weight` switches per role (`bold` / `medium`); `font-variant-numeric: tabular-nums` is a CSS keyword (no token surface) that aligns digits across states. Reaching for the composite first keeps you on the system's typography path; overrides surface only the genuine deviations.
+- **Custom CSS, structural.** `display: grid` / `display: flex`, `position: relative` / `absolute`, `place-items: center`, `isolation: isolate` (creates a stacking context so the connector line's `z-index: -1` doesn't escape), edge-aware `:first-child` / `:last-child` rules for row alignment, `border-radius` derived through `calc()`.
+- **Tokens for every design value.** Spacing (`--set-spacing-vertical-{400,800}`), colors (`--set-color-{foreground,background,border}-*`), border (`--set-layout-border-width-thick`), radius via `--set-radius-ratio-lg` composed against the component-scoped size, typography (`--set-typography-text-body-xs` composite, `--set-typography-font-weight-{bold,medium}` overrides), motion (`--set-motion-duration-200`, `--set-motion-easing-ease-{in-out,out}`).
+- **Component-scoped custom property.** `--app-stepper-size` is defined at the component-level selector and consumed by descendants in the same file. The same-file scope keeps it local to the component (the `set/set-known-tokens` lint rule accepts same-file definitions). Tokens still drive the value (`var(--set-spacing-vertical-800)`); the custom property just gives the component one knob to compose around.
+- **Animation through motion tokens.** `@keyframes app-stepper-check-in` defines the entrance transition; `animation: app-stepper-check-in var(--set-motion-duration-200) var(--set-motion-easing-ease-out)` runs it with the system's motion timing.
+- **CSS architecture.** Selector wrapped in `:where(.set)` so the root sits at `0,1,0` (matching system rules); top-level class is project-prefixed (`.app-stepper`); descendants are nested unprefixed.
+
+The `data-state` attribute is the seam between markup and styling. State semantics live on the element; state visuals are CSS rules keyed off the attribute. Adding a fourth state (e.g. `error`) is one CSS block referencing `--set-color-status-error-*` and one new value in the data.