@ornikar/bumper 3.10.0 → 3.10.1

package/docs/migration/Typography.md

@@ -58,11 +58,13 @@ import { Typography } from '@ornikar/bumper';
 
 ### 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)                     |
+| 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    | `16` → `$icon.s`, `20` → `$icon.m`, `24` → `$icon.l`. **Any other numeric value (e.g. `40`, `32`) has no bumper token** — see [Unsupported icon sizes](#unsupported-icon-sizes). |
+| `align`     | `alignSelf` | Rename prop     | `align="center"` → `alignSelf="center"`                                                                                                                                          |
+| `testID`    | `testID`    | Keep as-is      | Same API                                                                                                                                                                         |
 
 ## Value Mappings
 
@@ -150,10 +152,12 @@ These are the most common colors found in the codebase. They need the `kitt.bump
 
 ```
 16  → "$icon.s"
-20  → "$icon.m"
+20  → "$icon.m"   (kitt-universal default when size is omitted)
 24  → "$icon.l"
 ```
 
+**Unsupported sizes**: bumper's icon tokens only cover `s` / `m` / `l`. Sizes such as `40` and `32` have no equivalent token (`$icon.xl` does not exist — see [`bumperIcon.ts`](../../src/system/core/tokens/bumperIcon.ts)). Leave such call sites on `@ornikar/kitt-universal`'s `Icon` / `TypographyIcon`, or flag with a `// TODO: bumper has no matching icon size` comment — do not auto-migrate.
+
 ## Sub-Component Mapping
 
 | Source                       | Target               | Notes                                                                                         |
@@ -311,10 +315,12 @@ Key differences:
 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` → `$platform-web`, `_ios`/`_android` → `$platform-native`. Note that both `_ios` and `_android` map to the same `$platform-native` prop — Tamagui has no per-platform native distinction. If the source used different values for iOS and Android, they must be reconciled manually.
-8. **Color inheritance**: Both support color inheritance via context, but the context APIs differ internally. Behavior is equivalent.
+8. **Color inheritance**: When a `Typography.Text` is nested inside another bumper `Typography.*`, color propagates automatically via Tamagui's styled context — omit the `color` prop on the child and it will inherit the parent's value. However, inheritance **does NOT work** when the ancestor is a kitt-universal component that provides color via its own context (e.g., `Button`, `RadioGroup`, `CustomTooltip`). In those cases, **do not migrate** the `Typography.Text` — leave it on `@ornikar/kitt-universal`. See [Color inheritance from parent context](#color-inheritance-from-parent-context).
 9. **Responsive API**: Source uses breakpoint props (`base`, `medium`, `large`) or `type` object. Target uses Tamagui media props (`$small`, `$medium`, `$large`).
 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.
+12. **Icon `align` prop renamed**: Source uses `align`; target uses `alignSelf`.
+13. **Icon tokens only cover s/m/l**: Source accepts any numeric `size`; target only has `$icon.s` (16), `$icon.m` (20), `$icon.l` (24). Other values have no equivalent.
 
 ## Edge Cases
 
@@ -458,6 +464,34 @@ const color = getTypographyColor(state); // should return '$content.accent', '$c
 <Typography.Text color={color}>text</Typography.Text>;
 ```
 
+### Color inheritance from parent context
+
+**Inheritance works automatically** when the parent is a bumper `Typography.*`. Tamagui's styled context propagates the color to descendants — omit the `color` prop on the child:
+
+```tsx
+// Parent sets the color; child inherits via Tamagui context
+<Typography.Text color="$content.accent">
+  Headline with <Typography.Text weight="bold">bold</Typography.Text> inside
+</Typography.Text>
+```
+
+**Inheritance does NOT work** when the ancestor is a kitt-universal component that provides color via its own (non-Tamagui) context. bumper's `Typography.Text` applies its default `$content.base.hi` and has no reliable way to read those foreign contexts.
+
+**Skip the migration entirely** in these cases — leave the `Typography.*` on `@ornikar/kitt-universal`. Known problematic ancestors:
+
+- `Button` (any variant that renders on a contrasted surface)
+- `RadioGroup`
+- `CustomTooltip`
+
+```tsx
+// ❌ DO NOT migrate — Button provides color via kitt's context, bumper cannot inherit it
+<Button type="primary">
+  <Typography.Text>Action</Typography.Text> {/* keep on @ornikar/kitt-universal */}
+</Button>
+```
+
+If you cannot leave the call site on kitt-universal (e.g. mixed-imports are undesirable), the only safe escape hatch is to pass the correct bumper token explicitly — but prefer skipping the migration over guessing the token.
+
 ### TypographyIcon with color="inherit"
 
 ```tsx
@@ -468,6 +502,31 @@ const color = getTypographyColor(state); // should return '$content.accent', '$c
 <Typography.Icon icon={<CheckIcon />} />
 ```
 
+### TypographyIcon with `align`
+
+```tsx
+// Before — kitt-universal supports align
+<TypographyIcon icon={<LoaderIcon />} align="center" />
+
+// After — bumper renames to alignSelf
+<Typography.Icon icon={<LoaderIcon />} alignSelf="center" />
+```
+
+### Unsupported icon sizes
+
+`bumper`'s icon tokens only cover `s` (16) / `m` (20) / `l` (24). Any other numeric size has no equivalent token.
+
+```tsx
+// Before
+<TypographyIcon icon={<AvatarIcon />} size={40} />
+
+// After — DO NOT auto-migrate. Either:
+// (a) leave the call site on kitt-universal's TypographyIcon, or
+// (b) flag for manual review:
+// TODO: bumper has no matching icon size for 40
+<TypographyIcon icon={<AvatarIcon />} size={40} />
+```
+
 ## Migration Rules (machine-readable)
 
 1. **Update import**: Replace `import { Typography } from '@ornikar/kitt-universal'` with `import { Typography } from '@ornikar/bumper'`
@@ -492,7 +551,12 @@ const color = getTypographyColor(state); // should return '$content.accent', '$c
 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"`)
+23. **Icon size**: Map numeric sizes to tokens (`16` → `"$icon.s"`, `20` → `"$icon.m"`, `24` → `"$icon.l"`). **Omitted `size`** on the source (kitt-universal defaults to 20) also maps to `"$icon.m"`.
+24. **Color inheritance — prefer automatic inheritance, skip inside foreign contexts**:
+    - When the parent is a bumper `Typography.*` and the child has no `color` prop, inheritance works automatically via Tamagui's styled context — do not add an explicit `color`.
+    - When the ancestor is a kitt-universal component that provides color via its own context — specifically `Button`, `RadioGroup`, or `CustomTooltip` — **do not migrate** the nested `Typography.*`. Leave it on `@ornikar/kitt-universal`. Bumper cannot read those foreign contexts, so any migration would either regress the color or require a guessed explicit token.
+25. **Icon `align` → `alignSelf`**: Rename `align` to `alignSelf`.
+26. **Unsupported icon sizes**: If the source `size` is a numeric value other than `16` / `20` / `24`, do NOT migrate. Either leave the call site on `@ornikar/kitt-universal`'s `TypographyIcon`, or flag with a `// TODO: bumper has no matching icon size` comment.
 
 ## Not Migratable (requires human review)
 
@@ -504,3 +568,5 @@ const color = getTypographyColor(state); // should return '$content.accent', '$c
 - **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.
+- **TypographyIcon with unsupported `size`** — Any numeric `size` other than `16` / `20` / `24` has no bumper token. Call sites must either stay on `@ornikar/kitt-universal` or be resized to a supported token manually.
+- **`Typography.*` nested inside `Button`, `RadioGroup`, or `CustomTooltip`** — These components provide text color via kitt's own (non-Tamagui) context; bumper cannot inherit from them. Leave such call sites on `@ornikar/kitt-universal`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ornikar/bumper",
-  "version": "3.10.0",
+  "version": "3.10.1",
   "license": "MIT",
   "repository": {
     "directory": "@ornikar/bumper",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.24.0",
-    "@ornikar/kitt-icons": "^15.3.0",
+    "@ornikar/kitt-icons": "^15.3.1",
     "@tamagui/core": "1.144.2",
     "@tamagui/image": "1.144.2",
     "@tamagui/scroll-view": "1.144.2"

package/src/.eslintrc.json

@@ -1,9 +1,6 @@
 {
   "root": true,
   "parser": "@typescript-eslint/parser",
-  "parserOptions": {
-    "project": "@ornikar/bumper/tsconfig.eslint.json"
-  },
   "extends": [
     "@ornikar/eslint-config-typescript-react",
     "@ornikar/eslint-config/rollup",
@@ -12,8 +9,8 @@
   ],
   "settings": {
     "import/resolver": {
-      "node": {
-        "moduleDirectory": ["node_modules", "src"]
+      "typescript": {
+        "project": "@ornikar/bumper/tsconfig.json"
       }
     }
   },

package/src/shared/storybook/StorySection.tsx

@@ -2,8 +2,14 @@ import { styled } from '@tamagui/core';
 import type { ReactNode } from 'react';
 import type { Except } from 'type-fest';
 import { VStack, type VStackProps } from '../../system/core/primitives/Stack';
+import type { ViewProps } from '../../system/core/primitives/View';
+import type { PropsToTamaguiVariants } from '../../system/types';
 import { StoryTitle } from './StoryTitle';
 
+interface InternalStorySectionWithoutMediaProps {
+  withBackground?: boolean;
+}
+
 const InternalStorySection = styled(VStack, {
   paddingVertical: '$space.4',
   paddingHorizontal: '$space.4',
@@ -12,8 +18,9 @@ const InternalStorySection = styled(VStack, {
       true: {
         backgroundColor: '$content.base.hi',
       },
+      false: {},
     },
-  } as const,
+  } as const satisfies PropsToTamaguiVariants<InternalStorySectionWithoutMediaProps, ViewProps>,
 });
 
 export type StorySectionProps = Except<VStackProps, 'marginBottom'> & {

package/src/shared/storybook/StoryTitle.tsx

@@ -1,5 +1,11 @@
+import type { GetProps } from '@tamagui/core';
 import { styled } from '@tamagui/core';
 import { InternalTypography } from '../../system/content/typography/Typography';
+import type { PropsToTamaguiVariants } from '../../system/types';
+
+interface StoryTitleWithoutMediaProps {
+  level?: 1 | 2 | 3;
+}
 
 export const StoryTitle = styled(InternalTypography, {
   variants: {
@@ -8,9 +14,9 @@ export const StoryTitle = styled(InternalTypography, {
       2: { variant: 'heading-l', marginBottom: '$space.4' },
       3: { variant: 'heading-m', marginBottom: '$space.4' },
     },
-  } as const,
+  } as const satisfies PropsToTamaguiVariants<StoryTitleWithoutMediaProps, GetProps<typeof InternalTypography>>,
 
   defaultVariants: {
     level: 1,
   },
-} as const);
+});

package/src/system/actions/Button/Button.tsx

@@ -1,14 +1,16 @@
 import { styled, withStaticProperties } from '@tamagui/core';
 import { useProps } from '../../core/hooks/useProps';
+import type { HStackProps } from '../../core/primitives/Stack';
 import { HStack } from '../../core/primitives/Stack';
 import { View } from '../../core/primitives/View';
 import { Loader } from '../../loading/loader/Loader';
+import type { PropsToTamaguiVariants } from '../../types';
 import { ButtonBadge } from './components/ButtonBadge';
 import { ButtonIcon } from './components/ButtonIcon';
 import { ButtonText } from './components/ButtonText';
 import type { ButtonType } from './context';
 import { context } from './context';
-import type { ButtonProps, ButtonTypeStyle } from './types';
+import type { ButtonProps, ButtonTypeStyle, ButtonWithoutMediaProps } from './types';
 
 export const InternalButtonFrame = styled(HStack, {
   name: 'Button',
@@ -125,7 +127,7 @@ export const InternalButtonFrame = styled(HStack, {
       },
       false: {},
     },
-  } as const,
+  } as const satisfies PropsToTamaguiVariants<ButtonWithoutMediaProps, HStackProps>,
 });
 
 export const InternalButton = InternalButtonFrame.styleable<ButtonProps, ButtonProps>((props, ref) => {

package/src/system/actions/IconButton/IconButton.tsx

@@ -1,7 +1,8 @@
 import { styled, withStaticProperties } from '@tamagui/core';
 import type { ReactNode } from 'react';
 import type { Except } from 'type-fest';
-import type { TamaguiMediaProps } from '../../types';
+import type { ViewProps } from '../../core/primitives/View';
+import type { PropsToTamaguiVariants, TamaguiMediaProps } from '../../types';
 import { InternalButton } from '../Button/Button';
 import { ButtonBadge } from '../Button/components/ButtonBadge';
 import { ButtonIcon } from '../Button/components/ButtonIcon';
@@ -31,7 +32,7 @@ export const InternalIconButtonFrame = styled(InternalButton, {
         height: 48,
       },
     },
-  } as const,
+  } as const satisfies PropsToTamaguiVariants<IconButtonWithoutMediaProps, ViewProps>,
 });
 
 function InternalIconButton(props: IconButtonProps): ReactNode {

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

@@ -3,9 +3,14 @@ import { styled, useStyle } from '@tamagui/core';
 import type { ReactElement, ReactNode } from 'react';
 import { cloneElement } from 'react';
 import { useProps } from '../../core/hooks/useProps';
+import type { ViewProps } from '../../core/primitives/View';
 import { View } from '../../core/primitives/View';
 import type { BumperIconTokens } from '../../core/tokens/bumperIcon';
-import type { TamaguiMediaProps } from '../../types';
+import type { PropsToTamaguiVariants, TamaguiMediaProps } from '../../types';
+
+interface IconContainerVariantProps {
+  size?: BumperIconTokens;
+}
 
 const IconContainer = styled(View, {
   name: 'Icon',
@@ -16,7 +21,7 @@ const IconContainer = styled(View, {
         height: tokens.bumperIcon[iconSize],
       };
     },
-  } as const,
+  } as const satisfies PropsToTamaguiVariants<IconContainerVariantProps, ViewProps>,
 
   defaultVariants: {
     size: '$icon.m',

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

@@ -1,9 +1,9 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { VStack } from '../../core/primitives/Stack';
-import type { BodyProps, TypographyTextProps } from './Typography';
+import type { TypographyBodyProps, TypographyTextProps } from './Typography';
 import { Typography } from '.';
 
-const meta: Meta<Extract<TypographyTextProps, BodyProps>> = {
+const meta: Meta<Extract<TypographyTextProps, TypographyBodyProps>> = {
   title: 'Bumper/Content/Typography/Features',
   component: Typography.Text,
 };

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

@@ -1,9 +1,9 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { contentColorArgType } from '../../../shared/storybook/helpers/argsHelpers';
-import type { BodyProps, TypographyTextProps } from './Typography';
+import type { TypographyBodyProps, TypographyTextProps } from './Typography';
 import { Typography } from '.';
 
-const meta: Meta<Extract<TypographyTextProps, BodyProps>> = {
+const meta: Meta<Extract<TypographyTextProps, TypographyBodyProps>> = {
   title: 'Bumper/Content/Typography',
   component: Typography.Text,
   argTypes: {

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

@@ -1,4 +1,4 @@
-import type { ColorTokens, GetProps } from '@tamagui/core';
+import type { ColorTokens, TextProps } from '@tamagui/core';
 import { Text, styled } from '@tamagui/core';
 import type { ReactNode } from 'react';
 import { type Except } from 'type-fest';
@@ -13,13 +13,11 @@ import {
 } from '../../core/tokens/GTStandardFont';
 import { CONTENT_CAPS_VARIANTS, type ContentCapsVariants } from '../../core/tokens/GTStandardNarrowFont';
 import type { FontVariants } from '../../core/tokens/fonts';
-import type { TamaguiMediaProps } from '../../types';
+import type { PropsToTamaguiVariants, TamaguiMediaProps } from '../../types';
 import { typographyStyleContext } from './utils/typographyContext';
 
-interface TypographyWithoutMediaProps extends TypographyPropsWithoutFontStyleProps {}
-
 // Remove font-related style props from InternalTypography Props
-type TypographyExcludedFontStyleProps =
+type InternalTypographyExcludedFontStyleProps =
   | 'fontFamily'
   | 'fontSize'
   | 'lineHeight'
@@ -28,27 +26,30 @@ type TypographyExcludedFontStyleProps =
   | 'fontWeight'
   | 'color';
 
-type TypographyPropsWithoutFontStyleProps = Except<InternalTypographyProps, TypographyExcludedFontStyleProps> & {
+type InternalTypographyPropsWithoutFontStyleProps = Except<TextProps, InternalTypographyExcludedFontStyleProps> & {
   color?: ColorTokens;
 };
 
-export interface BodyProps extends TypographyWithoutMediaProps {
+interface InternalTypographyWithoutMediaProps extends InternalTypographyPropsWithoutFontStyleProps {}
+
+interface TypographyBodyWithoutMediaProps extends InternalTypographyWithoutMediaProps {
   variant?: BodyFontVariants;
   weight?: 'regular' | 'bold';
 }
-export interface HeadingLabelProps extends TypographyWithoutMediaProps {
+interface TypographyHeadingLabelWithoutMediaProps extends InternalTypographyWithoutMediaProps {
   variant: HeadingFontVariants | LabelFontVariants;
   weight?: 'semibold';
 }
-export interface ContentCapsProps extends TypographyWithoutMediaProps {
+interface TypographyContentCapsWithoutMediaProps extends InternalTypographyWithoutMediaProps {
   variant: ContentCapsVariants;
   weight?: 'bold';
 }
 
-export type TypographyTextProps =
-  | TamaguiMediaProps<BodyProps>
-  | TamaguiMediaProps<HeadingLabelProps>
-  | TamaguiMediaProps<ContentCapsProps>;
+export interface TypographyBodyProps extends TamaguiMediaProps<TypographyBodyWithoutMediaProps> {}
+export interface TypographyHeadingLabelProps extends TamaguiMediaProps<TypographyHeadingLabelWithoutMediaProps> {}
+export interface TypographyContentCapsProps extends TamaguiMediaProps<TypographyContentCapsWithoutMediaProps> {}
+
+export type TypographyTextProps = TypographyBodyProps | TypographyHeadingLabelProps | TypographyContentCapsProps;
 
 export const InternalTypography = styled(Text, {
   context: typographyStyleContext,
@@ -63,9 +64,9 @@ export const InternalTypography = styled(Text, {
     WebkitFontSmoothing: 'antialiased',
   },
   variants: {
-    variant: (variant: FontVariants) => {
+    variant: (variant: FontVariants): TextProps => {
       const commonVariantStyles = {
-        fontSize: `$${variant}`,
+        fontSize: `$${variant}` as const,
         lineHeight: `$${variant}`,
         letterSpacing: `$${variant}`,
       };
@@ -100,7 +101,7 @@ export const InternalTypography = styled(Text, {
         };
       }
 
-      return undefined;
+      return {};
     },
     weight: {
       regular: {
@@ -113,14 +114,15 @@ export const InternalTypography = styled(Text, {
         fontWeight: '$bold',
       },
     },
-  } as const,
+  } as const satisfies PropsToTamaguiVariants<
+    TypographyBodyWithoutMediaProps | TypographyHeadingLabelWithoutMediaProps | TypographyContentCapsWithoutMediaProps,
+    TextProps
+  >,
   defaultVariants: {
     weight: 'regular',
   },
 });
 
-export type InternalTypographyProps = GetProps<typeof InternalTypography>;
-
 export function TypographyBase(props: TypographyTextProps): ReactNode {
   const flattenProps = useProps(props);
   return <InternalTypography {...flattenProps} />;

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

@@ -1,12 +1,12 @@
 import { action } from '@storybook/addon-actions';
 import type { Meta, StoryObj } from '@storybook/react';
 import { VStack } from '../../core/primitives/Stack';
-import type { BodyProps } from './Typography';
+import type { TypographyBodyProps } from './Typography';
 import type { TypographyLinkProps } from './TypographyLink';
 import { InternalTypographyLink, TypographyLink } from './TypographyLink';
 import { Typography } from '.';
 
-const meta: Meta<Extract<TypographyLinkProps, BodyProps>> = {
+const meta: Meta<Extract<TypographyLinkProps, TypographyBodyProps>> = {
   title: 'Bumper/Content/TypographyLink/Features',
   component: TypographyLink,
 };

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

@@ -1,11 +1,11 @@
 import { action } from '@storybook/addon-actions';
 import type { Meta, StoryObj } from '@storybook/react';
 import { contentColorArgType } from '../../../shared/storybook/helpers/argsHelpers';
-import type { BodyProps } from './Typography';
+import type { TypographyBodyProps } from './Typography';
 import type { TypographyLinkProps } from './TypographyLink';
 import { TypographyLink } from './TypographyLink';
 
-const meta: Meta<Extract<TypographyLinkProps, BodyProps>> = {
+const meta: Meta<Extract<TypographyLinkProps, TypographyBodyProps>> = {
   title: 'Bumper/Content/TypographyLink',
   component: TypographyLink,
   argTypes: {

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

@@ -1,6 +1,7 @@
+import type { TextProps } from '@tamagui/core';
 import { styled } from '@tamagui/core';
 import type { ReactNode } from 'react';
-import type { TamaguiMediaProps } from '../../types';
+import type { PropsToTamaguiVariants, TamaguiMediaProps } from '../../types';
 import type { TypographyTextProps } from './Typography';
 import { InternalTypography } from './Typography';
 import { typographyStyleContext } from './utils/typographyContext';
@@ -9,6 +10,7 @@ export interface TypographyLinkWithoutMediaProps {
   disabled?: boolean;
   noUnderline?: boolean;
   onPress?: () => void;
+  href?: string;
 }
 
 export type TypographyLinkProps = TypographyTextProps & TamaguiMediaProps<TypographyLinkWithoutMediaProps>;
@@ -41,7 +43,7 @@ export const InternalTypographyLink = styled(InternalTypography, {
         textDecorationLine: 'underline',
       },
     },
-  } as const,
+  } as const satisfies PropsToTamaguiVariants<TypographyLinkWithoutMediaProps, TextProps>,
   defaultVariants: {
     disabled: false,
     noUnderline: false,

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

@@ -2,8 +2,9 @@ import { styled, useStyle } from '@tamagui/core';
 import type { ReactNode } from 'react';
 import { useEffect } from 'react';
 import { useSharedValue, withRepeat, withTiming } from 'react-native-reanimated';
+import type { ViewProps } from '../../core/primitives/View';
 import { View } from '../../core/primitives/View';
-import type { TamaguiMediaProps } from '../../types';
+import type { PropsToTamaguiVariants, TamaguiMediaProps } from '../../types';
 import { LoaderBackgroundCircle } from './LoaderBackgroundCircle';
 import { LoaderCircleWrapper } from './LoaderCircleWrapper';
 import { LoaderForegroundCircle } from './LoaderForegroundCircle';
@@ -12,19 +13,7 @@ import { LOADER_ANIMATION, LOADER_SIZE_CONFIG } from './loaderConfig';
 
 const { icon, page } = LOADER_SIZE_CONFIG;
 
-const LoaderContainer = styled(View, {
-  name: 'Loader',
-  position: 'relative',
-  rotate: '-90deg',
-  variants: {
-    size: {
-      icon: { width: icon.size, height: icon.size },
-      page: { width: page.size, height: page.size },
-    },
-  } as const,
-});
-
-interface InternalLoaderProps {
+interface InternalLoaderWithoutMediaProps {
   /** The size of the loader. `'icon'` renders a small 20px loader, `'page'` renders a larger 48px loader.
    * @default 'page'
    * */
@@ -37,7 +26,19 @@ interface InternalLoaderProps {
   testID?: string;
 }
 
-export type LoaderProps = TamaguiMediaProps<InternalLoaderProps>;
+const LoaderContainer = styled(View, {
+  name: 'Loader',
+  position: 'relative',
+  rotate: '-90deg',
+  variants: {
+    size: {
+      icon: { width: icon.size, height: icon.size },
+      page: { width: page.size, height: page.size },
+    },
+  } as const satisfies PropsToTamaguiVariants<InternalLoaderWithoutMediaProps, ViewProps>,
+});
+
+export type LoaderProps = TamaguiMediaProps<InternalLoaderWithoutMediaProps>;
 
 export function Loader({ size = 'page', isOnContrasted = false, testID }: LoaderProps): ReactNode {
   const backgroundStyle = useStyle({ color: '$border.base.mid' });

package/src/system/loading/loader/LoaderBackgroundCircle.tsx

@@ -1,9 +1,16 @@
 import { styled } from '@tamagui/core';
+import type { CircleProps } from 'react-native-svg';
 import { Circle } from 'react-native-svg';
+import type { PropsToTamaguiVariants } from '../../types';
+import type { LoaderSize } from './loaderConfig';
 import { LOADER_SIZE_CONFIG } from './loaderConfig';
 
 const { icon, page } = LOADER_SIZE_CONFIG;
 
+interface LoaderBackgroundCircleVariantProps {
+  size?: LoaderSize;
+}
+
 export const LoaderBackgroundCircle = styled(Circle, {
   fill: 'none',
   variants: {
@@ -11,5 +18,5 @@ export const LoaderBackgroundCircle = styled(Circle, {
       icon: { strokeWidth: icon.strokeWidth, cx: icon.center, cy: icon.center, r: icon.radius },
       page: { strokeWidth: page.strokeWidth, cx: page.center, cy: page.center, r: page.radius },
     },
-  } as const,
+  } as const satisfies PropsToTamaguiVariants<LoaderBackgroundCircleVariantProps, CircleProps>,
 });

package/src/system/loading/loader/LoaderCircleWrapper.tsx

@@ -1,9 +1,18 @@
 import { styled } from '@tamagui/core';
+import type { SvgProps } from 'react-native-svg';
 import Svg from 'react-native-svg';
+import type { ViewProps } from '../../core/primitives/View';
+import type { PropsToTamaguiVariants } from '../../types';
+import type { LoaderSize } from './loaderConfig';
 import { LOADER_SIZE_CONFIG } from './loaderConfig';
 
 const { icon, page } = LOADER_SIZE_CONFIG;
 
+interface LoaderCircleWrapperVariantProps {
+  size?: LoaderSize;
+  isForeground?: boolean;
+}
+
 export const LoaderCircleWrapper = styled(Svg, {
   variants: {
     size: {
@@ -14,6 +23,7 @@ export const LoaderCircleWrapper = styled(Svg, {
       true: {
         position: 'absolute',
       },
+      false: {},
     },
-  } as const,
+  } as const satisfies PropsToTamaguiVariants<LoaderCircleWrapperVariantProps, SvgProps & ViewProps>,
 });

package/src/system/types.ts

@@ -1,5 +1,9 @@
-// eslint-disable-next-line no-restricted-imports
-import type { PropsWithoutMediaStyles as InternalPropsWithoutMediaStyles, WithMediaProps } from '@tamagui/core';
+import type {
+  // eslint-disable-next-line no-restricted-imports
+  PropsWithoutMediaStyles as InternalPropsWithoutMediaStyles,
+  TokensParsed,
+  WithMediaProps,
+} from '@tamagui/core';
 
 /**
  * Rewrite of Tamagui PropsWithoutMediaStyles to make all responsive props optionnal.
@@ -17,3 +21,48 @@ export type PropsWithoutMediaStyles<A> = {
  * pass breakpoint-specific prop objects alongside regular props.
  */
 export type TamaguiMediaProps<A> = PropsWithoutMediaStyles<A> & WithMediaProps<InternalPropsWithoutMediaStyles<A>>;
+
+/**
+ * A list of keys to ignore as variants.
+ * If you do not want to ignore keys globally, you should instead use the third param of the {@link PropsToTamaguiVariants}.
+ */
+export type DefaultIgnoredKeys = 'children';
+
+/**
+ * Maps a component's variant-prop interface `T` to a Tamagui `variants` config whose entries produce
+ * style objects of type `V`.
+ *
+ * For each key `K` of `T`, the entry must be either:
+ * - a record keyed by the prop's literal values (with `boolean` props normalised to `'true' | 'false'`),
+ *   where each value is a style `V` or a function returning `V`, or
+ * - a function that receives the raw prop value and a {@link VariantGoodiesParams} context and returns
+ *   a style `V` (or `undefined`).
+ *
+ * Pass a union of keys as `IgnoredKeys` to skip props that should never be variants (e.g.
+ * event handlers). Ignored keys are stripped only from both the top-level map, not from `params.props`.
+ *
+ * Intended to be used with `satisfies` on the `variants` field of a `styled(...)` call so that the
+ * config is inferred `as const` while still being checked against the component's prop types, e.g.
+ * `{ ... } as const satisfies PropsToTamaguiVariants<MyVariantProps, ViewProps, 'size'>`.
+ */
+export type PropsToTamaguiVariants<T, V, IgnoredKeys extends keyof T = never> = {
+  [K in keyof T as K extends IgnoredKeys | Extract<keyof T, DefaultIgnoredKeys> ? never : K]: NonNullable<
+    T[K]
+  > extends boolean
+    ? Record<'true' | 'false', V | ((value: boolean | string | number, params: VariantGoodiesParams<T>) => V)>
+    : NonNullable<T[K]> extends PropertyKey
+    ? Record<NonNullable<T[K]>, V> | ((value: NonNullable<T[K]>, params: VariantGoodiesParams<T>) => V | undefined)
+    : never;
+};
+
+/**
+ * Second argument passed to function-form variants declared via {@link PropsToTamaguiVariants}.
+ *
+ * - `props`: the flattened props of the instance being styled, so a variant can branch on sibling
+ *   props (e.g. read `disabled` or `isOnContrasted` while resolving `type`).
+ * - `tokens`: Tamagui's parsed token map, for resolving design tokens from inside the variant.
+ */
+interface VariantGoodiesParams<T> {
+  props: T;
+  tokens: TokensParsed;
+}