@sarimarcus/content-sites-ui 0.3.0-rc.0 → 0.4.0-rc.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 0.4.0-rc.0 (2026-09-29)
+
+- `./primitives`: `Badge` and `Chip` (tones and accents are theme roles: `primary`, `secondary`, `accent`, `neutral`, `onImage`, `custom`), `PILL_BASE`, and the badge text limits `BADGE_MAX_CHARS`, `PRICE_LABEL_MAX`, `isBadgeLength`.
+- `./theme.css`: `primary`/`secondary`/`accent` `-tint` and `-emphasis` roles, `badge-on-image(-foreground)`, `chip-on-image(-hover/-foreground)`, so each site keeps its exact pill colours (SLA-2821).
+
+## 0.3.0 (2026-09-29)
+
+- Stable release of 0.3.0-rc.0, unchanged: adopted on all three sites with HTML identical on every page and the contract gate passing (SLA-2821).
+
 ## 0.3.0-rc.0 (2026-09-29)
 
 - `./theme.css`: the semantic theme roles as `--color-X: var(--X)` (18 existing roles moved from the sites, plus `primary`/`secondary`/`accent` `-strong`/`-soft`, `overlay`, `overlay-foreground`) and the radius scale. Sites set the values in `:root` (SLA-2821).

package/README.md

@@ -8,6 +8,27 @@ and `src/styles` holds the Tailwind entry.
 Depends on `@sarimarcus/content-sites-core` (exact lockstep peer) and `@lucide/astro` (the `Icon` primitive). It carries no reader-visible copy:
 text arrives through props and slots.
 
+## Primitives
+
+```ts
+import { Icon, Badge, Chip, PILL_BASE, isBadgeLength, PRICE_LABEL_MAX } from '@sarimarcus/content-sites-ui/primitives';
+```
+
+- `Icon`: any Lucide icon by kebab-case name.
+- `Badge`: a content label (`<span data-badge>`), clamped to `lines` (default 2). Tones: `primary` (default),
+  `secondary`, `accent`, `neutral`, `onImage`, or `custom` with a site-owned `toneClass`.
+- `Chip`: an interactive pill (`<a>`/`<button>`/`<span>`, `data-chip` first). `tone` sets the idle surface
+  (`outline`, `outlineMuted`, `outlineQuiet`, `muted`, `tint`, `onImage`, `custom`), `accent` the hover, active and
+  focus colour (`primary` (default), `secondary`, `accent`, `neutral`). `active` emits `data-active="true"|"false"`
+  only when set; scripts must write `dataset.active = 'true'|'false'`, never add or remove the attribute. Other
+  attributes pass through last, so markers such as `data-section-link` reach the element.
+- `PILL_BASE`: the shared pill geometry. `isBadgeLength`, `BADGE_MAX_CHARS`, `PRICE_LABEL_MAX`: the label-length
+  limits a call site branches on (pill or prose); a price-range schema `.max()` must equal `PRICE_LABEL_MAX`.
+
+`data-badge` and `data-chip` are what `validate-badge-overflow.mjs` selects on, so they are part of the API. Badge and
+Chip colour only through theme roles, including `-tint`, `-emphasis` and the `badge-on-image` / `chip-on-image`
+roles, which each site sets to its own values.
+
 ## Tailwind
 
 Tailwind v4 does not scan `node_modules`, so a site must import the package's source entry next to Tailwind:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-ui",
-  "version": "0.3.0-rc.0",
+  "version": "0.4.0-rc.0",
   "description": "Universal Astro UI components, layout shell and design tokens shared by the content sites.",
   "type": "module",
   "license": "MIT",
@@ -42,6 +42,6 @@
     "@lucide/astro": "^1.23.0",
     "astro": "^7.0.6",
     "tailwindcss": "^4.1.18",
-    "@sarimarcus/content-sites-core": "0.3.0-rc.0"
+    "@sarimarcus/content-sites-core": "0.4.0-rc.0"
   }
 }

