import { Meta } from '@storybook/addon-docs/blocks';
import { SemanticSwatch } from './components/ColorSwatch';

<Meta title="Foundations/Colors" />

# Colors

The Discourser Design System uses Material Design 3's color system, which provides a comprehensive palette of colors organized into tonal palettes and semantic tokens.

## Color Philosophy

Material Design 3 uses a three-tiered color system:

1. **Tonal Palettes**: Base color scales from 0-100, generated from source colors
2. **Semantic Tokens**: Context-aware color roles that adapt to light/dark themes
3. **Dynamic Color**: Colors that work harmoniously together across all contexts

## Tonal Palettes

> **These are internal pipeline values.** Tonal palette steps (0–100) are used to build the Radix-scale and semantic tokens — they are not Panda CSS tokens and should never be used directly in components. To see the usable color vocabulary, open **Foundations → Color Scale** in the sidebar.

---

## Semantic Tokens

Semantic tokens are context-aware colors that automatically adapt to light and dark themes. **Always use semantic tokens in your components** instead of directly referencing tonal palette values.

### Primary Colors

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))', gap: '24px', marginBottom: '32px' }}>
  <SemanticSwatch
    name="primary"
    description="Primary brand color for key actions and emphasis"
  />
  <SemanticSwatch
    name="onPrimary"
    description="Text/icons on primary color"
  />
  <SemanticSwatch
    name="primaryContainer"
    description="Container for primary elements"
  />
  <SemanticSwatch
    name="onPrimaryContainer"
    description="Text/icons on primary container"
  />
</div>

### Secondary Colors

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))', gap: '24px', marginBottom: '32px' }}>
  <SemanticSwatch
    name="secondary"
    description="Secondary actions and less prominent elements"
  />
  <SemanticSwatch
    name="onSecondary"
    description="Text/icons on secondary color"
  />
  <SemanticSwatch
    name="secondaryContainer"
    description="Container for secondary elements"
  />
  <SemanticSwatch
    name="onSecondaryContainer"
    description="Text/icons on secondary container"
  />
</div>

### Tertiary Colors

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))', gap: '24px', marginBottom: '32px' }}>
  <SemanticSwatch
    name="tertiary"
    description="Contrasting accent color for visual interest"
  />
  <SemanticSwatch
    name="onTertiary"
    description="Text/icons on tertiary color"
  />
  <SemanticSwatch
    name="tertiaryContainer"
    description="Container for tertiary elements"
  />
  <SemanticSwatch
    name="onTertiaryContainer"
    description="Text/icons on tertiary container"
  />
</div>

### Error Colors

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))', gap: '24px', marginBottom: '32px' }}>
  <SemanticSwatch
    name="error"
    description="Error states and destructive actions"
  />
  <SemanticSwatch
    name="onError"
    description="Text/icons on error color"
  />
  <SemanticSwatch
    name="errorContainer"
    description="Container for error messages"
  />
  <SemanticSwatch
    name="onErrorContainer"
    description="Text/icons on error container"
  />
</div>

### Surface Colors

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))', gap: '24px', marginBottom: '32px' }}>
  <SemanticSwatch
    name="surface"
    description="Base surface color for cards and containers"
  />
  <SemanticSwatch
    name="onSurface"
    description="Primary text and icons on surface"
  />
  <SemanticSwatch
    name="surfaceVariant"
    description="Alternative surface for variety"
  />
  <SemanticSwatch
    name="onSurfaceVariant"
    description="Text/icons on surface variant"
  />
</div>

### Surface Containers

M3 provides 5 surface container levels for creating subtle depth without elevation.

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))', gap: '24px', marginBottom: '32px' }}>
  <SemanticSwatch
    name="surfaceContainerLowest"
    description="Lowest container level"
  />
  <SemanticSwatch
    name="surfaceContainerLow"
    description="Low container level"
  />
  <SemanticSwatch
    name="surfaceContainer"
    description="Default container level"
  />
  <SemanticSwatch
    name="surfaceContainerHigh"
    description="High container level"
  />
  <SemanticSwatch
    name="surfaceContainerHighest"
    description="Highest container level"
  />
</div>

### Outline Colors

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))', gap: '24px', marginBottom: '32px' }}>
  <SemanticSwatch
    name="outline"
    description="Important borders and dividers"
  />
  <SemanticSwatch
    name="outlineVariant"
    description="Decorative borders and dividers"
  />
</div>

### Inverse Colors

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))', gap: '24px', marginBottom: '32px' }}>
  <SemanticSwatch
    name="inverseSurface"
    description="Inverted surface (e.g., tooltips, snackbars)"
  />
  <SemanticSwatch
    name="inverseOnSurface"
    description="Text on inverse surface"
  />
  <SemanticSwatch
    name="inversePrimary"
    description="Primary color on inverse surface"
  />
  <SemanticSwatch
    name="inverseSecondary"
    description="Secondary color on inverse surface (light mode = dark palette value)"
  />
  <SemanticSwatch
    name="inverseTertiary"
    description="Tertiary color on inverse surface (light mode = dark palette value)"
  />
</div>

### Utility Colors

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))', gap: '24px', marginBottom: '32px' }}>
  <SemanticSwatch
    name="background"
    description="Page background color"
  />
  <SemanticSwatch
    name="onBackground"
    description="Text/icons on background"
  />
  <SemanticSwatch
    name="scrim"
    description="Overlay for modals and dialogs"
  />
  <SemanticSwatch
    name="shadow"
    description="Shadow color for elevation"
  />
</div>

---

## Usage Guidelines

### When to Use Semantic Tokens vs Tonal Palettes

**✅ Always use semantic tokens** for:
- Component backgrounds and text
- Interactive states (hover, focus, disabled)
- Theme-aware UI elements
- Any production code

**⚠️ Only use tonal palettes** when:
- Creating new semantic tokens
- Generating custom color schemes
- Design exploration and prototyping

### Example Usage in Components

```tsx
import { css } from 'styled-system/css';

// ✅ Good: Using semantic tokens
const buttonStyle = css({
  bg: 'primary',
  color: 'onPrimary',
  _hover: {
    bg: 'primary.container'
  }
});

// ❌ Bad: Using tonal palette directly
const buttonStyle = css({
  bg: '#4C662B', // Hard-coded color
  color: '#FFFFFF'
});
```

### Accessibility

All semantic token pairings (e.g., `primary` with `onPrimary`) meet WCAG AA contrast requirements. When creating custom combinations, always verify contrast ratios.