@cdx-ui/components 0.0.1-beta.7 → 0.0.1-beta.70

package/src/hooks/useForgeBottomTabScreenOptions.ts

@@ -0,0 +1,245 @@
+/**
+ * useForgeBottomTabScreenOptions
+ *
+ * Returns a `screenOptions` object for **React Navigation bottom tab navigators**
+ * (`@react-navigation/bottom-tabs` v7+), populated with CDX UI design-system
+ * token values.
+ *
+ * CDX UI does not import `@react-navigation` — the consumer passes the returned
+ * object to their own navigator. This keeps the dependency out of
+ * `@cdx-ui/components` and works with any React Navigation tab variant:
+ * `createNativeBottomTabNavigator` (iOS/Android) or `createBottomTabNavigator`
+ * (web/JS).
+ *
+ * **Not compatible with:**
+ * - Expo Router `<NativeTabs>` — uses different prop names
+ * - React Router or DOM tab components — these are not React Navigation
+ *
+ * ## Basic usage
+ *
+ * ```tsx
+ * import { useForgeBottomTabScreenOptions } from '@cdx-ui/components';
+ * import { createNativeBottomTabNavigator } from '@react-navigation/bottom-tabs/unstable';
+ *
+ * const Tab = createNativeBottomTabNavigator<AppTabs>();
+ *
+ * function AppTabs() {
+ *   const screenOptions = useForgeBottomTabScreenOptions();
+ *   return (
+ *     <Tab.Navigator screenOptions={screenOptions}>
+ *       <Tab.Screen name="Home" component={HomeScreen} />
+ *     </Tab.Navigator>
+ *   );
+ * }
+ * ```
+ *
+ * ## Overriding individual tokens
+ *
+ * Spread the returned object and override only the keys you need.
+ * Nested style objects (`tabBarLabelStyle`, `tabBarStyle`, `tabBarBadgeStyle`)
+ * must be spread individually to preserve unrelated DS defaults:
+ *
+ * ```tsx
+ * const dsOptions = useForgeBottomTabScreenOptions();
+ * const screenOptions = {
+ *   ...dsOptions,
+ *   tabBarActiveTintColor: '#custom',
+ *   tabBarLabelStyle: { ...dsOptions.tabBarLabelStyle, fontFamily: 'MyFont' },
+ * };
+ * ```
+ *
+ * ## Token variable names
+ *
+ * | screenOption                       | CSS variable                       |
+ * | ---------------------------------- | ---------------------------------- |
+ * | tabBarActiveTintColor              | --color-content-action             |
+ * | tabBarInactiveTintColor            | --color-content-secondary          |
+ * | tabBarStyle.backgroundColor        | --color-surface-primary            |
+ * | tabBarLabelStyle.fontFamily        | --font-body                        |
+ * | tabBarLabelStyle.fontSize          | --text-xs (via `text-xs` class)    |
+ * | tabBarLabelStyle.fontWeight        | --font-weight-medium               |
+ * | tabBarBadgeStyle.backgroundColor   | --color-surface-danger-strong      |
+ *
+ * ## Platform notes
+ *
+ * - `tabBarInactiveTintColor` has no effect on iOS — inactive items always use
+ *   system grey.
+ * - `tabBarStyle.backgroundColor` is ignored on iOS 26+ (liquid glass takes
+ *   over). It is honoured on iOS ≤18 and all Android versions.
+ * - The hook resolves CSS variables via Uniwind's `useCSSVariable`. If the
+ *   Uniwind runtime is not set up (e.g. in a plain Jest test without a CSS
+ *   context), each variable resolves to `undefined` and the hardcoded fallback
+ *   is used instead — fallbacks intentionally match the CDX UI light-theme
+ *   values.
+ * - `tabBarLabelStyle.fontSize` is resolved via Uniwind's
+ *   `useResolveClassNames('text-xs')` rather than reading the rem-valued
+ *   `--text-xs` variable directly. React Navigation v7 requires a numeric
+ *   `fontSize`, and letting Uniwind resolve the class means the rem→px
+ *   conversion uses the consumer's configured rem base (default 16px,
+ *   overridable via the `polyfills.rem` Metro option) instead of a constant
+ *   hardcoded here.
+ */
+import type { TextStyle } from 'react-native';
+import { useCSSVariable, useResolveClassNames } from 'uniwind';
+import type { BottomTabNavigationOptions } from '@react-navigation/bottom-tabs';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * The `screenOptions` shape returned by `useForgeBottomTabScreenOptions`.
+ *
+ * These are concrete types (not the broad `StyleProp<…>` React Navigation
+ * uses internally) so consumers get precise IDE completion. The compile-time
+ * drift guard below ensures this type stays assignable to
+ * `BottomTabNavigationOptions` — the TypeScript compiler will error if CDX UI
+ * adds a key or value that React Navigation no longer accepts.
+ *
+ * Pass directly as `screenOptions` on a `createNativeBottomTabNavigator` or
+ * `createBottomTabNavigator` navigator, or spread and override individual keys.
+ */
+export interface ForgeReactNavigationBottomTabScreenOptions {
+  tabBarActiveTintColor: string;
+  tabBarInactiveTintColor: string;
+  tabBarStyle: { backgroundColor: string };
+  tabBarLabelStyle: {
+    fontFamily: string;
+    /** Pixel size — React Navigation requires a number for tab label fontSize. */
+    fontSize: number;
+    fontWeight: TextStyle['fontWeight'];
+  };
+  tabBarBadgeStyle: { backgroundColor: string };
+}
+
+/**
+ * Compile-time drift guard.
+ *
+ * `ForgeReactNavigationBottomTabScreenOptions` must be assignable to
+ * `BottomTabNavigationOptions`. TypeScript checks this assignment at build
+ * time — if React Navigation removes or incompatibly narrows one of our keys,
+ * this line becomes a type error before it reaches consumers.
+ *
+ * The `null as unknown as ...` cast keeps the runtime value `null` so tree-
+ * shakers eliminate the variable from the final bundle entirely.
+ */
+
+const _rnDriftGuard: BottomTabNavigationOptions =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  null as any as ForgeReactNavigationBottomTabScreenOptions;
+
+// ── Fallbacks ────────────────────────────────────────────────────────────────
+//
+// Resolved light-theme values for each token. Used when useCSSVariable returns
+// undefined (no Uniwind CSS context in scope, e.g. Jest).
+
+const FALLBACKS = {
+  activeTintColor: '#346099', // --color-brand-700 (--color-content-action)
+  inactiveTintColor: '#4a4c4f', // --color-base-800  (--color-content-secondary)
+  fontFamily: 'Inter', // --font-sans           (--font-body)
+  fontSize: 12, // px                    (--text-xs)
+  fontWeight: '500' as TextStyle['fontWeight'], // (--font-weight-medium)
+  backgroundColor: '#ffffff', // --color-white         (--color-surface-primary)
+  badgeBackgroundColor: '#c10007', // --color-red-700       (--color-surface-danger-strong)
+} as const;
+
+/**
+ * Coerces a Uniwind-resolved `fontSize` to a finite pixel number, falling
+ * back when the style could not be resolved (e.g. no Uniwind runtime in Jest).
+ *
+ * `useResolveClassNames('text-xs')` performs the rem→px conversion using
+ * Uniwind's configured rem base, so the value is already numeric on native.
+ * React Native Web may surface string values; unit-less and `px` strings are
+ * accepted, but anything else (`rem`, `em`, `%`) falls back rather than
+ * guessing a rem base here.
+ */
+function toPx(value: string | number | undefined, fallbackPx: number): number {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : fallbackPx;
+  }
+  if (typeof value !== 'string') return fallbackPx;
+  const trimmed = value.trim();
+  if (!/^-?\d*\.?\d+(px)?$/.test(trimmed)) return fallbackPx;
+  return parseFloat(trimmed);
+}
+
+/**
+ * Coerces a Uniwind `useCSSVariable` fontWeight value to a string.
+ *
+ * `--font-weight-*` variables are emitted as unit-less numbers (e.g. `500`),
+ * and `useCSSVariable` may return them as numbers. React Native's `TextStyle`
+ * accepts numeric fontWeight, but react-native-screens' native bottom tabs
+ * declare the corresponding host prop (`tabBarItemTitleFontWeight`) as a
+ * String — passing a number crashes Android Fabric with
+ * "java.lang.Double cannot be cast to java.lang.String".
+ */
+function toFontWeight(
+  value: string | number | undefined,
+  fallback: TextStyle['fontWeight'],
+): TextStyle['fontWeight'] {
+  if (value === undefined) return fallback;
+  return String(value) as TextStyle['fontWeight'];
+}
+
+// ── Hook ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Returns a `screenOptions` object for **React Navigation bottom tab
+ * navigators** (`@react-navigation/bottom-tabs` v7+), populated with CDX UI
+ * design-system token values.
+ *
+ * Must be called inside a React component or custom hook (React hook rules
+ * apply).
+ */
+/**
+ * Deep-merges consumer overrides into a base `ForgeReactNavigationBottomTabScreenOptions`
+ * object. Nested style objects (`tabBarLabelStyle`, `tabBarStyle`,
+ * `tabBarBadgeStyle`) are merged property-by-property so consumers can override
+ * individual style properties without losing unrelated DS defaults.
+ *
+ * Use with `useForgeBottomTabScreenOptions` to apply targeted overrides:
+ *
+ * ```tsx
+ * const dsOptions = useForgeBottomTabScreenOptions();
+ * const screenOptions = mergeForgeBottomTabScreenOptions(dsOptions, {
+ *   tabBarActiveTintColor: '#custom',
+ *   tabBarLabelStyle: { fontFamily: 'MyFont' }, // fontSize + fontWeight preserved
+ * });
+ * ```
+ */
+export function mergeForgeBottomTabScreenOptions(
+  base: ForgeReactNavigationBottomTabScreenOptions,
+  overrides: Partial<ForgeReactNavigationBottomTabScreenOptions>,
+): ForgeReactNavigationBottomTabScreenOptions {
+  return {
+    ...base,
+    ...overrides,
+    tabBarLabelStyle: { ...base.tabBarLabelStyle, ...overrides.tabBarLabelStyle },
+    tabBarStyle: { ...base.tabBarStyle, ...overrides.tabBarStyle },
+    tabBarBadgeStyle: { ...base.tabBarBadgeStyle, ...overrides.tabBarBadgeStyle },
+  };
+}
+
+export function useForgeBottomTabScreenOptions(): ForgeReactNavigationBottomTabScreenOptions {
+  const activeTintColor = useCSSVariable('--color-content-action');
+  const inactiveTintColor = useCSSVariable('--color-content-secondary');
+  const fontFamily = useCSSVariable('--font-body');
+  const labelTextStyle = useResolveClassNames('text-xs');
+  const fontWeight = useCSSVariable('--font-weight-medium');
+  const backgroundColor = useCSSVariable('--color-surface-primary');
+  const badgeBackgroundColor = useCSSVariable('--color-surface-danger-strong');
+
+  return {
+    tabBarActiveTintColor: String(activeTintColor ?? FALLBACKS.activeTintColor),
+    tabBarInactiveTintColor: String(inactiveTintColor ?? FALLBACKS.inactiveTintColor),
+    tabBarStyle: {
+      backgroundColor: String(backgroundColor ?? FALLBACKS.backgroundColor),
+    },
+    tabBarLabelStyle: {
+      fontFamily: String(fontFamily ?? FALLBACKS.fontFamily),
+      fontSize: toPx(labelTextStyle?.fontSize, FALLBACKS.fontSize),
+      fontWeight: toFontWeight(fontWeight, FALLBACKS.fontWeight),
+    },
+    tabBarBadgeStyle: {
+      backgroundColor: String(badgeBackgroundColor ?? FALLBACKS.badgeBackgroundColor),
+    },
+  };
+}