package/src/primitives/Badge.astro

@@ -0,0 +1,110 @@
+---
+// ------------------------------------------------------------------
+// Badge — the single pill primitive for content-driven labels (audience tags, event periods,
+// price pills, categories, markers).
+//
+// A pill written as hand-rolled markup has no width or line constraint, so a long content value
+// overflows its card. This component makes the safety net structural.
+//
+// The real guarantee lives in the schema (the `.max()` caps in the site's content config); this
+// clamp is defense in depth and should never visibly fire. That ordering is deliberate: an ellipsis
+// silently destroys meaning and a `title` tooltip is unreachable on touch, so the cap comes first
+// and the clamp only catches regressions. For fields that are legitimately sometimes-prose (a
+// free-text average price), don't reach for a bigger clamp: branch at the call site with
+// `isBadgeLength` from this package and render prose (or no pill) instead.
+//
+// On-image visibility rule: the translucent `primary` tint is for solid page/card backgrounds
+// ONLY. A pill overlaid on a photo must use `onImage` (an opaque scrim with backdrop blur) or a
+// fully opaque tone (`secondary`, or an opaque `custom` toneClass). Never a translucent tint over
+// an image.
+//
+// Sizes, all taking their line-height from the font-size utility:
+//   sm — dense label, extra-small text (tags in card bodies)
+//   md — roomier label, extra-small text (price pills over card photos)
+//   lg — roomiest label, small text (overlays, hero badges)
+// ------------------------------------------------------------------
+import type { HTMLAttributes } from 'astro/types';
+import Icon from './Icon.astro';
+import { PILL_BASE } from './pillRecipe';
+
+// Extends the span attributes so call sites can pass id / aria-* / data-* / slot through.
+interface Props extends Omit<HTMLAttributes<'span'>, 'class'> {
+  /** Preset color. Use `custom` + `toneClass` for runtime category/type color maps. */
+  tone?: 'primary' | 'secondary' | 'accent' | 'neutral' | 'onImage' | 'custom';
+  /** Color classes for tone="custom" (e.g. typeColors[type]). */
+  toneClass?: string;
+  size?: 'sm' | 'md' | 'lg';
+  /** Optional leading Lucide icon name — never shrinks. */
+  icon?: string;
+  /**
+   * Max wrapped lines before ellipsis. 1 = a single line. 0 = no clamp wrapper: the slot renders
+   * directly as children of the pill row (icons/dots stay in the row), relying on the schema caps
+   * and the badge-overflow gate alone. Use 0 for pills migrated from hand-rolled pill markup.
+   * A slotted <svg> REQUIRES 0 (or its own non-block display): preflight changes an svg's display,
+   * so inside the clamp wrapper it stacks ABOVE the label instead of beside it.
+   */
+  lines?: 0 | 1 | 2 | 3;
+  /** Style / tooltip passthrough (HTMLAttributes types them too loosely for astro check). */
+  style?: string;
+  title?: string;
+  /** Passthrough — call sites own the width budget (e.g. a percentage max width). */
+  class?: string;
+}
+
+const {
+  tone = 'primary',
+  toneClass,
+  size = 'sm',
+  icon,
+  lines = 2,
+  class: className,
+  ...rest
+} = Astro.props;
+
+// Astro has already consumed `slot` for slot assignment by the time props arrive; leaving it
+// in the spread renders a stray slot="" attribute on every pill.
+const passthrough = { ...rest };
+delete passthrough.slot;
+
+const tones = {
+  primary: 'bg-primary/10 text-primary-emphasis',
+  secondary: 'bg-secondary text-secondary-foreground',
+  accent: 'bg-accent-tint text-accent-emphasis',
+  neutral: 'bg-muted text-muted-foreground',
+  onImage: 'bg-badge-on-image text-badge-on-image-foreground backdrop-blur-sm',
+  custom: '',
+} as const;
+
+const sizes = {
+  sm: 'px-2 py-0.5 text-xs',
+  md: 'px-3 py-1 text-xs',
+  lg: 'px-3 py-1.5 text-sm',
+} as const;
+
+// `data-badge` is the marker scripts/validate-badge-overflow.mjs selects on. It must stay: the
+// gate used to key on the class string, which silently stopped matching the moment lines={0}
+// dropped the width guard, and a looser class selector then judged hand-rolled <a> chips the
+// 48-char cap was never calibrated for.
+// The width guard is what lets the pill narrow below its intrinsic content width so the clamp can
+// fire. With lines=0 there is no clamp, so it would only let an unwrapped label paint outside its
+// own pill background — the hand-rolled originals carried none.
+const widthGuard = lines === 0 ? undefined : 'min-w-0 max-w-full';
+
+const clamps = { 1: 'truncate', 2: 'line-clamp-2', 3: 'line-clamp-3' } as const;
+const iconSize = size === 'lg' ? 'h-4 w-4' : 'h-3.5 w-3.5';
+---
+
+<span
+  data-badge
+  {...passthrough}
+  class:list={[
+    PILL_BASE,
+    widthGuard,
+    sizes[size],
+    tone === 'custom' ? toneClass : tones[tone],
+    className,
+  ]}
+>
+  {icon && <Icon name={icon} class={`${iconSize} shrink-0`} />}
+  {lines === 0 ? <slot /> : <span class:list={['min-w-0', clamps[lines]]}><slot /></span>}
+</span>

