@brignano/design 0.3.0 → 0.4.0

package/DECISIONS.md

@@ -299,7 +299,12 @@ other theme.
   needs a colour resolves it through `getComputedStyle` on an element
   (DESIGN.md §11). ADR-0002's advice that `chart-colors.ts` read the custom
   properties still stands, but by that route.
-- Consumers shouldn't wrap tokens in `color-mix()`; washes are tokens.
+- Consumers shouldn't wrap tokens in `color-mix()`; washes are tokens. The
+  first consumer that needed one (`life`'s sticky bars) got `--surface-sticky`
+  in 0.3.1 rather than a local mix.
+- A build that lowers `light-dark()` for older browsers (Lightning CSS, inside
+  Next.js and Vite) fixes the theme at `:root`, losing scoped theming. Found in
+  `brignano.io`; consumers set `browserslist` to the floor (DESIGN.md §11).
 - Not a token rename and not a visual change, so a patch release.
 
 

package/DESIGN.md

@@ -135,6 +135,10 @@ for cards, `--radius-lg` for hero surfaces.
 a shadow (`--shadow-1/2/3`). Dark mode does not use borders — surfaces get
 *lighter* with elevation. This is why `--line` can stay nearly invisible in dark.
 
+**Sticky chrome** — a header or toolbar that content scrolls under — is
+`--surface-sticky` with `backdrop-filter: blur(8px)`: 92% of the card in light,
+of the page ground in dark, so it reads as the surface it sits on, not a new layer.
+
 ## 7. Motion
 
 **Content is visible by default. Motion is progressive enhancement layered on top
@@ -241,11 +245,30 @@ Two consequences for code that touches tokens directly:
   Re-read it when the theme changes.
 - **Don't wrap a token in `color-mix()` or `light-dark()`.** Nesting is valid CSS,
   but not every engine has been verified to resolve it. If you need a wash, it's
-  a token (`--*-surface`, `--*-line`); if it isn't, add it here.
+  a token (`--*-surface`, `--*-line`, `--surface-sticky`); if it isn't, add it here.
 
 Needs Chrome/Edge 123, Firefox 120, Safari 17.5 or later (all shipped by May 2024).
 An older browser drops every colour token and renders unstyled rather than wrong.
 
+### Build tools that lower `light-dark()`
+
+A CSS pipeline that targets browsers older than that floor rewrites
+`light-dark()` into a fallback. Lightning CSS (inside Next.js, Vite, Parcel)
+turns each token into `var(--lightningcss-light, …) var(--lightningcss-dark, …)`
+and flips those two variables wherever `color-scheme` changes. The tokens
+resolve on `:root`, so the side is fixed there. Page-wide theming still works,
+but **`data-theme` on an inner element stops re-theming that section.**
+
+The fix is to target the same floor the tokens need, which leaves `light-dark()`
+alone. In the consumer's `package.json`:
+
+```json
+"browserslist": ["chrome >= 123", "edge >= 123", "firefox >= 120", "safari >= 17.5"]
+```
+
+Verified with Lightning CSS: older targets lower the tokens; these targets
+pass `light-dark(#076bd3, #6ba5f3)` through untouched.
+
 ### Tailwind
 
 Tailwind's dark variant keys off a `.dark` class; these tokens key off
@@ -283,3 +306,47 @@ Hardcoded values silently survive a theme change. `life`'s status pills carried
 literal greys for months and would have stayed light grey in dark mode.
 `brignano.io` carried four literal violet hexes plus ~15 `violet-*` utilities,
 which is why changing the accent was a migration rather than a one-line edit.
+
+## 13. Product pages
+
+A product's marketing page is one argument and one ask. `product-page.css` is its
+structure; `previews/product-page.html` is the skeleton to copy. Import it after
+the tokens, put `tier-marketing` on `<html>` and `pp` on `<body>` (or a wrapper).
+
+```css
+@import '@brignano/design/tokens.css';
+@import '@brignano/design/product-page.css';
+```
+
+The order is fixed, because each band answers the question the last one raised:
+
+1. **Header** (`.pp-header`) — brand, two or three in-page links, the status, the
+   primary action. Sticky, on `--surface-sticky`.
+2. **Hero** (`.pp-hero`) — the status, a one-line **thesis** (`.pp-thesis`), a
+   subhead of one or two sentences, the primary action and one secondary, and a
+   **proof slot** (`.pp-media`). The proof is the product itself where it can be
+   (a live demo), else a real screenshot. Never stock imagery.
+3. **Story** (`ol.pp-story` of `.pp-chapter`) — three or four numbered chapters,
+   usually *the problem*, *how it works*, *who it's for*, *why now*. Each is a mono
+   label (`.pp-label`, numbered `01 /` by the list, so reordering renumbers), a
+   headline that is a sentence, a short body, and optionally `.pp-points` (two to
+   four ruled columns) or a `.pp-figure`.
+4. **Close** (`.pp-close`) — the primary action again, with the room a form needs
+   (`.pp-panel`).
+5. **Footer** (`.pp-footer`).
+
+Rules:
+
+- **One primary action per page.** `.pp-button` is that action, everywhere it
+  appears. Anything else is `.pp-button.is-secondary` or a link.
+- **The status is a word with a dot** (`.pp-status`): "Pilot open", "In
+  development". `data-state="open"` takes `--success` (you can join now),
+  `"soon"` takes `--attention`; no attribute stays neutral. The word carries the
+  meaning on its own (§3, never colour alone).
+- **Headlines are sentences.** Calm and declarative, no exclamation marks, no
+  claims the page can't back up.
+- **Restraint carries the style.** Hairlines between chapters, whitespace, the
+  type scale. No gradients, no tinted section backgrounds, no decorative colour.
+
+Every class starts with `.pp-`, so the file sits beside a site's own stylesheet.
+A page can change `--pp-width` (default 1160px) and `--pp-gutter` on `.pp`.

package/README.md

@@ -9,6 +9,7 @@ The shared design system for every brignano surface — `brignano.io`, `life`,
 | [`DECISIONS.md`](./DECISIONS.md) | Why the values are what they are. ADRs. |
 | [`tokens.css`](./tokens.css) | Single source of truth for colour, type, space, shape, motion. |
 | [`tokens.chart.css`](./tokens.chart.css) | Validated categorical palette for data viz. |
+| [`product-page.css`](./product-page.css) | The structure of a product's marketing page: header, thesis hero, numbered story, closing ask. DESIGN.md §13; skeleton in `previews/product-page.html`. |
 | [`previews/`](./previews) | Live swatches. Open one in a browser to see the tokens render. |
 
 ## The shape of it

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brignano/design",
-  "version": "0.3.0",
-  "description": "Shared design system for brignano surfaces — colour, type, space, shape, motion.",
+  "version": "0.4.0",
+  "description": "Shared design system for brignano surfaces \u2014 colour, type, space, shape, motion.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,6 +17,7 @@
   "files": [
     "tokens.css",
     "tokens.chart.css",
+    "product-page.css",
     "tailwind.css",
     "DESIGN.md",
     "DECISIONS.md"
@@ -24,7 +25,8 @@
   "exports": {
     "./tokens.css": "./tokens.css",
     "./tokens.chart.css": "./tokens.chart.css",
-    "./tailwind.css": "./tailwind.css"
+    "./tailwind.css": "./tailwind.css",
+    "./product-page.css": "./product-page.css"
   },
   "sideEffects": [
     "*.css"

package/product-page.css

@@ -0,0 +1,172 @@
+/* product-page.css — the page structure for a product's marketing site.
+ *
+ *   @import '@brignano/design/tokens.css';
+ *   @import '@brignano/design/product-page.css';
+ *   <html class="tier-marketing">
+ *
+ * One page, read top to bottom, that makes one argument and asks for one thing:
+ *
+ *   .pp-header    brand, a few in-page links, the status, the primary action
+ *   .pp-hero      status, a one-line thesis, a subhead, two actions, a proof slot
+ *   .pp-story     3–4 numbered chapters: problem, how it works, who it's for, why now
+ *   .pp-close     the primary action again, with whatever it needs (a form)
+ *   .pp-footer
+ *
+ * The skeleton is previews/product-page.html: copy it, keep the order, replace
+ * the words. Rules (DESIGN.md §13):
+ *
+ *   - One primary action per page (.pp-button). Everything else is secondary.
+ *   - The status is a word with a dot, never a coloured badge on its own.
+ *   - The proof slot is the product itself where possible (a live demo), else a
+ *     real screenshot. No stock imagery, no illustrations of people.
+ *   - Chapters are numbered by the list, so reordering them renumbers them.
+ *
+ * Every class starts with .pp- so it can sit beside a site's own stylesheet.
+ * Colours are tokens only; widths are --pp-width / --pp-gutter, which a page
+ * may override on .pp. */
+
+.pp {
+  --pp-width: 1160px;
+  --pp-gutter: var(--s5);
+  background: var(--bg);
+  color: var(--ink);
+  font: var(--text-base) / 1.6 var(--sans);
+  font-variant-numeric: tabular-nums;
+  -webkit-font-smoothing: antialiased;
+}
+@media (max-width: 560px) { .pp { --pp-gutter: var(--s4); } }
+
+/* The content column every band lines up on. */
+.pp-wrap { max-width: var(--pp-width); margin: 0 auto; padding: 0 var(--pp-gutter); }
+
+/* ── Skip link ─────────────────────────────────────────────────────────── */
+.pp-skip { position: absolute; left: var(--s4); top: -100px; z-index: 20; padding: var(--s2) var(--s3);
+  background: var(--card); color: var(--ink); border-radius: var(--radius-sm); box-shadow: var(--shadow-2); }
+.pp-skip:focus { top: var(--s3); }
+
+/* ── Header ────────────────────────────────────────────────────────────── */
+.pp-header {
+  position: sticky; top: 0; z-index: 10;
+  background: var(--surface-sticky); -webkit-backdrop-filter: blur(8px); backdrop-filter: blur(8px);
+  border-bottom: 1px solid var(--line);
+}
+.pp-header > .pp-wrap { display: flex; align-items: center; gap: var(--s5); min-height: 64px; }
+.pp-brand {
+  display: inline-flex; align-items: center; gap: 10px; color: var(--ink); text-decoration: none;
+  font-weight: 600; font-size: var(--text-lg); letter-spacing: -0.01em;
+}
+.pp-brand img, .pp-brand svg { width: 26px; height: 26px; }
+.pp-nav { display: flex; align-items: center; gap: var(--s5); margin-left: auto; }
+.pp-nav a { color: var(--ink-soft); text-decoration: none; font-size: var(--text-sm); font-weight: 500; }
+.pp-nav a:hover { color: var(--ink); }
+.pp-header-actions { display: flex; align-items: center; gap: var(--s3); }
+.pp-nav + .pp-header-actions { margin-left: 0; }
+.pp-brand + .pp-header-actions { margin-left: auto; }
+@media (max-width: 860px) { .pp-nav { display: none; } .pp-header-actions { margin-left: auto; } }
+@media (max-width: 480px) { .pp-header .pp-status { display: none; } }
+
+/* ── Status ────────────────────────────────────────────────────────────
+   Where the product stands, as a word with a dot: "Pilot open", "In
+   development", "Closed beta". The dot takes a state hue only when the state
+   asks something of the reader (DESIGN.md §3): open = success (you can join),
+   soon = attention (it is coming, watch for it). Without data-state it stays
+   neutral. The word always carries the meaning on its own. */
+.pp-status {
+  display: inline-flex; align-items: center; gap: var(--s2); white-space: nowrap;
+  font: 500 var(--text-xs) / 1 var(--mono); letter-spacing: 0.08em; text-transform: uppercase;
+  color: var(--ink-soft); padding: 6px 10px; border: 1px solid var(--line-strong); border-radius: 999px;
+}
+.pp-status::before { content: ""; width: 7px; height: 7px; border-radius: 50%; background: var(--slate); flex: none; }
+.pp-status[data-state="open"]::before { background: var(--success); box-shadow: 0 0 0 3px var(--success-surface); }
+.pp-status[data-state="soon"]::before { background: var(--attention); box-shadow: 0 0 0 3px var(--attention-surface); }
+
+/* ── Buttons ───────────────────────────────────────────────────────────
+   .pp-button is the page's one primary action. .is-secondary is everything
+   else. Works on <a> and <button>. */
+.pp-button {
+  display: inline-flex; align-items: center; justify-content: center; gap: var(--s2);
+  font: 600 var(--text-base) / 1.2 var(--sans); text-decoration: none; white-space: nowrap; cursor: pointer;
+  padding: 13px 22px; border-radius: 8px; border: 1px solid var(--i);
+  background: var(--i); color: var(--on-i);
+  transition: background-color var(--dur-fast) var(--ease), border-color var(--dur-fast) var(--ease);
+}
+.pp-button:hover { background: var(--i-hover); border-color: var(--i-hover); color: var(--on-i); }
+.pp-button:active { background: var(--i-pressed); border-color: var(--i-pressed); }
+.pp-button.is-secondary { background: transparent; color: var(--ink); border-color: var(--line-control); font-weight: 500; }
+.pp-button.is-secondary:hover { background: var(--surface-hover); color: var(--ink); }
+.pp-button.is-secondary:active { background: var(--surface-active); }
+.pp-button.is-small { font-size: var(--text-sm); padding: 8px 14px; }
+.pp-button:focus-visible { outline: 2px solid var(--i-ink); outline-offset: 2px; }
+.pp-button:disabled { background: var(--i-disabled-bg); border-color: transparent; color: var(--i-disabled-ink); cursor: not-allowed; }
+@media (pointer: coarse) { .pp-button { min-height: 44px; } }
+
+.pp-actions { display: flex; flex-wrap: wrap; align-items: center; gap: var(--s3); margin: 0; }
+.pp-note { margin: var(--s3) 0 0; font-size: var(--text-sm); color: var(--ink-soft); }
+
+/* ── Hero ──────────────────────────────────────────────────────────────
+   Copy on the left, proof on the right; stacked below 960px with the copy
+   first. The thesis is one line of argument, not a tagline. */
+.pp-hero { padding: var(--s8) 0 var(--s8); }
+.pp-hero > .pp-wrap { display: grid; gap: var(--s7); align-items: center; grid-template-columns: minmax(0, 1fr); }
+@media (min-width: 960px) { .pp-hero > .pp-wrap { grid-template-columns: minmax(0, 5fr) minmax(0, 6fr); } }
+.pp-hero .pp-status { margin-bottom: var(--s5); }
+.pp-thesis {
+  font-size: var(--text-4xl); font-weight: 600; line-height: 1.04; letter-spacing: -0.035em;
+  margin: 0 0 var(--s4); max-width: 14ch; text-wrap: balance;
+}
+.pp-subhead { font-size: var(--text-lg); line-height: 1.5; color: var(--ink-soft); margin: 0 0 var(--s6); max-width: 40ch; }
+.pp-media { margin: 0; min-width: 0; }
+
+/* ── Story ─────────────────────────────────────────────────────────────
+   An <ol> of chapters. Each opens on a hairline with "01 / Label" in mono,
+   then a headline that is a sentence, then a short body and an optional
+   figure. Wide screens put the label in its own column. */
+.pp-story { list-style: none; margin: 0; padding: 0; counter-reset: pp-chapter; }
+.pp-chapter { counter-increment: pp-chapter; padding: var(--s8) 0; border-top: 1px solid var(--line); scroll-margin-top: 64px; }
+.pp-chapter > .pp-wrap { display: grid; gap: var(--s4) var(--s7); grid-template-columns: minmax(0, 1fr); }
+@media (min-width: 960px) {
+  .pp-chapter > .pp-wrap { grid-template-columns: minmax(0, 3fr) minmax(0, 9fr); }
+  .pp-chapter-body { grid-column: 2; }
+}
+.pp-label { margin: 0; padding-top: 0.4em; font: 500 var(--text-xs) / 1.4 var(--mono); letter-spacing: 0.08em; text-transform: uppercase; color: var(--ink-soft); }
+.pp-label::before { content: counter(pp-chapter, decimal-leading-zero) " / "; color: var(--ink); }
+.pp-chapter h2 {
+  font-size: clamp(var(--text-xl), 1rem + 2vw, var(--text-3xl)); font-weight: 600; line-height: 1.15;
+  letter-spacing: -0.025em; margin: 0 0 var(--s4); max-width: 22ch; text-wrap: balance;
+}
+.pp-chapter-body > p { margin: 0 0 var(--s4); max-width: 62ch; color: var(--ink-soft); font-size: var(--text-lg); line-height: 1.55; }
+.pp-chapter-body > p:last-child { margin-bottom: 0; }
+
+/* Two to four short points under a chapter: a ruled column each. */
+.pp-points { list-style: none; margin: var(--s6) 0 0; padding: 0; display: grid; gap: var(--s5); grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); }
+.pp-points > li { border-top: 2px solid var(--ink); padding-top: var(--s3); }
+.pp-points h3 { margin: 0 0 6px; font-size: var(--text-lg); font-weight: 600; letter-spacing: -0.01em; }
+.pp-points p { margin: 0; color: var(--ink-soft); }
+
+/* A chapter's figure: a terminal, a screenshot, a small mock of the product. */
+.pp-figure { margin: var(--s6) 0 0; }
+.pp-figure > img { display: block; width: 100%; height: auto; border-radius: var(--radius-lg); border: 1px solid var(--line); box-shadow: var(--shadow-2); }
+.pp-figure figcaption { margin-top: var(--s2); font-size: var(--text-sm); color: var(--ink-soft); }
+.pp-terminal { margin: 0; overflow-x: auto; background: var(--card); color: var(--ink); border: 1px solid var(--line); border-radius: var(--radius); box-shadow: var(--shadow-1);
+  padding: var(--s5); font: var(--text-sm) / 1.7 var(--mono); }
+.pp-terminal code { font: inherit; }
+
+/* ── Close ─────────────────────────────────────────────────────────────
+   The primary action once more, with the room a form needs. */
+.pp-close { padding: var(--s8) 0 var(--s9); border-top: 1px solid var(--line); scroll-margin-top: 64px; }
+.pp-close > .pp-wrap { display: grid; gap: var(--s6); grid-template-columns: minmax(0, 1fr); }
+@media (min-width: 960px) { .pp-close > .pp-wrap { grid-template-columns: minmax(0, 5fr) minmax(0, 6fr); } }
+.pp-close h2 { font-size: clamp(var(--text-xl), 1rem + 2vw, var(--text-3xl)); font-weight: 600; line-height: 1.15; letter-spacing: -0.025em; margin: var(--s4) 0 var(--s3); text-wrap: balance; }
+.pp-close .pp-subhead { margin-bottom: 0; }
+.pp-panel { background: var(--card); border: 1px solid var(--line); border-radius: var(--radius-lg); box-shadow: var(--shadow-2); padding: var(--s6); }
+@media (max-width: 560px) { .pp-panel { padding: var(--s5) var(--s4); } }
+
+/* ── Footer ────────────────────────────────────────────────────────────── */
+.pp-footer { border-top: 1px solid var(--line); padding: var(--s6) 0 var(--s7); color: var(--ink-soft); font-size: var(--text-sm); }
+.pp-footer > .pp-wrap { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: var(--s4) var(--s6); }
+.pp-footer p { margin: 0; display: flex; flex-wrap: wrap; align-items: center; gap: var(--s3); }
+.pp-footer .pp-brand { font-size: var(--text-base); }
+.pp-footer .pp-brand img, .pp-footer .pp-brand svg { width: 20px; height: 20px; }
+.pp-footer nav { display: flex; flex-wrap: wrap; gap: var(--s4); }
+.pp-footer nav a { color: var(--ink-soft); text-decoration: none; }
+.pp-footer nav a:hover { color: var(--ink); }

package/tailwind.css

@@ -23,6 +23,7 @@
   --color-line-control: var(--line-control);
   --color-surface-hover: var(--surface-hover);
   --color-surface-active: var(--surface-active);
+  --color-surface-sticky: var(--surface-sticky);
   --color-on-dark: var(--on-dark);
 
   --color-interactive: var(--i);

package/tokens.css

@@ -119,6 +119,11 @@
   --card: light-dark(#ffffff, #17171a); /* n-0 / n-50 */
   --surface-hover: var(--n-100);
   --surface-active: var(--n-200);
+  /* Sticky chrome — a header or toolbar that content scrolls under, usually
+     with `backdrop-filter: blur()`. 92% of the surface it sits on: the card
+     in light, the page ground in dark, where cards are lighter than the
+     page. A token so consumers never color-mix() one (DESIGN.md §11). */
+  --surface-sticky: light-dark(color-mix(in srgb, #ffffff 92%, transparent), color-mix(in srgb, #0d0d0f 92%, transparent)); /* card / bg */
   --ink: var(--n-900);
   --ink-soft: var(--n-700);
   --slate: light-dark(#6b6b73, #8b8b93); /* n-600 / n-500 — text-safe: eyebrows, axis labels, captions */