@cdx-ui/components 0.0.1-beta.50 → 0.0.1-beta.51

package/lib/typescript/hooks/useForgeBottomTabScreenOptions.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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';
+/**
+ * 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;
+    };
+}
+/**
+ * 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 declare function mergeForgeBottomTabScreenOptions(base: ForgeReactNavigationBottomTabScreenOptions, overrides: Partial<ForgeReactNavigationBottomTabScreenOptions>): ForgeReactNavigationBottomTabScreenOptions;
+export declare function useForgeBottomTabScreenOptions(): ForgeReactNavigationBottomTabScreenOptions;
+//# sourceMappingURL=useForgeBottomTabScreenOptions.d.ts.map

package/lib/typescript/hooks/useForgeBottomTabScreenOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useForgeBottomTabScreenOptions.d.ts","sourceRoot":"","sources":["../../../src/hooks/useForgeBottomTabScreenOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAM9C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,0CAA0C;IACzD,qBAAqB,EAAE,MAAM,CAAC;IAC9B,uBAAuB,EAAE,MAAM,CAAC;IAChC,WAAW,EAAE;QAAE,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,gBAAgB,EAAE;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,8EAA8E;QAC9E,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;KACrC,CAAC;IACF,gBAAgB,EAAE;QAAE,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAyED;;;;;;;GAOG;AACH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,0CAA0C,EAChD,SAAS,EAAE,OAAO,CAAC,0CAA0C,CAAC,GAC7D,0CAA0C,CAQ5C;AAED,wBAAgB,8BAA8B,IAAI,0CAA0C,CAwB3F"}

package/lib/typescript/index.d.ts

@@ -1,5 +1,7 @@
 /// <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';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AACA,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AACA,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC"}

package/lib/typescript/navigation/forgeTabIcon.d.ts

@@ -0,0 +1,27 @@
+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 declare function forgeTabIcon(icon: ForgeTabIcon): ForgeTabBarIcon;
+//# sourceMappingURL=forgeTabIcon.d.ts.map

package/lib/typescript/navigation/forgeTabIcon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forgeTabIcon.d.ts","sourceRoot":"","sources":["../../../src/navigation/forgeTabIcon.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,eAAe,CAKhE"}

package/lib/typescript/navigation/forgeTabIcon.native.d.ts

@@ -0,0 +1,15 @@
+import type { ForgeTabIcon } from '@cdx-ui/icons/tab-icons';
+import type { 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 declare function forgeTabIcon(icon: ForgeTabIcon): ForgeTabBarIcon;
+//# sourceMappingURL=forgeTabIcon.native.d.ts.map

package/lib/typescript/navigation/forgeTabIcon.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forgeTabIcon.native.d.ts","sourceRoot":"","sources":["../../../src/navigation/forgeTabIcon.native.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAA4B,eAAe,EAAE,MAAM,SAAS,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,eAAe,CAqBhE"}

package/lib/typescript/navigation/index.d.ts

@@ -0,0 +1,4 @@
+export { forgeTabIcon } from './forgeTabIcon';
+export type { ForgeNativeBottomTabIcon, ForgeTabBarIcon } from './types';
+export type { ForgeTabIcon, ForgeTabIconNativeSources } from '@cdx-ui/icons/tab-icons';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/navigation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/navigation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACzE,YAAY,EAAE,YAAY,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC"}

package/lib/typescript/navigation/types.d.ts

@@ -0,0 +1,37 @@
+import type { ReactElement } from 'react';
+import type { ImageSourcePropType } from 'react-native';
+/**
+ * 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);
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/navigation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/navigation/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAC1C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAIxD;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,OAAO,CAAC;IACd,oEAAoE;IACpE,MAAM,EAAE,mBAAmB,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,EAAE;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,KAAK,YAAY,CAAC,GACjB,CAAC,CAAC,KAAK,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,KAAK,wBAAwB,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cdx-ui/components",
-  "version": "0.0.1-beta.50",
+  "version": "0.0.1-beta.51",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
   "react-native": "src/index.ts",
@@ -67,11 +67,13 @@
     "@gorhom/bottom-sheet": "^5.2.6",
     "class-variance-authority": "^0.7.1",
     "uniwind": "1.6.1",
-    "@cdx-ui/primitives": "0.0.1-beta.50",
-    "@cdx-ui/utils": "0.0.1-beta.50",
-    "@cdx-ui/icons": "0.0.1-beta.50"
+    "@cdx-ui/primitives": "0.0.1-beta.51",
+    "@cdx-ui/utils": "0.0.1-beta.51",
+    "@cdx-ui/icons": "0.0.1-beta.51"
   },
   "devDependencies": {
+    "@react-navigation/bottom-tabs": "*",
+    "react-native-screens": "*",
     "@types/react": "*",
     "@types/react-dom": "*",
     "react": "*",

package/src/components/Button/index.tsx

@@ -175,9 +175,9 @@ ButtonGroup.displayName = 'Button.Group';
 export interface ButtonIconProps extends Omit<IconProps, 'children'> {}
 
 const ButtonIcon = ({ className, style, as, ...props }: ButtonIconProps) => {
-  const { size } = useButtonStyleContext();
+  const { variant, color, size } = useButtonStyleContext();
 
-  const computedClassName = cn(buttonIconVariants({ size }), className);
+  const computedClassName = cn(buttonIconVariants({ variant, color, size }), className);
 
   return <Icon as={as} className={computedClassName} style={style} {...props} />;
 };

package/src/components/Button/styles.ts

@@ -351,12 +351,41 @@ export const buttonGroupVariants = cva([], {
 
 export const buttonIconVariants = cva([], {
   variants: {
+    variant: {
+      solid: [],
+      outline: [],
+      ghost: [],
+    },
+    color: {
+      action: [],
+      danger: [],
+      warning: [],
+      success: [],
+      info: [],
+    },
     size: {
       default: 'size-5',
       small: 'size-4',
     },
   },
+  compoundVariants: [
+    // ── solid × color (filled foreground icon) ──────────────────────
+    { variant: 'solid', color: 'action', className: 'text-content-action-on-strong' },
+    { variant: 'solid', color: 'danger', className: 'text-content-danger-on-strong' },
+    { variant: 'solid', color: 'warning', className: 'text-content-warning-on-strong' },
+    { variant: 'solid', color: 'success', className: 'text-content-success-on-strong' },
+    { variant: 'solid', color: 'info', className: 'text-content-info-on-strong' },
+
+    // ── outline/ghost × color (transparent foreground icon) ──────────
+    { variant: ['outline', 'ghost'], color: 'action', className: 'text-content-action' },
+    { variant: ['outline', 'ghost'], color: 'danger', className: 'text-content-danger' },
+    { variant: ['outline', 'ghost'], color: 'warning', className: 'text-content-warning' },
+    { variant: ['outline', 'ghost'], color: 'success', className: 'text-content-success' },
+    { variant: ['outline', 'ghost'], color: 'info', className: 'text-content-info' },
+  ],
   defaultVariants: {
+    variant: 'solid',
+    color: 'action',
     size: 'default',
   },
 });

package/src/hooks/index.ts

@@ -0,0 +1,5 @@
+export {
+  useForgeBottomTabScreenOptions,
+  mergeForgeBottomTabScreenOptions,
+  type ForgeReactNavigationBottomTabScreenOptions,
+} from './useForgeBottomTabScreenOptions';

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.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+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/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;
+}