OpenNoodl/dev-docs/tasks/phase-9-styles-overhaul/STYLE-001-token-system-enhancement/CHANGELOG.md

STYLE-001: Token System Enhancement - Changelog

2026-02-18 - Phase 1 & 2 Complete

Phase 1: Token Data Structure

New Files

packages/noodl-editor/src/editor/src/models/StyleTokensModel/

• TokenCategories.ts — TypeScript types for the design token system:

  • TokenCategory union type (13 categories: color-semantic, color-palette, spacing, typography-, border-, shadow, animation-*)
  • StyleToken, StyleTokenRecord, StyleTokensData interfaces
  • TOKEN_CATEGORIES metadata map (label, description, group)
  • TOKEN_CATEGORY_GROUPS ordered display groups

• DefaultTokens.ts — Full Tailwind-inspired default token set:

  • ~24 semantic colors (primary, secondary, destructive, muted, accent, surface, border, ring)
  • ~90 palette colors (gray, blue, red, green, amber, purple at 10 shades each)
  • ~32 spacing tokens (0–128px numeric scale + semantic aliases xs/sm/md/lg/xl/2xl/3xl)
  • 10 font sizes, 9 font weights, 6 line heights, 6 letter spacings, 3 font families
  • 8 border radii, 5 border widths
  • 7 shadow scales
  • 8 animation durations + 5 easing functions
  • Only overrides stored in project.json — defaults never persisted

• TokenResolver.ts — CSS var() reference resolution:

  • Resolves chained references (e.g. --space-xs → var(--space-1) → 4px)
  • LRU-style cache with targeted invalidation
  • generateCss() for :root { ... } CSS block generation
  • Max depth protection against circular references

• StyleTokensModel.ts — Main model class:

  • Extends Model (EventDispatcher-compatible)
  • getTokens(), getTokensByCategory(), getTokensByGroup(), getTokensGrouped()
  • setToken(), addCustomToken(), deleteCustomToken(), resetAllToDefaults() — all undo-aware
  • generateCss(), exportCustomTokensJson(), importCustomTokensJson()
  • Persists only custom overrides under designTokens metadata key
  • Auto-reloads on ProjectModel.importComplete / ProjectModel.instanceHasChanged
  • Properly uses new UndoActionGroup(...) for undo stack integration

• index.ts — Clean public exports

Phase 2: Context & Panel Enhancement

Modified

• ProjectDesignTokenContext.tsx — Enhanced with:
  • designTokens: StyleTokenRecord[] — live token array, re-renders on tokensChanged
  • styleTokensModel: StyleTokensModel | null — model instance for direct interaction
  • Uses useEventListener hook (correct pattern, no direct .on())
  • Backward compatible — existing staticColors, dynamicColors, textStyles unchanged

New

• DesignTokenPanel.tsx — Replaced basic 2-tab panel with proper structure:

  • New "Tokens" tab (primary) + legacy "Colors" tab preserved

• components/DesignTokensTab/ — Tokens tab:

  • Groups all tokens by display category (Colors, Spacing, Typography, Borders, Effects, Animation)
  • Collapsible sections per group via CollapsableSection
  • Shows "N overrides" banner with "Reset all" when tokens are customised

• components/TokenCategorySection/ — Per-group token list:

  • Color swatches for color tokens
  • Spacing bars for spacing tokens (proportional width)
  • Border radius preview boxes
  • Shadow preview boxes
  • Font size "Aa" previews
  • Override indicator (highlighted name) with reset button (↺) on hover
  • SCSS using design tokens throughout (no hardcoded values)

---

What's Still Pending

Phase 3: TokenPicker Component (STYLE-001)

• Reusable <TokenPicker> dropdown for use in property panels
• Currently onTokenChange prop exists but inline editing not yet wired
• Will be built as part of STYLE-002/STYLE-004 integration

Phase 4: CSS Variable Injection (STYLE-001)

• StyleTokensModel.generateCss() is ready
• Need to inject into preview iframe when tokens change
• Requires investigation of preview server injection point in noodl-viewer-react

---

Started: 2026-02-18