@newtonedev/components 0.1.0 → 0.1.2

package/src/theme/types.ts

@@ -5,17 +5,34 @@ import type { DynamicRange, PaletteConfig } from 'newtone';
  */
 export type ColorMode = 'light' | 'dark';
 
+/**
+ * Font configuration for a single font slot
+ */
+export interface FontConfig {
+  readonly type: 'system' | 'google' | 'custom';
+  readonly family: string;       // 'ui-monospace' | 'Roboto' | custom name
+  readonly customUrl?: string;   // Supabase Storage URL for custom fonts
+  readonly fallback: string;     // CSS fallback stack
+}
+
 /**
  * Theme names for different UI contexts
  */
 export type ThemeName = 'neutral' | 'primary' | 'secondary' | 'strong';
 
 /**
- * Elevation levels for surfaces
+ * Elevation levels for surfaces (internal)
  * 0 = sunken, 1 = default, 2 = elevated
  */
 export type ElevationLevel = 0 | 1 | 2;
 
+/**
+ * User-facing elevation for Frame component
+ * -2 = deeply sunken (inset shadow), -1 = sunken, 0 = default,
+ * 1 = elevated, 2 = prominently elevated (drop shadow)
+ */
+export type FrameElevation = -2 | -1 | 0 | 1 | 2;
+
 /**
  * Theme mapping: which palette and normalizedValue to use for backgrounds/text
  * Based on playground theme preview logic
@@ -48,6 +65,54 @@ export interface NewtoneThemeConfig {
   readonly elevation: {
     readonly offsets: readonly [number, number, number]; // NV offsets for [sunken, default, elevated]
   };
+  readonly spacing: {
+    readonly xs: number;   // 4 * multiplier
+    readonly sm: number;   // 8 * multiplier
+    readonly md: number;   // 12 * multiplier
+    readonly lg: number;   // 16 * multiplier
+    readonly xl: number;   // 24 * multiplier
+    readonly xxl: number;  // 32 * multiplier
+  };
+  readonly radius: {
+    readonly none: number;    // 0
+    readonly sm: number;      // 4 * multiplier
+    readonly md: number;      // 6 * multiplier
+    readonly lg: number;      // 8 * multiplier
+    readonly xl: number;      // 12 * multiplier
+    readonly pill: 999;       // Fixed large value
+  };
+  readonly typography: {
+    readonly fonts: {
+      readonly mono: FontConfig;
+      readonly display: FontConfig;
+      readonly default: FontConfig;
+    };
+    readonly scale: {
+      readonly xs: number;    // baseSize / ratio^2
+      readonly sm: number;    // baseSize / ratio
+      readonly base: number;  // baseSize
+      readonly md: number;    // baseSize * ratio
+      readonly lg: number;    // baseSize * ratio^2
+      readonly xl: number;    // baseSize * ratio^3
+      readonly xxl: number;   // baseSize * ratio^4
+    };
+    readonly lineHeight: {
+      readonly tight: number;   // 1.25
+      readonly normal: number;  // 1.5
+      readonly relaxed: number; // 1.75
+    };
+    readonly fontWeight: {
+      readonly regular: number;  // 400
+      readonly medium: number;   // 500
+      readonly semibold: number; // 600
+      readonly bold: number;     // 700
+    };
+  };
+  readonly icons: {
+    readonly variant: 'outlined' | 'rounded' | 'sharp';
+    readonly weight: 100 | 200 | 300 | 400 | 500 | 600 | 700;
+    readonly autoGrade: boolean;  // true = mode-aware grade (light=-25, dark=200)
+  };
 }
 
 /**

package/src/tokens/computeTokens.ts

@@ -1,7 +1,16 @@
 import { getColor, getColorByContrast } from 'newtone';
-import type { ColorSystemConfig, ColorMode, ThemeMapping, ElevationLevel } from '../theme/types';
+import type { PaletteConfig } from 'newtone';
+import type { ColorSystemConfig, ColorMode, ThemeMapping, ElevationLevel, FontConfig } from '../theme/types';
 import type { ResolvedTokens } from './types';
 
+/**
+ * Convert FontConfig to CSS font-family string
+ */
+function fontConfigToFamily(font: FontConfig): string {
+  const family = font.family.includes(' ') ? `"${font.family}"` : font.family;
+  return `${family}, ${font.fallback}`;
+}
+
 /**
  * Compute design tokens for a specific mode/theme/elevation combination.
  *
@@ -14,6 +23,10 @@ import type { ResolvedTokens } from './types';
  * @param themeMapping - Theme configuration (which palette and NV to use)
  * @param elevation - Elevation level (0=sunken, 1=default, 2=elevated)
  * @param elevationOffsets - NV offsets for each elevation level
+ * @param spacing - Spacing scale for paddings, gaps, and margins
+ * @param radius - Border radius scale for component roundness
+ * @param typography - Typography configuration with fonts and scales
+ * @param icons - Icon configuration with variant, weight, and auto-grade setting
  * @returns Resolved design tokens with all necessary colors
  *
  * @example
@@ -23,7 +36,11 @@ import type { ResolvedTokens } from './types';
  *   'light',
  *   config.themes.neutral,
  *   1,
- *   config.elevation.offsets
+ *   config.elevation.offsets,
+ *   config.spacing,
+ *   config.radius,
+ *   config.typography,
+ *   config.icons
  * );
  * console.log(tokens.background.srgb); // { r: 0.95, g: 0.95, b: 0.95 }
  * ```
@@ -33,7 +50,20 @@ export function computeTokens(
   mode: ColorMode,
   themeMapping: ThemeMapping,
   elevation: ElevationLevel,
-  elevationOffsets: readonly [number, number, number]
+  elevationOffsets: readonly [number, number, number],
+  spacing: { readonly xs: number; readonly sm: number; readonly md: number; readonly lg: number; readonly xl: number; readonly xxl: number },
+  radius: { readonly none: number; readonly sm: number; readonly md: number; readonly lg: number; readonly xl: number; readonly pill: 999 },
+  typography: {
+    readonly fonts: { readonly mono: FontConfig; readonly display: FontConfig; readonly default: FontConfig };
+    readonly scale: { readonly xs: number; readonly sm: number; readonly base: number; readonly md: number; readonly lg: number; readonly xl: number; readonly xxl: number };
+    readonly lineHeight: { readonly tight: number; readonly normal: number; readonly relaxed: number };
+    readonly fontWeight: { readonly regular: number; readonly medium: number; readonly semibold: number; readonly bold: number };
+  },
+  icons: {
+    readonly variant: 'outlined' | 'rounded' | 'sharp';
+    readonly weight: 100 | 200 | 300 | 400 | 500 | 600 | 700;
+    readonly autoGrade: boolean;
+  }
 ): ResolvedTokens {
   const { dynamicRange, palettes } = config;
   const palette = palettes[themeMapping.paletteIndex];
@@ -84,7 +114,7 @@ export function computeTokens(
     palette.paletteHueGrading
   );
 
-  // Compute text colors with WCAG contrast requirements
+  // Compute text colors with WCAG contrast against actual background
   // Primary text: WCAG AA (4.5:1 for body text)
   const textPrimary = getColorByContrast(
     palette.hue,
@@ -93,7 +123,8 @@ export function computeTokens(
     4.5,
     effectiveTextMode,
     palette.desaturation,
-    palette.paletteHueGrading
+    palette.paletteHueGrading,
+    background,
   );
 
   // Secondary text: Lower contrast (3.0:1 for captions)
@@ -104,7 +135,8 @@ export function computeTokens(
     3.0,
     effectiveTextMode,
     palette.desaturation,
-    palette.paletteHueGrading
+    palette.paletteHueGrading,
+    background,
   );
 
   // Interactive colors: Use accent palette (index 1)
@@ -114,20 +146,35 @@ export function computeTokens(
     throw new Error('Accent palette (index 1) not found');
   }
 
-  // Interactive base: WCAG AA contrast against current background
-  const interactive = getColorByContrast(
-    accentPalette.hue,
-    accentPalette.saturation,
-    dynamicRange,
-    4.5,
-    effectiveTextMode,
-    accentPalette.desaturation,
-    accentPalette.paletteHueGrading
-  );
+  // Resolve per-mode key color: light mode uses keyNormalizedValue, dark uses keyNormalizedValueDark
+  const resolveKeyNv = (p: PaletteConfig): number | undefined =>
+    mode === 'dark' ? p.keyNormalizedValueDark : p.keyNormalizedValue;
+
+  // Interactive base: use user-chosen key color or auto WCAG AA contrast
+  const accentKeyNv = resolveKeyNv(accentPalette);
+  const interactive = accentKeyNv !== undefined
+    ? getColor(
+        accentPalette.hue,
+        accentPalette.saturation,
+        dynamicRange,
+        accentKeyNv,
+        accentPalette.desaturation,
+        accentPalette.paletteHueGrading
+      )
+    : getColorByContrast(
+        accentPalette.hue,
+        accentPalette.saturation,
+        dynamicRange,
+        4.5,
+        effectiveTextMode,
+        accentPalette.desaturation,
+        accentPalette.paletteHueGrading,
+        background,
+      );
 
   // Hover/active states: Shift NV slightly from interactive base
   // In light mode (light bg), go darker; in dark mode (dark bg), go lighter
-  const interactiveNv = effectiveTextMode === 'light' ? 0.3 : 0.7;
+  const interactiveNv = accentKeyNv ?? (effectiveTextMode === 'light' ? 0.3 : 0.7);
 
   const interactiveHover = getColor(
     accentPalette.hue,
@@ -159,45 +206,36 @@ export function computeTokens(
   );
 
   // Semantic status colors: success (palette 2), warning (palette 3), error (palette 4)
-  // Each computed at WCAG AA contrast against the mode background, same as interactive
+  // Each computed at WCAG AA contrast against actual background
   const successPalette = palettes[2];
   const warningPalette = palettes[3];
   const errorPalette = palettes[4];
 
+  const successKeyNv = successPalette ? resolveKeyNv(successPalette) : undefined;
   const success = successPalette
-    ? getColorByContrast(
-        successPalette.hue,
-        successPalette.saturation,
-        dynamicRange,
-        4.5,
-        effectiveTextMode,
-        successPalette.desaturation,
-        successPalette.paletteHueGrading
-      )
-    : interactive; // Fallback to interactive if palette missing
+    ? (successKeyNv !== undefined
+        ? getColor(successPalette.hue, successPalette.saturation, dynamicRange,
+            successKeyNv, successPalette.desaturation, successPalette.paletteHueGrading)
+        : getColorByContrast(successPalette.hue, successPalette.saturation, dynamicRange,
+            4.5, effectiveTextMode, successPalette.desaturation, successPalette.paletteHueGrading, background))
+    : interactive;
 
+  const warningKeyNv = warningPalette ? resolveKeyNv(warningPalette) : undefined;
   const warning = warningPalette
-    ? getColorByContrast(
-        warningPalette.hue,
-        warningPalette.saturation,
-        dynamicRange,
-        4.5,
-        effectiveTextMode,
-        warningPalette.desaturation,
-        warningPalette.paletteHueGrading
-      )
+    ? (warningKeyNv !== undefined
+        ? getColor(warningPalette.hue, warningPalette.saturation, dynamicRange,
+            warningKeyNv, warningPalette.desaturation, warningPalette.paletteHueGrading)
+        : getColorByContrast(warningPalette.hue, warningPalette.saturation, dynamicRange,
+            4.5, effectiveTextMode, warningPalette.desaturation, warningPalette.paletteHueGrading, background))
     : interactive;
 
+  const errorKeyNv = errorPalette ? resolveKeyNv(errorPalette) : undefined;
   const error = errorPalette
-    ? getColorByContrast(
-        errorPalette.hue,
-        errorPalette.saturation,
-        dynamicRange,
-        4.5,
-        effectiveTextMode,
-        errorPalette.desaturation,
-        errorPalette.paletteHueGrading
-      )
+    ? (errorKeyNv !== undefined
+        ? getColor(errorPalette.hue, errorPalette.saturation, dynamicRange,
+            errorKeyNv, errorPalette.desaturation, errorPalette.paletteHueGrading)
+        : getColorByContrast(errorPalette.hue, errorPalette.saturation, dynamicRange,
+            4.5, effectiveTextMode, errorPalette.desaturation, errorPalette.paletteHueGrading, background))
     : interactive;
 
   return {
@@ -213,5 +251,24 @@ export function computeTokens(
     success,
     warning,
     error,
+    spacing,
+    radius,
+    typography: {
+      fonts: {
+        mono: fontConfigToFamily(typography.fonts.mono),
+        display: fontConfigToFamily(typography.fonts.display),
+        default: fontConfigToFamily(typography.fonts.default),
+      },
+      size: typography.scale,
+      lineHeight: typography.lineHeight,
+      weight: typography.fontWeight,
+    },
+    icons: {
+      variant: icons.variant,
+      weight: icons.weight,
+      grade: icons.autoGrade
+        ? (mode === 'light' ? -25 : 200)
+        : 0,
+    },
   };
 }

package/src/tokens/types.ts

@@ -28,4 +28,56 @@ export interface ResolvedTokens {
   readonly warning: ColorResult;
   /** Error/destructive state color (from error palette, index 4) */
   readonly error: ColorResult;
