@tjakoen/grain 0.1.27 → 0.1.29

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
@@ -204,6 +204,10 @@ is the worked example: `project/` and `tjakoen.github.io/` are two consumers doi
204
204
 
205
205
  ### A · A theme (re-skin): override token slots, never components
206
206
 
207
+ *Keep a theme at WCAG 2.2 AA:* muted ink and the accent each need 4.5:1 against both the page and the
208
+ panel background, in both color schemes, because both are used as text. The faint ink token is
209
+ decorative only and never carries text or a control.
210
+
207
211
  1. Write a stylesheet that redefines the §4 token slots (`--paper`, `--ink`, `--font-*`,
208
212
  `--space-*`, `--radius-*`, `--ai-veil`, …). **Touch no component CSS.**
209
213
  2. Link it **after** GRAIN's `variables.css` in your pages. Every `b-*` atom re-skins.
@@ -173,7 +173,7 @@ export function createCatalog(componentsDir: string | string[], pages?: () => st
173
173
  ${p.flat ? `<p class="panel__flat">Source only — this one owns the whole window, so a panel cannot host it. Open a real one.</p>` : `<div class="panel__live">${liveSafe(p.code)}</div>`}
174
174
  <div class="panel__src">
175
175
  <button class="panel__copy" type="button">Copy</button>
176
- <pre><code>${esc(p.code)}</code></pre>
176
+ <pre tabindex="0"><code>${esc(p.code)}</code></pre>
177
177
  </div>
178
178
  </figure>`;
179
179
  }
@@ -6,7 +6,7 @@
6
6
  background: transparent;
7
7
  }
8
8
  .badge[data-status="active"] { color: var(--ink); border-color: var(--ink); }
9
- .badge[data-status="archived"] { color: var(--ink-faint); }
9
+ .badge[data-status="archived"] { color: var(--ink-muted); }
10
10
 
11
11
  /* ---- AI / in-transit: the non-text grain. A badge the AI is setting (live pending, or
12
12
  any grain ancestor) wears the dashed "terminal" edge; the label already swaps to the
@@ -8,7 +8,7 @@
8
8
  color: var(--ink); background: transparent;
9
9
  border: var(--border); border-radius: var(--radius-sm); /* hard edge — you tap it */
10
10
  }
11
- .field__input::placeholder { color: var(--ink-faint); }
11
+ .field__input::placeholder { color: var(--ink-muted); }
12
12
  /* focus ring; data-force parallel lets the catalog show the state statically (same pattern as
13
13
  the button) — never `autofocus`, which would steal focus + scroll the catalog on load. */
14
14
  .field__input:focus-visible, .field__input[data-force~="focus"] { outline: 2px solid var(--color-accent); outline-offset: 1px; }
@@ -21,7 +21,7 @@
21
21
  per-control copy of these rules is how one frame becomes four. Both hide when empty, which is what
22
22
  makes them safe to put in every template: a slot with nothing in it must not open a gap in the
23
23
  column, and an optional slot nobody fills is the common case, not the exception. */
24
- .field__hint { font-size: var(--text-xs); color: var(--ink-faint); line-height: var(--leading-normal); }
24
+ .field__hint { font-size: var(--text-xs); color: var(--ink-muted); line-height: var(--leading-normal); }
25
25
  /* An error is NOT a red one. Status is weight, not hue (DESIGN-SYSTEM §2): the message reads at full
26
26
  ink against a hint's faint, and --color-danger is hueless by default so a flavor that DOES own a
27
27
  hue can reach it without this file ever naming a color. */
@@ -10,9 +10,11 @@ the meter an `aria-label`; for a single-value progress meter add `aria-valuenow`
10
10
 
11
11
  ## Health bar (three tones)
12
12
  `ok` is solid ink, `bad` is a dense hatch, an untoned/`pending` segment is faint. Order and
13
- widths are author-set.
13
+ widths are author-set. Several segments are not one value, so the health bar is `role="img"` with a label that
14
+ states the split in words; `role="meter"` is kept for the single-value progress form, where
15
+ `aria-valuenow` is required (WCAG 4.1.2).
14
16
  ```html
15
- <div class="meter" role="meter" aria-label="Run health">
17
+ <div class="meter" role="img" aria-label="Run health: 70% ok, 20% failing, 10% pending">
16
18
  <span class="meter__seg" data-tone="ok" style="--seg: 70%"></span>
17
19
  <span class="meter__seg" data-tone="bad" style="--seg: 20%"></span>
18
20
  <span class="meter__seg" data-tone="pending" style="--seg: 10%"></span>
@@ -30,14 +32,14 @@ widths are author-set.
30
32
  `data-state="busy"` sweeps a faint stripe across the track (static faint fill under
31
33
  `prefers-reduced-motion`).
32
34
  ```html
33
- <div class="meter" data-state="busy" role="meter" aria-label="Running…">
35
+ <div class="meter" data-state="busy" role="progressbar" aria-label="Running…">
34
36
  <span class="meter__seg"></span>
35
37
  </div>
36
38
  ```
37
39
 
38
40
  ## In transit (AI updating the meter)
39
41
  ```html
40
- <div class="meter" data-commit="pending" role="meter" aria-label="Run health">
42
+ <div class="meter" data-commit="pending" role="img" aria-label="Run health, updating">
41
43
  <span class="meter__seg" data-tone="ok" style="--seg: 55%"></span>
42
44
  <span class="meter__seg" data-tone="pending" style="--seg: 45%"></span>
43
45
  </div>
@@ -18,7 +18,7 @@
18
18
  scale moves it too. */
19
19
  min-height: calc(var(--text-base) * var(--leading-relaxed) * 4 + var(--space-2) * 2);
20
20
  }
21
- .field__textarea::placeholder { color: var(--ink-faint); }
21
+ .field__textarea::placeholder { color: var(--ink-muted); }
22
22
  /* focus ring; data-force parallel lets the catalog show the state statically (same pattern as
23
23
  b-input) — never `autofocus`, which would steal focus + scroll the catalog on load. */
24
24
  .field__textarea:focus-visible, .field__textarea[data-force~="focus"] { outline: 2px solid var(--color-accent); outline-offset: 1px; }
@@ -5,16 +5,18 @@ A monospace block for fenced code — plus a `.code-inline` run for inline code.
5
5
  edge (non-text grain), not a font swap. CSS-only: composed by hand (by MILL), nothing data-binds
6
6
  it, so there is no template. Long lines scroll rather than break the column.
7
7
 
8
+ A code block that can scroll sideways carries `tabindex="0"` so a keyboard can scroll it (WCAG 2.1.1); MILL adds it to every fence.
9
+
8
10
  ## Block
9
11
 
10
12
  ### Plain
11
13
  ```html
12
- <pre class="code-block"><code>bun run dev</code></pre>
14
+ <pre class="code-block" tabindex="0"><code>bun run dev</code></pre>
13
15
  ```
14
16
 
15
17
  ### With a language tag
16
18
  ```html
17
- <pre class="code-block" data-lang="ts"><code>export const answer = 42;</code></pre>
19
+ <pre class="code-block" tabindex="0" data-lang="ts"><code>export const answer = 42;</code></pre>
18
20
  ```
19
21
 
20
22
  ## Inline
@@ -27,7 +27,7 @@
27
27
  .chat-message[data-grade="grain"], .chat-message[data-commit="pending"] { --type-font: var(--font-grain-fine); }
28
28
  .chat-message__who {
29
29
  display: block; margin-bottom: 2px;
30
- font-size: var(--text-xs); text-transform: uppercase; letter-spacing: 0.06em; color: var(--ink-faint);
30
+ font-size: var(--text-xs); text-transform: uppercase; letter-spacing: 0.06em; color: var(--ink-muted);
31
31
  }
32
32
  /* the body reads the inherited grade font (a <span> isn't in grain.css's type selector), so the
33
33
  AI's line actually renders grain when the message carries data-grade="grain". */
@@ -23,5 +23,11 @@ title as the message, tags as branch chips. Opt in per collection (MILL's `index
23
23
  default listing is unchanged for collections that don't ask for it.
24
24
 
25
25
  ```html
26
- <ul class="content-index" data-variant="log">…</ul>
26
+ <ul class="content-index" data-variant="log">
27
+ <li class="content-index__item">
28
+ <p class="content-index__meta">2026-07-04</p>
29
+ <h2 class="content-index__title"><a href="/notes/the-browser-grew-up">The Browser Grew Up</a></h2>
30
+ <div class="note__tags"><span class="badge" data-status="active">native-first</span></div>
31
+ </li>
32
+ </ul>
27
33
  ```
@@ -15,7 +15,7 @@
15
15
  line-height: var(--leading-tight); color: var(--ink);
16
16
  }
