@oxyhq/bloom 0.19.1 → 0.20.0

package/src/design-tokens/color-roles.ts

@@ -0,0 +1,110 @@
+/**
+ * Semantic color-role vocabulary for the Oxy Unified Design Language.
+ *
+ * Every role is an ALIAS onto one of Bloom's existing canonical theme tokens
+ * (`--background`, `--surface`, `--primary`, …) — the SINGLE source of resolved
+ * color values produced by `getResolvedTokens` and written to the document root
+ * (web) / `rootVariables` (native) by `BloomThemeProvider`. No color VALUE is
+ * invented here: a role's value is the `var(--canonical)` reference, so it stays
+ * driven by the active light/dark mode and color preset automatically.
+ *
+ * The maps are consumed by the Bloom Tailwind preset (`tailwind-preset.ts`),
+ * which slots them into `theme.extend.{backgroundColor,textColor,borderColor}`.
+ * Because the values are `var(--x)` strings, the SAME class names resolve on
+ * Tailwind (web) and NativeWind (native): web reads the CSS custom property from
+ * `document.documentElement`; native reads it from react-native-css's
+ * `rootVariables` family — both populated by Bloom from one pipeline.
+ *
+ * Web CSS-var contract (see Bloom AGENTS.md): base `--x` tokens already resolve
+ * to a FULL `rgb(...)` color at runtime, so the role values reference them with
+ * `var(--x)` directly — NEVER `hsl(var(--x))`.
+ *
+ * ADDITIVE: these are NEW utility names (`bg-fill`, `text-text-tertiary`,
+ * `border-border-image`, …). They do not touch the existing app-defined color
+ * utilities (`bg-background`, `text-muted-foreground`, …), which keep working.
+ */
+
+/** A `var(--canonical-token)` reference string. */
+type TokenRef = `var(--${string})`;
+
+const ref = (token: string): TokenRef => `var(--${token})`;
+
+/**
+ * Surface / fill roles → background-color utilities (`bg-<role>`).
+ *
+ * | role              | utility            | canonical token   | rationale                                   |
+ * | ----------------- | ------------------ | ----------------- | ------------------------------------------- |
+ * | bg                | bg-bg              | --background      | the page background                          |
+ * | fill              | bg-fill            | --card            | default raised surface (cards/sheets)        |
+ * | fill-secondary    | bg-fill-secondary  | --muted           | muted/secondary fill                         |
+ * | fill-hover        | bg-fill-hover      | --accent          | hover state of a secondary fill              |
+ * | fill-brand        | bg-fill-brand      | --primary         | brand-colored fill                           |
+ * | fill-brand-hover  | bg-fill-brand-hover| --ring            | hover of brand fill (ring == primary hue)    |
+ * | fill-inverse      | bg-fill-inverse    | --foreground      | inverse (high-contrast) fill                 |
+ * | fill-inverse-hover| bg-fill-inverse-hov| --muted-foreground| hover of inverse fill                        |
+ * | fill-placeholder  | bg-fill-placeholder| --muted           | disabled/placeholder surface                 |
+ */
+export const FILL_ROLES = {
+  bg: ref('background'),
+  fill: ref('card'),
+  'fill-secondary': ref('muted'),
+  'fill-hover': ref('accent'),
+  'fill-brand': ref('primary'),
+  'fill-brand-hover': ref('ring'),
+  'fill-inverse': ref('foreground'),
+  'fill-inverse-hover': ref('muted-foreground'),
+  'fill-placeholder': ref('muted'),
+} as const;
+
+/**
+ * Text roles → text-color utilities (`text-<role>`).
+ *
+ * Tailwind prefixes text-color utilities with `text-`, so a role literally
+ * named `text` becomes the utility `text-text`, `text-secondary` → the utility
+ * `text-text-secondary`, etc. (matches the namespaced spec).
+ *
+ * | role             | utility               | canonical token       | rationale                          |
+ * | ---------------- | --------------------- | --------------------- | ---------------------------------- |
+ * | text             | text-text             | --foreground          | primary text                        |
+ * | text-secondary   | text-text-secondary   | --muted-foreground    | secondary text                      |
+ * | text-tertiary    | text-text-tertiary    | --muted-foreground    | tertiary/least-emphasis text        |
+ * | text-inverse     | text-text-inverse     | --primary-foreground  | text on a brand fill                |
+ * | text-fixed-light | text-text-fixed-light | --primary-foreground  | always-light text (on brand)        |
+ * | text-placeholder | text-text-placeholder | --muted-foreground    | placeholder/input hint              |
+ */
+export const TEXT_ROLES = {
+  text: ref('foreground'),
+  'text-secondary': ref('muted-foreground'),
+  'text-tertiary': ref('muted-foreground'),
+  'text-inverse': ref('primary-foreground'),
+  'text-fixed-light': ref('primary-foreground'),
+  'text-placeholder': ref('muted-foreground'),
+} as const;
+
+/**
+ * Border roles → border-color utilities (`border-<role>`).
+ *
+ * | role               | utility                 | canonical token | rationale                                  |
+ * | ------------------ | ----------------------- | --------------- | ------------------------------------------ |
+ * | border             | border-border           | --border        | default border                              |
+ * | border-image       | border-border-image     | --border        | hairline border color (0.5px width helper)  |
+ * | border-secondary   | border-border-secondary | --input         | secondary/softer border                     |
+ * | border-input       | border-border-input     | --input         | input field border                          |
+ * | border-input-active| border-border-input-active | --ring       | focused input border (== primary)           |
+ *
+ * NOTE: the hairline 0.5px WIDTH for `border-image` is shipped as a separate
+ * `borderWidth` scale entry (`border-hairline`) in the preset; the color role
+ * above only provides the matching color. Consumers compose them:
+ * `border-hairline border-border-image`.
+ */
+export const BORDER_ROLES = {
+  border: ref('border'),
+  'border-image': ref('border'),
+  'border-secondary': ref('input'),
+  'border-input': ref('input'),
+  'border-input-active': ref('ring'),
+} as const;
+
+export type FillRole = keyof typeof FILL_ROLES;
+export type TextRole = keyof typeof TEXT_ROLES;
+export type BorderRole = keyof typeof BORDER_ROLES;

