@startsimpli/ui-native 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# @startsimpli/ui-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React Native UI primitives for StartSimpli apps — the native counterpart to
+[`@startsimpli/ui`](../ui) (web/Tailwind). Both draw from the same design-token
+values; see [`./src/tokens.ts`](./src/tokens.ts) and
+[`packages/ui/theme/contract.css`](../ui/theme/contract.css).
+
+> **Status: new package, in progress.** This is part of the
+> `react-native-enablement` initiative. The token system and the 30+ primitives
+> below are live and tested, but the React Native parity story is still being
+> built out — the `examples/mobile-rn` Expo demo is the canonical consumer
+> today.
+
+Ships raw TypeScript source; Metro/Expo bundles it directly.
+
+## Install
+
+```sh
+pnpm add @startsimpli/ui-native
+
+# Required peers:
+pnpm add react react-native
+
+# Optional peers (Screen safe-area insets, chart primitives):
+pnpm add react-native-safe-area-context react-native-svg
+```
+
+`react-native-safe-area-context` is required for `Screen`'s inset handling and
+the `SafeAreaProvider` that `ThemeProvider` mounts. `react-native-svg` is
+required only for the chart primitives (`Sparkline`, `DonutChart`,
+`TrendChart`, `TrendCard`).
+
+## Quick start
+
+```tsx
+import {
+  ThemeProvider,
+  Screen,
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  Text,
+  Button,
+} from '@startsimpli/ui-native';
+
+export default function App() {
+  return (
+    <ThemeProvider>
+      <Screen scroll>
+        <Card>
+          <CardHeader>
+            <CardTitle>Hello</CardTitle>
+            <CardDescription>Rendered from shared primitives.</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Text variant="muted">Tap to continue.</Text>
+            <Button title="Continue" variant="primary" />
+          </CardContent>
+        </Card>
+      </Screen>
+    </ThemeProvider>
+  );
+}
+```
+
+`ThemeProvider` follows the OS light/dark scheme by default (pass an explicit
+`theme={lightTheme | darkTheme | customTheme}` to pin it) and mounts a
+`SafeAreaProvider` so `Screen` can apply insets.
+
+## Design tokens
+
+Tokens are the single source for color, spacing, type scale, radii, and
+animation durations. Available both as a barrel (`@startsimpli/ui-native`)
+and at a stable subpath:
+
+```ts
+import { palette, hsl, radii, spacing, fontSizes, fontWeights, durations }
+  from '@startsimpli/ui-native/tokens';
+
+import { makeTheme, lightTheme, darkTheme, type Theme }
+  from '@startsimpli/ui-native';
+```
+
+Colors are stored as HSL channel strings (`"221.2 83.2% 53.3%"`) that mirror
+the CSS custom properties in `packages/ui/theme/contract.css` — the same source
+the web Tailwind preset reads via `hsl(var(--token))`. The `hsl()` helper
+converts a channel string into a React Native–parseable
+`hsl(h, s%, l%)` color, and `makeTheme(scheme)` resolves a whole palette into
+a ready-to-use `Theme` object.
+
+> **Cross-link: [startsim-sw1.8](../../.beads/)** — *Single-source design
+> tokens between ui-native `tokens.ts` and web Tailwind/`contract.css`.*
+> Today the channel-string palette in `tokens.ts` is hand-mirrored from
+> `contract.css`. The plan is to derive one from the other so a single token
+> edit flows to both web and native (parent: `startsim-sw1` "RN-enable shared
+> packages"). Until that lands, treat any token change as a two-file edit.
+
+## Public surface
+
+### Theming + layout
+
+| Export | Purpose |
+|---|---|
+| `ThemeProvider` / `useTheme` | OS-following light/dark, pinnable via `theme` prop. Provides `Theme` to every primitive. |
+| `Screen` | Top-level scrolling/non-scrolling container with safe-area insets. |
+| `ErrorBoundary` | Surface render errors as a styled fallback. |
+| `AccentProvider` / `useAccent` | Per-subtree accent override (e.g. brand-colored section). |
+
+### Primitives
+
+`Text`, `Button`, `Badge`, `Label`, `Input`, `Separator`, `Checkbox`, `Switch`,
+`Progress`, `Alert`, `Skeleton`, `SkeletonList`, `Spinner`, `Avatar`, `Chip`,
+`SegmentedControl`, `TabBar`, `ShareBar` — and the `Card` composition
+(`Card` / `CardHeader` / `CardTitle` / `CardDescription` / `CardContent`).
+
+### Composed building blocks
+
+`StatTile`, `EmptyState`, `ListRow`, `MetricRow`, `Timeline`, `DataTable`,
+`HeroBanner`, `GradientBox`.
+
+### Charts (require `react-native-svg`)
+
+`Sparkline`, `DonutChart`, `DonutLegend`, `TrendChart`, `TrendCard`, plus the
+pure math helpers re-exported from `charts-math` (used by the components and
+safely importable in tests).
+
+### Pure style builders
+
+Every component's style logic is split into `./src/styles.ts` so it can be
+unit-tested without a React Native renderer. The builders are re-exported for
+custom components that want the same look:
+
+```ts
+import { buttonContainerStyle, buttonTextStyle, badgeStyle, /* ... */ }
+  from '@startsimpli/ui-native';
+```
+
+## Dark mode
+
+`ThemeProvider` reads `useColorScheme()` from `react-native` and resolves to
+`lightTheme` or `darkTheme` per OS setting. Pin with `theme={lightTheme}` to
+force a scheme; pass a custom `makeTheme(...)` to override the palette.
+
+## Verification
+
+```bash
+pnpm --filter @startsimpli/ui-native test          # 51 tests across 6 files
+pnpm --filter @startsimpli/ui-native type-check
+```
+
+Tests cover the tokens, the resolved themes, the chart math, and every style
+builder (dashboard composites + primitives). Component rendering is exercised
+end-to-end by `examples/mobile-rn/App.tsx` (Expo iOS/Android/web).
+
+**Browser/device verification is not optional** for visual changes — drive the
+Expo demo on simulator/device (`pnpm --filter mobile-rn ios|android|web`) and
+report what you actually saw. Type-checks and unit tests do not prove a
+primitive renders. See the MCP-default rule in
+`/Users/qosha/Repos/start-simpli/CLAUDE.md` (rule 10).
+
+## Shared-package policy
+
+Per `CLAUDE.md` rule 9, every RN UI primitive that another app might
+plausibly want belongs here — **not** in `apps/*/src`. If you're about to
+build a Pressable wrapper, a card variant, a chart, or a token-aware style
+helper in an app, extend this package instead. The web equivalent lives in
+[`@startsimpli/ui`](../ui); keep the two in lock-step.
+
+## License
+
+Private package for the StartSimpli monorepo.

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@startsimpli/ui-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "React Native UI primitives for StartSimpli apps (View/Text/Pressable), fed by shared design tokens",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "react-native": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./tokens": "./src/tokens.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.74.0",
+    "react-native-safe-area-context": ">=4.0.0",
+    "react-native-svg": ">=14.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native-safe-area-context": {
+      "optional": true
+    },
+    "react-native-svg": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "react": "^19.2.5",
+    "react-native": "0.85.3",
+    "react-native-safe-area-context": "~5.7.0",
+    "react-native-svg": "15.15.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  }
+}

