import { Meta } from '@storybook/addon-docs/blocks';
import { ElevationGrid, elevationClasses } from './components/ElevationCard';

<Meta title="Foundations/Elevation" />

# Elevation

Elevation in Material Design 3 creates depth and hierarchy through the use of shadows. The Discourser Design System provides 6 elevation levels, from no elevation to the highest prominence.

## Token Architecture

The elevation system uses a **three-layer architecture** for flexibility and consistency:

### Layer 1: Base Tokens (Material 3 Values)
The foundation layer contains actual M3 elevation values:
- `level0` through `level5` — Registered via `transform.ts`
- Contains raw shadow CSS values from Material Design 3 spec
- **Do not use directly in components**

### Layer 2: Semantic Tokens (Design Intent)
The middle layer maps design intent to base tokens:
- `xs`, `sm`, `md`, `lg`, `xl`, `2xl` — Defined in `src/preset/shadows.ts`
- Each semantic token references a base token (e.g., `sm` → `{shadows.level2}`)
- Provides meaningful names that express elevation purpose

### Layer 3: Component Usage
Components use semantic tokens for flexibility:
```tsx
// ✅ Use semantic tokens in components
boxShadow: 'xs'   // level1 — subtle cards
boxShadow: 'sm'   // level2 — default cards
boxShadow: 'md'   // level3 — dialogs, dropdowns
boxShadow: 'lg'   // level4 — drawers, sheets
boxShadow: 'xl'   // level5 — FABs, tooltips

// ❌ Don't use base tokens directly — these are internal only
boxShadow: 'level1'
boxShadow: 'level2'
```

**Shadow semantic token map:** `xs`=level1, `sm`=level2, `md`=level3, `lg`=level4, `xl`=level5.

This architecture allows the design language to be swapped by changing which base tokens the semantic layer references, without touching component code.

## Elevation Scale

<ElevationGrid />

---

## Elevation Reference

| M3 Level | Semantic Token | Shadow Value | Use Case |
|----------|---------------|--------------|----------|
| **level0** | (no shadow) | none | Flat elements, no elevation needed |
| **level1** | **`xs`** | `0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)` | Cards at rest, contained buttons |
| **level2** | **`sm`** | `0px 1px 2px rgba(0,0,0,0.3), 0px 2px 6px 2px rgba(0,0,0,0.15)` | Cards on hover, raised buttons |
| **level3** | **`md`** | `0px 4px 8px 3px rgba(0,0,0,0.15), 0px 1px 3px rgba(0,0,0,0.3)` | Dialogs, dropdowns, popovers |
| **level4** | **`lg`** | `0px 6px 10px 4px rgba(0,0,0,0.15), 0px 2px 3px rgba(0,0,0,0.3)` | Navigation drawer, modal sheets |
| **level5** | **`xl`** | `0px 8px 12px 6px rgba(0,0,0,0.15), 0px 4px 4px rgba(0,0,0,0.3)` | Floating action buttons, tooltips |

---

## Usage Guidelines

### Component Elevation Hierarchy

Material Design 3 uses elevation to communicate importance and interactivity:

**Level 0 (No Elevation)**
- Background surfaces
- Flat buttons
- Content that shouldn't float

**Level 1 (Subtle)**
- Cards in their default state
- Contained buttons
- Search bars
- List items with separation

**Level 2 (Moderate)**
- Cards on hover
- Raised buttons
- Chips
- App bars

**Level 3 (Prominent)**
- Dialogs and modals
- Dropdown menus
- Date pickers
- Autocomplete suggestions

**Level 4 (High)**
- Navigation drawers
- Bottom sheets
- Side sheets
- Large modals

**Level 5 (Highest)**
- Floating Action Buttons (FAB)
- Tooltips
- Snackbars
- Banner notifications

### Interactive States

Use elevation changes to indicate interactivity:

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