package/src/design-tokens/index.ts

@@ -0,0 +1,45 @@
+/**
+ * `@oxyhq/bloom/design-tokens` — the centralized, semantic design-token
+ * vocabulary for the Oxy Unified Design Language.
+ *
+ * Exposes:
+ *   - `bloomTailwindPreset` — the Tailwind/NativeWind preset (web + native) that
+ *     adds the semantic utility classes (`bg-fill`, `text-text-tertiary`,
+ *     `p-space-8`, `rounded-radius-20`, `text-body`, `font-body`, `shadow-s`).
+ *   - `bloomThemeCss` / `bloomThemeBlock` — the Tailwind v4 `@theme` equivalent
+ *     for CSS-configured web apps.
+ *   - The raw token maps (`FILL_ROLES`, `TEXT_ROLES`, `BORDER_ROLES`, `SPACING`,
+ *     `RADIUS`, `TYPOGRAPHY`, `SHADOW_BOX`) for direct programmatic use.
+ *   - `bloomShadowStyle` — platform-correct shadow style object (web box-shadow /
+ *     native elevation) so a consumer writes one call for both platforms.
+ *
+ * Additive and non-breaking: every export here is NEW. It does not change any
+ * existing Bloom token, theme value, or utility class.
+ */
+
+export { bloomTailwindPreset } from './tailwind-preset';
+export type {
+  TailwindPreset,
+  TailwindPresetThemeExtend,
+} from './tailwind-preset';
+
+export { bloomThemeCss, bloomThemeBlock } from './theme-css';
+
+export {
+  FILL_ROLES,
+  TEXT_ROLES,
+  BORDER_ROLES,
+} from './color-roles';
+export type { FillRole, TextRole, BorderRole } from './color-roles';
+
+export {
+  SPACING,
+  RADIUS,
+  BORDER_WIDTH,
+  TYPOGRAPHY,
+  FONT_FAMILY_VARS,
+} from './scales';
+export type { TypeRole, TypeRoleName } from './scales';
+
+export { SHADOW_BOX, bloomShadowStyle } from './shadows';
+export type { ShadowRole } from './shadows';

