@jflamb/ledger 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0 — 2026-07-13
+
+Initial release, implementing the Ledger v2 foundations specification.
+
+- Layer-1 primitives (theme-varying) and layer-2 semantic aliases (theme-stable); components consume only layer 2.
+- Light, dark (media query + `data-theme` override), high-contrast, and print themes.
+- Status semantics: critical (red, failure/blocker only), attention (amber), info/waiting (blue), neutral/done (grey). Viridian is brand & interactive only.
+- Three type roles: `--font-prose` (serif), `--font-ui` (system sans), `--font-mono`.
+- 4px spacing grid including `--space-5` (20px); `--control-min-block-size: 48px` as its own token.
+- Contextual radii: static 0, tag 2px, control 6px, selectable 8px, pill 999px. `--shadow-overlay` for overlays only.
+- Contrast gate (`npm test`): 69 checks across three themes, parsed from the shipped `ledger.css`.
+
+### Deviation from the v2 spec document
+
+- `--rule-strong` darkened from the spec's `#99a094 / #4d564a` to **`#7d857b` (light) / `#6a7366` (dark)**: the gate measured the spec values at ~2.4:1 against paper, below the 3:1 requirement for interactive control borders. First bug caught by the gate, before first release. The spec document should be updated to match.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaime Lamb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# Ledger
+
+Ledger is the shared CSS foundation for [jflamb.com](https://jflamb.com), [Assistant Workbench](https://assistant.jflamb.com), and the [Retirement Dashboard](https://retirement.jflamb.com). It gives the three products one visual identity: ink on warm paper, a viridian brand, serif prose, mono figures, and rules instead of decorative shadows.
+
+The package is intentionally small. It provides versioned design tokens, themes, accessibility defaults, and a stable contract for site-local components. It does not force the three products into one component library.
+
+## Install
+
+```sh
+npm install @jflamb/ledger
+```
+
+Until the first npm release is published, projects can install the package directly from this public repository:
+
+```sh
+npm install github:jflamb/ledger
+```
+
+Import the stylesheet from application CSS:
+
+```css
+@import "@jflamb/ledger/ledger.css";
+```
+
+Or import it from JavaScript when the bundler handles CSS:
+
+```js
+import "@jflamb/ledger/ledger.css";
+```
+
+For a site without npm tooling, use a version-pinned CDN URL or vendor the file into the site repository:
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@jflamb/ledger@0.1.0/ledger.css">
+```
+
+Pin the version in production. Do not load an unversioned `latest` URL.
+
+## Use semantic tokens
+
+Site components should use semantic roles rather than palette values:
+
+```css
+.panel {
+  color: var(--color-text-primary);
+  background: var(--color-surface-panel);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-static);
+  padding: var(--space-4);
+}
+
+.primary-action {
+  min-block-size: var(--control-min-block-size);
+  color: var(--color-text-on-action);
+  background: var(--color-action);
+  border-radius: var(--radius-control);
+}
+
+.primary-action:focus-visible {
+  outline: var(--focus-ring);
+  outline-offset: var(--focus-ring-offset);
+}
+```
+
+Palette primitives such as `--viridian` and `--paper` are implementation details. Keeping components on semantic tokens lets Ledger improve contrast or rebalance themes without requiring component rewrites.
+
+## Rules of consumption
+
+1. **Components consume only layer-2 semantic tokens** (`--color-*`, `--font-*`, `--text-*`, `--space-*`, `--radius-*`, `--control-*`, `--focus-*`, `--shadow-*`). Layer-1 primitives (`--paper`, `--ink`, `--viridian`, …) are private to `ledger.css` and are the only values that change per theme.
+2. **Color never carries meaning alone.** Every status has a text label; selection changes border weight and adds a check, not just a fill.
+3. **Square is static, round is interactive.** `--radius-static` for panels and tables; `--radius-control` / `--radius-selectable` mark what can be operated.
+4. **Shadows are for overlays only** (`--shadow-overlay`): menus, tooltips, dialogs. Static grouping uses rules and the one-step paper raise.
+5. **Type roles:** `--font-prose` (serif) for display and explanatory text, `--font-ui` (system sans) for controls/navigation/dense labels, `--font-mono` for figures, dates, codes, and short statuses (with `font-variant-numeric: tabular-nums`).
+6. Site-local tokens (e.g. the dashboard's `--chart-*`) may alias down to Ledger tokens; they may not redefine shared names.
+
+## Token families
+
+- `--color-*`: text, surfaces, borders, actions, focus, and statuses
+- `--font-*`: prose, interface, and numeric roles
+- `--text-*`: type scale
+- `--space-*`: 4px spacing scale
+- `--radius-*`: static, tag, control, selectable, and pill shapes
+- `--control-*`: interaction sizing
+- `--focus-*`: keyboard focus treatment
+- `--shadow-*`: overlays only
+
+The full token list and values live in [`ledger.css`](./ledger.css).
+
+## Theming
+
+`ledger.css` defines light (default), dark (`prefers-color-scheme` **and** `:root[data-theme="dark"]`, so a manual toggle beats the system), high contrast (`prefers-contrast: more`), and print. The theme preference is shared across subdomains via a first-party cookie — localStorage is origin-scoped and serves only as a same-origin fallback:
+
+```js
+// set on toggle — readable by every *.jflamb.com origin
+document.cookie =
+  "jflamb-theme=dark; Domain=.jflamb.com; Path=/; Max-Age=31536000; SameSite=Lax; Secure";
+
+// no-flash bootstrap (inline in <head>): cookie → localStorage → system
+const t = document.cookie.match(/(?:^|; )jflamb-theme=(dark|light)/)?.[1]
+       ?? localStorage.getItem("jflamb-theme");
+if (t) document.documentElement.dataset.theme = t;
+```
+
+Use `data-theme="light"` or `data-theme="dark"` for a manual override. Without an override, Ledger follows `prefers-color-scheme`. The stylesheet also includes `prefers-contrast: more` and print values.
+
+## CI
+
+`npm test` runs the contrast gate: it parses `ledger.css` itself and verifies every text-role/surface pair at ≥ 4.5:1 and every interactive-border/focus pair at ≥ 3:1, across light, dark, and high-contrast, and confirms the two dark blocks never diverge. A palette change that regresses accessibility fails the build.
+
+Run the local checks before committing:
+
+```sh
+npm test
+npm run check:package
+```
+
+`npm run sync:site -- /path/to/jflamb.com` vendors the canonical stylesheet into a zero-tooling site. `npm run check:drift -- /path/to/jflamb.com` verifies that copy byte-for-byte.
+
+## Versioning
+
+Semver. Renaming or removing a primitive or semantic token is **major**; adding or re-pointing a semantic alias is **minor**; value tweaks that pass the gate are **patch**.
+
+## Publishing
+
+1. Update `version` in `package.json` and add a dated entry to `CHANGELOG.md`.
+2. Merge the change to `main`.
+3. Create a GitHub release whose tag exactly matches `v<package version>`.
+4. The `publish` workflow validates the tag, reruns the accessibility and package checks, and publishes the public package to npm with provenance.
+
+The repository needs an npm automation token stored as the `NPM_TOKEN` Actions secret. Publishing is intentionally tied to a GitHub release; ordinary pushes and pull requests cannot publish packages.
+
+## License
+
+[MIT](./LICENSE)

package/ledger.css

@@ -0,0 +1,169 @@
+/* ═══════════════════════════════════════════════════════════════════
+   @jflamb/ledger · v0.1.0
+   Design tokens for jflamb.com, assistant.jflamb.com, retirement.jflamb.com
+   Source of truth: this repo. Spec: see README.
+   Components consume ONLY layer-2 semantic tokens (--color-*, --font-*,
+   --text-*, --space-*, --radius-*, --control-*, --focus-*, --shadow-*).
+   Layer-1 primitives are theme-varying and private to this file.
+   ═══════════════════════════════════════════════════════════════════ */
+
+:root {
+  color-scheme: light dark;
+
+  /* ── layer 1 · primitives (theme-varying) ─────────────────────── */
+  --paper: #f6f3eb;
+  --paper-raised: #fcfaf4;
+  --ink: #182320;
+  --ink-soft: #4c564f;
+  --graphite: #666d63;        /* small-text tertiary · >=4.5:1 on both papers */
+  --faint: #878e86;           /* decoration + disabled text ONLY */
+  --rule: #c8cbc0;            /* hairline dividers, static panel borders */
+  --rule-strong: #7d857b;     /* interactive borders · >=3:1 on both papers */
+  --viridian: #1d5c46;
+  --viridian-deep: #143f30;
+  --viridian-wash: #e6efe8;
+  --red: #a6301f;   --red-wash: #f6e9e5;
+  --amber: #8a5a12; --amber-wash: #f3ecdd;
+  --blue: #40618d;  --blue-wash: #e8edf4;
+
+  /* ── layer 2 · semantics (theme-stable · components consume these) ── */
+  --color-text-primary: var(--ink);
+  --color-text-secondary: var(--ink-soft);
+  --color-text-tertiary: var(--graphite);
+  --color-text-disabled: var(--faint);
+  --color-text-on-action: var(--paper);
+  --color-surface-page: var(--paper);
+  --color-surface-panel: var(--paper-raised);
+  --color-surface-selected: var(--viridian-wash);
+  --color-border: var(--rule);
+  --color-border-interactive: var(--rule-strong);
+  --color-action: var(--viridian);
+  --color-action-hover: var(--viridian-deep);
+  --color-link: var(--viridian);
+  --color-focus: var(--blue);
+  --color-status-critical: var(--red);
+  --color-status-critical-surface: var(--red-wash);
+  --color-status-attention: var(--amber);
+  --color-status-attention-surface: var(--amber-wash);
+  --color-status-info: var(--blue);
+  --color-status-info-surface: var(--blue-wash);
+  --color-status-neutral: var(--ink-soft);
+  --color-status-neutral-surface: var(--paper-raised);
+
+  /* ── type roles ──────────────────────────────────────────────── */
+  --font-prose: Charter, "Bitstream Charter", "Iowan Old Style", Georgia, serif;
+  --font-ui: system-ui, "Segoe UI", -apple-system, "Helvetica Neue", sans-serif;
+  --font-mono: ui-monospace, "Cascadia Mono", "SF Mono", Menlo, Consolas, monospace;
+
+  /* ── scales ──────────────────────────────────────────────────── */
+  --text-xs: 0.72rem;
+  --text-sm: 0.85rem;
+  --text-base: 1rem;
+  --text-lg: 1.15rem;
+  --text-xl: 1.45rem;
+  --text-2xl: 1.9rem;
+  --text-hero: clamp(3rem, 9vw, 8.5rem);
+
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-5: 20px;
+  --space-6: 24px;
+  --space-8: 32px;
+  --space-12: 48px;
+  --space-16: 64px;
+
+  /* ── shape & interaction ─────────────────────────────────────── */
+  --radius-static: 0;         /* read, not operated */
+  --radius-tag: 2px;          /* status tags, badges, tooltips */
+  --radius-control: 6px;      /* buttons, inputs, segmented controls */
+  --radius-selectable: 8px;   /* selectable cards, alternative choosers */
+  --radius-pill: 999px;       /* filter chips (site-local, sparingly) */
+  --control-min-block-size: 48px;
+  --focus-ring: 2px solid var(--color-focus);
+  --focus-ring-offset: 2px;
+  --shadow-overlay: 0 8px 28px rgba(10, 18, 14, 0.18); /* overlays ONLY */
+}
+
+/* ── dark · system preference ─────────────────────────────────── */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --paper: #10150f;
+    --paper-raised: #171d16;
+    --ink: #e8e6d9;
+    --ink-soft: #adb3a6;
+    --graphite: #868d81;
+    --faint: #6d746a;
+    --rule: #333b31;
+    --rule-strong: #6a7366;
+    --viridian: #79c4a0;
+    --viridian-deep: #a4dcc0;
+    --viridian-wash: #1c2b22;
+    --red: #e08268;   --red-wash: #2e1c16;
+    --amber: #d3a355; --amber-wash: #2b2312;
+    --blue: #8aa8cf;  --blue-wash: #171f2b;
+    --shadow-overlay: 0 8px 28px rgba(0, 0, 0, 0.5);
+  }
+}
+
+/* ── manual theme · beats the media query ─────────────────────── */
+:root[data-theme="dark"] {
+  --paper: #10150f;
+  --paper-raised: #171d16;
+  --ink: #e8e6d9;
+  --ink-soft: #adb3a6;
+  --graphite: #868d81;
+  --faint: #6d746a;
+  --rule: #333b31;
+  --rule-strong: #6a7366;
+  --viridian: #79c4a0;
+  --viridian-deep: #a4dcc0;
+  --viridian-wash: #1c2b22;
+  --red: #e08268;   --red-wash: #2e1c16;
+  --amber: #d3a355; --amber-wash: #2b2312;
+  --blue: #8aa8cf;  --blue-wash: #171f2b;
+  --shadow-overlay: 0 8px 28px rgba(0, 0, 0, 0.5);
+}
+:root[data-theme="light"] {
+  --paper: #f6f3eb;
+  --paper-raised: #fcfaf4;
+  --ink: #182320;
+  --ink-soft: #4c564f;
+  --graphite: #666d63;
+  --faint: #878e86;
+  --rule: #c8cbc0;
+  --rule-strong: #7d857b;
+  --viridian: #1d5c46;
+  --viridian-deep: #143f30;
+  --viridian-wash: #e6efe8;
+  --red: #a6301f;   --red-wash: #f6e9e5;
+  --amber: #8a5a12; --amber-wash: #f3ecdd;
+  --blue: #40618d;  --blue-wash: #e8edf4;
+  --shadow-overlay: 0 8px 28px rgba(10, 18, 14, 0.18);
+}
+
+/* ── high contrast · system-level (promoted from jflamb.com) ──── */
+@media (prefers-contrast: more) {
+  :root {
+    --paper: #ffffff;
+    --paper-raised: #ffffff;
+    --ink: #081214;
+    --ink-soft: #1c2a26;
+    --graphite: #2e3a35;
+    --rule: #081214;
+    --rule-strong: #081214;
+    --viridian: #143f30;
+    --viridian-deep: #0c2a1f;
+  }
+}
+
+/* ── print ────────────────────────────────────────────────────── */
+@media print {
+  :root {
+    --paper: #ffffff;
+    --paper-raised: #ffffff;
+    --ink: #000000;
+    --shadow-overlay: none;
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@jflamb/ledger",
+  "version": "0.1.0",
+  "description": "Ledger — design tokens for jflamb.com, assistant.jflamb.com, and retirement.jflamb.com. Ink on warm paper, viridian brand, semantic tokens underneath.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jflamb/ledger.git"
+  },
+  "homepage": "https://github.com/jflamb/ledger#readme",
+  "bugs": {
+    "url": "https://github.com/jflamb/ledger/issues"
+  },
+  "keywords": [
+    "css",
+    "design-system",
+    "design-tokens",
+    "themes",
+    "accessibility"
+  ],
+  "style": "ledger.css",
+  "exports": {
+    ".": "./ledger.css",
+    "./ledger.css": "./ledger.css"
+  },
+  "files": [
+    "ledger.css",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "scripts": {
+    "test": "node scripts/check-contrast.mjs",
+    "check:package": "npm pack --dry-run",
+    "sync:site": "node scripts/sync-site.mjs",
+    "check:drift": "node scripts/check-drift.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT"
+}