17
17
  .stat__label { font-size: var(--text-sm); color: var(--color-muted); }
18
- .stat__sub { font-size: var(--text-xs); color: var(--ink-faint); }
18
+ .stat__sub { font-size: var(--text-xs); color: var(--ink-muted); }
19
19
 
20
20
  /* ---- tone (attribute) — ink-level + border weight, NOT hue ----
21
21
  default : the calm baseline (a healthy/positive count needs no shouting).
@@ -23,8 +23,8 @@
23
23
  bad : draws the eye monochromatically — a solid-ink border + full-ink value.
24
24
  muted : a context/secondary count (skipped, pending, a total) recedes to faint. */
25
25
  .stat[data-tone="bad"] { border-color: var(--ink); }
26
- .stat[data-tone="muted"] .stat__value { color: var(--ink-faint); }
27
- .stat[data-tone="muted"] .stat__label { color: var(--ink-faint); }
26
+ .stat[data-tone="muted"] .stat__value { color: var(--ink-muted); }
27
+ .stat[data-tone="muted"] .stat__label { color: var(--ink-muted); }
28
28
 
29
29
  /* ---- AI / in-transit: the non-text grain, same vocabulary as the button/field/badge
30
30
  (AI-INTERFACE §5). A tile whose number is mid-update wears the dashed "terminal" edge; a
@@ -24,7 +24,7 @@
24
24
  /* ---- waiting: a row the runner hasn't reached yet recedes to faint (generic queue/pending
25
25
  state — not a domain status) ---- */
