@tjakoen/grain 0.1.22 → 0.1.23

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.
@@ -10,6 +10,14 @@
10
10
  line-height: var(--leading-normal);
11
11
  }
12
12
 
13
+ /* diagram variant: an inline SVG rather than an <img>. MILL emits this for a rendered
14
+ mermaid fence. The SVG carries token references, so it re-colors with the theme; the only
15
+ job here is fitting it to the column and letting a wide flowchart scroll rather than
16
+ shrink to unreadable. No caption: a diagram fence has no caption source, and the prose
17
+ convention (an italic line under the figure) stays. */
18
+ .figure[data-variant="diagram"] { max-width: 100%; overflow-x: auto; }
19
+ .figure[data-variant="diagram"] svg { display: block; max-width: 100%; height: auto; }
20
+
13
21
  /* clipped-photo variant: a hard editorial clip instead of a straight rectangle */
14
22
  .figure[data-variant="clipped"] img { border: 0; clip-path: polygon(0 0, 100% 0, 100% 94%, 96% 100%, 0 100%); }
15
23
 
@@ -18,3 +18,15 @@ composed by hand, so nothing data-binds it. Images never overflow the column.
18
18
  <img src="/assets/figure-sample.svg" alt="The same image, clipped">
19
19
  </figure>
20
20
  ```
21
+
22
+ ## Diagram
23
+ Holds an inline SVG instead of an image. MILL emits this for a rendered mermaid fence, with the
24
+ SVG's colors written as token references so the diagram follows both theme axes without being
25
+ re-rendered. A diagram wider than the column scrolls rather than shrinking to unreadable.
26
+
27
+ ```html
28
+ <figure class="figure" data-variant="diagram">
29
+ <svg viewBox="0 0 120 40"><rect x="1" y="1" width="118" height="38"
30
+ fill="var(--color-surface)" stroke="var(--color-line)"></rect></svg>
31
+ </figure>
32
+ ```
@@ -0,0 +1,51 @@
1
+ /* molecules/readiness — a verdict over its evidence: whether a set of boundary conditions
2
+ holds, the one line saying why, and what is still in the way. The generic shape behind
3
+ "ready to deploy", "ready to release", "ready to hand off". CSS-only (CONVENTIONS §4):
4
+ composed by hand, nothing data-binds it.
5
+
6
+ Parent context: none required. It fills its container and carries no width of its own —
7
+ drop it inside a `.card` for a bordered tile, or leave it bare in a panel.
8
+
9
+ Composition: the evidence rows are a `status-list`, NOT a shape this component invents.
10
+ A readiness block that grows its own row markup is the thing to avoid — the marks, the
11
+ in-flight lifecycle and the per-row `data-surface` hook all already live there.
12
+
13
+ This is a READOUT, not an ask. It reports state and stops. A closed-set question with
14
+ options and an escape belongs on CRUMB's decision ask, and having two surfaces put the
15
+ same question to someone is the failure DECISIONS names outright. */
16
+
17
+ .readiness { display: flex; flex-direction: column; gap: var(--space-2); }
18
+
19
+ /* The verdict sits at display scale on purpose: grade texture only reads at >= --text-2xl
20
+ (CLAUDE.md lesson 4), and a verdict is exactly the line an AI might compose — so put
21
+ `data-grade="grain"` here and the provenance is legible instead of theoretical. */
22
+ .readiness__verdict {
23
+ font-size: var(--text-2xl);
24
+ line-height: var(--leading-tight);
25
+ color: var(--color-fg);
26
+ }
27
+
28
+ .readiness__why {
29
+ font-size: var(--text-sm);
30
+ line-height: var(--leading-normal);
31
+ color: var(--color-muted);
32
+ }
33
+
34
+ /* State reads as ink level and edge weight, never hue — the same rule stat-tile follows.
35
+ `blocked` earns a solid-ink edge because it is the one meant to stop you; `waiting`
36
+ recedes; `ready` and the default are identical, since a healthy verdict needs no
37
+ shouting. */
38
+ .readiness[data-state="blocked"] {
39
+ border-left: 2px solid var(--color-fg);
40
+ padding-left: var(--space-3);
41
+ }
42
+ .readiness[data-state="waiting"] .readiness__verdict { color: var(--color-muted); }
43
+
44
+ /* In transit — the detector has not finished deciding. The shared idiom keyed off
45
+ `data-commit="pending"` and an ancestor `[data-grade="grain"]`, expressed here as a
46
+ dashed leading edge, never a bespoke "loading" state. */
47
+ .readiness[data-commit="pending"],
48
+ [data-grade="grain"] .readiness[data-commit="pending"] {
49
+ border-left: 2px dashed var(--color-fg);
50
+ padding-left: var(--space-3);
51
+ }
@@ -0,0 +1,91 @@
1
+ # Readiness
2
+
3
+ A verdict over its evidence: whether a set of boundary conditions holds, one line saying why,
4
+ and what is still in the way. The generic shape behind "ready to deploy", "ready to release",
5
+ "ready to hand off" — a run that has finished checking and now has to tell someone.
6
+
7
+ It is a **readout, not an ask.** It reports and stops. A closed-set question with options and an
8
+ escape hatch belongs on CRUMB's decision ask; two surfaces putting the same question to the same
9
+ person is a failure mode rather than thoroughness.
10
+
11
+ Composition note: no parent context is required — it fills its container and carries no width of
12
+ its own, so it sits inside a `card` or bare in a panel. The evidence rows are a **`status-list`**,
13
+ not markup this component invents: the marks, the in-flight lifecycle and the per-row
14
+ `data-surface` hook already live there. Counts alongside the verdict are `stat` tiles, laid out by
15
+ the parent.
16
+
17
+ State is an attribute (`data-state`), and reads as ink level and edge weight, never hue.
18
+
19
+ ## Ready
20
+ ```html
21
+ <div class="readiness" data-state="ready">
22
+ <span class="readiness__verdict">Ready to hand off</span>
23
+ <span class="readiness__why">Gates green, plan synced, nothing in flight.</span>
24
+ <ul class="status-list">
25
+ <li class="status-list__item">
26
+ <span class="status-list__mark">✓</span>
27
+ <span class="status-list__title">gates green</span>
28
+ <span class="status-list__meta">check · test</span>
29
+ </li>
30
+ <li class="status-list__item">
31
+ <span class="status-list__mark">✓</span>
32
+ <span class="status-list__title">plan synced</span>
33
+ <span class="status-list__meta">PLAN.md</span>
34
+ </li>
35
+ </ul>
36
+ </div>
37
+ ```
38
+
39
+ ## Blocked
40
+ The one state meant to stop you, so it takes a solid-ink edge. What blocks goes in the rows; the
41
+ verdict says only that something does.
42
+ ```html
43
+ <div class="readiness" data-state="blocked">
44
+ <span class="readiness__verdict">Not yet</span>
45
+ <span class="readiness__why">Two conditions still hold it open.</span>
46
+ <ul class="status-list">
47
+ <li class="status-list__item">
48
+ <span class="status-list__mark">✕</span>
49
+ <span class="status-list__title">tests failing</span>
50
+ <span class="status-list__meta">3 of 663</span>
51
+ </li>
52
+ <li class="status-list__item" data-state="waiting">
53
+ <span class="status-list__mark">·</span>
54
+ <span class="status-list__title">plan not synced</span>
55
+ <span class="status-list__meta">PLAN.md</span>
56
+ </li>
57
+ </ul>
58
+ </div>
59
+ ```
60
+
61
+ ## Waiting
62
+ Nothing has been checked yet, so the verdict recedes rather than claiming a result.
63
+ ```html
64
+ <div class="readiness" data-state="waiting">
65
+ <span class="readiness__verdict">Not checked</span>
66
+ <span class="readiness__why">No gate has run this session.</span>
67
+ </div>
68
+ ```
69
+
70
+ ## With counts
71
+ Tiles are laid out by the parent, never by a wrapper inside the component.
72
+ ```html
73
+ <div class="readiness" data-state="blocked">
74
+ <span class="readiness__verdict">Not yet</span>
75
+ <span class="readiness__why">Work is uncommitted.</span>
76
+ <div style="display:flex;gap:var(--space-3)">
77
+ <div class="stat" data-tone="bad"><span class="stat__value">12</span><span class="stat__label">uncommitted</span></div>
78
+ <div class="stat" data-tone="muted"><span class="stat__value">1</span><span class="stat__label">unpushed</span></div>
79
+ </div>
80
+ </div>
81
+ ```
82
+
83
+ ## In transit (the detector is still deciding)
84
+ The shared in-flight idiom, not a bespoke loading state. The verdict sits at display scale
85
+ precisely so that an AI-composed line reads as grain rather than claiming to be checked fact.
86
+ ```html
87
+ <div class="readiness" data-commit="pending">
88
+ <span class="readiness__verdict" data-grade="grain">Checking…</span>
89
+ <span class="readiness__why">Reading the gate log.</span>
90
+ </div>
91
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tjakoen/grain",
3
- "version": "0.1.22",
3
+ "version": "0.1.23",
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",
@@ -42,8 +42,12 @@
42
42
  --paper-2: #E8E6DF; /* subtle hover surface */
43
43
  --panel: #E8E6DF; /* grouped "sheet" — a hair brighter than the page */
44
44
  --ink: #1C1B17; /* primary text, filled dots, rules */
45
- --ink-muted: #6E6C64; /* secondary text, section labels */
46
- --ink-faint: #ABA89F; /* fading insights, empty/future dots */
45
+ /* The two quiet tiers, and the line between them is a contract, not a shade. MUTED carries text
46
+ a reader is meant to read, so it clears WCAG AA (4.5:1) on --paper; it was #6E6C64 and measured
47
+ 3.98:1, which is why it moved. FAINT is decoration: fading insights, empty and future dots. It
48
+ does NOT clear AA and is not meant to, so nothing a reader needs may be painted with it. */
49
+ --ink-muted: #65635B; /* secondary text, section labels. 4.55:1 on --paper */
50
+ --ink-faint: #ABA89F; /* fading insights, empty/future dots. DECORATIVE ONLY */
47
51
  --hairline: #1C1B17; /* solid rules (under headlines) */
48
52
  --line-soft: rgba(28, 27, 23, .14); /* translucent border for quiet grouping */
49
53