@ankhorage/zora 2.11.0 → 2.13.0

package/dist/theme/resolveZoraThemeRecipe.js

@@ -0,0 +1,56 @@
+import { ZORA_THEME_RECIPE_META } from '../metadata/themeRecipeMeta';
+const recipeMetaByName = new Map(Object.entries(ZORA_THEME_RECIPE_META));
+export function resolveZoraThemeRecipe(theme, recipeName) {
+    const meta = recipeMetaByName.get(recipeName);
+    if (!meta)
+        throw new RangeError(`Unknown ZORA theme recipe: ${recipeName}.`);
+    const recipes = meta.kind === 'component' ? theme.config.recipes?.components : theme.config.recipes?.patterns;
+    const overrides = new Map(Object.entries(recipes ?? {})).get(recipeName);
+    const overrideByField = new Map(Object.entries(overrides ?? {}));
+    const resolved = [];
+    for (const [fieldName, fieldMeta] of Object.entries(meta.fields)) {
+        const override = overrideByField.get(fieldName);
+        if (override !== undefined) {
+            validateFieldValue(theme, recipeName, fieldName, fieldMeta, override);
+            resolved.push([fieldName, override]);
+        }
+        else if (fieldMeta.default !== undefined) {
+            resolved.push([fieldName, fieldMeta.default]);
+        }
+    }
+    return Object.fromEntries(resolved);
+}
+function validateFieldValue(theme, recipeName, fieldName, meta, value) {
+    if (meta.type === 'boolean') {
+        if (typeof value !== 'boolean') {
+            throw new TypeError(`Theme recipe ${recipeName}.${fieldName} must be boolean.`);
+        }
+        return;
+    }
+    if (typeof value !== 'string') {
+        throw new TypeError(`Theme recipe ${recipeName}.${fieldName} must be a string.`);
+    }
+    if (meta.type === 'choice' && !meta.options.includes(value)) {
+        throw new RangeError(`Invalid theme recipe choice for ${recipeName}.${fieldName}: ${value}.`);
+    }
+    if (meta.type === 'token' && !hasThemeToken(theme, meta.tokenFamily, value)) {
+        throw new RangeError(`Unknown ${meta.tokenFamily} token for ${recipeName}.${fieldName}: ${value}.`);
+    }
+}
+function hasThemeToken(theme, family, token) {
+    if (family === 'colors')
+        return hasOwn(theme.colors, token);
+    if (family === 'spacing')
+        return hasOwn(theme.spacing, token);
+    if (family === 'radii')
+        return hasOwn(theme.radii, token);
+    if (family === 'shadows')
+        return hasOwn(theme.shadows, token);
+    return (hasOwn(theme.typography.sizes, token) ||
+        hasOwn(theme.typography.weights, token) ||
+        hasOwn(theme.typography.headings, token));
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+//# sourceMappingURL=resolveZoraThemeRecipe.js.map

package/dist/theme/resolveZoraThemeRecipe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveZoraThemeRecipe.js","sourceRoot":"","sources":["../../src/theme/resolveZoraThemeRecipe.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ThemeConfig, ThemeRecipeOverrideValue } from '@ankhorage/contracts';\n\nimport { ZORA_THEME_RECIPE_META } from '../metadata/themeRecipeMeta';\nimport type { ZoraThemeRecipeFieldMeta, ZoraThemeTokenFamily } from '../metadata/themeRecipeTypes';\n\ninterface ZoraThemeRecipeRuntimeTheme {\n  readonly config: ThemeConfig;\n  readonly colors: object;\n  readonly spacing: object;\n  readonly radii: object;\n  readonly shadows: object;\n  readonly typography: {\n    readonly sizes: object;\n    readonly weights: object;\n    readonly headings: object;\n  };\n}\n\nconst recipeMetaByName = new Map(Object.entries(ZORA_THEME_RECIPE_META));\n\nexport function resolveZoraThemeRecipe(\n  theme: ZoraThemeRecipeRuntimeTheme,\n  recipeName: string,\n): Readonly<Record<string, ThemeRecipeOverrideValue>> {\n  const meta = recipeMetaByName.get(recipeName);\n  if (!meta) throw new RangeError(`Unknown ZORA theme recipe: ${recipeName}.`);\n\n  const recipes =\n    meta.kind === 'component' ? theme.config.recipes?.components : theme.config.recipes?.patterns;\n  const overrides = new Map(Object.entries(recipes ?? {})).get(recipeName);\n  const overrideByField = new Map(Object.entries(overrides ?? {}));\n  const resolved: [string, ThemeRecipeOverrideValue][] = [];\n\n  for (const [fieldName, fieldMeta] of Object.entries(meta.fields)) {\n    const override = overrideByField.get(fieldName);\n    if (override !== undefined) {\n      validateFieldValue(theme, recipeName, fieldName, fieldMeta, override);\n      resolved.push([fieldName, override]);\n    } else if (fieldMeta.default !== undefined) {\n      resolved.push([fieldName, fieldMeta.default]);\n    }\n  }\n\n  return Object.fromEntries(resolved);\n}\n\nfunction validateFieldValue(\n  theme: ZoraThemeRecipeRuntimeTheme,\n  recipeName: string,\n  fieldName: string,\n  meta: ZoraThemeRecipeFieldMeta,\n  value: ThemeRecipeOverrideValue,\n): void {\n  if (meta.type === 'boolean') {\n    if (typeof value !== 'boolean') {\n      throw new TypeError(`Theme recipe ${recipeName}.${fieldName} must be boolean.`);\n    }\n    return;\n  }\n  if (typeof value !== 'string') {\n    throw new TypeError(`Theme recipe ${recipeName}.${fieldName} must be a string.`);\n  }\n  if (meta.type === 'choice' && !meta.options.includes(value)) {\n    throw new RangeError(`Invalid theme recipe choice for ${recipeName}.${fieldName}: ${value}.`);\n  }\n  if (meta.type === 'token' && !hasThemeToken(theme, meta.tokenFamily, value)) {\n    throw new RangeError(\n      `Unknown ${meta.tokenFamily} token for ${recipeName}.${fieldName}: ${value}.`,\n    );\n  }\n}\n\nfunction hasThemeToken(\n  theme: ZoraThemeRecipeRuntimeTheme,\n  family: ZoraThemeTokenFamily,\n  token: string,\n): boolean {\n  if (family === 'colors') return hasOwn(theme.colors, token);\n  if (family === 'spacing') return hasOwn(theme.spacing, token);\n  if (family === 'radii') return hasOwn(theme.radii, token);\n  if (family === 'shadows') return hasOwn(theme.shadows, token);\n  return (\n    hasOwn(theme.typography.sizes, token) ||\n    hasOwn(theme.typography.weights, token) ||\n    hasOwn(theme.typography.headings, token)\n  );\n}\n\nfunction hasOwn(value: object, key: PropertyKey): boolean {\n  return Object.prototype.hasOwnProperty.call(value, key);\n}\n"]}

