@discourser/design-system 0.3.0 → 0.3.1

package/guidelines/components/switch.md

@@ -0,0 +1,457 @@
+# Switch
+
+**Purpose:** Toggle control for binary on/off states following Material Design 3 patterns.
+
+## Import
+
+```typescript
+import { Switch } from '@discourser/design-system';
+```
+
+## Overview
+
+The Switch component provides:
+- Binary on/off toggle functionality
+- Visual feedback for state changes
+- Smooth animation between states
+- Built-in label support
+- Form integration capabilities
+- Keyboard accessibility
+
+## Sizes
+
+| Size | Track Width | Track Height | Thumb Size (off) | Thumb Size (on) | Label Size |
+|------|------------|--------------|------------------|-----------------|-----------|
+| `sm` | 44px | 24px | 12×12px | 16×16px | bodySmall |
+| `md` | 52px | 32px | 16×16px | 24×24px | bodyMedium |
+
+**Note:** The thumb (circle) grows larger when the switch is in the "on" state, following M3 specifications.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | - | Label text displayed next to switch |
+| `checked` | `boolean` | - | Controlled checked state |
+| `defaultChecked` | `boolean` | - | Uncontrolled default checked state |
+| `onCheckedChange` | `(details: { checked: boolean }) => void` | - | Callback when checked state changes |
+| `disabled` | `boolean` | `false` | Disable switch interaction |
+| `name` | `string` | - | Name attribute for form submission |
+| `value` | `string` | - | Value attribute for form submission |
+| `required` | `boolean` | `false` | Whether switch is required in form |
+| `size` | `'sm' \| 'md'` | `'md'` | Switch size |
+
+## Examples
+
+### Basic Usage
+
+```typescript
+// Uncontrolled switch (default off)
+<Switch label="Enable notifications" />
+
+// Uncontrolled with default checked
+<Switch label="Dark mode" defaultChecked />
+
+// Controlled switch
+const [enabled, setEnabled] = useState(false);
+
+<Switch
+  label="Email notifications"
+  checked={enabled}
+  onCheckedChange={({ checked }) => setEnabled(checked)}
+/>
+```
+
+### Different Sizes
+
+```typescript
+// Small switch
+<Switch size="sm" label="Compact toggle" />
+
+// Medium switch (default)
+<Switch size="md" label="Standard toggle" />
+```
+
+### Disabled State
+
+```typescript
+<Switch label="Disabled (off)" disabled />
+
+<Switch label="Disabled (on)" disabled defaultChecked />
+```
+
+### Without Label
+
+```typescript
+// Switch without label (ensure you provide accessibility context elsewhere)
+<Switch />
+```
+
+## Common Patterns
+
+### Settings Panel
+
+```typescript
+const [settings, setSettings] = useState({
+  notifications: true,
+  darkMode: false,
+  autoSave: true,
+});
+
+<div className={css({ display: 'flex', flexDirection: 'column', gap: 'md' })}>
+  <Switch
+    label="Push notifications"
+    checked={settings.notifications}
+    onCheckedChange={({ checked }) =>
+      setSettings({ ...settings, notifications: checked })
+    }
+  />
+  <Switch
+    label="Dark mode"
+    checked={settings.darkMode}
+    onCheckedChange={({ checked }) =>
+      setSettings({ ...settings, darkMode: checked })
+    }
+  />
+  <Switch
+    label="Auto-save"
+    checked={settings.autoSave}
+    onCheckedChange={({ checked }) =>
+      setSettings({ ...settings, autoSave: checked })
+    }
+  />
+</div>
+```
+
+### Form Integration
+
+```typescript
+<form onSubmit={handleSubmit}>
+  <Switch
+    name="terms"
+    value="accepted"
+    label="I agree to the terms and conditions"
+    required
+  />
+
+  <Switch
+    name="newsletter"
+    value="subscribed"
+    label="Subscribe to newsletter (optional)"
+  />
+
+  <Button type="submit">Submit</Button>
+</form>
+```
+
+### With Description
+
+```typescript
+import { css } from '@discourser/design-system/styled-system/css';
+
+<div className={css({ display: 'flex', alignItems: 'flex-start', gap: 'sm' })}>
+  <Switch
+    checked={autoBackup}
+    onCheckedChange={({ checked }) => setAutoBackup(checked)}
+  />
+  <div>
+    <label className={css({ textStyle: 'bodyMedium', fontWeight: 500 })}>
+      Automatic backups
+    </label>
+    <p className={css({ textStyle: 'bodySmall', color: 'onSurfaceVariant', mt: 'xxs' })}>
+      Your data will be backed up automatically every 24 hours
+    </p>
+  </div>
+</div>
+```
+
+### Dynamic Enable/Disable
+
+```typescript
+const [featureEnabled, setFeatureEnabled] = useState(false);
+const [advancedMode, setAdvancedMode] = useState(false);
+
+<>
+  <Switch
+    label="Enable advanced features"
+    checked={featureEnabled}
+    onCheckedChange={({ checked }) => {
+      setFeatureEnabled(checked);
+      if (!checked) setAdvancedMode(false);  // Reset dependent switch
+    }}
+  />
+
+  <Switch
+    label="Advanced mode"
+    checked={advancedMode}
+    onCheckedChange={({ checked }) => setAdvancedMode(checked)}
+    disabled={!featureEnabled}  // Only enabled when feature is on
+  />
+</>
+```
+
+### List of Toggleable Items
+
+```typescript
+const [items, setItems] = useState([
+  { id: 1, name: 'Feature A', enabled: true },
+  { id: 2, name: 'Feature B', enabled: false },
+  { id: 3, name: 'Feature C', enabled: true },
+]);
+
+const toggleItem = (id: number) => {
+  setItems(items.map(item =>
+    item.id === id ? { ...item, enabled: !item.enabled } : item
+  ));
+};
+
+<div className={css({ display: 'flex', flexDirection: 'column', gap: 'sm' })}>
+  {items.map(item => (
+    <Switch
+      key={item.id}
+      label={item.name}
+      checked={item.enabled}
+      onCheckedChange={() => toggleItem(item.id)}
+    />
+  ))}
+</div>
+```
+
+## DO NOT
+
+```typescript
+// ❌ Don't use checkbox for on/off toggles (use Switch instead)
+<input type="checkbox" /> Enable feature
+
+// ✅ Use Switch for binary toggles
+<Switch label="Enable feature" />
+
+// ❌ Don't use Switch for multiple choice (use radio or checkbox)
+<Switch label="Option A" />
+<Switch label="Option B" />
+<Switch label="Option C" />  // Wrong for mutually exclusive options
+
+// ✅ Use radio buttons for mutually exclusive choices
+<input type="radio" name="option" value="a" /> Option A
+<input type="radio" name="option" value="b" /> Option B
+
+// ❌ Don't use Switch for submit actions (use Button instead)
+<Switch label="Submit form" />  // Wrong
+
+// ✅ Use Button for actions
+<Button type="submit">Submit</Button>
+
+// ❌ Don't nest switches or use as navigation
+<Switch label="Navigate to settings" onClick={() => navigate('/settings')} />  // Wrong
+```
+
+## Accessibility
+
+The Switch component follows WCAG 2.1 Level AA standards:
+
+- **Keyboard Navigation**: Toggle with Space key, focus with Tab
+- **ARIA Attributes**: Uses role="switch", aria-checked for state
+- **Labels**: Label associated with switch for screen readers
+- **Focus Indicator**: Visible focus state
+- **State Announcement**: State changes announced to screen readers
+- **Touch Target**: Adequate size for touch interaction
+
+### Accessibility Best Practices
+
+```typescript
+// ✅ Always provide labels for clarity
+<Switch label="Enable notifications" />
+
+// ✅ Use descriptive labels
+<Switch label="Receive email updates" />  // Clear what it toggles
+
+// ❌ Vague labels
+<Switch label="Enable" />  // Enable what?
+
+// ✅ Indicate state in label if needed
+<Switch
+  label={darkMode ? 'Dark mode (on)' : 'Dark mode (off)'}
+  checked={darkMode}
+  onCheckedChange={({ checked }) => setDarkMode(checked)}
+/>
+
+// ✅ Provide context for switch without visible label
+<Switch
+  aria-label="Enable push notifications for this conversation"
+/>
+```
+
+## State Behaviors
+
+| State | Visual Change | Behavior |
+|-------|---------------|----------|
+| **Unchecked** | Track: `surfaceContainerHighest` with `outline` border<br />Thumb: Small, `outline` color, left position | Off state |
+| **Checked** | Track: `primary` color<br />Thumb: Larger, `onPrimary` color, right position | On state |
+| **Hover** | Subtle visual feedback | Interactive feedback |
+| **Focus** | Focus indicator (handled by Ark UI) | Keyboard accessibility |
+| **Disabled** | 38% opacity, greyed out | Cannot be toggled |
+| **Animation** | Smooth thumb transition (fast easing) | Visual confirmation of state change |
+
+## Visual States
+
+### Unchecked (Off)
+- Track background: `surfaceContainerHighest`
+- Track border: 2px `outline`
+- Thumb: Small (16×16px for md), `outline` color
+- Thumb position: Left
+
+### Checked (On)
+- Track background: `primary`
+- Track border: 2px `primary`
+- Thumb: Large (24×24px for md), `onPrimary` color
+- Thumb position: Right
+
+### Disabled
+- Track background: `surfaceVariant`
+- Track border: `onSurface` (12% opacity)
+- Thumb: `onSurface` (38% opacity)
+- Overall opacity: 38%
+
+## Form Integration
+
+```typescript
+// React Hook Form
+import { useForm, Controller } from 'react-hook-form';
+
+const { control, handleSubmit } = useForm();
+
+<form onSubmit={handleSubmit(onSubmit)}>
+  <Controller
+    name="notifications"
+    control={control}
+    defaultValue={false}
+    render={({ field }) => (
+      <Switch
+        label="Enable notifications"
+        checked={field.value}
+        onCheckedChange={({ checked }) => field.onChange(checked)}
+      />
+    )}
+  />
+</form>
+
+// Formik
+import { useFormik } from 'formik';
+
+const formik = useFormik({
+  initialValues: { darkMode: false },
+  onSubmit: values => { /* ... */ },
+});
+
+<Switch
+  label="Dark mode"
+  name="darkMode"
+  checked={formik.values.darkMode}
+  onCheckedChange={({ checked }) => formik.setFieldValue('darkMode', checked)}
+/>
+```
+
+## Use Cases
+
+| Use Case | Recommendation |
+|----------|---------------|
+| Enable/disable feature | ✅ Perfect use case |
+| On/off settings | ✅ Perfect use case |
+| Binary preferences | ✅ Perfect use case |
+| Show/hide sections | ✅ Good use case |
+| Mutually exclusive options | ❌ Use radio buttons |
+| Multiple selections | ❌ Use checkboxes |
+| Trigger actions | ❌ Use buttons |
+
+## Responsive Considerations
+
+```typescript
+// Mobile: Consider using md (default) for better touch targets
+<Switch size="md" label="Enable feature" />
+
+// Desktop: Can use sm for denser layouts
+<Switch size={{ base: 'md', lg: 'sm' }} label="Enable feature" />
+
+// Settings panel with responsive spacing
+<div className={css({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: { base: 'md', lg: 'sm' }
+})}>
+  <Switch label="Notification 1" />
+  <Switch label="Notification 2" />
+  <Switch label="Notification 3" />
+</div>
+```
+
+## Testing
+
+```typescript
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+test('switch toggles checked state', async () => {
+  const handleChange = vi.fn();
+  render(
+    <Switch
+      label="Enable feature"
+      checked={false}
+      onCheckedChange={handleChange}
+    />
+  );
+
+  const switchControl = screen.getByRole('switch', { name: 'Enable feature' });
+  expect(switchControl).not.toBeChecked();
+
+  await userEvent.click(switchControl);
+
+  expect(handleChange).toHaveBeenCalledWith({ checked: true });
+});
+
+test('switch respects disabled state', async () => {
+  const handleChange = vi.fn();
+  render(
+    <Switch
+      label="Disabled switch"
+      disabled
+      onCheckedChange={handleChange}
+    />
+  );
+
+  const switchControl = screen.getByRole('switch', { name: 'Disabled switch' });
+  await userEvent.click(switchControl);
+
+  expect(handleChange).not.toHaveBeenCalled();
+});
+
+test('switch works with keyboard', async () => {
+  const handleChange = vi.fn();
+  render(
+    <Switch
+      label="Keyboard test"
+      checked={false}
+      onCheckedChange={handleChange}
+    />
+  );
+
+  const switchControl = screen.getByRole('switch', { name: 'Keyboard test' });
+  switchControl.focus();
+
+  await userEvent.keyboard(' ');  // Space key
+
+  expect(handleChange).toHaveBeenCalledWith({ checked: true });
+});
+```
+
+## When to Use Switch vs Checkbox
+
+| Feature | Switch | Checkbox |
+|---------|--------|----------|
+| **Purpose** | Toggle state (on/off) | Select option(s) |
+| **Effect** | Immediate | Usually requires submit |
+| **State** | Active/inactive | Selected/unselected |
+| **Typical Use** | Settings, preferences | Forms, multi-select |
+| **Example** | "Enable dark mode" | "I agree to terms" |
+| **Visual** | Track + thumb | Box + checkmark |
+
+**Rule of thumb**: Use Switch when the change takes effect immediately. Use Checkbox when part of a form that needs submission.