26
26
  .status-list__item[data-state="waiting"] .status-list__mark,
27
- .status-list__item[data-state="waiting"] .status-list__title { color: var(--ink-faint); }
27
+ .status-list__item[data-state="waiting"] .status-list__title { color: var(--ink-muted); }
28
28
 
29
29
  /* ---- AI / in-transit + "this row is being acted on": the grain control lifecycle (lesson 2),
30
30
  same vocabulary as the button/field. An in-flight row (a runner is acting on it, or the AI is)
@@ -19,14 +19,16 @@
19
19
  .tab[aria-current="page"] .tab__icon, .tab[data-active="true"] .tab__icon { color: var(--color-accent, var(--ink)); }
20
20
  .tab__close {
21
21
  display: inline-flex; align-items: center; justify-content: center;
22
- width: 1.15rem; height: 1.15rem; border-radius: var(--radius-sm);
22
+ width: 1.5rem; height: 1.5rem; /* 24px: the WCAG 2.2 target-size minimum (2.5.8) */ border-radius: var(--radius-sm);
23
23
  color: transparent; pointer-events: none; /* hidden until the tab is hovered/active */
24
24
  }
25
- .tab:hover .tab__close, .tab[aria-current="page"] .tab__close, .tab[data-active="true"] .tab__close { color: var(--ink-faint); }
25
+ .tab:hover .tab__close, .tab[aria-current="page"] .tab__close, .tab[data-active="true"] .tab__close { color: var(--ink-muted); }
26
26
  /* the PINNED marker: same box as .tab__close but ALWAYS visible and never interactive — it
27
27
  reads "this tab doesn't close" (a pinned tab ships a .tab__pin instead of a .tab__close). */
28
28
  .tab__pin {
29
29
  display: inline-flex; align-items: center; justify-content: center;
30
- width: 1.15rem; height: 1.15rem; border-radius: var(--radius-sm);
31
- color: var(--ink-faint); pointer-events: none;
30
+ width: 1.5rem; height: 1.5rem; /* 24px: the WCAG 2.2 target-size minimum (2.5.8) */ border-radius: var(--radius-sm);
31
+ color: var(--ink-muted); pointer-events: none;
32
32
  }
33
+ /* WCAG 2.4.7: a keyboard user tabbing onto a hidden × must see it, not just a ring round nothing. */
34
+ .tab__close:focus-visible { color: var(--ink-muted); }
@@ -94,7 +94,7 @@
94
94
  .code-editor[data-history="open"] .code-editor__history { transform: translateX(0); }
95
95
  .code-editor__history-head { flex: 0 0 auto; display: flex; align-items: center; gap: var(--space-2);
96
96
  padding: var(--space-2) var(--space-3); border-bottom: 1px solid var(--color-line);
97
- text-transform: uppercase; letter-spacing: 0.06em; font-size: var(--text-xs); color: var(--ink-faint); }
97
+ text-transform: uppercase; letter-spacing: 0.06em; font-size: var(--text-xs); color: var(--ink-muted); }
98
98
  .code-editor__version { display: flex; flex-direction: column; gap: 2px;
99
99
  padding: var(--space-2) var(--space-3); border-bottom: 1px solid var(--color-line); cursor: pointer; }
100
100
  .code-editor__version:hover { background: var(--paper-2); }
@@ -63,8 +63,10 @@
63
63
  .console__prompt { color: var(--color-muted); flex: 0 0 auto; }
64
64
  .console__cmd { flex: 1; min-width: 0; background: transparent; border: 0; padding: 0; margin: 0;
65
65
  color: var(--color-fg); font-family: var(--font-smooth); font-size: var(--text-sm); }
66
- .console__cmd::placeholder { color: var(--ink-faint); }
66
+ .console__cmd::placeholder { color: var(--ink-muted); }
67
67
  .console__cmd:focus { outline: none; }
68
+ /* WCAG 2.4.7 and 1.4.1: a prompt that only changes color is not enough, so the row also takes a ring. */
69
+ .console__input:focus-within { outline: 2px solid var(--color-accent); outline-offset: -2px; }
68
70
  .console__input:focus-within .console__prompt { color: var(--color-accent); }
69
71
 
70
72
  /* the chat's mid-run "thinking" box: a compact indicator + a small LIVE PREVIEW of the terminal
@@ -73,7 +75,7 @@
73
75
  border: 1px dashed var(--ink-faint); border-radius: var(--radius-md); padding: var(--space-2) var(--space-3);
74
76
  background: color-mix(in srgb, var(--ink) 4%, transparent); }
75
77
  .chat-thinking__head { display: flex; align-items: center; justify-content: space-between; margin-bottom: var(--space-1); }
76
- .chat-thinking__who { font-size: var(--text-xs); text-transform: uppercase; letter-spacing: 0.06em; color: var(--ink-faint); }
78
+ .chat-thinking__who { font-size: var(--text-xs); text-transform: uppercase; letter-spacing: 0.06em; color: var(--ink-muted); }
77
79
  /* compact icon button (saves space in the run-time thinking box) */
