@prestack/thread-ui 0.1.10 → 0.1.11

package/dist/ui/styleguide.ts

@@ -1,231 +0,0 @@
-import type { MODES } from './modes.ts'
-import { held, sheeted, type Holds, type Token } from './token.ts'
-import type { TOKENS } from './tokens.ts'
-
-type ModeId = (typeof MODES)['holds'][number]['id']
-
-export interface StyleGuide {
-  readonly id: string
-
-  readonly picks: readonly {
-    readonly id: string
-
-    readonly token: (typeof TOKENS)['holds'][number]['id'] | (typeof TOKENS)['declares'][number]['id']
-
-    readonly is?: string
-
-    readonly asks?: Readonly<Record<string, string | number>>
-
-    readonly modes?: Readonly<Partial<Record<ModeId, string>>>
-
-    readonly themes?: Readonly<
-      Record<
-        string,
-        {
-          readonly is?: string
-          readonly modes?: Readonly<Partial<Record<ModeId, string>>>
-        }
-      >
-    >
-  }[]
-}
-
-export function themedBy(theme: string): string {
-  return `:root[data-theme="${theme}"]`
-}
-
-function tokenFor(
-  guide: StyleGuide | undefined,
-  pick: { readonly id: string; readonly token: string },
-  tokens: Readonly<Record<string, Token>>,
-): Token {
-  const found = tokens[pick.token]
-  if (found !== undefined) return found
-  throw new Error(
-    `\`${guide?.id ?? 'a style guide'}\` states \`${pick.id}\`, and no token \`${pick.token}\` is ` +
-      'declared. A token has to exist before the style guide can give it a value.',
-  )
-}
-
-const HEX = /^#[0-9a-fA-F]{3,8}$/
-const ZERO_OR_LENGTH = /^(0|\d+(\.\d+)?px)$/
-const LENGTH = /^\d+(\.\d+)?px$/
-const INTEGER = /^\d+$/
-const DECIMAL = /^\d+(\.\d+)?$/
-const TRACKING = /^-?\d+(\.\d+)?(em)?$/
-const DURATION = /^\d+(\.\d+)?ms$/
-const RATIO = /^\d+\s*\/\s*\d+$/
-const CALL = /^[a-z][a-zA-Z-]*\([^()]*\)$/
-
-interface Shape {
-  readonly suits: (value: string) => boolean
-  readonly looks: string
-}
-
-const matches = (test: RegExp, looks: string): Shape => ({ suits: (value) => test.test(value), looks })
-
-const among = (words: readonly string[]): Shape => ({
-  suits: (value) => words.includes(value),
-  looks: words.map((word) => `\`${word}\``).join(' · '),
-})
-
-const prefixed = (starts: readonly string[], looks: string): Shape => ({
-  suits: (value) => starts.some((one) => value.startsWith(one)),
-  looks,
-})
-
-const SHAPES: Readonly<Record<string, Shape>> = {
-  colour: {
-    suits: (value) => HEX.test(value) || value.startsWith('color-mix(') || value === 'transparent',
-    looks: 'a hex colour, a `color-mix(...)`, or `transparent`',
-  },
-
-  shadow: {
-    suits: (value) => value === 'none' || /^(inset\s+)?-?\d[\d.]*[a-z%]*\s+-?\d/.test(value),
-    looks: 'a box-shadow list — at least an x and a y offset — or `none`',
-  },
-  space: matches(ZERO_OR_LENGTH, 'a length in pixels, or `0`'),
-  radius: matches(ZERO_OR_LENGTH, 'a length in pixels, or `0`'),
-  edge: matches(LENGTH, 'a length in pixels'),
-  type: matches(LENGTH, 'a length in pixels'),
-  icon: matches(LENGTH, 'a length in pixels'),
-  control: matches(LENGTH, 'a length in pixels'),
-  weight: matches(INTEGER, 'a bare number'),
-  layer: matches(INTEGER, 'a bare number'),
-  leading: matches(DECIMAL, 'a bare decimal'),
-  opacity: matches(DECIMAL, 'a bare decimal'),
-  tracking: matches(TRACKING, 'a number, signed, with an optional `em`'),
-  motion: matches(DURATION, 'a duration in `ms`'),
-  ratio: matches(RATIO, 'two numbers divided, like `16 / 9`'),
-  filter: matches(CALL, 'a single CSS function call'),
-  transform: matches(CALL, 'a single CSS function call'),
-
-  animation: matches(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, 'the name of a declared animation'),
-  line: among(['solid', 'dashed', 'none']),
-  case: among(['uppercase', 'none']),
-  cursor: among(['pointer', 'grab', 'grabbing', 'not-allowed']),
-  img: among(['none']),
-
-  layout: among(['flex', 'block', 'inline-block']),
-  flow: among(['row', 'column']),
-
-  align: among(['center', 'flex-start', 'flex-end', 'stretch', 'baseline', 'space-between']),
-  wrap: among(['wrap', 'nowrap']),
-  position: among(['static', 'relative', 'absolute', 'fixed', 'sticky']),
-  visibility: among(['visible', 'hidden', 'collapse']),
-  reach: among(['auto', 'none']),
-  picking: among(['auto', 'none', 'text', 'all']),
-  touch: among(['auto', 'none', 'pan-x', 'pan-y', 'manipulation']),
-  readying: among(['auto', 'transform', 'opacity', 'contents', 'scroll-position']),
-  origin: among(['center', 'top', 'bottom', 'left', 'right']),
-  overflow: among(['visible', 'hidden', 'clip', 'scroll', 'auto']),
-  blur: prefixed(['blur('], 'a `blur(...)`'),
-  ease: prefixed(['cubic-bezier('], 'a `cubic-bezier(...)`'),
-  noise: prefixed(['url('], 'a `url(...)`'),
-  gradient: prefixed(
-    ['linear-gradient(', 'radial-gradient(', 'conic-gradient('],
-    'a `linear-gradient(...)`, `radial-gradient(...)` or `conic-gradient(...)`',
-  ),
-  texture: prefixed(
-    ['repeating-linear-gradient(', 'repeating-radial-gradient('],
-    'a `repeating-linear-gradient(...)` or `repeating-radial-gradient(...)`',
-  ),
-}
-
-export function kindsHeld(): readonly string[] {
-  return Object.keys(SHAPES).sort()
-}
-
-export function shapeOf(kind: string): { readonly suits: (value: string) => boolean; readonly looks: string } | undefined {
-  return SHAPES[kind]
-}
-
-function suited(
-  guide: StyleGuide | undefined,
-  pick: { readonly id: string; readonly token: string },
-  value: string,
-): string {
-  const shape = SHAPES[pick.token]
-  if (shape === undefined || shape.suits(value)) return value
-  throw new Error(
-    `\`${guide?.id ?? 'a style guide'}\` states \`${pick.id}\` as "${value}", and \`${pick.token}\` holds ` +
-      `${shape.looks}. A row's value has to look like the kind it names.`,
-  )
-}
-
-function valued(
-  guide: StyleGuide | undefined,
-  pick: StyleGuide['picks'][number],
-  tokens: Readonly<Record<string, Token>>,
-): Holds {
-  const token = tokenFor(guide, pick, tokens)
-  if (pick.is !== undefined) return sheeted(pick.id, suited(guide, pick, pick.is))
-  if (token.makes !== undefined) return sheeted(pick.id, token.makes(pick.asks ?? {}))
-  throw new Error(
-    `\`${pick.id}\` states no value, and \`${pick.token}\` carries no rule to make one from. ` +
-      'A style guide row is either a value or the arguments a token turns into one.',
-  )
-}
-
-export function chosen(
-  guide: StyleGuide | undefined,
-  tokens: Readonly<Record<string, Token>>,
-): Readonly<Record<string, Holds>> {
-  const made: Record<string, Holds> = {}
-  for (const pick of guide?.picks ?? []) made[pick.id] = valued(guide, pick, tokens)
-
-  const named = new Set(Object.keys(made))
-  for (const id of Object.keys(made)) held(named, made[id] ?? '', id)
-
-  return made
-}
-
-function themesFor(
-  guide: StyleGuide | undefined,
-  pick: StyleGuide['picks'][number],
-  themes: ReadonlySet<string>,
-): void {
-  for (const theme of Object.keys(pick.themes ?? {})) {
-    if (themes.has(theme)) continue
-    const list = [...themes].sort().map((one) => `\`${one}\``)
-    const known =
-      list.length === 0
-        ? 'The app declares no themes.'
-        : `The declared themes are ${list.join(', ')}.`
-    throw new Error(
-      `\`${guide?.id ?? 'a style guide'}\` states \`${pick.id}\`, and no theme \`${theme}\` is ` +
-        `declared. ${known}`,
-    )
-  }
-}
-
-export function shifted(
-  guide: StyleGuide | undefined,
-  tokens: Readonly<Record<string, Token>>,
-  mode: string | undefined,
-  theme: string | undefined,
-  themes: ReadonlySet<string>,
-): Readonly<Record<string, Holds>> {
-  const named = new Set((guide?.picks ?? []).map((pick) => pick.id))
-  const made: Record<string, Holds> = {}
-
-  for (const pick of guide?.picks ?? []) {
-    tokenFor(guide, pick, tokens)
-    themesFor(guide, pick, themes)
-
-    const under = theme === undefined ? undefined : pick.themes?.[theme]
-
-    const value =
-      theme === undefined
-        ? mode === undefined
-          ? undefined
-          : pick.modes?.[mode as ModeId]
-        : mode === undefined
-          ? under?.is
-          : under?.modes?.[mode as ModeId]
-
-    if (value !== undefined) made[pick.id] = held(named, suited(guide, pick, value), pick.id)
-  }
-
-  return made
-}

