@tjakoen/grain 0.1.33 → 0.1.35

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -241,6 +241,30 @@ every theme, and verify it still reads in dark.
241
241
  passes its dir to `createRenderer` / the style bundle / `createCatalog`). It then appears
242
242
  in `/catalog` automatically.
243
243
 
244
+ Two optional parts of the doc make the catalog entry an explorer rather than a page. A
245
+ `controls` fence, one control per line, gives the entry a playground: its first example
246
+ becomes a live preview beside a form, with a phone, tablet and full width switch and the
247
+ source regenerated from the live markup.
248
+
249
+ ```controls
250
+ select data-state = - | empty | stale a "-" option removes the attribute
251
+ toggle data-commit = pending present or absent
252
+ text .dash-panel__title = Signups edits that element's text
253
+ ```
254
+
255
+ A `## Accessibility` section renders as its own block above the examples. Every component in
256
+ the dashboards layer carries both.
257
+
258
+ ### Dashboards
259
+
260
+ `components/dashboards/` holds the layer most GRAIN apps end up needing: `dashboard` (a head
261
+ that states the period and baseline, a KPI strip that adds columns as it widens, a panel grid
262
+ that queries its own width), `dash-panel` (ready, loading, empty, stale and failed), `delta` (a
263
+ change with a one-word baseline and no red or green), `bullet-graph` (in place of a gauge) and
264
+ `rank-list` (a slim share bar per row). They compose the stat tile, trend chart and data table
265
+ molecules. Charts take caller-computed values through custom properties; there is no chart
266
+ library. See plans/dashboard-layer.md.
267
+
244
268
  ### C · Make it AI-operable (optional: the payoff)
245
269
 
246
270
  Add the §2 conventions and the shared dispatcher drives it with **no bespoke JS**:
@@ -249,6 +273,31 @@ manifest), a `data-action="verb"` trigger, and express AI-mode off `data-commit`
249
273
  Register the verb in the vocabulary (`ai/contract.ts`, see the §5 rough-edge note). That's the
250
274
  whole path: a themed, catalogued, AI-operable component without editing GRAIN.
251
275
 
276
+ ## 7. grain-lint: keep the tells of machine-made design out
277
+
278
+ grain-lint renders a GRAIN page and checks it against a named list of tells, the defaults a
279
+ model falls into when it designs: a label above every heading, tracked capitals as decoration,
280
+ one coloured word in a headline, a run of identical cards, a sign-up closing the page. It is built
281
+ for the agent first. It runs on one page in seconds, names the rule and the selector, and says
282
+ which GRAIN token or component to use instead, so the agent fixes its own output before a person
283
+ looks.
284
+
285
+ ```sh
286
+ bun scripts/grain-lint.ts http://localhost:3000/notes # rendered at 360, 768 and 1280
287
+ bun scripts/grain-lint.ts --static components/ styles/ # source only, no browser, under a second
288
+ bun scripts/grain-lint.ts --json --rule tracked-caps page.html
289
+ ```
290
+
291
+ Every rule sits in one tier, and the tier decides what a finding does. Floor findings block with
292
+ no override: contrast below AA, a missing focus ring, motion that ignores reduced motion, a
293
+ hardcoded colour, sideways scroll at phone width, a form that goes nowhere. Reflex findings block
294
+ unless the element records a reason, as data-grain-lint-allow="rule-id: reason" on the element or
295
+ an ancestor, so the excuse sits next to the thing it excuses and shows up in a diff. Finish
296
+ findings report and never block. The rules are data in scripts/grain-lint-rules.ts, each with a
297
+ failing fixture and a shared clean page under scripts/fixtures/grain-lint. When the consumer has
298
+ axe-core installed, the contrast rule uses axe's own run rather than a second implementation.
299
+
300
+
252
301
  ---
253
302
 
254
303
  🤖 **Built with Claude, on the same buttons you'd click.** I called the shots, Claude typed them,
@@ -6,7 +6,7 @@ import { expect, test, describe, beforeAll, afterAll } from "bun:test";
6
6
  import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
7
7
  import { tmpdir } from "node:os";
8
8
  import { join } from "node:path";
9
- import { createCatalog } from "./catalog.ts";
9
+ import { createCatalog, parseControl } from "./catalog.ts";
10
10
 
11
11
  describe("createCatalog inject seams", () => {
12
12
  let dir: string;
@@ -65,3 +65,58 @@ describe("flat panels render source only", () => {
65
65
  expect(html).toContain(`data-surface="catalog:deck"`);
66
66
  });
67
67
  });