package/src/__tests__/charts-math.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import { points, linePath, areaPath, donutDashes, sharedExtent, multiLinePaths } from '../charts-math';
+
+describe('points', () => {
+  it('spreads x across the padded width and maps min->bottom, max->top', () => {
+    const box = { width: 100, height: 50, pad: 0 };
+    const pts = points([0, 10], box);
+    expect(pts[0]).toEqual([0, 50]); // first x=0, min value -> bottom (y=height)
+    expect(pts[1]).toEqual([100, 0]); // last x=width, max value -> top (y=0)
+  });
+  it('centers a single point and never divides by zero on a flat series', () => {
+    expect(points([5], { width: 80, height: 20 })[0][0]).toBe(40);
+    const flat = points([3, 3, 3], { width: 90, height: 30, pad: 0 });
+    expect(flat.every(([, y]) => Number.isFinite(y))).toBe(true);
+  });
+});
+
+describe('paths', () => {
+  it('linePath starts with M and has a point per value', () => {
+    const d = linePath([1, 2, 3], { width: 60, height: 20 });
+    expect(d.startsWith('M')).toBe(true);
+    expect((d.match(/[ML]/g) ?? []).length).toBe(3);
+  });
+  it('areaPath closes back to the baseline', () => {
+    const d = areaPath([1, 2], { width: 60, height: 20, pad: 0 });
+    expect(d.endsWith('Z')).toBe(true);
+  });
+});
+
+describe('donutDashes', () => {
+  it('splits the circumference proportionally and accumulates offsets', () => {
+    const c = 100;
+    const d = donutDashes([{ value: 1, color: 'a' }, { value: 3, color: 'b' }], c, 0);
+    expect(d[0].fraction).toBeCloseTo(0.25);
+    expect(d[0].dash).toBeCloseTo(25);
+    expect(d[1].dash).toBeCloseTo(75);
+    expect(d[0].offset).toBe(-0); // first slice starts at 0
+    expect(d[1].offset).toBeCloseTo(-25); // second starts where first ended
+  });
+  it('handles all-zero input without NaN', () => {
+    const d = donutDashes([{ value: 0, color: 'a' }], 100);
+    expect(Number.isFinite(d[0].dash)).toBe(true);
+  });
+});
+
+describe('shared-domain scaling (multi-series compare)', () => {
+  it('points honors an explicit domain so flat series sit by their absolute level', () => {
+    const box = { width: 100, height: 50, pad: 0 };
+    // value 5 in domain [0,10] → halfway up (y = height/2)
+    expect(points([5, 5], box, [0, 10])[0][1]).toBeCloseTo(25);
+    // value 10 in the same domain → top
+    expect(points([10], box, [0, 10])[0][1]).toBeCloseTo(0);
+  });
+
+  it('sharedExtent spans the min and max across every series', () => {
+    expect(sharedExtent([[1, 4], [2, 9], [0, 3]])).toEqual([0, 9]);
+  });
+
+  it('sharedExtent is finite on empty input', () => {
+    const [lo, hi] = sharedExtent([]);
+    expect(Number.isFinite(lo) && Number.isFinite(hi)).toBe(true);
+  });
+
+  it('multiLinePaths returns one path per series, all on the same scale', () => {
+    const box = { width: 100, height: 50, pad: 0 };
+    const paths = multiLinePaths([[0, 10], [5, 5]], box);
+    expect(paths.length).toBe(2);
+    expect(paths.every((d) => d.startsWith('M'))).toBe(true);
+    // series B is flat at 5 → both endpoints at the same y (mid of shared [0,10])
+    const yB = paths[1].match(/M[\d.]+ ([\d.]+)/)?.[1];
+    expect(Number(yB)).toBeCloseTo(25);
+  });
+});

