From 95c393edd4bcba53ba94da526cf5bbad274af477 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 24 Jul 2026 07:25:45 +0000
Subject: [PATCH 1/3] docs: add agent-facing build system (getting-started,
 cookbook, slashed-build skill)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Close the "single entry point for AI agents" gaps found auditing the LLM
docs: the token layer was complete, but an agent reading only llm-guide.md
had no install/getting-started path, no cross-links to the class-based API,
and no task-oriented recipes.

- docs/getting-started.md: install, bundle choice, boilerplate, dark mode,
  6-token rebrand, token-first rule. Multipliers framed as an advanced,
  opt-in escape hatch — not the default workflow.
- docs/cookbook.md: copy-paste task recipes (page shell, stack, card grid,
  hero, sidebar, prose, surface, buttons, states, rebrand + dark toggle).
- .claude/skills/slashed-build/SKILL.md: thin router/"brain" — mental model,
  build workflow, decision tree, and routing into the CI-gated docs. No
  duplicated token/class inventories (anti-drift).
- llm-guide.md + README: cross-link the new docs and the class-based API.
- check-doc-refs.js: scan the skill dir too, so SKILL.md's --sf-*/.sf-*
  references are drift-guarded like every other doc.

check:doc-refs and check:llm-guide both pass (17 docs scanned).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Fad4UDMPgW3dBurUpkJE9d
---
 .claude/skills/slashed-build/SKILL.md | 112 ++++++++++++
 README.md                             |   6 +
 docs/cookbook.md                      | 242 ++++++++++++++++++++++++++
 docs/getting-started.md               | 170 ++++++++++++++++++
 docs/llm-guide.md                     |   8 +
 scripts/check-doc-refs.js             |   2 +-
 6 files changed, 539 insertions(+), 1 deletion(-)
 create mode 100644 .claude/skills/slashed-build/SKILL.md
 create mode 100644 docs/cookbook.md
 create mode 100644 docs/getting-started.md