78
80
  .chat-thinking__toggle { cursor: pointer; font: inherit; color: var(--color-fg);
79
81
  display: inline-flex; align-items: center; justify-content: center; width: 1.5rem; height: 1.5rem; padding: 0;
@@ -24,7 +24,7 @@
24
24
  /* the chevron: one glyph, rotated by state — no per-state art */
25
25
  .file-tree__dir > summary::before {
26
26
  content: "▸"; flex: 0 0 auto; width: 0.9em;
27
- color: var(--ink-faint); font-size: 0.9em;
27
+ color: var(--ink-muted); font-size: 0.9em;
28
28
  transition: transform 0.15s ease;
29
29
  }
30
30
  .file-tree__dir[open] > summary::before { transform: rotate(90deg); }
@@ -47,7 +47,7 @@
47
47
  background: color-mix(in srgb, var(--color-surface) 70%, transparent); }
48
48
  /* an index/entry file (a folder's own page, e.g. index.html) is DIMMED — the directory name
49
49
  above it carries the meaning, so the filename recedes. Hover + current win by later position. */
50
- .file-tree__file[data-variant="index"] { color: var(--ink-faint); }
50
+ .file-tree__file[data-variant="index"] { color: var(--ink-muted); }
51
51
  /* the OPEN file: ink + a quiet accent edge (mirrors the rail's current-item bar) */
52
52
  .file-tree__file[aria-current="page"] {
53
53
  color: var(--color-fg); position: relative;
@@ -69,11 +69,11 @@
69
69
  .file-tree__file:has(.file-tree__close) { display: flex; align-items: center; justify-content: space-between; }
70
70
  .file-tree__close {
71
71
  display: inline-flex; align-items: center; justify-content: center; flex: 0 0 auto;
72
- width: 1.15rem; height: 1.15rem; border-radius: var(--radius-sm);
72
+ width: 1.5rem; height: 1.5rem; /* 24px: the WCAG 2.2 target-size minimum (2.5.8) */ border-radius: var(--radius-sm);
73
73
  color: transparent; pointer-events: none;
74
74
  }
75
75
  .file-tree__file:hover .file-tree__close, .file-tree__file[aria-current="page"] .file-tree__close {
76
- color: var(--ink-faint);
76
+ color: var(--ink-muted);
77
77
  }
78
78
  .file-tree__close:hover { color: var(--color-fg); background: color-mix(in srgb, var(--color-surface) 70%, transparent); }
79
79
 
@@ -83,3 +83,5 @@
83
83
  /* ---- explorer variant of the rail: the icon gutter is the NAV rail's look; a tree brings its
84
84
  own indent guides, so the host drops the gutter line ---- */
85
85
  .side-rail[data-variant="explorer"]::before { display: none; }
86
+ /* WCAG 2.4.7: a keyboard user tabbing onto a hidden × must see it, not just a ring round nothing. */
87
+ .file-tree__close:focus-visible { color: var(--ink-muted); }
@@ -14,7 +14,7 @@
14
14
  .notepad__head { display: flex; align-items: center; gap: var(--space-2); flex: 0 0 auto;
15
15
  padding: var(--space-2) var(--space-3); border-bottom: 1px solid var(--color-line); }
16
16
  .notepad__title { font-family: var(--font-grain); font-size: var(--text-xs); text-transform: uppercase;
17
- letter-spacing: 0.06em; color: var(--ink-faint); margin-right: auto; }
17
+ letter-spacing: 0.06em; color: var(--ink-muted); margin-right: auto; }
18
18
  .notepad__toggle, .notepad__commit { cursor: pointer; font: inherit; font-size: var(--text-xs);
19
19
  color: var(--color-fg); background: transparent; border: 1px solid var(--color-line);
20
20
  border-radius: var(--radius-sm); padding: 2px var(--space-2); }
@@ -37,7 +37,7 @@
37
37
  .notepad__body { display: flex; flex-direction: column; gap: var(--space-3); }
38
38
  .notepad__body:empty::after,
39
39
  .notepad__body:not(:has(.notepad__entry))::after {
40
- content: "Nothing noted yet."; color: var(--ink-faint); font-style: italic; }
40
+ content: "Nothing noted yet."; color: var(--ink-muted); font-style: italic; }
41
41
  /* min-width:0 lets the entry shrink below its content's intrinsic width (a flex child won't by
42
42
  default), and overflow-wrap breaks a long unbroken token instead of forcing the whole pane wide —
43
43
  together they stop a long AI line or pasted URL from giving the panel a horizontal scrollbar. */
@@ -59,6 +59,8 @@
59
59
  .notepad__source { display: block; width: 100%; resize: none; box-sizing: border-box;
60
60
  background: var(--color-bg); border: 0; outline: none;
61
61
  color: var(--color-fg); font-family: var(--font-grain); font-size: var(--text-sm); line-height: 1.6; }