package/src/design-tokens/scales.ts

@@ -0,0 +1,134 @@
+/**
+ * Numeric design-token scales for the Oxy Unified Design Language.
+ *
+ * These are platform-agnostic plain numbers / CSS strings consumed by the Bloom
+ * Tailwind preset (`tailwind-preset.ts`). The SAME keys produce the SAME utility
+ * class names on Tailwind (web) and NativeWind (native):
+ *   - spacing  → `p-space-8`, `gap-space-20`, `px-screen-margin`, `m-space-16`
+ *   - radius   → `rounded-radius-20`
+ *   - type     → `font-body` (family/weight) + `text-body` (size/lineHeight)
+ *   - shadow   → `shadow-s`, `shadow-m`
+ *
+ * ADDITIVE: every key is namespaced (`space-*`, `radius-*`, the typography role
+ * names, `shadow-s/m`) and does not collide with Tailwind's built-in numeric
+ * scale (`p-4`, `rounded-lg`, `text-sm`) — those keep working unchanged.
+ */
+
+/* -------------------------------------------------------------------------- */
+/*  Spacing                                                                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Spacing scale (px). Consumed via every Tailwind spacing utility:
+ * `p-space-8`, `px-space-16`, `gap-space-20`, `m-space-24`, `py-space-12`, …
+ *
+ * `screen-margin` is the standard page gutter (left/right inset). Default 20px —
+ * matches Bloom's existing `space.xl` and the `Dialog` default `contentPadding`.
+ */
+export const SPACING = {
+  'space-2': 2,
+  'space-4': 4,
+  'space-8': 8,
+  'space-12': 12,
+  'space-16': 16,
+  'space-20': 20,
+  'space-24': 24,
+  'space-32': 32,
+  'screen-margin': 20,
+} as const;
+
+/* -------------------------------------------------------------------------- */
+/*  Radius                                                                     */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Corner-radius scale (px). Consumed via `rounded-radius-*`:
+ * `rounded-radius-8`, `rounded-radius-12`, `rounded-radius-20`,
+ * `rounded-radius-28`, `rounded-radius-max` (pill / circle).
+ */
+export const RADIUS = {
+  'radius-8': 8,
+  'radius-12': 12,
+  'radius-20': 20,
+  'radius-28': 28,
+  'radius-max': 9999,
+} as const;
+
+/* -------------------------------------------------------------------------- */
+/*  Border width (hairline)                                                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Border-width helpers. `border-hairline` is the 0.5px hairline that pairs with
+ * the `border-border-image` color role. (Tailwind's default `border` = 1px
+ * stays untouched.)
+ */
+export const BORDER_WIDTH = {
+  hairline: 0.5,
+} as const;
+
+/* -------------------------------------------------------------------------- */
+/*  Typography                                                                 */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * One typography role. `size`/`lineHeight` are px; `weight` is a CSS font-weight
+ * string; `family` selects the Bloom font CSS var (`sans` = body/UI,
+ * `display` = headings/serif).
+ *
+ * The Tailwind preset splits each role into TWO utilities so a consumer can
+ * apply the size/leading and the family/weight independently or together:
+ *   - `text-<role>`  → `fontSize` + `lineHeight`   (via theme.fontSize)
+ *   - `font-<role>`  → `fontFamily` + `fontWeight` (via theme.fontFamily, which
+ *                       maps a key to a [family, { fontWeight }] tuple)
+ */
+export interface TypeRole {
+  /** Font size in px. */
+  size: number;
+  /** Line height in px. */
+  lineHeight: number;
+  /** CSS font-weight (string for Tailwind/RN parity). */
+  weight: '400' | '500' | '600' | '700';
+  /** Which Bloom font family CSS var to use. */
+  family: 'sans' | 'display';
+}
+
+/**
+ * The coherent Oxy type scale. Sizes climb 11 → 28; line-heights use a ~1.3–1.5
+ * leading for body roles and tighter leading for large titles.
+ *
+ * | role            | size/line | weight | family  | usage                          |
+ * | --------------- | --------- | ------ | ------- | ------------------------------ |
+ * | caption         | 11 / 14   | 400    | sans    | timestamps, meta, fine print   |
+ * | bodySmall       | 13 / 18   | 400    | sans    | secondary body, captions       |
+ * | bodyTitleSmall  | 13 / 18   | 600    | sans    | small emphasized labels        |
+ * | body            | 15 / 22   | 400    | sans    | default body text              |
+ * | subtitle        | 17 / 24   | 500    | sans    | list subtitles, lead-ins       |
+ * | sectionTitle    | 20 / 26   | 600    | sans    | section headers                |
+ * | headerBold      | 28 / 34   | 700    | display | screen / page titles           |
+ * | buttonLarge     | 17 / 22   | 600    | sans    | primary button label           |
+ */
+export const TYPOGRAPHY = {
+  caption: { size: 11, lineHeight: 14, weight: '400', family: 'sans' },
+  bodySmall: { size: 13, lineHeight: 18, weight: '400', family: 'sans' },
+  bodyTitleSmall: { size: 13, lineHeight: 18, weight: '600', family: 'sans' },
+  body: { size: 15, lineHeight: 22, weight: '400', family: 'sans' },
+  subtitle: { size: 17, lineHeight: 24, weight: '500', family: 'sans' },
+  sectionTitle: { size: 20, lineHeight: 26, weight: '600', family: 'sans' },
+  headerBold: { size: 28, lineHeight: 34, weight: '700', family: 'display' },
+  buttonLarge: { size: 17, lineHeight: 22, weight: '600', family: 'sans' },
+} as const satisfies Record<string, TypeRole>;
+
+export type TypeRoleName = keyof typeof TYPOGRAPHY;
+
+/**
+ * Bloom font-family CSS-var stacks, keyed by the `family` field above. Web reads
+ * `var(--bloom-font-*)` (set by `applyFontFaces`); the preset falls back to the
+ * literal stack so utilities still resolve before the vars are injected and on
+ * native (where NativeWind passes the family string straight through).
+ */
+export const FONT_FAMILY_VARS = {
+  sans: 'var(--bloom-font-sans)',
+  display: 'var(--bloom-font-display)',
+  mono: 'var(--bloom-font-mono)',
+} as const;

