metabuilder/frontends/codegen/docs/THEME_JSON_SYSTEM.md

Theme JSON System Implementation

Overview

Implemented a comprehensive theme configuration system that loads styling from theme.json, making the application's visual appearance highly configurable without code changes.

What Was Fixed

1. Sidebar Styling Issues: Fixed messed up sidebar styling by implementing proper theme loading and CSS variable management
2. Theme JSON Loading: Created a robust theme loading system that reads from theme.json
3. CSS Variables: Properly configured CSS custom properties for sidebar and application theming
4. Type Safety: Added TypeScript interfaces for theme configuration

Files Changed

New Files

• /src/hooks/use-theme-config.ts - Hook for loading and applying theme configuration
• Updated /theme.json - Comprehensive theme configuration with sidebar settings

Modified Files

• /src/components/ui/sidebar.tsx - Now uses theme config for sidebar dimensions
• /src/index.css - Added sidebar CSS variables and component classes
• /src/hooks/index.ts - Exported the new useThemeConfig hook

Theme Configuration Structure

The theme.json file supports the following structure:

{
  "sidebar": {
    "width": "16rem",
    "widthMobile": "18rem",
    "widthIcon": "3rem",
    "backgroundColor": "oklch(0.19 0.02 265)",
    "foregroundColor": "oklch(0.95 0.01 265)",
    "borderColor": "oklch(0.28 0.03 265)",
    "accentColor": "oklch(0.58 0.24 265)",
    "accentForeground": "oklch(1 0 0)",
    "hoverBackground": "oklch(0.25 0.03 265)",
    "activeBackground": "oklch(0.30 0.04 265)",
    "headerHeight": "4rem",
    "transitionDuration": "200ms",
    "zIndex": 40
  },
  "colors": {
    "background": "oklch(...)",
    "foreground": "oklch(...)",
    "primary": "oklch(...)",
    ...
  },
  "spacing": {
    "radius": "0.5rem"
  },
  "typography": {
    "fontFamily": {
      "body": "'IBM Plex Sans', sans-serif",
      "heading": "'JetBrains Mono', monospace",
      "code": "'JetBrains Mono', monospace"
    }
  }
}

How It Works

1. Theme Loading

The useThemeConfig hook:

• Fetches /theme.json on mount
• Falls back to sensible defaults if loading fails
• Returns loading state for conditional rendering

2. CSS Variable Application

When theme config loads, it automatically sets CSS custom properties:

• --sidebar-width
• --sidebar-bg
• --sidebar-fg
• --sidebar-border
• And many more...

3. Component Usage

The sidebar component uses these CSS variables:

const { themeConfig } = useThemeConfig()
const sidebarWidth = themeConfig.sidebar?.width || '16rem'

Benefits

1. Easy Customization: Change colors, sizes, and spacing without touching code
2. Consistent Theming: Single source of truth for design tokens
3. Runtime Updates: Theme can be modified without rebuilding
4. Type Safety: Full TypeScript support with interfaces
5. Graceful Fallbacks: Defaults ensure app works even if theme.json is missing

Usage Examples

Changing Sidebar Width

Edit theme.json:

{
  "sidebar": {
    "width": "20rem"
  }
}

Changing Color Scheme

{
  "sidebar": {
    "backgroundColor": "oklch(0.25 0.05 280)",
    "accentColor": "oklch(0.65 0.25 200)"
  }
}

Using in Custom Components

import { useThemeConfig } from '@/hooks/use-theme-config'

function MyComponent() {
  const { themeConfig, isLoading } = useThemeConfig()
  
  if (isLoading) return <Skeleton />
  
  return (
    <div style={{ 
      backgroundColor: themeConfig.sidebar?.backgroundColor 
    }}>
      Content
    </div>
  )
}

CSS Variables Reference

The following CSS variables are automatically set:

Sidebar Variables

• --sidebar-width: Sidebar width (default: 16rem)
• --sidebar-width-mobile: Mobile sidebar width (default: 18rem)
• --sidebar-width-icon: Icon-only sidebar width (default: 3rem)
• --sidebar-bg: Sidebar background color
• --sidebar-fg: Sidebar text color
• --sidebar-border: Sidebar border color
• --sidebar-accent: Accent color for highlights
• --sidebar-accent-fg: Accent foreground color
• --sidebar-hover-bg: Hover state background
• --sidebar-active-bg: Active state background
• --sidebar-header-height: Header height
• --sidebar-transition: Transition duration
• --sidebar-z-index: Z-index for layering

Color Variables

All color tokens from theme.json are mapped to CSS variables following the pattern:

• --color-{name}: For each color defined in the theme

Technical Details

Hook Implementation

• Uses useState and useEffect for async loading
• Applies CSS variables via document.documentElement.style.setProperty
• Provides loading state for better UX
• Merges loaded config with defaults using spread operator

Sidebar Component Integration

• Removed hardcoded constants (SIDEBAR_WIDTH, etc.)
• Now reads from theme config
• Falls back to defaults if theme not loaded
• Maintains backward compatibility

CSS Strategy

• Uses CSS custom properties for runtime theming
• Includes fallback values in all properties
• Component-level classes for sidebar-specific styling
• Tailwind theme integration via @theme directive

Future Enhancements

Potential improvements:

1. Hot-reload theme changes in development
2. Theme validation and error reporting
3. Multiple theme support (light/dark/custom)
4. Theme editor UI
5. Theme export/import functionality
6. Animation settings in theme config
7. Breakpoint customization

Migration Notes

If you were previously using hardcoded values:

1. Move those values to theme.json
2. Update components to use useThemeConfig hook
3. Use CSS variables instead of hardcoded colors
4. Test with and without theme.json to ensure fallbacks work