package/src/index.ts

@@ -1,4 +1,6 @@
 /// <reference types="uniwind/types" preserve="true" />
 export * from './components';
+export * from './hooks';
+export * from './navigation';
 export { View, ScrollView, KeyboardAvoidingView } from 'react-native';
 export { SafeAreaView, useSafeAreaInsets } from 'react-native-safe-area-context';

package/src/metro/withCdxMetroConfig.ts

@@ -1,29 +1,4 @@
-import type { MetroConfig } from 'metro-config';
-import { withUniwindConfig } from 'uniwind/metro';
-
-export interface CdxMetroConfigOptions {
-  /** Path to the CSS entry file (e.g., `'./global.css'`). */
-  cssEntryFile: string;
-  /** Path where generated Tailwind class type definitions are written. */
-  generatedTypesFile?: string;
-}
-
-/**
- * Wraps a Metro config with CDX UI's styling-layer configuration.
- *
- * Today this delegates to Uniwind. If the styling layer is swapped (see
- * `docs/research/uniwind-to-nativewind-contingency.md`), only the internals
- * of this function change — consuming Metro configs stay the same.
- *
- * Must be the **outermost** Metro config wrapper (after any other wrappers
- * like `withStorybook`).
- */
-export function withCdxMetroConfig<T extends MetroConfig>(
-  config: T,
-  options: CdxMetroConfigOptions,
-): T {
-  return withUniwindConfig(config, {
-    cssEntryFile: options.cssEntryFile,
-    dtsFile: options.generatedTypesFile,
-  }) as T;
-}
+/** @deprecated Use `withForgeMetroConfig` instead. Will be removed in a future major release. */
+export { withForgeMetroConfig as withCdxMetroConfig } from './withForgeMetroConfig';
+/** @deprecated Use `ForgeMetroConfigOptions` instead. Will be removed in a future major release. */
+export type { ForgeMetroConfigOptions as CdxMetroConfigOptions } from './withForgeMetroConfig';

