@nicohaberkorn/sinn 0.0.0-stage → 0.12.1

package/README.md

@@ -1,3 +1,282 @@
-# Temporary Holding Version
+# @nicohaberkorn/sinn
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The design system behind [nicohaberkorn.com](https://nicohaberkorn.com): layered design tokens (color, typography, layout, motion), intrinsic layout primitives and a small set of motion components. The whole visual identity is expressed as tokens, so the site can be rebranded by switching a preset rather than rewriting CSS.
+
+```bash
+npm i @nicohaberkorn/sinn
+```
+
+## Intent
+
+Three ideas shape the system.
+
+1. **Components never see raw values.** A component asks for a *role*, such as "text on a surface", "a pencil stroke" or "the display typeface". It never asks for a colour value, a font name or a pixel size. The preset decides what that role looks like. A rebrand is then a new preset plus, at most, a few new roles, with no component changes.
+2. **Explore everything, ship one thing.** The source describes a large design space: 22 hues across 2 base palettes, 4 contrast modes, several typefaces, type scales and line-heights. That is useful while designing. A visitor, however, only needs the single combination the site uses. The build resolves that combination ahead of time and ships only its final values, plus the light/dark switch, which is the one axis that stays live at runtime. The full, switchable space is still available as a separate development-only stylesheet.
+3. **Space comes from type, and layout adapts to its container.** Every spacing value derives from one line-height unit. The layout primitives adapt to the space they are given (they are intrinsic) rather than to viewport breakpoints.
+
+## How tokens are layered
+
+Tokens resolve in four layers. Each layer may only reference the layer below it.
+
+```
+PAL   raw values            --sn-pal-teal-60: oklch(0.6389 0.1202 175.29)      --sn-pal-type-family-fraunces: 'Fraunces', …
+ ↓
+REF   the preset's choices  --sn-ref-primary-40: <a pal step>   --sn-ref-type-family-serif: <a pal family>
+ ↓
+ROLE  what things mean      --sn-role-color-on-surface     --sn-role-type-prose-family
+ ↓
+COMP  component specifics   --sn-comp-color-filled-button-background   --sn-comp-color-stamp-border
+```
+
+**Only ROLE and COMP tokens are public.** A preset build removes PAL and REF entirely, so neither exists at runtime. The one exception is `--sn-ref-type-family-mono`, which the typography base styles use for `code`. Build components against `--sn-role-*` and `--sn-comp-color-*` only.
+
+### Naming
+
+Every custom property starts with `sn`, the name space, so nothing collides with another system. After it comes the level, the attribute and the token, and each part says what it is:
+
+- `--sn-role-color-*`, `--sn-role-type-*` and `--sn-comp-color-*`: level, attribute, token. The level is the token level the value sits at.
+- Foundation tokens have no preset and no levels of their own, so they are `sn` plus the attribute: `--sn-space-*`, `--sn-radius-*`, `--sn-layer-*`, `--sn-motion-*`, `--sn-measure-*`, `--sn-cq-*`, `--sn-ratio-*`, `--sn-focus-*`, `--sn-gutter`, `--sn-page-max-width` and `--sn-line-height-unit`.
+- Palettes are named after the colour model they were generated in (`sn-pal-hct`, `sn-pal-hsl`), and accent sets after what they do (`monochrome`, `solarpunk`, `marginalia`), so a name tells you why it exists.
+
+Migrating from 0.8: add the `sn-` prefix to `--space-*`, `--radius-*`, `--layer-*`, `--motion-*`, `--measure*`, `--cq-*`, `--ratio-*`, `--gutter`, `--page-max-width`, `--focus-outline-*` and `--line-height-unit`; rename `--color-comp-*` to `--sn-comp-color-*` and `--color-focus` to `--sn-focus-color`. Removed: `--color-role-background` and `--color-role-on-background` (unused duplicates of role tokens) and the legacy `--font-size-h1` … `-caption` aliases (use `--sn-role-type-size-*`).
+
+### Namespace and token space (the model behind the names)
+
+A token name has two parts. The **name space** says where it lives: `sn` (the system), a **theme** (the preset) and a **domain** (website, webapp, d-app, m-app). The **token space** says what it is: a design attribute (color, text) and a token level.
+
+| Level | Diagram name | Purpose (color / text) | Mode criterion | Today |
+|---|---|---|---|---|
+| comp | comp | variation / compose | composition | `--sn-comp-color-*` (color only) |
+| role | sys | combination / combine | context: brightness / screen real estate | `--sn-role-color-*`, `--sn-role-type-*` |
+| ref | ref | allocation / allocate | selection | build-time only |
+| pal | pal | restriction / restrict | expression | build-time only |
+| scale | scale | operation / operate | structure | generative: tonal scale 0-100, type ratios (data in `trace/scales.json`) |
+| space | space | specification / specify | format | generative: oklch for colour, px to rem and clamp() for type |
+| seed | seed | inception / incept | input | generative: a family's key colour, a scale's base size |
+
+Theme is not part of any variable name: a preset build fixes it, so the same names carry different values per preset. Domain is documented but not yet built: only `website` exists. The intent is that colors, seed and palette are shared across domains while comp (and parts of role) differ, so a button in a web app is denser than on the website but visibly the same family.
+
+### Generative levels: seed, space, scale
+
+The seven levels split in two. **Applied levels** make decisions: comp, role, ref and pal. **Generative levels** create the possibilities the applied levels choose from: seed (inception, input), space (specification, format) and scale (operation, structure). Read from the bottom, a value is a seed, put into a space, run through a scale, curated into a palette, allocated by a preset, given a meaning by a role and specialised by a component.
+
+| | Colour | Type |
+|---|---|---|
+| **seed** | a hue and chroma per ramp (recorded for the `sn-pal-hct` families), a key colour | a base size in px: 16, 18, 54, 102 … |
+| **space** | oklch (every tone is written as `oklch(L C H)`, L and C to three decimals, H in whole degrees) | px converted to rem (px / 16), and `clamp()` for fluid sizes |
+| **scale** | a tonal scale of 0 to 100, where a tone tracks CIE L* lightness, so one step is equally light in every hue | a named ratio applied to the base: step n = base x ratio^(n-1) |
+
+The type palette holds 14 named scales of five steps: three golden-ratio scales (bases 54, 71 and 102 px, in whole pixels), a perfect fourth at 20 px, a major third at 18 px, minor thirds at 16 and 14 px and major seconds at 18, 16, 14, 12, 11, 9 and 8 px. The ref level turns two scale steps into one fluid size: `clamp(min, slope x 100vw + intercept, max)`, growing linearly between a 20rem and an 80rem viewport, where slope = (max - min) / (80rem - 20rem) and intercept = min - slope x 20rem. Which step each end takes is written in `tokens/type/scale-map.json`, and `scripts/build-typescale.mjs` generates `tokens/type/ref/typescale-*.json` from it, so no size is a free-standing number. Each group takes one scale per end (steps 5 to 1 from largest to smallest):
+
+| Group | At 320px | At 1280px |
+|---|---|---|
+| display | golden ratio, 54px seed | golden ratio, 102px seed |
+| heading | minor third, 16px seed | perfect fourth, 20px seed |
+| body | major second, 12px seed | major second, 16px seed |
+| label | major second, 8px seed | major second, 11px seed |
+
+Every size is within a pixel of the value it had before it was tied to a scale. `--sn-role-type-size-subheading` is `heading-smallest`, so a subheading is never larger than any heading. The `smaller` and `smallest` type scales are copies of `default` for now.
+
+Each palette family has three tonal ramps of up to 31 tones: the family (`teal`), a desaturated companion (`tealvariant`) and a tinted neutral (`tealgray`). The palettes are named after the colour model they were generated in. `sn-pal-hct` was generated in HCT (hue, chroma, tone) and follows CIE L* closely, so tone 40 is L* 40 within a fraction; the hue and chroma noted for each ramp are in `tokens/color/seeds/seeds.json`. `sn-pal-hsl` was generated in HSL with a shared tone-lightness curve and is more saturated; its neutrals are a straight percentage of 255. In both palettes lightness rises with every tone, and in `sn-pal-hct` every tone is within 2 L* of its number; tones that broke this were corrected, and only those.
+
+`dist/trace/scales.json` exposes all of this as data: the type scales with ratio and base, every fluid ref size with its min, max and where each end comes from, and every colour ramp. Import it as `@nicohaberkorn/sinn/trace/scales.json`.
+
+### Resolution trace (`trace/<preset>.json`)
+
+Because pal and ref never ship as CSS, each build also writes `dist/trace/<preset>.json`: for every public token, per theme, the chain it resolves through (comp, role, ref, pal, literal) with the value at each step. Import it as `@nicohaberkorn/sinn/trace/marginalia.json`. Documentation, not runtime styling.
+
+### Axes
+
+A preset is one value chosen per axis:
+
+| Axis | What it controls | Values |
+|---|---|---|
+| `colorPal` | Base palette (the PAL layer) | `sn-pal-hsl` (HSL, more saturated), `sn-pal-hct` (HCT, follows CIE L*) |
+| `colorRef` | Primary hue driving the REF color ramps | 22 hues, e.g. `sn-ref-truegray`, `sn-ref-blue`, `sn-ref-green` |
+| `mode` | Contrast mode | `normal`, `calm`, `playful`, `vibrant` |
+| `vibe` | Accent strategy (the `accent-1`…`accent-7` colours) | `solarpunk`, `monochrome`, `marginalia` |
+| `refExpression` | Typefaces, weights and tracking | `natural`, `good`, `bad` (a QA placeholder), `editorial` |
+| `refTypescale` | Fluid type scale | `default`, `smaller`, `smallest` |
+| `expression` | Which typeface each role uses | `natural`, `technical`, `modern`, `editorial` |
+| `leading` | Line-heights | `default`, `comfy` |
+| `theme` | Light or dark | the only axis switched at runtime, via `[data-theme]` |
+
+## Presets
+
+| Preset | Look | Axes |
+|---|---|---|
+| **`marginalia`** | Monochrome editorial base with one teal "pencil" that edits, circles, highlights and stamps. Bricolage Grotesque for display and UI, Fraunces for prose, Geist Mono for labels, Caveat for handwritten notes. **This is what nicohaberkorn.com ships.** | `sn-pal-hct` · `sn-ref-truegray` · `calm` · `marginalia` · `editorial` / `editorial` · `default` · `comfy` |
+| `modern-classic` | Inter everywhere, Merriweather prose, single blue accent. | `sn-pal-hsl` · `sn-ref-blue` · `normal` · `monochrome` · `modern` / `natural` · `default` · `default` |
+| `technology` | Monospaced headings on a neutral grey base. | `sn-pal-hct` · `sn-ref-truegray` · `normal` · `technology` · `technical` / `natural` · `smaller` · `default` |
+| `solarpunk` | Green base with a full color-wheel of section accents, serif display. | `sn-pal-hsl` · `sn-ref-green` · `calm` · `solarpunk` · `natural` / `natural` · `default` · `comfy` |
+
+Each preset ships as two files: `root.css` (`:root, [data-theme="light"]`) and `dark.css` (`[data-theme="dark"]`). Always set `data-theme` on `<html>` explicitly.
+
+## Using it
+
+```css
+@import "@nicohaberkorn/sinn/foundation.css";   /* space, measure, layers, radius, motion: preset-independent */
+@import "@nicohaberkorn/sinn/primitives.css";   /* layout primitives + typography base */
+@import "@nicohaberkorn/sinn/motion.css";       /* motion components + annotation types */
+@import "@nicohaberkorn/sinn/presets/marginalia/root.css";
+@import "@nicohaberkorn/sinn/presets/marginalia/dark.css";
+```
+
+```html
+<html data-theme="light"> … </html>
+```
+
+The preset files contain literal font-family names such as `'Bricolage Grotesque'`. The consuming app loads the font files itself, for example with `next/font` or `@font-face`, under exactly those family names.
+
+For design exploration, import `@nicohaberkorn/sinn/dev-all.css` instead of a preset. It keeps the full `[data-*]` cascade, so every axis can be switched live via attributes on `<html>` (`data-color-pal`, `data-color-ref`, `data-mode`, `data-vibe`, `data-expression`, `data-ref-expression`, `data-ref-typescale`, `data-leading`, `data-theme`). It is large; load it only in development.
+
+## Token reference
+
+### Color roles: `--sn-role-color-*`
+
+Surfaces and text follow Material-style role pairs:
+
+- `primary` / `on-primary`, `primary-container` / `on-primary-container`, `inverse-primary`
+- `secondary` / `on-secondary`, with `-container` variants
+- `surface` / `on-surface`, plus `surface-variant`, `on-surface-variant` (secondary text), and `surface-dim` / `-bright`
+- `surface-container-{lowest,low,,high,highest}`
+- `inverse-surface` / `inverse-on-surface` / `inverse-on-surface-variant` (secondary text on inverse bands) / `inverse-primary`
+- `outline` / `outline-variant`
+- `error` / `on-error`, with containers
+- `shadow`, `disabled` / `on-disabled`
+- **Accents**, a full set per number, mirroring `primary` (below)
+
+Two gotchas: `outline` is nearly invisible against surfaces, so use `outline-variant` for control borders. `surface` always means a neutral background; accents never use the words `surface`, `outline` or `variant`.
+
+### Accents: `accent-1` … `accent-7`
+
+Each accent is a complete role set in the same shape as `primary`:
+
+| `primary` | Accent | Meaning |
+|---|---|---|
+| `primary` | `accent-N` | the colour itself; safe as text or stroke on `surface` |
+| `on-primary` | `on-accent-N` | content on a filled accent |
+| `primary-container` | `accent-N-container` | soft tinted fill |
+| `on-primary-container` | `on-accent-N-container` | content on that fill |
+| `inverse-primary` | `inverse-accent-N` | the accent on `inverse-surface` (the bands) |
+
+What each number is depends on the vibe: `solarpunk` is a colour wheel (green, teal, blue, violet, fuchsia, grey, teal), `monochrome` is single-hue (every accent is the primary ramp), and `marginalia` has teal, blue and violet in 1-3 and monochrome in 4-7. Tones follow one recipe (light: 40 / 100 / 90 / 10 / 80; dark: 70 / 20 / 30 / 90 / 40), so any hue works.
+
+### Type roles beyond the voices
+
+| Token | Use |
+|---|---|
+| `type-script-{family,weight,tracking,line-height}` | Handwriting voice (Caveat in `marginalia`) |
+| `type-display-stretch` | Display width (`90%` in `editorial`) |
+| `type-label-transform` | Label case (`uppercase` in `editorial`) |
+
+### Component tokens: `--sn-comp-color-*`
+
+- Buttons: `filled-`, `tonal-`, `outline-`, `text-` and `elevated-button-{background,border,shadow}`, plus the matching `on-*` tokens
+- `hover`, `disabled-button-background`
+- Annotation layer: `mark-stroke` (`accent-1`), `mark-stroke-on-inverse` (`inverse-accent-1`), `mark-highlight-background` (`accent-1-container`), `on-mark-highlight-background` (`on-accent-1-container`), `annotation-text` and `stamp-{border,text}` (`accent-1`), `stamp-neutral-{border,text}` (`on-surface`). These are thin aliases: point a mark at `accent-2` and it changes colour.
+
+### Type roles: `--sn-role-type-*`
+
+- Voices `display`, `heading`, `subheading`, `body`, `prose` (long-form reading), `label`, `nav` and `script`, each with `-family`, `-weight`, `-tracking` and `-line-height`. `prose` is `body` with a reading typeface: it inherits body's sizes, weight, tracking and line height, so only the family differs
+- Fluid sizes `size-{display,heading,body,label}-{largest,large,medium,small,smallest}` and `size-subheading`
+
+### Foundation (`foundation.css`, one file for every preset)
+
+| Group | Tokens |
+|---|---|
+| Space | `--sn-space-3xs` … `--sn-space-4xl`, all derived from `--sn-line-height-unit` (1.5rem). Fluid pairs `--sn-space-xs-s` … `--sn-space-2xl-3xl` |
+| Measure | `--sn-measure-narrow` (45ch), `-body` (65ch), `-wide` (85ch), `-max` (110ch) |
+| Page | `--sn-page-max-width`, `--sn-gutter` |
+| Container sizes | `--sn-cq-compact`, `-medium`, `-wide`, `-full` |
+| Ratios | `--sn-ratio-widescreen`, `-landscape`, `-standard`, `-square`, `-portrait`, `-tall` |
+| Layers | `--sn-layer-base` … `--sn-layer-tooltip` (0–70). Always pair with `isolation: isolate` |
+| Radius | `--sn-radius-xs` (2px), `-s` (6px), `-m` (8px), `-pill` |
+| Motion | `--sn-motion-duration-{instant,fast,medium,slow,stamp,draw-intro,draw-follow}`, `--sn-motion-ease-{out,in-out,overshoot,linear}`, `--sn-motion-draw-{start,end}`, `--sn-motion-stamp-trigger`, `--sn-motion-stagger`, `--sn-motion-intro-gap`. Under `prefers-reduced-motion` every duration becomes `0ms` |
+| Focus | `--sn-focus-outline-width`, `--sn-focus-outline-offset`, `--sn-focus-color` |
+
+## Layout primitives (`primitives.css`)
+
+These are hand-authored intrinsic layouts in the Every Layout style. They respond to the space they are given, not to the viewport.
+
+| Class | Purpose |
+|---|---|
+| `.stack` | Vertical flow with a consistent `gap` (`data-gap="xs|s|l|xl"`) |
+| `.cluster` | Wrapping horizontal group (`data-justify`) |
+| `.switcher` | Row that becomes a column below a threshold |
+| `.auto-grid` | `repeat(auto-fill, minmax(min(100%, 18rem), 1fr))` (`data-min`) |
+| `.with-sidebar` | Sidebar plus content that wraps when the content would get too narrow |
+| `.center-wrap`, `.center--text`, `.center--intrinsic` | Max-width, centering and gutters |
+| `.cover` | Vertically centered principal element |
+| `.frame`, `.page-grid`, `.full-bleed`, `.flow` | Media frames, page grid, bleeding out of the grid, prose rhythm |
+
+## Motion (`@nicohaberkorn/sinn/motion` + `motion.css`)
+
+React components (peer dependencies `react` ≥ 19; built on `motion`):
+
+- `Button`, `ButtonLink`: press and hover physics
+- `ChromaticTextReveal`, `SharedLayoutBg`
+- Shared easing constants: `EASE_OUT` and `EASE_IN_OUT`, which match `--sn-motion-ease-out` and `--sn-motion-ease-in-out`, and `SPRING_LAYOUT` and `SPRING_PRESS`
+
+The annotation layer draws a reader's marks as the page scrolls. It is framework-agnostic CSS plus a small engine:
+
+| Class | Draws as |
+|---|---|
+| `.sn-mark-highlight` | Highlighter swipe |
+| `.sn-mark-underline` | Pen line |
+| `.sn-mark-circle` | Hand-drawn ring |
+| `.sn-mark-strike` | An edit through a word |
+| `.sn-mark-margin` | Double stroke in the margin |
+| `.sn-mark-box` | Hand-drawn frame around a key passage |
+| `.sn-annotation` | Handwritten note, revealed as if written |
+| `.sn-draw-path` | Any SVG stroke (add `pathLength="1"`) |
+| `.sn-scribble` | Wavy underline |
+| `.sn-stamp`, `.sn-stamp--neutral` | Status label that lands once |
+
+Mark an element with `data-sn-draw` so the engine animates it. Add `data-sn-delay="ms"` to use a timed intro instead of scroll-linked drawing, typically for marks above the fold. Mark stamps with `data-sn-stamp`.
+
+```ts
+import { createScrollDraw, setMarksVisible, restoreMarks } from '@nicohaberkorn/sinn/motion'
+// React: useScrollDraw(deps), <Mark kind="highlight|underline|circle|strike">, <Annotation>, <Stamp tone>
+```
+
+`.sn-on-inverse` switches the pencil for inverse bands. `[data-marks="hidden"]` on `<html>` hides the reader's marks; `setMarksVisible()` sets it and `restoreMarks()` restores the saved choice. Under reduced motion every mark renders fully drawn.
+
+## Source layout
+
+```
+tokens/                 DTCG JSON, the source of truth
+  color/pal/{sn-pal-hsl,sn-pal-hct}/<hue>.json
+  color/ref/sn-ref-<hue>.json
+  color/role/{light,dark}-{normal,calm,playful,vibrant}.json   complete per mode
+  color/role/accent-<vibe>-{light,dark}.json                   the seven accent sets per vibe
+  color/comp/comp.json
+  type/pal.json, type/ref/*.json, type/role/*.json
+  layout/layout.json, motion/motion.json
+  registry.js           axis → value → source files
+presets.js              preset definitions and BUILT_PRESETS
+scripts/                build-tokens (presets + foundation), build-dev-all, build-primitives, build-motion-css
+src/primitives/         hand-authored layout CSS
+src/motion/             React components, scroll-draw engine, motion CSS
+dist/                   generated; never edit by hand
+```
+
+## Development
+
+```bash
+npm install
+npm run build        # dist/: foundation, primitives, presets, dev-all, motion
+```
+
+### Adding a preset
+
+1. Pick a value for each axis in `presets.js` and add the name to `BUILT_PRESETS`.
+2. If you need a value that doesn't exist yet, add its token file under `tokens/` and register it in `tokens/registry.js`. A new vibe needs `accent-<vibe>-{light,dark}.json`, plus a selector in `scripts/build-dev-all.mjs`.
+3. Prefer existing role shapes over new ones: a new colour is an accent set (`accent-N`, `on-accent-N`, …) in the vibe files, not a new group. A role every preset needs goes in **every** role-mode file, so each preset keeps shipping a complete set of tokens.
+4. Run `npm run build` and add the preset's two files to `exports` in `package.json`.
+
+A new preset must not change the resolved values of any existing preset. To check, diff `dist/<preset>/*.css` before and after the build.
+
+## License
+
+MIT © Nico Haberkorn

package/dist/dev-all/color-comp.css

@@ -0,0 +1,39 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+:root {
+  --sn-comp-color-filled-button-border: transparent;
+  --sn-comp-color-filled-button-shadow: transparent;
+  --sn-comp-color-tonal-button-border: transparent;
+  --sn-comp-color-tonal-button-shadow: transparent;
+  --sn-comp-color-outline-button-background: transparent;
+  --sn-comp-color-outline-button-shadow: transparent;
+  --sn-comp-color-text-button-background: transparent;
+  --sn-comp-color-text-button-border: transparent;
+  --sn-comp-color-text-button-shadow: transparent;
+  --sn-comp-color-filled-button-background: var(--sn-role-color-primary);
+  --sn-comp-color-on-filled-button-background: var(--sn-role-color-on-primary);
+  --sn-comp-color-on-tonal-button-background: var(--sn-role-color-on-primary-container);
+  --sn-comp-color-on-outline-button-background: var(--sn-role-color-on-primary-container);
+  --sn-comp-color-on-text-button-background: var(--sn-role-color-on-primary-container);
+  --sn-comp-color-on-elevated-button-background: var(--sn-role-color-on-primary-container);
+  --sn-comp-color-on-primary-hover: var(--sn-role-color-on-primary);
+  --sn-comp-color-on-disabled-button: var(--sn-role-color-on-disabled);
+  --sn-comp-color-on-mark-highlight-background: var(--sn-role-color-on-accent-1-container);
+  --sn-comp-color-tonal-button-background: var(--sn-role-color-primary-container);
+  --sn-comp-color-outline-button-border: var(--sn-role-color-outline);
+  --sn-comp-color-elevated-button-background: var(--sn-role-color-surface-container-high);
+  --sn-comp-color-elevated-button-border: var(--sn-role-color-outline);
+  --sn-comp-color-elevated-button-shadow: var(--sn-role-color-shadow);
+  --sn-comp-color-hover: var(--sn-role-color-primary);
+  --sn-comp-color-disabled-button-background: var(--sn-role-color-disabled);
+  --sn-comp-color-mark-stroke: var(--sn-role-color-accent-1);
+  --sn-comp-color-mark-stroke-on-inverse: var(--sn-role-color-inverse-accent-1);
+  --sn-comp-color-mark-highlight-background: var(--sn-role-color-accent-1-container);
+  --sn-comp-color-annotation-text: var(--sn-role-color-accent-1);
+  --sn-comp-color-stamp-border: var(--sn-role-color-accent-1);
+  --sn-comp-color-stamp-text: var(--sn-role-color-accent-1);
+  --sn-comp-color-stamp-neutral-border: var(--sn-role-color-on-surface);
+  --sn-comp-color-stamp-neutral-text: var(--sn-role-color-on-surface);
+}