package/src/primitives/Chip.astro

@@ -0,0 +1,248 @@
+---
+// ------------------------------------------------------------------
+// Chip — the pill primitive for INTERACTIVE controls.
+//
+// Badge renders a <span>, so a pill that is a link or a button is excluded from it by
+// construction. Chip stamps `data-chip`, which scripts/validate-badge-overflow.mjs caps at 80
+// chars — a separate, deliberately looser ceiling than Badge's 48, because a control label is a
+// nav label, not a clamped content value.
+//
+// Badge vs Chip, in one line each:
+//   Badge — content labels. A <span>. Clamped. 48 chars. Text comes from a schema field.
+//   Chip  — controls. An <a>/<button>. Free-wrapping, tappable. 80 chars. Text is authored UI copy.
+//
+// THE ORDERING TRAP, and why this component's API looks the way it does.
+//
+// Tailwind v4 emits same-property utilities in ascending NUMERIC order for numeric scales
+// (padding) but in ALPHABETICAL suffix order for everything else. For font size that puts
+// extra-small after small, so extra-small wins; for font weight it puts medium after bold, so a
+// base medium weight beats a passthrough bold one.
+//
+// A `class` passthrough therefore cannot reliably override a preset: padding only goes up, and
+// font size/weight are decided by spelling. So Chip never emits a utility a call site is meant to
+// override. `size` owns padding, `text` owns font size, `weight` owns font weight, and each emits
+// exactly ONE utility, chosen here in TypeScript. That is also why the escape hatches are
+// `text="inherit"` / `weight="inherit"` rather than "pass your own class": they emit arbitrary
+// properties with !important, which win regardless of emission order. Use the `!` PREFIX form: the
+// v4 suffix form emits nothing, and `!` combined with a variant emits nothing at all.
+//
+// Active state is `data-active="true"|"false"`, styled through the data-active=true variant,
+// NEVER a build-time class branch: a scroll-spy mutates `dataset.active` at runtime, and a branch
+// resolved at build time would freeze it. That variant also carries attribute-selector
+// specificity ((0,2,0) vs a plain class's (0,1,0)), so it beats the IDLE colours no matter how
+// emission order falls. Against hover it is only a tie that emission order happens to break the
+// right way today — so a chip whose active state is toggled at RUNTIME and must survive a Tailwind
+// reorder should pass `hover={false}` and spell its inactive hover out.
+//
+// `active` is undefined by default and then NO attribute is emitted at all. That is load-bearing,
+// not tidiness: a chip that has no active state must not advertise one, or a presence-keyed
+// `[data-active]` selector elsewhere on the page matches every chip on first paint. Scripts that
+// drive a chip's active state must write `dataset.active = 'true'|'false'` (value-keyed) — never
+// presence-keyed (`dataset.active = ''` / `delete`), which a `[data-active]` selector also matches.
+// ------------------------------------------------------------------
+import type { HTMLAttributes } from 'astro/types';
+import Icon from './Icon.astro';
+import { PILL_BASE } from './pillRecipe';
+
+type Accent = 'primary' | 'secondary' | 'accent' | 'neutral';
+type Tone = 'outline' | 'outlineMuted' | 'outlineQuiet' | 'muted' | 'tint' | 'onImage' | 'custom';
+
+// `type`/`href`/`rel`/`target` are Omitted rather than just redeclared, because HTMLAttributes<'a'>
+// types them more loosely and narrowing an inherited key is an incompatible override.
+//
+// `Astro.props` is annotated `: Props` explicitly below rather than left to Astro's implicit
+// binding. Without it props degrade to `any`, every map lookup becomes an implicit-any error,
+// and the BUILD STAYS GREEN. Only `astro check` reports it.
+interface Props extends Omit<HTMLAttributes<'a'>, 'class' | 'type' | 'href' | 'rel' | 'target'> {
+  /** Element. Defaults to `a` when `href` is set, else `button`. `span` is for a pill that is only
+   *  sometimes a link (rendered unlinked when there is nowhere to go). A `span` gets no focus ring
+   *  and no hover. */
+  as?: 'a' | 'button' | 'span';
+  href?: string | null;
+  type?: 'button' | 'submit' | 'reset';
+  rel?: string;
+  target?: string;
+  /** Padding + tap target. `md`/`lg` carry a 44px minimum height; `xs`/`sm` do NOT, so a call
+   *  site that needs the 44px tap target on those adds its own. */
+  size?: 'xs' | 'sm' | 'md' | 'lg';
+  /** Font size. Defaults per `size`; `inherit` emits an !important inherited font size. */
+  text?: 'xs' | 'sm' | 'base' | 'inherit';
+  /** `inherit` emits an !important inherited font weight — for chips whose weight lives on their
+   *  children. */
+  weight?: 'medium' | 'inherit';
+  /** Idle surface. */
+  tone?: Tone;
+  /** Hover / active / focus-ring colour. */
+  accent?: Accent;
+  /** Colour classes for tone="custom" (runtime colour maps, three-state pills). */
+  toneClass?: string;
+  /** Active-state classes for tone="custom". Spell them with the data-active=true variant. */
+  activeClass?: string;
+  /** Set false for a chip that deliberately has no hover — scroll-spy rails, filter pills that
+   *  express state through the active variant alone. */
+  hover?: boolean;
+  /** Emits `data-active`. Leave undefined to emit no attribute (see the header note). */
+  active?: boolean;
+  /** Optional leading Lucide icon — never shrinks. */
+  icon?: string;
+  class?: string;
+}
+
+const {
+  as,
+  href,
+  type,
+  rel,
+  target,
+  size = 'md',
+  text,
+  weight = 'medium',
+  tone = 'outline',
+  accent = 'primary',
+  toneClass,
+  activeClass,
+  hover = true,
+  active,
+  icon,
+  class: className,
+  ...rest
+}: Props = Astro.props;
+
+const Tag = as ?? (href ? 'a' : 'button');
+
+// Astro has already consumed `slot` for slot assignment by the time props arrive; leaving it in
+// the spread renders a stray slot="" attribute on every chip.
+const passthrough: Record<string, unknown> = { ...rest };
+delete passthrough.slot;
+
+const sizes = {
+  xs: 'px-2.5 py-1',
+  sm: 'px-3 py-1.5',
+  md: 'px-4 py-2 min-h-[44px]',
+  lg: 'px-5 py-2.5 min-h-[44px]',
+} as const;
+
+const defaultText = { xs: 'xs', sm: 'xs', md: 'sm', lg: 'inherit' } as const;
+
+const texts = {
+  xs: 'text-xs',
+  sm: 'text-sm',
+  base: 'text-base',
+  inherit: '![font-size:inherit] ![line-height:inherit]',
+} as const;
+
+// Idle surfaces. `outlineQuiet` is `outline` with muted label text — for a chip that is a
+// wayfinding aid rather than a primary action.
+const tones = {
+  outline: 'border border-border bg-card text-foreground',
+  outlineMuted: 'border border-border bg-muted/40 text-foreground',
+  outlineQuiet: 'border border-border bg-card text-muted-foreground',
+  muted: 'bg-muted text-muted-foreground',
+  tint: '',
+  onImage: 'bg-chip-on-image text-chip-on-image-foreground backdrop-blur-sm',
+  custom: '',
+} as const;
+
+// The emphasis roles carry the contrast decision per theme: text in the accent hue that reads on
+// its own tint, a card or a muted surface.
+const tints: Record<Accent, string> = {
+  primary: 'bg-primary-tint text-primary-emphasis',
+  secondary: 'bg-secondary-tint text-secondary-emphasis',
+  accent: 'bg-accent-tint text-accent-emphasis',
+  neutral: 'bg-muted text-muted-foreground',
+};
+
+// One hover per tone x accent cell. `outline` hovers by tinting its fill, `outlineQuiet` by
+// recolouring its label.
+const hovers: Record<Exclude<Tone, 'custom'>, Record<Accent, string>> = {
+  outline: {
+    primary: 'hover:border-primary hover:bg-primary/10',
+    secondary: 'hover:border-secondary hover:bg-secondary/10',
+    accent: 'hover:border-accent hover:bg-accent/10',
+    neutral: 'hover:border-foreground/30',
+  },
+  outlineMuted: {
+    primary: 'hover:border-primary hover:bg-primary/10',
+    secondary: 'hover:border-secondary hover:bg-secondary/10',
+    accent: 'hover:border-accent hover:bg-accent/10',
+    neutral: 'hover:border-foreground/30',
+  },
+  outlineQuiet: {
+    primary: 'hover:border-primary hover:text-primary-emphasis',
+    secondary: 'hover:border-secondary hover:text-secondary-emphasis',
+    accent: 'hover:border-accent hover:text-accent-emphasis',
+    neutral: 'hover:border-foreground/30 hover:text-foreground',
+  },
+  muted: {
+    primary: 'hover:bg-primary/10 hover:text-primary-emphasis',
+    secondary: 'hover:bg-secondary/10 hover:text-secondary-emphasis',
+    accent: 'hover:bg-accent/10 hover:text-accent-emphasis',
+    neutral: 'hover:bg-muted/80 hover:text-foreground',
+  },
+  tint: {
+    primary: 'hover:bg-primary/20',
+    secondary: 'hover:bg-secondary/20',
+    accent: 'hover:bg-accent/20',
+    neutral: 'hover:bg-muted/80',
+  },
+  onImage: {
+    primary: 'hover:bg-chip-on-image-hover',
+    secondary: 'hover:bg-chip-on-image-hover',
+    accent: 'hover:bg-chip-on-image-hover',
+    neutral: 'hover:bg-chip-on-image-hover',
+  },
+};
+
+// Deliberately carries no elevation: a call site that wants one on its active state passes it
+// back through `class`, rather than making it the default for every chip.
+const actives: Record<Accent, string> = {
+  primary:
+    'data-[active=true]:border-primary data-[active=true]:bg-primary data-[active=true]:text-primary-foreground',
+  secondary:
+    'data-[active=true]:border-secondary data-[active=true]:bg-secondary data-[active=true]:text-secondary-foreground',
+  accent:
+    'data-[active=true]:border-accent data-[active=true]:bg-accent data-[active=true]:text-accent-foreground',
+  neutral:
+    'data-[active=true]:border-foreground/40 data-[active=true]:bg-foreground/5 data-[active=true]:text-foreground',
+};
+
+const rings: Record<Accent, string> = {
+  primary: 'focus-visible:ring-primary',
+  secondary: 'focus-visible:ring-secondary',
+  accent: 'focus-visible:ring-accent',
+  neutral: 'focus-visible:ring-foreground/40',
+};
+
+const interactive = Tag !== 'span';
+// A non-interactive chip must not advertise a hover any more than a focus ring: inheriting the
+// linked variant's hover makes an unclickable pill look clickable.
+const showHover = hover && interactive;
+const iconSize = size === 'lg' ? 'h-4 w-4' : 'h-3.5 w-3.5';
+const resolvedText = texts[text ?? defaultText[size]];
+---
+
+<Tag
+  data-chip
+  href={Tag === 'a' ? href : undefined}
+  type={Tag === 'button' ? (type ?? 'button') : undefined}
+  rel={Tag === 'a' ? (rel ?? (target === '_blank' ? 'noopener noreferrer' : undefined)) : undefined}
+  target={Tag === 'a' ? target : undefined}
+  data-active={active === undefined ? undefined : active ? 'true' : 'false'}
+  class:list={[
+    PILL_BASE,
+    Tag === 'button' && 'cursor-pointer',
+    sizes[size],
+    resolvedText,
+    weight === 'inherit' && '![font-weight:inherit]',
+    tone === 'custom' ? toneClass : tone === 'tint' ? tints[accent] : tones[tone],
+    tone !== 'custom' && 'transition-[background-color,border-color,color] duration-200',
+    showHover && tone !== 'custom' && hovers[tone][accent],
+    tone === 'custom' ? activeClass : active !== undefined && actives[accent],
+    interactive && `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 ${rings[accent]}`,
+    className,
+  ]}
+  {...passthrough}
+>
+  {icon && <Icon name={icon} class={`${iconSize} shrink-0`} />}
+  <slot />
+</Tag>

