# Theme Migration Guide

This document explains how to migrate the MetaMuLate theme system to work with @theorchard/suite-components.

## Original Theme System

The HTML implementation uses:
1. CSS custom properties (`:root` variables)
2. `data-theme` attribute for theme switching
3. Tailwind CSS utilities with CSS overrides

### Original Variables

```css
:root {
  /* From original HTML */
  --mm-bg-primary: #0f172a;
  --mm-bg-secondary: #1e293b;
  --mm-border: #334155;
  --mm-text-primary: #e2e8f0;
  --mm-text-secondary: #94a3b8;
  --mm-accent-blue: #3b82f6;
  --mm-accent-emerald: #10b981;
  --mm-accent-amber: #f59e0b;
  --mm-accent-red: #ef4444;
}

[data-theme="orchard"] {
  --mm-accent-blue: #e67e4a;  /* Orchard orange */
  --mm-accent-emerald: #f97316;
}
```

---

## Suite-Components Theme Integration

### Step 1: Extend Suite Theme Provider

```tsx
import { ThemeProvider, createTheme } from '@theorchard/suite-components';

const metamulateTheme = createTheme({
  // Extend suite theme
  colors: {
    // Map to suite semantic colors
    primary: 'var(--mm-accent-blue)',
    success: 'var(--mm-accent-emerald)',
    warning: 'var(--mm-accent-amber)',
    danger: 'var(--mm-accent-red)',
    
    // Custom colors
    'mm-bg-primary': 'var(--mm-bg-primary)',
    'mm-bg-secondary': 'var(--mm-bg-secondary)',
  },
  
  // Console source colors
  consoleSources: {
    apple: '#f472b6',
    discogs: '#f97316',
    musicbrainz: '#fbbf24',
    genius: '#a78bfa',
    lyrics: '#818cf8',
    snowflake: '#38bdf8',
    wikidata: '#22c55e',
    bandcamp: '#06b6d4',
    webscrape: '#6366f1',
  },
});

function App() {
  return (
    <ThemeProvider theme={metamulateTheme}>
      <MetamulateApp />
    </ThemeProvider>
  );
}
```

### Step 2: Theme Switching

```tsx
import { useTheme } from '@theorchard/suite-components';

function ThemeSwitcher() {
  const { theme, setTheme } = useTheme();
  
  return (
    <button onClick={() => setTheme(theme === 'default' ? 'orchard' : 'default')}>
      Switch Theme
    </button>
  );
}
```

### Step 3: Use Theme in Components

```tsx
import { useTheme, Box, Text } from '@theorchard/suite-components';

function ConsoleEntry({ source, message }: { source: string; message: string }) {
  const { theme } = useTheme();
  const sourceColor = theme.consoleSources[source] || theme.colors.text;
  
  return (
    <Box display="flex" gap={2}>
      <Text color={sourceColor}>[{source}]</Text>
      <Text>{message}</Text>
    </Box>
  );
}
```

---

## CSS Custom Property Mapping

### Tailwind → Suite

| Tailwind Class | Suite Component | Notes |
|---------------|-----------------|-------|
| `bg-slate-900` | `<Box bg="background">` | Use semantic names |
| `text-blue-400` | `<Text color="primary">` | Primary action color |
| `text-emerald-400` | `<Text color="success">` | Success/resolved |
| `text-amber-400` | `<Text color="warning">` | Warning state |
| `text-red-400` | `<Text color="danger">` | Error state |
| `border-slate-700` | `<Box borderColor="border">` | Border color |

### Custom Property Fallback

For gradual migration, keep CSS custom properties as fallbacks:

```css
.matrix-cell {
  /* Suite variable with MetaMuLate fallback */
  background: var(--suite-color-surface, var(--mm-bg-secondary));
  border-color: var(--suite-color-border, var(--mm-border));
}
```

---

## Orchard Theme Specifics

### Brand Colors

```css
[data-theme="orchard"] {
  /* Orchard brand orange */
  --mm-accent-blue: #e67e4a;
  
  /* Gradient for buttons */
  --mm-gradient-primary: linear-gradient(135deg, #e67e4a 0%, #f97316 100%);
  
  /* Logo replacement */
  --mm-logo-filter: hue-rotate(30deg);
}
```

### Logo Adaptation

```tsx
function AppLogo({ theme }: { theme: 'default' | 'orchard' }) {
  if (theme === 'orchard') {
    return <OrchardLogo className="w-10 h-10" />;
  }
  return <MetamulateLogo className="w-10 h-10" />;
}
```

---

## Component-Specific Theming

### Matrix Cell

```tsx
import { Box } from '@theorchard/suite-components';

function MatrixCell({ isSelected, isHighlighted }: MatrixCellProps) {
  return (
    <Box
      p={3}
      borderRadius="md"
      borderWidth={1}
      borderColor={isSelected ? 'success' : isHighlighted ? 'primary' : 'border'}
      bg={isSelected ? 'success.subtle' : isHighlighted ? 'primary.subtle' : 'surface'}
      cursor="pointer"
      _hover={{ borderColor: 'primary' }}
    >
      {/* Cell content */}
    </Box>
  );
}
```

### Console Log

```tsx
function ConsoleLog() {
  const { theme } = useTheme();
  
  return (
    <Box
      bg="surface.dark"
      borderTop={1}
      borderColor="border"
      fontFamily="mono"
    >
      {logs.map((log) => (
        <LogEntry 
          key={log.ts}
          level={log.l}
          color={theme.logLevels[log.l]}
        />
      ))}
    </Box>
  );
}
```

---

## Migration Checklist

- [ ] Install `@theorchard/suite-components`
- [ ] Create custom theme extending suite theme
- [ ] Add CSS custom property mapping
- [ ] Update Header component
- [ ] Update Button instances
- [ ] Update Input/Search components
- [ ] Update Modal components
- [ ] Test theme switching
- [ ] Verify Orchard theme colors
- [ ] Check dark mode contrast ratios
- [ ] Update documentation

---

## Testing Themes

```typescript
describe('Theme System', () => {
  it('should switch between default and orchard themes', () => {
    const { getByRole, rerender } = render(
      <ThemeProvider theme="default">
        <Button>Test</Button>
      </ThemeProvider>
    );
    
    expect(getByRole('button')).toHaveStyle({
      background: expect.stringContaining('3b82f6'),
    });
    
    rerender(
      <ThemeProvider theme="orchard">
        <Button>Test</Button>
      </ThemeProvider>
    );
    
    expect(getByRole('button')).toHaveStyle({
      background: expect.stringContaining('e67e4a'),
    });
  });
});
```