@newtonedev/configurator 0.1.0 → 0.1.2

package/dist/types.d.ts

@@ -1,5 +1,7 @@
 import type { DesaturationStrength, HueGradingStrength } from 'newtone';
 import type { ColorMode, ThemeName } from '@newtonedev/components';
+/** Spacing preset options */
+export type SpacingPreset = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 /** Per-palette state in the configurator (human-readable, traditional hues) */
 export interface PaletteState {
     readonly name: string;
@@ -10,12 +12,21 @@ export interface PaletteState {
     readonly hueGradeStrength: HueGradingStrength;
     readonly hueGradeHue: number;
     readonly hueGradeDirection: 'light' | 'dark';
+    readonly keyColor?: number;
+    readonly keyColorDark?: number;
 }
 /** Global hue grading endpoint state */
 export interface HueGradingEndpointState {
     readonly strength: HueGradingStrength;
     readonly hue: number;
 }
+/** Font configuration for a single font slot */
+export interface FontConfig {
+    readonly type: 'system' | 'google' | 'custom';
+    readonly family: string;
+    readonly customUrl?: string;
+    readonly fallback: string;
+}
 /** Complete configurator state */
 export interface ConfiguratorState {
     readonly palettes: readonly PaletteState[];
@@ -31,5 +42,27 @@ export interface ConfiguratorState {
         readonly mode: ColorMode;
         readonly theme: ThemeName;
     };
+    readonly spacing?: {
+        readonly preset: SpacingPreset;
+    };
+    readonly roundness?: {
+        readonly intensity: number;
+    };
+    readonly typography?: {
+        readonly fonts: {
+            readonly mono: FontConfig;
+            readonly display: FontConfig;
+            readonly default: FontConfig;
+        };
+        readonly scale: {
+            readonly baseSize: number;
+            readonly ratio: number;
+        };
+    };
+    readonly icons?: {
+        readonly variant: 'outlined' | 'rounded' | 'sharp';
+        readonly weight: 100 | 200 | 300 | 400 | 500 | 600 | 700;
+        readonly autoGrade: boolean;
+    };
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnE,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,oBAAoB,EAAE,oBAAoB,CAAC;IACpD,QAAQ,CAAC,qBAAqB,EAAE,OAAO,GAAG,MAAM,CAAC;IACjD,QAAQ,CAAC,gBAAgB,EAAE,kBAAkB,CAAC;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,iBAAiB,EAAE,OAAO,GAAG,MAAM,CAAC;CAC9C;AAED,wCAAwC;AACxC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,kCAAkC;AAClC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE;QACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,QAAQ,CAAC,gBAAgB,EAAE;QACzB,QAAQ,CAAC,KAAK,EAAE,uBAAuB,CAAC;QACxC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;KACxC,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;QACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;KAC3B,CAAC;CACH"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newtonedev/configurator",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Embeddable palette builder widget for Newtone color systems",
   "license": "MIT",
   "repository": {

package/src/Configurator.tsx

@@ -9,6 +9,7 @@ import { PalettePanel } from './panels/PalettePanel';
 import { GlobalPanel } from './panels/GlobalPanel';
 import { PreviewPanel } from './panels/PreviewPanel';
 import { ExportPanel } from './panels/ExportPanel';
+import { DesignPanel } from './panels/DesignPanel';
 
 /**
  * Newtone Configurator — embeddable palette builder widget.
@@ -74,6 +75,11 @@ export function Configurator({
         )}
       </View>
 
+      {/* Design System controls */}
+      <View style={styles.designRow}>
+        <DesignPanel state={state} dispatch={dispatch} />
+      </View>
+
       {/* Palette tab bar */}
       <View style={styles.tabBar}>
         {state.palettes.map((palette, index) => (
@@ -115,6 +121,7 @@ export function Configurator({
         index={activePaletteIndex}
         dispatch={dispatch}
         previewColors={previews[activePaletteIndex]}
+        state={state}
       />
 
       {showExport && <ExportPanel state={state} />}
@@ -160,6 +167,9 @@ const styles = StyleSheet.create({
   topRowPanel: {
     flex: 1,
   },
+  designRow: {
+    marginBottom: 4,
+  },
   tabBar: {
     flexDirection: 'row',
     gap: 4,

package/src/bridge/toCSS.ts

@@ -20,6 +20,10 @@ export function toCSS(state: ConfiguratorState): string {
       config.themes.neutral,
       1,
       config.elevation.offsets,
+      config.spacing,
+      config.radius,
+      config.typography,
+      config.icons
     );
 
     const selector = mode === 'light' ? ':root' : '[data-theme="dark"]';

package/src/bridge/toThemeConfig.ts

@@ -1,8 +1,72 @@
-import type { ConfiguratorState } from '../types';
-import type { NewtoneThemeConfig } from '@newtonedev/components';
+import type { ConfiguratorState, SpacingPreset } from '../types';
+import type { NewtoneThemeConfig, FontConfig } from '@newtonedev/components';
 import type { PaletteConfig, DynamicRange, HueGrading, HueGradingEndpoint } from 'newtone';
 import { traditionalHueToOklch } from '../hue-conversion';
 
+/**
+ * Spacing preset to base pixel value mapping
+ */
+const SPACING_PRESET_TO_BASE: Record<SpacingPreset, number> = {
+  xs: 6,   // Extra Small: compact/dense UI
+  sm: 7,   // Small: tighter spacing
+  md: 8,   // Medium: default/balanced
+  lg: 9,   // Large: more spacious
+  xl: 10,  // Extra Large: maximum spacing
+};
+
+/**
+ * Convert roundness intensity [0, 1] to radius multiplier [0, 2.0]
+ */
+function roundnessToMultiplier(intensity: number): number {
+  return intensity * 2.0;  // lerp(0, 2.0, intensity)
+}
+
+/**
+ * Compute typography scale from base size and ratio.
+ * Uses modular scale: baseSize * ratio^n
+ */
+function computeTypographyScale(baseSize: number, ratio: number) {
+  return {
+    xs: Math.round(baseSize / (ratio ** 2)),
+    sm: Math.round(baseSize / ratio),
+    base: baseSize,
+    md: Math.round(baseSize * ratio),
+    lg: Math.round(baseSize * (ratio ** 2)),
+    xl: Math.round(baseSize * (ratio ** 3)),
+    xxl: Math.round(baseSize * (ratio ** 4)),
+  };
+}
+
+/**
+ * Default font configurations using system fonts
+ */
+const DEFAULT_FONTS: { readonly mono: FontConfig; readonly display: FontConfig; readonly default: FontConfig } = {
+  mono: {
+    type: 'system',
+    family: 'ui-monospace',
+    fallback: 'SFMono-Regular, Menlo, Monaco, Consolas, monospace',
+  },
+  display: {
+    type: 'system',
+    family: 'system-ui',
+    fallback: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+  },
+  default: {
+    type: 'system',
+    family: 'system-ui',
+    fallback: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+  },
+};
+
+/**
+ * Default icon configuration using Material Symbols Rounded
+ */
+const DEFAULT_ICONS = {
+  variant: 'rounded' as const,  // Material Design 3 aesthetic
+  weight: 400 as const,          // Normal weight
+  autoGrade: true,               // Enable mode-aware grade
+};
+
 /**
  * Convert configurator state (traditional hues, human-readable controls)
  * to a NewtoneThemeConfig (OKLCH hues, engine-ready format).
@@ -23,7 +87,14 @@ export function toThemeConfig(state: ConfiguratorState): NewtoneThemeConfig {
         } as const
       : undefined;
 
-    return { hue: oklchHue, saturation: p.saturation, desaturation, paletteHueGrading };
+    return {
+      hue: oklchHue,
+      saturation: p.saturation,
+      desaturation,
+      paletteHueGrading,
+      ...(p.keyColor !== undefined ? { keyNormalizedValue: p.keyColor } : {}),
+      ...(p.keyColorDark !== undefined ? { keyNormalizedValueDark: p.keyColorDark } : {}),
+    };
   });
 
   // Build global hue grading
@@ -43,6 +114,12 @@ export function toThemeConfig(state: ConfiguratorState): NewtoneThemeConfig {
     ...(hueGrading ? { hueGrading } : {}),
   };
 
+  // Compute spacing base from preset (default 'md' = 8px base)
+  const spacingBase = SPACING_PRESET_TO_BASE[state.spacing?.preset ?? 'md'];
+
+  // Compute radius multiplier from roundness intensity slider (default 0.5 = 1.0x multiplier)
+  const radiusMultiplier = roundnessToMultiplier(state.roundness?.intensity ?? 0.5);
+
   return {
     colorSystem: { dynamicRange, palettes },
     themes: {
@@ -54,5 +131,38 @@ export function toThemeConfig(state: ConfiguratorState): NewtoneThemeConfig {
     elevation: {
       offsets: [-0.02, 0, 0.04] as const,
     },
+    spacing: {
+      '00': Math.round(spacingBase * 0),      // Always 0
+      '02': Math.round(spacingBase * 0.25),
+      '04': Math.round(spacingBase * 0.5),
+      '06': Math.round(spacingBase * 0.75),
+      '08': Math.round(spacingBase * 1),      // Equals base
+      '10': Math.round(spacingBase * 1.25),
+      '12': Math.round(spacingBase * 1.5),
+      '16': Math.round(spacingBase * 2),
+      '20': Math.round(spacingBase * 2.5),
+      '24': Math.round(spacingBase * 3),
+      '32': Math.round(spacingBase * 4),
+      '40': Math.round(spacingBase * 5),
+      '48': Math.round(spacingBase * 6),
+    },
+    radius: {
+      none: 0,
+      sm: Math.round(4 * radiusMultiplier),
+      md: Math.round(6 * radiusMultiplier),
+      lg: Math.round(8 * radiusMultiplier),
+      xl: Math.round(12 * radiusMultiplier),
+      pill: 999,
+    },
+    typography: {
+      fonts: state.typography?.fonts ?? DEFAULT_FONTS,
+      scale: computeTypographyScale(
+        state.typography?.scale.baseSize ?? 16,
+        state.typography?.scale.ratio ?? 1.25
+      ),
+      lineHeight: { tight: 1.25, normal: 1.5, relaxed: 1.75 },
+      fontWeight: { regular: 400, medium: 500, semibold: 600, bold: 700 },
+    },
+    icons: state.icons ?? DEFAULT_ICONS,
   };
 }

package/src/hex-conversion.ts

@@ -0,0 +1,99 @@
+import {
+  hexToSrgb,
+  srgbToOklch,
+  findMaxChromaInGamut,
+  lightnessToNormalizedValue,
+} from 'newtone';
+import type { DynamicRange } from 'newtone';
+import { traditionalHueToOklch } from './hue-conversion';
+
+/** Result of decomposing a hex color into palette parameters */
+export interface HexPaletteParams {
+  /** Traditional HSL hue [0, 359] */
+  readonly hue: number;
+  /** Saturation as % of max in-gamut chroma [0, 100] */
+  readonly saturation: number;
+  /** Position on the luminosity scale [0, 1] */
+  readonly normalizedValue: number;
+}
+
+// Achromatic threshold — below this chroma, the color has no meaningful hue
+const ACHROMATIC_THRESHOLD = 0.005;
+
+// Lookup table for OKLCH hue → traditional hue (built once, lazily)
+let traditionalHueLut: readonly number[] | null = null;
+
+function buildTraditionalHueLut(): readonly number[] {
+  const lut: number[] = new Array(360);
+  for (let h = 0; h < 360; h++) {
+    lut[h] = traditionalHueToOklch(h);
+  }
+  return lut;
+}
+
+/**
+ * Convert an OKLCH hue back to the nearest traditional HSL hue.
+ * Uses a precomputed lookup table with 1° resolution.
+ */
+export function oklchHueToTraditional(oklchHue: number): number {
+  if (!traditionalHueLut) {
+    traditionalHueLut = buildTraditionalHueLut();
+  }
+
+  const target = ((oklchHue % 360) + 360) % 360;
+  let bestHue = 0;
+  let bestDelta = Infinity;
+
+  for (let h = 0; h < 360; h++) {
+    // Shortest angular distance
+    const raw = Math.abs(traditionalHueLut[h] - target);
+    const delta = Math.min(raw, 360 - raw);
+    if (delta < bestDelta) {
+      bestDelta = delta;
+      bestHue = h;
+    }
+  }
+
+  return bestHue;
+}
+
+/**
+ * Decompose a hex color string into palette parameters (hue, saturation, luminosity).
+ *
+ * Returns null if the hex string is invalid.
+ *
+ * @param hex - Hex color string (e.g., "#FF0000", "#f00", "FF0000")
+ * @param dynamicRange - Current dynamic range for normalizedValue mapping
+ */
+export function hexToPaletteParams(
+  hex: string,
+  dynamicRange: DynamicRange,
+): HexPaletteParams | null {
+  // Validate hex format
+  const cleaned = hex.startsWith('#') ? hex.slice(1) : hex;
+  if (!/^[0-9a-fA-F]{3}$/.test(cleaned) && !/^[0-9a-fA-F]{6}$/.test(cleaned)) {
+    return null;
+  }
+
+  const srgb = hexToSrgb(hex);
+  const oklch = srgbToOklch(srgb);
+
+  // Map OKLCH lightness to normalizedValue within the dynamic range
+  const normalizedValue = lightnessToNormalizedValue(dynamicRange, oklch.L);
+
+  // Achromatic case: no meaningful hue
+  if (oklch.C < ACHROMATIC_THRESHOLD) {
+    return { hue: 0, saturation: 0, normalizedValue };
+  }
+
+  // Reverse-map OKLCH hue to traditional hue
+  const hue = oklchHueToTraditional(oklch.h);
+
+  // Compute saturation as percentage of max available chroma at this L and h
+  const maxChroma = findMaxChromaInGamut(oklch.L, oklch.h);
+  const saturation = maxChroma > 0
+    ? Math.min(100, Math.round(oklch.C / maxChroma * 100))
+    : 0;
+
+  return { hue, saturation, normalizedValue };
+}

package/src/hooks/useWcagValidation.ts

@@ -0,0 +1,111 @@
+import { useMemo } from 'react';
+import {
+  getColor,
+  getColorByContrast,
+  getWcagContrastRatio,
+  lightnessToNormalizedValue,
+} from 'newtone';
+import type { DynamicRange } from 'newtone';
+import type { ConfiguratorState } from '../types';
+import { traditionalHueToOklch } from '../hue-conversion';
+
+export interface WcagValidation {
+  /** WCAG contrast ratio at the key color position (null if no keyColor set) */
+  readonly keyColorContrast: number | null;
+  /** Whether the key color passes WCAG AA for normal text (>= 4.5:1) */
+  readonly passesAA: boolean;
+  /** Whether the key color passes WCAG AA for large text (>= 3:1) */
+  readonly passesAALargeText: boolean;
+  /** The normalizedValue where auto contrast search would place the key color */
+  readonly autoNormalizedValue: number;
+}
+
+/**
+ * Compute WCAG validation info for a non-neutral palette's key color.
+ *
+ * Validates the palette's key color against the neutral background
+ * in the current preview mode. Also computes where the auto contrast
+ * search would place the key color (for showing the default position).
+ */
+export function useWcagValidation(
+  state: ConfiguratorState,
+  paletteIndex: number,
+): WcagValidation {
+  return useMemo(() => {
+    const palette = state.palettes[paletteIndex];
+    const neutral = state.palettes[0];
+    if (!palette || !neutral) {
+      return { keyColorContrast: null, passesAA: true, passesAALargeText: true, autoNormalizedValue: 0.5 };
+    }
+
+    const mode = state.preview.mode;
+
+    // Build dynamic range with global hue grading
+    const light = state.globalHueGrading.light.strength !== 'none'
+      ? { hue: traditionalHueToOklch(state.globalHueGrading.light.hue), strength: state.globalHueGrading.light.strength }
+      : undefined;
+    const dark = state.globalHueGrading.dark.strength !== 'none'
+      ? { hue: traditionalHueToOklch(state.globalHueGrading.dark.hue), strength: state.globalHueGrading.dark.strength }
+      : undefined;
+    const hueGrading = (light || dark) ? { light, dark } : undefined;
+
+    const dynamicRange: DynamicRange = {
+      lightest: state.dynamicRange.lightest,
+      darkest: state.dynamicRange.darkest,
+      ...(hueGrading ? { hueGrading } : {}),
+    };
+
+    // Compute neutral background for the current preview mode
+    const neutralOklchHue = traditionalHueToOklch(neutral.hue);
+    const neutralDesat = neutral.desaturationStrength !== 'none'
+      ? { direction: neutral.desaturationDirection, strength: neutral.desaturationStrength } as const
+      : undefined;
+    const neutralPhg = neutral.hueGradeStrength !== 'none'
+      ? { hue: traditionalHueToOklch(neutral.hueGradeHue), strength: neutral.hueGradeStrength, direction: neutral.hueGradeDirection } as const
+      : undefined;
+
+    const backgroundNv = mode === 'light' ? 0.95 : 0.1;
+    const background = getColor(neutralOklchHue, neutral.saturation, dynamicRange, backgroundNv, neutralDesat, neutralPhg);
+
+    // Build palette engine params
+    const paletteOklchHue = traditionalHueToOklch(palette.hue);
+    const effectiveTextMode = mode === 'light' ? 'light' as const : 'dark' as const;
+    const paletteDesat = palette.desaturationStrength !== 'none'
+      ? { direction: palette.desaturationDirection, strength: palette.desaturationStrength } as const
+      : undefined;
+    const palettePhg = palette.hueGradeStrength !== 'none'
+      ? { hue: traditionalHueToOklch(palette.hueGradeHue), strength: palette.hueGradeStrength, direction: palette.hueGradeDirection } as const
+      : undefined;
+
+    // Compute auto position: where contrast search would place the key color
+    const autoColor = getColorByContrast(
+      paletteOklchHue, palette.saturation, dynamicRange,
+      4.5, effectiveTextMode, paletteDesat, palettePhg, background,
+    );
+    const autoNormalizedValue = lightnessToNormalizedValue(dynamicRange, autoColor.oklch.L);
+
+    // Resolve per-mode key color: light mode uses keyColor, dark uses keyColorDark
+    const effectiveKeyColor = mode === 'dark' ? palette.keyColorDark : palette.keyColor;
+
+    // If no key color set for this mode, everything passes (auto is always WCAG-compliant)
+    if (effectiveKeyColor === undefined) {
+      return { keyColorContrast: null, passesAA: true, passesAALargeText: true, autoNormalizedValue };
+    }
+
+    // Compute the actual color at the user-chosen key position for this mode
+    const keyColor = getColor(
+      paletteOklchHue, palette.saturation, dynamicRange,
+      effectiveKeyColor, paletteDesat, palettePhg,
+    );
+
+    // Compute WCAG contrast against the neutral background
+    const contrast = getWcagContrastRatio(keyColor.srgb, background.srgb);
+
+    return {
+      keyColorContrast: contrast,
+      passesAA: contrast >= 4.5,
+      passesAALargeText: contrast >= 3.0,
+      autoNormalizedValue,
+    };
+  }, [state, paletteIndex]);
+}

package/src/index.ts

@@ -3,7 +3,7 @@ export { Configurator } from './Configurator';
 export type { ConfiguratorProps } from './Configurator.types';
 
 // State types
-export type { ConfiguratorState, PaletteState, HueGradingEndpointState } from './types';
+export type { ConfiguratorState, PaletteState, HueGradingEndpointState, SpacingPreset } from './types';
 export type { ConfiguratorAction } from './state/actions';
 
 // Bridge functions (for headless usage)
@@ -12,13 +12,20 @@ export { toCSS } from './bridge/toCSS';
 export { toJSON } from './bridge/toJSON';
 export type { ConfiguratorExport } from './bridge/toJSON';
 
-// Hue conversion utility
+// Hue conversion utilities
 export { traditionalHueToOklch } from './hue-conversion';
+export { oklchHueToTraditional, hexToPaletteParams } from './hex-conversion';
+export type { HexPaletteParams } from './hex-conversion';
 
 // Defaults
 export { DEFAULT_CONFIGURATOR_STATE } from './state/defaults';
 
+// Constants
+export { SEMANTIC_HUE_RANGES } from './constants';
+
 // Hooks (for custom configurator UIs)
 export { useConfigurator } from './hooks/useConfigurator';
 export type { UseConfiguratorResult } from './hooks/useConfigurator';
 export { usePreviewColors } from './hooks/usePreviewColors';
+export { useWcagValidation } from './hooks/useWcagValidation';
+export type { WcagValidation } from './hooks/useWcagValidation';

package/src/panels/DesignPanel.tsx

@@ -0,0 +1,149 @@
+import React from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { Card, Slider, Select, useTokens } from '@newtonedev/components';
+import { srgbToHex } from 'newtone';
+import type { ConfiguratorState, SpacingPreset } from '../types';
+import type { ConfiguratorAction } from '../state/actions';
+
+const ICON_VARIANT_OPTIONS = [
+  { label: 'Outlined', value: 'outlined' },
+  { label: 'Rounded', value: 'rounded' },
+  { label: 'Sharp', value: 'sharp' },
+];
+
+const ICON_WEIGHT_OPTIONS = [
+  { label: '100', value: '100' },
+  { label: '200', value: '200' },
+  { label: '300', value: '300' },
+  { label: '400', value: '400' },
+  { label: '500', value: '500' },
+  { label: '600', value: '600' },
+  { label: '700', value: '700' },
+];
+
+interface DesignPanelProps {
+  readonly state: ConfiguratorState;
+  readonly dispatch: (action: ConfiguratorAction) => void;
+}
+
+export function DesignPanel({ state, dispatch }: DesignPanelProps) {
+  const tokens = useTokens(1);
+
+  const spacingPreset = state.spacing?.preset ?? 'md';
+  const intensity = state.roundness?.intensity ?? 0.5;
+  const baseSize = state.typography?.scale.baseSize ?? 16;
+  const ratio = state.typography?.scale.ratio ?? 1.25;
+  const variant = state.icons?.variant ?? 'rounded';
+  const weight = state.icons?.weight ?? 400;
+  return (
+    <Card elevation={1} style={styles.container}>
+      <Text style={[styles.title, { color: srgbToHex(tokens.textPrimary.srgb) }]}>
+        Design System
+      </Text>
+
+      {/* Spacing Section */}
+      <Text style={[styles.subtitle, { color: srgbToHex(tokens.textSecondary.srgb) }]}>
+        Spacing
+      </Text>
+      <Select
+        value={spacingPreset}
+        onValueChange={(preset) => dispatch({ type: 'SET_SPACING_PRESET', preset: preset as SpacingPreset })}
+        options={[
+          { value: 'xs', label: 'Extra Small' },
+          { value: 'sm', label: 'Small' },
+          { value: 'md', label: 'Medium' },
+          { value: 'lg', label: 'Large' },
+          { value: 'xl', label: 'Extra Large' },
+        ]}
+        label="Preset"
+      />
+
+      {/* Roundness Section */}
+      <Text style={[styles.subtitle, { color: srgbToHex(tokens.textSecondary.srgb) }]}>
+        Roundness
+      </Text>
+      <Slider
+        value={Math.round(intensity * 100)}
+        onValueChange={(v) => dispatch({ type: 'SET_ROUNDNESS_INTENSITY', intensity: v / 100 })}
+        min={0}
+        max={100}
+        label="Intensity"
+        showValue
+      />
+
+      {/* Typography Section */}
+      <Text style={[styles.subtitle, { color: srgbToHex(tokens.textSecondary.srgb) }]}>
+        Typography
+      </Text>
+      <View style={styles.row}>
+        <View style={styles.flex}>
+          <Slider
+            value={baseSize}
+            onValueChange={(v) => dispatch({ type: 'SET_TYPOGRAPHY_BASE_SIZE', baseSize: v })}
+            min={12}
+            max={24}
+            step={1}
+            label="Base Size"
+            showValue
+          />
+        </View>
+        <View style={styles.flex}>
+          <Slider
+            value={Math.round(ratio * 100)}
+            onValueChange={(v) => dispatch({ type: 'SET_TYPOGRAPHY_RATIO', ratio: v / 100 })}
+            min={110}
+            max={150}
+            step={5}
+            label="Scale Ratio"
+            showValue
+          />
+        </View>
+      </View>
+
+      {/* Icons Section */}
+      <Text style={[styles.subtitle, { color: srgbToHex(tokens.textSecondary.srgb) }]}>
+        Icons
+      </Text>
+      <View style={styles.row}>
+        <View style={styles.flex}>
+          <Select
+            options={ICON_VARIANT_OPTIONS}
+            value={variant}
+            onValueChange={(v) => dispatch({ type: 'SET_ICON_VARIANT', variant: v as 'outlined' | 'rounded' | 'sharp' })}
+            label="Variant"
+          />
+        </View>
+        <View style={styles.flex}>
+          <Select
+            options={ICON_WEIGHT_OPTIONS}
+            value={weight.toString()}
+            onValueChange={(v) => dispatch({ type: 'SET_ICON_WEIGHT', weight: parseInt(v) as 100 | 200 | 300 | 400 | 500 | 600 | 700 })}
+            label="Weight"
+          />
+        </View>
+      </View>
+    </Card>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    gap: 12,
+  },
+  title: {
+    fontSize: 16,
+    fontWeight: '700',
+  },
+  subtitle: {
+    fontSize: 13,
+    fontWeight: '600',
+    marginTop: 4,
+  },
+  row: {
+    flexDirection: 'row',
+    gap: 12,
+  },
+  flex: {
+    flex: 1,
+  },
+});