62
- .notepad__source::placeholder { color: var(--ink-faint); }
62
+ /* WCAG 2.4.7: the borderless source still owes a visible focus ring when reached by keyboard. */
63
+ .notepad__source:focus-visible { outline: 2px solid var(--color-accent); outline-offset: -2px; }
64
+ .notepad__source::placeholder { color: var(--ink-muted); }
63
65
 
64
66
  @media (prefers-reduced-motion: reduce) { .notepad__body, .notepad__source { scroll-behavior: auto; } }
@@ -134,15 +134,22 @@
134
134
 
135
135
  .presentation__dots {
136
136
  position: absolute; left: calc(var(--u) * 11.7); bottom: calc(var(--u) * 3.4);
137
- display: flex; gap: calc(var(--u) * 0.85); align-items: center;
137
+ display: flex; gap: 0; align-items: center;
138
+ margin-left: calc((24px - var(--u) * 0.62) / -2); /* the first dot still lines up with the text */
138
139
  }
140
+ /* WCAG 2.5.8: the button is a 24px target and the dot is drawn inside it, so the row looks the
141
+ same and every dot is still easy to hit. The dot is a control, so it uses muted ink (1.4.11). */
139
142
  .presentation__dot {
140
- width: calc(var(--u) * 0.62); height: calc(var(--u) * 0.62); border-radius: 50%;
141
- background: var(--ink-faint); border: 0; padding: 0; cursor: pointer;
143
+ display: grid; place-items: center; width: max(24px, calc(var(--u) * 1.47)); height: 24px;
144
+ background: transparent; border: 0; padding: 0; cursor: pointer; border-radius: 50%;
145
+ }
146
+ .presentation__dot::before {
147
+ content: ""; width: calc(var(--u) * 0.62); height: calc(var(--u) * 0.62); border-radius: 50%;
148
+ background: transparent; box-shadow: inset 0 0 0 1.5px var(--ink-muted); /* unseen: a ring */
142
149
  transition: transform 0.24s ease, background 0.24s ease;
143
150
  }
144
- .presentation__dot[data-seen] { background: var(--color-muted); }
145
- .presentation__dot[data-now] { background: var(--color-accent); transform: scale(1.9); }
151
+ .presentation__dot[data-seen]::before { background: var(--color-muted); }
152
+ .presentation__dot[data-now]::before { background: var(--color-accent); transform: scale(1.9); }
146
153
  .presentation__dot:focus-visible { outline: 2px solid var(--color-accent); outline-offset: 3px; }
147
154
 
148
155
 
@@ -157,7 +164,7 @@
157
164
  z-index: 1;
158
165
  }
159
166
  .presentation__meta, .presentation__hint, .presentation__legend {
160
- margin: 0; font-size: calc(var(--u) * 1.4); color: var(--ink-faint);
167
+ margin: 0; font-size: calc(var(--u) * 1.4); color: var(--ink-muted);
161
168
  display: flex; gap: calc(var(--u) * 2.2); align-items: baseline; min-width: 0;
162
169
  }
