@tjakoen/grain 0.1.32 → 0.1.34
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/atoms/b-button/b-button.css +1 -1
- 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/organisms/app-shell/app-shell.css +2 -2
- package/components/organisms/app-shell/app-shell.md +9 -1
- package/components/organisms/app-shell/app-shell.test.ts +22 -3
- package/components/organisms/app-window/app-window.css +2 -2
- package/components/organisms/note/note.css +1 -2
- package/components/organisms/note/note.md +2 -2
- package/components/organisms/presentation/presentation.css +2 -1
- package/components/organisms/sidebar-panel/sidebar-panel.css +3 -3
- package/components/organisms/status-bar/status-bar.css +1 -1
- package/package.json +3 -2
- package/scripts/catalog-peek.js +1 -1
- package/scripts/cmdk.js +1 -1
- package/scripts/fixtures/grain-lint/accent-word.fail.html +28 -0
- package/scripts/fixtures/grain-lint/card-run.fail.html +34 -0
- package/scripts/fixtures/grain-lint/clean.html +32 -0
- package/scripts/fixtures/grain-lint/closing-signup.fail.html +29 -0
- package/scripts/fixtures/grain-lint/contrast-aa.fail.html +29 -0
- package/scripts/fixtures/grain-lint/dead-form.fail.html +28 -0
- package/scripts/fixtures/grain-lint/focus-visible.fail.html +29 -0
- package/scripts/fixtures/grain-lint/heading-widow.fail.html +29 -0
- package/scripts/fixtures/grain-lint/hero-overflow.fail.html +29 -0
- package/scripts/fixtures/grain-lint/image-ratio.fail.html +28 -0
- package/scripts/fixtures/grain-lint/label-above-heading.fail.html +31 -0
- package/scripts/fixtures/grain-lint/off-scale-space.fail.html +29 -0
- package/scripts/fixtures/grain-lint/phone-overflow.fail.html +29 -0
- package/scripts/fixtures/grain-lint/raw-color.fail.html +29 -0
- package/scripts/fixtures/grain-lint/reduced-motion.fail.html +30 -0
- package/scripts/fixtures/grain-lint/text-above-h1.allowed.html +28 -0
- package/scripts/fixtures/grain-lint/text-above-h1.fail.html +28 -0
- package/scripts/fixtures/grain-lint/tracked-caps.fail.html +29 -0
- package/scripts/grain-lint-rules.ts +524 -0
- package/scripts/grain-lint.test.ts +77 -0
- package/scripts/grain-lint.ts +179 -0
- package/scripts/shell.js +3 -3
- package/styles/global.css +4 -3
- package/styles/variables.css +8 -0
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# Dash panel
|
|
2
|
+
|
|
3
|
+
The surface one chart, table or ranked list sits on inside a dashboard. It has a title, an
|
|
4
|
+
optional action on the same line, and a state. A panel is never just a box: it is ready, loading,
|
|
5
|
+
empty, stale or failed, and it says which in a word a reader can act on.
|
|
6
|
+
|
|
7
|
+
Loading reuses the shared in-transit idiom, data-commit="pending", the same dashed edge a stat tile
|
|
8
|
+
or a button wears while the AI is writing it. Empty says what to do next rather than "No data".
|
|
9
|
+
Stale says when the numbers were last true. Failed says what to try.
|
|
10
|
+
|
|
11
|
+
## States
|
|
12
|
+
|
|
13
|
+
### Ready
|
|
14
|
+
|
|
15
|
+
```html
|
|
16
|
+
<section class="dash-panel" data-surface="panel:signups">
|
|
17
|
+
<header class="dash-panel__head">
|
|
18
|
+
<h3 class="dash-panel__title">Signups</h3>
|
|
19
|
+
<a class="dash-panel__action" href="#signups">Open report</a>
|
|
20
|
+
</header>
|
|
21
|
+
<p class="dash-panel__note">312 this week</p>
|
|
22
|
+
</section>
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
### Loading
|
|
26
|
+
|
|
27
|
+
```html
|
|
28
|
+
<section class="dash-panel" data-commit="pending" aria-busy="true" data-surface="panel:signups">
|
|
29
|
+
<header class="dash-panel__head"><h3 class="dash-panel__title">Signups</h3></header>
|
|
30
|
+
<p class="dash-panel__note">Loading this week</p>
|
|
31
|
+
</section>
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### Empty
|
|
35
|
+
|
|
36
|
+
```html
|
|
37
|
+
<section class="dash-panel" data-state="empty" data-surface="panel:refunds">
|
|
38
|
+
<header class="dash-panel__head"><h3 class="dash-panel__title">Refunds</h3></header>
|
|
39
|
+
<p class="dash-panel__note">None this period. Refunds appear here as soon as one is issued.</p>
|
|
40
|
+
</section>
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### Stale
|
|
44
|
+
|
|
45
|
+
```html
|
|
46
|
+
<section class="dash-panel" data-state="stale" data-surface="panel:traffic">
|
|
47
|
+
<header class="dash-panel__head"><h3 class="dash-panel__title">Traffic</h3></header>
|
|
48
|
+
<p class="dash-panel__note">Last updated 09:40, the feed has not answered since</p>
|
|
49
|
+
</section>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
```controls
|
|
53
|
+
select data-state = - | empty | stale | error
|
|
54
|
+
toggle data-commit = pending
|
|
55
|
+
text .dash-panel__title = Signups
|
|
56
|
+
text .dash-panel__note = 312 this week
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Accessibility
|
|
60
|
+
|
|
61
|
+
A loading panel sets aria-busy so assistive technology waits for the content instead of reading a
|
|
62
|
+
half-drawn panel. The state is always written as text in the note, never carried by the border
|
|
63
|
+
alone; the border is a second cue for sighted readers, not the only one.
|
|
64
|
+
|
|
65
|
+
The action is a real link or button with a specific label ("Open report"), never "More" or an icon
|
|
66
|
+
on its own.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/* dashboards/dashboard — the page a dashboard sits on: a head that states the period and what the
|
|
2
|
+
numbers compare against, a KPI strip that ADDS columns as the screen widens (no narrow column
|
|
3
|
+
floating on a wide monitor), and a panel grid where a panel spans one, two or every column.
|
|
4
|
+
One column on a phone. Layout only: no colour of its own, so it follows both theme axes. */
|
|
5
|
+
.dash { display: grid; gap: var(--space-6); container-type: inline-size; min-inline-size: 0; }
|
|
6
|
+
.dash__head { display: flex; flex-wrap: wrap; align-items: baseline; justify-content: space-between;
|
|
7
|
+
gap: var(--space-2) var(--space-4); padding-bottom: var(--space-3); border-bottom: var(--border); }
|
|
8
|
+
.dash__title { margin: 0; font-size: var(--text-xl); font-weight: var(--font-weight-semibold);
|
|
9
|
+
line-height: var(--leading-tight); color: var(--ink); }
|
|
10
|
+
.dash__period { margin: 0; font-size: var(--text-sm); color: var(--color-muted); }
|
|
11
|
+
.dash__kpis { display: grid; gap: var(--space-3);
|
|
12
|
+
grid-template-columns: repeat(auto-fit, minmax(min(100%, 11rem), 1fr)); }
|
|
13
|
+
.dash__grid { display: grid; gap: var(--space-4); grid-template-columns: repeat(var(--dash-cols, 1), minmax(0, 1fr)); }
|
|
14
|
+
.dash__grid > * { min-inline-size: 0; }
|
|
15
|
+
@container (min-width: 40rem) { .dash__grid { --dash-cols: 2; } }
|
|
16
|
+
@container (min-width: 72rem) { .dash__grid { --dash-cols: 3; } }
|
|
17
|
+
@container (min-width: 120rem) { .dash__grid { --dash-cols: 4; } }
|
|
18
|
+
.dash__grid > [data-span="2"] { grid-column: span min(2, var(--dash-cols, 1)); }
|
|
19
|
+
.dash__grid > [data-span="full"] { grid-column: 1 / -1; }
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Dashboard
|
|
2
|
+
|
|
3
|
+
The page a dashboard sits on. A head names the dashboard, the period and what every delta on the
|
|
4
|
+
page compares against, so a reader never has to guess the baseline. Below it, a strip of stat tiles
|
|
5
|
+
that adds columns as the screen grows, then a grid of panels that runs one column on a phone, two on
|
|
6
|
+
a tablet, three on a desktop and four on an ultrawide.
|
|
7
|
+
|
|
8
|
+
The layout queries its own width, not the viewport's, so a dashboard inside a sidebar or a catalog
|
|
9
|
+
panel lays itself out for the room it actually has. A panel spans two columns with data-span="2"
|
|
10
|
+
and the whole row with data-span="full".
|
|
11
|
+
|
|
12
|
+
Stat tiles, trend charts and data tables are the existing molecules; this layer composes them and
|
|
13
|
+
adds the dash panel, the delta, the bullet graph and the rank list. Every tile and panel carries a
|
|
14
|
+
data-surface slug so a tour, a lamp or the reasoner can point at one number rather than at the page.
|
|
15
|
+
|
|
16
|
+
## Overview
|
|
17
|
+
|
|
18
|
+
### A dashboard with a KPI strip and three panels
|
|
19
|
+
|
|
20
|
+
```html
|
|
21
|
+
<div class="dash" data-surface="dashboard:sales">
|
|
22
|
+
<header class="dash__head">
|
|
23
|
+
<h2 class="dash__title">Sales</h2>
|
|
24
|
+
<p class="dash__period">1 to 14 November, compared with the two weeks before</p>
|
|
25
|
+
</header>
|
|
26
|
+
<div class="dash__kpis">
|
|
27
|
+
<div class="stat" data-surface="stat:revenue">
|
|
28
|
+
<span class="stat__value">€48.2k</span>
|
|
29
|
+
<span class="stat__label">Revenue</span>
|
|
30
|
+
<span class="delta" data-dir="up"><span class="delta__glyph" aria-hidden="true">▲</span> 12% <span class="delta__base">vs prior</span></span>
|
|
31
|
+
</div>
|
|
32
|
+
<div class="stat" data-surface="stat:orders">
|
|
33
|
+
<span class="stat__value">1,204</span>
|
|
34
|
+
<span class="stat__label">Orders</span>
|
|
35
|
+
<span class="delta" data-dir="down"><span class="delta__glyph" aria-hidden="true">▼</span> 3% <span class="delta__base">vs prior</span></span>
|
|
36
|
+
</div>
|
|
37
|
+
<div class="stat" data-surface="stat:refunds">
|
|
38
|
+
<span class="stat__value">0</span>
|
|
39
|
+
<span class="stat__label">Refunds</span>
|
|
40
|
+
<span class="delta" data-dir="flat" data-small-base><span class="delta__base">was 1</span></span>
|
|
41
|
+
</div>
|
|
42
|
+
</div>
|
|
43
|
+
<div class="dash__grid">
|
|
44
|
+
<section class="dash-panel" data-span="2" data-surface="panel:revenue-by-source">
|
|
45
|
+
<header class="dash-panel__head"><h3 class="dash-panel__title">Revenue by source</h3></header>
|
|
46
|
+
<ol class="rank-list">
|
|
47
|
+
<li class="rank-list__row" style="--share: 0.52"><span class="rank-list__name">Direct</span><span class="rank-list__value">€25.1k</span></li>
|
|
48
|
+
<li class="rank-list__row" style="--share: 0.31"><span class="rank-list__name">Search</span><span class="rank-list__value">€14.9k</span></li>
|
|
49
|
+
<li class="rank-list__row" style="--share: 0.17"><span class="rank-list__name">Referral</span><span class="rank-list__value">€8.2k</span></li>
|
|
50
|
+
</ol>
|
|
51
|
+
</section>
|
|
52
|
+
<section class="dash-panel" data-surface="panel:target">
|
|
53
|
+
<header class="dash-panel__head"><h3 class="dash-panel__title">Monthly target</h3></header>
|
|
54
|
+
<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">
|
|
55
|
+
<span class="bullet__bar"></span><span class="bullet__target"></span>
|
|
56
|
+
</div>
|
|
57
|
+
<p class="bullet__legend">€48.2k of €60k</p>
|
|
58
|
+
</section>
|
|
59
|
+
</div>
|
|
60
|
+
</div>
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Accessibility
|
|
64
|
+
|
|
65
|
+
The head is a real heading, and each panel title is the next level down, so a screen reader's
|
|
66
|
+
heading list reads as the dashboard's table of contents. The period line is plain text rather than
|
|
67
|
+
a tooltip, because it is the one sentence a reader must not miss.
|
|
68
|
+
|
|
69
|
+
Tiles read in source order, left to right and then down; the grid never reorders them visually, so
|
|
70
|
+
keyboard and reading order match what is on screen. The layout has no motion.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
// grain/components/dashboards/dashboards.test.ts — holds the dashboards layer to its own rules
|
|
2
|
+
// (plans/dashboard-layer.md): every component ships a doc and a stylesheet, every doc has an
|
|
3
|
+
// Accessibility section and addresses its examples through data-surface, no stylesheet reaches for
|
|
4
|
+
// a raw colour or tracked capitals, and every class an example uses is one the layer defines.
|
|
5
|
+
import { test, expect } from "bun:test";
|
|
6
|
+
import { readdirSync, readFileSync, existsSync } from "node:fs";
|
|
7
|
+
import { join } from "node:path";
|
|
8
|
+
|
|
9
|
+
const root = import.meta.dir;
|
|
10
|
+
const names = readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
|
|
11
|
+
const md = (n: string) => readFileSync(join(root, n, `${n}.md`), "utf8");
|
|
12
|
+
const css = (n: string) => readFileSync(join(root, n, `${n}.css`), "utf8");
|
|
13
|
+
|
|
14
|
+
test("the layer holds the five components", () => {
|
|
15
|
+
expect(names.sort()).toEqual(["bullet-graph", "dash-panel", "dashboard", "delta", "rank-list"]);
|
|
16
|
+
for (const n of names) { expect(existsSync(join(root, n, `${n}.md`))).toBe(true); expect(existsSync(join(root, n, `${n}.css`))).toBe(true); }
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
test("every doc carries an Accessibility section and a data-surface address", () => {
|
|
20
|
+
for (const n of names) {
|
|
21
|
+
expect(md(n)).toMatch(/^## Accessibility$/m);
|
|
22
|
+
expect(md(n)).toContain("data-surface=");
|
|
23
|
+
}
|
|
24
|
+
});
|
|
25
|
+
|
|
26
|
+
test("no stylesheet hardcodes a colour or tracks its capitals", () => {
|
|
27
|
+
for (const n of names) {
|
|
28
|
+
const src = css(n);
|
|
29
|
+
expect(src).not.toMatch(/#[0-9a-fA-F]{3,8}\b|\b(rgb|hsl)a?\(/);
|
|
30
|
+
expect(src).not.toMatch(/text-transform:\s*uppercase|letter-spacing/);
|
|
31
|
+
}
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
test("every dashboard-layer class an example uses is defined in the layer", () => {
|
|
35
|
+
const defined = new Set(names.flatMap((n) => [...css(n).matchAll(/\.([a-z][a-z0-9_-]*)/g)].map((m) => m[1])));
|
|
36
|
+
const prefixes = ["dash", "dash-panel", "delta", "bullet", "rank-list"];
|
|
37
|
+
for (const n of names) for (const m of md(n).matchAll(/class="([^"]+)"/g))
|
|
38
|
+
for (const cls of m[1].split(/\s+/))
|
|
39
|
+
if (prefixes.some((p) => cls === p || cls.startsWith(`${p}__`))) expect(defined.has(cls)).toBe(true);
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
test("no example colours a delta by direction", () => {
|
|
43
|
+
expect(css("delta")).not.toMatch(/--color-(danger|success)/);
|
|
44
|
+
});
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/* dashboards/delta — the change beside a number: a direction glyph, the change, a one-word
|
|
2
|
+
baseline. Monochrome: direction is the glyph and the words, never red or green, because whether
|
|
3
|
+
"up" is good depends on the measure and GRAIN assigns no meaning to direction. A delta on a
|
|
4
|
+
base too small for a percentage to be honest says "was 1" in a quiet tone instead. */
|
|
5
|
+
.delta { display: inline-flex; align-items: baseline; gap: var(--space-1); font-size: var(--text-xs);
|
|
6
|
+
font-weight: var(--font-weight-medium); color: var(--ink); font-variant-numeric: tabular-nums; }
|
|
7
|
+
.delta__glyph { font-size: 0.8em; }
|
|
8
|
+
.delta__base { font-weight: var(--font-weight-regular); color: var(--color-muted); }
|
|
9
|
+
.delta[data-dir="flat"], .delta[data-small-base] { color: var(--color-muted); }
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Delta
|
|
2
|
+
|
|
3
|
+
The change beside a number: a direction glyph, the size of the change, and a one-word baseline such
|
|
4
|
+
as "vs prior". The baseline sits on the tile and the full sentence, if one is needed, lives in the
|
|
5
|
+
dashboard head, so a tile never grows a paragraph under its number.
|
|
6
|
+
|
|
7
|
+
A delta never colours itself red or green. Whether up is good depends on the measure (revenue up is
|
|
8
|
+
good, churn up is not), and the component cannot know which, so direction is carried by the glyph
|
|
9
|
+
and the words. When the base is too small for a percentage to mean anything, write "was 1" with
|
|
10
|
+
data-small-base instead of a loud minus 100 percent.
|
|
11
|
+
|
|
12
|
+
## Directions
|
|
13
|
+
|
|
14
|
+
### Up
|
|
15
|
+
|
|
16
|
+
```html
|
|
17
|
+
<span class="delta" data-dir="up" data-surface="delta:revenue"><span class="delta__glyph" aria-hidden="true">▲</span> 12% <span class="delta__base">vs prior</span></span>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
### Down
|
|
21
|
+
|
|
22
|
+
```html
|
|
23
|
+
<span class="delta" data-dir="down"><span class="delta__glyph" aria-hidden="true">▼</span> 3% <span class="delta__base">vs prior</span></span>
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
### Small base
|
|
27
|
+
|
|
28
|
+
```html
|
|
29
|
+
<span class="delta" data-dir="flat" data-small-base><span class="delta__base">was 1</span></span>
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
```controls
|
|
33
|
+
select data-dir = up | down | flat
|
|
34
|
+
toggle data-small-base
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Accessibility
|
|
38
|
+
|
|
39
|
+
The glyph is hidden from assistive technology, so the delta must say its direction in words when
|
|
40
|
+
the number alone would be ambiguous: give the tile an accessible name such as "Orders, down 3
|
|
41
|
+
percent versus prior" when the visible text is only "3%". The words are what carry direction for a
|
|
42
|
+
colour-blind reader too, which is the reason the component has no colour to lose.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/* dashboards/rank-list — a ranked breakdown. Each row carries a slim share bar along its bottom
|
|
2
|
+
edge (width = --share, a fraction 0..1) instead of a tinted block behind the whole row, so the
|
|
3
|
+
names stay on plain paper and the bars compare by length. */
|
|
4
|
+
.rank-list { list-style: none; margin: 0; padding: 0; display: grid; gap: var(--space-2); }
|
|
5
|
+
.rank-list__row { --share: 0; position: relative; display: flex; justify-content: space-between; gap: var(--space-3);
|
|
6
|
+
padding-block: var(--space-1) var(--space-2); font-size: var(--text-sm); color: var(--ink); }
|
|
7
|
+
.rank-list__row::after { content: ""; position: absolute; inset-inline-start: 0; inset-block-end: 0;
|
|
8
|
+
block-size: 3px; inline-size: calc(var(--share, 0) * 100%); background: var(--ink-muted); border-radius: var(--radius-sm); }
|
|
9
|
+
.rank-list__name { min-inline-size: 0; overflow-wrap: anywhere; }
|
|
10
|
+
.rank-list__value { font-variant-numeric: tabular-nums; color: var(--ink); }
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Rank list
|
|
2
|
+
|
|
3
|
+
A ranked breakdown: sources by revenue, pages by views, courses by enrolment. Each row is a name and
|
|
4
|
+
a value, with a slim share bar along its bottom edge whose length is the row's share of the total.
|
|
5
|
+
The bar replaces a tinted block behind the whole row, which turns a list into a wall of colour and
|
|
6
|
+
makes the names harder to read than the numbers.
|
|
7
|
+
|
|
8
|
+
The caller sorts the rows and passes each share as --share, a fraction between 0 and 1.
|
|
9
|
+
|
|
10
|
+
## Breakdown
|
|
11
|
+
|
|
12
|
+
### Revenue by source
|
|
13
|
+
|
|
14
|
+
```html
|
|
15
|
+
<ol class="rank-list" data-surface="rank:revenue-by-source">
|
|
16
|
+
<li class="rank-list__row" style="--share: 0.52"><span class="rank-list__name">Direct</span><span class="rank-list__value">€25.1k</span></li>
|
|
17
|
+
<li class="rank-list__row" style="--share: 0.31"><span class="rank-list__name">Search</span><span class="rank-list__value">€14.9k</span></li>
|
|
18
|
+
<li class="rank-list__row" style="--share: 0.17"><span class="rank-list__name">Referral</span><span class="rank-list__value">€8.2k</span></li>
|
|
19
|
+
</ol>
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Accessibility
|
|
23
|
+
|
|
24
|
+
The list is an ordered list, so a screen reader announces the rank and the count. The share bar is
|
|
25
|
+
decoration drawn by CSS and is never read; the value in each row is the text a reader hears, so
|
|
26
|
+
the value must carry its unit. Long names wrap instead of truncating, so nothing is hidden on a
|
|
27
|
+
phone.
|
|
@@ -112,7 +112,7 @@
|
|
|
112
112
|
/* ---- CONTAINER (2026-07-14 responsive-polish fix): the two layout breakpoints below used to be
|
|
113
113
|
`@media`, which reads the actual BROWSER viewport — so the viewport-toggle's cosmetic max-width
|
|
114
114
|
clamp on `.app-shell` (see the bottom of this file) never made them fire; a squeezed real window
|
|
115
|
-
between
|
|
115
|
+
between 640-1100px also just squeezed the fixed rail/aside tracks instead of collapsing (the
|
|
116
116
|
`minmax(0,1fr)` main column went to zero, not the layout).
|
|
117
117
|
|
|
118
118
|
Fix: `.app-shell` cannot query an `@container` condition on ITSELF (the CSS containment spec:
|
|
@@ -136,7 +136,7 @@ body:has(.app-shell) { container-type: inline-size; container-name: shell-frame;
|
|
|
136
136
|
|
|
137
137
|
/* ---- mobile: single column; the rail becomes an off-canvas drawer. The aside (assistant)
|
|
138
138
|
becomes a bottom sheet (sidebar-panel.css, which loads after this file and wins the tie). ---- */
|
|
139
|
-
@container shell-frame (max-width:
|
|
139
|
+
@container shell-frame (max-width: 640px) {
|
|
140
140
|
.app-shell {
|
|
141
141
|
grid-template-columns: minmax(0, 1fr);
|
|
142
142
|
/* the last row only reserves room for the bottom sheet's peeking head (sidebar-panel.css),
|
|
@@ -13,7 +13,7 @@ chrome — `tjakoen.github.io`'s `portfolio-frame`).
|
|
|
13
13
|
|
|
14
14
|
**Parent context (implicit, self-installing).** `.app-shell` must be a direct-or-nested child of
|
|
15
15
|
`<body>` — every real composition already is. `app-shell.css` sets `container-type: inline-size`
|
|
16
|
-
on `body:has(.app-shell)` (named `shell-frame`) because the shell's own
|
|
16
|
+
on `body:has(.app-shell)` (named `shell-frame`) because the shell's own layout
|
|
17
17
|
breakpoints restyle `.app-shell`'s OWN grid properties, and an element can never `@container`-query
|
|
18
18
|
a condition on itself — only a descendant can query an ancestor container. Using `body` (rather
|
|
19
19
|
than a purpose-built wrapper) means the real narrow-viewport case works with zero JS; the
|
|
@@ -23,6 +23,14 @@ share this container for their own mobile rules. One documented gap: `app-window
|
|
|
23
23
|
padding lives on `body` itself (`.app-window-backdrop`), so it can't follow suit — it stays a real
|
|
24
24
|
`@media` and only responds to a genuinely narrow window, not the toggle preview.
|
|
25
25
|
|
|
26
|
+
**Breakpoints.** The shell has two, named as tokens in `styles/variables.css`. At `--bp-phone`
|
|
27
|
+
(640px) and under, it is the phone layout: one column, with the rail and the assistant as
|
|
28
|
+
drawers. Up to `--bp-narrow` (1100px) it keeps all three columns with a narrower assistant, so a
|
|
29
|
+
tablet gets the desk shell rather than the phone one. Above that it is the full desk. Container
|
|
30
|
+
and media queries cannot read a custom property, so each query writes the literal value, and
|
|
31
|
+
`app-shell.test.ts` fails if any `shell-frame` query in GRAIN uses a width other than these two.
|
|
32
|
+
Scripts such as `shell.js` read the same numbers. Every control in the shell is at least 24px.
|
|
33
|
+
|
|
26
34
|
Two **optional full-width rows** bracket the workspace: `__window` (top — the `app-window`
|
|
27
35
|
title bar) and `__status` (bottom — the `status-bar`). They're auto rows, so a shell that
|
|
28
36
|
places nothing in them renders exactly as before; fill them to dress the shell as an editor
|
|
@@ -35,13 +35,13 @@ test("app-shell.css establishes the shell-frame container on <body>, not on .app
|
|
|
35
35
|
test("app-shell.css's own layout breakpoints are @container, not @media (the self-query trap)", () => {
|
|
36
36
|
expect(appShellCss).not.toMatch(MEDIA_LAYOUT_BP);
|
|
37
37
|
expect(appShellCss).toMatch(/@container shell-frame \(max-width: 1100px\)/);
|
|
38
|
-
expect(appShellCss).toMatch(/@container shell-frame \(max-width:
|
|
38
|
+
expect(appShellCss).toMatch(/@container shell-frame \(max-width: 640px\)/);
|
|
39
39
|
});
|
|
40
40
|
|
|
41
41
|
test("sidebar-panel + status-bar mobile rules follow the shell's container, not a stale @media", () => {
|
|
42
42
|
for (const [name, css] of [["sidebar-panel.css", sidebarPanelCss], ["status-bar.css", statusBarCss]] as const) {
|
|
43
43
|
expect(css, `${name} still has a real-viewport-only layout @media`).not.toMatch(MEDIA_LAYOUT_BP);
|
|
44
|
-
expect(css, `${name} lost its @container shell-frame mobile rule`).toMatch(/@container shell-frame \(max-width:
|
|
44
|
+
expect(css, `${name} lost its @container shell-frame mobile rule`).toMatch(/@container shell-frame \(max-width: 640px\)/);
|
|
45
45
|
}
|
|
46
46
|
});
|
|
47
47
|
|
|
@@ -58,7 +58,7 @@ test("app-window.css keeps exactly the documented self-query exception, converts
|
|
|
58
58
|
const mediaBody = afterMedia.slice(0, afterMedia.indexOf("}") + 1);
|
|
59
59
|
expect(mediaBody).toMatch(/\.app-window-backdrop\s*\{\s*padding:\s*0/);
|
|
60
60
|
expect(mediaBody).not.toMatch(/\.app-shell\.app-window|\.window-bar/);
|
|
61
|
-
expect(appWindowCss).toMatch(/@container shell-frame \(max-width:
|
|
61
|
+
expect(appWindowCss).toMatch(/@container shell-frame \(max-width: 640px\)\s*\{[^}]*\.app-shell\.app-window/);
|
|
62
62
|
expect(appWindowCss).toMatch(/\.window-bar\s*\{\s*display:\s*none/);
|
|
63
63
|
});
|
|
64
64
|
|
|
@@ -72,3 +72,22 @@ test("the viewport-toggle clamps body[data-viewport], not .app-shell[data-viewpo
|
|
|
72
72
|
test("reduced-motion queries stay real @media (they read a user preference, not a size)", () => {
|
|
73
73
|
expect(appShellCss).toMatch(/@media \(prefers-reduced-motion: reduce\)/);
|
|
74
74
|
});
|
|
75
|
+
|
|
76
|
+
// One named breakpoint set (variables.css: --bp-phone, --bp-narrow). Every shell-frame container
|
|
77
|
+
// query and every width media query in GRAIN's components and scripts must use one of those two
|
|
78
|
+
// values, so a component can never disagree with the shell about which layout it is in.
|
|
79
|
+
test("every shell breakpoint in GRAIN is one of the named set", () => {
|
|
80
|
+
const vars = read("styles/variables.css");
|
|
81
|
+
const named = new Set([...vars.matchAll(/--bp-(?:phone|narrow):\s*(\d+px);/g)].map((m) => m[1]));
|
|
82
|
+
expect([...named].sort()).toEqual(["1100px", "640px"]);
|
|
83
|
+
const { readdirSync } = require("node:fs") as typeof import("node:fs");
|
|
84
|
+
const walk = (dir: string): string[] => readdirSync(join(root, dir), { withFileTypes: true }).flatMap((e) =>
|
|
85
|
+
e.isDirectory() ? walk(join(dir, e.name)) : /\.(css|js)$/.test(e.name) ? [join(dir, e.name)] : []);
|
|
86
|
+
const offenders: string[] = [];
|
|
87
|
+
for (const file of [...walk("components"), ...walk("scripts")]) {
|
|
88
|
+
const src = read(file);
|
|
89
|
+
for (const m of src.matchAll(/(?:@container shell-frame\s*|@media\s*|matchMedia\(["'`])\((?:max|min)-width:\s*(\d+px)\)/g))
|
|
90
|
+
if (!named.has(m[1])) offenders.push(`${file}: ${m[0]}`);
|
|
91
|
+
}
|
|
92
|
+
expect(offenders).toEqual([]);
|
|
93
|
+
});
|
|
@@ -102,10 +102,10 @@
|
|
|
102
102
|
a demo-only feature. `.app-shell.app-window` and `.window-bar`, though, are DESCENDANTS of body,
|
|
103
103
|
not body itself, so they're free to follow the container — converted, so the toggle's preview at
|
|
104
104
|
least drops the frame border/shadow/title-bar even though the backdrop margin lingers. ---- */
|
|
105
|
-
@media (max-width:
|
|
105
|
+
@media (max-width: 640px) {
|
|
106
106
|
.app-window-backdrop { padding: 0; }
|
|
107
107
|
}
|
|
108
|
-
@container shell-frame (max-width:
|
|
108
|
+
@container shell-frame (max-width: 640px) {
|
|
109
109
|
.app-shell.app-window { border: 0; border-radius: 0; box-shadow: none; }
|
|
110
110
|
.window-bar { display: none; }
|
|
111
111
|
}
|
|
@@ -6,8 +6,7 @@
|
|
|
6
6
|
.note { max-width: 72ch; }
|
|
7
7
|
.note > p, .note > ul, .note > ol, .note > blockquote { line-height: var(--leading-relaxed); }
|
|
8
8
|
|
|
9
|
-
.note__head .
|
|
10
|
-
.note__head .masthead { font-size: var(--text-3xl); margin-bottom: var(--space-3); }
|
|
9
|
+
.note__head .masthead { font-size: var(--text-3xl); margin-bottom: var(--space-2); }
|
|
11
10
|
.note__lede {
|
|
12
11
|
color: var(--color-muted);
|
|
13
12
|
font-size: var(--text-lg);
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Note
|
|
2
2
|
|
|
3
3
|
The editorial content article — the layout MILL's default GRAIN adapter emits for a
|
|
4
|
-
rendered Markdown document (
|
|
4
|
+
rendered Markdown document (masthead → byline meta → lede → tag badges → hairline rule →
|
|
5
5
|
prose). CSS-only: MILL composes the markup; nothing data-binds it. Human-authored content →
|
|
6
6
|
always clean ink (`data-grade="smooth"`; only the AI grains).
|
|
7
7
|
|
|
@@ -9,8 +9,8 @@ always clean ink (`data-grade="smooth"`; only the AI grains).
|
|
|
9
9
|
```html
|
|
10
10
|
<article class="note" data-grade="smooth">
|
|
11
11
|
<header class="note__head">
|
|
12
|
-
<p class="eyebrow">2026-07-03 · ~13 min</p>
|
|
13
12
|
<h1 class="masthead">Ten Times Zero Is Still Zero</h1>
|
|
13
|
+
<p class="byline">2026-07-03 · ~13 min</p>
|
|
14
14
|
<p class="note__lede">How I actually work with AI, and why it holds up.</p>
|
|
15
15
|
<div class="note__tags"><span class="badge" data-status="active">ai</span> <span class="badge" data-status="active">workflow</span></div>
|
|
16
16
|
<hr class="rule">
|
|
@@ -180,9 +180,10 @@
|
|
|
180
180
|
position: absolute; right: calc(var(--u) * 11.7); bottom: calc(var(--u) * 2.4);
|
|
181
181
|
display: flex; align-items: center; gap: calc(var(--u) * 0.8);
|
|
182
182
|
}
|
|
183
|
+
/* WCAG 2.5.8: like the dots, a control never shrinks under a 24px target when the deck scales down. */
|
|
183
184
|
.presentation__ctl {
|
|
184
185
|
display: inline-flex; align-items: center; justify-content: center;
|
|
185
|
-
min-width: calc(var(--u) * 3.4); height: calc(var(--u) * 3.4); padding: 0 calc(var(--u) * 1.1);
|
|
186
|
+
min-width: max(24px, calc(var(--u) * 3.4)); height: max(24px, calc(var(--u) * 3.4)); padding: 0 calc(var(--u) * 1.1);
|
|
186
187
|
background: transparent; border: 1px solid var(--color-line); border-radius: var(--radius-sm);
|
|
187
188
|
color: var(--color-muted); font: inherit; font-size: calc(var(--u) * 1.5); line-height: 1; cursor: pointer;
|
|
188
189
|
transition: border-color 0.18s ease, color 0.18s ease, background 0.18s ease;
|
|
@@ -39,7 +39,7 @@
|
|
|
39
39
|
here is not an interrupt (ai-dispatch ignores aside/console clicks). */
|
|
40
40
|
.app-shell[data-acting="true"] .app-shell__aside { position: relative; z-index: var(--z-ai-surface, 9002); }
|
|
41
41
|
|
|
42
|
-
/* mobile (<
|
|
42
|
+
/* mobile (<640px): the panel becomes a bottom SHEET. The shell drops the aside column, so re-show it
|
|
43
43
|
fixed to the bottom, collapsed to its header as a grab bar; tap the header to raise the full panel.
|
|
44
44
|
`@container shell-frame`, not `@media` (app-shell.css establishes the container on `<body>` and
|
|
45
45
|
converts its own layout breakpoints the same way — this one has to move in lockstep, or the
|
|
@@ -47,7 +47,7 @@
|
|
|
47
47
|
override ever kicking in to replace it, since its old `@media` never fired off the toggle's
|
|
48
48
|
clamp). Every selector here targets a descendant of body (`.app-shell__aside`, `.assistant__head`),
|
|
49
49
|
never body itself, so the container-query self-query rule doesn't block this file. */
|
|
50
|
-
@container shell-frame (max-width:
|
|
50
|
+
@container shell-frame (max-width: 640px) {
|
|
51
51
|
.app-shell__aside {
|
|
52
52
|
display: flex; position: fixed; left: 0; right: 0; bottom: 0; z-index: var(--z-ai-surface, 9002);
|
|
53
53
|
height: 85dvh; opacity: 1;
|
|
@@ -70,6 +70,6 @@
|
|
|
70
70
|
|
|
71
71
|
/* WCAG 2.4.11 (focus not obscured): the collapsed sheet peeks over the page bottom on a narrow
|
|
72
72
|
frame, so the page's scrollers keep a focused element clear of that strip. */
|
|
73
|
-
@container shell-frame (max-width:
|
|
73
|
+
@container shell-frame (max-width: 640px) {
|
|
74
74
|
.app-shell__main { scroll-padding-bottom: 3.75rem; }
|
|
75
75
|
}
|
|
@@ -27,7 +27,7 @@
|
|
|
27
27
|
(app-shell.css establishes the container on `<body>`) so this fires off BOTH a real narrow
|
|
28
28
|
window and the shell's viewport-toggle clamp, not just the real one — `.status-bar` is a
|
|
29
29
|
descendant of body, never body itself, so it's legal to query here (see app-shell.css). */
|
|
30
|
-
@container shell-frame (max-width:
|
|
30
|
+
@container shell-frame (max-width: 640px) {
|
|
31
31
|
.status-bar { gap: var(--space-4); }
|
|
32
32
|
.status-bar [data-status-optional] { display: none; }
|
|
33
33
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tjakoen/grain",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.34",
|
|
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",
|
|
@@ -37,7 +37,8 @@
|
|
|
37
37
|
],
|
|
38
38
|
"scripts": {
|
|
39
39
|
"check": "tsc --noEmit",
|
|
40
|
-
"test": "bun test"
|
|
40
|
+
"test": "bun test",
|
|
41
|
+
"lint:grain": "bun scripts/grain-lint.ts"
|
|
41
42
|
},
|
|
42
43
|
"devDependencies": {
|
|
43
44
|
"bun-types": "^1.3.14",
|
package/scripts/catalog-peek.js
CHANGED
|
@@ -79,7 +79,7 @@
|
|
|
79
79
|
const modeTab = (m) => shell.querySelector(`.assistant__modes [data-shell-mode="${m}"]`);
|
|
80
80
|
const setOpen = (v) => {
|
|
81
81
|
modeTab(v ? "catalog" : "chat")?.click();
|
|
82
|
-
if (v && matchMedia("(max-width:
|
|
82
|
+
if (v && matchMedia("(max-width: 640px)").matches) shell.setAttribute("data-aside-open", "");
|
|
83
83
|
};
|
|
84
84
|
// [data-peek] hooks: "open" forces open, "close" forces closed, "toggle" (default) flips.
|
|
85
85
|
// preventDefault so a hook can be a real <a> (the Catalog tab is href="/grain" for no-JS nav /
|
package/scripts/cmdk.js
CHANGED
|
@@ -112,7 +112,7 @@
|
|
|
112
112
|
const MARGIN = 8;
|
|
113
113
|
// Narrow viewport: a full-width sheet dropping from just under the field. A
|
|
114
114
|
// compact trigger button must not squeeze the palette to its own width.
|
|
115
|
-
if (vw <=
|
|
115
|
+
if (vw <= 640) {
|
|
116
116
|
root.style.setProperty("--cmdk-top", `${r.bottom + 4}px`);
|
|
117
117
|
root.style.setProperty("--cmdk-left", `${MARGIN}px`);
|
|
118
118
|
root.style.setProperty("--cmdk-width", `${vw - MARGIN * 2}px`);
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
+
<title>grain-lint fixture: accent-word</title>
|
|
7
|
+
<style>
|
|
8
|
+
:root { --color-fg: #1d1a16; --color-muted: #5c554c; --color-bg: #f4efe6; --color-accent: #7a4a10;
|
|
9
|
+
--space-2: 0.5rem; --space-3: 0.75rem; --space-4: 1rem; --space-6: 1.5rem; --text-sm: 0.875rem; --display: 2.5rem; }
|
|
10
|
+
body { margin: 0; background: var(--color-bg); color: var(--color-fg); font: 16px/1.5 Georgia, serif; }
|
|
11
|
+
main { max-width: 40rem; margin: 0 auto; padding: 0 var(--space-4); }
|
|
12
|
+
h1, h2, h3 { font-weight: 400; text-wrap: balance; }
|
|
13
|
+
.masthead { font-size: var(--display); margin: var(--space-6) 0 var(--space-2); }
|
|
14
|
+
.byline { font-size: var(--text-sm); margin: 0 0 var(--space-3); }
|
|
15
|
+
.rule { border: 0; border-bottom: 1px solid var(--color-fg); margin: 0 0 var(--space-6); }
|
|
16
|
+
a { color: var(--color-accent); }
|
|
17
|
+
:focus-visible { outline: 2px solid var(--color-accent); outline-offset: 2px; }
|
|
18
|
+
.pop { color: var(--color-accent); }
|
|
19
|
+
</style>
|
|
20
|
+
</head>
|
|
21
|
+
<body>
|
|
22
|
+
<main>
|
|
23
|
+
<h1 class="masthead">Build something <span class="pop">remarkable</span> today</h1>
|
|
24
|
+
<p class="byline">Tjakoen Stolk · 17 Nov 2026</p>
|
|
25
|
+
<hr class="rule">
|
|
26
|
+
</main>
|
|
27
|
+
</body>
|
|
28
|
+
</html>
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
+
<title>grain-lint fixture: card-run</title>
|
|
7
|
+
<style>
|
|
8
|
+
:root { --color-fg: #1d1a16; --color-muted: #5c554c; --color-bg: #f4efe6; --color-accent: #7a4a10;
|
|
9
|
+
--space-2: 0.5rem; --space-3: 0.75rem; --space-4: 1rem; --space-6: 1.5rem; --text-sm: 0.875rem; --display: 2.5rem; }
|
|
10
|
+
body { margin: 0; background: var(--color-bg); color: var(--color-fg); font: 16px/1.5 Georgia, serif; }
|
|
11
|
+
main { max-width: 40rem; margin: 0 auto; padding: 0 var(--space-4); }
|
|
12
|
+
h1, h2, h3 { font-weight: 400; text-wrap: balance; }
|
|
13
|
+
.masthead { font-size: var(--display); margin: var(--space-6) 0 var(--space-2); }
|
|
14
|
+
.byline { font-size: var(--text-sm); margin: 0 0 var(--space-3); }
|
|
15
|
+
.rule { border: 0; border-bottom: 1px solid var(--color-fg); margin: 0 0 var(--space-6); }
|
|
16
|
+
a { color: var(--color-accent); }
|
|
17
|
+
:focus-visible { outline: 2px solid var(--color-accent); outline-offset: 2px; }
|
|
18
|
+
.cards { display: grid; gap: var(--space-4); }
|
|
19
|
+
.card { border: 1px solid var(--color-fg); padding: var(--space-4); }
|
|
20
|
+
</style>
|
|
21
|
+
</head>
|
|
22
|
+
<body>
|
|
23
|
+
<main>
|
|
24
|
+
<h1 class="masthead">A page that reads like a person made it</h1>
|
|
25
|
+
<p class="byline"><span class="name">Tjakoen Stolk</span> · 17 Nov 2026</p>
|
|
26
|
+
<hr class="rule">
|
|
27
|
+
<div class="cards">
|
|
28
|
+
<div class="card"><h3>Fast</h3><p>It is fast.</p></div>
|
|
29
|
+
<div class="card"><h3>Simple</h3><p>It is simple.</p></div>
|
|
30
|
+
<div class="card"><h3>Secure</h3><p>It is secure.</p></div>
|
|
31
|
+
</div>
|
|
32
|
+
</main>
|
|
33
|
+
</body>
|
|
34
|
+
</html>
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
+
<title>grain-lint fixture: clean</title>
|
|
7
|
+
<style>
|
|
8
|
+
:root { --color-fg: #1d1a16; --color-muted: #5c554c; --color-bg: #f4efe6; --color-accent: #7a4a10;
|
|
9
|
+
--space-2: 0.5rem; --space-3: 0.75rem; --space-4: 1rem; --space-6: 1.5rem; --text-sm: 0.875rem; --display: 2.5rem; }
|
|
10
|
+
body { margin: 0; background: var(--color-bg); color: var(--color-fg); font: 16px/1.5 Georgia, serif; }
|
|
11
|
+
main { max-width: 40rem; margin: 0 auto; padding: 0 var(--space-4); }
|
|
12
|
+
h1, h2, h3 { font-weight: 400; text-wrap: balance; }
|
|
13
|
+
.masthead { font-size: var(--display); margin: var(--space-6) 0 var(--space-2); }
|
|
14
|
+
.byline { font-size: var(--text-sm); margin: 0 0 var(--space-3); }
|
|
15
|
+
.rule { border: 0; border-bottom: 1px solid var(--color-fg); margin: 0 0 var(--space-6); }
|
|
16
|
+
a { color: var(--color-accent); }
|
|
17
|
+
:focus-visible { outline: 2px solid var(--color-accent); outline-offset: 2px; }
|
|
18
|
+
</style>
|
|
19
|
+
</head>
|
|
20
|
+
<body>
|
|
21
|
+
<main>
|
|
22
|
+
<h1 class="masthead">A page that reads like a person made it</h1>
|
|
23
|
+
<p class="byline"><span class="name">Tjakoen Stolk</span> · 17 Nov 2026</p>
|
|
24
|
+
<hr class="rule">
|
|
25
|
+
<p>One idea per paragraph, written plainly, with a <a href="#more">link that goes somewhere</a>.</p>
|
|
26
|
+
<h2 id="more">What it covers</h2>
|
|
27
|
+
<p>The heading carries the section, and context sits in the first sentence below it.</p>
|
|
28
|
+
<img src="data:image/gif;base64,R0lGODlhAQABAAAAACw=" width="40" height="20" alt="">
|
|
29
|
+
<form action="/notes"><label>Search <input name="q"></label> <button>Go</button></form>
|
|
30
|
+
</main>
|
|
31
|
+
</body>
|
|
32
|
+
</html>
|