@half-built/css 0.1.0 → 0.3.0

package/README.md

@@ -9,3 +9,83 @@ Extracted from the private `half-built-robots-blog` repository, where
 this CSS was built and used in production. The extraction review that
 checked it for blog-specific assumptions before the move is the design
 record for this package.
+
+## Usage
+
+Import order matters. In your base layout, load the layer declaration
+first, then tokens, then the base entry, then the patterns you use:
+
+```js
+import "@half-built/css/layers";
+import "@half-built/css/tokens";
+import "@half-built/css";
+import "@half-built/css/patterns.css";
+import "@half-built/css/prose.css";
+import "@half-built/css/code.css";
+```
+
+The island stylesheets (`lightbox.css`, `plate-modal.css`,
+`path-player.css`) load the same way, from whichever layout or
+component mounts their island. The `.` entry is the base layer (reset,
+shell, link-tip, scroll-top); it is not the whole system, which is why
+the explicit order above exists.
+
+The breakpoints are `@custom-media` rules, so your build needs
+`postcss-custom-media` with `@csstools/postcss-global-data` fed the
+breakpoints file:
+
+```js
+// postcss.config.mjs
+import { fileURLToPath } from "node:url";
+const breakpoints = fileURLToPath(
+  import.meta.resolve("@half-built/css/tokens/breakpoints.css"),
+);
+// plugins: [postcssGlobalData({ files: [breakpoints] }), postcssCustomMedia()]
+```
+
+Sites add their own `site` cascade layer after these imports for local
+overrides. The layer order in `layers.css` already declares it.
+
+## Theming
+
+The entire third-party theming surface is six primitives: two brand
+families, three stops each. Override any or all of them in your
+`site` layer; every other token in the system derives from these six.
+
+| Variable | Default | Role |
+|---|---|---|
+| `--brand-1-500` | `#ffaa3c` | Base: lines and fills, dark-theme text ink, light-theme focus ring. |
+| `--brand-1-600` | `#d1820f` | Chart kin; light-theme track-x. |
+| `--brand-1-700` | `#a36300` | Text ink on the light paper. |
+| `--brand-2-300` | `#8ee6f2` | Light kin: dark-theme text ink and track-y. |
+| `--brand-2-500` | `#3cc7dd` | Base: lines and fills, dark-theme focus ring. |
+| `--brand-2-700` | `#1a7f90` | Text ink on the light paper. |
+
+An override looks like this:
+
+```css
+/* half-built palette override, generated at ui.half-built-robots.com */
+:root {
+  --brand-1-500: #3cc74a;
+  --brand-1-600: #2a9c38;
+  --brand-1-700: #1c6b27;
+  --brand-2-300: #a0e8b0;
+  --brand-2-500: #34b350;
+  --brand-2-700: #1f7a38;
+}
+```
+
+A derived ramp is built to three thresholds: the 700 stops clear 4.5:1
+against white, the 300 stop clears 4.5:1 against `#111111`, and the
+600 stop clears 3:1 against white. The shipped defaults clear all
+three (the 600 stop was retuned to `#d1820f` for the 3:1 non-text
+gate in 0.2.0). These are targets the derivation satisfies, not a
+floor the system enforces on your behalf. If
+you write your own six values instead of deriving them, you own their
+contrast.
+
+The reference site generates a compliant block for you: give it two
+base colors and its palette editor derives the other four stops and
+prints a ready-to-paste override in exactly the shape above. It will
+live at `ui.half-built-robots.com` once deployed; today the source for
+that derivation is `site/src/lib/derive-palette.ts` in this repo.

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@half-built/css",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Design tokens, base, patterns, and prose CSS for the half-built design system.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/curthenrichs/half-built-ui.git",
+    "directory": "packages/css"
+  },
   "type": "module",
   "files": ["src"],
   "dependencies": {
@@ -12,6 +17,7 @@
     ".": "./src/global.css",
     "./layers": "./src/layers.css",
     "./tokens": "./src/tokens.css",
+    "./package.json": "./package.json",
     "./*": "./src/*"
   },
   "publishConfig": { "access": "public" }

package/src/tokens/primitives.css

@@ -36,27 +36,49 @@
     --gray-750: #3a3a3a;
     --gray-400: #9a9a9a;
 