package/src/metro/withForgeMetroConfig.ts

@@ -0,0 +1,29 @@
+import type { MetroConfig } from 'metro-config';
+import { withUniwindConfig } from 'uniwind/metro';
+
+export interface ForgeMetroConfigOptions {
+  /** Path to the CSS entry file (e.g., `'./global.css'`). */
+  cssEntryFile: string;
+  /** Path where generated Tailwind class type definitions are written. */
+  generatedTypesFile?: string;
+}
+
+/**
+ * Wraps a Metro config with Forge UI's styling-layer configuration.
+ *
+ * Today this delegates to Uniwind. If the styling layer is swapped (see
+ * `docs/research/uniwind-to-nativewind-contingency.md`), only the internals
+ * of this function change — consuming Metro configs stay the same.
+ *
+ * Must be the **outermost** Metro config wrapper (after any other wrappers
+ * like `withStorybook`).
+ */
+export function withForgeMetroConfig<T extends MetroConfig>(
+  config: T,
+  options: ForgeMetroConfigOptions,
+): T {
+  return withUniwindConfig(config, {
+    cssEntryFile: options.cssEntryFile,
+    dtsFile: options.generatedTypesFile,
+  }) as T;
+}

package/src/navigation/forgeTabIcon.native.ts

@@ -0,0 +1,36 @@
+import type { ForgeTabIcon } from '@cdx-ui/icons/tab-icons';
+import type { ForgeNativeBottomTabIcon, ForgeTabBarIcon } from './types';
+
+/**
+ * forgeTabIcon — iOS/Android implementation (see `forgeTabIcon.ts` for the
+ * full contract and usage example).
+ *
+ * Returns a `tabBarIcon` function for `createNativeBottomTabNavigator` that
+ * resolves the descriptor's pre-rasterized template PNGs: outlined at rest,
+ * filled when focused (iOS only — Android tabs use one static icon and
+ * express selection via tint). `tinted: true` makes the native tab bar apply
+ * `tabBarActiveTintColor` / `tabBarInactiveTintColor` at runtime, so theming
+ * and dark mode flow through `useForgeBottomTabScreenOptions` unchanged.
+ */
+export function forgeTabIcon(icon: ForgeTabIcon): ForgeTabBarIcon {
+  const { native } = icon;
+
+  if (!native) {
+    const name = icon.Component.displayName ?? 'icon';
+    throw new Error(
+      `forgeTabIcon: "${name}" has no native tab assets. Use a generated ` +
+        `descriptor from '@cdx-ui/icons/tab-icons' (curated in the icon ` +
+        `package's tab-icons.config.json), or pass a descriptor with your ` +
+        `own template PNGs: { native: { outlined: require(...), filled: ` +
+        `require(...) } } at a 24dp base size with @2x/@3x variants.`,
+    );
+  }
+
+  const resolve = ({ focused }: { focused: boolean }): ForgeNativeBottomTabIcon => ({
+    type: 'image',
+    source: focused ? native.filled : native.outlined,
+    tinted: true,
+  });
+
+  return resolve as ForgeTabBarIcon;
+}