163
170
  .presentation__hint { overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
@@ -242,7 +249,7 @@
242
249
  .presenter__next h3 { font-size: 0.95rem; letter-spacing: 0.12em; text-transform: uppercase;
243
250
  color: var(--color-muted); margin: 0 0 var(--space-2); }
244
251
  .presenter__next p { color: var(--color-muted); }
245
- .presenter__hint { grid-column: 1 / -1; margin: 0; font-size: 0.85rem; color: var(--ink-faint);
252
+ .presenter__hint { grid-column: 1 / -1; margin: 0; font-size: 0.85rem; color: var(--ink-muted);
246
253
  letter-spacing: 0.08em; text-transform: uppercase; }
247
254
 
248
255
 
@@ -30,7 +30,7 @@
30
30
  .assistant__composer { border-top: 1px solid var(--color-line); padding: var(--space-3); display: flex; gap: var(--space-2); }
31
31
  .assistant__composer .field__input { flex: 1; font: inherit; font-size: var(--text-sm); color: var(--color-fg);
32
32
  background: var(--color-bg); border: 1px solid var(--color-line); border-radius: var(--radius-md); padding: var(--space-2) var(--space-3); }
33
- .assistant__composer .field__input::placeholder { color: var(--ink-faint); }
33
+ .assistant__composer .field__input::placeholder { color: var(--ink-muted); }
34
34
 
35
35
  /* TAKEOVER: the shell raises `data-acting` (grain/scripts/ai-dispatch.js). The terminal (console)
36
36
  narrates the AI's THINKING; the chat is for COMMUNICATION — the two are separate concerns and
@@ -67,3 +67,9 @@
67
67
  .app-shell__aside { transition: none; }
68
68
  .assistant__log { scroll-behavior: auto; }
69
69
  }
70
+
71
+ /* WCAG 2.4.11 (focus not obscured): the collapsed sheet peeks over the page bottom on a narrow
72
+ frame, so the page's scrollers keep a focused element clear of that strip. */
73
+ @container shell-frame (max-width: 768px) {
74
+ .app-shell__main { scroll-padding-bottom: 3.75rem; }
75
+ }
@@ -36,10 +36,10 @@ untouched.
36
36
  ```html
37
37
  <div class="assistant" data-mode="chat">
38
38
  <div class="assistant__head"><span>Assistant</span>
39
- <nav class="assistant__modes" aria-label="Panel mode">
40
- <button type="button" data-shell-mode="chat" aria-selected="true">Chat</button>
41
- <button type="button" data-shell-mode="catalog" aria-selected="false">Catalog</button>
42
- </nav>
39
+ <div class="assistant__modes" role="tablist" aria-label="Panel mode">
40
+ <button type="button" role="tab" data-shell-mode="chat" aria-selected="true">Chat</button>
41
+ <button type="button" role="tab" data-shell-mode="catalog" aria-selected="false">Catalog</button>
42
+ </div>
43
43
  </div>
44
44
  <div class="assistant__pane" data-pane="chat">…log + composer…</div>
45
45
  <div class="assistant__pane" data-pane="catalog" hidden>…anything…</div>
@@ -23,7 +23,7 @@
23
23
  display: flex; flex-direction: column; gap: var(--space-1);
24
24
  flex: 0 1 auto; min-height: 0; max-height: 18rem; overflow: auto; scroll-behavior: smooth; }
25
25
  .timeline__feed:empty::after { content: "No crossings yet — ask the AI, or watch it act.";
26
- color: var(--ink-faint); font-family: var(--font-grain); font-size: var(--text-sm); padding: var(--space-2); }
26
+ color: var(--ink-muted); font-family: var(--font-grain); font-size: var(--text-sm); padding: var(--space-2); }
27
27
 
28
28
  /* one crossing. The left edge carries the provenance; the row reads verb + detail. */
29
29
  .timeline__entry { display: flex; align-items: baseline; gap: var(--space-2);
@@ -33,10 +33,12 @@ caps the DOM at 80 rows. CSS-only (no `.html`).
33
33
  Each `log` op appends one row (built by `timelineEntryHtml`):
34
34
 
35
35
  ```html
36
+ <ol class="timeline__feed">
36
37
  <li class="timeline__entry" data-provenance="ai" data-kind="response" data-seq="4">
37
38
  <span class="timeline__who">ai</span>
38
39
  <span class="timeline__mark">✓</span>
39
40
  <span class="timeline__verb">chat.send</span>
40
41
  <span class="timeline__detail">2 ops</span>
41
42
  </li>
43
+ </ol>
42
44
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tjakoen/grain",
3
- "version": "0.1.27",
3
+ "version": "0.1.29",
4
4
  "description": "GRAIN — an AI-interaction design system where every surface is operable by both a human and an AI through one shared vocabulary.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -10,8 +10,10 @@
10
10
  // open/close hooks, the lazy iframe load (base, unconditional), and the hover/tap bridge (enhanced,
11
11
  // gated on the demo root existing).
12
12
  //
13
- // It maps each rendered CSS class to its catalog section slug (the .md title slug — stable for
14
- // grain's components). The catalog exposes a "single" mode (data-peek-single + .is-peek-active,
13
+ // It maps each rendered CSS class to its catalog section slug. The lookup is read from the loaded
14
+ // catalog itself: a class matches an entry whose slug equals it, or whose title does once a
15
+ // trailing "(source)" is dropped, which is how a consumer's own components ("cv-entry (portfolio)")
16
+ // get found. The hand MAP below only holds the aliases where the class and the slug differ. The catalog exposes a "single" mode (data-peek-single + .is-peek-active,
15
17
  // driven here via window.__catSetActive). The bridge adapts to the pointer: with a HOVERING
16
18
  // pointer it's a hover-reveal in single mode (one entry at a time, cross-fading). On a COARSE
17
19
  // pointer (touch, no hover) a finger can't hover, so the same usage→specimen link becomes a TAP:
@@ -34,10 +36,12 @@
34
36
  // on touch it would be undrivable, so there we leave the full scrollable catalog.
35
37
  const canHover = matchMedia("(hover: hover) and (pointer: fine)").matches;
36
38
 
37
- // rendered CSS class → catalog slug. A hand-maintained BRIDGE (the rendered class often differs
38
- // from the slug: "icon-btn" → "icon-button", "field" → "input"), so keep it in sync when a
39
- // component's class or title changes. A drift test (catalog-peek.test.ts) fails if a slug here
40
- // stops matching a real component. Innermost match wins (hover the glyph → Icon; the row → Nav item).
39
+ // ALIASES: rendered CSS class → catalog slug, only where the two differ ("icon-btn" →
40
+ // "icon-button", "field" → "input"). Every other class resolves through the index built from the
41
+ // loaded catalog (indexCatalog below), so a new component reveals on hover with no edit here.
42
+ // Identity rows are kept so the bridge still works in the moment before the catalog loads. A
43
+ // drift test (catalog-peek.test.ts) fails if a slug here stops matching a real component.
44
+ // Innermost match wins (hover the glyph → Icon; the row → Nav item).
41
45
  const MAP = {
42
46
  "action-badge": "action-badge", "icon-btn": "icon-button", "nav-item": "nav-item",
43
47
  "tab-bar": "tab-bar", "side-rail": "side-rail", "app-shell": "app-shell",
@@ -46,6 +50,28 @@
46
50
  "icon": "icon", "t": "typography",
47
51
  };
48
52
 
53
+ // class → slug, filled from the embedded catalog's own entries once it loads.
54
+ const INDEX = new Map();
55
+ const titleKey = (t) => t.replace(/\s*\([^)]*\)\s*$/, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
56
+ function indexCatalog(doc) {
57
+ for (const d of doc.querySelectorAll(".cat-doc[id]")) {
58
+ if (!INDEX.has(d.id)) INDEX.set(d.id, d.id);
59
+ const h = d.querySelector("h1, h2");
60
+ const key = h && titleKey(h.textContent || "");
61
+ if (key && !INDEX.has(key)) INDEX.set(key, d.id);
62
+ }
63
+ }
64
+ // the slug for one element, or null: an alias first, then the catalog's own index
65
+ const slugFor = (el) => {
66
+ if (!el.classList) return null;
67
+ for (const cls of el.classList) {
68
+ if (Object.prototype.hasOwnProperty.call(MAP, cls)) return MAP[cls];
69
+ const hit = INDEX.get(cls);
70
+ if (hit) return hit;
71
+ }
72
+ return null;
73
+ };
74
+
49
75
  const isOpen = () => !pane.hidden;
50
76
  // open/close = switch the sidebar-panel's mode — REUSE the shell's one mechanic (click its mode
51
77
  // tab; shell.js flips data-mode/hidden/aria-selected), never a parallel show/hide path. On the
@@ -74,6 +100,7 @@
74
100
  // on touch we skip single mode and leave the full scrollable catalog.
75
101
  frame.addEventListener("load", () => {
76
102
  // touch: no single mode — honour a tap that fired before the frame finished loading.
103
+ try { if (frame.contentDocument) indexCatalog(frame.contentDocument); } catch { /* cross-origin — aliases only */ }
77
104
  if (!canHover) { if (pendingTouch) { scrollToInFrame(pendingTouch); pendingTouch = null; } return; }
78
105
  try {
79
106
  const doc = frame.contentDocument;
@@ -119,7 +146,8 @@
119
146
  if (!canHover || !isOpen()) return;
120
147
  let el = e.target;
121
148
  while (el && el !== demo) {
122
- if (el.classList) for (const cls in MAP) if (el.classList.contains(cls)) { peek(MAP[cls]); return; }
149
+ const slug = slugFor(el);
150
+ if (slug) { peek(slug); return; }
123
151
  el = el.parentElement;
124
152
  }
125
153
  // No component under the pointer → HOLD the current reveal (don't switch on prose/gaps). This
@@ -144,7 +172,7 @@
144
172
  if (e.target.closest("a,button,input,textarea,select,label,[data-action],[data-peek]")) return;
145
173
  let el = e.target, slug = null;
146
174
  while (el && el !== demo && !slug) {
147
- if (el.classList) for (const cls in MAP) if (el.classList.contains(cls)) { slug = MAP[cls]; break; }
175
+ slug = slugFor(el);
148
176
  el = el.parentElement;
149
177
  }
150
178
  if (!slug) return;
package/scripts/theme.js CHANGED
@@ -85,3 +85,41 @@
85
85
  window.grain = window.grain || {};
86
86
  window.grain.theme = { setScheme, setTheme, toggleScheme, cycleTheme, scheme, theme, themes };
87
87
  })();
88
+
89
+ // Keyboard reach for scrolling regions (WCAG 2.1.1). Any GRAIN surface that scrolls (a wide
90
+ // table, a code block, the tab strip, a notepad body) must be scrollable without a mouse. Most
91
+ // already hold a link or a button that takes focus and scrolls them; the ones that hold only text
92
+ // get tabindex="0" here, so the guarantee lives in the system rather than in every component's
93
+ // markup. It lives in theme.js because every GRAIN page loads it. An element that already has a
94
+ // tabindex, or holds anything focusable, is left exactly as it is.
95
+ (function () {
96
+ const FOCUSABLE = 'a[href], button, input, select, textarea, [tabindex], [contenteditable="true"]';
97
+ const scrolls = (el) => {
98
+ const s = getComputedStyle(el);
99
+ const x = /(auto|scroll)/.test(s.overflowX) && el.scrollWidth > el.clientWidth + 1;
100
+ const y = /(auto|scroll)/.test(s.overflowY) && el.scrollHeight > el.clientHeight + 1;
101
+ return x || y;
102
+ };
103
+ const check = (el) => {
104
+ if (el.hasAttribute("tabindex") || !scrolls(el) || el.querySelector(FOCUSABLE)) return;
105
+ el.setAttribute("tabindex", "0");
106
+ el.setAttribute("data-grain-scroll-focus", "");
107
+ };
108
+ const sweep = (root) => { check(root); for (const el of root.querySelectorAll("*")) check(el); };
109
+ // Later passes look only at what was added, and only when the page is idle: a full rescan on
110
+ // every change measured as a hang on pages whose live effects never stop mutating.
111
+ const idle = window.requestIdleCallback || ((fn) => setTimeout(fn, 200));
112
+ let pending = new Set(), queued = false;
113
+ const flush = () => { queued = false; const roots = pending; pending = new Set();
114
+ for (const r of roots) if (r.isConnected) sweep(r); };
115
+ const start = () => {
116
+ sweep(document.body);
117
+ new MutationObserver((records) => {
118
+ for (const m of records) for (const n of m.addedNodes) if (n.nodeType === 1) pending.add(n);
119
+ if (pending.size && !queued) { queued = true; idle(flush); }
120
+ }).observe(document.body, { childList: true, subtree: true });
121
+ addEventListener("resize", () => { pending.add(document.body); if (!queued) { queued = true; idle(flush); } });
122
+ };
123
+ if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", start);
124
+ else start();
125
+ })();
package/styles/cmdk.css CHANGED
@@ -44,7 +44,7 @@
44
44
  /* no outline:none — the input is the palette's focused control; it takes the global
45
45
  :focus-visible accent ring (global.css) so keyboard focus is visible on open. */
46
46
  }
47
- .cmdk__input::placeholder { color: var(--ink-faint); }
47
+ .cmdk__input::placeholder { color: var(--ink-muted); }
48
48
 
49
49
  .cmdk__list { list-style: none; margin: 0; padding: .25rem; max-height: 52vh; overflow: auto; }
50
50
  .cmdk__item { display: flex; align-items: baseline; gap: .6rem; padding: .5rem .75rem; border-radius: 2px; cursor: pointer; }
@@ -55,7 +55,7 @@
55
55
 
56
56
  .cmdk__sub { color: var(--color-muted); font-size: .85em; }
57
57
 
58
- .cmdk__kind { margin-left: auto; font-size: .7rem; text-transform: uppercase; letter-spacing: .08em; color: var(--ink-faint); }
58
+ .cmdk__kind { margin-left: auto; font-size: .7rem; text-transform: uppercase; letter-spacing: .08em; color: var(--ink-muted); }
59
59
 
60
60
  .cmdk__empty { padding: .75rem 1rem; color: var(--color-muted); }
61
61
 
@@ -23,7 +23,7 @@
23
23
  --paper: #FFFFFF; --paper-2: #F2F2F0; --panel: #FFFFFF;
24
24
  --ink: #1A1A1A; --ink-muted: #6B6B70; --ink-faint: #A6A6AB;
25
25
  --hairline: #1A1A1A; --line-soft: rgba(26, 26, 26, 0.11);
26
- --color-accent: #2F6FE0; --color-accent-hover: #2559C0; /* the ONE signature hue */
26
+ --color-accent: #2C68D6; --color-accent-hover: #2559C0; /* the ONE signature hue */
27
27
  --color-accent-contrast: #FFFFFF; --color-accent-soft: #E7EEFB;
28
28
  }
29
29
  /* ---- dark: the @media block follows the OS unless the user forced light ---- */
@@ -7,7 +7,7 @@
7
7
  --paper: #FAFAF8; --paper-2: #F2F2F0; --panel: #FFFFFF;
8
8
  --ink: #232326; --ink-muted: #6B6B70; --ink-faint: #A6A6AB;
9
9
  --hairline: #232326; --line-soft: rgba(35, 35, 38, 0.11);
10
- --color-accent: #2F6FE0; --color-accent-hover: #2559C0;
10
+ --color-accent: #2C68D6; --color-accent-hover: #2559C0;
11
11
  --color-accent-contrast: #FFFFFF; --color-accent-soft: #E7EEFB;
12
12
  }
