@tjakoen/grain 0.1.19 → 0.1.21
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/PLAN.md +31 -0
- package/assets/doc-sample.pdf +34 -0
- package/components/atoms/b-button/b-button.css +24 -18
- package/components/doc-links.test.ts +1 -0
- package/components/molecules/attachment/attachment.css +71 -0
- package/components/molecules/attachment/attachment.md +40 -0
- package/components/molecules/doc-frame/doc-frame.css +52 -0
- package/components/molecules/doc-frame/doc-frame.md +51 -0
- package/components/molecules/gallery/gallery.css +47 -0
- package/components/molecules/gallery/gallery.md +53 -0
- package/components/molecules/media-card/media-card.css +90 -0
- package/components/molecules/media-card/media-card.md +97 -0
- package/components/organisms/app-window/app-window.css +1 -1
- package/components/organisms/notepad/notepad.css +5 -1
- package/components/organisms/presentation/presentation.css +4 -4
- package/package.json +1 -1
- package/styles/variables.css +20 -0
- package/styles/vars-defined.test.ts +97 -0
package/PLAN.md
CHANGED
|
@@ -25,3 +25,34 @@
|
|
|
25
25
|
`ai-content-retrieval-layer`).
|
|
26
26
|
5. **Workflow / actions registry.** Named higher-level workflows composed from the atomic verbs, plus a
|
|
27
27
|
discoverable "what the AI can do" list (memory `actions-workflow-registry-idea`).
|
|
28
|
+
|
|
29
|
+
## Components
|
|
30
|
+
|
|
31
|
+
Component work does not belong in the numbered list above, which tracks the AI-interaction layer.
|
|
32
|
+
|
|
33
|
+
1. ~~**Gallery.**~~ **BUILT** (2026-08-12) — `molecules/gallery`, a captioned image grid: the
|
|
34
|
+
companion to `card-grid` for pictures rather than facts, tuned by `--gallery-min` and
|
|
35
|
+
`--gallery-ratio`, wired to `scripts/lightbox.js` by one group per gallery. Written because the
|
|
36
|
+
portfolio's event pages could only carry a hero strip, which hides anything past the fifth tile.
|
|
37
|
+
2. ~~**Media card.**~~ **BUILT** (2026-08-12) — `molecules/media-card`, a `card` that leads with a
|
|
38
|
+
picture: one image, a title, an optional description, an optional row of buttons, cropped to
|
|
39
|
+
`--media-ratio`. It reuses `card`'s vocabulary rather than a second one, and both optional rows
|
|
40
|
+
collapse to nothing when absent.
|
|
41
|
+
|
|
42
|
+
Both consumers are satisfied. The plain photo that links somewhere is the default stacked
|
|
43
|
+
layout. The video poster that links out is `data-layout="overlay"`, which carries the centred
|
|
44
|
+
play badge and lays the title along the bottom on a scrim, and it keeps the one hard rule that
|
|
45
|
+
made the original worth copying: **it embeds nothing.** No iframe, no platform script, no JS at
|
|
46
|
+
all, so the no-JS case is the only case. `tjakoen.github.io/view/components/molecules/event-video`
|
|
47
|
+
retires into it and `content.ts` `renderVideoCard` composes the molecule instead of owning it.
|
|
48
|
+
|
|
49
|
+
**The open question is answered: one component, layout is an attribute.** The two shapes share
|
|
50
|
+
every rule they have apart from where the text sits, so two molecules would fork the box, the
|
|
51
|
+
crop, the hover, the badge and the pending edge to move one block of text. A beside-the-picture
|
|
52
|
+
layout is deliberately not shipped, because nothing asks for it yet and it is one more attribute
|
|
53
|
+
value when something does.
|
|
54
|
+
|
|
55
|
+
Two new global tokens came with it, `--scrim` and `--on-scrim` in `styles/variables.css`. They
|
|
56
|
+
are the one pair that does **not** invert in the dark block, on purpose: a scrim darkens
|
|
57
|
+
somebody else's photograph so a label survives on top of it, and a photograph does not invert
|
|
58
|
+
with the palette.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
%PDF-1.4
|
|
2
|
+
1 0 obj
|
|
3
|
+
<< /Type /Catalog /Pages 2 0 R >>
|
|
4
|
+
endobj
|
|
5
|
+
2 0 obj
|
|
6
|
+
<< /Type /Pages /Kids [3 0 R] /Count 1 >>
|
|
7
|
+
endobj
|
|
8
|
+
3 0 obj
|
|
9
|
+
<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << /Font << /F1 5 0 R >> >> /Contents 4 0 R >>
|
|
10
|
+
endobj
|
|
11
|
+
4 0 obj
|
|
12
|
+
<< /Length 209 >>
|
|
13
|
+
stream
|
|
14
|
+
BT /F1 24 Tf 72 680 Td (Sample document) Tj ET
|
|
15
|
+
BT /F1 12 Tf 72 650 Td (A one page PDF, shipped with GRAIN so the doc-frame) Tj ET
|
|
16
|
+
BT /F1 12 Tf 72 632 Td (example in the catalog renders a real document.) Tj ET
|
|
17
|
+
endstream
|
|
18
|
+
endobj
|
|
19
|
+
5 0 obj
|
|
20
|
+
<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>
|
|
21
|
+
endobj
|
|
22
|
+
xref
|
|
23
|
+
0 6
|
|
24
|
+
0000000000 65535 f
|
|
25
|
+
0000000009 00000 n
|
|
26
|
+
0000000058 00000 n
|
|
27
|
+
0000000115 00000 n
|
|
28
|
+
0000000241 00000 n
|
|
29
|
+
0000000500 00000 n
|
|
30
|
+
trailer
|
|
31
|
+
<< /Size 6 /Root 1 0 R >>
|
|
32
|
+
startxref
|
|
33
|
+
570
|
|
34
|
+
%%EOF
|
|
@@ -1,17 +1,9 @@
|
|
|
1
1
|
/* atoms/b-button — the button, ONE class: .btn. Variants are ATTRIBUTES, not
|
|
2
2
|
extra classes (vanilla CSS, no utility soup). The component owns its styling.
|
|
3
|
-
Accent is three CSS vars scoped to .btn; a status attribute repoints them, so
|
|
4
|
-
every variant inherits the new color for free.
|
|
5
3
|
Each pseudo-state has a parallel data-force value so the catalog can show it
|
|
6
4
|
statically (e.g. .btn:hover AND .btn[data-force~="hover"]). */
|
|
7
5
|
|
|
8
6
|
.btn {
|
|
9
|
-
/* accent token set — [data-status] overrides these */
|
|
10
|
-
--btn-accent: var(--color-primary);
|
|
11
|
-
--btn-accent-hover: var(--color-primary-hover);
|
|
12
|
-
--btn-accent-contrast: var(--color-primary-contrast);
|
|
13
|
-
--btn-accent-soft: var(--color-primary-soft);
|
|
14
|
-
|
|
15
7
|
display: inline-flex; align-items: center; justify-content: center;
|
|
16
8
|
gap: var(--space-2);
|
|
17
9
|
font-family: var(--type-font);
|
|
@@ -24,7 +16,7 @@
|
|
|
24
16
|
border: var(--border); /* ink hairline — no fill, no shadow */
|
|
25
17
|
border-radius: var(--radius-sm);
|
|
26
18
|
cursor: pointer;
|
|
27
|
-
transition: background-color 0.15s, color 0.15s;
|
|
19
|
+
transition: background-color 0.15s, color 0.15s, border-color 0.15s;
|
|
28
20
|
|
|
29
21
|
/* default = transparent fill, ink border + label (DESIGN-SYSTEM §5 Buttons) */
|
|
30
22
|
background: transparent;
|
|
@@ -43,21 +35,35 @@
|
|
|
43
35
|
.btn[data-variant="soft"] { background: var(--paper-2); }
|
|
44
36
|
.btn[data-variant="outline"] { background: transparent; } /* already the default look */
|
|
45
37
|
|
|
46
|
-
/* ---- status (attribute):
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
38
|
+
/* ---- status (attribute): a doubled rule on the irreversible one, and nothing else ----
|
|
39
|
+
Settled 2026-08-11 by a walked review, not by a reading: plans/grain-token-debt.md in the
|
|
40
|
+
portfolio, tour review-grain-status, candidate B with the fill kept for the hover.
|
|
41
|
+
Four --btn-accent* tokens used to be declared above and repointed here. They are DELETED
|
|
42
|
+
rather than wired up, because wiring them would have rendered nothing: --color-success and
|
|
43
|
+
--color-danger both resolve to var(--ink), with the same --paper and --paper-2 partners as
|
|
44
|
+
every other button. There is no hue to spend and that is the design (DESIGN-SYSTEM §2), so
|
|
45
|
+
the honest fix is to stop declaring a colour the palette does not have.
|
|
46
|
+
success gets NO visual rule, on purpose. It keeps its meaning for assistive tech and for the
|
|
47
|
+
AI layer while visual ranking stays data-variant's job, which is the axis that already works
|
|
48
|
+
in a monochrome palette. Only the action you cannot undo is marked. */
|
|
49
|
+
.btn[data-status="danger"] { border-width: 2px; }
|
|
55
50
|
|
|
56
51
|
/* ---- pseudo-states. Hover = a quiet ink WASH (DESIGN-SYSTEM §5), never an invert and
|
|
57
52
|
never a new hue — the full ink-fill invert read as a loud accent block and revealed the
|
|
58
53
|
corner radius on otherwise-flat buttons (regression, 2026-07-04). ---- */
|
|
59
54
|
.btn:hover, .btn[data-force~="hover"] { background: color-mix(in srgb, var(--ink) 8%, transparent); }
|
|
60
55
|
|
|
56
|
+
/* The one exception to "hover is a wash", and the one place a solid fill is spent: the
|
|
57
|
+
destructive control. At rest it is only a doubled rule, so the row stays quiet; the moment the
|
|
58
|
+
pointer is on the button that cannot be undone it goes solid ink with a paper label, which is
|
|
59
|
+
the loudest thing GRAIN can say without a hue. Reads at (0,3,0) so it beats the wash above on
|
|
60
|
+
specificity, not on source order. border-color is set explicitly for a flavor that repoints
|
|
61
|
+
--hairline away from --ink; in the stock themes the two are the same value. */
|
|
62
|
+
.btn[data-status="danger"]:hover,
|
|
63
|
+
.btn[data-status="danger"][data-force~="hover"] {
|
|
64
|
+
background: var(--ink); color: var(--paper); border-color: var(--ink);
|
|
65
|
+
}
|
|
66
|
+
|
|
61
67
|
.btn:focus-visible, .btn[data-force~="focus"] { outline: 2px solid var(--color-accent); outline-offset: 2px; }
|
|
62
68
|
.btn:active, .btn[data-force~="active"] { transform: translateY(1px); }
|
|
63
69
|
|
|
@@ -23,6 +23,7 @@ const here = new URL(".", import.meta.url).pathname;
|
|
|
23
23
|
// resolve for anyone who mounted the package the way the README says to.
|
|
24
24
|
const SHIPPED_ASSETS = new Set([
|
|
25
25
|
"/assets/figure-sample.svg",
|
|
26
|
+
"/assets/doc-sample.pdf",
|
|
26
27
|
"/scripts/terminal.js",
|
|
27
28
|
]);
|
|
28
29
|
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/* molecules/attachment — a document hanging off a page: a deck, a paper, a slide set. CSS-only
|
|
2
|
+
(CONVENTIONS §4), composed by hand, nothing data-binds it.
|
|
3
|
+
|
|
4
|
+
The shape is deliberately quiet and horizontal. An attachment is not the page's content, it is
|
|
5
|
+
the thing the page is about, offered on the way in — so it announces itself in one row near the
|
|
6
|
+
top and then gets out of the way. That is the whole reason it is not a media-card: a poster-sized
|
|
7
|
+
tile at the top of a note reads as the subject rather than the appendix.
|
|
8
|
+
|
|
9
|
+
The whole row is the link. Composed as an <a> with <span> children, so every child that must sit
|
|
10
|
+
on its own line declares display, because a <span> inside an <a> does not get one for free. Owns
|
|
11
|
+
no outer margin: where an attachment sits is the consumer's layout decision. */
|
|
12
|
+
.attachment {
|
|
13
|
+
display: flex;
|
|
14
|
+
flex-wrap: wrap;
|
|
15
|
+
align-items: center;
|
|
16
|
+
gap: var(--space-4);
|
|
17
|
+
padding: var(--space-3) var(--space-4);
|
|
18
|
+
border: 1px solid var(--color-line);
|
|
19
|
+
border-radius: var(--radius-md);
|
|
20
|
+
text-decoration: none;
|
|
21
|
+
color: var(--color-fg);
|
|
22
|
+
transition: background-color 0.15s, border-color 0.15s;
|
|
23
|
+
}
|
|
24
|
+
.attachment:hover { background: var(--paper-2); border-color: var(--ink); }
|
|
25
|
+
|
|
26
|
+
/* the kind chip: PDF, DECK, SLIDES. Monospace and small, so it reads as a file type rather than
|
|
27
|
+
a heading, and fixed-width enough that a row of attachments lines up down the left. */
|
|
28
|
+
.attachment__kind {
|
|
29
|
+
flex: none;
|
|
30
|
+
min-width: 3.5rem;
|
|
31
|
+
padding: var(--space-1) var(--space-2);
|
|
32
|
+
border: 1px solid var(--color-line);
|
|
33
|
+
border-radius: var(--radius-sm);
|
|
34
|
+
font-family: var(--font-mono);
|
|
35
|
+
font-size: var(--text-xs);
|
|
36
|
+
text-transform: uppercase;
|
|
37
|
+
letter-spacing: .04em;
|
|
38
|
+
text-align: center;
|
|
39
|
+
color: var(--color-muted);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
.attachment__body { flex: 1 1 12rem; min-width: 10rem; }
|
|
43
|
+
.attachment__title { display: block; font-size: var(--text-base); overflow-wrap: anywhere; }
|
|
44
|
+
.attachment__meta {
|
|
45
|
+
display: block;
|
|
46
|
+
margin-top: var(--space-1);
|
|
47
|
+
font-size: var(--text-xs);
|
|
48
|
+
color: var(--color-muted);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/* the affordance on the right: says what the click does. Hidden on narrow screens, where the row
|
|
52
|
+
is obviously tappable and the words cost more than they carry.
|
|
53
|
+
|
|
54
|
+
The row WRAPS rather than squeezing (flex-wrap above, and a 12rem basis on the body). Without
|
|
55
|
+
that, a narrow container — the component catalog's preview column is the one that caught it —
|
|
56
|
+
crushes the title to one word per line while the chip and this label sit comfortably beside it.
|
|
57
|
+
A viewport media query cannot fix that: the viewport is wide, the box is not. */
|
|
58
|
+
.attachment__action {
|
|
59
|
+
flex: none;
|
|
60
|
+
font-size: var(--text-sm);
|
|
61
|
+
color: var(--color-muted);
|
|
62
|
+
}
|
|
63
|
+
.attachment:hover .attachment__action { color: var(--color-fg); }
|
|
64
|
+
@media (max-width: 32rem) {
|
|
65
|
+
.attachment__action { display: none; }
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/* ---- AI / in-transit: an attachment the AI is still producing wears the dashed terminal edge,
|
|
69
|
+
the same vocabulary card, badge and field use. */
|
|
70
|
+
.attachment[data-commit="pending"],
|
|
71
|
+
[data-grade="grain"] .attachment { border-style: dashed; border-color: var(--ink); }
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Attachment
|
|
2
|
+
|
|
3
|
+
A document hanging off a page: a deck, a paper, a slide set. One quiet horizontal row, near the top,
|
|
4
|
+
saying what is attached and what opening it costs. Composed by hand, so nothing data-binds it.
|
|
5
|
+
|
|
6
|
+
It is deliberately **not** a `media-card`. A poster-sized tile at the top of a note reads as the
|
|
7
|
+
subject of the page; an attachment is the thing the page is *about*, offered on the way in. It
|
|
8
|
+
announces itself in one row and gets out of the way.
|
|
9
|
+
|
|
10
|
+
The whole row is the link. Children are `<span>`s inside an `<a>`, so anything that must sit on its
|
|
11
|
+
own line declares `display` (a `<span>` in an `<a>` does not get one for free). The component owns no
|
|
12
|
+
outer margin: where it sits is the consumer's layout decision.
|
|
13
|
+
|
|
14
|
+
## Attachment
|
|
15
|
+
```html
|
|
16
|
+
<a class="attachment" href="#gallery">
|
|
17
|
+
<span class="attachment__kind">PDF</span>
|
|
18
|
+
<span class="attachment__body">
|
|
19
|
+
<span class="attachment__title">Beyond Limits, the ideation workshop</span>
|
|
20
|
+
<span class="attachment__meta">32 slides · 2.5 MB · opens in a tab here</span>
|
|
21
|
+
</span>
|
|
22
|
+
<span class="attachment__action">Open →</span>
|
|
23
|
+
</a>
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## A talk that lives on the site
|
|
27
|
+
```html
|
|
28
|
+
<a class="attachment" href="/notes/ten-times-zero">
|
|
29
|
+
<span class="attachment__kind">Talk</span>
|
|
30
|
+
<span class="attachment__body">
|
|
31
|
+
<span class="attachment__title">Ten times zero</span>
|
|
32
|
+
<span class="attachment__meta">28 slides · runs in the browser</span>
|
|
33
|
+
</span>
|
|
34
|
+
<span class="attachment__action">Open →</span>
|
|
35
|
+
</a>
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
**Write the meta line as a cost, not a boast.** Page count, size, and where it opens are the three
|
|
39
|
+
things someone weighs before clicking. `--space` and type come from the tokens; the only per-use knob
|
|
40
|
+
is the kind chip's text.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/* molecules/doc-frame — a document rendered INSIDE the page instead of replacing it. CSS-only
|
|
2
|
+
(CONVENTIONS §4), composed by hand, nothing data-binds it.
|
|
3
|
+
|
|
4
|
+
Why it exists: a link straight to a PDF hands the tab to the browser's viewer and the site is
|
|
5
|
+
gone, chrome and all. Pointed at a route that composes this, the document becomes an ordinary
|
|
6
|
+
page, which means it becomes an ordinary open tab (scripts/tabs.js projects visited paths), which
|
|
7
|
+
means the reader can close it and still be where they were.
|
|
8
|
+
|
|
9
|
+
<object> and not <iframe>: same element, better failure. A browser that cannot render the type
|
|
10
|
+
inline renders the element's CHILDREN instead, so the fallback is markup rather than a script
|
|
11
|
+
sniffing for support. Same origin only — this is for documents the site itself serves, and it is
|
|
12
|
+
emphatically not a hole for third-party embeds.
|
|
13
|
+
|
|
14
|
+
The escape hatch below the frame is NOT redundant with that fallback, and this is the part worth
|
|
15
|
+
remembering: iOS Safari neither renders a multi-page PDF inline nor triggers the fallback. It
|
|
16
|
+
draws page one in a dead box and stops. So the direct link is always visible, for everybody.
|
|
17
|
+
|
|
18
|
+
Height is a knob (--doc-frame-height) because a slide deck and a two-column paper want different
|
|
19
|
+
boxes; the default is most of the viewport, floored so a short window still shows a page. */
|
|
20
|
+
.doc-frame { margin: 0; }
|
|
21
|
+
|
|
22
|
+
.doc-frame__object {
|
|
23
|
+
display: block;
|
|
24
|
+
width: 100%;
|
|
25
|
+
height: var(--doc-frame-height, max(28rem, 78vh));
|
|
26
|
+
border: 1px solid var(--color-line);
|
|
27
|
+
border-radius: var(--radius-md);
|
|
28
|
+
background: var(--paper-2);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/* the <object>'s own children: shown only when the browser refuses the document inline */
|
|
32
|
+
.doc-frame__fallback {
|
|
33
|
+
margin: 0;
|
|
34
|
+
padding: var(--space-6);
|
|
35
|
+
color: var(--color-muted);
|
|
36
|
+
font-size: var(--text-sm);
|
|
37
|
+
line-height: var(--leading-relaxed);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/* always visible, under the frame: the plain link out, plus whatever the consumer puts beside it */
|
|
41
|
+
.doc-frame__escape {
|
|
42
|
+
display: flex;
|
|
43
|
+
flex-wrap: wrap;
|
|
44
|
+
align-items: baseline;
|
|
45
|
+
gap: var(--space-3);
|
|
46
|
+
margin-top: var(--space-3);
|
|
47
|
+
font-size: var(--text-sm);
|
|
48
|
+
color: var(--color-muted);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
.doc-frame[data-commit="pending"] .doc-frame__object,
|
|
52
|
+
[data-grade="grain"] .doc-frame__object { border-style: dashed; border-color: var(--ink); }
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Doc frame
|
|
2
|
+
|
|
3
|
+
A document rendered **inside** the page instead of replacing it. Point a route at one and a PDF
|
|
4
|
+
becomes an ordinary page, which makes it an ordinary open tab (`scripts/tabs.js` projects visited
|
|
5
|
+
paths), which means the reader can close it and still be where they were. A bare link to a `.pdf`
|
|
6
|
+
hands the tab to the browser's viewer and the site is gone, chrome and all.
|
|
7
|
+
|
|
8
|
+
Composed by hand, so nothing data-binds it. **Same-origin documents only.** This is for files the
|
|
9
|
+
site itself serves; it is not a hole for third-party embeds.
|
|
10
|
+
|
|
11
|
+
`<object>` rather than `<iframe>` for one reason: a browser that cannot render the type inline
|
|
12
|
+
renders the element's **children** instead, so the fallback is markup and not a script sniffing for
|
|
13
|
+
support.
|
|
14
|
+
|
|
15
|
+
## Doc frame
|
|
16
|
+
```html
|
|
17
|
+
<figure class="doc-frame">
|
|
18
|
+
<object class="doc-frame__object" data="/assets/doc-sample.pdf" type="application/pdf"
|
|
19
|
+
aria-label="Sample document, rendered in the page">
|
|
20
|
+
<p class="doc-frame__fallback">
|
|
21
|
+
This browser will not display the document inline. Open it directly instead.
|
|
22
|
+
</p>
|
|
23
|
+
</object>
|
|
24
|
+
<figcaption class="doc-frame__escape">
|
|
25
|
+
<a href="/assets/doc-sample.pdf">Open the file directly</a>
|
|
26
|
+
<span>1 page · 753 bytes</span>
|
|
27
|
+
</figcaption>
|
|
28
|
+
</figure>
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## The escape hatch is not optional
|
|
32
|
+
|
|
33
|
+
The `<figcaption>` link is **not** redundant with the `<object>` fallback, and this is the part worth
|
|
34
|
+
remembering when a future change makes it look like clutter: **iOS Safari neither renders a
|
|
35
|
+
multi-page PDF inline nor triggers the fallback.** It draws page one in a dead box and stops. Nothing
|
|
36
|
+
in the markup can detect that, so the direct link stays visible for everybody rather than being
|
|
37
|
+
hidden behind a fallback that never fires.
|
|
38
|
+
|
|
39
|
+
## Height
|
|
40
|
+
|
|
41
|
+
`--doc-frame-height` (default `max(28rem, 78vh)`) sets the box, because a slide deck and a
|
|
42
|
+
two-column paper want different ones. Set it on the `.doc-frame`.
|
|
43
|
+
|
|
44
|
+
```html
|
|
45
|
+
<figure class="doc-frame" style="--doc-frame-height: 32rem;">
|
|
46
|
+
<object class="doc-frame__object" data="/assets/doc-sample.pdf" type="application/pdf"
|
|
47
|
+
aria-label="Sample document in a shorter frame">
|
|
48
|
+
<p class="doc-frame__fallback">This browser will not display the document inline.</p>
|
|
49
|
+
</object>
|
|
50
|
+
</figure>
|
|
51
|
+
```
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/* molecules/gallery — a captioned image grid. CSS-only (CONVENTIONS §4): composed by hand, nothing
|
|
2
|
+
data-binds it. The companion to card-grid, for pictures rather than facts: every tile is equal
|
|
3
|
+
weight, cropped to one ratio, and carries its caption under it.
|
|
4
|
+
|
|
5
|
+
Deliberately NOT a hero strip. A strip runs one photo big to carry a post; a gallery is the roll
|
|
6
|
+
that hero was picked from, so a reader can scan it and move on. Tile width tunes with
|
|
7
|
+
--gallery-min (default 15rem, same idiom as --card-min), the crop with --gallery-ratio.
|
|
8
|
+
|
|
9
|
+
Lightbox: wrap the grid in [data-lightbox-group] and mark each tile [data-lightbox] (scripts/
|
|
10
|
+
lightbox.js). One group per gallery, so prev/next never walks out of it into another strip on the
|
|
11
|
+
same page. Keep the trigger an <a href> pointing at the full image: that is the no-JS fallback. */
|
|
12
|
+
.gallery {
|
|
13
|
+
display: grid;
|
|
14
|
+
gap: var(--space-4);
|
|
15
|
+
grid-template-columns: repeat(auto-fit, minmax(var(--gallery-min, 15rem), 1fr));
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
.gallery__item { margin: 0; display: flex; flex-direction: column; gap: var(--space-2); }
|
|
19
|
+
|
|
20
|
+
/* fixed box per tile: a real roll mixes portrait and landscape, and a ragged grid reads like a
|
|
21
|
+
mistake. object-fit crops to the box; the box reserves the space, so a lazily-loaded photo cannot
|
|
22
|
+
shift the page under someone mid-scroll. */
|
|
23
|
+
.gallery__link {
|
|
24
|
+
display: block;
|
|
25
|
+
overflow: hidden;
|
|
26
|
+
border: 1px solid var(--color-line);
|
|
27
|
+
border-radius: var(--radius-md);
|
|
28
|
+
background: var(--paper-2);
|
|
29
|
+
}
|
|
30
|
+
.gallery__link img {
|
|
31
|
+
display: block; width: 100%; height: 100%;
|
|
32
|
+
aspect-ratio: var(--gallery-ratio, 3 / 2);
|
|
33
|
+
object-fit: cover;
|
|
34
|
+
}
|
|
35
|
+
a.gallery__link { transition: border-color 0.15s; }
|
|
36
|
+
a.gallery__link:hover { border-color: var(--ink); }
|
|
37
|
+
|
|
38
|
+
.gallery__caption {
|
|
39
|
+
color: var(--color-muted);
|
|
40
|
+
font-size: var(--text-xs);
|
|
41
|
+
line-height: var(--leading-normal);
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/* ---- AI / in-transit: a gallery the AI is still filling wears the dashed "terminal" edge on its
|
|
45
|
+
tiles, the same vocabulary card + badge + field use. */
|
|
46
|
+
.gallery[data-commit="pending"] .gallery__link,
|
|
47
|
+
[data-grade="grain"] .gallery__link { border-style: dashed; border-color: var(--ink); }
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Gallery
|
|
2
|
+
|
|
3
|
+
A captioned image grid: the companion to `card-grid`, for pictures rather than facts. Every tile is
|
|
4
|
+
equal weight, cropped to one ratio, caption underneath. Composed by hand, so nothing data-binds it.
|
|
5
|
+
|
|
6
|
+
It is not a hero strip. A strip runs one photo big to carry a post; a gallery is the roll that hero
|
|
7
|
+
was picked from, and it belongs where a reader can scan it and move on. Tile width tunes with
|
|
8
|
+
`--gallery-min` (default `15rem`, the same idiom as `--card-min`), the crop with `--gallery-ratio`.
|
|
9
|
+
|
|
10
|
+
## Gallery
|
|
11
|
+
```html
|
|
12
|
+
<div class="gallery">
|
|
13
|
+
<figure class="gallery__item">
|
|
14
|
+
<span class="gallery__link"><img src="/assets/figure-sample.svg" alt="An abstract field of grain strokes"></span>
|
|
15
|
+
<figcaption class="gallery__caption">The caption is the alt text: it has to work read aloud and read on the page.</figcaption>
|
|
16
|
+
</figure>
|
|
17
|
+
<figure class="gallery__item">
|
|
18
|
+
<span class="gallery__link"><img src="/assets/figure-sample.svg" alt="The same field, second frame"></span>
|
|
19
|
+
<figcaption class="gallery__caption">One sentence, what is actually in the frame.</figcaption>
|
|
20
|
+
</figure>
|
|
21
|
+
</div>
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Wired to the lightbox
|
|
25
|
+
|
|
26
|
+
Wrap the grid in `data-lightbox-group` and mark each tile `data-lightbox` (`scripts/lightbox.js`).
|
|
27
|
+
**One group per gallery**, so prev/next never walks out of it into another strip on the same page.
|
|
28
|
+
Keep the trigger an `<a href>` pointing at the full image: with no JS, or a modified click, it
|
|
29
|
+
degrades to a plain navigation, which is the no-JS-safe fallback.
|
|
30
|
+
|
|
31
|
+
```html
|
|
32
|
+
<div class="gallery" data-lightbox-group>
|
|
33
|
+
<figure class="gallery__item">
|
|
34
|
+
<a class="gallery__link" data-lightbox href="/assets/figure-sample.svg">
|
|
35
|
+
<img src="/assets/figure-sample.svg" alt="An abstract field of grain strokes" loading="lazy" decoding="async">
|
|
36
|
+
</a>
|
|
37
|
+
<figcaption class="gallery__caption">Clicking any tile opens the viewer and walks the whole group.</figcaption>
|
|
38
|
+
</figure>
|
|
39
|
+
</div>
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Wider tiles, square crop
|
|
43
|
+
```html
|
|
44
|
+
<div class="gallery" style="--gallery-min: 20rem; --gallery-ratio: 1 / 1;">
|
|
45
|
+
<figure class="gallery__item">
|
|
46
|
+
<span class="gallery__link"><img src="/assets/figure-sample.svg" alt="A square crop of the same field"></span>
|
|
47
|
+
<figcaption class="gallery__caption">Both knobs are custom properties, set them on the grid.</figcaption>
|
|
48
|
+
</figure>
|
|
49
|
+
</div>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
**Alt text is the caption here**, so write one that carries both jobs: read aloud, and read on the
|
|
53
|
+
page under the picture.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
/* molecules/media-card — a card that leads with a picture. CSS-only (CONVENTIONS §4): composed by
|
|
2
|
+
hand, nothing data-binds it. Card's vocabulary, not a second one: hairline box, no fill, no
|
|
3
|
+
shadow (DESIGN-SYSTEM §2), data-pad for padding, and the whole tile navigable when the root is
|
|
4
|
+
an <a>. Description and action row are both optional and both collapse to nothing when absent.
|
|
5
|
+
|
|
6
|
+
Layout is an attribute, not a second component. The default stacks the text under the picture;
|
|
7
|
+
[data-layout="overlay"] lays it over the bottom of the picture on a scrim. Those are the two
|
|
8
|
+
shapes with a real consumer today, and they share every other rule they have: the box, the
|
|
9
|
+
crop, the hover, the badge, the pending edge. Splitting them into two molecules would fork all
|
|
10
|
+
five to move one block of text. A beside-the-picture layout is the same decision again and is
|
|
11
|
+
deliberately not shipped until something asks for it: it is one more attribute value here, not
|
|
12
|
+
a new component.
|
|
13
|
+
|
|
14
|
+
It embeds nothing. The video poster consumer is one anchor over a still we host ourselves, so
|
|
15
|
+
there is no iframe, no platform script, and no JS in this component at all, which makes the
|
|
16
|
+
no-JS case the only case. The play badge is decorative (mark it aria-hidden); the title carries
|
|
17
|
+
the meaning for a screen reader.
|
|
18
|
+
|
|
19
|
+
Crop tunes with --media-ratio (default 16 / 9, the same idiom as --gallery-ratio). */
|
|
20
|
+
.media-card {
|
|
21
|
+
position: relative;
|
|
22
|
+
display: block;
|
|
23
|
+
overflow: hidden;
|
|
24
|
+
border: 1px solid var(--color-line);
|
|
25
|
+
border-radius: var(--radius-md);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/* fixed box for the picture: the ratio reserves the space, so a lazily-loaded still cannot shift
|
|
29
|
+
the page under someone mid-scroll, and object-fit crops whatever it is handed to that box. */
|
|
30
|
+
.media-card__media { display: block; position: relative; background: var(--paper-2); }
|
|
31
|
+
.media-card__image {
|
|
32
|
+
display: block; width: 100%; height: 100%;
|
|
33
|
+
aspect-ratio: var(--media-ratio, 16 / 9);
|
|
34
|
+
object-fit: cover;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
.media-card__body { padding: var(--space-5); }
|
|
38
|
+
.media-card[data-pad="sm"] .media-card__body { padding: var(--space-4); }
|
|
39
|
+
|
|
40
|
+
/* both rows are display: block because the navigable form composes them as <span>. Inside an <a>
|
|
41
|
+
the whole tile is the link, and a <span> is the neutral element to reach for there; left inline
|
|
42
|
+
it would run the title and the description together on one line, which is what happens the first
|
|
43
|
+
time anyone copies the example. Declaring it here means the markup can be spans or an <h3> and a
|
|
44
|
+
<p>, and both stack. */
|
|
45
|
+
.media-card__title { display: block; font-size: var(--text-base); margin: 0; }
|
|
46
|
+
.media-card__text { display: block; color: var(--color-muted); font-size: var(--text-sm);
|
|
47
|
+
line-height: var(--leading-normal); margin: var(--space-2) 0 0; }
|
|
48
|
+
|
|
49
|
+
/* the action row: buttons composed by hand, wrapping rather than overflowing on a narrow tile */
|
|
50
|
+
.media-card__actions { display: flex; flex-wrap: wrap; gap: var(--space-2);
|
|
51
|
+
margin: var(--space-4) 0 0; }
|
|
52
|
+
|
|
53
|
+
/* a navigable tile: the whole card is the link, so the tap target is the picture. Quiet at rest,
|
|
54
|
+
the edge picks up ink on hover, the way a gallery tile does. */
|
|
55
|
+
a.media-card { text-decoration: none; color: var(--color-fg); }
|
|
56
|
+
a.media-card:hover { border-color: var(--ink); }
|
|
57
|
+
a.media-card[aria-disabled="true"] { pointer-events: none; opacity: 0.6; }
|
|
58
|
+
|
|
59
|
+
/* the play badge sits centred over the picture, carrying its own scrim disc so it survives a
|
|
60
|
+
bright frame. Decorative: the title is what a screen reader gets. */
|
|
61
|
+
.media-card__play {
|
|
62
|
+
position: absolute; inset: 0; margin: auto;
|
|
63
|
+
width: 4rem; height: 4rem;
|
|
64
|
+
display: grid; place-items: center;
|
|
65
|
+
border-radius: 50%;
|
|
66
|
+
background: var(--scrim); color: var(--on-scrim);
|
|
67
|
+
font-size: var(--text-2xl); line-height: 1; padding-left: .15em;
|
|
68
|
+
}
|
|
69
|
+
a.media-card:hover .media-card__play { background: var(--ink); }
|
|
70
|
+
|
|
71
|
+
/* ---- overlay: the text sits on the picture rather than under it. The gradient is the readability
|
|
72
|
+
device, not decoration: a label over an arbitrary photograph has no contrast guarantee without
|
|
73
|
+
it. Both scrim tokens hold their value across color schemes on purpose (variables.css). */
|
|
74
|
+
.media-card[data-layout="overlay"] .media-card__body {
|
|
75
|
+
position: absolute; left: 0; right: 0; bottom: 0;
|
|
76
|
+
padding: var(--space-4);
|
|
77
|
+
color: var(--on-scrim);
|
|
78
|
+
background: linear-gradient(to top, var(--scrim), transparent);
|
|
79
|
+
}
|
|
80
|
+
.media-card[data-layout="overlay"] .media-card__text { color: var(--on-scrim); opacity: 0.85; }
|
|
81
|
+
|
|
82
|
+
@media (prefers-reduced-motion: no-preference) {
|
|
83
|
+
a.media-card { transition: border-color 0.15s; }
|
|
84
|
+
.media-card__play { transition: background 0.15s; }
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/* ---- AI / in-transit: a media card the AI is still composing wears the dashed "terminal" edge,
|
|
88
|
+
the same vocabulary card + gallery + badge + field use. */
|
|
89
|
+
.media-card[data-commit="pending"],
|
|
90
|
+
[data-grade="grain"] .media-card { border-style: dashed; border-color: var(--ink); }
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# Media card
|
|
2
|
+
|
|
3
|
+
A card that leads with a picture: one image, a title, an optional description, an optional row of
|
|
4
|
+
buttons. It borrows `card`'s vocabulary rather than inventing a second one, so the box is a
|
|
5
|
+
hairline with no fill, `data-pad` tunes the padding, and the whole tile is the link when the root
|
|
6
|
+
is an `<a>`. Composed by hand, so nothing data-binds it. The crop tunes with `--media-ratio`
|
|
7
|
+
(default `16 / 9`, the same idiom as `--gallery-ratio`).
|
|
8
|
+
|
|
9
|
+
**It embeds nothing.** The reason lives in the second example below, but it applies to the whole
|
|
10
|
+
component: there is no iframe, no third-party script and no JS of any kind in it, which makes the
|
|
11
|
+
no-JS case the only case there is.
|
|
12
|
+
|
|
13
|
+
## A picture that links somewhere
|
|
14
|
+
|
|
15
|
+
The plain case. The root is the anchor, so the picture is the tap target, and the description
|
|
16
|
+
collapses to nothing when you leave it out.
|
|
17
|
+
|
|
18
|
+
```html
|
|
19
|
+
<a class="media-card" href="#media-card">
|
|
20
|
+
<span class="media-card__media">
|
|
21
|
+
<img class="media-card__image" src="/assets/figure-sample.svg"
|
|
22
|
+
alt="An abstract field of grain strokes" loading="lazy" decoding="async">
|
|
23
|
+
</span>
|
|
24
|
+
<span class="media-card__body">
|
|
25
|
+
<span class="media-card__title">The field, in one frame</span>
|
|
26
|
+
<span class="media-card__text">One sentence about where this goes, written like a link and not
|
|
27
|
+
like a button.</span>
|
|
28
|
+
</span>
|
|
29
|
+
</a>
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## A video poster that links out
|
|
33
|
+
|
|
34
|
+
`data-layout="overlay"` moves the text onto the bottom of the picture, on a scrim, and the play
|
|
35
|
+
badge sits centred over it. The badge is decorative, so it is `aria-hidden` and the title is what a
|
|
36
|
+
screen reader is given.
|
|
37
|
+
|
|
38
|
+
This is the shape to reach for when a video lives on somebody else's platform. Embedding it would
|
|
39
|
+
put a third-party iframe and its scripts on the page to play something that lives over there
|
|
40
|
+
regardless: the visitor lands on that platform the moment they press play either way. So the tile
|
|
41
|
+
is one anchor over a still you host yourself, and the title says where the tap goes and whose
|
|
42
|
+
platform it lands on, because the picture cannot.
|
|
43
|
+
|
|
44
|
+
```html
|
|
45
|
+
<a class="media-card" data-layout="overlay" href="https://example.com/reel/1" rel="noopener">
|
|
46
|
+
<span class="media-card__media">
|
|
47
|
+
<img class="media-card__image" src="/assets/figure-sample.svg" width="1600" height="900"
|
|
48
|
+
alt="A still from the recap, the room mid-session" loading="lazy" decoding="async">
|
|
49
|
+
<span class="media-card__play" aria-hidden="true">▶</span>
|
|
50
|
+
</span>
|
|
51
|
+
<span class="media-card__body">
|
|
52
|
+
<span class="media-card__title">Watch the recap on the platform it lives on</span>
|
|
53
|
+
</span>
|
|
54
|
+
</a>
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Both scrim colors hold their value in light and dark. A scrim darkens somebody else's photograph so
|
|
58
|
+
a label survives on top of it, and a photograph does not invert with the palette.
|
|
59
|
+
|
|
60
|
+
## With an action row
|
|
61
|
+
|
|
62
|
+
**When there are buttons, the root is a `<div>`, never an `<a>`.** A link inside a link is invalid
|
|
63
|
+
markup and browsers recover from it in their own ways, so the two are mutually exclusive: either
|
|
64
|
+
the whole tile navigates, or the buttons do.
|
|
65
|
+
|
|
66
|
+
```html
|
|
67
|
+
<div class="media-card" data-pad="sm">
|
|
68
|
+
<span class="media-card__media">
|
|
69
|
+
<img class="media-card__image" src="/assets/figure-sample.svg" style="--media-ratio: 3 / 2;"
|
|
70
|
+
alt="The same field, second frame" loading="lazy" decoding="async">
|
|
71
|
+
</span>
|
|
72
|
+
<div class="media-card__body">
|
|
73
|
+
<h3 class="media-card__title">Two ways out of one tile</h3>
|
|
74
|
+
<p class="media-card__text">The description is optional and so is this row. Both collapse to
|
|
75
|
+
nothing when they are absent.</p>
|
|
76
|
+
<div class="media-card__actions">
|
|
77
|
+
<a class="btn" data-size="sm" href="#media-card">Read the write-up</a>
|
|
78
|
+
<a class="btn" data-size="sm" data-variant="soft" href="#media-card">See the photos</a>
|
|
79
|
+
</div>
|
|
80
|
+
</div>
|
|
81
|
+
</div>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Layouts
|
|
85
|
+
|
|
86
|
+
`data-layout` carries the layout, because the two shapes share every rule they have apart from
|
|
87
|
+
where the text sits: the box, the crop, the hover, the badge and the pending edge. Two components
|
|
88
|
+
would fork all five of those to move one block of text.
|
|
89
|
+
|
|
90
|
+
| Value | What it does |
|
|
91
|
+
| --- | --- |
|
|
92
|
+
| *(omitted)* | Stacked. The text sits under the picture. |
|
|
93
|
+
| `overlay` | The text sits over the bottom of the picture, on a scrim. |
|
|
94
|
+
|
|
95
|
+
A beside-the-picture layout is the same decision one more time, and it is deliberately not shipped
|
|
96
|
+
until something asks for it. When something does, it is one more value in that table rather than a
|
|
97
|
+
new molecule.
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
/* the backdrop: the page behind the window, a shade darker than the paper */
|
|
21
21
|
.app-window-backdrop {
|
|
22
22
|
background: color-mix(in srgb, var(--ink) 12%, var(--paper));
|
|
23
|
-
padding: clamp(
|
|
23
|
+
padding: clamp(var(--space-2), 2vh, var(--space-6));
|
|
24
24
|
height: 100dvh;
|
|
25
25
|
box-sizing: border-box;
|
|
26
26
|
}
|
|
@@ -44,7 +44,11 @@
|
|
|
44
44
|
.notepad__entry { min-width: 0; overflow-wrap: anywhere; }
|
|
45
45
|
/* a code block is the one thing that shouldn't hard-wrap — let it scroll on its own, capped to width */
|
|
46
46
|
.notepad__entry pre { max-width: 100%; overflow-x: auto; }
|
|
47
|
-
|
|
47
|
+
/* --color-grain was referenced here and defined nowhere, in this one line and no other in the
|
|
48
|
+
estate, so the fallback was the only thing that ever rendered. There is no "grain colour" to
|
|
49
|
+
point it at either: the grade vocabulary is carried by the FONT (--font-grain / --type-font),
|
|
50
|
+
not by a hue. So the phantom goes and the fallback becomes the rule it always was. */
|
|
51
|
+
.notepad__entry[data-grade="grain"] { color: var(--color-muted); }
|
|
48
52
|
.notepad__entry > :first-child { margin-top: 0; }
|
|
49
53
|
.notepad__entry > :last-child { margin-bottom: 0; }
|
|
50
54
|
.notepad__entry a { color: var(--color-accent); text-decoration: none; }
|
|
@@ -229,18 +229,18 @@
|
|
|
229
229
|
.presenter { display: none; }
|
|
230
230
|
[data-mode="presenter"] .presenter {
|
|
231
231
|
display: grid; grid-template-columns: 1fr 1fr; grid-template-rows: auto 1fr;
|
|
232
|
-
align-content: start; gap:
|
|
232
|
+
align-content: start; gap: var(--space-6); padding: var(--space-6); min-height: 100dvh;
|
|
233
233
|
box-sizing: border-box; font-size: 1rem;
|
|
234
234
|
}
|
|
235
235
|
.presenter__now { grid-column: 1 / -1; display: flex; justify-content: space-between;
|
|
236
|
-
align-items: baseline; border-bottom: var(--rule); padding-bottom:
|
|
236
|
+
align-items: baseline; border-bottom: var(--rule); padding-bottom: var(--space-3); }
|
|
237
237
|
.presenter__clock { font-family: var(--font-mono); font-size: 2.6rem; }
|
|
238
238
|
.presenter__clock[data-over] { color: var(--color-accent); }
|
|
239
239
|
.presenter__pos { font-family: var(--font-mono); color: var(--color-muted); }
|
|
240
|
-
.presenter__title { font-size: 1.8rem; margin: 0 0
|
|
240
|
+
.presenter__title { font-size: 1.8rem; margin: 0 0 var(--space-3); }
|
|
241
241
|
.presenter__notes li { font-size: 1.15rem; line-height: 1.55; margin-bottom: 0.55rem; }
|
|
242
242
|
.presenter__next h3 { font-size: 0.95rem; letter-spacing: 0.12em; text-transform: uppercase;
|
|
243
|
-
color: var(--color-muted); margin: 0 0
|
|
243
|
+
color: var(--color-muted); margin: 0 0 var(--space-2); }
|
|
244
244
|
.presenter__next p { color: var(--color-muted); }
|
|
245
245
|
.presenter__hint { grid-column: 1 / -1; margin: 0; font-size: 0.85rem; color: var(--ink-faint);
|
|
246
246
|
letter-spacing: 0.08em; text-transform: uppercase; }
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tjakoen/grain",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.21",
|
|
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",
|
package/styles/variables.css
CHANGED
|
@@ -47,6 +47,14 @@
|
|
|
47
47
|
--hairline: #1C1B17; /* solid rules (under headlines) */
|
|
48
48
|
--line-soft: rgba(28, 27, 23, .14); /* translucent border for quiet grouping */
|
|
49
49
|
|
|
50
|
+
/* the photo scrim, and the text that sits on it. Deliberately NOT part of the paper/ink pair
|
|
51
|
+
and deliberately NOT overridden in the dark block below: a scrim darkens somebody else's
|
|
52
|
+
photograph so a label survives on top of it, and a photograph does not invert with the
|
|
53
|
+
palette. Flip these with the color scheme and the light mode gets a dark scrim, the dark
|
|
54
|
+
mode a pale one, and the same picture reads two different ways for no reason. */
|
|
55
|
+
--scrim: rgba(20, 19, 15, .72); /* over a still, so a label on it holds in both modes */
|
|
56
|
+
--on-scrim: #F4F2EA; /* the only text color legible on that scrim */
|
|
57
|
+
|
|
50
58
|
/* grade font families (clean = human, grain = AI / in-transit). Grain is grade 50 —
|
|
51
59
|
one step up from the 35 working grade for more visible texture. */
|
|
52
60
|
--font-smooth: "Redaction", "Times New Roman", Georgia, serif;
|
|
@@ -170,6 +178,18 @@
|
|
|
170
178
|
/* AI takeover STACKING — one source of truth so the AI module (grain/ai/ai.css) and any
|
|
171
179
|
consumer chrome (e.g. the app's portfolio-frame console/chat) agree without duplicating
|
|
172
180
|
magic z-index numbers. veil < spotlit surface < the AI surfaces that stay above the veil. */
|
|
181
|
+
/* Shared chrome heights. The one-line head that the drawer, the app-shell topbar and the
|
|
182
|
+
sidebar-panel all have to agree on: all three read `var(--editor-header-h, 2.9rem)` and none
|
|
183
|
+
of them defined it, so three organisms were agreeing by repeating a magic number rather than
|
|
184
|
+
by sharing a token. 2.9rem is the value that already rendered; declaring it here is what makes
|
|
185
|
+
the agreement real, and what makes it possible to change the row height in one place. */
|
|
186
|
+
--editor-header-h: 2.9rem;
|
|
187
|
+
|
|
188
|
+
/* Presentation sits BELOW the AI ladder on purpose: the lamp has to be able to dim a slide.
|
|
189
|
+
It was already reading `var(--z-presentation, 8000)` in presentation.css with nothing
|
|
190
|
+
defining it, so 8000 is the value that has always rendered — this declares it rather than
|
|
191
|
+
changing it, and puts it on the ladder where the next person can see the ordering. */
|
|
192
|
+
--z-presentation: 8000;
|
|
173
193
|
--z-ai-veil: 9000; /* the dimming backdrop */
|
|
174
194
|
--z-ai-spot: 9001; /* the spotlit surface, lifted out of the dim */
|
|
175
195
|
--z-ai-surface: 9002; /* AI surfaces kept above the veil (acting label, console, chat) */
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
// grain/styles/vars-defined.test.ts — the guard that plans/grain-token-debt.md G3 asks for: every
|
|
2
|
+
// custom property a stylesheet READS has to be one some stylesheet DEFINES.
|
|
3
|
+
//
|
|
4
|
+
// Why this exists, concretely. crumb.css shipped five references that were defined nowhere in grain
|
|
5
|
+
// or crumb: --accent, --font-ui, --ink-soft, --ok and --warn. Nothing failed, nothing warned, and
|
|
6
|
+
// two of them rendered — `var(--ok, green)` and `var(--warn, orange)` put a literal green and a
|
|
7
|
+
// literal orange on screen inside a palette that collapses every status to ink on purpose. They
|
|
8
|
+
// survived an audit and a release because CSS has no undefined-variable error: it takes the
|
|
9
|
+
// fallback and says nothing.
|
|
10
|
+
//
|
|
11
|
+
// So the fallback is NOT an excuse here, it is the aggravating factor. `var(--nope)` renders as
|
|
12
|
+
// nothing and someone notices within the hour; `var(--nope, green)` renders as green and ships. A
|
|
13
|
+
// reference with a fallback is held to exactly the same bar as one without, which is the only rule
|
|
14
|
+
// that would have caught the five.
|
|
15
|
+
//
|
|
16
|
+
// Scope is the whole package set rather than one package, because the vocabulary is shared: grain
|
|
17
|
+
// defines the tokens and crumb, mill and proof spend them. A per-package check would have called
|
|
18
|
+
// crumb's references "external" and passed.
|
|
19
|
+
import { test, expect } from "bun:test";
|
|
20
|
+
import { readdirSync, readFileSync } from "node:fs";
|
|
21
|
+
import { join, relative } from "node:path";
|
|
22
|
+
|
|
23
|
+
const PACKAGES = join(import.meta.dir, "..", "..");
|
|
24
|
+
|
|
25
|
+
// Directories that hold no shipped styling: dependencies, build output, and anything a package
|
|
26
|
+
// generates. A stylesheet under any of these is not ours to hold to the vocabulary.
|
|
27
|
+
const SKIP = new Set(["node_modules", "dist", "build", ".git", "coverage"]);
|
|
28
|
+
|
|
29
|
+
function cssFiles(dir: string, out: string[] = []): string[] {
|
|
30
|
+
for (const e of readdirSync(dir, { withFileTypes: true })) {
|
|
31
|
+
if (SKIP.has(e.name)) continue;
|
|
32
|
+
const full = join(dir, e.name);
|
|
33
|
+
if (e.isDirectory()) cssFiles(full, out);
|
|
34
|
+
else if (e.name.endsWith(".css")) out.push(full);
|
|
35
|
+
}
|
|
36
|
+
return out;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
// A DEFINITION is `--name:` in declaration position. A reference inside a value never matches,
|
|
40
|
+
// because `var(--x)` and `var(--x, y)` put a `)` or a `,` after the name, never a `:`.
|
|
41
|
+
const DEFINE = /(?:^|[;{\s])(--[a-zA-Z0-9_-]+)\s*:/g;
|
|
42
|
+
const REFERENCE = /var\(\s*(--[a-zA-Z0-9_-]+)/g;
|
|
43
|
+
|
|
44
|
+
// The two honest reasons a reference has no declaration, each with the receipt that makes it
|
|
45
|
+
// checkable. Adding a name here without one turns this guard back into the thing it replaced.
|
|
46
|
+
//
|
|
47
|
+
// 1. WRITTEN AT RUNTIME — a script sets it with style.setProperty, so no stylesheet can declare it.
|
|
48
|
+
// 2. AN INSTANCE KNOB — the component publishes it as a per-use parameter the CALLER supplies
|
|
49
|
+
// inline (`style="--seg: 70%"`), documented in that component's .md. The fallback in the
|
|
50
|
+
// stylesheet is the documented default, which is the one case where a fallback is the design
|
|
51
|
+
// rather than a cover for a missing token.
|
|
52
|
+
const EXTERNALLY_SET = new Map<string, string>([
|
|
53
|
+
["--cmdk-top", "runtime: grain/scripts/cmdk.js:116,130 setProperty"],
|
|
54
|
+
["--cmdk-left", "runtime: grain/scripts/cmdk.js setProperty"],
|
|
55
|
+
["--cmdk-width", "runtime: grain/scripts/cmdk.js setProperty"],
|
|
56
|
+
["--seg", "instance knob: components/atoms/b-meter/b-meter.md:5,16"],
|
|
57
|
+
["--card-min", "instance knob: components/molecules/card/card.md:4"],
|
|
58
|
+
["--gallery-min", "instance knob: components/molecules/gallery/gallery.md:8,48"],
|
|
59
|
+
["--gallery-ratio", "instance knob: components/molecules/gallery/gallery.md:8,48"],
|
|
60
|
+
["--media-ratio", "instance knob: components/molecules/media-card/media-card.md:6,76"],
|
|
61
|
+
["--doc-frame-height", "instance knob: components/molecules/doc-frame/doc-frame.md:47"],
|
|
62
|
+
["--rail-icon-col", "instance knob: components/molecules/nav-item/nav-item.md:4"],
|
|
63
|
+
["--draw-len", "instance knob: components/organisms/presentation/presentation.md:82"],
|
|
64
|
+
]);
|
|
65
|
+
const SET_IN_JS = new Set<string>(EXTERNALLY_SET.keys());
|
|
66
|
+
|
|
67
|
+
// Comments are blanked, not deleted, so line numbers survive for the report. This is not a nicety:
|
|
68
|
+
// the first run of this check reported --ok and --warn as still-undefined in crumb.css, and they
|
|
69
|
+
// were, in a comment explaining that they had just been removed. A checker that reads prose finds
|
|
70
|
+
// defects that are not there, which costs more trust than the ones it catches.
|
|
71
|
+
const decomment = (src: string) =>
|
|
72
|
+
src.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " "));
|
|
73
|
+
|
|
74
|
+
function scan(re: RegExp, src: string): string[] {
|
|
75
|
+
const found: string[] = [];
|
|
76
|
+
for (const m of src.matchAll(re)) found.push(m[1]);
|
|
77
|
+
return found;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
test("every var(--token) a stylesheet reads is defined by some stylesheet", () => {
|
|
81
|
+
const files = cssFiles(PACKAGES);
|
|
82
|
+
expect(files.length).toBeGreaterThan(0); // a silent empty sweep would pass forever
|
|
83
|
+
|
|
84
|
+
const defined = new Set<string>(SET_IN_JS);
|
|
85
|
+
for (const f of files) for (const name of scan(DEFINE, decomment(readFileSync(f, "utf8")))) defined.add(name);
|
|
86
|
+
|
|
87
|
+
const undefinedRefs: string[] = [];
|
|
88
|
+
for (const f of files) {
|
|
89
|
+
const src = decomment(readFileSync(f, "utf8"));
|
|
90
|
+
src.split("\n").forEach((line, i) => {
|
|
91
|
+
for (const name of scan(REFERENCE, line)) {
|
|
92
|
+
if (!defined.has(name)) undefinedRefs.push(`${relative(PACKAGES, f)}:${i + 1}: ${name}`);
|
|
93
|
+
}
|
|
94
|
+
});
|
|
95
|
+
}
|
|
96
|
+
expect([...new Set(undefinedRefs)]).toEqual([]);
|
|
97
|
+
});
|