@discourser/design-system 0.2.2 → 0.3.1

package/guidelines/design-tokens/elevation.md

@@ -0,0 +1,274 @@
+# Elevation Tokens
+
+The design system uses Material Design 3 elevation system combining surface tints and shadows to create depth and hierarchy.
+
+## What is Elevation?
+
+Elevation creates visual hierarchy by making elements appear to float above the background. M3 uses two techniques:
+1. **Surface Tints**: Background color changes (via `surfaceContainer*` tokens)
+2. **Shadows**: Subtle shadows for additional depth (optional)
+
+**Important**: M3 primarily uses surface tints, not heavy shadows like older Material Design versions.
+
+## Elevation Levels
+
+| Token | Shadow Value | Usage |
+|-------|--------------|-------|
+| `level0` | none | Flat elements, no elevation |
+| `level1` | `0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)` | Cards (low elevation) |
+| `level2` | `0px 1px 2px rgba(0,0,0,0.3), 0px 2px 6px 2px rgba(0,0,0,0.15)` | Raised cards, FAB (resting) |
+| `level3` | `0px 4px 8px 3px rgba(0,0,0,0.15), 0px 1px 3px rgba(0,0,0,0.3)` | Dialogs, menus |
+| `level4` | `0px 6px 10px 4px rgba(0,0,0,0.15), 0px 2px 3px rgba(0,0,0,0.3)` | FAB (hover), navigation drawers |
+| `level5` | `0px 8px 12px 6px rgba(0,0,0,0.15), 0px 4px 4px rgba(0,0,0,0.3)` | Modals, navigation bars |
+
+## M3 Elevation Strategy
+
+### Primary Method: Surface Containers
+
+M3 primarily uses surface container colors for elevation. Higher elevations get different background colors:
+
+```typescript
+import { css } from '@discourser/design-system/styled-system/css';
+
+// Level 0 (flat, on page)
+const flat = css({ bg: 'surface' });
+
+// Level 1 (low elevation - cards)
+const card = css({ bg: 'surfaceContainerLow' });
+
+// Level 3 (default containers)
+const container = css({ bg: 'surfaceContainer' });
+
+// Level 4 (high elevation - dialogs)
+const dialog = css({ bg: 'surfaceContainerHigh' });
+
+// Level 5 (highest elevation)
+const modal = css({ bg: 'surfaceContainerHighest' });
+```
+
+### Secondary Method: Shadows (Optional)
+
+Shadows can be added for additional depth, but use sparingly:
+
+```typescript
+// Card with subtle shadow
+const card = css({
+  bg: 'surfaceContainerLow',
+  boxShadow: 'level1'  // Optional shadow
+});
+
+// Dialog with shadow
+const dialog = css({
+  bg: 'surfaceContainerHigh',
+  boxShadow: 'level3'
+});
+```
+
+## Component Elevation Mapping
+
+| Component | Surface Container | Shadow Level | Elevation |
+|-----------|-------------------|--------------|-----------|
+| Page background | `surface` | `level0` | 0dp |
+| Filled Card | `surface` | `level0` | 0dp |
+| Outlined Card | `surface` | `level0` | 0dp |
+| Elevated Card | `surfaceContainerLow` | `level1` | 1dp |
+| Input (filled) | `surfaceContainerHighest` | `level0` | 0dp |
+| Button (filled) | `primary` | `level0` | 0dp |
+| Button (elevated) | `surfaceContainerLow` | `level1` | 1dp |
+| Dialog | `surfaceContainerHigh` | `level3` | 3dp |
+| Menu | `surfaceContainer` | `level2` | 2dp |
+| Navigation Drawer | `surfaceContainerLow` | `level1` | 1dp |
+
+## Usage Patterns
+
+### Cards
+
+```typescript
+// Filled card (no elevation)
+const filledCard = css({
+  bg: 'surface',
+  borderColor: 'outlineVariant',
+  borderWidth: '1px'
+});
+
+// Elevated card
+const elevatedCard = css({
+  bg: 'surfaceContainerLow',
+  boxShadow: 'level1'  // Optional
+});
+
+// Outlined card (no elevation)
+const outlinedCard = css({
+  bg: 'surface',
+  borderColor: 'outline',
+  borderWidth: '1px'
+});
+```
+
+### Dialogs and Modals
+
+```typescript
+// Dialog
+const dialog = css({
+  bg: 'surfaceContainerHigh',
+  boxShadow: 'level3',
+  borderRadius: 'large'
+});
+
+// Full-screen modal
+const modal = css({
+  bg: 'surfaceContainerHighest',
+  boxShadow: 'level5'
+});
+
+// Scrim (overlay behind dialog)
+const scrim = css({
+  bg: 'scrim',
+  opacity: 0.32
+});
+```
+
+### Interactive States
+
+Elevation can change on interaction:
+
+```typescript
+// Button hover (increase elevation)
+const button = css({
+  bg: 'surfaceContainerLow',
+  boxShadow: 'level1',
+  _hover: {
+    boxShadow: 'level2'  // Increase shadow on hover
+  }
+});
+
+// Card hover
+const card = css({
+  bg: 'surfaceContainerLow',
+  boxShadow: 'level1',
+  transition: 'box-shadow 0.2s',
+  _hover: {
+    boxShadow: 'level2'
+  }
+});
+```
+
+## What NOT to Do
+
+```typescript
+// ❌ NEVER use arbitrary shadow values
+const wrong = css({
+  boxShadow: '0 4px 6px rgba(0,0,0,0.1)'
+});
+
+// ❌ NEVER use heavy shadows (old Material Design style)
+const wrong = css({
+  boxShadow: '0 10px 40px rgba(0,0,0,0.5)'
+});
+
+// ❌ NEVER use elevation without surface tints
+const wrong = css({
+  bg: '#FFFFFF',  // Raw color
+  boxShadow: 'level1'
+});
+
+// ✅ ALWAYS use surface containers + optional shadows
+const correct = css({
+  bg: 'surfaceContainerLow',
+  boxShadow: 'level1'
+});
+```
+
+## Elevation Hierarchy Rules
+
+1. **Higher elements** should have higher elevation
+2. **Overlays and modals** should be highest (level 4-5)
+3. **Dialogs and menus** should be mid-high (level 2-3)
+4. **Cards and containers** should be low (level 0-1)
+5. **Page backgrounds** should be level 0
+
+### Layering Example
+
+```
+Page Background (surface, level0)
+  ├─ Filled Card (surface, level0)
+  ├─ Elevated Card (surfaceContainerLow, level1)
+  └─ Dialog (surfaceContainerHigh, level3)
+      └─ Button in Dialog (primary, level0)
+```
+
+## Accessibility
+
+### Color Contrast
+Surface tint changes must maintain adequate contrast:
+- Text on elevated surfaces still uses `onSurface` or `onSurfaceVariant`
+- The design system automatically handles this
+
+### Motion and Transitions
+When elevation changes on interaction:
+
+```typescript
+const card = css({
+  transition: 'box-shadow 0.2s cubic-bezier(0.4, 0, 0.2, 1)',
+  _hover: {
+    boxShadow: 'level2'
+  }
+});
+```
+
+Use M3 motion tokens for consistent timing:
+- `fast` (100ms) - Subtle changes
+- `normal` (200ms) - Standard transitions
+- `slow` (300ms) - Emphasized changes
+
+## Dark Mode
+
+Elevation behaves differently in dark mode:
+- **Light mode**: Higher elevation = lighter background
+- **Dark mode**: Higher elevation = lighter background (more tint)
+
+The surface container tokens handle this automatically. No code changes needed.
+
+```typescript
+// Automatically adapts to dark mode
+const card = css({ bg: 'surfaceContainerLow' });
+```
+
+## Component Usage
+
+Most components handle elevation automatically:
+
+```typescript
+import { Card, Dialog, Button } from '@discourser/design-system';
+
+// Card handles elevation via variant
+<Card variant="elevated">Content</Card>  // Auto uses surfaceContainerLow + level1
+
+// Dialog handles elevation automatically
+<Dialog.Content>Dialog content</Dialog.Content>  // Auto uses surfaceContainerHigh + level3
+
+// Button elevated variant
+<Button variant="elevated">Action</Button>  // Auto uses surfaceContainerLow + level1
+```
+
+Only use manual elevation tokens when creating custom layouts outside of components.
+
+## Best Practices
+
+1. **Prefer surface containers** over shadows alone
+2. **Use minimal shadows** - M3 is more subtle than older Material Design
+3. **Maintain hierarchy** - overlays above dialogs above cards
+4. **Animate elevation changes** for smooth interactions
+5. **Test in dark mode** to ensure proper contrast
+6. **Let components handle elevation** when possible
+7. **Use level 0-1 for most content** - save higher levels for overlays
+
+## Common Elevation Mistakes
+
+| ❌ Wrong | ✅ Right | Why |
+|---------|---------|-----|
+| Dialog at level1 | Dialog at level3 | Dialogs should float above content |
+| Heavy `boxShadow: '0 10px 50px'` | `boxShadow: 'level1'` | M3 uses subtle shadows |
+| Card at level5 | Card at level1 | Cards shouldn't float too high |
+| `bg: '#FFF', boxShadow: 'level1'` | `bg: 'surfaceContainerLow'` | Use surface containers, not raw colors |
+| No elevation for dialogs | `bg: 'surfaceContainerHigh'` | Dialogs need visual separation |