package/src/navigation/forgeTabIcon.ts

@@ -0,0 +1,33 @@
+import { createElement } from 'react';
+import type { ForgeTabIcon } from '@cdx-ui/icons/tab-icons';
+import type { ForgeTabBarIcon } from './types';
+
+/**
+ * forgeTabIcon — web/JS-navigator implementation.
+ *
+ * Maps a {@link ForgeTabIcon} descriptor to a React Navigation `tabBarIcon`
+ * value that renders the same Forge UI icon on every platform:
+ *
+ * - **Web** (`createBottomTabNavigator`): renders the SVG icon component with
+ *   `filled={focused}` and the navigator-supplied `color`/`size` — pair with
+ *   `useForgeBottomTabScreenOptions` so tints come from design tokens.
+ * - **iOS/Android** (`createNativeBottomTabNavigator`): the `.native` module
+ *   of this file returns a tinted template-image descriptor instead.
+ *
+ * ```tsx
+ * import { useForgeBottomTabScreenOptions, forgeTabIcon } from '@cdx-ui/components';
+ * import { HomeTabIcon } from '@cdx-ui/icons/tab-icons';
+ *
+ * <Tab.Screen
+ *   name="Home"
+ *   component={HomeScreen}
+ *   options={{ title: 'Home', tabBarIcon: forgeTabIcon(HomeTabIcon) }}
+ * />
+ * ```
+ */
+export function forgeTabIcon(icon: ForgeTabIcon): ForgeTabBarIcon {
+  const render = ({ focused, color, size }: { focused: boolean; color: string; size: number }) =>
+    createElement(icon.Component, { filled: focused, color, size });
+
+  return render as ForgeTabBarIcon;
+}