package/src/__tests__/styles-dashboard.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect } from 'vitest';
+import { lightTheme } from '../theme';
+import {
+  avatarStyle,
+  avatarTextStyle,
+  statTileStyle,
+  statValueStyle,
+  statDeltaColor,
+  listRowStyle,
+  listRowTitleStyle,
+  tabBarStyle,
+  tabItemStyle,
+  tabLabelStyle,
+  shareBarTrackStyle,
+  chipStyle,
+  chipTextStyle,
+  timelineDotStyle,
+  timelineConnectorStyle,
+} from '../styles';
+
+const t = lightTheme;
+
+describe('avatar', () => {
+  it('is a circular sized surface; md = 44px', () => {
+    const s = avatarStyle(t, 'md');
+    expect(s.width).toBe(44);
+    expect(s.borderRadius).toBe(t.radii.full);
+    expect(s.backgroundColor).toBe(t.colors.secondary);
+  });
+  it('honors a custom color and text color', () => {
+    expect(avatarStyle(t, 'sm', '#abc').backgroundColor).toBe('#abc');
+    expect(avatarTextStyle(t, 'lg', '#fff').color).toBe('#fff');
+  });
+});
+
+describe('statTile', () => {
+  it('value is a 3xl extrabold display number; delta colors track direction', () => {
+    expect(statValueStyle(t).fontSize).toBe(t.fontSizes['3xl']);
+    expect(statValueStyle(t).fontWeight).toBe(t.fontWeights.extrabold);
+    expect(statTileStyle(t).borderColor).toBe(t.colors.border);
+    expect(statDeltaColor(t, 'up')).toBe(t.colors.primary);
+    expect(statDeltaColor(t, 'down')).toBe(t.colors.destructive);
+    expect(statDeltaColor(t, 'neutral')).toBe(t.colors.mutedForeground);
+  });
+});
+
+describe('listRow', () => {
+  it('is a horizontal row; title is medium-weight foreground', () => {
+    expect(listRowStyle(t).flexDirection).toBe('row');
+    expect(listRowTitleStyle(t).fontWeight).toBe(t.fontWeights.medium);
+  });
+});
+
+describe('shareBar', () => {
+  it('is a rounded, clipped horizontal track', () => {
+    const s = shareBarTrackStyle(t, 10);
+    expect(s.flexDirection).toBe('row');
+    expect(s.height).toBe(10);
+    expect(s.overflow).toBe('hidden');
+    expect(s.borderRadius).toBe(t.radii.full);
+  });
+});
+
+describe('chip', () => {
+  it('selected fills primary; unselected is transparent with a border', () => {
+    expect(chipStyle(t, true).backgroundColor).toBe(t.colors.primary);
+    expect(chipTextStyle(t, true).color).toBe(t.colors.primaryForeground);
+    expect(chipStyle(t, false).backgroundColor).toBe('transparent');
+    expect(chipStyle(t, false).borderColor).toBe(t.colors.border);
+  });
+});
+
+describe('timeline', () => {
+  it('dot defaults to primary and is round; connector uses the border color', () => {
+    expect(timelineDotStyle(t).backgroundColor).toBe(t.colors.primary);
+    expect(timelineDotStyle(t, '#abc').backgroundColor).toBe('#abc');
+    expect(timelineDotStyle(t).borderRadius).toBe(t.radii.full);
+    expect(timelineConnectorStyle(t).backgroundColor).toBe(t.colors.border);
+  });
+});
+
+describe('tabBar', () => {
+  it('has a top border; items flex equally', () => {
+    expect(tabBarStyle(t).borderTopWidth).toBe(1);
+    expect(tabItemStyle(t).flex).toBe(1);
+  });
+  it('active label is primary + semibold, inactive is muted', () => {
+    expect(tabLabelStyle(t, true).color).toBe(t.colors.primary);
+    expect(tabLabelStyle(t, true).fontWeight).toBe(t.fontWeights.semibold);
+    expect(tabLabelStyle(t, false).color).toBe(t.colors.mutedForeground);
+  });
+});