package/dist/theme/useZoraTheme.d.ts

@@ -1,7 +1,7 @@
 export declare function useZoraTheme(): {
     theme: import("@ankhorage/surface").SurfaceTheme;
     mode: "light" | "dark";
-    setThemeConfig: (config: Partial<import("@ankhorage/contracts").ThemeConfig>) => void;
+    setThemeConfig: (config: Partial<import("@ankhorage/surface").ThemeConfig>) => void;
     setMode: (mode: "light" | "dark") => void;
     _hasProvider?: boolean;
 };

package/dist/theme/useZoraThemeRecipe.d.ts

@@ -0,0 +1,2 @@
+export declare function useZoraThemeRecipe(recipeName: string): Readonly<Record<string, import("@ankhorage/contracts").ThemeRecipeOverrideValue>>;
+//# sourceMappingURL=useZoraThemeRecipe.d.ts.map

package/dist/theme/useZoraThemeRecipe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useZoraThemeRecipe.d.ts","sourceRoot":"","sources":["../../src/theme/useZoraThemeRecipe.ts"],"names":[],"mappings":"AAGA,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,qFAGpD"}

package/dist/theme/useZoraThemeRecipe.js

@@ -0,0 +1,7 @@
+import { resolveZoraThemeRecipe } from './resolveZoraThemeRecipe';
+import { useZoraTheme } from './useZoraTheme';
+export function useZoraThemeRecipe(recipeName) {
+    const { theme } = useZoraTheme();
+    return resolveZoraThemeRecipe(theme, recipeName);
+}
+//# sourceMappingURL=useZoraThemeRecipe.js.map