package/src/navigation/index.ts

@@ -0,0 +1,3 @@
+export { forgeTabIcon } from './forgeTabIcon';
+export type { ForgeNativeBottomTabIcon, ForgeTabBarIcon } from './types';
+export type { ForgeTabIcon, ForgeTabIconNativeSources } from '@cdx-ui/icons/tab-icons';

package/src/navigation/types.ts

@@ -0,0 +1,54 @@
+import type { ReactElement } from 'react';
+import type { ImageSourcePropType } from 'react-native';
+import type { BottomTabNavigationOptions } from '@react-navigation/bottom-tabs';
+import type { NativeBottomTabNavigationOptions } from '@react-navigation/bottom-tabs/unstable';
+
+/**
+ * Structural mirror of the `image` arm of `NativeBottomTabIcon` from
+ * `@react-navigation/bottom-tabs/unstable`. Declared locally so
+ * `@cdx-ui/components` carries no runtime React Navigation dependency —
+ * the drift guards below fail the build if the upstream shape changes.
+ */
+export interface ForgeNativeBottomTabIcon {
+  type: 'image';
+  /** Metro-resolved asset (e.g. a static `require('./icon.png')`). */
+  source: ImageSourcePropType;
+  /**
+   * Render as a template image tinted with the tab bar's active/inactive
+   * tint color. iOS-only flag — Android always tints tab icons.
+   */
+  tinted?: boolean;
+}
+
+/**
+ * The value `forgeTabIcon()` returns — callable as `tabBarIcon` on **both**
+ * React Navigation bottom tab navigators. The intersection carries both call
+ * signatures; the platform-split implementation guarantees the matching one
+ * at runtime:
+ *
+ * - `createBottomTabNavigator` (web/JS) invokes it with
+ *   `{ focused, color, size }` and renders the returned element.
+ * - `createNativeBottomTabNavigator` (iOS/Android) invokes it with
+ *   `{ focused }` and receives a native icon descriptor.
+ */
+export type ForgeTabBarIcon = ((props: {
+  focused: boolean;
+  color: string;
+  size: number;
+}) => ReactElement) &
+  ((props: { focused: boolean }) => ForgeNativeBottomTabIcon);
+
+/**
+ * Compile-time drift guards (see `useForgeBottomTabScreenOptions` for the
+ * pattern): `ForgeTabBarIcon` must stay assignable to the `tabBarIcon`
+ * option of both navigators. The `null as any` casts keep the runtime
+ * values `null` so tree-shakers eliminate them entirely.
+ */
+
+const _rnDriftGuardWeb: BottomTabNavigationOptions['tabBarIcon'] =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  null as any as ForgeTabBarIcon;
+
+const _rnDriftGuardNative: NativeBottomTabNavigationOptions['tabBarIcon'] =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  null as any as ForgeTabBarIcon;

package/src/styles/primitives.ts

@@ -1,38 +1,67 @@
 // packages/components/src/styles/primitives.ts
-// Semantic constants for CDX UI component styling.
+// Semantic constants for Forge UI component styling.
 
 // ─── Colors ──────────────────────────────────────────────
 // Surface & background
+/** @deprecated Use `bg-surface-primary` (--color-surface-primary) instead. */
 export const COLOR_BG_PRIMARY = 'bg-white';
+/** @deprecated Use `bg-surface-secondary` (--color-surface-secondary) instead. */
 export const COLOR_BG_SUBTLE = 'bg-slate-50';
+/** @deprecated Use `bg-surface-neutral-subtle` (--color-surface-neutral-subtle) instead. */
 export const COLOR_BG_MUTED = 'bg-slate-100';
+/** @deprecated Use `bg-base-950` (--color-base-950) instead. */
 export const COLOR_BG_INVERSE = 'bg-slate-900';
 
 // Border
+/** @deprecated Use `border-stroke-secondary` (--color-stroke-secondary) instead. */
 export const COLOR_BORDER_DEFAULT = 'border-slate-200';
+/** @deprecated Use `border-stroke-hover` (--color-stroke-hover) instead. */
 export const COLOR_BORDER_STRONG = 'border-slate-300';
+/** @deprecated Use `border-stroke-focus` (--color-stroke-focus) instead. */
 export const COLOR_BORDER_FOCUS = 'border-slate-900';
+/** @deprecated Use `border-stroke-danger` (--color-stroke-danger) instead. */
 export const COLOR_BORDER_INVALID = 'border-red-500';
 
 // Text