68
+
69
+ // The explorer: a ```controls fence becomes a playground, an Accessibility section becomes its own
70
+ // block, and the sidebar search carries the status line it announces into (plans/catalog-explorer.md).
71
+ describe("catalog explorer", () => {
72
+ let dir: string;
73
+
74
+ beforeAll(async () => {
75
+ dir = await mkdtemp(join(tmpdir(), "batch-catalog-play-"));
76
+ await mkdir(join(dir, "dashboards", "tile"), { recursive: true });
77
+ await writeFile(join(dir, "dashboards", "tile", "tile.md"),
78
+ "# Tile\n\nA counted thing.\n\n## Default\n\n```html\n<div class=\"tile\"><b class=\"tile__v\">3</b></div>\n```\n\n" +
79
+ "```controls\nselect data-tone = - | bad\ntoggle data-commit = pending\ntext .tile__v = 3\nnot a control\n```\n\n" +
80
+ "## Accessibility\n\nRead in source order.\n");
81
+ });
82
+ afterAll(() => rm(dir, { recursive: true, force: true }));
83
+
84
+ test("parseControl reads the three kinds and rejects the rest", () => {
85
+ expect(parseControl("select data-dir @ .delta = up | down")).toEqual(
86
+ { kind: "select", name: "data-dir", selector: ".delta", options: ["up", "down"], value: "up" });
87
+ expect(parseControl("toggle data-commit = pending")?.value).toBe("pending");
88
+ expect(parseControl("text .stat__value = 128")).toMatchObject({ kind: "text", selector: ".stat__value", value: "128" });
89
+ expect(parseControl("select data-x =")).toBeNull();
90
+ expect(parseControl("prose line")).toBeNull();
91
+ });
92
+
93
+ test("a controls fence renders a playground with labelled inputs and a width switch", async () => {
94
+ const html = await createCatalog(dir).html();
95
+ expect(html).toContain(`aria-label="Playground for Tile"`);
96
+ expect(html).toContain(`<option value="-">none</option>`);
97
+ expect(html).toContain(`data-kind="toggle" data-name="data-commit"`);
98
+ expect(html).toContain(`<label for="ctl-tile-2">Text of .tile__v</label>`);
99
+ expect(html).toContain(`data-width="phone"`);
100
+ expect(html).not.toContain("not a control");
101
+ });
102
+
103
+ test("the Accessibility section is its own block, not a group heading", async () => {
104
+ const html = await createCatalog(dir).html();
105
+ expect(html).toContain(`class="cat-a11y"`);
106
+ expect(html).toContain("Read in source order.");
107
+ expect(html).not.toContain(`<h3 class="cat-group">Accessibility</h3>`);
108
+ });
109
+
110
+ test("search announces into a status region, opens with slash, and a skip link leads to main", async () => {
111
+ const html = await createCatalog(dir).html();
112
+ expect(html).toContain(`role="status" aria-live="polite"`);
113
+ expect(html).toContain(`aria-keyshortcuts="/"`);
114
+ expect(html).toContain(`href="#cat-main">Skip to components</a>`);
115
+ expect(html).toContain(`data-text="a counted thing."`);
116
+ });
117
+
118
+ test("the catalog chrome wears no tracked capitals", async () => {
119
+ const html = await createCatalog(dir).html();
120
+ expect(html).not.toMatch(/text-transform:\s*uppercase/);
121
+ });
122
+ });
@@ -17,7 +17,13 @@ interface Panel { label: string; code: string; flat?: boolean; }
17
17
  // absent. Both intro and group prose are PARAGRAPHS rather than one joined string: joining them was
18
18
  // what turned four paragraphs of a component doc into a single wall.
19
19
  interface Group { label: string; prose: string[]; panels: Panel[]; }
20
- interface Doc { name: string; slug: string; intro: string[]; groups: Group[]; }
20
+ // A control is one input on a doc's playground, declared in a ```controls fence (one per line):
21
+ // select <attr> [@ <selector>] = a | b | c a "-" option removes the attribute
22
+ // toggle <attr> [@ <selector>] [= <value>] present or absent; value defaults to empty
23
+ // text <selector> = <default text> edits that element's text
24
+ // The shape copies Ladle's and Storybook's small fixed set of control kinds (plans/catalog-explorer.md).
25
+ export interface Control { kind: "select" | "toggle" | "text"; name: string; selector: string; options: string[]; value: string; }
26
+ interface Doc { name: string; slug: string; intro: string[]; groups: Group[]; controls: Control[]; a11y: string[]; }
21
27
  interface Component { layer: string; slug: string; name: string; human: Doc; ai: Doc | null; }
22
28
 
23
29
  const slugify = (s: string) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
@@ -42,9 +48,21 @@ const inline = (s: string) => esc(s)
42
48
  .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1");
43
49
 
44
50
  // atomic-design layers render in this order; unknown dirs fall to the end.
45
- const LAYER_ORDER = ["atoms", "molecules", "organisms"];
51
+ const LAYER_ORDER = ["atoms", "molecules", "organisms", "dashboards"];
46
52
  const rank = (layer: string) => { const i = LAYER_ORDER.indexOf(layer); return i < 0 ? 99 : i; };
47
53
 
54
+ /** Parse one line of a ```controls fence, or return null when it is not one. */
55
+ export function parseControl(line: string): Control | null {
56
+ const m = line.trim().match(/^(select|toggle|text)\s+(\S+)(?:\s+@\s+([^=]+?))?\s*(?:=\s*(.*))?$/);
57
+ if (!m) return null;
58
+ const kind = m[1] as Control["kind"];
59
+ const rest = (m[4] ?? "").trim();
60
+ if (kind === "text") return { kind, name: m[2], selector: m[2], options: [], value: rest };
61
+ const options = kind === "select" ? rest.split("|").map((o) => o.trim()).filter(Boolean) : [];
62
+ if (kind === "select" && !options.length) return null;
63
+ return { kind, name: m[2], selector: (m[3] ?? "").trim(), options, value: kind === "select" ? options[0] : rest };
64
+ }
65
+
48
66
  // minimal markdown: # title, ## group, ### panel, ```html fences, plain prose.
49
67
  // A fence tagged ```html flat renders as SOURCE ONLY, with no live panel. That escape hatch
50
68
  // exists for markup a catalog panel cannot honestly host: a component that sizes itself from
