@ornikar/bumper 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.3.0](https://github.com/ornikar/kitt/compare/@ornikar/bumper@3.2.0...@ornikar/bumper@3.3.0) (2026-03-10)
+
+
+### Features
+
+* **bumper:** create typography migration process [no issue] ([#2914](https://github.com/ornikar/kitt/issues/2914)) ([61d576a](https://github.com/ornikar/kitt/commit/61d576ada6c95fc8bdb8bf5aa1a3ca63a1da9327))
+
+
+
 ## [3.2.0](https://github.com/ornikar/kitt/compare/@ornikar/bumper@3.1.0...@ornikar/bumper@3.2.0) (2026-03-09)
 
 

package/docs/migration/Typography.md

@@ -0,0 +1,484 @@
+# Typography → Typography Migration Guide
+
+> Source: `@ornikar/kitt-universal/Typography`
+> Target: `@ornikar/bumper/Typography`
+> Generated: 2026-03-05
+
+## Import Change
+
+```tsx
+// Before
+import { Typography } from '@ornikar/kitt-universal';
+import { TypographyLink } from '@ornikar/kitt-universal';
+import { TypographyIcon } from '@ornikar/kitt-universal';
+import { TypographyEmoji } from '@ornikar/kitt-universal';
+
+// After
+import { Typography } from '@ornikar/bumper';
+// TypographyLink → Typography.Link (compound component)
+// TypographyIcon → Typography.Icon (compound component)
+// TypographyEmoji has NO equivalent in bumper (requires manual review)
+```
+
+## Props Mapping
+
+### Typography.Text / Typography.Header\*
+
+| Source Prop                                   | Target Prop                                    | Transform                                              | Notes                                                                                |
+| --------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `base="body-m"`                               | `variant="body-m"`                             | Rename prop `base` → `variant`                         | When used as the only size prop (non-responsive)                                     |
+| `base` + `medium` + `large` etc.              | `variant` + `$md` + `$lg` etc.                 | See [Responsive Typography](#responsive-typography)    | Legacy breakpoint props become Tamagui media props                                   |
+| `type={{ base: "body-m", medium: "body-l" }}` | `variant="body-m" $md={{ variant: "body-l" }}` | Destructure `type` object into `variant` + media props | See [Responsive Typography](#responsive-typography)                                  |
+| `variant="regular"`                           | `weight="regular"`                             | Rename prop `variant` → `weight`                       | Only applies to body variants                                                        |
+| `variant="bold"`                              | `weight="bold"`                                | Rename prop `variant` → `weight`                       | Only applies to body variants                                                        |
+| `variant="semibold"`                          | Remove                                         | Remove prop                                            | Headings/labels are always semibold by default; body variants don't support semibold |
+| `color="black"`                               | `color="$content.base.hi"`                     | Map color value                                        | See [Color Mapping](#color-mapping)                                                  |
+| `accessibilityRole`                           | Remove                                         | Remove prop                                            | Sub-components handle roles automatically                                            |
+| `textAlign`                                   | `textAlign`                                    | Keep as-is                                             | Same API                                                                             |
+| `textTransform`                               | `textTransform`                                | Keep as-is                                             | content-caps auto-applies uppercase in both                                          |
+| `underline`                                   | `textDecorationLine="underline"`               | Convert boolean to style prop                          | —                                                                                    |
+| `strikeThrough`                               | `textDecorationLine="line-through"`            | Convert boolean to style prop                          | —                                                                                    |
+| `_web={{ ... }}`                              | `$platform-web={{ ... }}`                      | Rename platform prop                                   | Tamagui media query syntax                                                           |
+| `_ios={{ ... }}`                              | `$platform-native={{ ... }}`                   | Rename platform prop                                   | No iOS-specific prop; use platform-native                                            |
+| `_android={{ ... }}`                          | `$platform-native={{ ... }}`                   | Rename platform prop                                   | No Android-specific prop; use platform-native                                        |
+
+### TypographyLink → Typography.Link
+
+| Source Prop         | Target Prop        | Transform                        | Notes                                                  |
+| ------------------- | ------------------ | -------------------------------- | ------------------------------------------------------ |
+| `variant="bold"`    | `weight="bold"`    | Rename prop `variant` → `weight` | Required in source, same in target                     |
+| `variant="regular"` | `weight="regular"` | Rename prop `variant` → `weight` | —                                                      |
+| `href`              | Remove             | Remove prop                      | `href` is handled by the parent `ExternalLink` wrapper |
+| `hrefAttrs`         | Remove             | Remove prop                      | Handled by parent wrapper                              |
+| `disabled`          | `disabled`         | Keep as-is                       | Same API                                               |
+| `noUnderline`       | `noUnderline`      | Keep as-is                       | Same API                                               |
+| `onPress`           | `onPress`          | Keep as-is                       | Same API                                               |
+| `base="body-s"`     | `variant="body-s"` | Rename prop `base` → `variant`   | Same as Typography.Text                                |
+| `color`             | `color`            | Map color value                  | See [Color Mapping](#color-mapping)                    |
+
+### TypographyIcon → Typography.Icon
+
+| Source Prop | Target Prop | Transform       | Notes                                                                                 |
+| ----------- | ----------- | --------------- | ------------------------------------------------------------------------------------- |
+| `icon`      | `icon`      | Keep as-is      | Same API                                                                              |
+| `color`     | `color`     | Map color value | See [Color Mapping](#color-mapping); `"inherit"` value removed — omit prop to inherit |
+| `size`      | `size`      | Map to token    | Numeric values → `$icon.s` (16) / `$icon.m` (20) / `$icon.l` (24)                     |
+
+## Value Mappings
+
+### Variant (Type/Size) Mapping
+
+Most body variants are identical. Key renames:
+
+```
+heading-xxs  → heading-2xs
+heading-xs   → heading-xs     (unchanged)
+heading-s    → heading-s      (unchanged)
+heading-m    → heading-m      (unchanged)
+heading-l    → heading-l      (unchanged)
+heading-xl   → heading-xl     (unchanged)
+heading-xxl  → heading-2xl
+
+body-xs      → body-xs        (unchanged)
+body-s       → body-s         (unchanged)
+body-m       → body-m         (unchanged)
+body-l       → body-l         (unchanged)
+body-xl      → body-xl        (unchanged)
+
+label-small  → label-s
+label-medium → label-m
+label-large  → label-l
+
+content-caps-xs   → content-caps-xs    (unchanged)
+content-caps-s    → content-caps-s     (unchanged)
+content-caps-m    → content-caps-m     (unchanged)
+content-caps-l    → content-caps-l     (unchanged)
+content-caps-xl   → content-caps-xl    (unchanged)
+content-caps-xxl  → content-caps-2xl
+content-caps-xxxl → content-caps-3xl
+```
+
+### Weight Mapping
+
+Source `variant` prop → Target `weight` prop:
+
+```
+"regular"  → "regular"   (body only)
+"semibold" → remove prop (headings/labels enforce semibold automatically)
+"bold"     → "bold"      (body only)
+```
+
+**Important**: In bumper, `weight` is only meaningful for body variants. Heading, label, and content-caps variants have fixed weights. If the source has `variant="semibold"` on a heading, simply remove the prop.
+
+### Color Mapping
+
+#### Predefined Color Names (kitt-universal → bumper tokens)
+
+```
+"black"           → "$content.base.hi"
+"black-anthracite" → "$content.base.hi"
+"black-disabled"  → "$content.disabled"
+"black-light"     → "$content.base.mid"
+"white"           → "$content.base.onContrasted.hi"
+"white-light"     → "$content.base.onContrasted.mid"
+"primary"         → "$content.accent"
+"primary-light"   → "$content.accent"
+"accent"          → "$content.accent"
+"success"         → "$content.success"
+"danger"          → "$content.danger"
+"warning"         → "$content.warning"
+```
+
+#### Bumper Design Token Colors (already used in learner-apps)
+
+These are the most common colors found in the codebase. They need the `kitt.bumper.` prefix stripped and `$` prefix added:
+
+```
+"kitt.bumper.content.base.mid"             → "$content.base.mid"
+"kitt.bumper.content.base.low"             → "$content.base.low"
+"kitt.bumper.content.base.onContrasted.hi" → "$content.base.onContrasted.hi"
+"kitt.bumper.content.base.hi"              → "$content.base.hi"
+"kitt.bumper.content.accent"               → "$content.accent"
+"kitt.bumper.content.disabled"             → "$content.disabled"
+"kitt.bumper.content.success"              → "$content.success"
+"kitt.bumper.content.danger"               → "$content.danger"
+```
+
+**Rule**: If the color starts with `"kitt.bumper."`, strip the `"kitt.bumper."` prefix and prepend `"$"`.
+
+### Icon Size Mapping
+
+```
+16  → "$icon.s"
+20  → "$icon.m"
+24  → "$icon.l"
+```
+
+## Sub-Component Mapping
+
+| Source                       | Target               | Notes                                                                                         |
+| ---------------------------- | -------------------- | --------------------------------------------------------------------------------------------- |
+| `Typography.Text`            | `Typography.Text`    | Same name, props differ (see mapping)                                                         |
+| `Typography.Paragraph`       | `Typography.Text`    | **Removed** — use `Typography.Text` (add `role="paragraph"` manually if semantic role needed) |
+| `Typography.Header1`         | `Typography.Header1` | Same name, props differ                                                                       |
+| `Typography.Header2`         | `Typography.Header2` | Same name, props differ                                                                       |
+| `Typography.Header3`         | `Typography.Header3` | Same name, props differ                                                                       |
+| `Typography.Header4`         | `Typography.Header4` | Same name, props differ                                                                       |
+| `Typography.Header5`         | `Typography.Header5` | Same name, props differ                                                                       |
+| `Typography.Header6`         | `Typography.Header6` | Same name, props differ                                                                       |
+| `Typography.SetDefaultColor` | **None**             | **Removed** — no equivalent. Apply color directly to each child.                              |
+| `TypographyLink`             | `Typography.Link`    | Standalone import → compound component                                                        |
+| `TypographyIcon`             | `Typography.Icon`    | Standalone import → compound component                                                        |
+| `TypographyEmoji`            | **None**             | **Removed** — no equivalent in bumper. Requires manual review.                                |
+
+## Responsive Typography
+
+Source uses legacy breakpoint props or a `type` object. Target uses Tamagui media props.
+
+### Breakpoint Prop Mapping
+
+```
+base   → variant (the base/default value)
+small  → $sm={{ variant: "..." }}
+medium → $md={{ variant: "..." }}
+large  → $lg={{ variant: "..." }}
+wide   → $xl={{ variant: "..." }}
+```
+
+### Examples
+
+```tsx
+// Before — legacy shorthand props
+<Typography.Text base="body-s" medium="body-l">
+  Responsive text
+</Typography.Text>
+
+// After
+<Typography.Text variant="body-s" $md={{ variant: "body-l" }}>
+  Responsive text
+</Typography.Text>
+```
+
+```tsx
+// Before — type object
+<Typography.Text type={{ base: "body-s", medium: "body-m", large: "body-l" }}>
+  Responsive text
+</Typography.Text>
+
+// After
+<Typography.Text variant="body-s" $md={{ variant: "body-m" }} $lg={{ variant: "body-l" }}>
+  Responsive text
+</Typography.Text>
+```
+
+## Children & Composition
+
+Children patterns are largely identical between source and target. Both accept:
+
+- String/number children
+- Nested Typography components
+- Link, Icon components as children
+
+Key differences:
+
+- `TypographyEmoji` cannot be nested in bumper Typography (no equivalent)
+- `Typography.Paragraph` children should be moved to `Typography.Text`
+
+### Before/After: Bold Emphasis Pattern
+
+```tsx
+// Before
+<Typography.Text>
+  <FormattedMessage
+    defaultMessage="Text with <bold>emphasis</bold>"
+    values={{
+      bold: (chunks) => <Typography.Text variant="bold">{chunks}</Typography.Text>,
+    }}
+  />
+</Typography.Text>
+
+// After
+<Typography.Text>
+  <FormattedMessage
+    defaultMessage="Text with <bold>emphasis</bold>"
+    values={{
+      bold: (chunks) => <Typography.Text weight="bold">{chunks}</Typography.Text>,
+    }}
+  />
+</Typography.Text>
+```
+
+### Before/After: Link in FormattedMessage
+
+```tsx
+// Before
+<Typography.Text>
+  <FormattedMessage
+    defaultMessage="Click <link>here</link>"
+    values={{
+      link: (chunks) => (
+        <ExternalLink as={TypographyLink} variant="bold" href={url}>
+          {chunks}
+        </ExternalLink>
+      ),
+    }}
+  />
+</Typography.Text>
+
+// After
+<Typography.Text>
+  <FormattedMessage
+    defaultMessage="Click <link>here</link>"
+    values={{
+      link: (chunks) => (
+        <ExternalLink as={Typography.Link} weight="bold" href={url}>
+          {chunks}
+        </ExternalLink>
+      ),
+    }}
+  />
+</Typography.Text>
+```
+
+## Behavioral Differences
+
+1. **Default color changed**: Source defaults to `"black"`. Target defaults to `"$content.base.hi"` (equivalent, but token-based).
+2. **Weight prop name**: Source uses `variant` for weight. Target uses `weight`.
+3. **Size prop name**: Source uses `base`/`type` for size. Target uses `variant`.
+4. **No Typography.Paragraph**: Target has no Paragraph sub-component. Use Typography.Text.
+5. **No SetDefaultColor**: Target has no context provider for default colors. Colors must be set on each component individually.
+6. **No TypographyEmoji**: Target has no emoji sub-component.
+7. **Platform props syntax**: `_web`/`_ios`/`_android` → `$platform-web`/`$platform-native`.
+8. **Color inheritance**: Both support color inheritance via context, but the context APIs differ internally. Behavior is equivalent.
+9. **Responsive API**: Source uses breakpoint props (`base`, `medium`, `large`) or `type` object. Target uses Tamagui media props (`$sm`, `$md`, `$lg`).
+10. **TypographyLink/TypographyIcon**: Source exports as standalone components. Target uses compound component pattern (`Typography.Link`, `Typography.Icon`).
+11. **Icon color="inherit"**: Source supports `color="inherit"`. Target does not — simply omit the color prop to inherit from parent.
+
+## Edge Cases
+
+### Conditional props
+
+```tsx
+// Before — conditional variant (weight)
+<Typography.Text variant={isImportant ? "bold" : "regular"}>text</Typography.Text>
+
+// After — rename prop, keep expression
+<Typography.Text weight={isImportant ? "bold" : "regular"}>text</Typography.Text>
+```
+
+```tsx
+// Before — conditional base (size)
+<Typography.Text base={isLarge ? "body-l" : "body-s"}>text</Typography.Text>
+
+// After — rename prop, keep expression
+<Typography.Text variant={isLarge ? "body-l" : "body-s"}>text</Typography.Text>
+```
+
+### Spread props
+
+```tsx
+// Before
+<Typography.Text {...typographyProps} />;
+
+// After — rename spread keys
+const { base, variant, type, _web, _ios, _android, accessibilityRole, underline, strikeThrough, ...rest } =
+  typographyProps;
+<Typography.Text
+  variant={base}
+  weight={variant}
+  {...(underline && { textDecorationLine: 'underline' })}
+  {...(strikeThrough && { textDecorationLine: 'line-through' })}
+  {...(_web && { '$platform-web': _web })}
+  {...rest}
+/>;
+```
+
+**Note**: Spread props require manual review as the prop names are ambiguous without runtime context.
+
+### Typography.Paragraph migration
+
+```tsx
+// Before
+<Typography.Paragraph base="body-m">
+  Paragraph content
+</Typography.Paragraph>
+
+// After — no semantic paragraph in bumper
+<Typography.Text variant="body-m">
+  Paragraph content
+</Typography.Text>
+```
+
+If semantic `<p>` element is required, add `tag="p"` if supported by Tamagui, or wrap in a `<p>` element.
+
+### Typography.SetDefaultColor migration
+
+```tsx
+// Before
+<Typography.SetDefaultColor value="primary">
+  <Typography.Text base="body-m">Inherits primary</Typography.Text>
+  <Typography.Text base="body-s">Also inherits primary</Typography.Text>
+</Typography.SetDefaultColor>
+
+// After — apply color to each child
+<Typography.Text variant="body-m" color="$content.accent">Explicit color</Typography.Text>
+<Typography.Text variant="body-s" color="$content.accent">Explicit color</Typography.Text>
+```
+
+### TypographyEmoji migration
+
+```tsx
+// Before
+<Typography.Text base="body-m">
+  Text with <TypographyEmoji emoji="💸" base="heading-m" /> emoji
+</Typography.Text>
+
+// After — NO equivalent in bumper. Use inline text emoji or custom component.
+<Typography.Text variant="body-m">
+  Text with 💸 emoji
+</Typography.Text>
+```
+
+**Requires manual review** — TypographyEmoji provides consistent cross-platform rendering via Twemoji. A plain emoji character may render differently across platforms.
+
+### Wrapper / re-export migration
+
+#### InternalTypographyLink
+
+```tsx
+// Before — wrapper imports TypographyLink
+import { TypographyLink } from '@ornikar/kitt-universal';
+
+// After — wrapper should import Typography.Link
+import { Typography } from '@ornikar/bumper';
+// Use Typography.Link instead of TypographyLink
+```
+
+The `InternalTypographyLink` wrapper in `learner-apps-shared` must be updated to use `Typography.Link` from bumper. Its internal `variant` prop should be renamed to `weight`.
+
+#### Price component
+
+The `Price` component wraps `Typography.Text` and uses `TypographyTextProps`. Update:
+
+- Import source: `@ornikar/kitt-universal` → `@ornikar/bumper`
+- Prop type references to match bumper's types
+- Internal `base` → `variant`, `variant` → `weight` mappings
+
+#### getTypographyColor helper
+
+This helper maps semantic states to Typography colors. Update returned color values from kitt-universal predefined colors to bumper `$content.*` tokens.
+
+### Styled / extended components
+
+Source components extended via NativeBase `styled()` should be migrated to Tamagui's `styled()`:
+
+```tsx
+// Before
+import { styled } from 'native-base';
+const StyledText = styled(Typography.Text, { ... });
+
+// After
+import { styled } from 'tamagui';
+const StyledText = styled(Typography.Text, { ... });
+```
+
+Props passed to styled components must follow the same prop mapping rules.
+
+### Dynamic color from helper functions
+
+```tsx
+// Before
+const color = getTypographyColor(state); // returns 'primary', 'danger', etc.
+<Typography.Text color={color}>text</Typography.Text>;
+
+// After — update the helper to return bumper tokens
+const color = getTypographyColor(state); // should return '$content.accent', '$content.danger', etc.
+<Typography.Text color={color}>text</Typography.Text>;
+```
+
+### TypographyIcon with color="inherit"
+
+```tsx
+// Before
+<TypographyIcon color="inherit" icon={<CheckIcon />} />
+
+// After — omit color prop to inherit
+<Typography.Icon icon={<CheckIcon />} />
+```
+
+## Migration Rules (machine-readable)
+
+1. **Update import**: Replace `import { Typography } from '@ornikar/kitt-universal'` with `import { Typography } from '@ornikar/bumper'`
+2. **Update import**: Replace `import { TypographyLink } from '@ornikar/kitt-universal'` — use `Typography.Link` from `@ornikar/bumper` instead
+3. **Update import**: Replace `import { TypographyIcon } from '@ornikar/kitt-universal'` — use `Typography.Icon` from `@ornikar/bumper` instead
+4. **Update import**: Replace `import { TypographyEmoji } from '@ornikar/kitt-universal'` — flag for manual review (no bumper equivalent)
+5. **Rename component**: `TypographyLink` → `Typography.Link`
+6. **Rename component**: `TypographyIcon` → `Typography.Icon`
+7. **Rename component**: `Typography.Paragraph` → `Typography.Text`
+8. **Remove component**: `Typography.SetDefaultColor` — apply color directly to each child
+9. **Rename prop**: `base` → `variant` (when used as size/type)
+10. **Rename prop**: `variant` → `weight` (when used as font weight)
+11. **Remove prop**: `accessibilityRole` (sub-components handle this)
+12. **Convert boolean**: `underline` → `textDecorationLine="underline"`
+13. **Convert boolean**: `strikeThrough` → `textDecorationLine="line-through"`
+14. **Rename platform prop**: `_web={{ ... }}` → `$platform-web={{ ... }}`
+15. **Rename platform prop**: `_ios={{ ... }}` → `$platform-native={{ ... }}`
+16. **Rename platform prop**: `_android={{ ... }}` → `$platform-native={{ ... }}`
+17. **Convert responsive**: `type={{ base: X, small: Y, medium: Z, large: W, wide: V }}` → `variant={X} $sm={{ variant: Y }} $md={{ variant: Z }} $lg={{ variant: W }} $xl={{ variant: V }}`
+18. **Convert responsive shorthand**: `small="X"` → `$sm={{ variant: "X" }}`; `medium="X"` → `$md={{ variant: "X" }}`; `large="X"` → `$lg={{ variant: "X" }}`; `wide="X"` → `$xl={{ variant: "X" }}`
+19. **Map variant values**: Apply value mapping table (e.g. `heading-xxs` → `heading-2xs`, `label-small` → `label-s`)
+20. **Map color values**: Apply color mapping table (e.g. `"black"` → `"$content.base.hi"`, `"kitt.bumper.X"` → `"$X"`)
+21. **Remove weight on headings/labels**: If target `variant` is a heading or label type, remove the `weight` prop (it's fixed)
+22. **Icon color="inherit"**: Remove `color="inherit"` prop (omitting color achieves inheritance)
+23. **Icon size**: Map numeric sizes to tokens (`16` → `"$icon.s"`, `20` → `"$icon.m"`, `24` → `"$icon.l"`)
+
+## Not Migratable (requires human review)
+
+- **TypographyEmoji usage** — No bumper equivalent. ~low frequency but renders differently as plain emoji vs Twemoji.
+- **Typography.SetDefaultColor with many children** — Each child needs explicit color. Large trees may need careful review to ensure no child is missed.
+- **Spread props (`{...typographyProps}`)** — Prop names change (`base` → `variant`, `variant` → `weight`), cannot be renamed in spread without runtime knowledge of the shape.
+- **Dynamic type/variant expressions** — `base={someVariable}` where the variable may contain values that need renaming (e.g. `heading-xxs` → `heading-2xs`). Requires runtime mapping function or audit of variable sources.
+- **Custom color strings (hex/rgb)** — Source accepts arbitrary CSS color strings. Target uses Tamagui ColorTokens. Arbitrary hex values should be mapped to the nearest token.
+- **NativeBase styled() extensions** — Must be migrated to Tamagui `styled()` with updated prop names.
+- **Type imports** — `TypographyTextProps`, `TypographyHeadingProps`, `TypographyColor`, `ExtendedTypographyColor` type imports must be updated to bumper equivalents.
+- **Platform-specific overrides merging** — Source has separate `_ios` and `_android` props. Target only has `$platform-native`. If different iOS/Android overrides were used, they need reconciliation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ornikar/bumper",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "license": "MIT",
   "repository": {
     "directory": "@ornikar/bumper",
@@ -24,7 +24,8 @@
       "storybook"
     ],
     "extraEntries": [
-      "./src/tamagui.config.ts"
+      "./src/tamagui.config.ts",
+      "./docs/**/*.md"
     ]
   },
   "dependencies": {
@@ -118,7 +119,8 @@
       }
     },
     "./package.json": "./package.json",
-    "./src/tamagui.config.ts": "./src/tamagui.config.ts"
+    "./src/tamagui.config.ts": "./src/tamagui.config.ts",
+    "./docs/**/*.md": "./docs/**/*.md"
   },
   "browser": {
     ".": "./dist/index.es",

package/src/Bumper.mdx

@@ -0,0 +1,36 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Bumper/Overview" />
+
+# Bumper
+
+Next-generation Ornikar design system built on Tamagui. Semantic token system for
+spacing, color, radius, and typography.
+
+[Back to Introduction](?path=/docs/docs-introduction--docs)
+
+## Core
+
+### Primitives
+
+- [View](?path=/docs/bumper-core-primitives-view--docs) — Base layout box. Backgrounds, borders, spacing, flex.
+- [Pressable](?path=/docs/bumper-core-primitives-pressable--docs) — Polymorphic interactive primitive with hover/press styles.
+- [Stack](?path=/docs/bumper-core-primitives-stack--docs) — Flex container. Includes HStack and VStack presets.
+- [Center](?path=/docs/bumper-core-primitives-center--docs) — View with centered content.
+- [Image](?path=/docs/bumper-core-primitives-image--docs) — Image component from Tamagui.
+- [ScrollView](?path=/docs/bumper-core-primitives-scrollview--docs) — Scrollable container.
+
+## Content
+
+- [Typography](?path=/docs/bumper-content-typography--docs) — Foundational text component. All typographic variants.
+- [TypographyIcon](?path=/docs/bumper-content-typographyicon--docs) — Inline icon within Typography context. Inherits color.
+- [TypographyLink](?path=/docs/bumper-content-typographylink--docs) — Interactive link with underline and disabled states.
+- [Icon](?path=/docs/bumper-content-icon--docs) — Standalone icon wrapper. Color and size via tokens.
+
+## Data Displays
+
+- [Badge](?path=/docs/bumper-data-displays-badge--docs) — Numeric count or dot indicator.
+
+## Loading
+
+- [Loader](?path=/docs/bumper-loading-loader--docs) — Animated circular spinner.

package/src/system/content/icon/Icon.mdx

@@ -0,0 +1,31 @@
+import { Meta, Title, Subtitle, Primary, Controls, Canvas } from '@storybook/blocks';
+import * as IconStories from './Icon.stories';
+import * as IconFeatures from './Icon.features.stories';
+
+<Meta of={IconStories} />
+<Title />
+<Subtitle />
+
+<Primary />
+<Controls />
+
+## Overview
+
+`Icon` is a standalone icon wrapper that applies color and size to an icon element. Pass any icon from `@ornikar/kitt-icons/ornicons` via the `icon` prop. Defaults to `$icon.m` (20px) and `$content.base.hi` color. For icons inside `Typography.Text`, use `Typography.Icon` instead — it inherits color from the typography context.
+
+## Sizes
+
+Use `size` to control the icon dimensions: `$icon.s` (16px), `$icon.m` (20px), or `$icon.l` (24px).
+
+<Canvas of={IconFeatures.Sizes} />
+
+## Colors
+
+Use `color` with semantic `$content.*` tokens. The icon element receives the resolved color via `cloneElement`.
+
+<Canvas of={IconFeatures.Colors} />
+
+## Related
+
+- [TypographyIcon](?path=/docs/bumper-content-typographyicon--docs)
+- [Typography](?path=/docs/bumper-content-typography--docs)

package/src/system/content/icon/Icon.stories.tsx

@@ -6,7 +6,6 @@ import { Icon } from './Icon';
 const meta: Meta<typeof Icon> = {
   title: 'Bumper/Content/Icon',
   component: Icon,
-  tags: ['autodocs'],
   argTypes: {
     size: {
       control: 'select',

package/src/system/content/typography/Typography.mdx

@@ -0,0 +1,68 @@
+import { Meta, Title, Subtitle, Primary, Controls, Canvas } from '@storybook/blocks';
+import * as TypographyStories from './Typography.stories';
+import * as TypographyFeatures from './Typography.features.stories';
+
+<Meta of={TypographyStories} />
+<Title />
+<Subtitle />
+
+<Primary />
+<Controls />
+
+## Overview
+
+`Typography.Text` is the foundational text component in Bumper. It supports four variant families — heading, body, label, and content-caps — each with a fixed font weight. Defaults to `body-m` / `regular`. Use `color` with `$content.*` tokens and `variant` to control size and style.
+
+## Default values
+
+When no props are specified, `Typography.Text` renders as `body-m` with `regular` weight and `$content.base.hi` color.
+
+<Canvas of={TypographyFeatures.DefaultValues} />
+
+## Heading variants
+
+Heading variants range from `heading-2xl` down to `heading-2xs`. All headings use `semibold` weight. Use these for titles and section headers.
+
+<Canvas of={TypographyFeatures.HeadingVariants} />
+
+## Body variants
+
+Body variants range from `body-xl` to `body-xs`. They support both `regular` and `bold` weights. Use `body-m` as the default for paragraph text.
+
+<Canvas of={TypographyFeatures.BodyVariants} />
+
+### Bold body
+
+Set `weight="bold"` on body variants to emphasize important text within paragraphs.
+
+<Canvas of={TypographyFeatures.BodyVariantsBold} />
+
+## Label variants
+
+Label variants (`label-l`, `label-m`, `label-s`) use `semibold` weight. Use them for form labels, button text, and short UI copy that needs emphasis.
+
+<Canvas of={TypographyFeatures.LabelVariants} />
+
+## Content caps variants
+
+Content caps variants (`content-caps-3xl` to `content-caps-xs`) use the GTStandardNarrow font with automatic `uppercase` transformation and `bold` weight. Use them for tags, badges, and short categorical labels.
+
+<Canvas of={TypographyFeatures.ContentCapsVariants} />
+
+## Semantic header components
+
+Use `Typography.Header1` through `Typography.Header6` for semantically correct headings. These render with the `heading` ARIA role and the appropriate `aria-level`.
+
+<Canvas of={TypographyFeatures.HeaderComponents} />
+
+## Context inheritance
+
+Nested `Typography.Text` components inherit `variant`, `weight`, and `color` from their parent. Child components can override any inherited value by setting the prop explicitly.
+
+<Canvas of={TypographyFeatures.ContextInheritance} />
+
+## Related
+
+- [TypographyIcon](?path=/docs/bumper-content-typographyicon--docs)
+- [TypographyLink](?path=/docs/bumper-content-typographylink--docs)
+- [Icon](?path=/docs/bumper-content-icon--docs)

package/src/system/content/typography/Typography.stories.tsx

@@ -6,7 +6,6 @@ import { Typography } from '.';
 const meta: Meta<Extract<TypographyTextProps, BodyProps>> = {
   title: 'Bumper/Content/Typography',
   component: Typography.Text,
-  tags: ['autodocs'],
   argTypes: {
     variant: {
       control: 'select',

package/src/system/content/typography/TypographyIcon.mdx

@@ -0,0 +1,50 @@
+import { Meta, Title, Subtitle, Primary, Controls, Canvas } from '@storybook/blocks';
+import * as TypographyIconStories from './TypographyIcon.stories';
+import * as TypographyIconFeatures from './TypographyIcon.features.stories';
+
+<Meta of={TypographyIconStories} />
+<Title />
+<Subtitle />
+
+<Primary />
+<Controls />
+
+## Overview
+
+`Typography.Icon` renders an icon inline within a `Typography.Text` block. It automatically inherits the parent's `color` from the typography context. Use it when placing icons alongside text — it ensures the icon stays color-consistent with surrounding copy.
+
+## Explicit color
+
+Pass `color` directly to override the inherited value. Use semantic `$content.*` tokens to convey meaning — `$content.accent`, `$content.success`, `$content.warning`, `$content.danger`.
+
+<Canvas of={TypographyIconFeatures.WithExplicitColor} />
+
+## Color inheritance from Typography
+
+When `color` is omitted, `Typography.Icon` reads the nearest parent `Typography.Text` color from context. This keeps icon and text colors in sync automatically.
+
+<Canvas of={TypographyIconFeatures.InheritFromTypography} />
+
+## Overriding inherited color
+
+Set `color` explicitly on `Typography.Icon` to break from the parent's color — useful when an icon should convey a different status than its surrounding text.
+
+<Canvas of={TypographyIconFeatures.OverrideInheritedColor} />
+
+## Sizes
+
+Use `size` to match the icon to its typographic context: `$icon.s` (16px) for small text, `$icon.m` (20px) for body text, `$icon.l` (24px) for headings.
+
+<Canvas of={TypographyIconFeatures.DifferentSizes} />
+
+## Nested inheritance
+
+In deeply nested `Typography.Text` trees, icons inherit color from their closest ancestor. A child `Typography.Text` that overrides color will also change the color of its nested icons.
+
+<Canvas of={TypographyIconFeatures.NestedTypographyInheritance} />
+
+## Related
+
+- [Typography](?path=/docs/bumper-content-typography--docs)
+- [Icon](?path=/docs/bumper-content-icon--docs)
+- [TypographyLink](?path=/docs/bumper-content-typographylink--docs)

package/src/system/content/typography/TypographyIcon.stories.tsx

@@ -6,7 +6,6 @@ import { TypographyIcon } from './TypographyIcon';
 const meta: Meta<typeof TypographyIcon> = {
   title: 'Bumper/Content/TypographyIcon',
   component: TypographyIcon,
-  tags: ['autodocs'],
   argTypes: {
     icon: {
       control: false,

package/src/system/content/typography/TypographyLink.mdx

@@ -0,0 +1,49 @@
+import { Meta, Title, Subtitle, Primary, Controls, Canvas } from '@storybook/blocks';
+import * as TypographyLinkStories from './TypographyLink.stories';
+import * as TypographyLinkFeatures from './TypographyLink.features.stories';
+
+<Meta of={TypographyLinkStories} />
+<Title />
+<Subtitle />
+
+<Primary />
+<Controls />
+
+## Overview
+
+`Typography.Link` is an interactive text component with `role="link"`. It renders underlined by default and removes the underline on hover. It inherits all typography props (`variant`, `weight`, `color`) from `Typography.Text`. Use it for inline navigational links within text blocks.
+
+## Enabled state
+
+By default, `disabled` is `false` — the link shows a pointer cursor and responds to `onPress`.
+
+<Canvas of={TypographyLinkFeatures.DisabledFalse} />
+
+## Disabled state
+
+Set `disabled` to disable the link. The cursor changes to `not-allowed`, `onPress` is removed, and the text color switches to `$content.disabled`.
+
+<Canvas of={TypographyLinkFeatures.DisabledTrue} />
+
+## With underline (default)
+
+By default, `noUnderline` is `false` — the link renders with an underline that disappears on hover.
+
+<Canvas of={TypographyLinkFeatures.NoUnderlineFalse} />
+
+## Without underline
+
+Set `noUnderline` to remove the underline entirely. Use this for links where the context already makes the interactive nature obvious.
+
+<Canvas of={TypographyLinkFeatures.NoUnderlineTrue} />
+
+## Hover state
+
+On hover, the underline is removed. When `noUnderline` is already set or the link is `disabled`, hover has no visible effect.
+
+<Canvas of={TypographyLinkFeatures.StateHover} />
+
+## Related
+
+- [Typography](?path=/docs/bumper-content-typography--docs)
+- [TypographyIcon](?path=/docs/bumper-content-typographyicon--docs)

package/src/system/content/typography/TypographyLink.stories.tsx

@@ -8,7 +8,6 @@ import { TypographyLink } from './TypographyLink';
 const meta: Meta<Extract<TypographyLinkProps, BodyProps>> = {
   title: 'Bumper/Content/TypographyLink',
   component: TypographyLink,
-  tags: ['autodocs'],
   argTypes: {
     variant: {
       control: 'select',

package/src/system/core/primitives/Center.mdx

@@ -0,0 +1,31 @@
+import { Meta, Title, Subtitle, Primary, Controls, Canvas } from '@storybook/blocks';
+import * as CenterStories from './Center.stories';
+import * as CenterFeatures from './Center.features.stories';
+
+<Meta of={CenterStories} />
+<Title />
+<Subtitle />
+
+<Primary />
+<Controls />
+
+## Overview
+
+`Center` is a styled `View` with `justifyContent: center` and `alignItems: center` baked in. Use it whenever you need to center content within a fixed-size container — icons, avatars, placeholder blocks, or any content that should sit in the middle of its parent.
+
+## Centering text
+
+Give `Center` explicit `width` and `height` to create a fixed container. Text and other children are automatically centered both horizontally and vertically.
+
+<Canvas of={CenterFeatures.CenteringText} />
+
+## Circular centering
+
+Combine `Center` with `borderRadius="$radius.circle"` and equal `width`/`height` to create circular containers — useful for avatars, step indicators, or numbered badges.
+
+<Canvas of={CenterFeatures.CircularCentering} />
+
+## Related
+
+- [View](?path=/docs/bumper-core-primitives-view--docs)
+- [Stack](?path=/docs/bumper-core-primitives-stack--docs)

package/src/system/core/primitives/Center.stories.tsx

@@ -6,7 +6,6 @@ import { Center } from './Center';
 const meta: Meta<typeof Center> = {
   title: 'Bumper/Core/Primitives/Center',
   component: Center,
-  tags: ['autodocs'],
   argTypes: {
     backgroundColor: backgroundColorArgType,
     padding: spaceArgType,

package/src/system/core/primitives/Image/Image.mdx

@@ -0,0 +1,15 @@
+import { Meta, Title, Subtitle, Primary, Controls } from '@storybook/blocks';
+import * as ImageStories from './Image.stories';
+
+<Meta of={ImageStories} />
+<Title />
+<Subtitle />
+
+<Primary />
+<Controls />
+
+## Overview
+
+`Image` is Tamagui's image primitive, re-exported from `@tamagui/image`. Use it to display images with Bumper's `$size.*` tokens for `width` and `height`. Set `resizeMode` to control how the image fills its container: `"contain"` preserves aspect ratio within bounds, `"cover"` fills the container and crops, `"stretch"` distorts to fit, and `"center"` keeps the original size.
+
+Pass the image source via the `source` prop as `{ uri: string }` for remote images or a require call for local assets.

package/src/system/core/primitives/Image/Image.stories.tsx

@@ -5,7 +5,6 @@ import { Image } from './Image';
 const meta: Meta<typeof Image> = {
   title: 'Bumper/Core/Primitives/Image',
   component: Image,
-  tags: ['autodocs'],
   argTypes: {
     source: {
       table: { disable: true },

package/src/system/core/primitives/Pressable.mdx

@@ -0,0 +1,37 @@
+import { Meta, Title, Subtitle, Primary, Controls, Canvas } from '@storybook/blocks';
+import * as PressableStories from './Pressable.stories';
+import * as PressableFeatures from './Pressable.features.stories';
+
+<Meta of={PressableStories} />
+<Title />
+<Subtitle />
+
+<Primary />
+<Controls />
+
+## Overview
+
+`Pressable` is a polymorphic interactive primitive that renders as a button with `cursor: pointer` and `role="button"`. Use it to make any layout element tappable — it wraps a Tamagui component (defaults to `View`) and adds press/hover interaction styles.
+
+## Hover effects
+
+Use `hoverStyle` to apply visual feedback on hover. Common patterns include changing `backgroundColor`, scaling up with `scale`, or reducing `opacity`.
+
+<Canvas of={PressableFeatures.HoverEffects} />
+
+## Press effects
+
+Use `pressStyle` to give immediate tactile feedback on press. Combine `scale`, `backgroundColor`, `opacity`, and `rotateZ` for richer interactions.
+
+<Canvas of={PressableFeatures.PressEffects} />
+
+## Polymorphic rendering
+
+Pass the `as` prop to render `Pressable` as a different Tamagui component. Use `as={HStack}` or `as={VStack}` when you need a pressable flex container with a specific direction.
+
+<Canvas of={PressableFeatures.PolymorphicAs} />
+
+## Related
+
+- [View](?path=/docs/bumper-core-primitives-view--docs)
+- [Stack](?path=/docs/bumper-core-primitives-stack--docs)

package/src/system/core/primitives/Pressable.stories.tsx

@@ -7,7 +7,6 @@ import { Pressable } from './Pressable';
 const meta: Meta<typeof Pressable> = {
   title: 'Bumper/Core/Primitives/Pressable',
   component: Pressable,
-  tags: ['autodocs'],
   argTypes: {
     backgroundColor: backgroundColorArgType,
     padding: spaceArgType,

package/src/system/core/primitives/ScrollView/ScrollView.mdx

@@ -0,0 +1,36 @@
+import { Meta, Title, Subtitle, Primary, Controls, Canvas } from '@storybook/blocks';
+import * as ScrollViewStories from './ScrollView.stories';
+import * as ScrollViewFeatures from './ScrollView.features.stories';
+
+<Meta of={ScrollViewStories} />
+<Title />
+<Subtitle />
+
+<Primary />
+<Controls />
+
+## Overview
+
+`ScrollView` is Tamagui's scrollable container, re-exported from `@tamagui/scroll-view`. Use it when content exceeds the available space and needs to be scrollable. Give it a fixed `height` (and optionally `width`) so the scroll area has clear bounds.
+
+## Horizontal scrolling
+
+Set `horizontal` to arrange and scroll content on the horizontal axis. Useful for carousels, tag lists, or any horizontally overflowing content.
+
+<Canvas of={ScrollViewFeatures.HorizontalScroll} />
+
+## Hidden scroll indicators
+
+Set `showsVerticalScrollIndicator={false}` or `showsHorizontalScrollIndicator={false}` to hide native scrollbars. Use this for cleaner UIs where the scroll affordance is implicit.
+
+<Canvas of={ScrollViewFeatures.HiddenIndicators} />
+
+## Disabled scrolling
+
+Set `scrollEnabled={false}` to prevent scrolling entirely. Use this when content should be visible but not interactable — for example, in a preview or locked state.
+
+<Canvas of={ScrollViewFeatures.ScrollDisabled} />
+
+## Related
+
+- [View](?path=/docs/bumper-core-primitives-view--docs)

package/src/system/core/primitives/ScrollView/ScrollView.stories.tsx

@@ -7,7 +7,6 @@ import { ScrollView } from './ScrollView';
 const meta: Meta<typeof ScrollView> = {
   title: 'Bumper/Core/Primitives/ScrollView',
   component: ScrollView,
-  tags: ['autodocs'],
   argTypes: {
     horizontal: {
       control: 'boolean',

package/src/system/core/primitives/Stack.mdx

@@ -0,0 +1,55 @@
+import { Meta, Title, Subtitle, Primary, Controls, Canvas } from '@storybook/blocks';
+import * as StackStories from './Stack.stories';
+import * as StackFeatures from './Stack.features.stories';
+
+<Meta of={StackStories} />
+<Title />
+<Subtitle />
+
+<Primary />
+<Controls />
+
+## Overview
+
+`Stack` is the base flex container from Tamagui. Bumper also exports `HStack` (row direction) and `VStack` (column direction) as convenient presets. Use these instead of setting `flexDirection` manually on `View` when building layouts.
+
+## VStack
+
+Use `VStack` to arrange children vertically. Set `gap` with `$space.*` tokens to control spacing between items.
+
+<Canvas of={StackFeatures.VStackBasic} />
+
+## HStack
+
+Use `HStack` to arrange children horizontally. Same API as `VStack` but with `flexDirection: row`.
+
+<Canvas of={StackFeatures.HStackBasic} />
+
+## Wrapping
+
+Set `flexWrap="wrap"` on `HStack` with a constrained `maxWidth` to create flowing layouts where items wrap to the next line.
+
+<Canvas of={StackFeatures.FlexWrap} />
+
+## Nested stacks
+
+Combine `VStack` and `HStack` to build complex layouts. Nest stacks to create sections with mixed directions.
+
+<Canvas of={StackFeatures.NestedStacks} />
+
+## Flex grow
+
+Use `flexGrow` on children to distribute available space. Fixed-width children sit alongside flexible ones.
+
+<Canvas of={StackFeatures.FlexGrowExample} />
+
+## Grid-like layout
+
+Combine nested `HStack` rows inside a `VStack` with `flexGrow={1}` on each cell to build uniform grid layouts.
+
+<Canvas of={StackFeatures.GridLikeLayout} />
+
+## Related
+
+- [View](?path=/docs/bumper-core-primitives-view--docs)
+- [Center](?path=/docs/bumper-core-primitives-center--docs)

package/src/system/core/primitives/Stack.stories.tsx

@@ -7,7 +7,6 @@ import { View } from './View';
 const meta: Meta<typeof Stack> = {
   title: 'Bumper/Core/Primitives/Stack',
   component: Stack,
-  tags: ['autodocs'],
   argTypes: {
     flexDirection: {
       control: 'select',

package/src/system/core/primitives/View.mdx

@@ -0,0 +1,86 @@
+import { Meta, Title, Subtitle, Primary, Controls, Canvas } from '@storybook/blocks';
+import * as ViewStories from './View.stories';
+import * as ViewFeatures from './View.features.stories';
+
+<Meta of={ViewStories} />
+<Title />
+<Subtitle />
+
+<Primary />
+<Controls />
+
+## Overview
+
+`View` is the foundational layout primitive in Bumper, re-exported from Tamagui's `View`. Use it as the base building block for backgrounds, borders, spacing, and flex layouts. All spacing and color values should use Bumper's semantic tokens (`$bg.*`, `$space.*`, `$radius.*`, `$border.*`).
+
+## Background colors
+
+Use `backgroundColor` with semantic `$bg.*` tokens to apply surface colors. Choose `$bg.base.low.default` for subtle backgrounds, `$bg.base.mid.default` for standard surfaces, and `$bg.accent.default` or `$bg.promo.hi.default` for high-emphasis areas that require contrasted text.
+
+<Canvas of={ViewFeatures.BackgroundColors} />
+
+## Borders and radius
+
+Combine `borderWidth`, `borderColor`, and `borderRadius` to define the shape and outline of a `View`. Radius tokens range from `$radius.none` (sharp corners) to `$radius.circle` (fully round). Use `$radius.m` as the default for cards and containers.
+
+<Canvas of={ViewFeatures.BordersAndRadius} />
+
+### Border colors
+
+Border color tokens follow the same semantic naming as backgrounds. Use `$border.base.mid` for standard outlines and semantic tokens like `$border.info`, `$border.success`, `$border.warning`, or `$border.danger` to convey status.
+
+<Canvas of={ViewFeatures.BorderColors} />
+
+## Padding
+
+Use `padding` with `$space.*` tokens to control inner spacing. Available values range from `$space.none` (0) to `$space.32`.
+
+<Canvas of={ViewFeatures.PaddingVariants} />
+
+### Directional padding
+
+Use `paddingTop`, `paddingBottom`, `paddingLeft`, `paddingRight`, `paddingHorizontal`, and `paddingVertical` when you need asymmetric inner spacing.
+
+<Canvas of={ViewFeatures.DirectionalPadding} />
+
+## Margin
+
+Use `margin` with `$space.*` tokens to control outer spacing between elements.
+
+<Canvas of={ViewFeatures.MarginVariants} />
+
+### Directional margin
+
+Use directional margin props (`marginTop`, `marginBottom`, `marginHorizontal`, `marginVertical`) for asymmetric outer spacing.
+
+<Canvas of={ViewFeatures.DirectionalMargin} />
+
+## Flex layout
+
+`View` supports all flexbox properties. Use `flexDirection="row"` for horizontal layouts and `flexGrow` to distribute available space between children.
+
+<Canvas of={ViewFeatures.FlexLayout} />
+
+### Alignment
+
+Combine `alignItems` and `justifyContent` to position children within the container. Use `stretch` with `space-between` when children should fill the cross axis and be evenly distributed.
+
+<Canvas of={ViewFeatures.FlexAlignment} />
+
+### Wrapping
+
+Set `flexWrap="wrap"` with `gap` to create grid-like layouts where items flow to the next line when the container runs out of horizontal space.
+
+<Canvas of={ViewFeatures.FlexWrap} />
+
+## Overflow behavior
+
+Use `overflow="hidden"` to clip content that exceeds the container's dimensions, or `overflow="scroll"` to make it scrollable.
+
+<Canvas of={ViewFeatures.OverflowBehavior} />
+
+## Related
+
+- [Stack](?path=/docs/bumper-core-primitives-stack--docs)
+- [Center](?path=/docs/bumper-core-primitives-center--docs)
+- [Pressable](?path=/docs/bumper-core-primitives-pressable--docs)

package/src/system/core/primitives/View.stories.tsx

@@ -5,7 +5,6 @@ import { View } from './View';
 const meta: Meta<typeof View> = {
   title: 'Bumper/Core/Primitives/View',
   component: View,
-  tags: ['autodocs'],
   argTypes: {
     backgroundColor: backgroundColorArgType,
     padding: spaceArgType,

package/src/system/dataDisplays/Badge/Badge.mdx

@@ -0,0 +1,32 @@
+import { Meta, Title, Subtitle, Primary, Controls, Canvas } from '@storybook/blocks';
+import * as BadgeStories from './Badge.stories';
+import * as BadgeFeatures from './Badge.features.stories';
+
+<Meta of={BadgeStories} />
+<Title />
+<Subtitle />
+
+<Primary />
+<Controls />
+
+## Overview
+
+`Badge` displays a numeric count or a simple dot indicator. Use it to flag unread items, notifications, or new content. It renders as a circular red pill (`$bg.danger.hi`) with white text. When `count` exceeds `maxCount` (default: 9), it displays `"{max}+"`.
+
+## Dot (no count)
+
+Omit `count` entirely to render the badge as an 8px dot. Use this when you want to flag new or unread content without surfacing an exact number.
+
+<Canvas of={BadgeFeatures.WithoutCount} />
+
+## Count values
+
+Pass `count` to display a numeric value. The badge auto-sizes its width to fit the number. A count of `0` is rendered literally.
+
+<Canvas of={BadgeFeatures.WithCount} />
+
+## Maximum count
+
+When `count` exceeds `maxCount`, the badge displays `"{maxCount}+"`. The default `maxCount` is `9`. Set a custom `maxCount` for higher thresholds like `99` or `999`.
+
+<Canvas of={BadgeFeatures.WithMaximumCount} />

package/src/system/dataDisplays/Badge/Badge.stories.tsx

@@ -4,7 +4,6 @@ import { Badge } from './Badge';
 const meta: Meta<typeof Badge> = {
   title: 'Bumper/Data Displays/Badge',
   component: Badge,
-  tags: ['autodocs'],
   argTypes: {
     count: {
       control: 'number',

package/src/system/loading/loader/Loader.mdx

@@ -0,0 +1,26 @@
+import { Meta, Title, Subtitle, Primary, Controls, Canvas } from '@storybook/blocks';
+import * as LoaderStories from './Loader.stories';
+import * as LoaderFeatures from './Loader.features.stories';
+
+<Meta of={LoaderStories} />
+<Title />
+<Subtitle />
+
+<Primary />
+<Controls />
+
+## Overview
+
+`Loader` is an animated circular spinner built with `react-native-reanimated`. It loops continuously and comes in two sizes. Defaults to `size="page"` (48px) with an accent-colored foreground. Use `size="icon"` (20px) for inline loading indicators next to text or buttons.
+
+## Sizes
+
+Use `size="icon"` (20px) for compact inline loaders and `size="page"` (48px) for full-page or section-level loading states.
+
+<Canvas of={LoaderFeatures.Sizes} />
+
+## On contrasted backgrounds
+
+Set `isOnContrasted` when the loader sits on a dark or accent background. This switches the foreground color from `$content.accent` to `$border.base.onContrasted.hi` for proper contrast.
+
+<Canvas of={LoaderFeatures.OnContrasted} />

package/src/system/loading/loader/Loader.stories.tsx

@@ -4,7 +4,6 @@ import { Loader } from './Loader';
 const meta: Meta<typeof Loader> = {
   title: 'Bumper/Loading/Loader',
   component: Loader,
-  tags: ['autodocs'],
   argTypes: {
     size: {
       control: 'select',