+  /** Spacing tokens for paddings, gaps, and margins */
+  readonly spacing: {
+    readonly xs: number;
+    readonly sm: number;
+    readonly md: number;
+    readonly lg: number;
+    readonly xl: number;
+    readonly xxl: number;
+  };
+  /** Border radius tokens for component roundness */
+  readonly radius: {
+    readonly none: number;
+    readonly sm: number;
+    readonly md: number;
+    readonly lg: number;
+    readonly xl: number;
+    readonly pill: 999;
+  };
+  /** Typography tokens for fonts, sizes, line heights, and weights */
+  readonly typography: {
+    readonly fonts: {
+      readonly mono: string;      // CSS font-family string
+      readonly display: string;   // CSS font-family string
+      readonly default: string;   // CSS font-family string
+    };
+    readonly size: {
+      readonly xs: number;
+      readonly sm: number;
+      readonly base: number;
+      readonly md: number;
+      readonly lg: number;
+      readonly xl: number;
+      readonly xxl: number;
+    };
+    readonly lineHeight: {
+      readonly tight: number;
+      readonly normal: number;
+      readonly relaxed: number;
+    };
+    readonly weight: {
+      readonly regular: number;
+      readonly medium: number;
+      readonly semibold: number;
+      readonly bold: number;
+    };
+  };
+  /** Icon tokens for Material Symbols configuration */
+  readonly icons: {
+    readonly variant: 'outlined' | 'rounded' | 'sharp';
+    readonly weight: 100 | 200 | 300 | 400 | 500 | 600 | 700;
+    readonly grade: -25 | 0 | 200;  // Mode-aware: light=-25, dark=200
+  };
 }

