refactor(ui): migrate all components to dynamic palette system

[JasonWarrenUK]

Summary

Completes the palette system migration by converting all 35 component files to use dynamic CSS custom properties instead of hardcoded colour values. This establishes TypeScript palette files as the single source of truth for all UI colours.

What Changed

Build Infrastructure (Previously Completed)

• ✅ Build-time CSS generation from TypeScript palette sources
• ✅ Automatic palette variable generation on dev and build
• ✅ 75+ CSS variables generated for 5 workflow palettes

Component Conversions (This PR)

Metis Components (4 files) - 30 colour values

• FileUpload, StructuredInputForm, ModulePreview, ChangelogViewer

Themis Components (7 files) - ~160 colour values

• CourseConfigForm, ArcStructurePlanner, ModuleStructurePlanner
• ModuleWithinArcPlanner, CourseStructureReview
• ModuleGenerationList, CourseOverview

Theia Components (3 files) - 76 colour values

• CourseStructureUpload, ExportButton, ExportConfigModal

Error Components (2 files) - 18 colour values

• ErrorBoundary, ErrorAlert

Total Impact

• 35 component files converted
• ~350 hardcoded colour values replaced with palette variables
• 100% of components now use dynamic theming

Key Benefits

1. Single Source of Truth: All colours defined in src/lib/config/palettes/*.ts
2. Zero Runtime Overhead: CSS generated at build time
3. Consistent Theming: Components automatically adapt to workflow palettes
4. Easy Palette Updates: Change TypeScript, rebuild, done
5. Type Safety: Palette structure validated by TypeScript

Technical Details

Colour Mapping Patterns

• Success states → var(--palette-foreground)
• Error states → var(--palette-primary)
• Warning states → var(--palette-accent)
• Body text → var(--palette-foreground-alt)
• Borders → var(--palette-line)
• Subtle backgrounds → var(--palette-bg-subtle)

Example Conversion

- background: #28a745;
- color: white;
+ background: var(--palette-foreground);
+ color: white;

- box-shadow: 0 0 0 3px rgba(40, 167, 69, 0.1);
+ box-shadow: 0 0 0 3px color-mix(in srgb, var(--palette-foreground) 10%, transparent);

Testing

• ✅ Build succeeds with no TypeScript errors
• ✅ Dev server runs without errors
• ⏳ Visual testing across all workflows (recommended before merge)
• ⏳ Palette switching verification

Documentation

Updated docs/dev/ref/palettes/PALETTE-MIGRATION-STATUS.md with:

• Complete conversion tracking
• Colour mapping reference
• Progress statistics

Migration Status

Components: 35/35 ✅ (100%)

See full migration details in: /docs/dev/ref/palettes/PALETTE-MIGRATION-STATUS.md

---

🤖 Generated with Claude Code

[claude]

Summary

This PR successfully completes the palette system migration by converting all 35 component files to use dynamic CSS custom properties. The implementation establishes a solid build-time generation architecture with TypeScript palette files as the single source of truth. While the code quality and architecture are excellent, there are opportunities to improve the regex-based parsing approach and add test coverage.

Code Quality & Best Practices

Excellent:

• Clean separation of concerns: Data → Transformation → Generation → Components
• Consistent naming conventions: CSS variables follow predictable patterns
• Type safety: TypeScript interfaces ensure palette structure integrity
• Documentation: Comprehensive docs explain the system clearly
• Component consistency: All 35 components use the same palette variable patterns

Suggestions:

1. scripts/generatePaletteCss.js:37-52 - The regex parsing is fragile. Consider using a proper TypeScript AST parser or JSON export.
2. Magic string duplication: Workflow names appear in multiple places. Consider a shared constant file.
3. Error handling: Build script doesn't validate all required palette properties exist before generation.

Potential Issues

Medium Priority:

1. Regex parsing brittleness (lines 24-63) - Complex regex with multiple fallbacks could silently fail if palette structure changes
2. color-mix() browser support - Modern syntax, worth documenting minimum browser requirements

Low Priority:

1. Hardcoded workflow list requires editing build script in 3 places when adding workflows
2. No validation between TypeScript types and generated CSS variables

Performance

Excellent:

• Zero runtime overhead (build-time generation)
• No FOUC (CSS variables available immediately)
• Efficient selector specificity
• 170 lines of CSS is well within performance budgets

Security

No Issues Identified:

• No user input processed
• No external dependencies added
• Build script reads local files only
• TypeScript types prevent malformed data

Test Coverage

Current State: No tests

Recommendations:

1. Build script validation tests (HIGH PRIORITY)
2. Palette structure validation tests (HIGH PRIORITY)
3. Transformer tests (HIGH PRIORITY)
4. Integration tests for CSS variable application
5. Visual regression tests for palette consistency

The build script parsing is fragile (regex-based) and needs a safety net.

Recommendation

Approve with suggestions for follow-up.

This is excellent work:

• ✅ Single source of truth established
• ✅ All components converted (100%)
• ✅ Build-time generation working
• ✅ Comprehensive documentation

Before Merge (if possible):

1. Add basic validation to build script to ensure all palette properties exist
2. Test the build script manually with a malformed palette

Follow-up Issues (post-merge):

1. Add test coverage for palette system
2. Consider replacing regex parsing with proper TS parsing
3. Add visual regression tests

Great job on the architecture and execution! The separation of concerns and documentation are particularly well done.