13
13
  @media (prefers-color-scheme: dark) {
@@ -7,7 +7,7 @@
7
7
  --paper: #F5EEDD; --paper-2: #FBF5E7; --panel: #FFFDF6;
8
8
  --ink: #2C2416; --ink-muted: #6E6249; --ink-faint: #B9AC8E;
9
9
  --hairline: #2C2416; --line-soft: rgba(44, 36, 22, 0.14);
10
- --color-accent: #B77F1E; --color-accent-hover: #9A6A16;
10
+ --color-accent: #8A5E12; --color-accent-hover: #7A520F;
11
11
  --color-accent-contrast: #FFFFFF; --color-accent-soft: #F3E7CC;
12
12
  }
13
13
  @media (prefers-color-scheme: dark) {
@@ -47,7 +47,7 @@
47
47
  3.98:1, which is why it moved. FAINT is decoration: fading insights, empty and future dots. It
48
48
  does NOT clear AA and is not meant to, so nothing a reader needs may be painted with it. */
49
49
  --ink-muted: #65635B; /* secondary text, section labels. 4.55:1 on --paper */
50
- --ink-faint: #ABA89F; /* fading insights, empty/future dots. DECORATIVE ONLY */
50
+ --ink-faint: #ABA89F; /* fading insights, empty/future dots. DECORATIVE ONLY: never text, never a control (WCAG 1.4.3, 1.4.11) */
51
51
  --hairline: #1C1B17; /* solid rules (under headlines) */
52
52
  --line-soft: rgba(28, 27, 23, .14); /* translucent border for quiet grouping */
53
53