CSS Variables Not Type-Safe

[JakeLin]

Using string literals for design tokens:

// Current: No autocomplete, typo-prone
<div style={{
  gap: 'var(--ai-spacing-8)',        // ❌ String, no type safety
  fontSize: 'var(--ai-font-size-sm)' // ❌ Could typo
}} />

// Should export:
import { spacing, typography } from '@ainativekit/ui/tokens';

<div style={{
  gap: spacing[8],        // ✅ Autocomplete!
  fontSize: typography.body.fontSize
}} />

[JakeLin]

fix by ece1f40
feat: unify design tokens to use numeric keys throughout

Consolidate spacing and elevation tokens to use consistent numeric keys
instead of mixed string/numeric types. This provides a cleaner, more
intuitive API while maintaining full type safety.

Breaking Changes

• Spacing now uses numeric keys: spacing[16] instead of spacing['space-16']
• Elevation uses numeric keys: elevation[1] instead of elevation['1']
• Card component elevationLevel prop now accepts numbers: elevationLevel={1}

Changes

Token System:

• Converted spacing.ts to use numeric keys (0-64)
• Unified elevation.ts to numeric keys (0-5)
• Simplified token-helpers.ts to directly re-export source tokens
• Updated index.ts with single source of truth exports
• Removed dual type system complexity

API Improvements:

• spacing[16] returns '32px' (instead of spacing['space-16'])
• elevation[1].shadow (instead of elevation['1'].shadow)
• <Card elevationLevel={1} /> (instead of elevationLevel="1")
• cssVar.spacing(8) returns 'var(--ai-spacing-8)'

Type Exports:

• SpacingScale - 0 | 1 | 2 | 4 | 6 | 8 | 10 | 12 | 16 | 20 | 24 | 32 | 64
• ElevationLevel - 0 | 1 | 2 | 3 | 4 | 5

Documentation:

• Added TOKEN_USAGE.md with comprehensive examples
• Added EXAMPLES.tsx with real-world component patterns
• Updated README with numeric key examples
• Updated all Storybook examples

Testing:

• Added 35 new tests for token helpers
• All 548 tests passing
• Full TypeScript type safety maintained

Benefits

• Cleaner API: spacing[16] vs spacing['space-16']
• Single source of truth (no duplicate types)
• Consistent numeric access for scalar tokens
• Better developer experience
• Simplified codebase (-50 lines of conversion code)