@@ -52,7 +70,7 @@ const rank = (layer: string) => { const i = LAYER_ORDER.indexOf(layer); return i
52
70
  // demonstrating itself inside its box. Default stays live — flat is the exception a doc asks for.
53
71
  function parseDoc(md: string): Doc {
54
72
  const lines = md.split("\n");
55
- const doc: Doc = { name: "Untitled", slug: "untitled", intro: [], groups: [] };
73
+ const doc: Doc = { name: "Untitled", slug: "untitled", intro: [], groups: [], controls: [], a11y: [] };
56
74
  let group: Group | null = null;
57
75
  let pendingLabel = "";
58
76
  const intro: string[] = [];
@@ -84,6 +102,12 @@ function parseDoc(md: string): Doc {
84
102
  group.panels.push({ label: pendingLabel, code: body.join("\n").trim(), flat });
85
103
  continue;
86
104
  }
105
+ if (line.startsWith("```controls")) {
106
+ i++;
107
+ while (i < lines.length && !lines[i].startsWith("```")) { const c = parseControl(lines[i]); if (c) doc.controls.push(c); i++; }
108
+ i++;
109
+ continue;
110
+ }
87
111
  // Any OTHER fence (```json, a bare ```) is skipped whole rather than read as prose. Falling
88
112
  // through used to sweep a spec block's braces into the surrounding paragraph, which is how raw
89
113
  // JSON ended up mid-sentence in two shipped intros.
@@ -98,6 +122,14 @@ function parseDoc(md: string): Doc {
98
122
  }
99
123
  doc.intro = intro.filter(Boolean);
100
124
  for (const g of doc.groups) g.prose = g.prose.filter(Boolean);
125
+ // An Accessibility section renders as its own labelled block beside the preview, not as one more
126
+ // group of panels, so it is lifted out here. Its panels, if a doc gave it any, stay as a group.
127
+ const a11y = doc.groups.findIndex((g) => /^accessibility$/i.test(g.label));
128
+ if (a11y >= 0) {
129
+ doc.a11y = doc.groups[a11y].prose;
130
+ if (doc.groups[a11y].panels.length) doc.groups[a11y].prose = [];
131
+ else doc.groups.splice(a11y, 1);
132
+ }
101
133
  return doc;
102
134
  }
103
135
 
@@ -185,8 +217,46 @@ export function createCatalog(componentsDir: string | string[], pages?: () => st
185
217
  ${paras("cat-note", g.prose)}
186
218
  ${g.panels.length ? `<div class="panel-grid">${g.panels.map(renderPanel).join("")}</div>` : ""}`).join("");
187
219
 
188
- const renderView = (doc: Doc, view: "smooth" | "grain") => `<div class="cat-doc__view" data-view="${view}">
220
+ const renderControl = (slug: string, c: Control, n: number): string => {
221
+ const id = `ctl-${slug}-${n}`;
222
+ const data = `data-kind="${c.kind}" data-name="${esc(c.name)}" data-selector="${esc(c.selector)}"`;
223
+ const label = c.kind === "text" ? `Text of ${c.selector}` : c.selector ? `${c.name} on ${c.selector}` : c.name;
224
+ if (c.kind === "select") return `<div class="cat-ctl"><label for="${id}">${esc(label)}</label>
225
+ <select id="${id}" class="cat-ctl__input" ${data}>${c.options.map((o) => `<option value="${esc(o)}">${o === "-" ? "none" : esc(o)}</option>`).join("")}</select></div>`;
226
+ if (c.kind === "toggle") return `<div class="cat-ctl cat-ctl--toggle"><input id="${id}" type="checkbox" class="cat-ctl__input" ${data} data-value="${esc(c.value)}"><label for="${id}">${esc(label)}</label></div>`;
227
+ return `<div class="cat-ctl"><label for="${id}">${esc(label)}</label><input id="${id}" type="text" class="cat-ctl__input" ${data} value="${esc(c.value)}"></div>`;
228
+ };
229
+
230
+ // The playground: the doc's first live example, a form of its controls, a width switch and the
231
+ // source regenerated from the live markup by the page script, so what you copy is what you see.
232
+ function renderPlayground(slug: string, doc: Doc): string {
233
+ const first = doc.groups.flatMap((g) => g.panels).find((p) => !p.flat);
234
+ if (!doc.controls.length || !first) return "";
235
+ return `<section class="cat-play" aria-label="Playground for ${esc(doc.name)}" data-play>
236
+ <div class="cat-play__stage">
237
+ <div class="cat-play__widths" role="group" aria-label="Preview width">
238
+ ${["Full", "Tablet", "Phone"].map((w, n) => `<button type="button" class="cat-play__width" data-width="${w.toLowerCase()}" aria-pressed="${n === 0}">${w}</button>`).join("")}
239
+ </div>
240
+ <div class="cat-play__frame" data-width="full" tabindex="0" role="region" aria-label="Preview of ${esc(doc.name)}"><div class="cat-play__live panel__live">${liveSafe(first.code)}</div></div>
241
+ </div>
242
+ <form class="cat-play__controls" aria-label="Controls" onsubmit="return false">
243
+ <h3 class="cat-play__heading">Controls</h3>
244
+ ${doc.controls.map((c, n) => renderControl(slug, c, n)).join("")}
245
+ </form>
246
+ <div class="panel__src cat-play__src">
247
+ <button class="panel__copy" type="button">Copy</button>
248
+ <pre tabindex="0" aria-label="Source for the current controls"><code>${esc(first.code)}</code></pre>
249
+ </div>
250
+ </section>`;
251
+ }
252
+
253
+ const renderA11y = (doc: Doc) => doc.a11y.length ? `<aside class="cat-a11y" aria-label="Accessibility notes for ${esc(doc.name)}">
254
+ <h3 class="cat-a11y__heading">Accessibility</h3>${paras("cat-note", doc.a11y)}</aside>` : "";
255
+
256
+ const renderView = (doc: Doc, view: "smooth" | "grain", slug = doc.slug) => `<div class="cat-doc__view" data-view="${view}">
189
257
  ${paras("cat-intro", doc.intro)}
258
+ ${view === "smooth" ? renderPlayground(slug, doc) : ""}
259
+ ${renderA11y(doc)}
190
260
  ${renderGroups(doc.groups)}
191
261
  </div>`;
192
262
 
@@ -197,15 +267,15 @@ export function createCatalog(componentsDir: string | string[], pages?: () => st
197
267
  return `<section class="cat-doc" id="${c.slug}" data-surface="catalog:${esc(c.slug)}" data-grade="smooth" data-layer="${c.layer}">
198
268
  <header class="cat-doc__head">
199
269
  <div class="cat-doc__title">
200
- <p class="cat-doc__eyebrow">${esc(cap(c.layer))}</p>
201
270
  <h2>${esc(c.name)}</h2>
271
+ <p class="cat-doc__layer">${esc(cap(c.layer))}</p>
202
272
  </div>
203
273
  <div class="grade-toggle" role="group" aria-label="Interaction mode for ${esc(c.name)}">
204
274
  <button type="button" class="grade-toggle__btn is-on" data-grade-set="smooth">Human</button>
205
275
  <button type="button" class="grade-toggle__btn" data-grade-set="grain">AI</button>
206
276
  </div>
207
277
  </header>
208
- ${renderView(c.human, "smooth")}
278
+ ${renderView(c.human, "smooth", c.slug)}
209
279
  ${renderView(ai, "grain")}
210
280
  </section>`;
211
281
  }
@@ -223,8 +293,8 @@ export function createCatalog(componentsDir: string | string[], pages?: () => st
223
293
  for (const c of list) { if (!byLayer.has(c.layer)) byLayer.set(c.layer, []); byLayer.get(c.layer)!.push(c); }
224
294
  const navGroups = [...byLayer.entries()].map(([layer, list]) => `
225
295
  <details class="cat-nav__group" open>
226
- <summary>${esc(cap(layer))}</summary>
227
- ${list.map(c => `<a href="#${c.slug}" data-name="${esc(c.name.toLowerCase())}">${esc(c.name)}</a>`).join("")}
296
+ <summary>${esc(cap(layer))} <span class="cat-nav__count">${list.length}</span></summary>
297
+ ${list.map(c => `<a href="#${c.slug}" data-name="${esc(c.name.toLowerCase())}" data-text="${esc(c.human.intro.join(" ").toLowerCase().slice(0, 400))}">${esc(c.name)}</a>`).join("")}
228
298
  </details>`).join("");
229
299
 
230
300
  const pageNav = (pages?.() ?? []).map(p => `<a href="${p}">${esc(p)}</a>`).join("");
@@ -255,7 +325,7 @@ function page(pageNav: string, navGroups: string, main: string, inject: CatalogI
255
325
  data-color-scheme/data-theme the render-blocking theme-boot inject applies from storage,
256
326
  so an embedded catalog matches its host. */
257
327
  body { margin: 0; background: var(--color-bg); color: var(--color-fg); }
258
- .cat { display: grid; grid-template-columns: 240px 1fr; min-height: 100vh; background: var(--color-bg); }
328
+ .cat { display: grid; grid-template-columns: 240px minmax(0, 1fr); min-height: 100vh; background: var(--color-bg); }
259
329
  .cat-nav { position: sticky; top: 0; align-self: start; height: 100vh; overflow: auto;
260
330
  padding: var(--space-6) var(--space-4); border-right: 1px solid var(--color-line); }
261
331
  .cat-back { display: inline-flex; align-items: center; margin-bottom: var(--space-4);
@@ -267,16 +337,27 @@ function page(pageNav: string, navGroups: string, main: string, inject: CatalogI
267
337
  padding: var(--space-1) var(--space-2); font-family: var(--font-smooth); font-size: var(--text-sm);
268
338
  color: var(--ink); background: transparent; border: 1px solid var(--ink); border-radius: var(--radius-sm); }
269
339
  .cat-search::placeholder { color: var(--ink-faint); }
270
- .cat-nav__heading { font-size: var(--text-xs); text-transform: uppercase; letter-spacing: 0.05em;
271
- color: var(--color-muted); margin: var(--space-4) 0 var(--space-1); }
340
+ .cat-nav__heading { font-size: var(--text-sm); font-weight: var(--font-weight-semibold);
341
+ color: var(--ink); margin: var(--space-4) 0 var(--space-1); }
272
342
  .cat-nav__group { margin-bottom: var(--space-2); }
273
343
  .cat-nav__group > summary { cursor: pointer; list-style: none; padding: var(--space-1) 0;
274
- font-size: var(--text-xs); text-transform: uppercase; letter-spacing: 0.06em; color: var(--color-muted); }
344
+ font-size: var(--text-sm); font-weight: var(--font-weight-semibold); color: var(--ink); }
345
+ .cat-nav__count { font-weight: var(--font-weight-regular); color: var(--color-muted); }
275
346
  .cat-nav__group > summary::-webkit-details-marker { display: none; }
276
347
  .cat-nav__group > summary::before { content: "▸ "; }
277
348
  .cat-nav__group[open] > summary::before { content: "▾ "; }
278
- .cat-nav a { display: block; color: var(--color-muted); text-decoration: none; padding: var(--space-1) 0; }
349
+ .cat-nav a { display: block; color: var(--color-muted); text-decoration: none; padding: var(--space-1) var(--space-2);
350
+ border-radius: var(--radius-sm); border-inline-start: 2px solid transparent; }
279
351
  .cat-nav a:hover { color: var(--ink); text-decoration: underline; }
352
+ .cat-nav a[aria-current="true"] { color: var(--ink); border-inline-start-color: var(--ink); background: var(--paper-2); }
353
+ .cat :focus-visible { outline: 2px solid var(--ink); outline-offset: 2px; }
354
+ .cat-skip { position: absolute; inset-inline-start: var(--space-2); inset-block-start: -10rem; z-index: 50;
355
+ padding: var(--space-2) var(--space-3); background: var(--paper); color: var(--ink); border: var(--border); border-radius: var(--radius-sm); }
356
+ .cat-skip:focus { inset-block-start: var(--space-2); }
357
+ .cat-search__wrap { position: relative; }
358
+ .cat-search__key { position: absolute; inset-inline-end: var(--space-2); inset-block-start: var(--space-1);
359
+ font-size: var(--text-xs); color: var(--color-muted); pointer-events: none; }
360
+ .cat-search__status { font-size: var(--text-xs); color: var(--color-muted); margin: calc(-1 * var(--space-3)) 0 var(--space-3); min-block-size: 1.2em; }
280
361
  .cat-main { padding: var(--space-8); max-width: 900px; }
281
362
  /* each component reads as a bounded CARD (hairline + generous padding), not bare text loose on
282
363
  the page — a doc with no live panels (a CSS-only pattern component, prose-only) used to read
@@ -288,14 +369,12 @@ function page(pageNav: string, navGroups: string, main: string, inject: CatalogI
288
369
  padding: var(--space-6); border: 1px solid var(--color-line); border-radius: var(--radius-md);
289
370
  }
290
371
  .cat-doc h2 { font-size: var(--text-2xl); margin: 0; }
291
- .cat-doc__eyebrow { font-size: var(--text-xs); text-transform: uppercase; letter-spacing: 0.06em;
292
- color: var(--color-muted); margin: 0 0 var(--space-1); }
372
+ .cat-doc__layer { font-size: var(--text-sm); color: var(--color-muted); margin: var(--space-1) 0 0; }
293
373
  .cat-doc__head { display: flex; align-items: baseline; justify-content: space-between; gap: var(--space-4);
294
374
  flex-wrap: wrap; padding-bottom: var(--space-3); margin-bottom: var(--space-4);
295
375
  border-bottom: 1px solid var(--color-line); } /* masthead rhythm: title block → hairline → body */
296
376
  .grade-toggle { display: inline-flex; border: 1px solid var(--ink); border-radius: var(--radius-sm); overflow: hidden; }
297
- .grade-toggle__btn { font-family: var(--font-smooth); font-size: var(--text-xs); text-transform: uppercase;
298
- letter-spacing: 0.08em; padding: var(--space-1) var(--space-3); cursor: pointer;
377
+ .grade-toggle__btn { font-family: var(--font-smooth); font-size: var(--text-sm); padding: var(--space-1) var(--space-3); cursor: pointer;
299
378
  background: transparent; color: var(--ink); border: 0; }
300
379
  .grade-toggle__btn.is-on { background: var(--ink); color: var(--paper); }
301
380
  /* Human/AI: show exactly one view, chosen by the section's data-grade */
@@ -318,13 +397,45 @@ function page(pageNav: string, navGroups: string, main: string, inject: CatalogI
318
397
  background: var(--paper-2); padding: 0 0.3em; border-radius: 2px; color: var(--ink); }
319
398
  .cat-intro strong, .cat-note strong { color: var(--ink); font-weight: var(--font-weight-semibold); }
320
399
  .cat-intro a, .cat-note a { color: var(--ink); }
321
- .cat-group { font-size: var(--text-sm); text-transform: uppercase; letter-spacing: 0.05em;
322
- color: var(--color-muted); margin: var(--space-6) 0 var(--space-3); }
400
+ .cat-group { font-size: var(--text-base); font-weight: var(--font-weight-semibold);
401
+ color: var(--ink); margin: var(--space-6) 0 var(--space-3); }
402
+ /* Playground: preview, controls and live source. Two columns when there is room, one when not. */
403
+ .cat-play { display: grid; gap: 0; grid-template-columns: minmax(0, 1fr) minmax(12rem, 16rem); margin: 0 0 var(--space-6);
404
+ border: var(--border); border-radius: var(--radius-md); overflow: hidden; background: var(--color-surface); }
405
+ .cat-play__stage { display: grid; align-content: start; gap: var(--space-2); padding: var(--space-3); min-inline-size: 0; }
406
+ .cat-play__widths { display: inline-flex; gap: var(--space-1); justify-self: start; }
407
+ .cat-play__width { font: inherit; font-size: var(--text-xs); padding: var(--space-1) var(--space-2); cursor: pointer;
408
+ border: var(--border); border-radius: var(--radius-sm); background: transparent; color: var(--ink); }
409
+ .cat-play__width[aria-pressed="true"] { background: var(--ink); color: var(--paper); border-color: var(--ink); }
410
+ .cat-play__frame { inline-size: 100%; margin-inline: auto; border: 1px dashed var(--color-line); border-radius: var(--radius-sm); overflow: auto; }
411
+ .cat-play__frame[data-width="tablet"] { max-inline-size: 48rem; }
412
+ .cat-play__frame[data-width="phone"] { max-inline-size: 23.5rem; }
413
+ .cat-play__live { display: block; }
414
+ .cat-play__controls { display: grid; align-content: start; gap: var(--space-3); padding: var(--space-3) var(--space-4);
415
+ border-inline-start: var(--border); font-size: var(--text-sm); }
416
+ .cat-play__heading { margin: 0; font-size: var(--text-sm); font-weight: var(--font-weight-semibold); }
417
+ .cat-ctl { display: grid; gap: var(--space-1); }
418
+ .cat-ctl label { color: var(--color-muted); }
419
+ .cat-ctl--toggle { grid-template-columns: auto 1fr; align-items: center; gap: var(--space-2); }
420
+ .cat-ctl__input { font: inherit; color: var(--ink); background: var(--color-bg); border: 1px solid var(--ink);
421
+ border-radius: var(--radius-sm); padding: var(--space-1) var(--space-2); min-inline-size: 0; }
422
+ .cat-ctl--toggle .cat-ctl__input { inline-size: 1.1rem; block-size: 1.1rem; padding: 0; accent-color: var(--ink); }
423
+ .cat-play__src { grid-column: 1 / -1; }
424
+ .cat-a11y { margin: 0 0 var(--space-6); padding: var(--space-3) var(--space-4); border-inline-start: 3px solid var(--ink);
425
+ background: var(--paper-2); border-radius: var(--radius-sm); }
426
+ .cat-a11y__heading { margin: 0 0 var(--space-2); font-size: var(--text-base); font-weight: var(--font-weight-semibold); color: var(--ink); }
427
+ .cat-a11y .cat-note { color: var(--ink); }
428
+ .cat-a11y .cat-note:last-child { margin-bottom: 0; }
429
+ @media (max-width: 760px) { .cat-play { grid-template-columns: minmax(0, 1fr); }
430
+ .cat-play__controls { border-inline-start: 0; border-block-start: var(--border); } }
323
431
  .panel-grid { display: grid; gap: var(--space-4); grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); }
432
+ /* Dashboards lay themselves out by their own width, so their panels take the whole row and the
433
+ live area stops centring: a centred flex box shrank a dashboard to the width of its widest word. */
434
+ .cat-doc[data-layer="dashboards"] .panel-grid { grid-template-columns: minmax(0, 1fr); }
435
+ .cat-doc[data-layer="dashboards"] .panel__live { display: block; }
324
436
  .panel { margin: 0; border: 1px solid var(--color-line); border-radius: var(--radius-md);
325
437
  overflow: hidden; background: var(--color-surface); }
326
- .panel__label { font-size: var(--text-xs); font-weight: var(--font-weight-semibold);
327
- text-transform: uppercase; letter-spacing: 0.04em; color: var(--color-muted);
438
+ .panel__label { font-size: var(--text-sm); font-weight: var(--font-weight-medium); color: var(--color-muted);
328
439
  padding: var(--space-2) var(--space-3); border-bottom: 1px solid var(--color-line); }
329
440
  .panel__live { padding: var(--space-6); display: flex; align-items: center; justify-content: center; background: var(--color-bg); }
330
441
  .panel__flat { margin: 0; padding: var(--space-4) var(--space-6); background: var(--color-bg);
@@ -344,19 +455,17 @@ function page(pageNav: string, navGroups: string, main: string, inject: CatalogI
344
455
  persistent 240px menu, so the nav COLLAPSES by default and opens FULL-WIDTH over the
345
456
  main — the small-screen drawer pattern. The narrow catalog-peek sidebar inherits this. */
346
457
  @media (max-width: 640px) {
347
- .cat { grid-template-columns: 1fr; }
458
+ .cat { grid-template-columns: minmax(0, 1fr); }
348
459
  .cat-navtoggle { display: inline-flex; align-items: center; position: sticky; top: 0; z-index: 30;
349
460
  width: 100%; box-sizing: border-box; padding: var(--space-3) var(--space-4);
350
461
  border: 0; border-bottom: 1px solid var(--color-line); background: var(--paper); color: var(--ink);
351
- font-family: var(--font-smooth); font-size: var(--text-sm); text-transform: uppercase;
352
- letter-spacing: 0.06em; cursor: pointer; }
462
+ font-family: var(--font-smooth); font-size: var(--text-sm); font-weight: var(--font-weight-semibold); cursor: pointer; }
353
463
  .cat-nav { position: fixed; inset: 0; z-index: 40; width: 100%; height: 100dvh;
354
464
  background: var(--paper); /* opaque: a full-screen drawer OVER the main, not see-through */
355
465
  transform: translateX(-100%); transition: transform 0.25s ease; overscroll-behavior: contain; }
356
466
  .cat[data-nav="open"] .cat-nav { transform: none; } /* full-screen takeover */
357
467
  .cat-nav__close { display: inline-flex; align-items: center; background: transparent; border: 0;
358
- padding: 0 0 var(--space-3); font-family: var(--font-smooth); font-size: var(--text-sm);
359
- text-transform: uppercase; letter-spacing: 0.06em; color: var(--color-muted); cursor: pointer; }
468
+ padding: 0 0 var(--space-3); font-family: var(--font-smooth); font-size: var(--text-sm); color: var(--color-muted); cursor: pointer; }
360
469
  .cat-main { padding: var(--space-6); overscroll-behavior: contain; }
361
470
  }
362
471
  @media (prefers-reduced-motion: reduce) { .cat-nav { transition: none; } }
@@ -378,6 +487,7 @@ function page(pageNav: string, navGroups: string, main: string, inject: CatalogI
378
487
  </style>
379
488
  </head>
380
489
  <body>
490
+ <a class="cat-skip" href="#cat-main">Skip to components</a>
381
491
  <div class="cat" data-nav="closed">
382
492
  <button class="cat-navtoggle" type="button" aria-controls="cat-nav" aria-expanded="false">☰&nbsp;&nbsp;Catalog</button>
383
493
  <aside class="cat-nav" id="cat-nav">
@@ -387,13 +497,17 @@ function page(pageNav: string, navGroups: string, main: string, inject: CatalogI
387
497
  <button class="cat-nav__close" type="button" aria-label="Close menu">✕&nbsp;&nbsp;Close</button>
388
498
  <h1>Catalog</h1>
389
499
  <p class="cat-nav__auto">Auto-generated by GRAIN from each component's <code>.md</code> doc — not hand-authored.</p>
390
- <input class="cat-search" type="search" placeholder="Search components…" aria-label="Search components">
500
+ <div class="cat-search__wrap">
501
+ <input class="cat-search" type="search" placeholder="Search components" aria-label="Search components" aria-keyshortcuts="/" aria-describedby="cat-search-status">
502
+ <kbd class="cat-search__key" aria-hidden="true">/</kbd>
503
+ </div>
504
+ <p class="cat-search__status" id="cat-search-status" role="status" aria-live="polite"></p>
391
505
  <p class="cat-nav__heading">Pages</p>
392
506
  ${pageNav}
393
507
  <p class="cat-nav__heading">Components</p>
394
508
  ${navGroups}
395
509
  </aside>
396
- <main class="cat-main">
510
+ <main class="cat-main" id="cat-main" tabindex="-1">
397
511
  ${main}
398
512
  </main>
399
513
  </div>
@@ -453,20 +567,82 @@ function page(pageNav: string, navGroups: string, main: string, inject: CatalogI
453
567
  }
454
568
  }));
455
569
 
456
- // sidebar search: filter component links; hide empty groups; open groups while searching.
570
+ // sidebar search: name and opening prose; hide empty groups; announce the count; "/" opens it,
571
+ // Escape clears it. Arrow keys move through the visible sidebar links.
457
572
  const search = document.querySelector(".cat-search");
458
- if (search) search.addEventListener("input", () => {
573
+ const status = document.getElementById("cat-search-status");
574
+ const filter = () => {
459
575
  const q = search.value.trim().toLowerCase();
576
+ let hits = 0;
460
577
  document.querySelectorAll(".cat-nav__group").forEach((group) => {
461
578
  let any = false;
462
579
  group.querySelectorAll("a").forEach((a) => {
463
- const hit = !q || (a.dataset.name || "").includes(q);
580
+ const hit = !q || (a.dataset.name || "").includes(q) || (a.dataset.text || "").includes(q);
464
581
  a.style.display = hit ? "" : "none";
465
- if (hit) any = true;
582
+ if (hit) { any = true; hits++; }
466
583
  });
467
584
  group.style.display = any ? "" : "none";
468
585
  if (q) group.open = true;
469
586
  });
587
+ if (status) status.textContent = !q ? "" : hits ? hits + (hits === 1 ? " component matches" : " components match") : "No component matches \u201c" + search.value.trim() + "\u201d";
588
+ };
589
+ if (search) {
590
+ search.addEventListener("input", filter);
591
+ search.addEventListener("keydown", (e) => { if (e.key === "Escape" && search.value) { search.value = ""; filter(); e.stopPropagation(); } });
592
+ document.addEventListener("keydown", (e) => {
593
+ const t = e.target;
594
+ const typing = t && (t.tagName === "INPUT" || t.tagName === "TEXTAREA" || t.tagName === "SELECT" || t.isContentEditable);
595
+ if (e.key === "/" && !typing && !e.metaKey && !e.ctrlKey) { e.preventDefault(); setNav(true); search.focus(); }
596
+ });
597
+ }
598
+ const navEl = document.querySelector(".cat-nav");
599
+ navEl && navEl.addEventListener("keydown", (e) => {
600
+ if (e.key !== "ArrowDown" && e.key !== "ArrowUp") return;
601
+ const links = [...navEl.querySelectorAll(".cat-nav__group a")].filter((a) => a.offsetParent !== null);
602
+ if (!links.length) return;
603
+ const i = links.indexOf(document.activeElement);
604
+ if (i < 0 && document.activeElement !== search) return;
605
+ e.preventDefault();
606
+ const next = e.key === "ArrowDown" ? Math.min(i + 1, links.length - 1) : Math.max(i - 1, 0);
607
+ links[next].focus();
608
+ });
609
+
610
+ // mark the component in view in the sidebar (aria-current), so the reader knows where they are
611
+ if ("IntersectionObserver" in window) {
612
+ const navLinks = new Map([...document.querySelectorAll(".cat-nav__group a")].map((a) => [a.getAttribute("href").slice(1), a]));
613
+ const io = new IntersectionObserver((entries) => {
614
+ for (const en of entries) if (en.isIntersecting) {
615
+ navLinks.forEach((a) => a.removeAttribute("aria-current"));
616
+ navLinks.get(en.target.id)?.setAttribute("aria-current", "true");
617
+ }
618
+ }, { rootMargin: "-20% 0px -70% 0px" });
619
+ document.querySelectorAll(".cat-doc").forEach((d) => io.observe(d));
620
+ }
621
+
622
+ // playground: each control rewrites the preview's root (or a selector inside it), then the
623
+ // source panel is regenerated from the live markup, so the copied code matches the preview.
624
+ document.querySelectorAll("[data-play]").forEach((play) => {
625
+ const live = play.querySelector(".cat-play__live");
626
+ const code = play.querySelector(".cat-play__src code");
627
+ const root = live.firstElementChild;
628
+ const sync = () => { code.textContent = root ? root.outerHTML : ""; };
629
+ play.querySelectorAll(".cat-ctl__input").forEach((input) => {
630
+ const apply = () => {
631
+ const sel = input.dataset.selector;
632
+ const kind = input.dataset.kind;
633
+ if (kind === "text") { const el = live.querySelector(sel); if (el) el.textContent = input.value; return sync(); }
634
+ const el = sel ? live.querySelector(sel) : root;
635
+ if (!el) return;
636
+ if (kind === "select") { input.value === "-" ? el.removeAttribute(input.dataset.name) : el.setAttribute(input.dataset.name, input.value); }
637
+ else input.checked ? el.setAttribute(input.dataset.name, input.dataset.value || "") : el.removeAttribute(input.dataset.name);
638
+ sync();
639
+ };
640
+ input.addEventListener(input.type === "text" ? "input" : "change", apply);
641
+ });
642
+ play.querySelectorAll(".cat-play__width").forEach((b) => b.addEventListener("click", () => {
643
+ play.querySelector(".cat-play__frame").dataset.width = b.dataset.width;
644
+ play.querySelectorAll(".cat-play__width").forEach((x) => x.setAttribute("aria-pressed", String(x === b)));
645
+ }));
470
646
  });
471
647
  </script>
472
648
  ${inject.bodyEnd ?? ""}
@@ -0,0 +1,15 @@
1
+ /* dashboards/bullet-graph — a bar, a target line and grey qualitative ranges, in place of a
2
+ radial gauge. Values arrive as fractions of the scale through custom properties (--value,
3
+ --target, --poor, --fair), so no chart library and no inline colour. The ranges are ink tints,
4
+ darkest for the worst band, so the bar reads against them in both themes. */
5
+ .bullet { --value: 0; --target: 0; --poor: 0; --fair: 0; position: relative; block-size: var(--space-6); border-radius: var(--radius-sm);
6
+ background: linear-gradient(to right,
7
+ var(--ink-faint) 0 calc(var(--poor, 0) * 100%),
8
+ var(--line-soft) 0 calc(var(--fair, 0) * 100%),
9
+ var(--paper-2) 0 100%); }
10
+ .bullet__bar { position: absolute; inset-block: 35%; inset-inline-start: 0;
11
+ inline-size: calc(var(--value, 0) * 100%); background: var(--ink); border-radius: var(--radius-sm); }
12
+ .bullet__target { position: absolute; inset-block: 15%; inline-size: var(--space-1);
13
+ inset-inline-start: calc(var(--target, 0) * 100% - var(--space-1) / 2); background: var(--ink); }
14
+ .bullet__legend { margin: var(--space-1) 0 0; font-size: var(--text-sm); color: var(--color-muted);
15
+ font-variant-numeric: tabular-nums; }
@@ -0,0 +1,34 @@
1
+ # Bullet graph
2
+
3
+ A measure against its target, drawn as a bar over grey qualitative ranges with a short line at the
4
+ target. It replaces the radial gauge, which spends a circle of space to show one number and makes
5
+ two values hard to compare.
6
+
7
+ The caller passes fractions of the scale as custom properties: --value for the bar, --target for
8
+ the line, and --poor and --fair for where the two darker bands end. The component computes nothing
9
+ and judges nothing; which band counts as poor is the caller's call, and it belongs in the legend.
10
+
11
+ ## Against a target
12
+
13
+ ### Near target
14
+
15
+ ```html
16
+ <div class="bullet" role="img" aria-label="Revenue €48.2k of a €60k target" style="--value: 0.8; --target: 0.9; --poor: 0.5; --fair: 0.75" data-surface="bullet:revenue">
17
+ <span class="bullet__bar"></span><span class="bullet__target"></span>
18
+ </div>
19
+ ```
20
+
21
+ ### Well short
22
+
23
+ ```html
24
+ <div class="bullet" role="img" aria-label="Signups 140 of a 400 target" style="--value: 0.35; --target: 0.8; --poor: 0.5; --fair: 0.75" data-surface="bullet:signups">
25
+ <span class="bullet__bar"></span><span class="bullet__target"></span>
26
+ </div>
27
+ ```
28
+
29
+ ## Accessibility
30
+
31
+ The graph is one image to assistive technology, so its aria-label must state the value and the
32
+ target in words, unit first. Put the same numbers in a visible legend (bullet__legend) below the
33
+ graph, because a reader zoomed in or on a small screen should not need to estimate a bar length.
34
+ The ranges differ in lightness, not hue, so they survive greyscale and colour blindness.
@@ -0,0 +1,14 @@
1
+ /* dashboards/dash-panel — the surface a chart, table or list sits on. A heading, an optional
2
+ action, and the four states every data panel has: ready, loading (the shared
3
+ data-commit="pending" idiom), empty, stale. Tone is border weight and ink level, never hue. */
4
+ .dash-panel { display: flex; flex-direction: column; gap: var(--space-3); min-inline-size: 0;
5
+ padding: var(--space-4); border: var(--border); border-radius: var(--radius-md); background: var(--color-surface); }
6
+ .dash-panel__head { display: flex; align-items: baseline; justify-content: space-between; gap: var(--space-3); }
7
+ .dash-panel__title { margin: 0; font-size: var(--text-base); font-weight: var(--font-weight-medium); color: var(--ink); }
8
+ .dash-panel__action { font-size: var(--text-sm); color: var(--ink); }
9
+ .dash-panel__note { margin: 0; font-size: var(--text-sm); color: var(--color-muted); }
10
+ .dash-panel[data-state="empty"] .dash-panel__note,
11
+ .dash-panel[data-state="error"] .dash-panel__note { color: var(--ink); }
12
+ .dash-panel[data-state="stale"] { border-style: dotted; }
13
+ .dash-panel[data-state="error"] { border-color: var(--ink); }
14
+ .dash-panel[data-commit="pending"], [data-grade="grain"] .dash-panel { border-style: dashed; border-color: var(--ink); }