@tenphi/cookbook 0.15.0 → 0.17.0

package/docs/upstream/glaze/docs/methodology.md

@@ -0,0 +1,686 @@
+# Methodology
+
+A practical way to design a Glaze palette without fighting dark mode. Start from
+tone relationships, add contrast only where a role needs a readable floor, and
+let `extend()` carry the same decisions across status hues.
+
+For the full API surface, see [api.md](api.md). For the Glaze color-model
+overview, see [okhst.md](okhst.md); the derivation lives in the
+[canonical OKHST specification](https://github.com/tenphi/okhst).
+
+## The mental model
+
+Glaze palettes work best as one default neutral theme plus a few colored sibling
+themes:
+
+* `default` owns the neutral system most components consume: `#surface`,
+  `#surface-text`, `#border`, `#disabled-surface`, and so on.
+* Status themes (`success`, `danger`, `warning`, `note`, ...) are created with
+  `extend()`. They swap the hue and keep only the inherited tokens that should
+  become status-aware.
+* `inherit: false` keeps a token local to the parent theme. Use it for neutral
+  ladders, shadows, code colors, overlays, and anything that should not be
+  repeated for every status hue.
+
+The main simplification is OKHST tone. Dark mode is a single inversion
+(`100 - t`) plus a scheme tone window, so a relative **tone delta** stays
+anchored to its base in every scheme. A token authored as `tone: '-4'` remains
+the same kind of visual step in light and dark. The step is exactly
+contrast-even for neutrals and approximate for chromatic colors; add a
+`contrast` floor when the measured result matters.
+
+Use `glaze.color()` instead of a theme when you need one standalone color or
+one base/dependent pair and do not need a named palette. The same tone,
+adaptation, and contrast rules apply; see
+[Standalone color tokens](api.md#standalone-color-tokens).
+
+## Implementation workflow
+
+Build in dependency order so every decision has a clear base:
+
+1. Configure the output schemes and application states once.
+2. Choose the default theme's hue and saturation seed.
+3. Define root surfaces with absolute tones.
+4. Add dependent surfaces, text, borders, and icons with tone deltas.
+5. Add contrast floors only to roles that need measured readability or
+   recognizability.
+6. Choose adaptation per color: `auto`, `fixed`, or `static`.
+7. Add explicit HC pairs where high contrast should increase separation.
+8. Mark default-only tokens `inherit: false`, then extend the shared
+   definitions into status themes.
+9. Compose and export the palette in the shape your application consumes.
+10. Verify complete screens in all emitted scheme variants.
+
+The sections below follow this order and build one palette incrementally.
+
+## Authoring decisions
+
+Use this order when defining a token:
+
+1. Pick the base it visually belongs to.
+2. Use an absolute numeric `tone` for independent placement. Use a signed
+   **tone delta** (`'+N'` / `'-N'`) for distance from a base: surface ladders,
+   soft chips, disabled states, hover ramps, and similar relationships.
+3. Add `contrast` only when readability or recognizability needs a measured
+   floor.
+4. Prefer APCA presets for content-like colors when perceptual readability is
+   the design goal:
+   `contrast: { apca: 'content' }` or
+   `contrast: { apca: ['content', 'body'] }`.
+5. Use WCAG numbers or presets when compatibility, policy, or migration
+   requires a WCAG ratio:
+   `contrast: 4.5`, `contrast: 'AAA'`, or `contrast: { wcag: [4.5, 7] }`.
+6. Let token names infer APCA roles. Names ending in `text`, `label`, `border`,
+   `surface`, `fill`, `bg`, and similar aliases already tell Glaze which side is
+   foreground or background. Set `role` only when a name is ambiguous.
+7. Add high-contrast pairs only where HC should intentionally tighten:
+   text/content contrast, border tone, shadow intensity, mix value, or similar.
+
+### Choosing adaptation mode
+
+| Mode             | Choose it when                                                                                                              |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `auto` (default) | The color should exchange light/dark positions through dark tone inversion. Typical for surfaces, text, borders, and icons. |
+| `fixed`          | A brand fill, status banner, or inverse surface should stay on the authored side of the tone scale.                         |
+| `static`         | The exact authored tone and saturation must render in every scheme, without tone-window mapping or dark desaturation.       |
+
+Dark tone inversion is controlled by `mode`; it is unrelated to `autoFlip`.
+`autoFlip` only allows an overshooting tone delta or an unsuccessful contrast
+direction to reverse around its base.
+
+### Root or dependent?
+
+* Use a root color when its tone has meaning on its own: the page surface, a
+  fixed brand anchor, or a scheme extreme.
+* Use a dependent color when its purpose exists relative to another token:
+  text on a surface, a border around a fill, or a tint of an accent.
+* Setting `base` with an absolute tone is valid when the color needs a contrast
+  relationship but not a tone delta. The absolute position is resolved
+  independently; `contrast` acts as a safety floor.
+
+## Seed and configure
+
+Keep hue decisions named and configure output modes once:
+
+```ts
+import { glaze } from '@tenphi/glaze';
+
+const PURPLE_HUE = 280.3;
+const SUCCESS_HUE = 156.9;
+const DANGER_HUE = 23.1;
+const WARNING_HUE = 84.3;
+const NOTE_HUE = 302.3;
+
+const SEED_SATURATION = 80;
+
+glaze.configure({
+  states: { dark: '@dark', highContrast: '@hc' },
+  modes: { dark: true, highContrast: true },
+});
+```
+
+Per-color `saturation` is a factor of the theme seed, not an absolute
+saturation. With `SEED_SATURATION = 80`, `saturation: 0.25` means one quarter of
+that seed.
+
+### When dark needs its own chroma
+
+Dark schemes get a flat `darkDesaturation` haircut (10% by default), which is
+enough for most palettes. Reach for a second seed only when dark is wrong in a
+way a uniform reduction cannot fix — a hue that reads muddy against dark
+surfaces, or an accent that stays gaudy no matter how much you dial the global
+knob:
+
+```ts
+const primary = glaze({
+  hue: PURPLE_HUE,
+  saturation: SEED_SATURATION,
+  darkHue: PURPLE_HUE - 12, // cooler purple on dark surfaces
+  darkSaturation: 62, // calmer than a 10% haircut would give
+});
+```
+
+An explicit `darkSaturation` replaces `darkDesaturation` rather than stacking
+with it, so the number you write is the number you get. Prefer tuning the seed
+over per-color `darkHue` / `darkSaturation`: one seed keeps the palette
+coherent, while scattered per-color dark overrides drift apart as the palette
+grows. Save the per-color form for the one or two tokens that genuinely need it.
+
+## Naming
+
+Prefer purpose first and variant last:
+
+* Surfaces: `surface`, `surface-2`, `surface-3`.
+* Foregrounds: `surface-text`, `surface-text-soft`, `surface-text-soft-2`.
+* Structure: `border`, `divider`, `outline`, `placeholder`, `focus`.
+* Fills: `accent-surface`, `accent-surface-2`,
+  `accent-surface-hover`.
+* Foregrounds on neutral surfaces: `accent-text`, `accent-text-soft`,
+  `accent-icon`.
+* Disabled states: `disabled-surface`, `disabled-surface-text`,
+  `accent-disabled-surface`, `accent-disabled-surface-text`.
+* Effects: `shadow-sm`, `shadow-md`, `shadow-lg`, `overlay`, `hover`, `tint`.
+
+These names are not only readable. They also help APCA role inference pick the
+right polarity. For example, `button-text` is foreground, `input-bg` is a
+surface, and `card-outline` is a border.
+
+## Build the default theme
+
+Start with the surface family. It is mostly tone, with small saturation changes
+to keep the ladder visually coherent:
+
+```ts
+const defaultTheme = glaze(PURPLE_HUE, SEED_SATURATION);
+
+defaultTheme.colors({
+  surface: { tone: 100, saturation: 0.11 },
+  'surface-2': {
+    base: 'surface',
+    tone: '-2',
+    saturation: 0.15,
+    inherit: false,
+  },
+  'surface-3': {
+    base: 'surface',
+    tone: '-4',
+    saturation: 0.19,
+    inherit: false,
+  },
+});
+```
+
+Because each tone delta re-anchors to the resolved surface in every scheme,
+these small relative offsets are enough to define the ladder. There is no
+separate dark-mode curve to tune.
+
+### Text and borders
+
+Use a hard edge tone for maximum-prominence text, and APCA floors for softer
+content:
+
+```ts
+defaultTheme.colors({
+  'surface-text': {
+    base: 'surface',
+    tone: 2,
+    saturation: 0.475,
+  },
+  'surface-text-soft': {
+    base: 'surface',
+    tone: '-1',
+    saturation: 0.375,
+    contrast: { apca: ['content', 'body'] },
+    inherit: false,
+  },
+  'surface-text-soft-2': {
+    base: 'surface',
+    tone: '-1',
+    saturation: 0.24,
+    contrast: { apca: ['large', 'content'] },
+    inherit: false,
+  },
+  border: {
+    base: 'surface',
+    tone: ['-10', '-20'],
+    saturation: 0.175,
+    inherit: false,
+  },
+});
+```
+
+`surface-text` uses an absolute `tone: 2` despite having a base: it is
+intentionally edge-anchored, and the base records the relationship used by
+role inference. The soft variants use a `-1` tone delta as the preferred
+direction and APCA as the readable floor. `border` uses an HC tone-delta pair
+because borders usually need a larger visible step in high contrast.
+
+Repeat the same pattern for `surface-2` and `surface-3` only if components need
+text directly on those surfaces.
+
+### Neutral utility tokens
+
+Keep neutral-only primitives local to the default theme:
+
+```ts
+defaultTheme.colors({
+  placeholder: {
+    base: 'surface',
+    tone: 67,
+    saturation: 0.175,
+    inherit: false,
+  },
+  focus: {
+    base: 'surface',
+    tone: 71,
+    saturation: 0.8625,
+    inherit: false,
+  },
+  disabled: {
+    tone: 80.8,
+    saturation: 0.4,
+    inherit: false,
+  },
+});
+```
+
+Absolute tones are fine for primitives whose job is visual placement rather than
+a strict relationship to a specific surface.
+
+## Chips and disabled states
+
+For subtle fills, tone is usually clearer than contrast:
+
+```ts
+defaultTheme.colors({
+  'disabled-surface': {
+    base: 'surface',
+    tone: '-3',
+    saturation: 0.2,
+    inherit: false,
+  },
+  'disabled-surface-text': {
+    base: 'disabled-surface',
+    tone: '+18',
+    saturation: 0.3,
+    autoFlip: false,
+    inherit: false,
+  },
+});
+```
+
+This says exactly what the pair should do: the chip sits a small tone delta off
+the page, and the label sits a muted delta from the chip. `autoFlip: false`
+keeps the label on the authored side when the delta reaches the edge.
+
+Use contrast instead when the chip must hit an explicit accessibility floor:
+
+```ts
+defaultTheme.colors({
+  'disabled-surface-text': {
+    base: 'disabled-surface',
+    tone: '+1',
+    saturation: 0.3,
+    contrast: { apca: 'non-text' },
+    inherit: false,
+  },
+});
+```
+
+When a token needs the scheme extreme, use `tone: 'min'` or `tone: 'max'`
+directly. Avoid large magic numbers or fake contrast floors just to push a color
+to the edge.
+
+Pair the extreme with a `base` when the gap between the two has to survive the
+scheme switch. Glaze then replays the light-scheme tone shift against the
+resolved dark base instead of re-mapping the extreme through the dark window,
+so a knockout on a surface keeps the same contrast in both schemes.
+
+## Fixed surfaces and accent fills
+
+Use `mode: 'fixed'` when the authored color should stay recognizable across
+schemes.
+
+```ts
+defaultTheme.colors({
+  'surface-inverse': {
+    tone: 12,
+    saturation: 0.475,
+    mode: 'fixed',
+    inherit: false,
+  },
+
+  'accent-surface-text': {
+    tone: 100,
+    mode: 'fixed',
+  },
+  'accent-surface': {
+    base: 'accent-surface-text',
+    tone: '-1',
+    contrast: { apca: ['content', 'body'] },
+    mode: 'fixed',
+  },
+  'accent-surface-2': {
+    base: 'accent-surface-text',
+    tone: '-1',
+    contrast: { apca: [65, 80] },
+    mode: 'fixed',
+  },
+  'accent-surface-hover': {
+    base: 'accent-surface-text',
+    tone: '-1',
+    contrast: { apca: ['body', 'preferred'] },
+    mode: 'fixed',
+  },
+});
+```
+
+The accent fill family is a fixed chain against a fixed text anchor. The names
+infer `surface` and `text` roles, so APCA gets the right polarity without extra
+fields.
+
+## Adaptive accent foregrounds
+
+Brand foregrounds that sit on neutral surfaces should stay adaptive:
+
+```ts
+defaultTheme.colors({
+  'accent-text': {
+    base: 'surface',
+    tone: '-1',
+    saturation: 1,
+    contrast: { apca: ['content', 'body'] },
+  },
+  'accent-text-soft': {
+    base: 'surface',
+    tone: '-1',
+    saturation: 1,
+    contrast: { apca: ['large', 'content'] },
+  },
+  'accent-icon': {
+    base: 'surface',
+    tone: '-1',
+    saturation: 0.9375,
+    contrast: { apca: ['non-text', 'large'] },
+  },
+});
+```
+
+Anchor these to `surface`, not to `accent-surface`. Their real job is to remain
+readable on neutral UI, so `mode: 'auto'` and a surface base are the right
+defaults.
+
+Brand-tinted disabled states can usually be pure tone:
+
+```ts
+defaultTheme.colors({
+  'accent-disabled-surface': {
+    base: 'surface',
+    tone: '+3',
+    saturation: 0.5,
+  },
+  'accent-disabled-surface-text': {
+    base: 'accent-disabled-surface',
+    tone: '+18',
+    saturation: 0.4,
+    autoFlip: false,
+  },
+});
+```
+
+These are inherited, so status themes automatically get
+`success-accent-disabled-surface`, `danger-accent-disabled-surface`, and the
+matching text tokens.
+
+## Special-purpose colors
+
+Use absolute `hue` overrides for tokens that should come from another hue family
+but keep the same adaptation behavior:
+
+```ts
+defaultTheme.colors({
+  'code-comment': {
+    base: 'surface',
+    hue: 280,
+    saturation: 0.1,
+    tone: '-1',
+    contrast: { apca: ['large', 'content'] },
+    inherit: false,
+  },
+  'code-keyword': {
+    base: 'surface',
+    hue: 348,
+    saturation: 1,
+    tone: '-1',
+    contrast: { apca: ['content', 'body'] },
+    inherit: false,
+  },
+  'code-string': {
+    base: 'surface',
+    hue: SUCCESS_HUE,
+    saturation: 1,
+    tone: '-1',
+    contrast: { apca: ['large', 'content'] },
+    inherit: false,
+  },
+});
+```
+
+Use small tone ramps for decorative motion:
+
+```ts
+defaultTheme.colors({
+  'loading-face-1': {
+    base: 'surface',
+    tone: 98,
+    saturation: 0.3,
+    inherit: false,
+  },
+  'loading-face-2': {
+    base: 'surface',
+    tone: 91,
+    saturation: 0.62,
+    inherit: false,
+  },
+  'loading-face-3': {
+    base: 'surface',
+    tone: 79,
+    saturation: 0.66,
+    inherit: false,
+  },
+});
+```
+
+Since tone steps now invert consistently across schemes, the same ramp keeps its
+spacing in light and dark without involving the contrast solver. Use an HC tone
+pair only when the animation should become more pronounced in high contrast.
+
+## Effects
+
+Define one neutral shadow system:
+
+```ts
+defaultTheme.colors({
+  'shadow-sm': {
+    type: 'shadow',
+    bg: 'surface',
+    fg: 'surface-text',
+    intensity: 5,
+    inherit: false,
+  },
+  'shadow-md': {
+    type: 'shadow',
+    bg: 'surface',
+    fg: 'surface-text',
+    intensity: [10, 20],
+    inherit: false,
+  },
+  'shadow-lg': {
+    type: 'shadow',
+    bg: 'surface',
+    fg: 'surface-text',
+    intensity: [15, 30],
+    inherit: false,
+  },
+});
+```
+
+Including `fg` lets shadow strength follow the resolved foreground/background
+gap. Use an HC pair for shadows that should deepen in high contrast.
+
+Use `opacity` for one fixed-alpha color:
+
+```ts
+defaultTheme.colors({
+  overlay: { tone: 10, opacity: 0.5, inherit: false },
+});
+```
+
+Use mixes when one color should tint through another:
+
+```ts
+defaultTheme.colors({
+  hover: {
+    type: 'mix',
+    base: 'surface',
+    target: 'accent-surface',
+    value: 8,
+    blend: 'transparent',
+  },
+  tint: {
+    type: 'mix',
+    base: 'surface',
+    target: 'accent-surface',
+    value: 20,
+  },
+});
+```
+
+Transparent mixes are good for hover overlays. Opaque mixes are good for solid
+tints. Opaque mixes default to perceptual OKHSL interpolation; choose `srgb`
+when matching channel compositing matters. Transparent mixes always composite
+in linear sRGB. Mix colors can also use `contrast`; the solver adjusts the
+value or opacity to hit the floor. See [Mix colors](api.md#mix-colors).
+
+## Extend into status themes
+
+Once the default theme is shaped, create colored siblings by replacing hue and
+overriding only the root surface that should become visibly tinted:
+
+```ts
+const TINTED_SURFACE_OVERRIDE = {
+  surface: { tone: 96, saturation: 0.8 },
+};
+
+const primaryTheme = defaultTheme.extend({
+  colors: TINTED_SURFACE_OVERRIDE,
+});
+const successTheme = defaultTheme.extend({
+  hue: SUCCESS_HUE,
+  colors: TINTED_SURFACE_OVERRIDE,
+});
+const dangerTheme = defaultTheme.extend({
+  hue: DANGER_HUE,
+  colors: TINTED_SURFACE_OVERRIDE,
+});
+const warningTheme = defaultTheme.extend({
+  hue: WARNING_HUE,
+  colors: TINTED_SURFACE_OVERRIDE,
+});
+const noteTheme = defaultTheme.extend({
+  hue: NOTE_HUE,
+  colors: TINTED_SURFACE_OVERRIDE,
+});
+```
+
+The inherited accent and disabled tokens now resolve in each status hue. Tokens
+marked `inherit: false` stay default-only, so sibling themes remain small.
+
+## Export the palette
+
+Compose the themes once:
+
+```ts
+const palette = glaze.palette({
+  default: defaultTheme,
+  primary: primaryTheme,
+  success: successTheme,
+  danger: dangerTheme,
+  warning: warningTheme,
+  note: noteTheme,
+});
+```
+
+The usual export shape is default unprefixed and status themes prefixed:
+
+```ts
+const prefix = {
+  default: '',
+  primary: 'primary-',
+  success: 'success-',
+  danger: 'danger-',
+  warning: 'warning-',
+  note: 'note-',
+};
+
+palette.tasty({ prefix });
+```
+
+An explicit prefix map is the clearest choice when the palette has a neutral
+`default` theme. The separate palette `primary` option serves another pattern:
+it duplicates one named theme without a prefix while retaining its prefixed
+tokens. Do not combine the two accidentally; choose the token namespace your
+components expect.
+
+The palette design is independent of the exporter:
+
+```ts
+palette.tokens({ prefix }); // JavaScript maps, native oklch by default
+palette.css({ prefix }); // CSS custom-property declarations
+palette.dtcg({ prefix }); // one design-token tree per scheme
+palette.tailwind({ prefix }); // Tailwind CSS v4 theme
+```
+
+Use `palette.tasty({ prefix })` for [Tasty](../../tasty/README.md) state bindings. See
+[migration.md](migration.md#choosing-an-export) for output shapes, application
+wiring, and the `primary` alias pattern.
+
+## High contrast
+
+High contrast is not a separate palette. Any value that accepts an HC pair can
+tighten the HC variant: `tone`, `contrast`, shadow `intensity`, and mix `value`.
+
+Use HC pairs where users should actually get more separation:
+
+* Text/content contrast: `{ apca: ['content', 'body'] }`.
+* Accent fills: `{ apca: ['content', 'body'] }` or stronger.
+* Borders: `tone: ['-10', '-20']`.
+* Shadows: `intensity: [10, 20]`.
+* Decorative ramps that must stay perceivable.
+
+In HC variants, Glaze bypasses the normal tone window and uses the full
+`[0, 100]` range. Edge tones can reach the edge; contrast floors have more room
+to solve.
+
+### A slider through the tier
+
+The two-tier model assumes contrast is a binary OS preference. When contrast is
+instead a setting *your users* control, set
+[`contrastLevel`](api.md#manual-contrast-level) to a number and your **normal**
+palette slides along a `0–100` ramp: level `0` is the palette you authored, `100`
+is the HC palette you authored, and everything between is resolved at that level.
+
+The authoring work is the same — the HC pairs above are what the slider ramps
+toward, so a palette tuned for high contrast needs no new fields. Two things
+worth planning for:
+
+* The slider and the tier compose. The HC tier keeps resolving at full contrast
+  regardless of the level, so wire the level into your build or runtime *and*
+  keep your `prefers-contrast: more` block: a user who has raised the slider and
+  asked their OS for more contrast still gets the escalation on top. The one
+  exception is level `100`, where the two coincide and the tier is dropped as a
+  duplicate.
+* `contrastLevel: 0` is the natural rest position for a slider you ship but
+  default off — it reproduces the `'auto'` output bit for bit.
+
+## Checklist
+
+Before shipping a palette, verify:
+
+* Text, icon, and content tokens either have APCA/WCAG contrast or are
+  deliberately edge-anchored.
+* Accent fills use `mode: 'fixed'`; accent foregrounds on neutral UI stay
+  `mode: 'auto'` and are based on `surface`.
+* Ambiguous APCA tokens have an explicit `role`; obvious names rely on inference.
+* Low-stakes visual relationships use tone deltas instead of fake contrast
+  floors.
+* `inherit: false` is set on default-only tokens so status themes stay focused.
+* HC pairs exist where high contrast should visibly tighten (they double as the
+  ramp for a manual `contrastLevel`).
+* `glaze.configure({ states, modes })` matches the states registered in the app.
+* Every emitted scheme (`light`, `dark`, `lightContrast`, `darkContrast`) has
+  been reviewed on complete screens, not only in a token grid.
+* Rendered WCAG/APCA results have been checked for chromatic foreground/base
+  pairs that carry accessibility requirements.
+* Resolution emits no unexplained unreachable-contrast or token-collision
+  warnings.