@oxyhq/bloom 0.87.0 → 0.88.0

package/src/design-tokens/tokens-json.ts

@@ -0,0 +1,214 @@
+/**
+ * The machine-readable form of every Bloom design token, in W3C Design Tokens
+ * (DTCG) format.
+ *
+ * The CSS artifacts next to this file (`theme.css`, `bloomThemeCss()`) are the
+ * ALIAS layer and only make sense to a browser. A consumer that is not a
+ * browser — Astro codegens `SkColor` tables for Chromium's native UI so the
+ * toolbar and the WebUI pages cannot disagree about what "primary" is — needs
+ * the RESOLVED values, for every preset and both schemes, in a format it can
+ * read without running Bloom's colour engine. That is this file.
+ *
+ * Same single source as everything else: `getResolvedTokens`, i.e. the colour
+ * engine. `tokens.json` is generated from it by
+ * `scripts/generate-design-tokens-json.ts`, and
+ * `src/__tests__/design-tokens-json.test.ts` fails if the checked-in file is
+ * not byte-identical to a fresh render — so the JSON, the CSS and the runtime
+ * palette cannot drift from each other.
+ */
+
+import {
+  APP_COLOR_NAMES,
+  APP_COLOR_PRESETS,
+  type AppColorName,
+} from '../theme/color-presets';
+import { getResolvedTokens } from '../theme/token-registry';
+import {
+  BORDER_WIDTH,
+  RADIUS,
+  SPACING,
+  TYPOGRAPHY,
+  type TypeRoleName,
+} from './scales';
+
+/** One DTCG token. `$type` is inherited from the nearest group that declares it. */
+export interface DesignToken {
+  $value: string | number;
+  $type?: string;
+  $description?: string;
+}
+
+/** Bloom-specific metadata on a preset group, namespaced per the DTCG `$extensions` rule. */
+export interface PresetExtensions {
+  'so.oxy.bloom': {
+    /** The brand seed the engine derived the whole palette from. */
+    seed: string;
+    /** The tonal scheme variant used with that seed. */
+    variant: string;
+    /** Who may pick the preset; absent means everyone. */
+    gate?: string;
+    /** Present when the preset forces a white label in both schemes. */
+    label?: string;
+  };
+}
+
+export interface PresetGroup {
+  $description: string;
+  $extensions: PresetExtensions;
+  light: Record<string, DesignToken>;
+  dark: Record<string, DesignToken>;
+}
+
+export interface BloomDesignTokens {
+  $description: string;
+  color: { $type: 'color'; $description: string } & Record<string, unknown>;
+  spacing: { $type: 'dimension'; $description: string } & Record<string, unknown>;
+  radius: { $type: 'dimension'; $description: string } & Record<string, unknown>;
+  borderWidth: { $type: 'dimension'; $description: string } & Record<string, unknown>;
+  typography: { $description: string } & Record<string, unknown>;
+}
+
+const FILE_DESCRIPTION = [
+  'Bloom design tokens, resolved. W3C Design Tokens Community Group format.',
+  'SHAPE CONTRACT (consumers codegen against this — additions are additive, existing paths do not move):',
+  'color.<preset>.<scheme>.<token> — <preset> is a Bloom AppColorName, <scheme> is "light" or "dark",',
+  'and <token> is the CSS custom property Bloom writes on the document root with its leading "--" removed,',
+  'so color.oxy.dark.card carries the value of --card under the oxy preset in dark.',
+  'Every colour $value is an sRGB hex string: "#rrggbb", or "#rrggbbaa" when the token carries alpha',
+  '(the -subtle family does). spacing/radius/borderWidth are DTCG dimensions with a px unit in the string.',
+  'typography.<role> is a group of fontSize (dimension), lineHeight (dimension) and fontWeight (number);',
+  'font FAMILIES are deliberately absent — they resolve to CSS variables a non-browser consumer cannot use.',
+  'Shadows are absent for the same reason: Bloom ships them as a platform-forked style object (bloomShadowStyle),',
+  'not as a value.',
+  'AUTO-GENERATED by scripts/generate-design-tokens-json.ts from Bloom’s colour engine — do not edit.',
+].join(' ');
+
+/**
+ * Turn one resolved token value into an sRGB hex string.
+ *
+ * The engine emits exactly two forms — `rgb(r g b)` for opaque tokens and
+ * `rgba(r, g, b, a)` for the translucent `-subtle` family. Anything else is a
+ * change in the engine's output that this file has not been taught about, and
+ * throwing at generation time is the only way that surfaces: a silently
+ * passed-through CSS string would end up in a C++ colour table as garbage.
+ */
+export function resolvedColorToHex(value: string): string {
+  const channels = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)\s*(?:[,/]\s*([\d.]+%?)\s*)?\)$/.exec(
+    value,
+  );
+  if (!channels) {
+    throw new Error(
+      `Bloom token value is not an rgb()/rgba() colour: ${JSON.stringify(value)}`,
+    );
+  }
+
+  const [, red = '0', green = '0', blue = '0', alpha] = channels;
+  const byte = (channel: string): string =>
+    Math.round(Number(channel)).toString(16).padStart(2, '0');
+  const hex = `#${byte(red)}${byte(green)}${byte(blue)}`;
+
+  if (alpha === undefined) return hex;
+  const fraction = alpha.endsWith('%')
+    ? Number(alpha.slice(0, -1)) / 100
+    : Number(alpha);
+  if (fraction >= 1) return hex;
+  return `${hex}${byte(String(fraction * 255))}`;
+}
+
+function schemeTokens(
+  preset: AppColorName,
+  scheme: 'light' | 'dark',
+): Record<string, DesignToken> {
+  const tokens: Record<string, DesignToken> = {};
+  for (const [property, value] of Object.entries(getResolvedTokens(preset, scheme))) {
+    tokens[property.replace(/^--/, '')] = { $value: resolvedColorToHex(value) };
+  }
+  return tokens;
+}
+
+function colorGroup(): BloomDesignTokens['color'] {
+  const group: Record<string, unknown> = {
+    $type: 'color',
+    $description:
+      'One group per Bloom colour preset, each with a light and a dark scheme. Token names match the CSS custom properties without the leading "--".',
+  };
+
+  for (const name of APP_COLOR_NAMES) {
+    const preset = APP_COLOR_PRESETS[name];
+    const extensions: PresetExtensions = {
+      'so.oxy.bloom': { seed: preset.hex, variant: preset.variant },
+    };
+    if (preset.gate) extensions['so.oxy.bloom'].gate = preset.gate;
+    if (preset.label) extensions['so.oxy.bloom'].label = preset.label;
+
+    group[name] = {
+      $description: `Derived by Bloom’s colour engine from seed ${preset.hex} (${preset.variant}).`,
+      $extensions: extensions,
+      light: schemeTokens(name, 'light'),
+      dark: schemeTokens(name, 'dark'),
+    } satisfies PresetGroup;
+  }
+
+  return group as BloomDesignTokens['color'];
+}
+
+function dimensionGroup(
+  description: string,
+  scale: Record<string, number>,
+): BloomDesignTokens['spacing'] {
+  const group: Record<string, unknown> = {
+    $type: 'dimension',
+    $description: description,
+  };
+  for (const [key, value] of Object.entries(scale)) {
+    group[key] = { $value: `${value}px` } satisfies DesignToken;
+  }
+  return group as BloomDesignTokens['spacing'];
+}
+
+function typographyGroup(): BloomDesignTokens['typography'] {
+  const group: Record<string, unknown> = {
+    $description:
+      'One group per type role. Sizes and line-heights are px dimensions; weights are DTCG numeric font weights.',
+  };
+  for (const name of Object.keys(TYPOGRAPHY) as TypeRoleName[]) {
+    const role = TYPOGRAPHY[name];
+    group[name] = {
+      fontSize: { $type: 'dimension', $value: `${role.size}px` },
+      lineHeight: { $type: 'dimension', $value: `${role.lineHeight}px` },
+      fontWeight: { $type: 'fontWeight', $value: Number(role.weight) },
+    };
+  }
+  return group as BloomDesignTokens['typography'];
+}
+
+/** The whole token file, as a plain object. */
+export function bloomDesignTokens(): BloomDesignTokens {
+  return {
+    $description: FILE_DESCRIPTION,
+    color: colorGroup(),
+    spacing: dimensionGroup(
+      'The Oxy spacing scale. Same keys as the Tailwind/NativeWind utilities (p-space-8, gap-space-20, px-screen-margin).',
+      SPACING,
+    ),
+    radius: dimensionGroup(
+      'The corner-radius scale. Same keys as the rounded-radius-* utilities; radius-max is the pill/circle sentinel.',
+      RADIUS,
+    ),
+    borderWidth: dimensionGroup(
+      'Border widths. hairline is the 0.5px rule that pairs with the border-image colour role.',
+      BORDER_WIDTH,
+    ),
+    typography: typographyGroup(),
+  };
+}
+
+/**
+ * The exact bytes of `design-tokens/tokens.json`.
+ *
+ * Both the generator script and the drift test call this, so neither can be
+ * right about the file while the other is wrong.
+ */
+export function renderBloomTokensJson(): string {
+  return `${JSON.stringify(bloomDesignTokens(), null, 2)}\n`;
+}