-    /* Accents. amber-500 is the shared accent across the ecosystem;
-       amber-700 is its legible kin for text, tuned here for this site
-       the way cyan-700 was: the amber hue at full saturation, taken
-       down until it clears WCAG AA (4.5:1) as body text on the white
-       surface (4.84) and on the accent's 6% tint (4.66). It replaced
-       #b5680c, a value borrowed from BEADZ that sat at 4.24:1 on white
-       (owner call 2026-09-03; BEADZ is not a source of values). */
-    --amber-500: #ffaa3c;
-    --amber-700: #a36300;
-    /* Second accent, the cyan family (owner request 2026-08-26): chosen
-       to sit where the amber sits, cyan-500 matches amber-500's contrast
-       on both grounds (line and fill, not text on white) and cyan-700
-       is its legible kin for text on the light ground. */
-    --cyan-300: #8ee6f2;
-    --cyan-500: #3cc7dd;
-    --cyan-700: #1a7f90;
+    /* Brand ramps, the entire third-party theming surface. Family 1 is
+       the ecosystem amber by default, family 2 its cyan complement; the
+       names are hue-neutral because a consumer may override all six
+       (spec: docs/superpowers/specs/2026-09-05-reference-site-design.md).
+       500 is the base, 700 its AA text ink on the light paper, 600 the
+       chart kin, 300 the light kin legible as text on the dark ground.
+       Brand-1-700 is tuned here for this site the way brand-2-700 was:
+       the amber hue at full saturation, taken down until it clears WCAG
+       AA (4.5:1) as body text on the white surface (4.84) and on the
+       accent's 6% tint (4.66). It replaced #b5680c, a value borrowed
+       from BEADZ that sat at 4.24:1 on white (owner call 2026-09-03;
+       BEADZ is not a source of values). Family 2 (owner request
+       2026-08-26) was chosen to sit where family 1 sits: brand-2-500
+       matches brand-1-500's contrast on both grounds (line and fill,
+       not text on white) and brand-2-700 is its legible kin for text on
+       the light ground. Brand-1-600 was retuned 2026-09-05 (owner call)
+       from #d98a1f, which sat at 2.76:1 on white: walked down in OKLCH
+       with hue and chroma held until it clears 3:1 as a non-text chart
+       line on the light paper (now 3.04). */
+    --brand-1-500: #ffaa3c;
+    --brand-1-600: #d1820f;
+    --brand-1-700: #a36300;
+    --brand-2-300: #8ee6f2;
+    --brand-2-500: #3cc7dd;
+    --brand-2-700: #1a7f90;
+    /* Code-viewer kin of family 1 (spec 2026-09-06, live code colors):
+       the values the Shiki theme has always baked, promoted to
+       primitives so the code token roles below them can follow a
+       palette override. 300 is a true lightness stop (OKLCH L 0.885,
+       above the 500's 0.804), the family's light kin the way
+       brand-2-300 is. "vivid" is deliberately not a numbered stop: at
+       L 0.684 it sits at the 600's lightness with more chroma
+       (0.159 vs 0.146), so a ramp number would misstate what it is. */
+    --brand-1-300: #ffd18a;
+    --brand-1-vivid: #e07c14;
     --red-800: #7a1f16;
     --red-300: #ff8a7a;
-    --ochre-600: #d98a1f;
     --violet-600: #7a5aa0;
     --violet-300: #b39ad6;
+    /* Fixed system color like red and violet above, so it keeps a hue
+       name: the code comment ink, a dim warm gray that stays put when
+       the brand families are overridden. */
+    --umber-500: #8a7a63;
 
     /* Strokes, spacing, elevation, motion */
     --stroke-1: 1px;

package/src/tokens/theme-dark.css

@@ -23,10 +23,10 @@
 
     /* The bright amber is legible as text on the dark ground, so the
        accent and its ink form collapse to one value here. */
-    --accent-1: var(--amber-500);
-    --accent-1-ink: var(--amber-500);
-    --accent-2: var(--cyan-500);
-    --accent-2-ink: var(--cyan-300);
+    --accent-1: var(--brand-1-500);
+    --accent-1-ink: var(--brand-1-500);
+    --accent-2: var(--brand-2-500);
+    --accent-2-ink: var(--brand-2-300);
     --on-accent-1: var(--black-900);
     --on-accent-2: var(--black-900);
     --error-ink: var(--red-300);
@@ -36,15 +36,23 @@
     --code-bg: var(--ink-900);
     --code-fg: var(--parchment);
     --code-line: var(--ink-800);