package/src/design-tokens/shadows.native.ts

@@ -0,0 +1,44 @@
+import { type ViewStyle } from 'react-native';
+
+/**
+ * NATIVE variant of the shadow tokens (see `shadows.ts` for the rationale and
+ * the web `box-shadow` path). Metro selects this file on iOS/Android.
+ *
+ * The `SHADOW_BOX` map is kept identical to the web file so any code that reads
+ * the raw string (e.g. to feed a NativeWind `boxShadow` utility on a host that
+ * supports it) stays in lockstep; the canonical native styling path is
+ * `bloomShadowStyle`, which returns RN elevation + shadow props tuned to match
+ * the web `shadow-s` / `shadow-m` visual weight.
+ */
+
+export type ShadowRole = 's' | 'm';
+
+export const SHADOW_BOX: Record<ShadowRole, string> = {
+  s: '0 1px 2px rgb(0 0 0 / 0.06), 0 1px 3px rgb(0 0 0 / 0.10)',
+  m: '0 4px 12px rgb(0 0 0 / 0.08), 0 2px 6px rgb(0 0 0 / 0.12)',
+};
+
+const NATIVE_SHADOWS: Record<ShadowRole, ViewStyle> = {
+  s: {
+    shadowColor: '#000000',
+    shadowOffset: { width: 0, height: 1 },
+    shadowOpacity: 0.12,
+    shadowRadius: 3,
+    elevation: 2,
+  },
+  m: {
+    shadowColor: '#000000',
+    shadowOffset: { width: 0, height: 4 },
+    shadowOpacity: 0.16,
+    shadowRadius: 12,
+    elevation: 6,
+  },
+};
+
+/**
+ * RN shadow/elevation style matching the web `shadow-<role>` weight. Apply to a
+ * React Native `View`/surface: `style={bloomShadowStyle('m')}`.
+ */
+export function bloomShadowStyle(role: ShadowRole): ViewStyle {
+  return NATIVE_SHADOWS[role];
+}