package/src/tokens/useTokens.ts

@@ -1,5 +1,6 @@
 import { useMemo } from 'react';
 import { useNewtoneTheme } from '../theme/NewtoneProvider';
+import { useFrameContext } from '../theme/FrameContext';
 import { computeTokens } from './computeTokens';
 import type { ElevationLevel } from '../theme/types';
 import type { ResolvedTokens } from './types';
@@ -7,36 +8,50 @@ import type { ResolvedTokens } from './types';
 /**
  * Hook to compute design tokens for the current theme/mode/elevation.
  *
- * This hook automatically recomputes tokens when the theme configuration,
- * mode, theme name, or elevation changes. Results are memoized to avoid
- * unnecessary computation.
+ * Resolution order:
+ * 1. Explicit elevation parameter takes highest priority
+ * 2. FrameContext values (from nearest parent Frame) are used when elevation is omitted
+ * 3. Falls back to NewtoneProvider theme + elevation 1
  *
- * @param elevation - Elevation level (0=sunken, 1=default, 2=elevated)
+ * Theme always reads from FrameContext if present, falling back to NewtoneProvider.
+ *
+ * @param elevation - Elevation level (0=sunken, 1=default, 2=elevated).
+ *                    When omitted, reads from FrameContext or defaults to 1.
  * @returns Resolved design tokens with all necessary colors
  *
  * @example
  * ```tsx
- * function Button() {
- *   const tokens = useTokens(1); // Default elevation
+ * // Inside a <Frame theme="primary" elevation={1}>:
+ * function MyComponent() {
+ *   const tokens = useTokens(); // Gets primary theme, elevation 2 (mapped from Frame's 1)
  *   return (
- *     <button style={{ backgroundColor: srgbToHex(tokens.interactive.srgb) }}>
- *       Click me
- *     </button>
+ *     <View style={{ backgroundColor: srgbToHex(tokens.background.srgb) }} />
  *   );
  * }
  * ```
  */
-export function useTokens(elevation: ElevationLevel = 1): ResolvedTokens {
-  const { config, mode, theme } = useNewtoneTheme();
+export function useTokens(elevation?: ElevationLevel): ResolvedTokens {
+  const { config, mode, theme: providerTheme } = useNewtoneTheme();
+  const frameCtx = useFrameContext();
+
+  // Resolve theme: FrameContext overrides provider
+  const resolvedTheme = frameCtx?.theme ?? providerTheme;
+
+  // Resolve elevation: explicit param > FrameContext > default 1
+  const resolvedElevation: ElevationLevel = elevation ?? frameCtx?.elevation ?? 1;
 
   return useMemo(() => {
-    const themeMapping = config.themes[theme];
+    const themeMapping = config.themes[resolvedTheme];
     return computeTokens(
       config.colorSystem,
       mode,
       themeMapping,
-      elevation,
-      config.elevation.offsets
+      resolvedElevation,
+      config.elevation.offsets,
+      config.spacing,
+      config.radius,
+      config.typography,
+      config.icons
     );
-  }, [config, mode, theme, elevation]);
+  }, [config, mode, resolvedTheme, resolvedElevation]);
 }