package/guidelines/design-tokens/colors.md

@@ -0,0 +1,187 @@
+# Color Tokens
+
+The design system uses Material Design 3 semantic color tokens. **Always use semantic tokens, never raw hex values.**
+
+## Why Semantic Colors?
+
+Semantic colors automatically adapt to light/dark themes and follow M3 color roles. Using semantic names ensures:
+- Automatic theme switching
+- Consistent contrast ratios
+- Proper color relationships
+- Accessibility compliance
+
+## Semantic Colors Reference
+
+### Primary Colors
+Used for primary actions, key UI elements, and brand identity.
+
+| Token | Light Mode | Dark Mode | Usage |
+|-------|-----------|-----------|-------|
+| `primary` | #4C662B | #B1D18A | Primary buttons, active states, links |
+| `onPrimary` | #FFFFFF | #1F3701 | Text/icons on primary color |
+| `primaryContainer` | #CDEDA3 | #354E16 | Containers for primary content |
+| `onPrimaryContainer` | #354E16 | #CDEDA3 | Text/icons on primary container |
+
+### Secondary Colors
+Used for secondary actions and less prominent UI elements.
+
+| Token | Light Mode | Dark Mode | Usage |
+|-------|-----------|-----------|-------|
+| `secondary` | #586249 | #BFCBAD | Secondary buttons, less prominent actions |
+| `onSecondary` | #FFFFFF | #2A331E | Text/icons on secondary color |
+| `secondaryContainer` | #DCE7C8 | #404A33 | Secondary containers |
+| `onSecondaryContainer` | #404A33 | #DCE7C8 | Text/icons on secondary container |
+
+### Tertiary Colors
+Used for accent colors and tertiary actions.
+
+| Token | Light Mode | Dark Mode | Usage |
+|-------|-----------|-----------|-------|
+| `tertiary` | #386663 | #A0D0CB | Accent colors, tertiary actions |
+| `onTertiary` | #FFFFFF | #003735 | Text/icons on tertiary color |
+| `tertiaryContainer` | #BCECE7 | #1F4E4B | Tertiary containers |
+| `onTertiaryContainer` | #1F4E4B | #BCECE7 | Text/icons on tertiary container |
+
+### Error Colors
+Used for error states, warnings, and destructive actions.
+
+| Token | Light Mode | Dark Mode | Usage |
+|-------|-----------|-----------|-------|
+| `error` | #BA1A1A | #FFB4AB | Error text, error icons |
+| `onError` | #FFFFFF | #690005 | Text/icons on error color |
+| `errorContainer` | #FFDAD6 | #93000A | Error message backgrounds |
+| `onErrorContainer` | #93000A | #FFDAD6 | Text/icons in error containers |
+
+### Surface Colors
+Used for backgrounds and containers at different elevations.
+
+| Token | Light Mode | Dark Mode | Usage |
+|-------|-----------|-----------|-------|
+| `surface` | #F9FAEF | #12140E | Default background |
+| `onSurface` | #1A1C16 | #E2E3D8 | Default text color |
+| `surfaceVariant` | #E1E4D5 | #44483D | Alternate surface (subtle contrast) |
+| `onSurfaceVariant` | #44483D | #C5C8BA | Text on variant surfaces |
+
+### Surface Container Elevations
+M3 uses surface tints instead of shadows for elevation. Higher elevations get lighter in light mode, darker in dark mode.
+
+| Token | Light Mode | Dark Mode | Usage |
+|-------|-----------|-----------|-------|
+| `surfaceContainerLowest` | #FFFFFF | #0C0F09 | Lowest elevation (0dp) |
+| `surfaceContainerLow` | #F3F4E9 | #1A1C16 | Low elevation (1dp) - Cards |
+| `surfaceContainer` | #EEEFE3 | #1E201A | Default containers (3dp) |
+| `surfaceContainerHigh` | #E8E9DE | #282B24 | High elevation (4dp) - Dialogs |
+| `surfaceContainerHighest` | #E2E3D8 | #33362E | Highest elevation (5dp) |
+
+### Outline Colors
+Used for borders and dividers.
+
+| Token | Light Mode | Dark Mode | Usage |
+|-------|-----------|-----------|-------|
+| `outline` | #75796C | #8F9285 | Borders, dividers |
+| `outlineVariant` | #C5C8BA | #44483D | Subtle borders |
+
+### Inverse Colors
+Used for inverse color schemes (e.g., snackbars).
+
+| Token | Light Mode | Dark Mode | Usage |
+|-------|-----------|-----------|-------|
+| `inverseSurface` | #2F312A | #E2E3D8 | Inverse backgrounds |
+| `inverseOnSurface` | #F1F2E6 | #2F312A | Text on inverse surfaces |
+| `inversePrimary` | #B1D18A | #4C662B | Primary color on inverse |
+
+### Background Colors
+Used for page/app backgrounds.
+
+| Token | Light Mode | Dark Mode | Usage |
+|-------|-----------|-----------|-------|
+| `background` | #F9FAEF | #12140E | Page background |
+| `onBackground` | #1A1C16 | #E2E3D8 | Text on background |
+
+### Special Colors
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `scrim` | #000000 | Overlay behind modals/dialogs |
+| `shadow` | #000000 | Shadow color (rarely used directly) |
+
+## Usage in Code
+
+### Using Semantic Tokens in Components
+
+```typescript
+import { css } from '@discourser/design-system/styled-system/css';
+
+// ✅ Correct - Use semantic tokens
+const container = css({
+  bg: 'surfaceContainerLow',
+  color: 'onSurface',
+  borderColor: 'outline'
+});
+
+const primaryAction = css({
+  bg: 'primary',
+  color: 'onPrimary'
+});
+
+const errorMessage = css({
+  bg: 'errorContainer',
+  color: 'onErrorContainer'
+});
+```
+
+### Common Patterns
+
+```typescript
+// Card backgrounds
+bg: 'surfaceContainerLow'  // For elevated cards
+bg: 'surface'              // For filled/outlined cards
+
+// Text colors
+color: 'onSurface'         // Primary text
+color: 'onSurfaceVariant'  // Secondary text
+
+// Borders
+borderColor: 'outline'     // Standard borders
+borderColor: 'outlineVariant' // Subtle borders
+
+// Interactive states
+bg: 'primary'              // Default
+bg: 'primaryContainer'     // Hover/focus
+color: 'onPrimary'         // Text on primary
+```
+
+## What NOT to Do
+
+```typescript
+// ❌ NEVER use raw hex colors
+const wrong = css({ bg: '#4C662B' });
+
+// ❌ NEVER use RGB values
+const wrong = css({ bg: 'rgb(76, 102, 43)' });
+
+// ❌ NEVER hardcode light/dark colors
+const wrong = css({ bg: mode === 'dark' ? '#000' : '#fff' });
+
+// ✅ ALWAYS use semantic tokens
+const correct = css({ bg: 'surface' });
+```
+
+## Color Combinations
+
+Always pair colors with their corresponding "on" color for proper contrast:
+
+| Background | Text/Icon Color | Use Case |
+|-----------|----------------|----------|
+| `primary` | `onPrimary` | Filled buttons |
+| `primaryContainer` | `onPrimaryContainer` | Tonal buttons, chips |
+| `surface` | `onSurface` | Default backgrounds |
+| `surfaceVariant` | `onSurfaceVariant` | Alternate surfaces |
+| `error` | `onError` | Error badges |
+| `errorContainer` | `onErrorContainer` | Error messages |
+
+## Accessibility
+
+All semantic color combinations meet WCAG 2.1 Level AA contrast requirements (4.5:1 for normal text, 3:1 for large text).
+
+**Never override these combinations** unless you verify contrast ratios yourself.