+    /* Syntax token roles (spec 2026-09-06): what the Shiki theme bakes
+       as hex, restated as variables so the code-vars transformer can
+       emit tokens that follow a palette override. Identical in both
+       themes because the code surface is always the warm dark block. */
+    --code-token-keyword: var(--brand-1-500);
+    --code-token-function: var(--brand-1-300);
+    --code-token-string: var(--brand-1-vivid);
+    --code-token-comment: var(--umber-500);
 
     --veil: var(--black-a60);
     --mat-line: var(--gray-800);
     /* Keyboard ring: the second accent by night, the first by day
        (owner call 2026-08-26). */
-    --focus-ring: var(--cyan-500);
+    --focus-ring: var(--brand-2-500);
 
-    --track-x: var(--amber-500);
-    --track-y: var(--cyan-300);
+    --track-x: var(--brand-1-500);
+    --track-y: var(--brand-2-300);
     --track-z: var(--violet-300);
 
     /* The subscribe panel inverts by night: a dark panel with an amber
@@ -53,8 +61,8 @@
        2026-08-26). */
     --panel-bg: var(--black-850);
     --panel-ink: var(--parchment);
-    --panel-rule: var(--amber-500);
+    --panel-rule: var(--brand-1-500);
     --panel-error: var(--red-300);
-    --panel-ring: var(--amber-500);
+    --panel-ring: var(--brand-1-500);
   }
 }

package/src/tokens/theme-light.css

@@ -21,13 +21,13 @@
     /* Amber survives inside the code island and as a line or fill
        color; --accent-1-ink is its legible kin for any text on the
        surface (the tagline's box, Callout tip and warning types). */
-    --accent-1: var(--amber-500);
-    --accent-1-ink: var(--amber-700);
+    --accent-1: var(--brand-1-500);
+    --accent-1-ink: var(--brand-1-700);
     /* Second accent (cyan), the amber's complement. Same split: the
        bright value is a line or fill, the dark one is text. No component
        reads it yet; its jobs are an owner decision (2026-08-26). */
-    --accent-2: var(--cyan-500);
-    --accent-2-ink: var(--cyan-700);
+    --accent-2: var(--brand-2-500);
+    --accent-2-ink: var(--brand-2-700);
     /* Text on an accent fill (a hovered or pressed accent button). */
     --on-accent-1: var(--ink-900);
     --on-accent-2: var(--ink-900);
@@ -37,6 +37,14 @@
     --code-bg: var(--ink-900);
     --code-fg: var(--parchment);
     --code-line: var(--ink-800);
+    /* Syntax token roles (spec 2026-09-06): what the Shiki theme bakes
+       as hex, restated as variables so the code-vars transformer can
+       emit tokens that follow a palette override. Identical in both
+       themes because the code surface is always the warm dark block. */
+    --code-token-keyword: var(--brand-1-500);
+    --code-token-function: var(--brand-1-300);
+    --code-token-string: var(--brand-1-vivid);
+    --code-token-comment: var(--umber-500);
 
     /* Plate-modal chrome (spec 2026-07-30): veil over the blurred page,
        and the viewbox mat one step lighter than --hairline. Values
@@ -45,16 +53,16 @@
     --mat-line: var(--gray-075);
 
     /* Path-player timeline series (spec 2026-08-22, owner question 1). */
-    --track-x: var(--ochre-600);
+    --track-x: var(--brand-1-600);
     /* The second data track is the second accent (owner call 2026-08-26). */
-    --track-y: var(--cyan-500);
+    --track-y: var(--brand-2-500);
     --track-z: var(--violet-600);
 
     /* The subscribe panel, the amber block that bridges every property
        back to the blog. By day: amber ground, warm-dark ink and rule, a
        dark button with white text. By night the panel inverts (see
        theme-dark.css) so the button stays the brightest thing in it. */
-    --panel-bg: var(--amber-500);
+    --panel-bg: var(--brand-1-500);
     --panel-ink: var(--ink-900);
     --panel-rule: var(--ink-900);
     --panel-error: var(--red-800);
@@ -66,7 +74,7 @@
        so it reads on both grounds and never means the same as hover. */
     /* Keyboard ring: the first accent by day, the second by night
        (owner call 2026-08-26). */
-    --focus-ring: var(--amber-500);
+    --focus-ring: var(--brand-1-500);
 
     /* The signature stroke: 2px here, 3px on BEADZ. */
     --stroke: var(--stroke-2);