package/src/design-tokens/shadows.ts

@@ -0,0 +1,42 @@
+import { type ViewStyle } from 'react-native';
+
+/**
+ * Elevation / shadow tokens for the Oxy Unified Design Language.
+ *
+ * Two roles: `shadow-s` (subtle raise — cards, chips) and `shadow-m` (overlays —
+ * menus, popovers, dialogs). Consumers write ONE class (`shadow-s` / `shadow-m`)
+ * and Bloom owns the platform split:
+ *   - Web: the Bloom Tailwind preset registers `boxShadow.s` / `boxShadow.m`
+ *     (the `SHADOW_BOX` strings below) → `shadow-s` / `shadow-m` utilities.
+ *   - Native: NativeWind cannot translate a multi-layer web `box-shadow` to RN
+ *     elevation reliably, so apps that need the shadow on a React Native surface
+ *     apply the matching style object from `bloomShadowStyle('s' | 'm')` (this
+ *     module is platform-forked: `.native.ts` returns RN `shadow*`/`elevation`).
+ *
+ * This default file is the WEB / consumer-tsc variant. Metro selects the sibling
+ * `shadows.native.ts` on iOS/Android. Web bundlers and a consumer's `tsc` see
+ * this file (the `box-shadow` CSS string path), matching Bloom's existing
+ * `.native`/`.web` split convention.
+ */
+
+export type ShadowRole = 's' | 'm';
+
+/**
+ * Web `box-shadow` strings. Subtle, brand-neutral elevation that reads on both
+ * light and dark surfaces. Registered by the Tailwind preset as `boxShadow.s/m`.
+ */
+export const SHADOW_BOX: Record<ShadowRole, string> = {
+  s: '0 1px 2px rgb(0 0 0 / 0.06), 0 1px 3px rgb(0 0 0 / 0.10)',
+  m: '0 4px 12px rgb(0 0 0 / 0.08), 0 2px 6px rgb(0 0 0 / 0.12)',
+};
+
+/**
+ * Return the platform-appropriate shadow style for a role.
+ *
+ * On WEB this returns a `{ boxShadow }` style object (so it can also be applied
+ * inline without Tailwind). The `.native.ts` fork returns RN
+ * `shadowColor/shadowOffset/shadowOpacity/shadowRadius/elevation`.
+ */
+export function bloomShadowStyle(role: ShadowRole): ViewStyle {
+  return { boxShadow: SHADOW_BOX[role] } as ViewStyle;
+}

package/src/design-tokens/tailwind-preset.ts