diff --git a/.claude/skills/slashed-build/SKILL.md b/.claude/skills/slashed-build/SKILL.md
new file mode 100644
index 00000000..a96c3c8a
--- /dev/null
+++ b/.claude/skills/slashed-build/SKILL.md
@@ -0,0 +1,112 @@
+---
+name: slashed-build
+description: >-
+  Use when building or styling a UI, website, page, or component with the
+  SLASHED CSS framework (the `--sf-*` token API and `.sf-*` classes) — writing
+  the HTML/CSS, choosing tokens over hardcoded values, laying out with
+  primitives, rebranding, or wiring dark mode. Routes to the framework's
+  authoritative, CI-gated docs; does not duplicate token or class lists.
+---
+
+# Building with SLASHED
+
+SLASHED is a token-first, BEM-first CSS framework: the `--sf-*` design-token API
+is the product, and you compose components on top of it. This skill is the
+entry point — it teaches the mental model and the build workflow, then routes
+you to the authoritative reference docs for the exhaustive lists. **Do not
+memorise or reproduce token/class inventories from here; look them up in the
+linked docs, which CI keeps in sync with the source.**
+
+## When to use
+
+Use this whenever the task involves writing or styling markup that should look
+like SLASHED: new pages, components, layouts, rebrands, theming, or dark mode.
+If the user's project loads a `slashed*.css` bundle or uses `--sf-*` / `.sf-*`
+names, you are in scope.
+
+## The five principles (in priority order)
+
+1. **Never hardcode a visual value.** Every colour, space, radius, shadow,
+   font, z-index, and duration is a token. `padding: 24px` is a bug; write
+   `padding: var(--sf-space-m)`. Hardcoded numbers break consistency and dark
+   mode.
+2. **BEM-first, classes where they count.** Base elements are styled classless.
+   Use `.sf-*` classes for layout primitives, macros, and states; build your
+   own BEM components on the token API for everything else.
+3. **Prefer semantic tokens over primitive ones.** Reach for `var(--sf-gap)`
+   over `var(--sf-space-m)` in a grid — the semantic token lets one change
+   ripple everywhere without touching components.
+4. **Dark mode is free — don't fight it.** Never write dark-mode colour CSS or
+   toggle CSS variables in JS. Set `data-theme` and let the framework recompute
+   the palette from the source tokens.
+5. **Tweak by knob or `calc()`, never a new token.** For a one-off variation,
+   override an existing knob (`--sf-grid-gap: var(--sf-space-s)`) or compose
+   with `calc()`. Inventing `--my-*` tokens fragments the system and skips
+   dark-mode derivation.
+
+> **Advanced escape hatch (not the default workflow):** because everything
+> flows from tokens, global multipliers such as `--sf-radius-scale: 0` or
+> `--sf-motion-scale: 0` can restyle an entire site in one line. Treat these as
+> a deliberate power-user switch, hidden by default — do not introduce them
+> into ordinary component work.
+
+## Build workflow
+
+1. **Load the framework.** Confirm a bundle is present (or add one). Optimal is
+   the default; the full bundle adds `.sf-btn` / `.sf-card` + utilities. See
+   [getting-started.md](../../../docs/getting-started.md).
+2. **Lay out with primitives, not custom CSS.** Reach for `.sf-container`,
+   `.sf-stack`, `.sf-grid`, `.sf-cluster`, `.sf-sidebar`, `.sf-cover`, and
+   friends before writing flexbox/grid by hand. → [layout.md](../../../docs/layout.md)
+3. **Style with macros + tokens.** Panels → `.sf-surface`; articles →
+   `.sf-prose`; spacing/typography → tokens. → [macros.md](../../../docs/macros.md)
+4. **Wire state through `.sf-is-*` classes + ARIA**, toggled from JS — not
+   inline styles. → [states.md](../../../docs/states.md)
+5. **Brand via the six source colours** in the overrides space; add
+   `data-theme` for forced modes. → [theming.md](../../../docs/theming.md)
+6. **Verify token-first.** Before finishing, scan your CSS for hardcoded
+   colours/px/rem and replace them with tokens.
+
+## Decision tree — "I want to…"
+
+| Goal | Reach for | Reference |
+| --- | --- | --- |
+| Constrain / centre page content | `.sf-container` (+ `--narrow`/`--wide`/`--prose`) | [layout.md](../../../docs/layout.md) |
+| Space stacked children | `.sf-stack` | [layout.md](../../../docs/layout.md) |
+| Responsive card grid (no media queries) | `.sf-grid .sf-grid--fit` + `--sf-grid-min` | [layout.md](../../../docs/layout.md) |
+| Row that wraps (buttons, tags) | `.sf-cluster` | [layout.md](../../../docs/layout.md) |
+| Content + collapsing sidebar | `.sf-sidebar` | [layout.md](../../../docs/layout.md) |
+| A padded, elevated panel | `.sf-surface` (any bundle) / `.sf-card` (full) | [macros.md](../../../docs/macros.md) |
+| Rich article typography | `.sf-prose` | [macros.md](../../../docs/macros.md) |
+| Buttons | `.sf-btn` + variant (full bundle) | [classes.md](../../../docs/classes.md) |
+| Loading / selected / disabled state | `.sf-is-*` + matching ARIA | [states.md](../../../docs/states.md) |
+| A specific spacing / colour / radius value | a `--sf-*` token | [llm-guide.md](../../../docs/llm-guide.md) · [tokens.md](../../../docs/tokens.md) |
+| Rebrand the whole site | six `--sf-color-*-source-light` tokens | [theming.md](../../../docs/theming.md) |
+| Dark mode | `data-theme="dark"` on `<html>` or a section | [theming.md](../../../docs/theming.md) |
+| Look a name up programmatically | `api-index.json` / `token-index.json` | [docs/](../../../docs/) |
+
+## Reference map (authoritative, CI-gated)
+
+- **[getting-started.md](../../../docs/getting-started.md)** — install, bundle
+  choice, boilerplate, first rebrand.
+- **[cookbook.md](../../../docs/cookbook.md)** — copy-paste recipes for common
+  builds (page shell, card grid, hero, sidebar, form states, rebrand).
+- **[llm-guide.md](../../../docs/llm-guide.md)** — the deep token reference:
+  colour/type/space/layout/motion systems, tiers, best practices.
+- **[layout.md](../../../docs/layout.md)** / **[macros.md](../../../docs/macros.md)**
+  / **[states.md](../../../docs/states.md)** — every layout primitive, macro,
+  and state class.
+- **[theming.md](../../../docs/theming.md)** — rebrand, dark mode, multi-brand,
+  contrast.
+- **[classes.md](../../../docs/classes.md)** / **[tokens.md](../../../docs/tokens.md)**
+  — the complete generated inventories.
+- **`api-index.json`** / **`token-index.json`** — machine-readable indexes for
+  programmatic lookup.
+
+## Guardrails
+
+- Only reference `--sf-*` tokens and `.sf-*` classes that actually exist — check
+  the reference docs or the JSON indexes rather than guessing a name.
+- Do not edit `INTERNAL` tokens (e.g. `--sf-is-dark`); they are framework-managed.
+- Put your overrides in plain `:root` / your own selectors — the
+  `slashed.overrides` layer sits last, so you never need `!important`.
diff --git a/README.md b/README.md
index 2876ca4d..c10f27b4 100644
--- a/README.md
+++ b/README.md
@@ -156,6 +156,8 @@ Pre-built bundles ship with every [release](https://github.com/codeslash-dev/SLA
 
 | Guide | What's inside |
 | --- | --- |
+| [Getting started](docs/getting-started.md) | install, bundle choice, boilerplate, first rebrand — start here |
+| [Cookbook](docs/cookbook.md) | copy-paste recipes for common builds (page shell, card grid, hero, sidebar, states) |
 | [Architecture](docs/architecture.md) | layers, file structure, class taxonomy, bundles, token contract, performance |
 | [Theming](docs/theming.md) | rebrand in 6 tokens, dark mode, multi-brand, contrast |
 | [Layout primitives](docs/layout.md) | every `.sf-*` layout class + tokens |
@@ -168,6 +170,10 @@ Pre-built bundles ship with every [release](https://github.com/codeslash-dev/SLA
 | [LLM guide](docs/llm-guide.md) | compact API reference for AI-assisted development |
 | [Migration](docs/migration.md) | upgrading SLASHED + migrating from other frameworks |
 
+Building with an AI assistant? The **`slashed-build` skill**
+(`.claude/skills/slashed-build/`) turns this documentation set into a guided
+build workflow — mental model, decision tree, and routing into the docs above.
+
 ## Editor integration
 
 A generated [VS Code CSS Custom Data](https://github.com/microsoft/vscode-css-languageservice/blob/main/docs/customData.md)
diff --git a/docs/cookbook.md b/docs/cookbook.md
new file mode 100644
index 00000000..b938b5fa
--- /dev/null
+++ b/docs/cookbook.md
@@ -0,0 +1,242 @@
+# SLASHED Cookbook
+
+Task-oriented recipes: *"I want to build X"* → the markup and the tokens that
+get you there. Every recipe is copy-paste ready and works in light and dark
+mode with no extra CSS. For the reasoning behind each choice, follow the links
+into the [LLM guide](llm-guide.md).
+
+These recipes lean on the **optimal** bundle. Recipes that use `.sf-btn` or
+`.sf-card` note that they need the **full** bundle.
+
+- [Page shell](#page-shell)
+- [Vertical rhythm (stack)](#vertical-rhythm-stack)
+- [Card grid](#card-grid)
+- [Hero / landing section](#hero--landing-section)
+- [Sidebar layout](#sidebar-layout)
+- [Long-form article (prose)](#long-form-article-prose)
+- [A surface / panel](#a-surface--panel)
+- [Buttons and actions](#buttons-and-actions)
+- [Interactive states](#interactive-states)
+- [Rebrand + dark-mode toggle](#rebrand--dark-mode-toggle)
+- [Local tweaks without new tokens](#local-tweaks-without-new-tokens)
+
+---
+
+## Page shell
+
+Centre and constrain content with `.sf-container`; it caps line length and adds
+responsive side padding.
+
+```html
+<header class="sf-container"> … </header>
+<main class="sf-container"> … </main>
+<footer class="sf-container"> … </footer>
+```
+
+Width variants: `.sf-container--narrow`, `.sf-container--wide`,
+`.sf-container--full`, `.sf-container--prose` (ideal reading measure).
+
+---
+
+## Vertical rhythm (stack)
+
+`.sf-stack` puts consistent space **between** children — never margins on the
+children themselves.
+
+```html
+<div class="sf-stack">
+  <h2>Section title</h2>
+  <p>First paragraph.</p>
+  <p>Second paragraph.</p>
+</div>
+```
+
+Tune the gap per-instance with a size modifier (`.sf-stack--s` …
+`.sf-stack--2xl`) or globally with the `--sf-stack-gap` knob. See
+[layout.md](layout.md).
+
+---
+
+## Card grid
+
+A responsive grid that fits as many columns as will fit — no media queries.
+
+```html
+<ul class="sf-grid sf-grid--fit">
+  <li class="sf-card">Card one</li>
+  <li class="sf-card">Card two</li>
+  <li class="sf-card">Card three</li>
+</ul>
+```
+
+- `.sf-grid--fit` auto-fits columns based on `--sf-grid-min` (the minimum
+  column width). Set `--sf-grid-min` to change the breakpoint density.
+- `.sf-card` needs the **full** bundle. On the optimal bundle, use
+  `.sf-surface` for the same panel look.
+- Want a tighter grid? Set `--sf-grid-gap: var(--sf-space-s)` on the `<ul>`
+  instead of writing a new class.
+
+---
+
+## Hero / landing section
+
+`.sf-cover` vertically centres a headline block within a minimum-height region;
+`.sf-section` adds generous top/bottom padding.
+
+```html
+<section class="sf-section sf-cover">
+  <div class="sf-container sf-stack">
+    <h1>Ship your design system, not a build step.</h1>
+    <p class="sf-text-l">One stylesheet. Six tokens to rebrand. Dark mode free.</p>
+    <div class="sf-cluster">
+      <a class="sf-btn sf-btn--primary" href="#">Get started</a>
+      <a class="sf-btn sf-btn--outline" href="#">Read the docs</a>
+    </div>
+  </div>
+</section>
+```
+
+`.sf-cluster` lays out the buttons in a row that wraps gracefully on small
+screens. Section padding scales with `--sf-section-pad`.
+
+---
+
+## Sidebar layout
+
+A content area with a sidebar that collapses below a threshold — again, no
+breakpoints.
+
+```html
+<div class="sf-sidebar">
+  <aside> … navigation … </aside>
+  <main> … content … </main>
+</div>
+```
+
+`.sf-sidebar--right` flips the side; `.sf-sidebar--wide` /
+`.sf-sidebar--narrow` change the sidebar's target width, tuned by
+`--sf-sidebar-width`. The pair wraps to a single column automatically when the
+main content can no longer fit alongside — no breakpoints. See
+[layout.md](layout.md).
+
+---
+
+## Long-form article (prose)
+
+`.sf-prose` styles a block of raw HTML (headings, lists, blockquotes, code)
+into a readable article — the one place you *want* rich classless typography.
+
+```html
+<article class="sf-container--prose sf-prose">
+  <h1>Title</h1>
+  <p>Body copy with <a href="#">links</a>, <code>inline code</code>, lists…</p>
+  <blockquote>Pull quote.</blockquote>
+</article>
+```
+
+Wrap anything you must exclude from prose styling in `.sf-not-prose`.
+
+---
+
+## A surface / panel
+
+`.sf-surface` is the classless-friendly card look available in **every**
+bundle: padded, rounded, elevated, theme-aware.
+
+```html
+<div class="sf-surface sf-stack">
+  <h3>Panel title</h3>
+  <p>Content on a raised surface.</p>
+</div>
+```
+
+Semantic variants tint the surface: `.sf-surface--neutral`,
+`.sf-surface--secondary`, `.sf-surface--success`, `.sf-surface--danger`,
+`.sf-surface--info`, `.sf-surface--warning`, `.sf-surface--inverse`.
+
+---
+
+## Buttons and actions
+
+*(Requires the **full** bundle.)*
+
+```html
+<button class="sf-btn sf-btn--primary">Primary</button>
+<button class="sf-btn sf-btn--secondary">Secondary</button>
+<button class="sf-btn sf-btn--outline">Outline</button>
+<button class="sf-btn sf-btn--danger">Delete</button>
+```
+
+Sizes: `.sf-btn--xs` … `.sf-btn--xl`. Full-width: `.sf-btn--block`. Text
+colour on coloured buttons uses the `--sf-color-text--on-*` auto-contrast
+tokens, so it stays legible in both themes for free.
+
+---
+
+## Interactive states
+
+State classes map to ARIA and drive visuals — toggle them from your JS instead
+of editing inline styles.
+
+```html
+<button class="sf-btn sf-btn--primary sf-is-loading" aria-busy="true">Saving…</button>
+<li class="sf-card sf-is-selected" aria-selected="true">Chosen</li>
+<button class="sf-btn sf-is-disabled" aria-disabled="true">Unavailable</button>
+```
+
+The full catalogue and its ARIA mapping is in [states.md](states.md). Prefer a
+shimmer placeholder while loading? Use `.sf-is-shimmer`.
+
+---
+
+## Rebrand + dark-mode toggle
+
+```css
+/* your overrides — no !important needed */
+:root {
+  --sf-color-primary-source-light: #7048e8;
+  --sf-color-base-source-light:    #f8f9fa;
+}
+```
+
+```html
+<button id="theme" type="button">Toggle theme</button>
+<script>
+  const root = document.documentElement;
+  document.getElementById('theme').addEventListener('click', () => {
+    root.dataset.theme = root.dataset.theme === 'dark' ? 'light' : 'dark';
+  });
+</script>
+```
+
+Toggle the **attribute**, never the CSS variables — the framework recomputes the
+whole palette from `data-theme`. Add `class="sf-theme-transition"` on `<html>`
+for a smooth cross-fade.
+
+---
+
+## Local tweaks without new tokens
+
+When you need a one-off variation, compose with `calc()` or override an existing
+knob — do **not** invent a new token.
+
+```css
+/* ✓ a roomier hero — compose from the existing token */
+.hero { padding-block: calc(var(--sf-section-pad) * 1.5); }
+
+/* ✓ a tighter grid — set the knob, don't write .sf-grid--tight */
+.compact-grid { --sf-grid-gap: var(--sf-space-s); }
+```
+
+Why: new tokens fragment the system and skip dark-mode derivation. The full set
+of anti-patterns is in [Best Practices](llm-guide.md#14-best-practices).
+
+---
+
+## More building blocks
+
+This cookbook covers the common cases. The complete class inventory —
+`.sf-switcher`, `.sf-reel`, `.sf-frame`, `.sf-bento`, `.sf-center`,
+`.sf-imposter`, overflow-fade, scroll-snap, and the rest — is in
+[layout.md](layout.md), [macros.md](macros.md), and the generated
+[classes.md](classes.md).
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 00000000..b8c127f0
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,170 @@
+# Getting Started with SLASHED
+
+The fastest path from zero to a styled page — for humans and for LLM agents.
+This page answers the four questions the token reference does not: **how do I
+load it, which bundle do I pick, what is the minimal boilerplate, and what do I
+do first.** For the exhaustive API, follow the links in
+[Where to go next](#where-to-go-next).
+
+---
+
+## 1. Add one stylesheet
+
+SLASHED is one CSS file. No build step, no Node, no runtime dependency.
+
+### CDN (fastest)
+
+```html
+<link rel="stylesheet"
+  href="https://cdn.jsdelivr.net/gh/codeslash-dev/SLASHED@dist/slashed.optimal.min.css">
+```
+
+### npm
+
+```bash
+npm install slashed
+```
+
+```css
+/* in your own CSS */
+@import "slashed/optimal";   /* recommended bundle */
+/* or */
+@import "slashed";           /* the full bundle (adds .sf-btn / .sf-card + utilities) */
+```
+
+The package exposes the bundles as subpath imports: `slashed` and
+`slashed/full` resolve to the full bundle, `slashed/optimal` to the optimal
+one, and `slashed/flat` to a layer-flattened variant for tooling that cannot
+parse `@layer`.
+
+---
+
+## 2. Pick a bundle
+
+| Bundle | Load this when… | Adds over `optimal` |
+| --- | --- | --- |
+| `slashed.optimal.css` | **default choice** — you build your own components on the token API | — |
+| `slashed.full.css` | you want the shipped `.sf-btn` / `.sf-card` components and the curated utility helpers | component + utility layers |
+
+Both ship as readable, `.min` (with source map), and `.flat` (layer-flattened)
+variants on the [CDN](https://cdn.jsdelivr.net/gh/codeslash-dev/SLASHED@dist/).
+When in doubt, start with **optimal** — you can switch to full later by changing
+one URL.
+
+> À la carte loading of individual `core/` and `optional/` files is possible
+> but rarely needed — see the README's *À la carte* section. If you go that
+> route, `core/layers.css` must load **first**.
+
+---
+
+## 3. Minimal boilerplate
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet"
+    href="https://cdn.jsdelivr.net/gh/codeslash-dev/SLASHED@dist/slashed.optimal.min.css">
+  <title>My SLASHED page</title>
+</head>
+<body>
+  <main class="sf-container">
+    <div class="sf-stack">
+      <h1>Hello, SLASHED</h1>
+      <p>Base elements are styled with no classes. Layout uses primitives.</p>
+    </div>
+  </main>
+</body>
+</html>
+```
+
+That is a complete, responsive, dark-mode-ready page. `.sf-container` centres
+and constrains the content; `.sf-stack` spaces its children with a consistent
+rhythm. Everything else — headings, paragraphs, links — is styled **classless**
+from `core/base.css`.
+
+---
+
+## 4. Dark mode is already on
+
+No script, no flash of the wrong theme. The page follows the OS preference out
+of the box. To force a mode, set one attribute:
+
+```html
+<html data-theme="dark">      <!-- force dark for the whole page -->
+<section data-theme="dark">   <!-- a dark section inside a light page -->
+```
+
+You do **not** write any dark-mode CSS. Every colour derives automatically from
+the source tokens via `light-dark()` and relative colour syntax.
+
+---
+
+## 5. Make it yours — rebrand in six tokens
+
+Override six source colours in the reserved `slashed.overrides` space (plain
+`:root` works — the overrides layer sits last, so no `!important` needed):
+
+```css
+:root {
+  --sf-color-primary-source-light:   #3b5bdb;
+  --sf-color-secondary-source-light: #5c677d;
+  --sf-color-tertiary-source-light:  #0c8599;
+  --sf-color-action-source-light:    #0ca678;
+  --sf-color-neutral-source-light:   #495057;
+  --sf-color-base-source-light:      #f8f9fa;
+}
+```
+
+Every hover state, tint, shade, tonal step, the four status colours, and the
+whole dark palette derive from those six. Prefer to design visually? Open the
+[configurator](https://slashed.codeslash.dev/configurator/) and export the
+override CSS.
+
+---
+
+## 6. The one rule that matters
+
+**Never hardcode a visual value.** Reach for a token instead:
+
+```css
+/* ✗ hardcoded — breaks consistency and dark mode */
+.promo { padding: 24px; border-radius: 8px; box-shadow: 0 2px 8px #0002; }
+
+/* ✓ token-first — one knob changes it everywhere */
+.promo {
+  padding: var(--sf-space-m);
+  border-radius: var(--sf-radius-m);
+  box-shadow: var(--sf-shadow-m);
+}
+```
+
+This single habit keeps your design consistent and makes dark mode automatic.
+The full rationale and the rest of the principles live in the
+[LLM guide](llm-guide.md#14-best-practices).
+
+> **Advanced, opt-in:** because every value flows from tokens, global
+> multipliers like `--sf-radius-scale: 0` (sharp corners everywhere) or
+> `--sf-motion-scale: 0` (drop animation) can restyle a whole site in one line.
+> These are a power-user escape hatch, **not** part of the everyday workflow —
+> reach for them only when you deliberately want a system-wide switch.
+
+---
+
+## Where to go next
+
+| You want to… | Read |
+| --- | --- |
+| Build real pages step by step (recipes) | [Cookbook](cookbook.md) |
+| Understand the token system deeply | [LLM guide](llm-guide.md) |
+| Lay out a page (grid, stack, sidebar, cover…) | [Layout primitives](layout.md) |
+| Use recipe classes (prose, surface, flow…) | [Macros](macros.md) |
+| Wire up interactive states (loading, selected…) | [State classes](states.md) |
+| Rebrand, theme, or go multi-brand | [Theming](theming.md) |
+| Look up any token or class programmatically | [`api-index.json`](api-index.json) · [`token-index.json`](token-index.json) |
+
+Building with an AI assistant? Point it at the **`slashed-build` skill**
+(`.claude/skills/slashed-build/`), which turns this documentation set into a
+guided build workflow.
diff --git a/docs/llm-guide.md b/docs/llm-guide.md
index 551f6459..26796c79 100644
--- a/docs/llm-guide.md
+++ b/docs/llm-guide.md
@@ -2,6 +2,14 @@
 
 > Version: **0.7.27** · Tokens: **741** · Prefix: `--sf-`
 
+> **New to SLASHED?** Start with [getting-started.md](getting-started.md)
+> (install, bundles, boilerplate) and the [cookbook.md](cookbook.md)
+> (copy-paste build recipes). This guide is the deep **token** reference; the
+> **class-based** API lives in [layout.md](layout.md), [macros.md](macros.md),
+> [states.md](states.md), and the generated [classes.md](classes.md). Building
+> with an AI assistant? See the `slashed-build` skill in
+> `.claude/skills/slashed-build/`.
+
 ---
 
 ## Table of Contents
diff --git a/scripts/check-doc-refs.js b/scripts/check-doc-refs.js
index b55feb3b..f518c34f 100644
--- a/scripts/check-doc-refs.js
+++ b/scripts/check-doc-refs.js
@@ -59,7 +59,7 @@ const EXCLUDED_DOCS = new Map([
 
 function discoverDocs() {
   const docs = [];
-  for (const dir of ['docs', 'user-manual']) {
+  for (const dir of ['docs', 'user-manual', '.claude/skills/slashed-build']) {
     const abs = path.join(ROOT, dir);
     if (!fs.existsSync(abs)) continue;
     for (const f of fs.readdirSync(abs).filter((f) => f.endsWith('.md'))) {

From a8b17f0eb6b375a9a60a5847359cd7f2e56648ee Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 24 Jul 2026 07:47:03 +0000
Subject: [PATCH 2/3] docs: make slashed-build skill portable via GitHub doc
 links
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rewrite the skill's doc references from repo-relative paths
(../../../docs/*.md) to GitHub blob/tree URLs so the skill keeps its routing
when copied into a consumer project — the npm package ships only
docs/api-index.json, not the .md docs, so relative links would dangle. A note
in the reference map points in-repo users at the local docs/ copies.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Fad4UDMPgW3dBurUpkJE9d
---
 .claude/skills/slashed-build/SKILL.md | 53 ++++++++++++++-------------
 1 file changed, 28 insertions(+), 25 deletions(-)

diff --git a/.claude/skills/slashed-build/SKILL.md b/.claude/skills/slashed-build/SKILL.md
index a96c3c8a..4fed096a 100644
--- a/.claude/skills/slashed-build/SKILL.md
+++ b/.claude/skills/slashed-build/SKILL.md
@@ -54,16 +54,16 @@ names, you are in scope.
 
 1. **Load the framework.** Confirm a bundle is present (or add one). Optimal is
    the default; the full bundle adds `.sf-btn` / `.sf-card` + utilities. See
-   [getting-started.md](../../../docs/getting-started.md).
+   [getting-started.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/getting-started.md).
 2. **Lay out with primitives, not custom CSS.** Reach for `.sf-container`,
    `.sf-stack`, `.sf-grid`, `.sf-cluster`, `.sf-sidebar`, `.sf-cover`, and
-   friends before writing flexbox/grid by hand. → [layout.md](../../../docs/layout.md)
+   friends before writing flexbox/grid by hand. → [layout.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/layout.md)
 3. **Style with macros + tokens.** Panels → `.sf-surface`; articles →
-   `.sf-prose`; spacing/typography → tokens. → [macros.md](../../../docs/macros.md)
+   `.sf-prose`; spacing/typography → tokens. → [macros.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/macros.md)
 4. **Wire state through `.sf-is-*` classes + ARIA**, toggled from JS — not
-   inline styles. → [states.md](../../../docs/states.md)
+   inline styles. → [states.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/states.md)
 5. **Brand via the six source colours** in the overrides space; add
-   `data-theme` for forced modes. → [theming.md](../../../docs/theming.md)
+   `data-theme` for forced modes. → [theming.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/theming.md)
 6. **Verify token-first.** Before finishing, scan your CSS for hardcoded
    colours/px/rem and replace them with tokens.
 
@@ -71,34 +71,37 @@ names, you are in scope.
 
 | Goal | Reach for | Reference |
 | --- | --- | --- |
-| Constrain / centre page content | `.sf-container` (+ `--narrow`/`--wide`/`--prose`) | [layout.md](../../../docs/layout.md) |
-| Space stacked children | `.sf-stack` | [layout.md](../../../docs/layout.md) |
-| Responsive card grid (no media queries) | `.sf-grid .sf-grid--fit` + `--sf-grid-min` | [layout.md](../../../docs/layout.md) |
-| Row that wraps (buttons, tags) | `.sf-cluster` | [layout.md](../../../docs/layout.md) |
-| Content + collapsing sidebar | `.sf-sidebar` | [layout.md](../../../docs/layout.md) |
-| A padded, elevated panel | `.sf-surface` (any bundle) / `.sf-card` (full) | [macros.md](../../../docs/macros.md) |
-| Rich article typography | `.sf-prose` | [macros.md](../../../docs/macros.md) |
-| Buttons | `.sf-btn` + variant (full bundle) | [classes.md](../../../docs/classes.md) |
-| Loading / selected / disabled state | `.sf-is-*` + matching ARIA | [states.md](../../../docs/states.md) |
-| A specific spacing / colour / radius value | a `--sf-*` token | [llm-guide.md](../../../docs/llm-guide.md) · [tokens.md](../../../docs/tokens.md) |
-| Rebrand the whole site | six `--sf-color-*-source-light` tokens | [theming.md](../../../docs/theming.md) |
-| Dark mode | `data-theme="dark"` on `<html>` or a section | [theming.md](../../../docs/theming.md) |
-| Look a name up programmatically | `api-index.json` / `token-index.json` | [docs/](../../../docs/) |
+| Constrain / centre page content | `.sf-container` (+ `--narrow`/`--wide`/`--prose`) | [layout.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/layout.md) |
+| Space stacked children | `.sf-stack` | [layout.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/layout.md) |
+| Responsive card grid (no media queries) | `.sf-grid .sf-grid--fit` + `--sf-grid-min` | [layout.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/layout.md) |
+| Row that wraps (buttons, tags) | `.sf-cluster` | [layout.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/layout.md) |
+| Content + collapsing sidebar | `.sf-sidebar` | [layout.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/layout.md) |
+| A padded, elevated panel | `.sf-surface` (any bundle) / `.sf-card` (full) | [macros.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/macros.md) |
+| Rich article typography | `.sf-prose` | [macros.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/macros.md) |
+| Buttons | `.sf-btn` + variant (full bundle) | [classes.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/classes.md) |
+| Loading / selected / disabled state | `.sf-is-*` + matching ARIA | [states.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/states.md) |
+| A specific spacing / colour / radius value | a `--sf-*` token | [llm-guide.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/llm-guide.md) · [tokens.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/tokens.md) |
+| Rebrand the whole site | six `--sf-color-*-source-light` tokens | [theming.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/theming.md) |
+| Dark mode | `data-theme="dark"` on `<html>` or a section | [theming.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/theming.md) |
+| Look a name up programmatically | `api-index.json` / `token-index.json` | [docs/](https://github.com/codeslash-dev/SLASHED/tree/main/docs) |
 
 ## Reference map (authoritative, CI-gated)
 
-- **[getting-started.md](../../../docs/getting-started.md)** — install, bundle
+Links point at GitHub so this skill works when copied into any project. Inside
+the SLASHED repo itself, the same files live under `docs/` — read them locally.
+
+- **[getting-started.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/getting-started.md)** — install, bundle
   choice, boilerplate, first rebrand.
-- **[cookbook.md](../../../docs/cookbook.md)** — copy-paste recipes for common
+- **[cookbook.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/cookbook.md)** — copy-paste recipes for common
   builds (page shell, card grid, hero, sidebar, form states, rebrand).
-- **[llm-guide.md](../../../docs/llm-guide.md)** — the deep token reference:
+- **[llm-guide.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/llm-guide.md)** — the deep token reference:
   colour/type/space/layout/motion systems, tiers, best practices.
-- **[layout.md](../../../docs/layout.md)** / **[macros.md](../../../docs/macros.md)**
-  / **[states.md](../../../docs/states.md)** — every layout primitive, macro,
+- **[layout.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/layout.md)** / **[macros.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/macros.md)**
+  / **[states.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/states.md)** — every layout primitive, macro,
   and state class.
-- **[theming.md](../../../docs/theming.md)** — rebrand, dark mode, multi-brand,
+- **[theming.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/theming.md)** — rebrand, dark mode, multi-brand,
   contrast.
-- **[classes.md](../../../docs/classes.md)** / **[tokens.md](../../../docs/tokens.md)**
+- **[classes.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/classes.md)** / **[tokens.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/tokens.md)**
   — the complete generated inventories.
 - **`api-index.json`** / **`token-index.json`** — machine-readable indexes for
   programmatic lookup.

From ebfb492cd96dfeaa8c5de9764a2b2bc29e79a7a3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 24 Jul 2026 12:12:58 +0000
Subject: [PATCH 3/3] docs: address review feedback on cookbook,
 getting-started, and skill
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Four minor doc-quality fixes from PR review:

- cookbook.md: correct the interactive-states ARIA example — wrap the
  aria-selected item in a role="listbox"/role="option" pair (a bare <li>
  cannot carry aria-selected) and use native `disabled` on the button
  (aria-disabled only exposes state, does not block activation).
- cookbook.md: add the missing "requires the full bundle" note to the hero
  and interactive-states recipes, which use .sf-btn / .sf-card.
- getting-started.md: scope the "no Node / no build step" claim to the CDN
  path; the npm path uses a package manager + bundler.
- SKILL.md: spell out the container modifier classes
  (.sf-container--narrow/--wide/--prose) instead of abbreviating them, so an
  assistant doesn't emit bare `--narrow` selectors.

check:doc-refs passes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Fad4UDMPgW3dBurUpkJE9d
---
 .claude/skills/slashed-build/SKILL.md |  2 +-
 docs/cookbook.md                      | 19 ++++++++++++++++---
 docs/getting-started.md               |  4 +++-
 3 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/.claude/skills/slashed-build/SKILL.md b/.claude/skills/slashed-build/SKILL.md
index 4fed096a..a0fa668f 100644
--- a/.claude/skills/slashed-build/SKILL.md
+++ b/.claude/skills/slashed-build/SKILL.md
@@ -71,7 +71,7 @@ names, you are in scope.
 
 | Goal | Reach for | Reference |
 | --- | --- | --- |
-| Constrain / centre page content | `.sf-container` (+ `--narrow`/`--wide`/`--prose`) | [layout.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/layout.md) |
+| Constrain / centre page content | `.sf-container`, `.sf-container--narrow`, `.sf-container--wide`, `.sf-container--prose` | [layout.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/layout.md) |
 | Space stacked children | `.sf-stack` | [layout.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/layout.md) |
 | Responsive card grid (no media queries) | `.sf-grid .sf-grid--fit` + `--sf-grid-min` | [layout.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/layout.md) |
 | Row that wraps (buttons, tags) | `.sf-cluster` | [layout.md](https://github.com/codeslash-dev/SLASHED/blob/main/docs/layout.md) |
diff --git a/docs/cookbook.md b/docs/cookbook.md
index b938b5fa..606b62f6 100644
--- a/docs/cookbook.md
+++ b/docs/cookbook.md
@@ -83,6 +83,9 @@ A responsive grid that fits as many columns as will fit — no media queries.
 `.sf-cover` vertically centres a headline block within a minimum-height region;
 `.sf-section` adds generous top/bottom padding.
 
+*(The `.sf-btn` buttons below need the **full** bundle; the layout itself works
+on optimal.)*
+
 ```html
 <section class="sf-section sf-cover">
   <div class="sf-container sf-stack">
@@ -176,12 +179,22 @@ tokens, so it stays legible in both themes for free.
 ## Interactive states
 
 State classes map to ARIA and drive visuals — toggle them from your JS instead
-of editing inline styles.
+of editing inline styles. *(The `.sf-btn` / `.sf-card` examples need the
+**full** bundle.)*
+
+Pair each state class with the matching semantics: `aria-selected` needs a
+`role="option"` inside a `role="listbox"` (a bare `<li>` does not support it),
+and a disabled `<button>` needs the native `disabled` attribute — `aria-disabled`
+only exposes the state, it does not block activation.
 
 ```html
 <button class="sf-btn sf-btn--primary sf-is-loading" aria-busy="true">Saving…</button>
-<li class="sf-card sf-is-selected" aria-selected="true">Chosen</li>
-<button class="sf-btn sf-is-disabled" aria-disabled="true">Unavailable</button>
+
+<ul role="listbox" aria-label="Choices">
+  <li role="option" class="sf-card sf-is-selected" aria-selected="true">Chosen</li>
+</ul>
+
+<button class="sf-btn sf-is-disabled" disabled>Unavailable</button>
 ```
 
 The full catalogue and its ARIA mapping is in [states.md](states.md). Prefer a
diff --git a/docs/getting-started.md b/docs/getting-started.md
index b8c127f0..2f8be674 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -10,7 +10,9 @@ do first.** For the exhaustive API, follow the links in
 
 ## 1. Add one stylesheet
 
-SLASHED is one CSS file. No build step, no Node, no runtime dependency.
+SLASHED ships as plain CSS with no runtime dependency and nothing to compile.
+Via the CDN it needs no Node or build step at all; the npm path below installs
+the same stylesheet through your package manager and resolves it with a bundler.
 
 ### CDN (fastest)