+/** @deprecated Use `text-content-primary` (--color-content-primary) instead. */
 export const COLOR_TEXT_PRIMARY = 'text-slate-900';
+/** @deprecated Use `text-content-secondary` (--color-content-secondary) instead. */
 export const COLOR_TEXT_SECONDARY = 'text-slate-500';
+/** @deprecated Use `text-content-tertiary` (--color-content-tertiary) instead. */
 export const COLOR_TEXT_MUTED = 'text-slate-400';
+/** @deprecated Use the appropriate `text-content-*-on-strong` token for the surface color, e.g. `text-content-action-on-strong` (--color-content-action-on-strong). */
 export const COLOR_TEXT_INVERSE = 'text-white';
+/** @deprecated Use `text-content-tertiary` (--color-content-tertiary) instead. */
 export const COLOR_TEXT_PLACEHOLDER = 'text-slate-400';
+/** @deprecated Use `text-content-danger` (--color-content-danger) instead. */
 export const COLOR_TEXT_INVALID = 'text-red-600';
 
 // Brand / Action
+/** @deprecated Use `bg-surface-action-strong` (--color-surface-action-strong) instead. */
 export const COLOR_BRAND_DEFAULT = 'bg-slate-900';
+/** @deprecated Use `bg-surface-action-strong-hover` (--color-surface-action-strong-hover) instead. */
 export const COLOR_BRAND_HOVER = 'bg-slate-800';
+/** @deprecated Use `bg-surface-action-strong-active` (--color-surface-action-strong-active) instead. */
 export const COLOR_BRAND_ACTIVE = 'bg-slate-700';
 
 // Accent (for checked states, active indicators)
+/** @deprecated Use `bg-surface-action-strong` (--color-surface-action-strong) instead. */
 export const COLOR_ACCENT_DEFAULT = 'bg-slate-900';
+/** @deprecated Use `border-stroke-action` (--color-stroke-action) instead. */
 export const COLOR_ACCENT_BORDER = 'border-slate-900';
 