package/src/__tests__/styles-primitives.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect } from 'vitest';
+import { lightTheme } from '../theme';
+import {
+  buttonContainerStyle,
+  buttonTextStyle,
+  badgeStyle,
+  badgeTextStyle,
+  inputStyle,
+  labelStyle,
+  separatorStyle,
+  checkboxStyle,
+  progressTrackStyle,
+  progressFillStyle,
+  alertStyle,
+  alertTitleStyle,
+  skeletonStyle,
+  cardTitleStyle,
+  cardDescriptionStyle,
+} from '../styles';
+
+const t = lightTheme;
+
+describe('button: ghost + link variants', () => {
+  it('ghost is transparent with foreground text and no border', () => {
+    const c = buttonContainerStyle(t, 'ghost', 'md');
+    expect(c.backgroundColor).toBe('transparent');
+    expect(c.borderWidth).toBeUndefined();
+    expect(buttonTextStyle(t, 'ghost', 'md').color).toBe(t.colors.foreground);
+  });
+
+  it('link is transparent with primary-colored text', () => {
+    expect(buttonContainerStyle(t, 'link', 'md').backgroundColor).toBe('transparent');
+    expect(buttonTextStyle(t, 'link', 'md').color).toBe(t.colors.primary);
+  });
+});
+
+describe('badge', () => {
+  it('default fills primary; text is on-primary', () => {
+    expect(badgeStyle(t, 'default').backgroundColor).toBe(t.colors.primary);
+    expect(badgeTextStyle(t, 'default').color).toBe(t.colors.primaryForeground);
+  });
+  it('destructive fills destructive', () => {
+    expect(badgeStyle(t, 'destructive').backgroundColor).toBe(t.colors.destructive);
+  });
+  it('outline is transparent with a border', () => {
+    const s = badgeStyle(t, 'outline');
+    expect(s.backgroundColor).toBe('transparent');
+    expect(s.borderWidth).toBe(1);
+    expect(badgeTextStyle(t, 'outline').color).toBe(t.colors.foreground);
+  });
+});
+
+describe('input + label', () => {
+  it('input uses the input border by default and destructive when invalid', () => {
+    expect(inputStyle(t).borderColor).toBe(t.colors.input);
+    expect(inputStyle(t).borderWidth).toBe(1);
+    expect(inputStyle(t, { invalid: true }).borderColor).toBe(t.colors.destructive);
+  });
+  it('label is medium-weight foreground text', () => {
+    const l = labelStyle(t);
+    expect(l.color).toBe(t.colors.foreground);
+    expect(l.fontWeight).toBe(t.fontWeights.medium);
+  });
+});
+
+describe('separator', () => {
+  it('horizontal is a 1px full-width border-colored rule', () => {
+    const s = separatorStyle(t, 'horizontal');
+    expect(s.height).toBe(1);
+    expect(s.backgroundColor).toBe(t.colors.border);
+  });
+  it('vertical is a 1px-wide rule', () => {
+    expect(separatorStyle(t, 'vertical').width).toBe(1);
+  });
+});
+
+describe('checkbox', () => {
+  it('checked fills + borders with primary; unchecked is transparent', () => {
+    const on = checkboxStyle(t, true);
+    expect(on.backgroundColor).toBe(t.colors.primary);
+    expect(on.borderColor).toBe(t.colors.primary);
+    expect(checkboxStyle(t, false).backgroundColor).toBe('transparent');
+  });
+});
+
+describe('progress', () => {
+  it('track is a muted pill; fill is primary and width tracks value', () => {
+    expect(progressTrackStyle(t).backgroundColor).toBe(t.colors.muted);
+    expect(progressFillStyle(t, 50).width).toBe('50%');
+    expect(progressFillStyle(t, 50).backgroundColor).toBe(t.colors.primary);
+  });
+  it('clamps value to [0, 100]', () => {
+    expect(progressFillStyle(t, 150).width).toBe('100%');
+    expect(progressFillStyle(t, -5).width).toBe('0%');
+  });
+});
+
+describe('alert', () => {
+  it('default vs destructive variants color the border + title', () => {
+    expect(alertStyle(t, 'destructive').borderColor).toBe(t.colors.destructive);
+    expect(alertTitleStyle(t, 'destructive').color).toBe(t.colors.destructive);
+    expect(alertTitleStyle(t, 'default').color).toBe(t.colors.foreground);
+  });
+});
+
+describe('skeleton + card text', () => {
+  it('skeleton is a muted rounded block', () => {
+    expect(skeletonStyle(t).backgroundColor).toBe(t.colors.muted);
+  });
+  it('card title is semibold; description is muted', () => {
+    expect(cardTitleStyle(t).fontWeight).toBe(t.fontWeights.semibold);
+    expect(cardDescriptionStyle(t).color).toBe(t.colors.mutedForeground);
+  });
+});