@@ -0,0 +1,139 @@
+/**
+ * The Bloom Tailwind / NativeWind preset — the SINGLE opt-in that gives every
+ * Oxy app the same semantic design-token utility classes.
+ *
+ * Consumers add it to their Tailwind config:
+ *
+ *   // tailwind.config.js  (web Tailwind v3/v4 AND native NativeWind)
+ *   const { bloomTailwindPreset } = require('@oxyhq/bloom/tailwind-preset');
+ *   module.exports = {
+ *     presets: [bloomTailwindPreset],
+ *     content: [ ...existing globs ],
+ *     theme: { extend: { ...existing app overrides } },
+ *   };
+ *
+ * The preset only EXTENDS `theme` (everything lives under `theme.extend`), so it
+ * is purely additive: existing Tailwind built-ins (`p-4`, `rounded-lg`,
+ * `text-sm`) and the app's own `var(--x)`-backed color utilities keep working.
+ *
+ * Cross-platform: NativeWind reads the same `tailwind.config.js`, so the SAME
+ * class names (`bg-fill`, `text-text-tertiary`, `p-space-8`, `rounded-radius-20`,
+ * `text-body`, `font-body`, `shadow-s`) resolve on web (Tailwind → CSS) and
+ * native (NativeWind → react-native-css). Color roles are `var(--x)` references
+ * that Bloom's `BloomThemeProvider` populates at runtime on both platforms.
+ *
+ * Type: returned as a `TailwindPreset` (a structural subset of Tailwind's
+ * `Config`) so Bloom does not need to depend on `tailwindcss` types.
+ */
+
+import { BORDER_ROLES, FILL_ROLES, TEXT_ROLES } from './color-roles';
+import {
+  BORDER_WIDTH,
+  FONT_FAMILY_VARS,
+  RADIUS,
+  SPACING,
+  TYPOGRAPHY,
+  type TypeRoleName,
+} from './scales';
+import { SHADOW_BOX } from './shadows';
+
+/** A Tailwind `fontSize` value: `[size, { lineHeight }]`. */
+type FontSizeValue = [string, { lineHeight: string }];
+/** A Tailwind `fontFamily` value: `[family, { fontWeight }]`. */
+type FontFamilyValue = [string, { fontWeight: string }];
+
+export interface TailwindPresetThemeExtend {
+  colors: Record<string, string>;
+  backgroundColor: Record<string, string>;
+  textColor: Record<string, string>;
+  borderColor: Record<string, string>;
+  spacing: Record<string, string>;
+  borderRadius: Record<string, string>;
+  borderWidth: Record<string, string>;
+  fontSize: Record<string, FontSizeValue>;
+  fontFamily: Record<string, FontFamilyValue>;
+  boxShadow: Record<string, string>;
+}
+
+export interface TailwindPreset {
+  theme: { extend: TailwindPresetThemeExtend };
+}
+
+const px = (n: number): string => `${n}px`;
+
+/** `{ 'space-8': 8 }` → `{ 'space-8': '8px' }`. */
+function toPxMap(scale: Record<string, number>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(scale)) {
+    // 9999 (radius-max) and large values are still valid px; pill shapes clamp.
+    out[key] = px(value);
+  }
+  return out;
+}
+
+/** Build the `fontSize` extension: `text-<role>` → `[size, { lineHeight }]`. */
+function buildFontSize(): Record<string, FontSizeValue> {
+  const out: Record<string, FontSizeValue> = {};
+  for (const name of Object.keys(TYPOGRAPHY) as TypeRoleName[]) {
+    const role = TYPOGRAPHY[name];
+    out[name] = [px(role.size), { lineHeight: px(role.lineHeight) }];
+  }
+  return out;
+}
+
+/** Build the `fontFamily` extension: `font-<role>` → `[family, { fontWeight }]`. */
+function buildFontFamily(): Record<string, FontFamilyValue> {
+  const out: Record<string, FontFamilyValue> = {};
+  for (const name of Object.keys(TYPOGRAPHY) as TypeRoleName[]) {
+    const role = TYPOGRAPHY[name];
+    out[name] = [FONT_FAMILY_VARS[role.family], { fontWeight: role.weight }];
+  }
+  // Also expose the raw Bloom families directly: `font-bloom-sans`, etc.
+  out['bloom-sans'] = [FONT_FAMILY_VARS.sans, { fontWeight: '400' }];
+  out['bloom-display'] = [FONT_FAMILY_VARS.display, { fontWeight: '700' }];
+  out['bloom-mono'] = [FONT_FAMILY_VARS.mono, { fontWeight: '400' }];
+  return out;
+}
+
+const SPACING_PX = toPxMap(SPACING);
+const RADIUS_PX = toPxMap({ ...RADIUS });
+const BORDER_WIDTH_PX = toPxMap(BORDER_WIDTH);
+
+/**
+ * Color roles are exposed via `colors` (so they reach `bg-*`, `text-*`,
+ * `border-*`, `ring-*`, `divide-*`, `fill-*` …) AND via the dedicated
+ * `backgroundColor` / `textColor` / `borderColor` maps (so the namespaced roles
+ * land on exactly the intended utility families even where the role name would
+ * otherwise be ambiguous). All values are `var(--canonical)` references.
+ */
+const COLOR_ROLES: Record<string, string> = {
+  ...FILL_ROLES,
+  ...TEXT_ROLES,
+  ...BORDER_ROLES,
+};
+
+/**
+ * The Bloom Tailwind/NativeWind preset. Frozen so accidental mutation by a
+ * consumer's config merge cannot corrupt the shared vocabulary.
+ */
+export const bloomTailwindPreset: TailwindPreset = Object.freeze({
+  theme: {
+    extend: {
+      // Generic color bucket — feeds every color utility family.
+      colors: { ...COLOR_ROLES },
+      // Targeted buckets so the namespaced roles resolve on the right utility.
+      backgroundColor: { ...FILL_ROLES },
+      textColor: { ...TEXT_ROLES },
+      borderColor: { ...BORDER_ROLES },
+
+      spacing: SPACING_PX,
+      borderRadius: RADIUS_PX,
+      borderWidth: BORDER_WIDTH_PX,
+
+      fontSize: buildFontSize(),
+      fontFamily: buildFontFamily(),
+
+      boxShadow: { s: SHADOW_BOX.s, m: SHADOW_BOX.m },
+    },
+  },
+});