package/src/primitives/badgeText.ts

@@ -0,0 +1,37 @@
+/**
+ * Badge label-length helpers.
+ *
+ * Several content fields are author-written free text that is sometimes a short label ("€15–25")
+ * and sometimes a full sentence carrying real information ("€80 for six courses to €100 for nine;
+ * wine pairing available"). The long form is long because the fact is complicated, and there is
+ * no shorter true version.
+ *
+ * So a pill is the wrong home for it. Truncating destroys the information, and a `title`
+ * tooltip is unreachable on touch. The call site branches instead: short values render as a Badge,
+ * long ones as prose (or the card pill is omitted and the detail page's prose row carries it).
+ *
+ * Two different contracts with a site's content schema:
+ *
+ * - A price range that is ALWAYS a pill label: its schema `.max()` MUST equal PRICE_LABEL_MAX.
+ *   Change both or neither. When they drifted (schema 40, display gate 24), a quarter of the
+ *   entries had a schema-valid price that rendered no pill at all.
+ * - A price field that MAY be prose: the schema allows more, and pills render it only when
+ *   `isBadgeLength(v, PRICE_LABEL_MAX)`.
+ */
+
+/** Longest string that still reads as a label rather than a sentence. */
+export const BADGE_MAX_CHARS = 24;
+
+/** Longest price label that still belongs in a pill. Equals the price-range schema `.max()`. */
+export const PRICE_LABEL_MAX = 40;
+
+/**
+ * True when `value` is short enough to render inside a pill.
+ *
+ * @param value Raw content field; `undefined`/blank returns false so callers can
+ *              use this as a single presence-and-length guard.
+ * @param max   Override for surfaces with more or less room than the default.
+ */
+export function isBadgeLength(value?: string | null, max: number = BADGE_MAX_CHARS): boolean {
+  return typeof value === 'string' && value.trim().length > 0 && value.trim().length <= max;
+}

