@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 +49 -0
- package/catalog/catalog.test.ts +56 -1
- package/catalog/catalog.ts +208 -32
- package/components/dashboards/bullet-graph/bullet-graph.css +15 -0
- package/components/dashboards/bullet-graph/bullet-graph.md +34 -0
- package/components/dashboards/dash-panel/dash-panel.css +14 -0
- package/components/dashboards/dash-panel/dash-panel.md +66 -0
- package/components/dashboards/dashboard/dashboard.css +19 -0
- package/components/dashboards/dashboard/dashboard.md +70 -0
- package/components/dashboards/dashboards.test.ts +44 -0
- package/components/dashboards/delta/delta.css +9 -0
- package/components/dashboards/delta/delta.md +42 -0
- package/components/dashboards/rank-list/rank-list.css +10 -0
- package/components/dashboards/rank-list/rank-list.md +27 -0
- package/components/molecules/stat-tile/stat-tile.css +11 -0
- package/components/molecules/stat-tile/stat-tile.md +20 -0
- package/components/organisms/app-shell/app-shell.md +9 -1
- package/components/organisms/note/note.css +1 -2
- package/components/organisms/note/note.md +2 -2
- package/package.json +4 -2
- package/scripts/grain-lint-rules.ts +524 -0
- package/scripts/grain-lint.test.ts +77 -0
- package/scripts/grain-lint.ts +179 -0
- package/styles/global.css +4 -3
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,
|
package/catalog/catalog.test.ts
CHANGED
|
@@ -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
|
+
});
|
package/catalog/catalog.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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-
|
|
271
|
-
color: var(--
|
|
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-
|
|
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)
|
|
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-
|
|
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-
|
|
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-
|
|
322
|
-
color: var(--
|
|
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-
|
|
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);
|
|
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">☰ 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">✕ 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
|
-
<
|
|
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:
|
|
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
|
-
|
|
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); }
|