@cyberkaidev/ui 0.1.0

package/README.md

@@ -0,0 +1,721 @@
+# @cyberkaidev/ui
+
+A themeable React Native component library. Expo-first, TypeScript-first.
+
+## Contents
+
+- [Installation](#installation)
+- [Setup](#setup)
+- [Theming](#theming)
+- [Components](#components)
+  - [Text & buttons](#text--buttons)
+  - [Inputs](#inputs)
+  - [Layout — `Scaffold`](#layout--scaffold)
+  - [Fixed bars — `AppBar`, `TabBar`, `SearchBar`](#fixed-bars--appbar-tabbar-searchbar)
+  - [Lists — `InforList`](#lists--inforlist)
+  - [Overlays — `Overlays`, `SlideModal`, `Toast`, `LoadingApp`](#overlays--overlays-slidemodal-toast-loadingapp)
+  - [Touch effects — `BounceEffect`, `RippleEffect`](#touch-effects--bounceeffect-rippleeffect)
+- [Icons](#icons)
+- [Hooks](#hooks)
+- [Global state](#global-state)
+- [Responsive helpers](#responsive-helpers)
+- [Exported types](#exported-types)
+- [TypeScript & config notes](#typescript--config-notes)
+
+---
+
+## Installation
+
+```sh
+yarn add @cyberkaidev/ui
+```
+
+### Peer dependencies
+
+Install these in the consuming app:
+
+```sh
+yarn expo install react-native-reanimated react-native-worklets react-native-safe-area-context \
+  @shopify/flash-list expo-symbols expo-blur expo-constants
+```
+
+- `react-native-reanimated` needs its Babel plugin — `babel-preset-expo` adds it automatically on
+  Expo SDK 54+. On bare React Native, add `react-native-worklets/plugin` (last) to `babel.config.js`.
+- `zustand` ships as a normal dependency — you don't install it.
+
+---
+
+## Setup
+
+Wrap the app **once** in `SafeAreaProvider` and `ThemeProvider`, and mount `Overlays` at the
+root.
+
+```tsx
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+import { ThemeProvider, Overlays, colors } from '@cyberkaidev/ui';
+
+export default function App() {
+  return (
+    <SafeAreaProvider>
+      <ThemeProvider colors={colors}>
+        <RootNavigator />
+        <Overlays loadingLabel="Loading…" />
+      </ThemeProvider>
+    </SafeAreaProvider>
+  );
+}
+```
+
+- **`ThemeProvider` is required, and its `colors` prop is required** — there is no default
+  palette. Pass the exported `colors` (a ready-made palette), spread from it, or provide your own
+  `ColorsType`. Any component rendered outside a `ThemeProvider` throws.
+- **`SafeAreaProvider` is required.** `Scaffold.ScrollView` / `Scaffold.FlashList`, `TabBar` and
+  `SlideModal` read safe-area insets and throw without it.
+- **`Overlays`** renders the app-wide `Toast` + `LoadingApp` (see [`Overlays`](#overlays)).
+  Mount it once at the root, inside `ThemeProvider`; trigger them from anywhere with `useToast` /
+  `useLoadingApp`. You can also mount `<Toast />` / `<LoadingApp />` individually if you need to.
+- **Fonts.** Components reference the `Inter-Regular` / `Inter-Medium` / `Inter-Bold` families.
+  Load them in the app (e.g. `expo-font`); without them, text falls back to the system font.
+
+---
+
+## Theming
+
+The theme has six token groups: `colors` (**required**, full palette) plus `fontSizes`,
+`iconSize`, `spaces`, `borderRadius`, `pageSpacing` (**optional**, partial — a missing key is
+inherited from the nearest parent provider, or from the built-in defaults). Providers nest.
+
+```tsx
+import { colors } from '@cyberkaidev/ui';
+
+<ThemeProvider
+  colors={{ ...colors, primary: '#ff8a00', background: '#0b0b0f' }} // full ColorsType
+  fontSizes={{ m: 20 }} // partial
+  spaces={{ vertical: { m: 24 } }} // deep-merged one level
+  borderRadius={{ radius_20: 8 }}
+>
+  <Screen />
+</ThemeProvider>
+```
+
+A **nested** `ThemeProvider` also needs a full `colors` (it replaces the palette); the other
+groups still merge over the parent.
+
+### Reading the theme
+
+| API | Returns | Use for |
+|---|---|---|
+| `useColors()` | `ColorsType` | color values inside a component (shortcut for `useTheme().colors`) |
+| `useTheme()` | `ThemeType` | any token group inside a component |
+| `useThemedStyles(makeStyles)` | `T` | a `StyleSheet` built from the resolved theme, memoized against it |
+
+```tsx
+import { StyleSheet } from 'react-native';
+import { useTheme, useThemedStyles, type ThemeType } from '@cyberkaidev/ui';
+
+function Card() {
+  const { colors } = useTheme();
+  const styles = useThemedStyles(makeStyles);
+  return <View style={[styles.card, { borderColor: colors.border }]} />;
+}
+
+// module-level factory — keep it out of the component so the memo stays stable
+function makeStyles(t: ThemeType) {
+  return StyleSheet.create({
+    card: {
+      padding: t.spaces.horizontal.m,
+      borderRadius: t.borderRadius.radius_15,
+      backgroundColor: t.colors.surface,
+    },
+  });
+}
+```
+
+### Exported token objects
+
+- **`colors`** — a ready-made `ColorsType` palette. Not a default: you must still pass a palette
+  to `ThemeProvider`, but this is a fine one to pass.
+- **`fontSizes`, `iconSize`, `spaces`, `borderRadius`, `pageSpacing`** — the built-in defaults for
+  those groups (`ThemeProvider` merges your partials on top). `defaultTokens` bundles all five.
+
+```ts
+export const colors = {
+  background: 'black',
+  background_60: 'rgba(0,0,0,0.6)',
+  on_surface: '#1A191E',
+  surface: '#100e12',
+  surface_90: 'rgba(16, 14, 18, 0.9)',
+  border: '#3D3B40',
+  text: '#f6f1ff',
+  primary: '#4284ff',
+  red: '#ff0004',
+  green: '#00ff2a',
+  amber: '#FFC107',
+  transparent: 'transparent',
+};
+
+// fontSizes / iconSize: keys are xxxl…xs (fontSizes) and xl…s (iconSize), values in dp
+// spaces: { horizontal: { xs…xxl }, vertical: { xs…xxl } } in dp
+// borderRadius: { radius_5, radius_10, radius_15, radius_20, radius_100 }
+// pageSpacing: { horizontal, top, bottom }
+```
+
+> A **dark/light** theme is the app's job: keep two `ColorsType` palettes and swap which one you
+> pass to `ThemeProvider`.
+
+---
+
+## Components
+
+Every component takes an optional `testID`. Every value shown as a token (`FontSizeType`,
+`ColorsType` keys, …) resolves against the active theme.
+
+### Text & buttons
+
+#### `Text`
+
+Themed text primitive. All copy comes from `children`.
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `children` | `ReactNode` | — | |
+| `weight` | `'regular' \| 'medium' \| 'bold'` | `'regular'` | → `Inter-*` family |
+| `size` | `FontSizeType` (`xs`…`xxxl`) | `'s'` | |
+| `color` | `string` | theme `text` | |
+| `numberOfLines` | `number` | — | truncation |
+| `textAlign` | `'left' \| 'center' \| 'right'` | — | |
+| `marginT` / `marginB` / `marginL` / `marginR` | `number` | `0` | dp |
+| `opacity` | `number` | — | |
+
+```tsx
+<Text weight="bold" size="l">Title</Text>
+<Text color="#8a8a8a" numberOfLines={2}>Subtitle that may wrap…</Text>
+```
+
+#### `Button`
+
+Base pressable. iOS gets opacity feedback; Android gets a touch ripple. Style it yourself — the
+other buttons wrap this.
+
+| Prop | Type | Notes |
+|---|---|---|
+| `children` | `ReactNode` | |
+| `onPress` / `onPressIn` / `onPressOut` | `() => void` | |
+| `disabled` | `boolean` | |
+| `style` | `StyleProp<ViewStyle>` | |
+| `hitSlop` | `Insets` | |
+| `rippleColor` / `rippleContainerBorderRadius` | `string` / `number` | Android only |
+
+#### `ShapedButton`
+
+Filled call-to-action with a loading state.
+
+| Prop | Type | Default |
+|---|---|---|
+| `children` | `ReactNode` | — |
+| `onPress` | `() => void` | — (required) |
+| `type` | `'primary' \| 'secondary'` | `'primary'` |
+| `size` | `FontSizeType` | — |
+| `disabled` | `boolean` | — |
+| `isLoading` | `boolean` | `false` |
+
+```tsx
+<ShapedButton isLoading={saving} onPress={save}>Save</ShapedButton>
+<ShapedButton type="secondary" onPress={cancel}>Cancel</ShapedButton>
+```
+
+#### `TextButton`
+
+Text-only button, no fill.
+
+| Prop | Type | Default |
+|---|---|---|
+| `children` | `ReactNode` | — |
+| `onPress` | `() => void` | — (required) |
+| `color` | `string` | theme `primary` |
+| `size` | `FontSizeType` | — |
+| `disabled` | `boolean` | `false` |
+
+#### `IconButton`
+
+Circular icon-only button with an optional "active" dot.
+
+| Prop | Type | Default |
+|---|---|---|
+| `icon` | `IconNameType` | — (required) |
+| `onPress` | `() => void` | — (required) |
+| `active` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+
+```tsx
+<IconButton icon="filter" active={hasFilters} onPress={openFilters} />
+```
+
+### Inputs
+
+#### `Chips`
+
+Horizontally scrolling row of selectable chips. Generic over the item key type.
+
+| Prop | Type | Default |
+|---|---|---|
+| `data` | `{ key: Item; label: string; disabled?: boolean; prefix?: ReactNode; scheme?: 'primary' \| 'surface' \| 'on_surface' }[]` | — (`scheme` defaults to `'surface'`) |
+| `onPress` | `(key: Item) => void` | — (omit → non-interactive) |
+| `marginT` / `marginB` | `number` | `0` |
+
+```tsx
+<Chips
+  data={[
+    { key: 'all', label: 'All' },
+    { key: 'new', label: 'New', scheme: 'primary' },
+    { key: 'used', label: 'Used', disabled: true },
+  ]}
+  onPress={setFilter}
+/>
+```
+
+#### `TextInput`
+
+Single-line field with a supporting message and error state.
+
+| Prop | Type | Default |
+|---|---|---|
+| `value` | `string` | — (required) |
+| `placeholder` | `string` | — (required) |
+| `onChangeText` | `(text: string) => void` | — (required) |
+| `supportingText` | `string` | — (shown in the error color) |
+| `isError` | `boolean` | `false` |
+| `onEnter` | `() => void` | fired on submit when the value is non-empty |
+| `onBlur` | `TextInputProps['onBlur']` | — |
+| `autoFocus` / `autoCapitalize` / `autoCorrect` / `autoComplete` / `inputMode` | passthrough to RN `TextInput` | — |
+
+```tsx
+<TextInput
+  value={name}
+  placeholder="Your name"
+  supportingText={name.length < 2 ? 'At least 2 characters' : undefined}
+  isError={touched && name.length < 2}
+  onChangeText={setName}
+  onEnter={submit}
+/>
+```
+
+#### `SegmentedButton`
+
+Single-select segmented button in the Material 3 **Expressive** style — a rounded track holding
+equal-width segments. The selected segment morphs into a filled pill with a springy pop, and every
+segment squishes on press. Controlled, generic over the segment `value` type. Best with 2–5 segments.
+
+| Prop | Type | Default |
+|---|---|---|
+| `segments` | `{ value: Value; label: string; icon?: IconNameType; disabled?: boolean }[]` | — (required) |
+| `value` | `Value` | — (required) the selected segment |
+| `onChange` | `(value: Value) => void` | — (required) |
+| `size` | `'s' \| 'm' \| 'l'` | `'m'` (track height scale) |
+| `disabled` | `boolean` | `false` (disables the whole control) |
+| `showSelectedCheck` | `boolean` | `true` (leading check on the selected segment) |
+
+Export: `SEGMENTED_BUTTON_HEIGHT` (the `'m'` track height).
+
+> The classic outlined-with-dividers Material 3 version is archived at
+> [`docs/checkpoints/segmented-button-m3.md`](docs/checkpoints/segmented-button-m3.md).
+
+```tsx
+const [range, setRange] = useState<'day' | 'week' | 'month'>('week');
+
+<SegmentedButton
+  value={range}
+  onChange={setRange}
+  segments={[
+    { value: 'day', label: 'Day' },
+    { value: 'week', label: 'Week' },
+    { value: 'month', label: 'Month' },
+  ]}
+/>;
+```
+
+### Layout — `Scaffold`
+
+Compound component for page structure.
+
+| Piece | Props | Purpose |
+|---|---|---|
+| `Scaffold.Body` | `children`, `surface?: boolean` | full-screen container; `surface` uses the elevated background |
+| `Scaffold.View` | `children`, `paddingHorizontal?`, `paddingTop?` | non-scrolling region with page insets |
+| `Scaffold.ScrollView` | `spaceTopBar`, `spaceBottomBar`, `children`, `paddingHorizontal?`, `paddingTop?`, `paddingBottom?`, `onScroll?` | scrolling region (reanimated) |
+| `Scaffold.FlashList<T>` | `spaceTopBar`, `spaceBottomBar`, all `@shopify/flash-list` props + `paddingHorizontal?`, `paddingTop?`, `paddingBottom?`, `onScroll?`, `drawDistance?` | virtualized list |
+
+`spaceTopBar` (`'large' | 'small' | 'none'`) and `spaceBottomBar` (`boolean`) are **required** on
+`Scaffold.ScrollView` and `Scaffold.FlashList` — they reserve the top/bottom insets for the
+screen's fixed bars so you never pass `APP_BAR_HEIGHT` / `useTabBarHeight()` by hand:
+
+| `spaceTopBar` | top inset |
+|---|---|
+| `'large'` | `APP_BAR_LARGE_HEIGHT` — for `<AppBar large />` |
+| `'small'` | `APP_BAR_HEIGHT` — for a fixed `<AppBar />` / `<SearchBar />` |
+| `'none'` | `pageSpacing.top` |
+
+`spaceBottomBar={true}` adds the `TabBar` height (incl. bottom safe-area) to the bottom inset;
+`false` keeps just `pageSpacing.bottom` + safe-area. The numeric `paddingTop` / `paddingBottom` props
+still win when passed. `onScroll` takes a reanimated scroll handler (see [`useAppBarScroll`](#hooks)).
+
+`Scaffold.View` is non-scrolling — its content never slides under the fixed bars — so it takes
+neither prop; pass an explicit `paddingTop` if a bar covers it.
+
+```tsx
+<Scaffold.Body>
+  <AppBar title="Collection" large scrollY={scrollY} />
+  <Scaffold.FlashList
+    spaceTopBar="large"
+    spaceBottomBar
+    data={cards}
+    keyExtractor={(c) => c.id}
+    renderItem={({ item }) => <Row card={item} />}
+    onScroll={scrollHandler}
+  />
+</Scaffold.Body>
+```
+
+### Fixed bars — `AppBar`, `TabBar`, `SearchBar`
+
+All three are `position: absolute` — render them as siblings of your scrollable content inside a
+`Scaffold.Body`. The content region reserves the matching inset via `spaceTopBar` / `spaceBottomBar`
+(see above); the height constants below are exported for manual layouts.
+
+#### `AppBar`
+
+| Prop | Type | Notes |
+|---|---|---|
+| `title` | `string` | — |
+| `enabledBack` | `boolean` | shows the back control |
+| `onBack` | `() => void` | called by the back control |
+| `large` | `boolean` | large title that collapses on scroll |
+| `trailing` | `AppBarTrailingType` | right-side action |
+| `scrollY` | `SharedValue<number>` | drives the large-title collapse |
+
+`AppBarTrailingType = { label?: string; icon?: IconNameType; tintColor?: ColorValue; hidden?: boolean; onPress: () => void }`
+
+Exports: `APP_BAR_HEIGHT`, `APP_BAR_LARGE_HEIGHT` (computed from the **default** `pageSpacing`).
+
+```tsx
+const { scrollY, scrollHandler } = useAppBarScroll();
+
+<AppBar
+  title="Settings"
+  enabledBack
+  onBack={router.back}
+  trailing={{ icon: 'check', onPress: save }}
+  scrollY={scrollY}
+/>
+```
+
+#### `TabBar`
+
+Data-driven — it knows nothing about routing.
+
+| Prop | Type | Default |
+|---|---|---|
+| `items` | `TabItemType[]` | — |
+| `visible` | `boolean` | `true` (fades out + disables touches when `false`) |
+
+`TabItemType = { key: string; icon: IconNameType; label: string; active: boolean; onPress: () => void }`
+
+Export: `useTabBarHeight()` — the height a screen should reserve at the bottom.
+
+```tsx
+<TabBar
+  items={[
+    { key: 'home', icon: 'folder', label: 'Home', active: route === 'home', onPress: () => go('home') },
+    { key: 'search', icon: 'search', label: 'Search', active: route === 'search', onPress: () => go('search') },
+  ]}
+  visible={!keyboardOpen}
+/>
+```
+
+#### `SearchBar`
+
+| Prop | Type | Notes |
+|---|---|---|
+| `placeholder` | `string` | — |
+| `onEnter` | `(query: string) => void` | fired with the trimmed query on submit |
+| `onBack` | `() => void` | back control |
+| `editable` | `boolean` | — |
+| `autoFocus` | `boolean` | — |
+
+Export: `SEARCH_BAR_HEIGHT`.
+
+### Lists — `InforList`
+
+#### `InforList`
+
+Grouped list with dividers between rows. Compound.
+
+| Piece | Props |
+|---|---|
+| `InforList.Container` | `children`, `marginT?`, `marginB?` |
+| `InforList.Content` | `children`, `onPress?` (pressable when provided) |
+| `InforList.Title` | `children`, `color?` |
+
+```tsx
+<InforList.Container>
+  <InforList.Content onPress={openProfile}>
+    <InforList.Title>Name</InforList.Title>
+    <InforList.Title color={colors.primary}>Ada</InforList.Title>
+  </InforList.Content>
+  <InforList.Content>
+    <InforList.Title>Role</InforList.Title>
+    <InforList.Title>Engineer</InforList.Title>
+  </InforList.Content>
+</InforList.Container>
+```
+
+### Overlays — `Overlays`, `SlideModal`, `Toast`, `LoadingApp`
+
+#### `Overlays`
+
+The app-wide overlays (`Toast` + `LoadingApp`) in one component. **Mount once at the root**,
+inside `ThemeProvider`, as a sibling of your navigator — they render above everything and are
+driven from anywhere via `useToast` / `useLoadingApp`.
+
+| Prop | Type | Notes |
+|---|---|---|
+| `loadingLabel` | `string` | forwarded to `LoadingApp`'s `label` |
+
+```tsx
+<ThemeProvider colors={colors}>
+  <RootNavigator />
+  <Overlays loadingLabel="Loading…" />
+</ThemeProvider>
+```
+
+Use `<Toast />` / `<LoadingApp />` directly only if you need them mounted separately.
+
+#### `SlideModal`
+
+Bottom sheet, controlled through a `ref`.
+
+| Prop | Type | Default |
+|---|---|---|
+| `children` | `ReactNode` | — |
+| `title` | `string` | — (required) |
+| `isLoading` | `boolean` | `false` (swaps content for a spinner, blocks drag-to-dismiss) |
+
+`ref` exposes `SlideModalRef = { show: () => void; hide: () => void }`.
+
+```tsx
+const modal = useRef<SlideModalRef>(null);
+
+<ShapedButton onPress={() => modal.current?.show()}>Open</ShapedButton>
+<SlideModal ref={modal} title="Edit">
+  <EditForm onDone={() => modal.current?.hide()} />
+</SlideModal>
+```
+
+#### `Toast`
+
+Transient centered notice, auto-hides after ~3s. Mounted via [`Overlays`](#overlays) (or on its
+own once at the root); triggered from anywhere via [`useToast`](#global-state).
+
+```tsx
+useToast().showToast({ message: 'Saved', variant: 'success' });
+// variant: 'error' | 'success' | 'info' (default 'info')
+```
+
+#### `LoadingApp`
+
+Blocking full-screen loading overlay. Mounted via [`Overlays`](#overlays) (or on its own once at
+the root); driven from anywhere via [`useLoadingApp`](#global-state).
+
+| Prop | Type | Notes |
+|---|---|---|
+| `label` | `string` | optional caption under the spinner |
+
+```tsx
+useLoadingApp().setLoadingVisible(true);
+```
+
+### Touch effects — `BounceEffect`, `RippleEffect`
+
+#### `BounceEffect`
+
+Wraps a child and plays a scale "bounce" on press, firing the callback on release.
+
+| Prop | Type |
+|---|---|
+| `onActionTrigger` | `() => void` |
+| `children` | `ReactNode` |
+| `style` | `PressableProps['style']` |
+
+#### `RippleEffect`
+
+Wraps a child and paints a touch ripple at the press point. Accepts all `Pressable` props plus:
+
+| Prop | Type | Default |
+|---|---|---|
+| `rippleColor` | `string` | theme `text` |
+| `rippleOpacity` | `number` | `0.3` |
+| `rippleDuration` | `number` | `400` |
+| `rippleSize` | `number` | `0` (auto) |
+| `rippleContainerBorderRadius` | `number` | `0` |
+| `rippleCentered` | `boolean` | `false` |
+| `rippleSequential` | `boolean` | `false` |
+| `rippleFades` | `boolean` | `true` |
+
+---
+
+## Icons
+
+`Icon` renders a curated set of UI glyphs via `expo-symbols` (`SymbolView`).
+
+| Prop | Type | Default |
+|---|---|---|
+| `name` | `IconNameType` | — (required) |
+| `color` | `string` | theme `primary` |
+| `size` | `number` (dp) | `iconSize.m` |
+
+```tsx
+import { Icon, iconSize } from '@cyberkaidev/ui';
+
+<Icon name="search" />
+<Icon name="check" color="#00ff2a" size={iconSize.l} />
+```
+
+**Available names:** `arrow_back`, `search`, `close`, `add`, `remove`, `edit`, `check`, `error`,
+`filter`, `settings`, `folder`, `question`.
+
+---
+
+## Hooks
+
+### `useAppBarScroll()`
+
+Wires a collapsing `AppBar` to a scroll region.
+
+```tsx
+const { scrollY, scrollHandler } = useAppBarScroll();
+
+<Scaffold.Body>
+  <AppBar title="Feed" large scrollY={scrollY} />
+  <Scaffold.ScrollView spaceTopBar="large" spaceBottomBar onScroll={scrollHandler}>
+    {/* … */}
+  </Scaffold.ScrollView>
+</Scaffold.Body>;
+```
+
+Returns `{ scrollY: SharedValue<number>, scrollHandler }`.
+
+### `usePressAndHoldRepeat({ onTrigger, disabled? })`
+
+Press-and-hold with acceleration. Fires `onTrigger` once on press, then repeatedly (speeding up)
+while held. Clamping is the caller's job.
+
+```tsx
+const { onPressIn, onPressOut } = usePressAndHoldRepeat({
+  onTrigger: () => setCount((c) => Math.min(c + 1, max)),
+  disabled: count >= max,
+});
+
+<Button onPressIn={onPressIn} onPressOut={onPressOut}>
+  <Icon name="add" />
+</Button>;
+```
+
+---
+
+## Global state
+
+Two [zustand](https://zustand.docs.pmnd.rs/) stores. Use the hook inside components, or
+`.getState()` anywhere.
+
+### `useToast`
+
+```ts
+useToast(): {
+  visible: boolean;
+  variant: 'error' | 'success' | 'info';
+  message: string;
+  showToast: (args: { message: string; variant?: 'error' | 'success' | 'info' }) => void;
+  hideToast: () => void;
+};
+```
+
+### `useLoadingApp`
+
+```ts
+useLoadingApp(): {
+  visible: boolean;
+  setLoadingVisible: (visible: boolean) => void;
+};
+```
+
+```ts
+// outside React (e.g. an API layer)
+import { useLoadingApp } from '@cyberkaidev/ui';
+
+async function withLoading<T>(fn: () => Promise<T>) {
+  useLoadingApp.getState().setLoadingVisible(true);
+  try {
+    return await fn();
+  } finally {
+    useLoadingApp.getState().setLoadingVisible(false);
+  }
+}
+```
+
+---
+
+## Responsive helpers
+
+```ts
+import { widthDP, heightDP } from '@cyberkaidev/ui';
+
+widthDP(50); // 50% of screen width, in dp, rounded to the nearest pixel
+heightDP(4.3); // 4.3% of screen height
+```
+
+The theme's spacing / font-size / icon-size scales are built from these. Screen size is read once
+at module load — values don't react to rotation.
+
+---
+
+## Exported types
+
+| Type | Shape |
+|---|---|
+| `FontSizeType` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl' \| 'xxl' \| 'xxxl'` |
+| `IconSizeType` | `'s' \| 'm' \| 'l' \| 'xl'` |
+| `FontWeightType` | `'regular' \| 'medium' \| 'bold'` |
+| `TextAlignType` | `'left' \| 'center' \| 'right'` |
+| `ToastVariantType` | `'error' \| 'success' \| 'info'` |
+| `ColorsType` | the 12-key palette shape |
+| `ThemeType` | `{ colors, fontSizes, iconSize, spaces, borderRadius, pageSpacing }` |
+| `FontSizesType` / `IconSizesType` / `SpacesType` / `SpaceScaleType` / `BorderRadiusType` / `PageSpacingType` | individual token-group shapes |
+| `ThemeTokensType` | `ThemeType` without `colors` (the shape of `defaultTokens`) |
+| `IconNameType` | union of the icon names above |
+| `SlideModalRef` | `{ show(): void; hide(): void }` |
+| `TabItemType` | tab-bar item shape |
+| `AppBarTrailingType` | app-bar trailing action shape |
+| `SpaceTopBarType` | `'large' \| 'small' \| 'none'` — `Scaffold` `spaceTopBar` |
+| `SegmentedButtonItemType<Value>` | segmented-button segment shape |
+| `SegmentedButtonSizeType` | `'s' \| 'm' \| 'l'` — `SegmentedButton` `size` |
+
+---
+
+## TypeScript & config notes
+
+- Ships ESM + `.d.ts` (built with `react-native-builder-bob`); single entry point
+  `@cyberkaidev/ui`.
+- No `moduleSuffixes` needed in the consumer's `tsconfig` — `Button` is a single file with a
+  `Platform.OS` branch.
+- `Text` referencing `Inter-*` is a soft dependency: unregistered fonts fall back to the system
+  font, no crash.
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+MIT