package/src/primitives/index.ts

@@ -1,2 +1,6 @@
 // Public surface of @sarimarcus/content-sites-ui/primitives.
 export { default as Icon } from './Icon.astro';
+export { default as Badge } from './Badge.astro';
+export { default as Chip } from './Chip.astro';
+export { PILL_BASE } from './pillRecipe';
+export { BADGE_MAX_CHARS, PRICE_LABEL_MAX, isBadgeLength } from './badgeText';

package/src/primitives/pillRecipe.ts

@@ -0,0 +1,18 @@
+/**
+ * The pill shape, in one place. Badge and Chip both build on it.
+ *
+ * Geometry only: the pill shape, the row layout, the gap, the weight. Nothing about size, colour
+ * or state.
+ *
+ * Size scales are deliberately NOT shared, and should not be unified later:
+ *
+ * - Badge's sm/md/lg is a label scale. It sits inside a card without stealing room, and its
+ *   ceiling is the 48-char content cap.
+ * - Chip's xs/sm/md/lg is a touch-target scale (md and lg carry a 44px minimum height). It has to
+ *   be tappable, and its ceiling is the 80-char control cap.
+ *
+ * Merging them would make one of those two jobs lose. scripts/validate-badge-overflow.mjs enforces
+ * the two ceilings separately for the same reason, and pre-filters pages on this recipe's
+ * full-radius class, so that class must stay here.
+ */
+export const PILL_BASE = 'inline-flex items-center gap-1.5 rounded-full font-medium';