package/dist/theme/useZoraThemeRecipe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useZoraThemeRecipe.js","sourceRoot":"","sources":["../../src/theme/useZoraThemeRecipe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,MAAM,UAAU,kBAAkB,CAAC,UAAkB;IACnD,MAAM,EAAE,KAAK,EAAE,GAAG,YAAY,EAAE,CAAC;IACjC,OAAO,sBAAsB,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;AACnD,CAAC","sourcesContent":["import { resolveZoraThemeRecipe } from './resolveZoraThemeRecipe';\nimport { useZoraTheme } from './useZoraTheme';\n\nexport function useZoraThemeRecipe(recipeName: string) {\n  const { theme } = useZoraTheme();\n  return resolveZoraThemeRecipe(theme, recipeName);\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/zora",
   "type": "module",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "description": "Opinionated React Native and React Native Web UI kit built on @ankhorage/surface.",
   "homepage": "https://github.com/ankhorage/zora#readme",
   "bugs": {
@@ -42,8 +42,8 @@
   },
   "dependencies": {
     "@ankhorage/color-theory": "^0.0.8",
-    "@ankhorage/contracts": "^4.0.1",
-    "@ankhorage/surface": "^2.1.1"
+    "@ankhorage/contracts": "^7.6.0",
+    "@ankhorage/surface": "^2.2.0"
   },
   "files": [
     "dist",
@@ -90,7 +90,7 @@
   },
   "devDependencies": {
     "@ankhorage/devtools": "^1.3.4",
-    "@ankhorage/paradox": "^0.1.10",
+    "@ankhorage/paradox": "^0.1.21",
     "@changesets/cli": "^2.31.0",
     "@expo/vector-icons": "^15.1.1",
     "@react-native-picker/picker": "^2.11.4",

package/src/components/button/Button.tsx

@@ -1,8 +1,9 @@
 import { Button as SurfaceButton } from '@ankhorage/surface';
 import React from 'react';
 
-import { resolveButtonRecipe } from '../../internal/recipes';
+import { useZoraThemeRecipe } from '../../theme/useZoraThemeRecipe';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import { resolveButtonThemeRecipe } from './resolveButtonThemeRecipe';
 import type { ButtonProps } from './types';
 
 function ButtonInner({
@@ -14,7 +15,8 @@ function ButtonInner({
   interactionPolicy,
   ...props
 }: ButtonProps) {
-  const recipe = resolveButtonRecipe({ color, variant, size });
+  const themeFields = useZoraThemeRecipe('Button');
+  const recipe = resolveButtonThemeRecipe({ color, variant, size, themeFields });
 
   return (
     <SurfaceButton

package/src/components/button/meta.ts

@@ -1,20 +1,18 @@
 import { ZORA_COLORS } from '../../internal/colorModel';
 import type { ZoraComponentMeta } from '../../metadata';
 
+const themeAuthoring = {
+  authority: 'theme',
+  scope: 'component',
+  allowInstanceOverride: true,
+} as const;
+
 export const buttonMeta = {
   name: 'Button',
   category: 'component',
   directManifestNode: true,
   allowedChildren: [],
-  blueprint: {
-    label: 'Button',
-    defaultProps: {
-      children: 'Continue',
-      color: 'primary',
-      variant: 'solid',
-      size: 'm',
-    },
-  },
+  blueprint: { label: 'Button', defaultProps: { children: 'Continue' } },
   events: {
     press: {
       label: 'Press',
@@ -36,24 +34,21 @@ export const buttonMeta = {
       category: 'Style',
       label: 'Color',
       enum: [...ZORA_COLORS],
-      default: 'primary',
-      authoring: { authority: 'theme', scope: 'component' },
+      authoring: themeAuthoring,
     },
     variant: {
       type: 'enum',
       category: 'Style',
       label: 'Variant',
       enum: ['solid', 'outline', 'ghost', 'soft'],
-      default: 'solid',
-      authoring: { authority: 'theme', scope: 'component' },
+      authoring: themeAuthoring,
     },
     size: {
       type: 'enum',
       category: 'Style',
       label: 'Size',
       enum: ['s', 'm', 'l'],
-      default: 'm',
-      authoring: { authority: 'theme', scope: 'component' },
+      authoring: themeAuthoring,
     },
   },
 } as const satisfies ZoraComponentMeta;

package/src/components/button/resolveButtonThemeRecipe.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveButtonThemeRecipe } from './resolveButtonThemeRecipe';
+
+describe('resolveButtonThemeRecipe', () => {
+  test('uses theme defaults without changing the existing hard default', () => {
+    expect(
+      resolveButtonThemeRecipe({ themeFields: { color: 'primary', variant: 'solid', size: 'l' } }),
+    ).toEqual({
+      color: 'primary',
+      variant: 'solid',
+      size: 'l',
+    });
+  });
+
+  test('lets explicit instance props override theme recipe values', () => {
+    expect(
+      resolveButtonThemeRecipe({
+        color: 'danger',
+        size: 's',
+        themeFields: { color: 'primary', variant: 'soft', size: 'l' },
+      }),
+    ).toEqual({ color: 'danger', variant: 'soft', size: 's' });
+  });
+});

package/src/components/button/resolveButtonThemeRecipe.ts

@@ -0,0 +1,41 @@
+import type { ThemeRecipeOverrideValue } from '@ankhorage/contracts';
+
+import {
+  resolveButtonRecipe,
+  type ZoraButtonVariant,
+  type ZoraColor,
+  type ZoraControlSize,
+} from '../../internal/recipes';
+
+export function resolveButtonThemeRecipe(input: {
+  readonly color?: ZoraColor;
+  readonly variant?: ZoraButtonVariant;
+  readonly size?: ZoraControlSize;
+  readonly themeFields: Readonly<Record<string, ThemeRecipeOverrideValue>>;
+}) {
+  return resolveButtonRecipe({
+    color: input.color ?? readColor(input.themeFields.color),
+    variant: input.variant ?? readVariant(input.themeFields.variant),
+    size: input.size ?? readSize(input.themeFields.size),
+  });
+}
+
+function readColor(value: ThemeRecipeOverrideValue | undefined): ZoraColor | undefined {
+  if (typeof value !== 'string') return undefined;
+  if (value === 'primary' || value === 'secondary' || value === 'tertiary') return value;
+  if (value === 'quaternary' || value === 'neutral' || value === 'danger') return value;
+  if (value === 'success' || value === 'warning' || value === 'error' || value === 'info')
+    return value;
+  return undefined;
+}
+
+function readVariant(value: ThemeRecipeOverrideValue | undefined): ZoraButtonVariant | undefined {
+  if (value === 'solid' || value === 'outline' || value === 'ghost' || value === 'soft')
+    return value;
+  return undefined;
+}
+
+function readSize(value: ThemeRecipeOverrideValue | undefined): ZoraControlSize | undefined {
+  if (value === 's' || value === 'm' || value === 'l') return value;
+  return undefined;
+}

package/src/components/button/themeRecipeMeta.ts

@@ -1,14 +1,15 @@
+import { ZORA_COLORS } from '../../internal/colorModel';
 import type { ZoraThemeRecipeMeta } from '../../metadata/themeRecipeTypes';
 
 export const buttonThemeRecipeMeta = {
   name: 'Button',
   kind: 'component',
-  description: 'Maps shared theme tokens and semantic choices into Button presentation.',
+  description: 'Maps shared semantic choices into Button presentation defaults.',
   fields: {
     color: {
-      type: 'token',
-      tokenFamily: 'colors',
+      type: 'choice',
       label: 'Color',
+      options: ZORA_COLORS,
       default: 'primary',
     },
     variant: {
@@ -22,13 +23,7 @@ export const buttonThemeRecipeMeta = {
       label: 'Size',
       description: 'A Button-specific semantic scale, not a universal pixel size.',
       options: ['s', 'm', 'l'],
-      default: 'm',
-    },
-    radius: {
-      type: 'token',
-      tokenFamily: 'radii',
-      label: 'Corner radius',
-      default: 'm',
+      default: 'l',
     },
   },
 } as const satisfies ZoraThemeRecipeMeta;

package/src/components/card/Card.tsx

@@ -3,9 +3,11 @@ import React from 'react';
 
 import { Box, Stack } from '../../foundation';
 import { resolveCardVariant } from '../../internal/recipes';
+import { useZoraThemeRecipe } from '../../theme/useZoraThemeRecipe';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { Heading } from '../heading';
 import { Text } from '../text';
+import { resolveCardThemeRecipe } from './resolveCardThemeRecipe';
 import type { CardProps } from './types';
 
 function CardInner({
@@ -17,15 +19,19 @@ function CardInner({
   eyebrow,
   actions,
   footer,
-  tone = 'default',
-  compact = false,
+  tone,
+  compact,
+  padding,
+  radius,
   onPress,
   interactionPolicy,
   ...props
 }: CardProps) {
+  const themeFields = useZoraThemeRecipe('Card');
+  const recipe = resolveCardThemeRecipe({ tone, compact, padding, radius, themeFields });
   const hasHeader = [eyebrow, title, description, actions].some((item) => item != null);
   const hasFooter = footer !== undefined;
-  const gap = compact ? 's' : 'm';
+  const gap = recipe.compact ? 's' : 'm';
   const isInteractive = Boolean(onPress) && !actions;
   const passive = interactionPolicy === 'passive';
 
@@ -33,9 +39,9 @@ function CardInner({
     <SurfaceCard
       {...props}
       onPress={isInteractive && !passive ? onPress : undefined}
-      p={compact ? 'm' : 'l'}
-      radius="l"
-      variant={resolveCardVariant(tone)}
+      p={recipe.padding}
+      radius={recipe.radius}
+      variant={resolveCardVariant(recipe.tone)}
     >
       <Stack gap={gap}>
         {hasHeader ? (
@@ -52,7 +58,7 @@ function CardInner({
                     {eyebrow}
                   </Text>
                 ) : null}
-                {title ? <Heading level={compact ? 4 : 3}>{title}</Heading> : null}
+                {title ? <Heading level={recipe.compact ? 4 : 3}>{title}</Heading> : null}
                 {description ? (
                   <Text emphasis="muted" variant="bodySmall">
                     {description}

package/src/components/card/meta.ts

@@ -1,18 +1,18 @@
 import type { ZoraComponentMeta } from '../../metadata';
 import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
 
+const themeAuthoring = {
+  authority: 'theme',
+  scope: 'component',
+  allowInstanceOverride: true,
+} as const;
+
 export const cardMeta = {
   name: 'Card',
   category: 'component',
   directManifestNode: true,
   allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
-  blueprint: {
-    label: 'Card',
-    defaultProps: {
-      title: 'Card',
-      tone: 'default',
-    },
-  },
+  blueprint: { label: 'Card', defaultProps: { title: 'Card' } },
   props: {
     title: {
       type: 'string',
@@ -37,15 +37,15 @@ export const cardMeta = {
       category: 'Style',
       label: 'Tone',
       enum: ['default', 'subtle', 'outline'],
-      default: 'default',
-      authoring: { authority: 'theme', scope: 'component' },
+      authoring: themeAuthoring,
     },
-    compact: {
-      type: 'boolean',
-      category: 'Layout',
-      label: 'Compact',
-      default: false,
-      authoring: { authority: 'theme', scope: 'component' },
+    compact: { type: 'boolean', category: 'Layout', label: 'Compact', authoring: themeAuthoring },
+    padding: { type: 'spacing', category: 'Layout', label: 'Padding', authoring: themeAuthoring },
+    radius: {
+      type: 'radius',
+      category: 'Style',
+      label: 'Corner radius',
+      authoring: themeAuthoring,
     },
   },
 } as const satisfies ZoraComponentMeta;

package/src/components/card/resolveCardThemeRecipe.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveCardThemeRecipe } from './resolveCardThemeRecipe';
+
+describe('resolveCardThemeRecipe', () => {
+  test('preserves compact-aware padding when theme padding is unset', () => {
+    expect(
+      resolveCardThemeRecipe({ themeFields: { tone: 'default', compact: true, radius: 'l' } }),
+    ).toEqual({
+      tone: 'default',
+      compact: true,
+      padding: 'm',
+      radius: 'l',
+    });
+  });
+
+  test('lets explicit instance props win over theme values', () => {
+    expect(
+      resolveCardThemeRecipe({
+        tone: 'outline',
+        compact: false,
+        padding: 'hero',
+        radius: 'pill',
+        themeFields: { tone: 'subtle', compact: true, padding: 'm', radius: 'l' },
+      }),
+    ).toEqual({ tone: 'outline', compact: false, padding: 'hero', radius: 'pill' });
+  });
+});

package/src/components/card/resolveCardThemeRecipe.ts

@@ -0,0 +1,33 @@
+import type { ThemeRecipeOverrideValue } from '@ankhorage/contracts';
+
+import type { ZoraCardTone } from '../../internal/recipes';
+
+export function resolveCardThemeRecipe(input: {
+  readonly tone?: ZoraCardTone;
+  readonly compact?: boolean;
+  readonly padding?: string;
+  readonly radius?: string;
+  readonly themeFields: Readonly<Record<string, ThemeRecipeOverrideValue>>;
+}) {
+  const tone = input.tone ?? readTone(input.themeFields.tone) ?? 'default';
+  const compact = input.compact ?? readBoolean(input.themeFields.compact) ?? false;
+  return {
+    tone,
+    compact,
+    padding: input.padding ?? readString(input.themeFields.padding) ?? (compact ? 'm' : 'l'),
+    radius: input.radius ?? readString(input.themeFields.radius) ?? 'l',
+  };
+}
+
+function readTone(value: ThemeRecipeOverrideValue | undefined): ZoraCardTone | undefined {
+  if (value === 'default' || value === 'subtle' || value === 'outline') return value;
+  return undefined;
+}
+
+function readBoolean(value: ThemeRecipeOverrideValue | undefined): boolean | undefined {
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+function readString(value: ThemeRecipeOverrideValue | undefined): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}

package/src/components/card/themeRecipeMeta.ts

@@ -15,7 +15,7 @@ export const cardThemeRecipeMeta = {
       type: 'token',
       tokenFamily: 'spacing',
       label: 'Padding',
-      default: 'l',
+      description: 'When unset, Card keeps its compact-aware spacing default.',
     },
     radius: {
       type: 'token',

package/src/components/card/types.ts

@@ -14,4 +14,6 @@ export interface CardProps
   footer?: React.ReactNode;
   tone?: ZoraCardTone;
   compact?: boolean;
+  padding?: string;
+  radius?: string;
 }

package/src/components/contentFallback.test.ts

@@ -9,15 +9,15 @@ const headingSource = readFileSync(join(import.meta.dir, 'heading', 'Heading.tsx
 describe('content fallback ownership', () => {
   it('keeps Text free of translation context coupling', () => {
     expect(textSource).not.toMatch(/useTranslationContext/);
-    expect(textSource).toMatch(/if \(children !== undefined\) \{/);
-    expect(textSource).toMatch(/if \(text !== undefined\) \{/);
+    expect(textSource).toMatch(/if \(children !== undefined\) return children;/);
+    expect(textSource).toMatch(/if \(text !== undefined\) return text;/);
     expect(textSource).toMatch(/return i18nKey;/);
   });
 
   it('keeps Heading free of translation context coupling', () => {
     expect(headingSource).not.toMatch(/useTranslationContext/);
-    expect(headingSource).toMatch(/if \(children !== undefined\) \{/);
-    expect(headingSource).toMatch(/if \(text !== undefined\) \{/);
+    expect(headingSource).toMatch(/if \(children !== undefined\) return children;/);
+    expect(headingSource).toMatch(/if \(text !== undefined\) return text;/);
     expect(headingSource).toMatch(/return i18nKey;/);
   });
 });

package/src/components/heading/Heading.tsx

@@ -3,8 +3,10 @@ import React from 'react';
 import { Platform, Text as ReactNativeText, type TextStyle } from 'react-native';
 
 import { useZoraTheme } from '../../theme/useZoraTheme';
+import { useZoraThemeRecipe } from '../../theme/useZoraThemeRecipe';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { resolveHeadingRecipe, resolveHeadingSizeFromLevel } from './resolveHeadingRecipe';
+import { resolveHeadingThemeRecipe } from './resolveHeadingThemeRecipe';
 import type { HeadingProps } from './types';
 
 const headingLayoutStyle = {
@@ -24,23 +26,10 @@ function resolveHeadingContent({
   children,
   text,
   i18nKey,
-}: {
-  children: HeadingProps['children'];
-  text: HeadingProps['text'];
-  i18nKey: HeadingProps['i18nKey'];
-}): React.ReactNode {
-  if (children !== undefined) {
-    return children;
-  }
-
-  if (text !== undefined) {
-    return text;
-  }
-
-  if (!i18nKey) {
-    return null;
-  }
-
+}: Pick<HeadingProps, 'children' | 'text' | 'i18nKey'>) {
+  if (children !== undefined) return children;
+  if (text !== undefined) return text;
+  if (i18nKey === undefined || i18nKey === '') return null;
   return i18nKey;
 }
 
@@ -53,10 +42,10 @@ function HeadingInner({
   level = 2,
   size,
   color,
-  emphasis = 'default',
+  emphasis,
   align,
   weight,
-  italic = false,
+  italic,
   numberOfLines,
   ellipsizeMode,
   selectable,
@@ -70,16 +59,17 @@ function HeadingInner({
 }: HeadingProps) {
   const { theme } = useZoraTheme();
   const { breakpoint } = useResponsiveRuntime();
+  const themeRecipe = resolveHeadingThemeRecipe(useZoraThemeRecipe('Heading'));
   const content = resolveHeadingContent({ children, text, i18nKey });
-  const resolvedSize = resolveResponsive(size, breakpoint) ?? resolveHeadingSizeFromLevel(level);
-  const resolvedColor = resolveResponsive(color, breakpoint);
-  const resolvedEmphasis = resolveResponsive(emphasis, breakpoint) ?? 'default';
-  const resolvedAlign = resolveResponsive(align, breakpoint);
-  const resolvedWeight = resolveResponsive(weight, breakpoint);
+  const resolvedSize =
+    resolveResponsive(size ?? themeRecipe.size, breakpoint) ?? resolveHeadingSizeFromLevel(level);
+  const resolvedColor = resolveResponsive(color ?? themeRecipe.color, breakpoint);
+  const resolvedEmphasis =
+    resolveResponsive(emphasis ?? themeRecipe.emphasis, breakpoint) ?? 'default';
+  const resolvedAlign = resolveResponsive(align ?? themeRecipe.align, breakpoint);
+  const resolvedWeight = resolveResponsive(weight ?? themeRecipe.weight, breakpoint);
 
-  if (content === null || content === undefined) {
-    return null;
-  }
+  if (content === null) return null;
 
   return (
     <ReactNativeText
@@ -95,7 +85,7 @@ function HeadingInner({
         headingLayoutStyle,
         resolveHeadingRecipe(theme, {
           align: resolvedAlign,
-          italic,
+          italic: italic ?? themeRecipe.italic ?? false,
           level,
           size: resolvedSize,
           color: resolvedColor,