package/src/design-tokens/theme-css.ts

@@ -0,0 +1,99 @@
+/**
+ * Tailwind v4 `@theme` block generator for the Oxy Unified Design Language.
+ *
+ * Tailwind v4 web apps (auth, console, website) configure their design tokens in
+ * CSS via `@theme { --color-X: var(--X); … }` rather than a JS preset. This
+ * module produces the exact `@theme` body that mirrors `bloomTailwindPreset`, so
+ * a v4 app gets the SAME semantic utilities (`bg-fill`, `text-text-tertiary`,
+ * `p-space-8`, `rounded-radius-20`, `text-body`, `font-body`, `shadow-s`) as the
+ * NativeWind/Tailwind-v3 apps that consume the JS preset.
+ *
+ * Each color role is emitted as a `--color-<role>: var(--canonical)` alias.
+ * Per Bloom's web CSS-var contract, the canonical `--x` token already resolves
+ * to a full `rgb(...)` color at runtime, so the alias is a direct `var(--x)`
+ * reference — NEVER `hsl(var(--x))`.
+ *
+ * Usage (web Tailwind v4, in the app's global stylesheet):
+ *
+ *   import { bloomThemeCss } from '@oxyhq/bloom/design-tokens';
+ *   // build-time: write `@theme { ${bloomThemeCss()} }` into global.css, OR
+ *   // paste the generated block once (see docs/design-tokens.md).
+ *
+ * A consumer that prefers a static stylesheet can copy the output of
+ * `bloomThemeCss()` directly into their `@theme { … }` — the values are stable.
+ */
+
+import { BORDER_ROLES, FILL_ROLES, TEXT_ROLES } from './color-roles';
+import {
+  BORDER_WIDTH,
+  FONT_FAMILY_VARS,
+  RADIUS,
+  SPACING,
+  TYPOGRAPHY,
+  type TypeRoleName,
+} from './scales';
+import { SHADOW_BOX } from './shadows';
+
+/**
+ * Produce the BODY of a Tailwind v4 `@theme` block (no surrounding braces) that
+ * registers the full Bloom semantic vocabulary.
+ *
+ * - Colors → `--color-<role>: var(--canonical);`
+ * - Spacing → `--spacing-<key>: <px>;`
+ * - Radius  → `--radius-<key>: <px>;`
+ * - Type    → `--text-<role>: <size>; --text-<role>--line-height: <lh>;`
+ *             `--font-<role>: var(--bloom-font-*);` (+ weight via utility doc)
+ * - Shadow  → `--shadow-<s|m>: <box-shadow>;`
+ */
+export function bloomThemeCss(): string {
+  const lines: string[] = [];
+
+  // Color roles.
+  for (const [role, value] of Object.entries({
+    ...FILL_ROLES,
+    ...TEXT_ROLES,
+    ...BORDER_ROLES,
+  })) {
+    lines.push(`  --color-${role}: ${value};`);
+  }
+
+  // Spacing.
+  for (const [key, value] of Object.entries(SPACING)) {
+    lines.push(`  --spacing-${key}: ${value}px;`);
+  }
+
+  // Radius.
+  for (const [key, value] of Object.entries(RADIUS)) {
+    lines.push(`  --radius-${key}: ${value}px;`);
+  }
+
+  // Hairline border width.
+  for (const [key, value] of Object.entries(BORDER_WIDTH)) {
+    lines.push(`  --border-width-${key}: ${value}px;`);
+  }
+
+  // Typography: size + line-height + family per role.
+  for (const name of Object.keys(TYPOGRAPHY) as TypeRoleName[]) {
+    const role = TYPOGRAPHY[name];
+    lines.push(`  --text-${name}: ${role.size}px;`);
+    lines.push(`  --text-${name}--line-height: ${role.lineHeight}px;`);
+    lines.push(`  --text-${name}--font-weight: ${role.weight};`);
+    lines.push(`  --font-${name}: ${FONT_FAMILY_VARS[role.family]};`);
+  }
+
+  // Bloom raw families.
+  lines.push(`  --font-bloom-sans: ${FONT_FAMILY_VARS.sans};`);
+  lines.push(`  --font-bloom-display: ${FONT_FAMILY_VARS.display};`);
+  lines.push(`  --font-bloom-mono: ${FONT_FAMILY_VARS.mono};`);
+
+  // Shadows.
+  lines.push(`  --shadow-s: ${SHADOW_BOX.s};`);
+  lines.push(`  --shadow-m: ${SHADOW_BOX.m};`);
+
+  return lines.join('\n');
+}
+
+/** The full `@theme { … }` block, ready to inject into a v4 stylesheet. */
+export function bloomThemeBlock(): string {
+  return `@theme {\n${bloomThemeCss()}\n}`;
+}