package/src/styles/theme.css

@@ -1,7 +1,9 @@
 /* Semantic theme roles. A site imports this right after its own `@theme inline` block and sets a value for every
-   role below in its `:root` (`--X` for each `--color-X: var(--X)`), plus `--radius`. Runtime vars, so a site's
+   role below in its `:root` (`--X` for each `--color-X: var(--X)`), plus `--radius`. A `-tint` value carries its own
+   alpha (a colour-mix), so a site keeps its tint strength; `-emphasis` is the accent-coloured text that reads on a
+   tint, a card or a muted surface. Runtime vars, so a site's
    `.dark` block and its non-Tailwind sheets (consent, search, map) read the same values. No brand names here:
-   scripts/platform/theme-contract.mjs checks both rules. */
+   scripts/platform/validate-theme-contract.mjs checks both rules. */
 @theme inline {
   --radius-sm: calc(var(--radius) - 4px);
   --radius-md: calc(var(--radius) - 2px);
@@ -21,20 +23,31 @@
   --color-primary-foreground: var(--primary-foreground);
   --color-primary-strong: var(--primary-strong);
   --color-primary-soft: var(--primary-soft);
+  --color-primary-tint: var(--primary-tint);
+  --color-primary-emphasis: var(--primary-emphasis);
   --color-secondary: var(--secondary);
   --color-secondary-foreground: var(--secondary-foreground);
   --color-secondary-strong: var(--secondary-strong);
   --color-secondary-soft: var(--secondary-soft);
+  --color-secondary-tint: var(--secondary-tint);
+  --color-secondary-emphasis: var(--secondary-emphasis);
   --color-muted: var(--muted);
   --color-muted-foreground: var(--muted-foreground);
   --color-accent: var(--accent);
   --color-accent-foreground: var(--accent-foreground);
   --color-accent-strong: var(--accent-strong);
   --color-accent-soft: var(--accent-soft);
+  --color-accent-tint: var(--accent-tint);
+  --color-accent-emphasis: var(--accent-emphasis);
   --color-destructive: var(--destructive);
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);
   --color-overlay: var(--overlay);
   --color-overlay-foreground: var(--overlay-foreground);
+  --color-badge-on-image: var(--badge-on-image);
+  --color-badge-on-image-foreground: var(--badge-on-image-foreground);
+  --color-chip-on-image: var(--chip-on-image);
+  --color-chip-on-image-hover: var(--chip-on-image-hover);
+  --color-chip-on-image-foreground: var(--chip-on-image-foreground);
 }