@discourser/design-system 0.3.0 → 0.4.0

package/guidelines/components/button.md

@@ -0,0 +1,314 @@
+# Button
+
+**Purpose:** Primary interactive element for user actions following Material Design 3 patterns.
+
+## Import
+
+```typescript
+import { Button } from '@discourser/design-system';
+```
+
+## Variants
+
+The Button component supports 5 Material Design 3 variants, each with specific use cases:
+
+| Variant | Visual Style | Usage | When to Use |
+|---------|-------------|-------|-------------|
+| `filled` | Solid background with primary color | Primary actions | Submit forms, confirm dialogs, main CTAs |
+| `outlined` | Transparent background with border | Secondary actions | Cancel buttons, back navigation, alternative options |
+| `text` | Transparent background, no border | Tertiary actions | Links, less prominent actions, dialog actions |
+| `elevated` | Elevated surface with subtle shadow | Floating actions | FAB-like buttons, actions that need emphasis but not primary color |
+| `tonal` | Filled with secondary container color | Medium emphasis | Secondary CTAs, soft highlights, supportive actions |
+
+### Visual Characteristics
+
+- **filled**: Primary color background, white text, slight shadow on hover
+- **outlined**: Transparent background, primary color text, 1px outline border
+- **text**: Transparent background, primary color text, no border
+- **elevated**: Surface container background, primary color text, level 1 shadow
+- **tonal**: Secondary container background, on-secondary-container text
+
+## Sizes
+
+| Size | Height | Padding (Horizontal) | Font Size | Usage |
+|------|--------|---------------------|-----------|-------|
+| `sm` | 32px | 16px (md) | labelMedium | Compact UI, dense layouts, small dialogs |
+| `md` | 40px | 24px (lg) | labelLarge | Default, most use cases |
+| `lg` | 48px | 32px (xl) | labelLarge | Touch targets, mobile emphasis, hero sections |
+
+**Recommendation:** Use `md` for most cases. Use `lg` for mobile-first designs or prominent CTAs.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'filled' \| 'outlined' \| 'text' \| 'elevated' \| 'tonal'` | `'filled'` | Visual style variant |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
+| `leftIcon` | `ReactNode` | - | Icon or element before button text |
+| `rightIcon` | `ReactNode` | - | Icon or element after button text |
+| `disabled` | `boolean` | `false` | Disable button interaction |
+| `onClick` | `(event: MouseEvent) => void` | - | Click handler |
+| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | HTML button type |
+| `className` | `string` | - | Additional CSS classes (use sparingly) |
+| `children` | `ReactNode` | Required | Button text content |
+
+**Note:** Button extends `ButtonHTMLAttributes<HTMLButtonElement>`, so all standard HTML button attributes are supported.
+
+## Examples
+
+### Basic Usage
+
+```typescript
+// Primary action (default)
+<Button>Submit</Button>
+
+// Secondary action
+<Button variant="outlined">Cancel</Button>
+
+// Tertiary action
+<Button variant="text">Learn More</Button>
+
+// Medium emphasis
+<Button variant="tonal">Save Draft</Button>
+
+// Floating action
+<Button variant="elevated">Create</Button>
+```
+
+### With Icons
+
+```typescript
+import { PlusIcon, ArrowRightIcon } from 'your-icon-library';
+
+// Icon on left
+<Button leftIcon={<PlusIcon />}>
+  Add Item
+</Button>
+
+// Icon on right
+<Button rightIcon={<ArrowRightIcon />}>
+  Continue
+</Button>
+
+// Both icons (rare, but supported)
+<Button leftIcon={<PlusIcon />} rightIcon={<ArrowRightIcon />}>
+  Add and Continue
+</Button>
+```
+
+### Sizes
+
+```typescript
+// Small button (compact UI)
+<Button size="sm">Save</Button>
+
+// Default size
+<Button size="md">Submit</Button>
+
+// Large button (mobile-friendly)
+<Button size="lg">Get Started</Button>
+```
+
+### Form Integration
+
+```typescript
+// Submit button
+<form onSubmit={handleSubmit}>
+  <Input label="Email" />
+  <Button type="submit">Sign Up</Button>
+</form>
+
+// Reset button
+<Button type="reset" variant="text">Reset Form</Button>
+```
+
+### Disabled State
+
+```typescript
+const [isSubmitting, setIsSubmitting] = useState(false);
+
+<Button disabled={isSubmitting}>
+  {isSubmitting ? 'Submitting...' : 'Submit'}
+</Button>
+```
+
+### Event Handling
+
+```typescript
+const handleClick = () => {
+  console.log('Button clicked!');
+};
+
+<Button onClick={handleClick}>Click Me</Button>
+
+// With event parameter
+<Button onClick={(e) => {
+  e.preventDefault();
+  handleSubmit();
+}}>
+  Submit
+</Button>
+```
+
+## Common Patterns
+
+### Primary/Secondary Button Group
+
+```typescript
+<div className={css({ display: 'flex', gap: 'sm' })}>
+  <Button variant="outlined">Cancel</Button>
+  <Button variant="filled">Confirm</Button>
+</div>
+```
+
+### Dialog Actions
+
+```typescript
+<Dialog.Content>
+  <Dialog.Title>Confirm Action</Dialog.Title>
+  <Dialog.Description>Are you sure you want to proceed?</Dialog.Description>
+
+  <div className={css({ display: 'flex', gap: 'sm', justifyContent: 'flex-end' })}>
+    <Button variant="text">Cancel</Button>
+    <Button variant="filled">Confirm</Button>
+  </div>
+</Dialog.Content>
+```
+
+### Loading State
+
+```typescript
+const [loading, setLoading] = useState(false);
+
+<Button disabled={loading}>
+  {loading && <Spinner />}
+  {loading ? 'Loading...' : 'Submit'}
+</Button>
+```
+
+## DO NOT
+
+```typescript
+// ❌ Don't use native button element
+<button className="...">Submit</button>  // Use <Button> instead
+
+// ❌ Don't override button styles with inline styles
+<Button style={{ backgroundColor: 'red' }}>Delete</Button>
+
+// ❌ Don't use multiple filled buttons next to each other (unclear hierarchy)
+<div>
+  <Button variant="filled">Save</Button>
+  <Button variant="filled">Delete</Button>  // Use outlined or text instead
+</div>
+
+// ❌ Don't use button for navigation (use <a> tag or Next.js Link)
+<Button onClick={() => router.push('/page')}>Go to Page</Button>  // Bad
+
+// ❌ Don't omit text for accessibility (use IconButton instead)
+<Button><TrashIcon /></Button>  // Use <IconButton> for icon-only
+
+// ✅ Use IconButton for icon-only actions
+<IconButton aria-label="Delete"><TrashIcon /></IconButton>
+```
+
+## Accessibility
+
+The Button component follows WCAG 2.1 Level AA standards:
+
+- **Keyboard Navigation**: Focusable via Tab key, activates with Enter/Space
+- **Focus Indicator**: 2px outline on focus-visible
+- **Disabled State**: Uses `disabled` attribute, opacity 0.38, pointer-events: none
+- **Touch Target**: Minimum 44x44px (use `md` or `lg` size)
+- **Color Contrast**: All variants meet 4.5:1 contrast ratio
+
+### Accessibility Best Practices
+
+```typescript
+// ✅ Always provide meaningful text
+<Button>Submit Form</Button>
+
+// ✅ Use aria-label for dynamic content
+<Button aria-label={`Delete ${itemName}`}>Delete</Button>
+
+// ✅ Indicate loading state
+<Button aria-busy={loading} disabled={loading}>
+  {loading ? 'Loading...' : 'Submit'}
+</Button>
+
+// ✅ Use proper button types
+<Button type="submit">Submit</Button>
+<Button type="reset">Reset</Button>
+```
+
+## Variant Selection Guide
+
+| Scenario | Recommended Variant | Reasoning |
+|----------|-------------------|-----------|
+| Form submission | `filled` | Primary action, needs highest emphasis |
+| Cancel/Back | `outlined` or `text` | Secondary action, lower emphasis |
+| Dialog confirmation | `filled` | Primary action in dialog |
+| Dialog dismiss | `text` | Tertiary action, minimal emphasis |
+| Save draft | `tonal` | Medium emphasis, not primary action |
+| Delete/Destructive | `filled` or `tonal` | High attention, but consider error colors |
+| Filter/Sort | `text` or `outlined` | Lower emphasis, frequent use |
+| Floating action button | `elevated` | Needs to float above content |
+| Link-like actions | `text` | Minimal emphasis, inline with text |
+
+## State Behaviors
+
+| State | Visual Change | Behavior |
+|-------|---------------|----------|
+| **Hover** | Opacity change or shadow | `filled`: 92% opacity + level1 shadow<br />`outlined`: 8% primary background<br />`elevated`: Increase shadow to level2 |
+| **Active** | Further opacity/shadow change | `filled`: 88% opacity<br />`outlined`: 12% primary background |
+| **Focus** | 2px outline | Primary color outline, 2px offset |
+| **Disabled** | 38% opacity, no interaction | Cannot be clicked, greyed out appearance |
+
+## Responsive Considerations
+
+```typescript
+// Mobile-first: Use larger buttons for touch
+<Button size="lg">Submit</Button>
+
+// Desktop: Can use smaller sizes
+<Button size={{ base: 'lg', md: 'md' }}>Submit</Button>
+
+// Responsive button group
+<div className={css({
+  display: 'flex',
+  flexDirection: { base: 'column', md: 'row' },
+  gap: 'sm'
+})}>
+  <Button variant="outlined">Cancel</Button>
+  <Button variant="filled">Confirm</Button>
+</div>
+```
+
+## Testing
+
+When testing Button components:
+
+```typescript
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+test('button handles click events', async () => {
+  const handleClick = vi.fn();
+  render(<Button onClick={handleClick}>Click Me</Button>);
+
+  const button = screen.getByRole('button', { name: 'Click Me' });
+  await userEvent.click(button);
+
+  expect(handleClick).toHaveBeenCalledOnce();
+});
+
+test('disabled button cannot be clicked', async () => {
+  const handleClick = vi.fn();
+  render(<Button disabled onClick={handleClick}>Click Me</Button>);
+
+  const button = screen.getByRole('button', { name: 'Click Me' });
+  await userEvent.click(button);
+
+  expect(handleClick).not.toHaveBeenCalled();
+  expect(button).toBeDisabled();
+});
+```

package/guidelines/components/card.md

@@ -0,0 +1,353 @@
+# Card
+
+**Purpose:** Container component for grouping related content with Material Design 3 elevation and styling.
+
+## Import
+
+```typescript
+import { Card } from '@discourser/design-system';
+```
+
+## Variants
+
+The Card component supports 3 Material Design 3 variants:
+
+| Variant | Visual Style | Usage | When to Use |
+|---------|-------------|-------|-------------|
+| `elevated` | Surface with shadow, elevated appearance | Default cards, content containers | Most common use case, provides visual hierarchy |
+| `filled` | Filled background, no shadow | Secondary cards, less emphasis | When multiple cards are stacked, alternative style |
+| `outlined` | Outlined border, no shadow | Tertiary cards, minimal style | When you want subtle separation without elevation |
+
+### Visual Characteristics
+
+- **elevated**: `surfaceContainerLow` background, level1 shadow, level2 shadow on hover
+- **filled**: `surfaceContainerHighest` background, no shadow
+- **outlined**: `surface` background, 1px `outlineVariant` border
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'elevated' \| 'filled' \| 'outlined'` | `'elevated'` | Visual style variant |
+| `interactive` | `boolean` | `false` | Makes card clickable with hover/active states |
+| `onClick` | `(event: MouseEvent) => void` | - | Click handler (sets interactive=true automatically) |
+| `className` | `string` | - | Additional CSS classes (use sparingly) |
+| `children` | `ReactNode` | Required | Card content |
+
+**Note:** Card extends `HTMLAttributes<HTMLDivElement>`, so all standard HTML div attributes are supported.
+
+## Examples
+
+### Basic Usage
+
+```typescript
+// Elevated card (default)
+<Card>
+  <h3>Card Title</h3>
+  <p>Card content goes here...</p>
+</Card>
+
+// Filled card
+<Card variant="filled">
+  <h3>Secondary Card</h3>
+  <p>Less emphasized content</p>
+</Card>
+
+// Outlined card
+<Card variant="outlined">
+  <h3>Minimal Card</h3>
+  <p>Subtle separation</p>
+</Card>
+```
+
+### Interactive Cards
+
+```typescript
+// Clickable card
+<Card interactive onClick={() => navigate('/details')}>
+  <h3>Click me!</h3>
+  <p>This card responds to clicks</p>
+</Card>
+
+// Card as link wrapper
+<Card interactive as="a" href="/product">
+  <h3>Product Name</h3>
+  <p>Product description</p>
+</Card>
+```
+
+### With Custom Styling
+
+```typescript
+import { css } from '@discourser/design-system/styled-system/css';
+
+// Card with custom padding
+<Card className={css({ p: 'xl' })}>
+  <h3>Spacious Card</h3>
+  <p>Extra padding for comfort</p>
+</Card>
+
+// Card with custom width
+<Card className={css({ width: '400px' })}>
+  <h3>Fixed Width Card</h3>
+</Card>
+```
+
+## Common Patterns
+
+### Card Grid Layout
+
+```typescript
+import { css } from '@discourser/design-system/styled-system/css';
+
+const gridContainer = css({
+  display: 'grid',
+  gridTemplateColumns: { base: '1fr', md: 'repeat(2, 1fr)', lg: 'repeat(3, 1fr)' },
+  gap: 'lg'
+});
+
+<div className={gridContainer}>
+  <Card>
+    <h3>Card 1</h3>
+    <p>Content 1</p>
+  </Card>
+  <Card>
+    <h3>Card 2</h3>
+    <p>Content 2</p>
+  </Card>
+  <Card>
+    <h3>Card 3</h3>
+    <p>Content 3</p>
+  </Card>
+</div>
+```
+
+### Card with Image
+
+```typescript
+<Card variant="elevated">
+  <img
+    src="/image.jpg"
+    alt="Description"
+    className={css({ width: '100%', height: '200px', objectFit: 'cover' })}
+  />
+  <div className={css({ p: 'lg' })}>
+    <h3 className={css({ textStyle: 'titleLarge', mb: 'sm' })}>
+      Card Title
+    </h3>
+    <p className={css({ textStyle: 'bodyMedium', color: 'onSurfaceVariant' })}>
+      Card description goes here with supporting details.
+    </p>
+  </div>
+</Card>
+```
+
+### Card with Actions
+
+```typescript
+<Card>
+  <div className={css({ p: 'lg' })}>
+    <h3 className={css({ textStyle: 'titleLarge', mb: 'sm' })}>
+      Confirm Action
+    </h3>
+    <p className={css({ textStyle: 'bodyMedium', mb: 'md', color: 'onSurfaceVariant' })}>
+      Are you sure you want to proceed with this action?
+    </p>
+    <div className={css({ display: 'flex', gap: 'sm', justifyContent: 'flex-end' })}>
+      <Button variant="text">Cancel</Button>
+      <Button variant="filled">Confirm</Button>
+    </div>
+  </div>
+</Card>
+```
+
+### List of Cards
+
+```typescript
+const items = [
+  { id: 1, title: 'Item 1', description: 'Description 1' },
+  { id: 2, title: 'Item 2', description: 'Description 2' },
+  { id: 3, title: 'Item 3', description: 'Description 3' },
+];
+
+<div className={css({ display: 'flex', flexDirection: 'column', gap: 'md' })}>
+  {items.map(item => (
+    <Card key={item.id} interactive onClick={() => handleClick(item.id)}>
+      <div className={css({ p: 'lg' })}>
+        <h3 className={css({ textStyle: 'titleMedium' })}>{item.title}</h3>
+        <p className={css({ textStyle: 'bodySmall', color: 'onSurfaceVariant' })}>
+          {item.description}
+        </p>
+      </div>
+    </Card>
+  ))}
+</div>
+```
+
+## DO NOT
+
+```typescript
+// ❌ Don't use div when you need card styling
+<div className={css({ bg: 'surface', borderRadius: 'md', p: 'lg' })}>
+  Content
+</div>  // Use <Card> instead
+
+// ❌ Don't override elevation styles
+<Card style={{ boxShadow: '0 10px 50px rgba(0,0,0,0.5)' }}>
+  Content
+</Card>
+
+// ❌ Don't nest cards inappropriately
+<Card>
+  <Card>Nested card</Card>  // Avoid nesting cards
+</Card>
+
+// ❌ Don't use card for everything (over-cardification)
+<Card>
+  <Card>Login</Card>
+  <Card>Signup</Card>
+</Card>  // Consider simpler layouts
+
+// ✅ Use cards for logical content grouping
+<div className={css({ display: 'flex', gap: 'md' })}>
+  <Card>Login Form</Card>
+  <Card>Signup Form</Card>
+</div>
+```
+
+## Accessibility
+
+The Card component follows accessibility best practices:
+
+- **Semantic HTML**: Uses `<div>` by default, appropriate for content containers
+- **Interactive State**: When `interactive={true}`, card has proper cursor and hover states
+- **Keyboard Navigation**: If used as link/button, ensure proper tabindex and keyboard support
+- **Focus Indicators**: Should add focus styles when interactive
+
+### Accessibility Best Practices
+
+```typescript
+// ✅ Use semantic elements for clickable cards
+<Card as="button" interactive onClick={handleClick} aria-label="View details">
+  Card content
+</Card>
+
+// ✅ Use proper heading hierarchy
+<Card>
+  <h2 className={css({ textStyle: 'titleLarge' })}>Card Title</h2>
+  <p>Content</p>
+</Card>
+
+// ✅ Ensure sufficient color contrast
+<Card>
+  <p className={css({ color: 'onSurface' })}>Primary text</p>
+  <p className={css({ color: 'onSurfaceVariant' })}>Secondary text</p>
+</Card>
+```
+
+## Variant Selection Guide
+
+| Scenario | Recommended Variant | Reasoning |
+|----------|-------------------|-----------|
+| Product cards | `elevated` | Visual hierarchy, draws attention |
+| Form sections | `outlined` | Subtle separation without heavy elevation |
+| Dashboard widgets | `elevated` | Emphasizes different data sections |
+| List items | `outlined` or `filled` | Lighter style for repeated elements |
+| Content previews | `elevated` | Interactive, prominent |
+| Settings sections | `outlined` | Clean, minimal separation |
+
+## State Behaviors
+
+| State | Visual Change | Applies When |
+|-------|---------------|--------------|
+| **Hover** | `elevated`: shadow increases to level2<br />`filled`/`outlined`: slight opacity change | Only when `interactive={true}` |
+| **Active** | Opacity reduces to 0.92 | Only when `interactive={true}` |
+| **Default** | No hover effects | When `interactive={false}` (default) |
+
+## Responsive Considerations
+
+```typescript
+// Responsive card width
+<Card className={css({
+  width: { base: '100%', md: '400px' }
+})}>
+  Content
+</Card>
+
+// Responsive padding
+<Card>
+  <div className={css({ p: { base: 'md', lg: 'xl' } })}>
+    Content with responsive padding
+  </div>
+</Card>
+
+// Responsive grid
+const gridStyles = css({
+  display: 'grid',
+  gridTemplateColumns: {
+    base: '1fr',
+    sm: 'repeat(2, 1fr)',
+    lg: 'repeat(3, 1fr)',
+    xl: 'repeat(4, 1fr)'
+  },
+  gap: 'lg'
+});
+
+<div className={gridStyles}>
+  {items.map(item => <Card key={item.id}>...</Card>)}
+</div>
+```
+
+## Content Padding
+
+Cards have no default padding. Add padding to card content:
+
+```typescript
+// ✅ Recommended: Add padding to content
+<Card>
+  <div className={css({ p: 'lg' })}>
+    Content with padding
+  </div>
+</Card>
+
+// ✅ Or use className on Card itself
+<Card className={css({ p: 'lg' })}>
+  Content
+</Card>
+```
+
+## Testing
+
+```typescript
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+test('interactive card handles clicks', async () => {
+  const handleClick = vi.fn();
+  render(
+    <Card interactive onClick={handleClick}>
+      Card Content
+    </Card>
+  );
+
+  const card = screen.getByText('Card Content').closest('div');
+  await userEvent.click(card);
+
+  expect(handleClick).toHaveBeenCalledOnce();
+});
+
+test('non-interactive card does not trigger clicks', async () => {
+  const handleClick = vi.fn();
+  render(
+    <Card onClick={handleClick}>
+      Card Content
+    </Card>
+  );
+
+  const card = screen.getByText('Card Content').closest('div');
+  await userEvent.click(card);
+
+  // interactive is false by default, so onClick should not be called
+  expect(handleClick).not.toHaveBeenCalled();
+});
+```