@newtonedev/components 0.1.3 → 0.1.5

package/src/{Select → composites/form-controls/Select}/SelectOption.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
 import { Pressable, Text, View } from 'react-native';
 import type { SelectOption as SelectOptionType, SelectProps } from './Select.types';
-import { useTokens } from '../tokens/useTokens';
-import { Icon } from '../primitives/Icon/Icon';
+import { useTokens } from '../../../tokens/useTokens';
+import { Icon } from '../../../primitives/Icon/Icon';
 import { srgbToHex } from 'newtone';
 
 interface SelectOptionRowProps {

package/src/{TextInput → composites/form-controls/TextInput}/TextInput.styles.ts

@@ -1,6 +1,6 @@
 import { StyleSheet } from 'react-native';
 import { srgbToHex } from 'newtone';
-import type { ResolvedTokens } from '../tokens/types';
+import type { ResolvedTokens } from '../../../tokens/types';
 
 export function getTextInputStyles(tokens: ResolvedTokens, disabled: boolean) {
   return StyleSheet.create({

package/src/{TextInput → composites/form-controls/TextInput}/TextInput.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { View, Text, TextInput as RNTextInput } from 'react-native';
 import type { TextInputProps } from './TextInput.types';
-import { useTokens } from '../tokens/useTokens';
+import { useTokens } from '../../../tokens/useTokens';
 import { getTextInputStyles } from './TextInput.styles';
 import { srgbToHex } from 'newtone';
 

package/src/{Toggle → composites/form-controls/Toggle}/Toggle.styles.ts

@@ -1,6 +1,6 @@
 import { StyleSheet } from 'react-native';
 import { srgbToHex } from 'newtone';
-import type { ResolvedTokens } from '../tokens/types';
+import type { ResolvedTokens } from '../../../tokens/types';
 
 const TRACK_WIDTH = 40;
 const TRACK_HEIGHT = 22;

package/src/{Toggle → composites/form-controls/Toggle}/Toggle.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { View, Text, Pressable } from 'react-native';
 import type { ToggleProps } from './Toggle.types';
-import { useTokens } from '../tokens/useTokens';
+import { useTokens } from '../../../tokens/useTokens';
 import { getToggleStyles } from './Toggle.styles';
 
 export function Toggle({

package/src/{AppShell → composites/layout/AppShell}/AppShell.styles.ts

@@ -1,6 +1,6 @@
 import { StyleSheet } from 'react-native';
 import { srgbToHex } from 'newtone';
-import type { ResolvedTokens } from '../tokens/types';
+import type { ResolvedTokens } from '../../../tokens/types';
 
 export function getAppShellStyles(tokens: ResolvedTokens) {
   return StyleSheet.create({

package/src/{AppShell → composites/layout/AppShell}/AppShell.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { View } from 'react-native';
 import type { AppShellProps } from './AppShell.types';
-import { useTokens } from '../tokens/useTokens';
+import { useTokens } from '../../../tokens/useTokens';
 import { getAppShellStyles } from './AppShell.styles';
 
 export function AppShell({ sidebar, children }: AppShellProps) {

package/src/{Card → composites/layout/Card}/Card.styles.ts

@@ -1,6 +1,6 @@
 import { StyleSheet } from 'react-native';
 import { srgbToHex } from 'newtone';
-import type { ResolvedTokens } from '../tokens/types';
+import type { ResolvedTokens } from '../../../tokens/types';
 
 export function getCardStyles(tokens: ResolvedTokens, disabled: boolean) {
   return StyleSheet.create({

package/src/{Card → composites/layout/Card}/Card.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { View } from 'react-native';
 import type { CardProps } from './Card.types';
-import { useTokens } from '../tokens/useTokens';
+import { useTokens } from '../../../tokens/useTokens';
 import { getCardStyles } from './Card.styles';
 
 export function Card({

package/src/{Card → composites/layout/Card}/Card.types.ts

@@ -1,5 +1,5 @@
 import type { ViewStyle } from 'react-native';
-import type { ElevationLevel } from '../theme/types';
+import type { ElevationLevel } from '../../../theme/types';
 
 export interface CardProps {
   readonly children: React.ReactNode;

package/src/{Navbar → composites/layout/Navbar}/Navbar.styles.ts

@@ -1,6 +1,6 @@
 import { StyleSheet } from 'react-native';
 import { srgbToHex } from 'newtone';
-import type { ResolvedTokens } from '../tokens/types';
+import type { ResolvedTokens } from '../../../tokens/types';
 
 interface NavbarStyleInput {
   readonly tokens: ResolvedTokens;

package/src/{Navbar → composites/layout/Navbar}/Navbar.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { View } from 'react-native';
 import type { NavbarProps } from './Navbar.types';
-import { useTokens } from '../tokens/useTokens';
+import { useTokens } from '../../../tokens/useTokens';
 import { getNavbarStyles } from './Navbar.styles';
 
 export function Navbar({

package/src/{Sidebar → composites/layout/Sidebar}/Sidebar.styles.ts

@@ -1,6 +1,6 @@
 import { StyleSheet } from 'react-native';
 import { srgbToHex } from 'newtone';
-import type { ResolvedTokens } from '../tokens/types';
+import type { ResolvedTokens } from '../../../tokens/types';
 
 interface SidebarStyleInput {
   readonly tokens: ResolvedTokens;

package/src/{Sidebar → composites/layout/Sidebar}/Sidebar.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { View, ScrollView } from 'react-native';
 import type { SidebarProps } from './Sidebar.types';
-import { useTokens } from '../tokens/useTokens';
+import { useTokens } from '../../../tokens/useTokens';
 import { getSidebarStyles } from './Sidebar.styles';
 
 export function Sidebar({

package/src/{Popover → composites/overlays/Popover}/Popover.styles.ts

@@ -1,6 +1,6 @@
 import { StyleSheet } from 'react-native';
 import { srgbToHex } from 'newtone';
-import type { ResolvedTokens } from '../tokens/types';
+import type { ResolvedTokens } from '../../../tokens/types';
 
 export function getPopoverStyles(
   tokens: ResolvedTokens,

package/src/{Popover → composites/overlays/Popover}/Popover.tsx

@@ -1,7 +1,7 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { View } from 'react-native';
 import type { PopoverProps } from './Popover.types';
-import { useTokens } from '../tokens/useTokens';
+import { useTokens } from '../../../tokens/useTokens';
 import { getPopoverStyles } from './Popover.styles';
 
 // Module-level: set of close callbacks for all open Popovers.

package/src/{ColorScaleSlider → composites/range-inputs/ColorScaleSlider}/ColorScaleSlider.styles.ts

@@ -1,6 +1,6 @@
 import { StyleSheet } from 'react-native';
 import { srgbToHex } from 'newtone';
-import type { ResolvedTokens } from '../tokens/types';
+import type { ResolvedTokens } from '../../../tokens/types';
 
 const TRACK_HEIGHT = 22;
 export const THUMB_SIZE = 18;

package/src/{ColorScaleSlider → composites/range-inputs/ColorScaleSlider}/ColorScaleSlider.tsx

@@ -2,7 +2,7 @@ import React from 'react';
 import { View, Text, PanResponder, Animated } from 'react-native';
 import { srgbToHex } from 'newtone';
 import type { ColorScaleSliderProps } from './ColorScaleSlider.types';
-import { useTokens } from '../tokens/useTokens';
+import { useTokens } from '../../../tokens/useTokens';
 import { getColorScaleSliderStyles, THUMB_SIZE } from './ColorScaleSlider.styles';
 
 /**

package/src/{HueSlider → composites/range-inputs/HueSlider}/HueSlider.styles.ts

@@ -1,6 +1,6 @@
 import { StyleSheet } from 'react-native';
 import { srgbToHex } from 'newtone';
-import type { ResolvedTokens } from '../tokens/types';
+import type { ResolvedTokens } from '../../../tokens/types';
 
 const TRACK_HEIGHT = 22;
 export const THUMB_SIZE = 18;

package/src/{HueSlider → composites/range-inputs/HueSlider}/HueSlider.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { View, Text, TextInput, PanResponder } from 'react-native';
 import type { HueSliderProps } from './HueSlider.types';
-import { useTokens } from '../tokens/useTokens';
+import { useTokens } from '../../../tokens/useTokens';
 import {
   getHueSliderStyles,
   buildHueSegments,

package/src/{Slider → composites/range-inputs/Slider}/Slider.styles.ts

@@ -1,6 +1,6 @@
 import { StyleSheet } from 'react-native';
 import { srgbToHex } from 'newtone';
-import type { ResolvedTokens } from '../tokens/types';
+import type { ResolvedTokens } from '../../../tokens/types';
 
 const TRACK_HEIGHT = 6;
 export const THUMB_SIZE = 16;

package/src/{Slider → composites/range-inputs/Slider}/Slider.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { View, Text, TextInput, PanResponder } from 'react-native';
 import type { SliderProps } from './Slider.types';
-import { useTokens } from '../tokens/useTokens';
+import { useTokens } from '../../../tokens/useTokens';
 import { getSliderStyles, THUMB_SIZE } from './Slider.styles';
 
 export function Slider({

package/src/index.ts

@@ -20,12 +20,12 @@ export { useTokens } from './tokens/useTokens';
 export { computeTokens } from './tokens/computeTokens';
 export type { ResolvedTokens } from './tokens/types';
 
-// Components
-export { Button } from './Button/Button';
-export type { ButtonProps, ButtonVariant, ButtonSize, ButtonIconPosition } from './Button/Button.types';
+// Composite Components
+export { Button } from './composites/actions/Button/Button';
+export type { ButtonProps, ButtonVariant, ButtonSemantic, ButtonSize, ButtonIconPosition } from './composites/actions/Button/Button.types';
 
-export { Card } from './Card/Card';
-export type { CardProps } from './Card/Card.types';
+export { Card } from './composites/layout/Card/Card';
+export type { CardProps } from './composites/layout/Card/Card.types';
 
 export { useFocusVisible } from './primitives/useFocusVisible';
 export type { FocusVisibleResult } from './primitives/useFocusVisible';
@@ -52,28 +52,28 @@ export type {
 } from './primitives/Frame/Frame.types';
 export type { ResolvedCorners } from './primitives/Frame/Frame.utils';
 
-export { TextInput } from './TextInput/TextInput';
-export type { TextInputProps } from './TextInput/TextInput.types';
+export { TextInput } from './composites/form-controls/TextInput/TextInput';
+export type { TextInputProps } from './composites/form-controls/TextInput/TextInput.types';
 
-export { Popover } from './Popover/Popover';
-export type { PopoverProps, PopoverPlacement } from './Popover/Popover.types';
-export { usePopover } from './Popover/usePopover';
+export { Popover } from './composites/overlays/Popover/Popover';
+export type { PopoverProps, PopoverPlacement } from './composites/overlays/Popover/Popover.types';
+export { usePopover } from './composites/overlays/Popover/usePopover';
 
-export { Select } from './Select/Select';
-export type { SelectProps, SelectOption, SelectOptionGroup, SelectItem } from './Select/Select.types';
-export { isOptionGroup } from './Select/Select.types';
+export { Select } from './composites/form-controls/Select/Select';
+export type { SelectProps, SelectOption, SelectOptionGroup, SelectItem } from './composites/form-controls/Select/Select.types';
+export { isOptionGroup } from './composites/form-controls/Select/Select.types';
 
-export { Toggle } from './Toggle/Toggle';
-export type { ToggleProps } from './Toggle/Toggle.types';
+export { Toggle } from './composites/form-controls/Toggle/Toggle';
+export type { ToggleProps } from './composites/form-controls/Toggle/Toggle.types';
 
-export { Slider } from './Slider/Slider';
-export type { SliderProps } from './Slider/Slider.types';
+export { Slider } from './composites/range-inputs/Slider/Slider';
+export type { SliderProps } from './composites/range-inputs/Slider/Slider.types';
 
-export { HueSlider } from './HueSlider/HueSlider';
-export type { HueSliderProps } from './HueSlider/HueSlider.types';
+export { HueSlider } from './composites/range-inputs/HueSlider/HueSlider';
+export type { HueSliderProps } from './composites/range-inputs/HueSlider/HueSlider.types';
 
-export { ColorScaleSlider } from './ColorScaleSlider/ColorScaleSlider';
-export type { ColorScaleSliderProps } from './ColorScaleSlider/ColorScaleSlider.types';
+export { ColorScaleSlider } from './composites/range-inputs/ColorScaleSlider/ColorScaleSlider';
+export type { ColorScaleSliderProps } from './composites/range-inputs/ColorScaleSlider/ColorScaleSlider.types';
 
 export { Icon } from './primitives/Icon/Icon';
 export type { IconProps } from './primitives/Icon/Icon.types';
@@ -92,14 +92,14 @@ export type {
   TextAlign,
 } from './primitives/Text/Text.types';
 
-export { AppShell } from './AppShell/AppShell';
-export type { AppShellProps } from './AppShell/AppShell.types';
+export { AppShell } from './composites/layout/AppShell/AppShell';
+export type { AppShellProps } from './composites/layout/AppShell/AppShell.types';
 
-export { Sidebar } from './Sidebar/Sidebar';
-export type { SidebarProps } from './Sidebar/Sidebar.types';
+export { Sidebar } from './composites/layout/Sidebar/Sidebar';
+export type { SidebarProps } from './composites/layout/Sidebar/Sidebar.types';
 
-export { Navbar } from './Navbar/Navbar';
-export type { NavbarProps } from './Navbar/Navbar.types';
+export { Navbar } from './composites/layout/Navbar/Navbar';
+export type { NavbarProps } from './composites/layout/Navbar/Navbar.types';
 
 // Component registry + code generation
 export type {

package/src/primitives/Icon/Icon.tsx

@@ -42,8 +42,20 @@ export function Icon({
   const iconStyle = useMemo<TextStyle>(() => {
     // Use the provided size, or fall back to the theme's default text size.
     const fontSize = size ?? tokens.typography.size.base;
+
+    // Round to nearest Material Symbols optical size (20, 24, 40, 48)
+    // for optimal stroke weight and detail rendering.
+    const getOpticalSize = (size: number): number => {
+      if (size <= 22) return 20;
+      if (size <= 32) return 24;
+      if (size <= 44) return 40;
+      return 48;
+    };
+
     // Optical size adjusts stroke weight for readability at small sizes.
-    const opsz = opticalSize ?? fontSize;
+    // Use explicit opticalSize if provided, otherwise auto-calculate from fontSize.
+    const opsz = opticalSize ?? getOpticalSize(fontSize);
+
     // Use the provided color, or fall back to the theme's primary text color.
     const iconColor = color ?? srgbToHex(tokens.textPrimary.srgb);
 
@@ -62,6 +74,9 @@ export function Icon({
     return {
       fontFamily,
       fontSize,
+      width: fontSize, // Explicit width ensures square rendering
+      height: fontSize, // Explicit height ensures square rendering
+      lineHeight: fontSize, // Prevent text line-height from affecting total height
       color: iconColor,
       userSelect: 'none', // web-only: prevents users from selecting the icon as text
       fontVariationSettings, // web-only: controls the variable font axes listed above

package/src/primitives/Wrapper/Wrapper.types.ts

@@ -49,7 +49,7 @@ export interface WrapperProps {
    * Child elements. Must be React Native elements (View, Text, etc.).
    * Unlike Frame, raw strings are NOT auto-wrapped in `<Text>`.
    */
-  readonly children: React.ReactNode;
+  readonly children?: React.ReactNode;
 
   // ── Layout ──
 

package/src/registry/registry.ts

@@ -1,10 +1,12 @@
 import type { CategoryMeta, ComponentMeta } from './types';
 
 export const CATEGORIES: readonly CategoryMeta[] = [
+  { id: 'primitives', name: 'Design Primitives', description: 'Core building blocks for theme-aware layouts and typography' },
   { id: 'actions', name: 'Actions', description: 'Interactive elements that trigger actions' },
   { id: 'form-controls', name: 'Form Controls', description: 'Input elements for user data entry' },
-  { id: 'range-inputs', name: 'Range Inputs', description: 'Slider controls for numeric values' },
+  { id: 'range-inputs', name: 'Range Inputs', description: 'Slider controls for numeric and continuous values' },
   { id: 'layout', name: 'Layout', description: 'Structural and container components' },
+  { id: 'overlays', name: 'Overlays', description: 'Floating and portal-based UI elements' },
 ];
 
 export const COMPONENTS: readonly ComponentMeta[] = [
@@ -387,6 +389,216 @@ export const COMPONENTS: readonly ComponentMeta[] = [
       },
     ],
   },
+  // ── Design Primitives ──
+  {
+    id: 'text',
+    name: 'Text',
+    importName: 'Text',
+    categoryId: 'primitives',
+    description: 'Typography primitive with semantic size, weight, color, font, and lineHeight',
+    hasChildren: true,
+    variants: [
+      { id: 'default', label: 'Default', props: {} },
+      { id: 'heading', label: 'Heading', props: { size: 'xl', weight: 'bold' } },
+      { id: 'subheading', label: 'Subheading', props: { size: 'lg', weight: 'semibold' } },
+      { id: 'body', label: 'Body', props: { size: 'base' } },
+      { id: 'caption', label: 'Caption', props: { size: 'sm', color: 'secondary' } },
+      { id: 'link', label: 'Link', props: { color: 'interactive', weight: 'medium' } },
+      { id: 'mono', label: 'Monospace', props: { font: 'mono', size: 'sm' } },
+    ],
+    editableProps: [
+      {
+        name: 'size',
+        label: 'Size',
+        control: 'select',
+        options: [
+          { label: 'Extra Small', value: 'xs' },
+          { label: 'Small', value: 'sm' },
+          { label: 'Base', value: 'base' },
+          { label: 'Medium', value: 'md' },
+          { label: 'Large', value: 'lg' },
+          { label: 'Extra Large', value: 'xl' },
+          { label: 'XXL', value: 'xxl' },
+        ],
+        defaultValue: 'base',
+      },
+      {
+        name: 'weight',
+        label: 'Weight',
+        control: 'select',
+        options: [
+          { label: 'Regular', value: 'regular' },
+          { label: 'Medium', value: 'medium' },
+          { label: 'Semibold', value: 'semibold' },
+          { label: 'Bold', value: 'bold' },
+        ],
+        defaultValue: 'regular',
+      },
+      {
+        name: 'color',
+        label: 'Color',
+        control: 'select',
+        options: [
+          { label: 'Primary', value: 'primary' },
+          { label: 'Secondary', value: 'secondary' },
+          { label: 'Interactive', value: 'interactive' },
+        ],
+        defaultValue: 'primary',
+      },
+      {
+        name: 'font',
+        label: 'Font',
+        control: 'select',
+        options: [
+          { label: 'Default', value: 'default' },
+          { label: 'Display', value: 'display' },
+          { label: 'Mono', value: 'mono' },
+        ],
+        defaultValue: 'default',
+      },
+    ],
+  },
+  {
+    id: 'icon',
+    name: 'Icon',
+    importName: 'Icon',
+    categoryId: 'primitives',
+    description: 'Material Symbols icon with size, fill, and color',
+    hasChildren: false,
+    variants: [
+      { id: 'home', label: 'Home', props: { name: 'home' } },
+      { id: 'settings', label: 'Settings', props: { name: 'settings' } },
+      { id: 'check', label: 'Check', props: { name: 'check' } },
+      { id: 'add', label: 'Add', props: { name: 'add' } },
+      { id: 'delete', label: 'Delete', props: { name: 'delete' } },
+      { id: 'search', label: 'Search', props: { name: 'search' } },
+      { id: 'filled', label: 'Filled Icon', props: { name: 'favorite', fill: 1 } },
+      { id: 'large', label: 'Large Icon', props: { name: 'star', size: 32 } },
+    ],
+    editableProps: [
+      {
+        name: 'name',
+        label: 'Icon Name',
+        control: 'text',
+        defaultValue: 'home',
+      },
+      {
+        name: 'size',
+        label: 'Size',
+        control: 'number',
+        defaultValue: 24,
+      },
+      {
+        name: 'fill',
+        label: 'Fill',
+        control: 'select',
+        options: [
+          { label: 'Outlined', value: 0 },
+          { label: 'Filled', value: 1 },
+        ],
+        defaultValue: 0,
+      },
+    ],
+  },
+  {
+    id: 'wrapper',
+    name: 'Wrapper',
+    importName: 'Wrapper',
+    categoryId: 'primitives',
+    description: 'Lightweight layout container with direction, spacing, and alignment (no theming)',
+    hasChildren: true,
+    variants: [
+      { id: 'vertical', label: 'Vertical Stack', props: { direction: 'vertical', gap: 'md' } },
+      { id: 'horizontal', label: 'Horizontal Row', props: { direction: 'horizontal', gap: 'md', align: 'center' } },
+      { id: 'padded', label: 'Padded', props: { padding: 'lg', gap: 'md' } },
+      { id: 'centered', label: 'Centered', props: { align: 'center', justify: 'center', padding: 'xl' } },
+    ],
+    editableProps: [
+      {
+        name: 'direction',
+        label: 'Direction',
+        control: 'select',
+        options: [
+          { label: 'Vertical', value: 'vertical' },
+          { label: 'Horizontal', value: 'horizontal' },
+        ],
+        defaultValue: 'vertical',
+      },
+      {
+        name: 'gap',
+        label: 'Gap',
+        control: 'select',
+        options: [
+          { label: 'None', value: '' },
+          { label: 'Small', value: 'sm' },
+          { label: 'Medium', value: 'md' },
+          { label: 'Large', value: 'lg' },
+        ],
+        defaultValue: '',
+      },
+      {
+        name: 'padding',
+        label: 'Padding',
+        control: 'select',
+        options: [
+          { label: 'None', value: '' },
+          { label: 'Small', value: 'sm' },
+          { label: 'Medium', value: 'md' },
+          { label: 'Large', value: 'lg' },
+        ],
+        defaultValue: '',
+      },
+      {
+        name: 'align',
+        label: 'Align',
+        control: 'select',
+        options: [
+          { label: 'Start', value: 'start' },
+          { label: 'Center', value: 'center' },
+          { label: 'End', value: 'end' },
+        ],
+        defaultValue: 'start',
+      },
+      {
+        name: 'justify',
+        label: 'Justify',
+        control: 'select',
+        options: [
+          { label: 'Start', value: 'start' },
+          { label: 'Center', value: 'center' },
+          { label: 'End', value: 'end' },
+          { label: 'Space Between', value: 'space-between' },
+        ],
+        defaultValue: 'start',
+      },
+    ],
+  },
+  // ── Range Inputs (Addition: ColorScaleSlider) ──
+  {
+    id: 'color-scale-slider',
+    name: 'ColorScaleSlider',
+    importName: 'ColorScaleSlider',
+    categoryId: 'range-inputs',
+    description: 'Interactive palette preview slider with color segments',
+    hasChildren: false,
+    variants: [
+      { id: 'default', label: 'Default', props: { label: 'Key Color' } },
+    ],
+    editableProps: [
+      {
+        name: 'label',
+        label: 'Label',
+        control: 'text',
+        defaultValue: 'Key Color',
+      },
+      {
+        name: 'disabled',
+        label: 'Disabled',
+        control: 'toggle',
+        defaultValue: false,
+      },
+    ],
+  },
 ];
 
 export function getComponent(id: string): ComponentMeta | undefined {

package/src/tokens/computeTokens.ts

@@ -114,6 +114,21 @@ export function computeTokens(
     palette.paletteHueGrading
   );
 
+  // Compute interactive component background (FIXED -0.035 NV offset from current elevation)
+  // Unlike backgroundElevated/backgroundSunken which use discrete levels, this uses a fixed
+  // luminosity offset to ensure CONSISTENT visual contrast across all elevations (-2 to 2).
+  // Used by: Button (neutral primary variant) and future components with neutral filled backgrounds.
+  const INTERACTIVE_COMPONENT_OFFSET = -0.035; // Slightly darker than container for depth
+  const interactiveComponentNv = Math.max(0, Math.min(1, backgroundNv + INTERACTIVE_COMPONENT_OFFSET));
+  const backgroundInteractive = getColor(
+    palette.hue,
+    palette.saturation,
+    dynamicRange,
+    interactiveComponentNv,
+    palette.desaturation,
+    palette.paletteHueGrading
+  );
+
   // Compute text colors with WCAG contrast against actual background
   // Primary text: WCAG AA (4.5:1 for body text)
   const textPrimary = getColorByContrast(
@@ -242,6 +257,7 @@ export function computeTokens(
     background,
     backgroundElevated,
     backgroundSunken,
+    backgroundInteractive,
     textPrimary,
     textSecondary,
     interactive,

package/src/tokens/types.ts

@@ -10,6 +10,16 @@ export interface ResolvedTokens {
   readonly backgroundElevated: ColorResult;
   /** Background color for sunken surfaces (input fields, wells) */
   readonly backgroundSunken: ColorResult;
+  /**
+   * Background color for interactive components with neutral backgrounds.
+   * Uses a fixed -0.035 NV (luminosity) offset from current background to ensure
+   * consistent visual contrast across all elevations (-2 to 2).
+   *
+   * Use for: Button (neutral primary), and future components with neutral filled backgrounds.
+   * Don't use for: Semantic variants (accent/success/error/warning), transparent backgrounds,
+   * or primitives (Frame/Wrapper/Text/Icon already handle elevation correctly).
+   */
+  readonly backgroundInteractive: ColorResult;
   /** Primary text color (high contrast for body text) */
   readonly textPrimary: ColorResult;
   /** Secondary text color (lower contrast for captions, labels) */