package/src/__tests__/styles.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest';
+import { lightTheme } from '../theme';
+import {
+  buttonContainerStyle,
+  buttonTextStyle,
+  cardStyle,
+  textStyle,
+  badgeStyle,
+  badgeTextStyle,
+} from '../styles';
+
+describe('textStyle display variant', () => {
+  it('is a large, extra-bold variant suitable for hero numerals', () => {
+    const s = textStyle(lightTheme, 'display');
+    expect(s.fontSize ?? 0).toBeGreaterThanOrEqual(40);
+    expect(Number(s.fontWeight ?? '0')).toBeGreaterThanOrEqual(800);
+  });
+});
+
+describe('buttonContainerStyle touch targets', () => {
+  it('md (default) buttons meet the 44px touch-target guidance', () => {
+    expect(buttonContainerStyle(lightTheme, 'primary', 'md').minHeight).toBeGreaterThanOrEqual(44);
+  });
+  it('lg buttons are larger still', () => {
+    expect(buttonContainerStyle(lightTheme, 'primary', 'lg').minHeight).toBeGreaterThanOrEqual(48);
+  });
+});
+
+describe('badgeStyle semantic variants', () => {
+  it('success uses the success color with its foreground', () => {
+    expect(badgeStyle(lightTheme, 'success').backgroundColor).toBe(lightTheme.colors.success);
+    expect(badgeTextStyle(lightTheme, 'success').color).toBe(lightTheme.colors.successForeground);
+  });
+  it('warning uses the warning color with its foreground', () => {
+    expect(badgeStyle(lightTheme, 'warning').backgroundColor).toBe(lightTheme.colors.warning);
+    expect(badgeTextStyle(lightTheme, 'warning').color).toBe(lightTheme.colors.warningForeground);
+  });
+});
+
+describe('buttonContainerStyle', () => {
+  it('fills with the primary color and uses the md radius', () => {
+    const s = buttonContainerStyle(lightTheme, 'primary', 'md');
+    expect(s.backgroundColor).toBe(lightTheme.colors.primary);
+    expect(s.borderRadius).toBe(lightTheme.radii.md);
+  });
+
+  it('renders the destructive variant with the destructive color', () => {
+    expect(buttonContainerStyle(lightTheme, 'destructive', 'md').backgroundColor).toBe(
+      lightTheme.colors.destructive
+    );
+  });
+
+  it('renders outline as a transparent, bordered button', () => {
+    const s = buttonContainerStyle(lightTheme, 'outline', 'md');
+    expect(s.backgroundColor).toBe('transparent');
+    expect(s.borderWidth).toBe(1);
+    expect(s.borderColor).toBe(lightTheme.colors.border);
+  });
+
+  it('scales vertical padding with size', () => {
+    const sm = buttonContainerStyle(lightTheme, 'primary', 'sm');
+    const lg = buttonContainerStyle(lightTheme, 'primary', 'lg');
+    expect(Number(sm.paddingVertical)).toBeLessThan(Number(lg.paddingVertical));
+  });
+});
+
+describe('buttonTextStyle', () => {
+  it('uses the on-primary foreground for the primary variant', () => {
+    expect(buttonTextStyle(lightTheme, 'primary', 'md').color).toBe(
+      lightTheme.colors.primaryForeground
+    );
+  });
+
+  it('uses the foreground color for the outline variant', () => {
+    expect(buttonTextStyle(lightTheme, 'outline', 'md').color).toBe(lightTheme.colors.foreground);
+  });
+});
+
+describe('cardStyle', () => {
+  it('uses the card surface, lg radius and a hairline border', () => {
+    const s = cardStyle(lightTheme);
+    expect(s.backgroundColor).toBe(lightTheme.colors.card);
+    expect(s.borderRadius).toBe(lightTheme.radii.lg);
+    expect(s.borderWidth).toBe(1);
+    expect(s.borderColor).toBe(lightTheme.colors.border);
+  });
+});
+
+describe('textStyle', () => {
+  it('makes headings larger and heavier than body', () => {
+    const heading = textStyle(lightTheme, 'heading');
+    const body = textStyle(lightTheme, 'body');
+    expect(Number(heading.fontSize)).toBeGreaterThan(Number(body.fontSize));
+    expect(heading.fontWeight).toBe(lightTheme.fontWeights.bold);
+    expect(heading.color).toBe(lightTheme.colors.foreground);
+  });
+
+  it('renders muted text with the muted foreground color', () => {
+    expect(textStyle(lightTheme, 'muted').color).toBe(lightTheme.colors.mutedForeground);
+  });
+});