const interactiveCardStyle = css({
  boxShadow: 'xs',
  transition: 'box-shadow 200ms',
  _hover: {
    boxShadow: 'sm'
  }
});
```

### Accessibility Considerations

**Don't rely on elevation alone** to convey meaning:
- Elevation is visual only
- Use proper semantic HTML
- Provide alternative cues (borders, colors, icons)
- Consider users with low vision or color blindness

### Dark Mode

Elevation works differently in dark themes:
- In light themes, shadows create depth
- In dark themes, surfaces also get lighter tints with higher elevation
- This is handled automatically by Material Design 3

---

## Visual Comparison

### Cards with Different Elevations

<div style={{
  display: 'grid',
  gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))',
  gap: '24px',
  padding: '32px',
  backgroundColor: '#f5f5f5',
  borderRadius: '8px',
  marginBottom: '32px'
}}>
  <div
    className={elevationClasses['level0']}
    style={{ padding: '24px', backgroundColor: '#fff', borderRadius: '12px', textAlign: 'center' }}
  >
    <div style={{ fontWeight: '600', marginBottom: '8px' }}>Level 0</div>
    <div style={{ fontSize: '12px', color: '#666' }}>Flat surface</div>
  </div>

  <div
    className={elevationClasses['level1']}
    style={{ padding: '24px', backgroundColor: '#fff', borderRadius: '12px', textAlign: 'center' }}
  >
    <div style={{ fontWeight: '600', marginBottom: '8px' }}>Level 1</div>
    <div style={{ fontSize: '12px', color: '#666' }}>Subtle depth</div>
  </div>

  <div
    className={elevationClasses['level2']}
    style={{ padding: '24px', backgroundColor: '#fff', borderRadius: '12px', textAlign: 'center' }}
  >
    <div style={{ fontWeight: '600', marginBottom: '8px' }}>Level 2</div>
    <div style={{ fontSize: '12px', color: '#666' }}>Moderate depth</div>
  </div>
</div>

### Floating Elements

<div style={{
  display: 'grid',
  gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))',
  gap: '24px',
  padding: '32px',
  backgroundColor: '#f5f5f5',
  borderRadius: '8px'
}}>
  <div
    className={elevationClasses['level3']}
    style={{ padding: '24px', backgroundColor: '#fff', borderRadius: '12px', textAlign: 'center' }}
  >
    <div style={{ fontWeight: '600', marginBottom: '8px' }}>Level 3</div>
    <div style={{ fontSize: '12px', color: '#666' }}>Prominent float</div>
  </div>

  <div
    className={elevationClasses['level4']}
    style={{ padding: '24px', backgroundColor: '#fff', borderRadius: '12px', textAlign: 'center' }}
  >
    <div style={{ fontWeight: '600', marginBottom: '8px' }}>Level 4</div>
    <div style={{ fontSize: '12px', color: '#666' }}>High elevation</div>
  </div>

  <div
    className={elevationClasses['level5']}
    style={{ padding: '24px', backgroundColor: '#fff', borderRadius: '12px', textAlign: 'center' }}
  >
    <div style={{ fontWeight: '600', marginBottom: '8px' }}>Level 5</div>
    <div style={{ fontSize: '12px', color: '#666' }}>Highest elevation</div>
  </div>
</div>

---

## Example Usage

### Basic Elevation

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

const cardStyle = css({
  boxShadow: 'sm',   // level2 — default card elevation
  borderRadius: 'l3',
  padding: 'lg'
});
```

### Interactive Elevation

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

const elevatedButtonStyle = css({
  boxShadow: 'sm',
  transition: 'all',
  transitionDuration: 'fast',
  _hover: {
    boxShadow: 'md'
  },
  _active: {
    boxShadow: 'xs'
  }
});
```

### Modal Overlay

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

const modalStyle = css({
  position: 'fixed',
  top: '50%',
  left: '50%',
  transform: 'translate(-50%, -50%)',
  boxShadow: 'md',   // level3 — dialog elevation
  borderRadius: 'l3',
  backgroundColor: 'surface.container.high',
  padding: 'xl'
});
```

---

## Best Practices

### Do's ✅

- Use elevation consistently across similar components
- Animate elevation changes for smooth transitions
- Reserve higher elevations for truly important elements
- Test elevation in both light and dark themes
- Consider mobile devices where shadows may be subtle

### Don'ts ❌

- Don't use too many different elevation levels on one screen
- Don't stack elements with the same elevation
- Don't use elevation as the only indicator of interactivity
- Don't apply elevation to every element
- Don't forget to transition elevation changes

### Performance

Shadows can impact rendering performance:
- Use CSS box-shadow (not filters) for best performance
- Consider reducing elevation complexity on mobile
- Avoid animating shadows on many elements simultaneously
- Test on low-end devices

---

## Surface Containers vs Elevation

Material Design 3 provides two ways to create depth:

**Elevation (Shadows)**
- Creates visual depth through shadows
- Best for floating elements
- More prominent visual effect
- Works in both light and dark themes

**Surface Containers (Tonal Levels)**
- Creates depth through color tints
- Best for stacked surfaces
- Subtle, material-like layering
- See the Colors documentation for surface container tokens

Use surface containers for general layering, and elevation for interactive or floating elements.