Refactor library to use Tailwind v4

[mitchthorson]

Summary

Upgrade the dataviz-components library from its current custom CSS design system to Tailwind CSS v4, leveraging the new theme syntax and modern CSS features.

Current State Analysis

After analyzing the codebase, the library currently uses:

• Custom CSS design system: Defined in src/lib/Theme/Theme.svelte using CSS custom properties (CSS variables)
• Design tokens: Comprehensive system with:
  • Typography (font families, sizes, weights, line heights)
  • Color palette (blue, gray, yellow, magenta, green, red, space-gray with shade variations)
  • Spacing scale (1-20, using rem units)
  • Layout constraints (body/wide max-widths)
• Global styles: Typography defaults for headings, paragraphs, links, lists with responsive variations
• Theme compilation: Custom build process (bin/compileTheme.js) that extracts CSS from Svelte component and generates dist/style/theme.css
• No Tailwind dependency: Currently no Tailwind CSS found in package.json or configuration files

Migration Tasks

1. Install and Configure Tailwind v4

• use svelte cli to add tailwind and configuration npx sv add tailwindcss

2. Convert Design System to Tailwind Theme

• Migrate CSS custom properties from Theme.svelte:11-147 to Tailwind theme configuration
• Convert color palette to Tailwind color scale format
• Map typography scale to Tailwind font-size/line-height configuration
• Convert spacing scale to Tailwind spacing configuration
• Set up semantic color mappings (text-primary, accent-primary, etc.)

3. Update Theme.svelte Component

• Replace CSS custom properties with Tailwind theme references
• Maintain backward compatibility for CSS custom properties if needed
• Update global typography styles to use Tailwind's @layer base
• Ensure responsive typography variants work with Tailwind's responsive system

4. Update Build Process

• Modify compile-theme-styles script in package.json:8
• Update bin/compileTheme.js to work with Tailwind compilation
• Ensure dist/style/theme.css output maintains same public API
• Update package exports for theme CSS (./style/theme export)

5. Component Migration Strategy

• Audit existing components for any direct CSS custom property usage
• Create migration guide for consumers using the design system
• Test Storybook integration with new Tailwind setup

6. Documentation and Testing

• Update Theme documentation (src/lib/Theme/Theme.docs.mdx)
• Verify all Storybook stories render correctly

Technical Considerations

• Backward Compatibility: Consider maintaining CSS custom properties alongside Tailwind for gradual migration
• Bundle Size: Evaluate impact on library size and implement PurgeCSS/tree-shaking appropriately
• Performance: Ensure theme compilation performance doesn't regress from current build time
• Design Token Fidelity: Maintain exact color values and spacing scale during migration
• Build Integration: Seamless integration with existing Svelte/SvelteKit + Storybook workflow

Acceptance Criteria

• All existing design tokens available through Tailwind theme
• No visual regressions in Storybook components
• Build process generates identical theme.css output for consumers
• Documentation updated with new Tailwind v4 usage patterns
• Performance benchmarks meet or exceed current build times

[mitchthorson]

Note: during recent testing, some compatibility issues have come up with tailwind and svelte custom elements. Holding off on adopting this change until that issue can be resolved.