package/src/__tests__/theme.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { makeTheme, lightTheme, darkTheme } from '../theme';
+
+describe('theme', () => {
+  it('resolves palette channels into RN hsl() colors for the light scheme', () => {
+    const t = makeTheme('light');
+    expect(t.colors.primary).toBe('hsl(221.2, 83.2%, 53.3%)');
+    expect(t.colors.background).toBe('hsl(0, 0%, 100%)');
+  });
+
+  it('resolves the dark scheme', () => {
+    const t = makeTheme('dark');
+    expect(t.colors.background).toBe('hsl(222.2, 84%, 4.9%)');
+    expect(t.colors.primary).toBe('hsl(217.2, 91.2%, 59.8%)');
+  });
+
+  it('carries the shared shape/spacing/type scales', () => {
+    expect(lightTheme.radii.md).toBe(8);
+    expect(lightTheme.spacing.md).toBe(12);
+    expect(lightTheme.fontSizes.base).toBe(16);
+    expect(darkTheme.radii.md).toBe(8); // shape is scheme-independent
+  });
+});

package/src/__tests__/tokens.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import { palette, hsl, radii, spacing, fontSizes, fontWeights, durations } from '../tokens';
+
+describe('tokens', () => {
+  it('exposes HSL channel values that match packages/ui/theme/contract.css', () => {
+    // Single source of truth with the web CSS variables — keep these in sync.
+    expect(palette.light.primary).toBe('221.2 83.2% 53.3%');
+    expect(palette.light.background).toBe('0 0% 100%');
+    expect(palette.dark.background).toBe('222.2 84% 4.9%');
+    expect(palette.dark.primary).toBe('217.2 91.2% 59.8%');
+  });
+
+  it('hsl() converts channel strings into a React Native-parseable color', () => {
+    expect(hsl('221.2 83.2% 53.3%')).toBe('hsl(221.2, 83.2%, 53.3%)');
+    expect(hsl('0 0% 100%')).toBe('hsl(0, 0%, 100%)');
+  });
+
+  it('derives radii from contract.css (--radius: 0.5rem = 8px)', () => {
+    expect(radii.sm).toBe(4);
+    expect(radii.md).toBe(8);
+    expect(radii.lg).toBe(12);
+    expect(radii.xl).toBe(16);
+    expect(radii.full).toBe(9999);
+  });
+
+  it('provides numeric spacing / font scales for StyleSheet', () => {
+    expect(spacing.md).toBe(12);
+    expect(spacing.xs).toBeLessThan(spacing.xl);
+    expect(fontSizes.base).toBe(16);
+    expect(fontWeights.bold).toBe('700');
+    expect(durations.normal).toBe(200);
+  });
+});