package/guidelines/design-tokens/spacing.md

@@ -0,0 +1,289 @@
+# Spacing Tokens
+
+The design system uses a consistent spacing scale based on an 8px grid system for predictable, harmonious layouts.
+
+## Spacing Scale
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `none` | 0px | No spacing, reset margins/padding |
+| `xxs` | 2px | Minimal gaps, icon spacing, borders |
+| `xs` | 4px | Very tight spacing, inline elements |
+| `sm` | 8px | Small gaps, compact layouts |
+| `md` | 16px | Default spacing, most common use |
+| `lg` | 24px | Larger sections, comfortable spacing |
+| `xl` | 32px | Major sections, page margins |
+| `xxl` | 48px | Large sections, page padding |
+| `xxxl` | 64px | Maximum spacing, hero sections |
+
+## Usage Principles
+
+### The 8px Grid
+All spacing values (except `xxs` and `xs`) are multiples of 8px. This creates:
+- Visual rhythm and consistency
+- Predictable alignment
+- Easier mental math for designers and developers
+- Better cross-browser rendering
+
+### Common Patterns
+
+#### Component Internal Spacing
+```typescript
+import { css } from '@discourser/design-system/styled-system/css';
+
+// ✅ Button padding (handled by component)
+const button = css({
+  px: 'md',  // 16px horizontal
+  py: 'sm'   // 8px vertical
+});
+
+// ✅ Card padding
+const card = css({
+  p: 'lg'    // 24px all sides
+});
+
+// ✅ Input field
+const input = css({
+  px: 'md',  // 16px horizontal
+  py: 'sm'   // 8px vertical
+});
+```
+
+#### Layout Spacing
+```typescript
+// ✅ Stack of elements
+const stack = css({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 'md'  // 16px between items
+});
+
+// ✅ Grid layout
+const grid = css({
+  display: 'grid',
+  gap: 'lg'  // 24px between grid items
+});
+
+// ✅ Container with padding
+const container = css({
+  px: { base: 'md', lg: 'xl' },  // Responsive: 16px mobile, 32px desktop
+  py: 'lg'                        // 24px vertical
+});
+```
+
+#### Margin Between Sections
+```typescript
+// ✅ Section spacing
+const section = css({
+  mb: 'xxl'  // 48px bottom margin
+});
+
+// ✅ Page-level spacing
+const page = css({
+  p: { base: 'lg', lg: 'xxl' }  // 24px mobile, 48px desktop
+});
+```
+
+## Common Use Cases
+
+### Component Spacing
+
+| Use Case | Token | Example |
+|----------|-------|---------|
+| Button padding (horizontal) | `md` | 16px |
+| Button padding (vertical) | `sm` | 8px |
+| Input padding | `md` | 16px |
+| Card padding | `lg` or `xl` | 24-32px |
+| Dialog padding | `lg` or `xl` | 24-32px |
+| Icon margins | `xs` or `sm` | 4-8px |
+
+### Layout Spacing
+
+| Use Case | Token | Example |
+|----------|-------|---------|
+| Gap between form fields | `md` | 16px |
+| Gap between cards | `lg` | 24px |
+| Section margins | `xl` or `xxl` | 32-48px |
+| Page margins | `xl` or `xxl` | 32-48px |
+| Hero section padding | `xxxl` | 64px |
+
+### Content Spacing
+
+| Use Case | Token | Example |
+|----------|-------|---------|
+| Paragraph margins | `md` | 16px |
+| List item spacing | `sm` or `md` | 8-16px |
+| Icon-text gap | `xs` or `sm` | 4-8px |
+| Button group gap | `sm` | 8px |
+
+## Usage in Code
+
+### Padding
+
+```typescript
+import { css } from '@discourser/design-system/styled-system/css';
+
+// All sides
+const box = css({ p: 'md' });  // 16px all sides
+
+// Individual sides
+const box = css({
+  pt: 'lg',   // padding-top: 24px
+  pr: 'md',   // padding-right: 16px
+  pb: 'lg',   // padding-bottom: 24px
+  pl: 'md'    // padding-left: 16px
+});
+
+// Horizontal/Vertical
+const box = css({
+  px: 'md',  // padding-left + padding-right: 16px
+  py: 'sm'   // padding-top + padding-bottom: 8px
+});
+```
+
+### Margin
+
+```typescript
+// All sides
+const box = css({ m: 'md' });  // 16px all sides
+
+// Individual sides
+const box = css({
+  mt: 'lg',   // margin-top: 24px
+  mr: 'md',   // margin-right: 16px
+  mb: 'lg',   // margin-bottom: 24px
+  ml: 'md'    // margin-left: 16px
+});
+
+// Horizontal/Vertical
+const box = css({
+  mx: 'auto',  // margin-left + margin-right: auto (centering)
+  my: 'lg'     // margin-top + margin-bottom: 24px
+});
+```
+
+### Gap (Flexbox/Grid)
+
+```typescript
+// Flex/Grid gap
+const stack = css({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 'md'  // 16px between all children
+});
+
+// Different horizontal/vertical gaps
+const grid = css({
+  display: 'grid',
+  rowGap: 'lg',    // 24px between rows
+  columnGap: 'md'  // 16px between columns
+});
+```
+
+## Responsive Spacing
+
+Use different spacing values at different breakpoints:
+
+```typescript
+const container = css({
+  // Mobile: 16px padding
+  // Desktop: 32px padding
+  p: { base: 'md', lg: 'xl' }
+});
+
+const section = css({
+  // Mobile: 24px margin
+  // Desktop: 48px margin
+  mb: { base: 'lg', lg: 'xxl' }
+});
+```
+
+## What NOT to Do
+
+```typescript
+// ❌ NEVER use arbitrary pixel values
+const wrong = css({ padding: '17px' });
+const wrong = css({ margin: '13px' });
+
+// ❌ NEVER use rem/em values directly
+const wrong = css({ padding: '1.5rem' });
+
+// ❌ NEVER use non-token spacing
+const wrong = css({ gap: '20px' });
+
+// ✅ ALWAYS use spacing tokens
+const correct = css({ p: 'md', gap: 'lg' });
+```
+
+## Special Cases
+
+### Zero Spacing
+```typescript
+// Reset spacing
+const reset = css({
+  m: 'none',  // margin: 0
+  p: 'none'   // padding: 0
+});
+```
+
+### Negative Margins
+```typescript
+// Negative margins (use sparingly)
+const overlap = css({
+  mt: 'calc(var(--spacing-md) * -1)'  // -16px
+});
+```
+
+### Custom Spacing (Rare)
+Only use custom spacing when absolutely necessary and none of the tokens fit:
+
+```typescript
+// Last resort - custom spacing
+const custom = css({
+  padding: 'calc(var(--spacing-sm) + var(--spacing-xs))'  // 8px + 4px = 12px
+});
+```
+
+## Accessibility
+
+Proper spacing improves:
+- **Touch targets**: Minimum 44x44px (use appropriate padding)
+- **Readability**: Adequate spacing between text blocks
+- **Scannability**: Clear visual separation between sections
+- **Focus indicators**: Enough space for focus outlines
+
+### Minimum Touch Target Spacing
+
+```typescript
+// ✅ Adequate touch target (Button component handles this)
+const button = css({
+  minHeight: '44px',
+  px: 'md',
+  py: 'sm'
+});
+
+// ✅ Spacing between interactive elements
+const buttonGroup = css({
+  display: 'flex',
+  gap: 'sm'  // Minimum 8px between buttons
+});
+```
+
+## Best Practices
+
+1. **Prefer fewer, larger gaps** over many small gaps
+2. **Use consistent spacing** within similar components
+3. **Increase spacing** for more important separations
+4. **Follow the 8px grid** whenever possible
+5. **Test on mobile** to ensure adequate touch targets
+6. **Use responsive spacing** for better mobile/desktop experiences
+
+## Common Spacing Mistakes
+
+| ❌ Wrong | ✅ Right | Why |
+|---------|---------|-----|
+| `gap: 'xs'` for cards | `gap: 'lg'` | Cards need breathing room |
+| `p: 'xxxl'` for button | `px: 'md', py: 'sm'` | Too much padding overwhelms |
+| `mb: 'sm'` for sections | `mb: 'xl'` or `'xxl'` | Sections need clear separation |
+| `padding: '20px'` | `p: 'lg'` | Use tokens, not arbitrary values |
+| `gap: 'lg'` between icons | `gap: 'xs'` or `'sm'` | Icons are small, need less space |