package/dist/ui/styleguides.ts

@@ -1,374 +0,0 @@
-import type { Threaded } from '@prestack/thread/core/thread'
-
-import type { StyleGuide } from './styleguide.ts'
-import type { Token } from './token.ts'
-import type { SHADOW } from './tokens/shadow.ts'
-
-const here = 'thread/ui/styleguides.ts'
-
-const said = [
-  {
-    on: '2026-08-24',
-    said: 'The list of variables with default values is the style guide. Style guide says we have colour accent, colour background, colour that, and defines the values that are a pattern we can use. We have rows here too, kinda like tailwind.',
-  },
-]
-
-type Unsectioned = Omit<Threaded, 'at'> & StyleGuide['picks'][number]
-
-type Row = Unsectioned & { readonly section: string }
-
-const section = (name: string, rows: readonly Unsectioned[]): readonly Row[] =>
-  rows.map((row) => ({ ...row, section: name }))
-
-const one = (
-  id: string,
-  token: Row['token'],
-  is: string,
-  describes: string,
-  modes?: Row['modes'],
-): Unsectioned => ({
-  id,
-  token,
-  is,
-  describes,
-  version: 1,
-  ...(modes === undefined ? {} : { modes }),
-})
-
-const made = <T extends 'shadow'>(
-  id: string,
-  token: T,
-  asks: { readonly shadow: typeof SHADOW extends Token<infer Asks> ? Asks : never }[T],
-  describes: string,
-): Unsectioned => ({ id, token, asks, describes, version: 1 })
-
-export const holds: readonly Row[] = [
-  ...section('grounds', [
-    one('colour-page', 'colour', '#f8fbfa', 'What lies behind everything — the furthest surface back, which nothing sits under.', { dark: '#0d100f' }),
-    one('colour-surface', 'colour', '#ffffff', 'The panel a thing is drawn on. One step forward from the page, and what a card or a sheet is painted in.', { dark: '#161a18' }),
-    one('colour-raised', 'colour', '#ffffff', 'A surface lifted above its neighbours — a menu over a page, a dialog over a menu.', { dark: '#1f2322' }),
-    one('colour-sunken', 'colour', '#f0f5f3', 'A surface pressed into the page — a well, an input trough, an inactive tab.', { dark: '#070a09' }),
-    one('colour-clear', 'colour', 'transparent', 'No ground at all — whatever is behind shows through unchanged. Named rather than left unset, because a ghost button choosing to have no fill is a decision, and a material that sets nothing is one somebody forgot to finish.'),
-  ]),
-
-  ...section('ink', [
-    one('colour-ink', 'colour', '#141716', 'What words are written in. The darkest thing on a light page, and the first colour a reader resolves.', { dark: '#f3f6f5' }),
-    one('colour-ink-soft', 'colour', '#666e6b', 'Wording that supports rather than states — a caption, a hint, a label beside a value.', { dark: '#9ea7a3' }),
-    one('colour-ink-faint', 'colour', '#9ea7a3', 'Wording that is present but not being read — a placeholder, a disabled control, a watermark.', { dark: '#6b7470' }),
-    one('colour-on-accent', 'colour', '#141716', 'What words become when they sit on the accent. Never assumed to be white — it is chosen so the pair can be read.', { dark: '#0f1211' }),
-  ]),
-
-  ...section('accent', [
-    one('colour-accent', 'colour', '#43e2b6', 'The one colour an app is recognised by, and the one that says which thing on a screen is being asked for.', { dark: '#47f5c5' }),
-    one('colour-accent-hover', 'colour', 'color-mix(in oklab, var(--colour-accent) 92%, var(--colour-ink))', 'The accent colour with a little ink mixed in — enough that a surface being pointed at reads as reacting, not enough that it stops reading as the accent.'),
-    one('colour-accent-press', 'colour', 'color-mix(in oklab, var(--colour-accent) 85%, var(--colour-ink))', 'The accent colour with more ink mixed in than its hover — enough that a surface being pressed as well as pointed at reads as pushed in, not enough that it stops reading as the accent.'),
-    one('colour-positive', 'colour', '#09bb83', 'Something completed, granted or in good standing. Never the only signal, because a third of readers cannot separate it from negative. It sits in the accent’s family and is darker and greener than it, so a success reads as good news rather than as the thing being asked for.', { dark: '#48dba2' }),
-    one('colour-negative', 'colour', '#dc2626', 'Something refused, failed or destructive. Reserved for consequence, so it keeps its force.'),
-    one('colour-negative-hover', 'colour', 'color-mix(in oklab, var(--colour-negative) 92%, var(--colour-ink))', 'The negative colour with a little ink mixed in, so a destructive control being pointed at reads as reacting without stopping reading as destructive.'),
-    one('colour-negative-press', 'colour', 'color-mix(in oklab, var(--colour-negative) 85%, var(--colour-ink))', 'The negative colour with more ink mixed in than its hover — a destructive control being pushed in.'),
-    one('colour-on-negative', 'colour', '#ffffff', 'What words become when they sit on the negative colour. Chosen so the pair can be read, never assumed to be white for the same reason the accent one is not.'),
-    one('colour-warning', 'colour', '#d97706', 'Something that will go wrong if left alone. Between positive and negative rather than a weaker negative.'),
-    one('colour-info', 'colour', '#0284c7', 'Something worth knowing that asks for nothing. Distinct from accent so an explanation does not read as a request.'),
-  ]),
-
-  ...section('edges', [
-    one('colour-edge', 'colour', '#dce3e0', 'The line that separates without drawing attention — between rows, around a quiet panel.', { dark: '#2a2f2d' }),
-    one('colour-edge-faint', 'colour', 'color-mix(in oklab, var(--colour-ink) 12%, transparent)', 'The edge of a surface that is only just an edge — the ink of the page, thinned until it reads as a boundary rather than a line. It thins less in the dark, because a dark surface swallows a border that a light one would show.', { dark: 'color-mix(in oklab, var(--colour-ink) 22%, transparent)' }),
-    one('colour-edge-glass', 'colour', 'color-mix(in oklab, var(--colour-on-accent) 55%, transparent)', 'The edge of something you can see through, caught by the light behind it rather than drawn on top.', { dark: 'color-mix(in oklab, var(--colour-ink) 28%, transparent)' }),
-    one('colour-glass', 'colour', 'color-mix(in oklab, var(--colour-surface) 52%, transparent)', 'A surface you can see through — the surface colour, held back far enough for what is behind it to carry. It holds back less in the dark, because a dark backdrop shows through more readily.', { dark: 'color-mix(in oklab, var(--colour-surface) 64%, transparent)' }),
-    one('colour-surface-lit', 'colour', 'color-mix(in oklab, var(--colour-surface) 91%, var(--colour-accent))', 'The surface colour with a trace of the accent mixed in — enough that a surface asking for attention reads as lit from within, not enough that it stops reading as the surface.'),
-    one('colour-surface-alert', 'colour', 'color-mix(in oklab, var(--colour-surface) 91%, var(--colour-negative))', 'The surface colour with a trace of the negative mixed in — what appears under a pointer on something destructive that has no fill of its own, so the ground it gains still says what it will do.'),
-    one('colour-edge-lit', 'colour', 'color-mix(in oklab, var(--colour-accent) 76%, transparent)', 'The edge of something lit rather than framed — mostly accent, thinned just enough to glow at the boundary instead of drawing a line across it.'),
-    one('colour-edge-clay', 'colour', 'color-mix(in oklab, var(--colour-on-accent) 15%, transparent)', 'The faint rim of a surface moulded rather than cut — barely there, the way light catches the edge of something raised and rounded instead of framed.'),
-    one('colour-edge-ceramic', 'colour', 'color-mix(in oklab, var(--colour-on-accent) 10%, transparent)', 'The faint rim of a glazed surface, thinner than a moulded edge because a glaze catches less light at the boundary than a raised surface does.'),
-    one('colour-edge-strong', 'colour', '#d6d3d1', 'The line that is meant to be seen — a focused field, a chosen option, a boundary that matters.', { dark: '#3f3f3f' }),
-    one('colour-scrim', 'colour', '#0a0a0a', 'The veil laid over a page while something in front of it is being answered.'),
-  ]),
-
-  ...section('space', [
-    one('space-0', 'space', '0', 'No room at all. Named rather than written as zero so that removing space is a decision on the sheet.'),
-    one('space-1', 'space', '4px', 'The smallest gap that still separates — between an icon and the word beside it.'),
-    one('space-2', 'space', '8px', 'A gap inside one thing: the parts of a chip, a label above its field.'),
-    one('space-3', 'space', '12px', 'The room inside something small and pressable — a button, a row of a list.'),
-    one('space-4', 'space', '16px', 'The room inside an ordinary panel, and the gap between things that belong together.'),
-    one('space-5', 'space', '24px', 'The gap between things that are related but separate — two cards in a column.'),
-    one('space-6', 'space', '32px', 'The gap between sections of one screen.'),
-    one('space-7', 'space', '48px', 'The gap between one part of a page and the next, where a reader should feel a break.'),
-    one('space-8', 'space', '64px', 'The room around a whole region — the margin a page breathes in.'),
-    one('space-9', 'space', '96px', 'The largest room on the scale, for the space above and below a hero.'),
-  ]),
-
-  ...section('radius', [
-    one('radius-none', 'radius', '0', 'Square corners. Named so that a thing choosing to be square is a decision rather than an omission.'),
-    one('radius-sm', 'radius', '6px', 'Barely rounded — enough to soften a hard edge without reading as a shape.'),
-    one('radius-md', 'radius', '14px', 'The ordinary rounding of a panel, a field, a card.'),
-    one('radius-lg', 'radius', '24px', 'Rounding that becomes part of the look — a sheet, a large surface, a modal.'),
-    one('radius-xl', 'radius', '32px', 'The most rounded a rectangle gets before it stops reading as one.'),
-    one('radius-pill', 'radius', '999px', 'Fully round ends, whatever the height. What makes a chip a chip.'),
-  ]),
-
-  ...section('borders', [
-    one('edge-hair', 'edge', '0.5px', 'A line at the limit of what a screen can draw — present, and not a border anybody notices.'),
-    one('edge-thin', 'edge', '1px', 'An ordinary border.'),
-    one('edge-thick', 'edge', '2px', 'A border doing work — a focus ring, a chosen state, a deliberate frame.'),
-    one('line-solid', 'line', 'solid', 'An unbroken line. The default way a border is drawn.'),
-    one('line-dashed', 'line', 'dashed', 'A broken line, for a boundary that is provisional — a drop target, an empty slot.'),
-    one('line-off', 'line', 'none', 'No line drawn, however wide the border was set. How a border is removed without removing the rule that put it there.'),
-  ]),
-
-  ...section('shadow', [
-    one('shadow-0', 'shadow', 'none', 'Flat on the surface. Named so that being flat is a choice a variant makes.'),
-    made('shadow-1', 'shadow', { y: 1, blur: 2, alpha: 0.06 }, 'Barely lifted — enough to separate a row from what is behind it.'),
-    made('shadow-2', 'shadow', { y: 4, blur: 12, alpha: 0.1 }, 'Lifted — a card, a resting panel.'),
-    made('shadow-3', 'shadow', { y: 12, blur: 28, alpha: 0.14 }, 'Well clear of the page — a menu, a popover.'),
-    made('shadow-4', 'shadow', { y: 24, blur: 56, alpha: 0.2 }, 'Above everything — a dialog, a sheet dragged over the app.'),
-    made('shadow-inset', 'shadow', { y: 2, blur: 4, alpha: 0.08, inset: 'inset' }, 'Pressed in rather than lifted out — a trough, a held button.'),
-    one('shadow-glow', 'shadow', '0 0 24px rgba(14, 165, 233, 0.45)', 'Light thrown outward rather than a shadow cast — how a thing reads as lit.'),
-    one('shadow-hard', 'shadow', '5px 5px 0 0 var(--colour-ink)', 'An offset with no blur at all — a second edge stacked behind the surface rather than a shadow it casts. What gives a bordered card its cut-paper look.'),
-    one('shadow-moulded', 'shadow', '8px 8px 19px color-mix(in oklab, var(--colour-ink) 45%, transparent), -8px -8px 19px color-mix(in oklab, var(--colour-surface) 85%, transparent)', 'A shadow paired with its own highlight, dark on one side and pale on the other — how a surface reads as pressed from the page rather than laid on top of it.'),
-  ]),
-
-  ...section('blur', [
-    one('blur-sm', 'blur', 'blur(8px) saturate(1.2)', 'What shows through is softened a little. Saturation rides along, because a blur without it reads grey.'),
-    one('blur-md', 'blur', 'blur(17px) saturate(1.4)', 'The ordinary glass amount — a surface you can tell something is behind.'),
-    one('blur-lg', 'blur', 'blur(32px) saturate(1.6)', 'What is behind becomes colour and light rather than shape.'),
-  ]),
-
-  ...section('motion', [
-    one('motion-instant', 'motion', '0ms', 'No transition. Named so that a thing changing at once is a decision.'),
-    one('motion-quick', 'motion', '150ms', 'A change that answers a press — fast enough to feel like the tap did it.'),
-    one('motion-normal', 'motion', '250ms', 'An ordinary change of state, long enough to be followed by the eye.'),
-    one('motion-slow', 'motion', '400ms', 'Something arriving or leaving, where the movement itself is telling you what happened.'),
-  ]),
-
-  ...section('easing', [
-    one('ease-out', 'ease', 'cubic-bezier(0.4, 0, 0.2, 1)', 'Fast then settling. What almost everything entering a screen should use.'),
-    one('ease-in', 'ease', 'cubic-bezier(0.4, 0, 1, 1)', 'Slow then away. For a thing leaving, where the exit should not be watched.'),
-    one('ease-in-out', 'ease', 'cubic-bezier(0.65, 0, 0.35, 1)', 'Eased at both ends, for a change that starts and finishes on the screen.'),
-    one('ease-steady', 'ease', 'cubic-bezier(0, 0, 1, 1)', 'Paced evenly from end to end. The one easing a repeating turn can use, because anything else stutters once every revolution.'),
-    one('ease-spring', 'ease', 'cubic-bezier(0.32, 0.72, 0.28, 1.04)', 'Overshoots slightly and comes back, which reads as a physical thing rather than a value changing.'),
-  ]),
-
-  ...section('layer', [
-    one('layer-base', 'layer', '0', 'The plane the page is laid out on.'),
-    one('layer-raised', 'layer', '10', 'Above the page but part of it — a sticky header inside a panel, a hovered card.'),
-    one('layer-sticky', 'layer', '20', 'Pinned while content moves beneath it.'),
-    one('layer-overlay', 'layer', '30', 'A menu, a popover, a tooltip — above the app and dismissed by looking away.'),
-    one('layer-modal', 'layer', '40', 'The thing that must be answered, and the veil that comes with it.'),
-    one('layer-toast', 'layer', '50', 'Above even a dialog, because a message about the whole app outranks whatever is open.'),
-    one('layer-carried', 'layer', '60', 'What is following a finger or a cursor right now, which nothing may cover while it is being carried. The top of this ladder, and the only thing that belongs there — the drag ghost wrote `2147483647` before this row existed, which is a shout rather than a decision.'),
-  ]),
-
-  ...section('control', [
-    one('control-sm', 'control', '32px', 'The height of something pressable in a dense row.'),
-    one('control-md', 'control', '40px', 'The ordinary height of a button or a field.'),
-    one('control-lg', 'control', '48px', 'The height of a primary action, and the smallest a touch target should be on a phone.'),
-    one('control-radius', 'radius', '14px', 'How far the corner of a pressable thing is turned. Every button takes this one row, so squaring the whole app is one change here and none anywhere else — which is why it is not `radius-md` written into fourteen variants.'),
-    one('control-pad-x', 'space', '20px', 'The room to the left and right of what a control holds. Its own row rather than a step on the space scale, because the gap between two cards and the room inside a button are different decisions that happen to have landed on the same number.'),
-    one('control-pad-y', 'space', '8px', 'The room above and below what a control holds. Less than the horizontal room, which is what stops a button reading as a square with a word in it. It is what `control-md` has left after `icon-md`, and that is not a coincidence to be maintained by hand: at 10px the three rows could not all hold — 40 less twice 10 leaves 20, and the symbol it was holding was 24 — so every icon in every button overflowed its own padding by 2px and sat closer to the edge than any row said. Measured 2026-09-03 in a running app, off the served sheet.'),
-    one('control-pad-square', 'space', '8px', 'The room on every side of a control holding nothing but a symbol. One value on all four sides, so the thing comes out square whatever is in it — which at 10px it did not: 24 and twice 10 is 44, against a `control-md` of 40, so a square control could not also be the height of the buttons beside it. Same arithmetic as `control-pad-y` above and the same number, kept as its own row because the horizontal room is the decision that differs.'),
-    one('control-gap', 'space', '8px', 'The distance between the parts of one control — a symbol and the word beside it.'),
-    one('control-edge', 'edge', '1px', 'How thick the line around a control is drawn, where it is drawn at all.'),
-    one('control-ring', 'edge', '2px', 'How thick the ring a keyboard draws around a control is. Thicker than the control’s own edge, because a ring that matches the border is a ring nobody sees.'),
-    one('control-ring-offset', 'space', '4px', 'How far the keyboard’s ring sits outside the control, so it reads as around the thing rather than as part of it.'),
-  ]),
-
-  ...section('opacity', [
-    one('opacity-none', 'opacity', '0', 'Not drawn at all, while still occupying its place. What a thing fades up from and down to.'),
-    one('opacity-full', 'opacity', '1', 'Fully drawn. Named so that arriving at ordinary is a value an animation can name rather than a number it writes.'),
-    one('opacity-disabled', 'opacity', '0.45', 'Faded far enough to read as unavailable, not so far that it cannot be read at all.'),
-    one('opacity-muted', 'opacity', '0.65', 'Present and receded — a thing still live but not being attended to.'),
-  ]),
-
-  ...section('gradient', [
-    one('gradient-sheen', 'gradient', 'linear-gradient(180deg, color-mix(in oklab, var(--colour-surface) 50%, var(--colour-raised)), color-mix(in oklab, var(--colour-surface) 92%, var(--colour-ink)))', 'Light falling down the face of a surface, brightest at the top. What makes a glazed thing read as glazed.'),
-    one('gradient-fade', 'gradient', 'linear-gradient(180deg, transparent, var(--colour-page))', 'A surface dissolving into the page beneath it, for the bottom of a scrolling region.'),
-  ]),
-
-  ...section('texture', [
-    one('texture-stripe', 'texture', 'repeating-linear-gradient(45deg, color-mix(in oklab, var(--colour-ink) 6%, transparent) 0 1px, transparent 1px 8px)', 'Fine diagonal ruling, the quietest way to say a surface is not blank.'),
-  ]),
-
-  ...section('noise', [
-    one('noise-grain', 'noise', 'url("data:image/svg+xml,%3Csvg xmlns=%27http://www.w3.org/2000/svg%27%3E%3Cfilter id=%27n%27%3E%3CfeTurbulence type=%27fractalNoise%27 baseFrequency=%270.8%27/%3E%3C/filter%3E%3Crect width=%27100%25%27 height=%27100%25%27 filter=%27url(%23n)%27 opacity=%270.035%27/%3E%3C/svg%3E")', 'A faint scattered grain that stops a large flat area reading as dead. Generated rather than drawn, so it costs nothing to ship.'),
-  ]),
-
-  ...section('image', [
-    one('img-none', 'img', 'none', 'No picture at all. Named so that clearing one is a decision rather than an omission.'),
-  ]),
-
-  ...section('ratio', [
-    one('ratio-wide', 'ratio', '16 / 9', 'The shape video is shot in, and what a media block holds before anything has loaded.'),
-    one('ratio-square', 'ratio', '1 / 1', 'Equal sides — an avatar, a tile, a thumbnail.'),
-    one('ratio-portrait', 'ratio', '3 / 4', 'Taller than it is wide, for a photograph held the way a phone is held.'),
-  ]),
-
-  ...section('filter', [
-    one('filter-dimmed', 'filter', 'brightness(0.75)', 'Drawn darker than it is, for something behind what is being attended to.'),
-    one('filter-blurred', 'filter', 'blur(8px)', 'Softened past reading — where a thing sharpening into place starts, and where one dissolving ends.'),
-    one('filter-sharp', 'filter', 'blur(0px)', 'In focus. Named so that arriving at sharp is a value an animation can name rather than the absence of one.'),
-    one('filter-inert', 'filter', 'grayscale(1)', 'Drained of colour, for a thing present but out of play.'),
-  ]),
-
-  ...section('transform', [
-    one('transform-rest', 'transform', 'scale(1)', 'Where a thing sits when nothing is happening to it. Named so that returning to rest is a value an animation can name rather than the absence of one.'),
-    one('transform-press', 'transform', 'scale(0.97)', 'Shrunk very slightly, which is what makes a press feel like it landed.'),
-    one('transform-lift', 'transform', 'translateY(-2px)', 'Raised a little off the page, for a thing being pointed at.'),
-    one('transform-shrink', 'transform', 'scale(0.94)', 'Pulled in further than a press — small enough to read as leaving rather than as reacting.'),
-    one('transform-below', 'transform', 'translateY(8px)', 'Held below where it belongs, which is where a thing rising into place starts and a thing falling out of it ends.'),
-    one('transform-above', 'transform', 'translateY(-8px)', 'Held above where it belongs — where a thing dropping into place starts, and where a thing leaving upward ends.'),
-    one('transform-far-left', 'transform', 'translateX(-24px)', 'Held off to one side, far enough to read as coming from off-stage rather than as a nudge.'),
-    one('transform-far-right', 'transform', 'translateX(24px)', 'The same distance the other way.'),
-    one('transform-swell', 'transform', 'scale(1.04)', 'Grown very slightly — the overshoot a thing passes through on its way to resting, and what a hover uses to say it is reachable.'),
-    one('transform-grow', 'transform', 'scale(1.12)', 'Grown enough to read as arriving from nearer the reader. Where a zoom starts, and where one ends.'),
-    one('transform-tilt', 'transform', 'rotate(-3deg)', 'Turned slightly one way. Half of a wobble, and too small to read as rotation on its own.'),
-    one('transform-tilt-back', 'transform', 'rotate(3deg)', 'Turned slightly the other way. The other half.'),
-    one('transform-turn', 'transform', 'rotate(360deg)', 'A full revolution, which lands exactly where it started and is therefore the only rotation that can repeat without a jump.'),
-    one(
-      'transform-carried',
-      'transform',
-      'scale(0.96)',
-      'How big a thing is while it is being carried, composed after wherever the pointer has taken it. Smaller, because something lifted off the page is further from the reader than the page it left. Where it IS cannot be a row — that is the pointer’s to say — but how it looks while it is there is one, and changing this changes every drag in an app at once.',
-    ),
-    one(
-      'transform-carried-turn',
-      'transform',
-      'rotate(-1.5deg)',
-      'How far a carried thing hangs off square, composed after its size. It is a second row rather than part of the first because a `transform` row holds ONE function call — `scale(0.96) rotate(-1.5deg)` is refused by the kind, and refused loudly: the generator throws and no stylesheet is written at all, which is how a carry that had a size and a tilt ended up with neither and moved nowhere.',
-    ),
-    one('transform-left', 'transform', 'translateX(-4px)', 'Pushed slightly off centre one way. Half of a refusal.'),
-    one('transform-right', 'transform', 'translateX(4px)', 'Pushed slightly off centre the other way. The other half.'),
-  ]),
-
-  ...section('animation', [
-    one('animation-press', 'animation', 'press', 'What anything pressable plays when it is pressed.'),
-    one('animation-appear', 'animation', 'appear', 'What something plays arriving in place, where it was always going to be.'),
-    one('animation-dismiss', 'animation', 'dismiss', 'What something plays on its way out, where it is not coming back.'),
-    one('animation-rise', 'animation', 'rise', 'What a sheet, a menu or a toast plays coming in from below.'),
-    one('animation-fall', 'animation', 'fall', 'The exit that answers a rise.'),
-    one('animation-waiting', 'animation', 'pulse', 'What something plays while it waits — repeated, and saying nothing about how long is left.'),
-    one('animation-working', 'animation', 'spin', 'What something plays while it works and cannot say how far along it is.'),
-    one('animation-refused', 'animation', 'shake', 'What a control plays when what was offered was not accepted.'),
-  ]),
-
-  ...section('animation', [
-    one('animation-drop', 'animation', 'drop', 'What something plays arriving from above — the entrance that answers a rise.'),
-    one('animation-slide-in-left', 'animation', 'slide-in-left', 'What something plays coming in from the left, for a panel or a step arriving from off-stage.'),
-    one('animation-slide-in-right', 'animation', 'slide-in-right', 'What something plays coming in from the right.'),
-    one('animation-slide-out-left', 'animation', 'slide-out-left', 'What something plays leaving to the left.'),
-    one('animation-slide-out-right', 'animation', 'slide-out-right', 'What something plays leaving to the right.'),
-    one('animation-zoom-in', 'animation', 'zoom-in', 'What something plays arriving from nearer the reader, shrinking back to its true size.'),
-    one('animation-zoom-out', 'animation', 'zoom-out', 'What something plays leaving toward the reader as it fades.'),
-    one('animation-pop-in', 'animation', 'pop-in', 'What something plays arriving with an overshoot — past its size and back, which reads as physical rather than as a value changing.'),
-    one('animation-pop-out', 'animation', 'pop-out', 'What something plays leaving with a small swell first, the exit that answers a pop.'),
-    one('animation-blur-in', 'animation', 'blur-in', 'What something plays sharpening into place out of softness.'),
-    one('animation-blur-out', 'animation', 'blur-out', 'What something plays dissolving rather than moving.'),
-    one('animation-hover-lift', 'animation', 'lift', 'What something pointed at plays to say it is reachable — raised a little off the page.'),
-    one('animation-hover-swell', 'animation', 'swell', 'What something pointed at plays when lifting it would move its neighbours: it grows very slightly instead.'),
-    one('animation-hover-nudge', 'animation', 'nudge', 'What a marker beside wording plays when the wording is pointed at — a chevron leaning the way it would take you.'),
-    one('animation-attention', 'animation', 'wobble', 'What something plays to be noticed without being wrong — turned one way and back.'),
-    one('animation-flash', 'animation', 'flash', 'What something plays when its value has just changed underneath the reader, so the change is not missed.'),
-    one('animation-glow', 'animation', 'glow', 'What something plays to read as lit — the light around it swelling and settling.'),
-  ]),
-
-  ...section('cursor', [
-    one('cursor-press', 'cursor', 'pointer', 'Over something that will act if pressed.'),
-    one('cursor-drag', 'cursor', 'grab', 'Over something that can be picked up.'),
-    one('cursor-carrying', 'cursor', 'grabbing', 'Over something currently being carried.'),
-    one('cursor-refuse', 'cursor', 'not-allowed', 'Over something that will not take what is being offered.'),
-  ]),
-
-  ...section('layout', [
-    one('layout-flex', 'layout', 'flex', 'Children laid along one axis, each taking the room it needs. The arrangement nearly everything uses.'),
-    one('layout-block', 'layout', 'block', 'Children stacked as the page stacks paragraphs, each taking the full width. What a thing that is a box rather than an arrangement says — `hit-box` is the one that needs it, being a region a pointer is watched over rather than an arrangement of anything.'),
-    one('layout-inline-block', 'layout', 'inline-block', 'A box that sits in a line rather than starting one, and is a block on the inside. What wording needs in order to be trimmed: `text-box-trim` acts on a block container’s first and last line boxes, and an inline box is not one — so a role carrying the trim reaches nothing when the thing wearing it is inline. Measured 2026-09-03 in a running app: 66 of 90 text elements were trimmed to their cap height exactly, and the 24 that were inline were untouched, every one of them the sole text child of a block parent. Inline-block rather than block because wording still belongs in a line beside other things when an app puts it there.'),
-  ]),
-
-  ...section('flow', [
-    one('flow-across', 'flow', 'row', 'Children run left to right.'),
-    one('flow-down', 'flow', 'column', 'Children run top to bottom.'),
-  ]),
-
-  ...section('align', [
-    one('align-centre', 'align', 'center', 'Children centred across the flow. What a control does with its label and its icon.'),
-    one('align-start', 'align', 'flex-start', 'Children gathered at the start of the cross axis, each keeping its own size rather than stretching.'),
-    one('align-end', 'align', 'flex-end', 'Children gathered at the end of the cross axis.'),
-    one('align-stretch', 'align', 'stretch', 'Children stretched to fill the cross axis, which is what makes a column of cards the same width.'),
-    one('align-baseline', 'align', 'baseline', 'Children lined up on the baseline of their text, so wording of different sizes still reads as one line.'),
-    one('align-between', 'align', 'space-between', 'Children pushed to both ends with what is left over shared between them. Along the flow rather than across it, which is the axis this kind also answers for.'),
-  ]),
-
-  ...section('wrap', [
-    one('wrap-on', 'wrap', 'wrap', 'Children spill onto another line when they run out of room.'),
-    one('wrap-off', 'wrap', 'nowrap', 'Children stay on one line and let it overflow.'),
-  ]),
-
-  ...section('position', [
-    one('position-flow', 'position', 'static', 'Laid where the page put it, taking its own room. What nearly everything is, and what nothing has to say.'),
-    one('position-nudged', 'position', 'relative', 'Moved from where the page put it while the room it left stays its own, so nothing around it shifts. Also what a thing says to become the frame its lifted children are placed against.'),
-    one('position-lifted', 'position', 'absolute', 'Out of the flow and placed against the nearest thing that is not itself in flow. The page keeps no room for it, which is what lets it cover something.'),
-    one('position-pinned', 'position', 'fixed', 'Held against the window rather than the page, so it stays where it is while everything scrolls past.'),
-    one('position-clinging', 'position', 'sticky', 'In flow until scrolling brings it to its edge, and held there until its section is done.'),
-  ]),
-
-  ...section('visibility', [
-    one('visibility-shown', 'visibility', 'visible', 'Rendered, as almost everything is.'),
-    one('visibility-hidden', 'visibility', 'hidden', 'Not rendered, not reachable and not read aloud, while keeping every bit of the room it was given. What holds a layout still across something appearing and disappearing.'),
-    one('visibility-collapsed', 'visibility', 'collapse', 'A row or a column of a table removed without the columns beside it moving.'),
-  ]),
-
-  ...section('reach', [
-    one('reach-open', 'reach', 'auto', 'A press, a hover or a drag lands on it.'),
-    one('reach-through', 'reach', 'none', 'A pointer passes through to whatever is behind. What anything drawn over a control needs, so the control underneath stays pressable.'),
-  ]),
-
-  ...section('picking', [
-    one('picking-open', 'picking', 'auto', 'The wording inside can be selected, as prose should be.'),
-    one('picking-off', 'picking', 'none', 'The wording cannot be selected. What a control wants, so a press that turns into a small drag does not leave a smear of highlight across its label.'),
-    one('picking-words', 'picking', 'text', 'Selectable as text even where what holds it is not.'),
-    one('picking-whole', 'picking', 'all', 'One click takes the whole of it rather than a word. For a code block or an address meant to be copied entire.'),
-  ]),
-
-  ...section('touch', [
-    one('touch-page', 'touch', 'auto', 'A finger dragged across it scrolls the page, as it should nearly everywhere.'),
-    one('touch-own', 'touch', 'none', 'The drag belongs to the thing itself and the page does not move. What anything draggable needs on a phone.'),
-    one('touch-across', 'touch', 'pan-x', 'The page scrolls sideways under the finger and the thing keeps the up-and-down drag.'),
-    one('touch-down', 'touch', 'pan-y', 'The page scrolls up and down under the finger and the thing keeps the sideways drag. What a carousel inside a scrolling page wants.'),
-    one('touch-quick', 'touch', 'manipulation', 'Scrolling and pinching still work, and the wait for a possible double-tap is dropped — which is how a control stops feeling a third of a second late.'),
-  ]),
-
-  ...section('readying', [
-    one('readying-nothing', 'readying', 'auto', 'No warning given, which is right until something is measurably late.'),
-    one('readying-movement', 'readying', 'transform', 'Warns that it is about to move, turn or scale. What a thing being dragged says.'),
-    one('readying-fade', 'readying', 'opacity', 'Warns that it is about to fade in or out.'),
-    one('readying-contents', 'readying', 'contents', 'Warns that what is inside it is about to be replaced entirely.'),
-    one('readying-scroll', 'readying', 'scroll-position', 'Warns that it is about to be scrolled somewhere far from where it is.'),
-  ]),
-
-  ...section('origin', [
-    one('origin-centre', 'origin', 'center', 'Turns and scales about its own middle, which is what a thing does unless it says otherwise.'),
-    one('origin-top', 'origin', 'top', 'Grows downward from its top edge. What a menu opened from something above it does.'),
-    one('origin-bottom', 'origin', 'bottom', 'Grows upward from its bottom edge.'),
-    one('origin-left', 'origin', 'left', 'Grows rightward from its left edge.'),
-    one('origin-right', 'origin', 'right', 'Grows leftward from its right edge.'),
-  ]),
-
-  ...section('overflow', [
-    one('overflow-shown', 'overflow', 'visible', 'What does not fit is drawn past the edge anyway.'),
-    one('overflow-hidden', 'overflow', 'hidden', 'What does not fit is cut off at the edge and cannot be reached.'),
-    one('overflow-clipped', 'overflow', 'clip', 'Cut off at the edge like hidden, and without becoming something that can be scrolled by a script. The stricter of the two.'),
-    one('overflow-scrolls', 'overflow', 'scroll', 'Scrollable, and saying so with a bar whether or not there is anything past the edge.'),
-    one('overflow-as-needed', 'overflow', 'auto', 'Scrollable only once something does not fit.'),
-  ]),
-]
-
-export const STYLEGUIDES: Threaded & { readonly holds: readonly Row[] } = {
-  id: 'styleguide',
-  at: here,
-
-  describes:
-    'Every named value an app has, each saying which token it is one of and what it holds. This is where values live: a row is either the value itself or the arguments a token turns into one, and a row naming a token nobody declared is refused. A material and a variant reach for these names and never for a raw value. An app adds its own rows to the same list and may not remove what the framework put there.',
-  version: 1,
-  cites: said,
-  holds,
-}