package/src/index.ts

@@ -7,6 +7,35 @@ export type { ViewStyleProp, TextStyleProp } from './styles';
 export * as tokens from './styles/tokens';
 export { web, native, ios, android, platform, select } from './styles/platform';
 
+// Design tokens (Oxy Unified Design Language) — semantic Tailwind/NativeWind
+// vocabulary. The Tailwind preset is consumed from `@oxyhq/bloom/tailwind-preset`
+// in a config file; these named exports cover programmatic/runtime use.
+export {
+  bloomTailwindPreset,
+  bloomThemeCss,
+  bloomThemeBlock,
+  FILL_ROLES,
+  TEXT_ROLES,
+  BORDER_ROLES,
+  SPACING,
+  RADIUS,
+  BORDER_WIDTH,
+  TYPOGRAPHY,
+  FONT_FAMILY_VARS,
+  SHADOW_BOX,
+  bloomShadowStyle,
+} from './design-tokens';
+export type {
+  TailwindPreset,
+  TailwindPresetThemeExtend,
+  FillRole,
+  TextRole,
+  BorderRole,
+  TypeRole,
+  TypeRoleName,
+  ShadowRole,
+} from './design-tokens';
+
 // Hooks
 export { useInteractionState } from './hooks/useInteractionState';
 export { useDelayedLoading } from './hooks/useDelayedLoading';
@@ -69,6 +98,10 @@ export * as Skeleton from './skeleton';
 export * as Grid from './grid';
 export { Fill } from './fill';
 export { IconCircle } from './icon-circle';
+export { ConnectionDots } from './connection-dots';
+export type { ConnectionDotsProps } from './connection-dots';
+export { BenefitRow, BenefitList } from './benefit-list';
+export type { BenefitRowProps, BenefitListProps } from './benefit-list';
 
 // Form components
 export * from './text-field';