@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
|
@@ -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.
|
|
@@ -32,3 +32,14 @@
|
|
|
32
32
|
via the inherited --type-font. */
|
|
33
33
|
.stat[data-commit="pending"],
|
|
34
34
|
[data-grade="grain"] .stat { border-style: dashed; border-color: var(--ink); }
|
|
35
|
+
|
|
36
|
+
/* ---- a long text value (a plan id, a name) stays on one line and ends in an ellipsis rather
|
|
37
|
+
than wrapping the tile taller than its neighbours. Opt-in, because a number never needs it. */
|
|
38
|
+
.stat__value[data-fit="truncate"] { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
|
|
39
|
+
|
|
40
|
+
/* ---- a tile that is a link: a filter or a drill-down. It reads as the same tile; hover and focus
|
|
41
|
+
firm the border to full ink, and the selected tile (aria-current) adds an inset ink bar under
|
|
42
|
+
it. Weight and ink only, never hue. The focus ring stays the global one. */
|
|
43
|
+
a.stat { color: inherit; text-decoration: none; }
|
|
44
|
+
a.stat:hover { border-color: var(--ink); }
|
|
45
|
+
a.stat[aria-current]:not([aria-current="false"]) { border-color: var(--ink); box-shadow: inset 0 -3px 0 var(--ink); }
|
|
@@ -41,6 +41,26 @@ secondary/context count that recedes to faint; `ok` and the default read identic
|
|
|
41
41
|
<div class="stat" data-tone="muted"><span class="stat__value">3</span><span class="stat__label">skipped</span></div>
|
|
42
42
|
```
|
|
43
43
|
|
|
44
|
+
## A long text value
|
|
45
|
+
When the value is a word rather than a number (a plan id, a name), `data-fit="truncate"` keeps it
|
|
46
|
+
on one line and ends it in an ellipsis, so the tile stays the height of its neighbours. Put the
|
|
47
|
+
full text in a `title` so it can still be read.
|
|
48
|
+
```html
|
|
49
|
+
<div class="stat">
|
|
50
|
+
<span class="stat__value" data-fit="truncate" title="pantry-session-control">pantry-session-control</span>
|
|
51
|
+
<span class="stat__label">busiest plan</span>
|
|
52
|
+
</div>
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## As a link
|
|
56
|
+
A tile can be the link itself when it filters a view or opens the detail behind the number. Use a
|
|
57
|
+
real `<a>`, and mark the selected filter with `aria-current="page"`, which adds an ink bar under
|
|
58
|
+
the tile. The label should say where the link goes, as it does here.
|
|
59
|
+
```html
|
|
60
|
+
<a class="stat" href="?view=doing" aria-current="page"><span class="stat__value">4</span><span class="stat__label">doing</span></a>
|
|
61
|
+
<a class="stat" href="?view=blocked"><span class="stat__value">1</span><span class="stat__label">blocked</span></a>
|
|
62
|
+
```
|
|
63
|
+
|
|
44
64
|
## In transit (AI writing the number)
|
|
45
65
|
```html
|
|
46
66
|
<div class="stat" data-commit="pending">
|
|
@@ -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
|
|
@@ -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">
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tjakoen/grain",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.35",
|
|
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",
|
|
@@ -32,12 +32,14 @@
|
|
|
32
32
|
"components",
|
|
33
33
|
"fonts",
|
|
34
34
|
"scripts",
|
|
35
|
+
"!scripts/fixtures",
|
|
35
36
|
"styles",
|
|
36
37
|
"PLAN.md"
|
|
37
38
|
],
|
|
38
39
|
"scripts": {
|
|
39
40
|
"check": "tsc --noEmit",
|
|
40
|
-
"test": "bun test"
|
|
41
|
+
"test": "bun test",
|
|
42
|
+
"lint:grain": "bun scripts/grain-lint.ts"
|
|
41
43
|
},
|
|
42
44
|
"devDependencies": {
|
|
43
45
|
"bun-types": "^1.3.14",
|