-// Semantic colors (danger, warning, success, info)
-// Kept for Button's 5-color system
+/**
+ * @deprecated Use semantic token classes directly instead. Map each color key to its
+ * corresponding `--color-surface-*`, `--color-stroke-*`, and `--color-content-*` tokens:
+ * - `bg` → `bg-surface-{color}-strong` (--color-surface-{color}-strong)
+ * - `bgHover` → `bg-surface-{color}-strong-hover` (--color-surface-{color}-strong-hover)
+ * - `bgActive` → `bg-surface-{color}-strong-active` (--color-surface-{color}-strong-active)
+ * - `border` → `border-stroke-{color}` (--color-stroke-{color})
+ * - `text` → `text-content-{color}` (--color-content-{color})
+ * - `ring` → `ring-[--color-stroke-focus]` (--color-stroke-focus)
+ *
+ * See Button/styles.ts for a complete migration example.
+ */
 export const SEMANTIC_COLORS = {
   action: {
     bg: 'bg-slate-900',
@@ -77,21 +106,29 @@ export const SEMANTIC_COLORS = {
 } as const;
 
 // ─── Focus ───────────────────────────────────────────────
+/** @deprecated Use `ring-2 ring-[--color-stroke-focus] ring-offset-2` (--color-stroke-focus) instead. */
 export const FOCUS_RING = 'ring-2 ring-slate-400/50 ring-offset-2';
 
 // ─── Radius ──────────────────────────────────────────────
-export const RADIUS_SM = 'rounded-lg'; // buttons, inputs, checkboxes
-export const RADIUS_MD = 'rounded-xl'; // cards, dropdowns, modals
-export const RADIUS_FULL = 'rounded-full'; // pills, avatars, switches
+/** @deprecated Use `rounded-[var(--border-radius-button)]` for buttons/inputs or `rounded-[var(--border-radius-default)]` for containers. */
+export const RADIUS_SM = 'rounded-lg';
+/** @deprecated Use `rounded-[var(--border-radius-default)]` for cards/containers. */
+export const RADIUS_MD = 'rounded-xl';
+/** @deprecated Use `rounded-[var(--border-radius-round)]` for circular elements (icon buttons, radio, pills). */
+export const RADIUS_FULL = 'rounded-full';
 
 // ─── Shadows ─────────────────────────────────────────────
+
+/** @deprecated Use `shadow-sm` directly instead */
 export const SHADOW_SM = 'shadow-sm';
+/** @deprecated Use `shadow-md` directly instead */
 export const SHADOW_MD = 'shadow-md';
 
 // ─── Sizing ──────────────────────────────────────────────
 // Unified size scale for interactive/form components (Button, Input, Select, Checkbox).
 // Only two sizes: 'default' (regular) and 'small' (compact).
 // NOTE: Text and Heading use a separate typography scale (xs/sm/md/lg/xl) — not this.
+/** @deprecated */
 export const SIZE_SCALE = {
   default: { height: 'h-10', px: 'px-4', gap: 'gap-2', text: 'text-base' },
   small: { height: 'h-8', px: 'px-3', gap: 'gap-1.5', text: 'text-sm' },

package/src/utils/positionToDataIcon.ts

@@ -0,0 +1,34 @@
+import { dataAttributes } from '@cdx-ui/primitives';
+
+/**
+ * Position hint accepted by icon/spinner-bearing styled slots
+ * (`Button.Icon`, `Button.Spinner`, `Chip.Icon`, etc.). Maps to a logical
+ * `data-icon` attribute that CVA targets for leading/trailing padding.
+ *
+ * `'leading'`  → `data-icon="inline-start"`
+ * `'trailing'` → `data-icon="inline-end"`
+ */
+export type IconSlotPosition = 'leading' | 'trailing';
+
+/**
+ * Returns the data-attribute spread props for the requested position, or
+ * `undefined` when no position is set (so the attribute is omitted entirely
+ * and baseline spacing applies).
+ *
+ * Spread the result onto the rendered element:
+ *
+ * ```tsx
+ * <Icon {...positionToDataIcon(position)} />
+ * ```
+ *
+ * Spacing rules live in CVA variant strings, targeting the attribute via
+ * logical-property utilities so RTL flips automatically:
+ *
+ * ```ts
+ * cva(['data-[icon=inline-start]:me-1.5 data-[icon=inline-end]:ms-1.5'], { ... });
+ * ```
+ */
+export function positionToDataIcon(position?: IconSlotPosition) {
+  if (!position) return undefined;
+  return dataAttributes({ icon: position === 'leading' ? 'inline-start' : 'inline-end' });
+}

package/lib/commonjs/components/Field/FieldLabel.js

@@ -1,33 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.BaseFieldLabel = void 0;
-var _react = require("react");
-var _reactNative = require("react-native");
-var _utils = require("@cdx-ui/utils");
-var _jsxRuntime = require("react/jsx-runtime");
-/**
- * Native: `Text` label row — tap focuses the field input via form context
- * (parity with `<label htmlFor>` on web).
- */
-const BaseFieldLabel = exports.BaseFieldLabel = /*#__PURE__*/(0, _react.forwardRef)(({
-  htmlFor: _omitHtmlFor,
-  onPress,
-  ...props
-}, ref) => {
-  void _omitHtmlFor;
-  const {
-    focusInput,
-    isDisabled
-  } = (0, _utils.useFormControlContext)();
-  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
-    ref: ref,
-    ...props,
-    disabled: Boolean(isDisabled),
-    onPress: (0, _utils.composeEventHandlers)(onPress, () => focusInput?.())
-  });
-});
-BaseFieldLabel.displayName = 'BaseFieldLabel';
-//# sourceMappingURL=FieldLabel.js.map

package/lib/commonjs/components/Field/FieldLabel.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["_react","require","_reactNative","_utils","_jsxRuntime","BaseFieldLabel","exports","forwardRef","htmlFor","_omitHtmlFor","onPress","props","ref","focusInput","isDisabled","useFormControlContext","jsx","Text","disabled","Boolean","composeEventHandlers","displayName"],"sourceRoot":"../../../../src","sources":["components/Field/FieldLabel.tsx"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,YAAA,GAAAD,OAAA;AACA,IAAAE,MAAA,GAAAF,OAAA;AAA4E,IAAAG,WAAA,GAAAH,OAAA;AAS5E;AACA;AACA;AACA;AACO,MAAMI,cAAc,GAAAC,OAAA,CAAAD,cAAA,gBAAG,IAAAE,iBAAU,EACtC,CAAC;EAAEC,OAAO,EAAEC,YAAY;EAAEC,OAAO;EAAE,GAAGC;AAAM,CAAC,EAAEC,GAAG,KAAK;EACrD,KAAKH,YAAY;EAEjB,MAAM;IAAEI,UAAU;IAAEC;EAAW,CAAC,GAAG,IAAAC,4BAAqB,EAAC,CAAC;EAE1D,oBACE,IAAAX,WAAA,CAAAY,GAAA,EAACd,YAAA,CAAAe,IAAI;IACHL,GAAG,EAAEA,GAAI;IAAA,GACLD,KAAK;IACTO,QAAQ,EAAEC,OAAO,CAACL,UAAU,CAAE;IAC9BJ,OAAO,EAAE,IAAAU,2BAAoB,EAACV,OAAO,EAAE,MAAMG,UAAU,GAAG,CAAC;EAAE,CAC9D,CAAC;AAEN,CACF,CAAC;AAEDR,cAAc,CAACgB,WAAW,GAAG,gBAAgB","ignoreList":[]}

package/lib/commonjs/components/Field/FieldLabel.web.js

@@ -1,22 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.BaseFieldLabel = void 0;
-var _react = _interopRequireWildcard(require("react"));
-var _jsxRuntime = require("react/jsx-runtime");
-function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
-// TODO: Why does dataSet need to be decomposed into individual data attributes?
-
-/** Real `<label>` so clicking the label focuses the associated control (`htmlFor` → input `id`). */
-const BaseFieldLabel = exports.BaseFieldLabel = /*#__PURE__*/(0, _react.forwardRef)((props, ref) => {
-  return /*#__PURE__*/(0, _jsxRuntime.jsx)("label", {
-    ref: ref,
-    ...props,
-    "data-invalid": props.dataSet?.invalid,
-    "data-required": props.dataSet?.required
-  });
-});
-BaseFieldLabel.displayName = 'BaseFieldLabel';
-//# sourceMappingURL=FieldLabel.web.js.map

package/lib/commonjs/components/Field/FieldLabel.web.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["_react","_interopRequireWildcard","require","_jsxRuntime","e","t","WeakMap","r","n","__esModule","o","i","f","__proto__","default","has","get","set","hasOwnProperty","call","Object","defineProperty","getOwnPropertyDescriptor","BaseFieldLabel","exports","forwardRef","props","ref","jsx","dataSet","invalid","required","displayName"],"sourceRoot":"../../../../src","sources":["components/Field/FieldLabel.web.tsx"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,uBAAA,CAAAC,OAAA;AAA0D,IAAAC,WAAA,GAAAD,OAAA;AAAA,SAAAD,wBAAAG,CAAA,EAAAC,CAAA,6BAAAC,OAAA,MAAAC,CAAA,OAAAD,OAAA,IAAAE,CAAA,OAAAF,OAAA,YAAAL,uBAAA,YAAAA,CAAAG,CAAA,EAAAC,CAAA,SAAAA,CAAA,IAAAD,CAAA,IAAAA,CAAA,CAAAK,UAAA,SAAAL,CAAA,MAAAM,CAAA,EAAAC,CAAA,EAAAC,CAAA,KAAAC,SAAA,QAAAC,OAAA,EAAAV,CAAA,iBAAAA,CAAA,uBAAAA,CAAA,yBAAAA,CAAA,SAAAQ,CAAA,MAAAF,CAAA,GAAAL,CAAA,GAAAG,CAAA,GAAAD,CAAA,QAAAG,CAAA,CAAAK,GAAA,CAAAX,CAAA,UAAAM,CAAA,CAAAM,GAAA,CAAAZ,CAAA,GAAAM,CAAA,CAAAO,GAAA,CAAAb,CAAA,EAAAQ,CAAA,gBAAAP,CAAA,IAAAD,CAAA,gBAAAC,CAAA,OAAAa,cAAA,CAAAC,IAAA,CAAAf,CAAA,EAAAC,CAAA,OAAAM,CAAA,IAAAD,CAAA,GAAAU,MAAA,CAAAC,cAAA,KAAAD,MAAA,CAAAE,wBAAA,CAAAlB,CAAA,EAAAC,CAAA,OAAAM,CAAA,CAAAK,GAAA,IAAAL,CAAA,CAAAM,GAAA,IAAAP,CAAA,CAAAE,CAAA,EAAAP,CAAA,EAAAM,CAAA,IAAAC,CAAA,CAAAP,CAAA,IAAAD,CAAA,CAAAC,CAAA,WAAAO,CAAA,KAAAR,CAAA,EAAAC,CAAA;AAG1D;;AASA;AACO,MAAMkB,cAAc,GAAAC,OAAA,CAAAD,cAAA,gBAAG,IAAAE,iBAAU,EAAwC,CAACC,KAAK,EAAEC,GAAG,KAAK;EAC9F,oBACE,IAAAxB,WAAA,CAAAyB,GAAA;IACED,GAAG,EAAEA,GAAI;IAAA,GACJD,KAAK;IACV,gBAAcA,KAAK,CAACG,OAAO,EAAEC,OAAQ;IACrC,iBAAeJ,KAAK,CAACG,OAAO,EAAEE;EAAS,CACxC,CAAC;AAEN,CAAC,CAAC;AAEFR,cAAc,CAACS,WAAW,GAAG,gBAAgB","ignoreList":[]}