low-code-react-app-b/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:

```json
{
  "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:
```tsx
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`:
```json
{
  "sidebar": {
    "width": "20rem"
  }
}
```

### Changing Color Scheme
```json
{
  "sidebar": {
    "backgroundColor": "oklch(0.25 0.05 280)",
    "accentColor": "oklch(0.65 0.25 200)"
  }
}
```

### Using in Custom Components
```tsx
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