@discourser/design-system 0.4.0 → 0.6.0

package/guidelines/Guidelines.md

@@ -10,20 +10,24 @@ Before writing any code, follow these steps IN ORDER:
 
 Read ALL files with a name that starts with "overview-":
 
-- `overview-components.md` - Available components and usage patterns
+- **[overview-components.md](overview-components.md)** - Available components with quick reference tables
+- **[overview-imports.md](overview-imports.md)** - Package installation and import patterns
+- **[overview-patterns.md](overview-patterns.md)** - Common UI patterns combining multiple components
 
 ### Step 2: Read Design Token Files (REQUIRED)
 
 Read ALL files in the `design-tokens/` folder:
 
-- `design-tokens/colors.md`
-- `design-tokens/typography.md`
-- `design-tokens/spacing.md`
-- `design-tokens/elevation.md`
+- **[design-tokens/colors.md](design-tokens/colors.md)** - Semantic color tokens and usage
+- **[design-tokens/typography.md](design-tokens/typography.md)** - Typography scale and text styles
+- **[design-tokens/spacing.md](design-tokens/spacing.md)** - Spacing system and layout
+- **[design-tokens/elevation.md](design-tokens/elevation.md)** - Surface elevation and shadows
 
 ### Step 3: Plan Components Needed (REQUIRED)
 
-Identify which components you need to use.
+Identify which components you need to use based on your task.
+
+Refer to [overview-components.md](overview-components.md) for the complete list.
 
 ### Step 4: Read Component Guidelines BEFORE Using Components (REQUIRED)
 
@@ -31,44 +35,48 @@ BEFORE using ANY component, you MUST read its guidelines file first:
 
 **Interactive Elements:**
 
-- Using Button? → Read `components/button.md` FIRST
-- Using IconButton? → Read `components/icon-button.md` FIRST
-- Using Switch? → Read `components/switch.md` FIRST
-- Using Checkbox? → Read `components/checkbox.md` FIRST
-- Using RadioGroup? → Read `components/radio-group.md` FIRST
+- Using Button? → Read **[components/button.md](components/button.md)** FIRST
+- Using IconButton? → Read **[components/icon-button.md](components/icon-button.md)** FIRST
+- Using Switch? → Read **[components/switch.md](components/switch.md)** FIRST
+- Using Checkbox? → Read **[components/checkbox.md](components/checkbox.md)** FIRST
+- Using RadioGroup? → Read **[components/radio-group.md](components/radio-group.md)** FIRST
 
 **Form Elements:**
 
-- Using Input? → Read `components/input.md` FIRST
-- Using Textarea? → Read `components/textarea.md` FIRST
-- Using Select? → Read `components/select.md` FIRST
+- Using Input? → Read **[components/input.md](components/input.md)** FIRST
+- Using InputAddon? → Read **[components/input-addon.md](components/input-addon.md)** FIRST
+- Using InputGroup? → Read **[components/input-group.md](components/input-group.md)** FIRST
+- Using Textarea? → Read **[components/textarea.md](components/textarea.md)** FIRST
+- Using Select? → Read **[components/select.md](components/select.md)** FIRST
+- Using Slider? → Read **[components/slider.md](components/slider.md)** FIRST
 
 **Layout & Container:**
 
-- Using Card? → Read `components/card.md` FIRST
-- Using Accordion? → Read `components/accordion.md` FIRST
-- Using Tabs? → Read `components/tabs.md` FIRST
-- Using Drawer? → Read `components/drawer.md` FIRST
+- Using Card? → Read **[components/card.md](components/card.md)** FIRST
+- Using Accordion? → Read **[components/accordion.md](components/accordion.md)** FIRST
+- Using Tabs? → Read **[components/tabs.md](components/tabs.md)** FIRST
+- Using Drawer? → Read **[components/drawer.md](components/drawer.md)** FIRST
 
 **Overlay Elements:**
 
-- Using Dialog? → Read `components/dialog.md` FIRST
-- Using Popover? → Read `components/popover.md` FIRST
-- Using Tooltip? → Read `components/tooltip.md` FIRST
+- Using Dialog? → Read **[components/dialog.md](components/dialog.md)** FIRST
+- Using Popover? → Read **[components/popover.md](components/popover.md)** FIRST
+- Using Tooltip? → Read **[components/tooltip.md](components/tooltip.md)** FIRST
 
 **Feedback & Status:**
 
-- Using Badge? → Read `components/badge.md` FIRST
-- Using Avatar? → Read `components/avatar.md` FIRST
-- Using Toast? → Read `components/toast.md` FIRST
-- Using Progress? → Read `components/progress.md` FIRST
-- Using Skeleton? → Read `components/skeleton.md` FIRST
+- Using Badge? → Read **[components/badge.md](components/badge.md)** FIRST
+- Using Avatar? → Read **[components/avatar.md](components/avatar.md)** FIRST
+- Using Toast? → Read **[components/toast.md](components/toast.md)** FIRST
+- Using Progress? → Read **[components/progress.md](components/progress.md)** FIRST
+- Using Skeleton? → Read **[components/skeleton.md](components/skeleton.md)** FIRST
+- Using Spinner? → Read **[components/spinner.md](components/spinner.md)** FIRST
 
 **Typography:**
 
-- Using Heading? → Read `components/heading.md` FIRST
+- Using Heading? → Read **[components/heading.md](components/heading.md)** FIRST
 
-DO NOT write code using a component until you have read its specific guidelines.
+**DO NOT write code using a component until you have read its specific guidelines.**
 
 ## Core Principles
 
@@ -77,101 +85,16 @@ DO NOT write code using a component until you have read its specific guidelines.
 - **Follow M3 patterns** for variants, sizing, and state layers
 - **Do not override styles** unless absolutely necessary
 - **Never use inline styles** with raw color values
+- **Read component guidelines** before using any component
+- **Follow common patterns** documented in overview-patterns.md
 
-## Package Installation
-
-```bash
-npm install @discourser/design-system react react-dom
-```
-
-## Package Imports
-
-```typescript
-// Simple Components (exported directly)
-import {
-  Button,
-  Card,
-  Input,
-  Textarea,
-  Heading,
-  Badge,
-  Toaster,
-  toaster,
-} from '@discourser/design-system';
-
-// Compound Components (exported as namespaces)
-import * as Checkbox from '@discourser/design-system';
-import * as RadioGroup from '@discourser/design-system';
-import * as Select from '@discourser/design-system';
-import * as Dialog from '@discourser/design-system';
-import * as Drawer from '@discourser/design-system';
-import * as Popover from '@discourser/design-system';
-import * as Tooltip from '@discourser/design-system';
-import * as Accordion from '@discourser/design-system';
-import * as Tabs from '@discourser/design-system';
-import * as Avatar from '@discourser/design-system';
-import * as Progress from '@discourser/design-system';
-import * as Skeleton from '@discourser/design-system';
-import * as IconButton from '@discourser/design-system';
-import * as Switch from '@discourser/design-system';
-
-// For advanced styling (use sparingly)
-import { css } from '@discourser/design-system/styled-system/css';
-import { button } from '@discourser/design-system/styled-system/recipes';
-```
-
-## Quick Reference
-
-**Interactive Elements:**
-
-| Component  | Key Variants                            | Guidelines                  |
-| ---------- | --------------------------------------- | --------------------------- |
-| Button     | filled, outlined, text, elevated, tonal | `components/button.md`      |
-| IconButton | standard, filled, tonal, outlined       | `components/icon-button.md` |
-| Switch     | -                                       | `components/switch.md`      |
-| Checkbox   | solid, outline, subtle                  | `components/checkbox.md`    |
-| RadioGroup | solid                                   | `components/radio-group.md` |
-
-**Form Elements:**
-
-| Component | Key Variants                      | Guidelines               |
-| --------- | --------------------------------- | ------------------------ |
-| Input     | surface, outline, subtle          | `components/input.md`    |
-| Textarea  | surface, outline, subtle, flushed | `components/textarea.md` |
-| Select    | outline, surface                  | `components/select.md`   |
-
-**Layout & Containers:**
+## Quick Start
 
-| Component | Key Variants                        | Guidelines                |
-| --------- | ----------------------------------- | ------------------------- |
-| Card      | elevated, filled, outlined          | `components/card.md`      |
-| Accordion | outline, plain                      | `components/accordion.md` |
-| Tabs      | line, subtle, enclosed              | `components/tabs.md`      |
-| Drawer    | Placements: start, end, top, bottom | `components/drawer.md`    |
-
-**Overlays:**
-
-| Component | Key Features                  | Guidelines              |
-| --------- | ----------------------------- | ----------------------- |
-| Dialog    | Sizes: sm, md, lg, fullscreen | `components/dialog.md`  |
-| Popover   | 12 positioning options        | `components/popover.md` |
-| Tooltip   | Lightweight contextual help   | `components/tooltip.md` |
-
-**Feedback & Status:**
-
-| Component | Key Variants                                     | Guidelines               |
-| --------- | ------------------------------------------------ | ------------------------ |
-| Badge     | subtle, solid, surface, outline                  | `components/badge.md`    |
-| Avatar    | Sizes: 2xs to 2xl, Shapes: full, rounded, square | `components/avatar.md`   |
-| Toast     | Types: success, error, warning, loading          | `components/toast.md`    |
-| Progress  | Shapes: linear, circular                         | `components/progress.md` |
-| Skeleton  | Animations: pulse, shine, none                   | `components/skeleton.md` |
-
-**Typography:**
-
-| Component | Key Features                      | Guidelines              |
-| --------- | --------------------------------- | ----------------------- |
-| Heading   | Sizes: xs to 7xl (M3 text styles) | `components/heading.md` |
+1. Install the package (see [overview-imports.md](overview-imports.md))
+2. Import components you need
+3. Use components with their documented variants and props
+4. Apply semantic tokens for custom styling
+5. Follow accessibility best practices from component guidelines
 
 ## Theme Support
 
@@ -187,9 +110,30 @@ The design system supports light and dark themes. The theme is controlled by the
 
 All semantic color tokens automatically adapt to the current theme.
 
+## Documentation Structure
+
+```
+guidelines/
+├── Guidelines.md (this file)         # Main navigation
+├── overview-components.md            # Component catalog
+├── overview-imports.md               # Installation & imports
+├── overview-patterns.md              # Common UI patterns
+├── design-tokens/
+│   ├── colors.md                     # Color system
+│   ├── typography.md                 # Type scale
+│   ├── spacing.md                    # Spacing system
+│   └── elevation.md                  # Elevation system
+└── components/
+    ├── button.md                     # Component guidelines
+    ├── input.md
+    └── ...                           # (25 total components)
+```
+
 ## Getting Help
 
 For questions or issues, visit:
 
-- GitHub: https://github.com/Tasty-Maker-Studio/Discourser-Design-System
-- Documentation: Read the overview and component-specific guidelines in this folder
+- **GitHub:** https://github.com/Tasty-Maker-Studio/Discourser-Design-System
+- **Documentation:** Read the overview and component-specific guidelines in this folder
+- **Component Reference:** See [overview-components.md](overview-components.md)
+- **Patterns:** See [overview-patterns.md](overview-patterns.md)

package/guidelines/components/accordion.md

@@ -2,6 +2,99 @@
 
 **Purpose:** Collapsible content panels for organizing and revealing information progressively, following Material Design 3 principles.
 
+## When to Use This Component
+
+Use Accordion when you need to **organize and progressively disclose related content in collapsible sections** to conserve space while keeping content accessible.
+
+### Decision Tree
+
+| Scenario                                            | Use Accordion? | Alternative               | Reasoning                                                       |
+| --------------------------------------------------- | -------------- | ------------------------- | --------------------------------------------------------------- |
+| Displaying FAQ with expandable answers              | ✅ Yes         | -                         | Perfect for progressively disclosing detailed information       |
+| Organizing settings into collapsible sections       | ✅ Yes         | -                         | Groups related settings while saving vertical space             |
+| User needs to view multiple sections simultaneously | ⚠️ Maybe       | Tabs or Separate sections | Accordion with `multiple={true}` works, but tabs may be clearer |
+| Navigation between different views                  | ❌ No          | Tabs                      | Tabs show one view at a time with clear navigation              |
+| Content where all sections should be visible        | ❌ No          | Regular sections          | Don't hide content that should always be visible                |
+| Quick comparison of all options                     | ❌ No          | Table or Grid             | Accordion requires clicking to see content                      |
+
+### Component Comparison
+
+```typescript
+// ✅ Accordion - FAQs with expandable answers
+<Accordion.Root defaultValue="faq-1">
+  <Accordion.Item value="faq-1">
+    <Accordion.ItemTrigger>
+      What is your return policy?
+      <Accordion.ItemIndicator />
+    </Accordion.ItemTrigger>
+    <Accordion.ItemContent>
+      <Accordion.ItemBody>
+        We accept returns within 30 days of purchase with original packaging.
+      </Accordion.ItemBody>
+    </Accordion.ItemContent>
+  </Accordion.Item>
+  <Accordion.Item value="faq-2">
+    <Accordion.ItemTrigger>
+      How long does shipping take?
+      <Accordion.ItemIndicator />
+    </Accordion.ItemTrigger>
+    <Accordion.ItemContent>
+      <Accordion.ItemBody>
+        Standard shipping takes 5-7 business days.
+      </Accordion.ItemBody>
+    </Accordion.ItemContent>
+  </Accordion.Item>
+</Accordion.Root>
+
+// ❌ Don't use Accordion for navigation - Use Tabs instead
+<Accordion.Root>
+  <Accordion.Item value="overview">
+    <Accordion.ItemTrigger>Overview</Accordion.ItemTrigger>
+    <Accordion.ItemContent>
+      <Dashboard />
+    </Accordion.ItemContent>
+  </Accordion.Item>
+  <Accordion.Item value="analytics">
+    <Accordion.ItemTrigger>Analytics</Accordion.ItemTrigger>
+    <Accordion.ItemContent>
+      <AnalyticsView />
+    </Accordion.ItemContent>
+  </Accordion.Item>
+</Accordion.Root>
+
+// ✅ Better: Use Tabs for view switching
+<Tabs.Root defaultValue="overview">
+  <Tabs.List>
+    <Tabs.Trigger value="overview">Overview</Tabs.Trigger>
+    <Tabs.Trigger value="analytics">Analytics</Tabs.Trigger>
+    <Tabs.Indicator />
+  </Tabs.List>
+  <Tabs.Content value="overview"><Dashboard /></Tabs.Content>
+  <Tabs.Content value="analytics"><AnalyticsView /></Tabs.Content>
+</Tabs.Root>
+
+// ❌ Don't use Accordion when all content should be visible
+<Accordion.Root multiple defaultValue={['step1', 'step2', 'step3']}>
+  <Accordion.Item value="step1">
+    <Accordion.ItemTrigger>Step 1</Accordion.ItemTrigger>
+    <Accordion.ItemContent>Instructions</Accordion.ItemContent>
+  </Accordion.Item>
+  {/* If all steps need to be visible, don't hide them */}
+</Accordion.Root>
+
+// ✅ Better: Use regular sections for always-visible content
+<Stack gap="4">
+  <Section>
+    <Heading>Step 1</Heading>
+    <Text>Instructions...</Text>
+  </Section>
+  <Section>
+    <Heading>Step 2</Heading>
+    <Text>Instructions...</Text>
+  </Section>
+</Stack>
+```
+
 ## Import
 
 ```typescript

package/guidelines/components/avatar.md

@@ -2,6 +2,76 @@
 
 **Purpose:** Visual representation of users or entities through images, initials, or icons, providing identity context throughout the application.
 
+## When to Use This Component
+
+Use Avatar when you need to **visually represent a user, person, or entity** with an image, initials, or icon to provide identity context.
+
+### Decision Tree
+
+| Scenario                  | Use Avatar? | Alternative                 | Reasoning                                        |
+| ------------------------- | ----------- | --------------------------- | ------------------------------------------------ |
+| User profile pictures     | ✅ Yes      | -                           | Avatar is designed for user representation       |
+| Comment author indicators | ✅ Yes      | -                           | Shows who created the content                    |
+| Team member lists         | ✅ Yes      | -                           | Visual identification of people                  |
+| Status labels or tags     | ❌ No       | Badge                       | Badge is for status, not identity                |
+| Decorative icons          | ❌ No       | Icon component              | Use semantic icons for UI elements               |
+| Company logos (non-user)  | ⚠️ Maybe    | Image with `shape="square"` | Avatar with square shape works for organizations |
+
+### Component Comparison
+
+```typescript
+// ✅ Avatar - User profile representation
+<Avatar.Root colorPalette="primary" size="md">
+  <Avatar.Fallback name="John Doe" />
+  <Avatar.Image src="/avatars/john.jpg" alt="John Doe" />
+</Avatar.Root>
+
+// ❌ Don't use Avatar for status indicators - Use Badge
+<Avatar.Root colorPalette="success" size="sm">
+  <Avatar.Fallback>✓</Avatar.Fallback>
+</Avatar.Root>
+
+// ✅ Better: Use Badge for status
+<Badge colorPalette="success">Active</Badge>
+
+// ❌ Don't use Avatar for UI icons - Use Icon
+<Avatar.Root size="sm">
+  <Avatar.Fallback>
+    <SettingsIcon />
+  </Avatar.Fallback>
+</Avatar.Root>
+
+// ✅ Better: Use IconButton for UI actions
+<IconButton aria-label="Settings">
+  <SettingsIcon />
+</IconButton>
+
+// ✅ Avatar - Comment author with status
+<HStack gap="3">
+  <Box position="relative">
+    <Avatar.Root colorPalette="primary" size="md">
+      <Avatar.Fallback name="Jane Smith" />
+      <Avatar.Image src="/avatars/jane.jpg" alt="Jane Smith" />
+    </Avatar.Root>
+    {/* Online status indicator */}
+    <Box
+      position="absolute"
+      bottom="0"
+      right="0"
+      width="3"
+      height="3"
+      borderRadius="full"
+      bg="success.solid"
+      border="2px solid white"
+    />
+  </Box>
+  <Stack gap="1">
+    <Text fontWeight="semibold">Jane Smith</Text>
+    <Text fontSize="sm" color="fg.muted">2 hours ago</Text>
+  </Stack>
+</HStack>
+```
+
 ## Import
 
 ```typescript

package/guidelines/components/badge.md

@@ -2,6 +2,67 @@
 
 **Purpose:** Compact visual indicator for displaying status, labels, counts, or categories following Material Design 3 patterns.
 
+## When to Use This Component
+
+Use Badge when you need to **display compact visual indicators for status, counts, labels, or categories** as non-interactive elements.
+
+### Decision Tree
+
+| Scenario                                         | Use Badge? | Alternative    | Reasoning                                      |
+| ------------------------------------------------ | ---------- | -------------- | ---------------------------------------------- |
+| Displaying status labels (Active, Pending, etc.) | ✅ Yes     | -              | Badge provides clear visual categorization     |
+| Notification counts on icons or buttons          | ✅ Yes     | -              | Perfect for unread messages, alerts            |
+| Category tags or labels                          | ✅ Yes     | -              | Compact visual grouping                        |
+| Clickable filters or selections                  | ❌ No      | Button or Chip | Badge is non-interactive                       |
+| Primary call-to-action                           | ❌ No      | Button         | Button is designed for actions                 |
+| User profile images                              | ❌ No      | Avatar         | Avatar is specifically for user representation |
+
+### Component Comparison
+
+```typescript
+// ✅ Badge - Status indicator
+<Stack gap="2" direction="row">
+  <Badge colorPalette="success">Active</Badge>
+  <Badge colorPalette="warning">Pending</Badge>
+  <Badge colorPalette="error">Expired</Badge>
+</Stack>
+
+// ❌ Don't use Badge for interactive elements - Use Button
+<Badge onClick={handleClick} colorPalette="primary">
+  Click me
+</Badge>
+
+// ✅ Better: Use Button for clickable actions
+<Button size="sm" variant="outlined">
+  Click me
+</Button>
+
+// ❌ Don't use Badge for user avatars - Use Avatar
+<Badge colorPalette="primary" size="2xl">
+  JD
+</Badge>
+
+// ✅ Better: Use Avatar for user representation
+<Avatar.Root colorPalette="primary" size="md">
+  <Avatar.Fallback name="John Doe" />
+  <Avatar.Image src="/avatar.jpg" alt="John Doe" />
+</Avatar.Root>
+
+// ✅ Badge - Notification count on icon
+<Box position="relative">
+  <IconButton><BellIcon /></IconButton>
+  <Badge
+    position="absolute"
+    top="-1"
+    right="-1"
+    colorPalette="error"
+    size="sm"
+  >
+    5
+  </Badge>
+</Box>
+```
+
 ## Import
 
 ```typescript

package/guidelines/components/button.md

@@ -2,6 +2,41 @@
 
 **Purpose:** Primary interactive element for user actions following Material Design 3 patterns.
 
+## When to Use This Component
+
+Use Button when you need a clickable element that **triggers an action** (submit, save, cancel, etc.).
+
+**Decision Tree:**
+
+| Scenario                                 | Use This                      | Why                                               |
+| ---------------------------------------- | ----------------------------- | ------------------------------------------------- |
+| Trigger an action (submit, save, delete) | Button ✅                     | Semantic action element                           |
+| Navigate to a different page/route       | `<a>` tag or Next.js `<Link>` | Navigation should use links for SEO/accessibility |
+| Icon-only action (close, menu, settings) | IconButton                    | Better for icon-only affordances                  |
+| Toggle state (on/off, enable/disable)    | Switch                        | Visual metaphor for state changes                 |
+| Select from options (exclusive choice)   | RadioGroup                    | For mutually exclusive selections                 |
+| Select multiple options                  | Checkbox                      | For multiple selections                           |
+
+**Component Comparison:**
+
+```typescript
+// ✅ Use Button for actions
+<Button onClick={handleSave}>Save</Button>
+<Button onClick={handleDelete}>Delete</Button>
+
+// ❌ Don't use Button for navigation - use Link
+<Button onClick={() => router.push('/page')}>Go to Page</Button>  // Wrong
+<Link href="/page">Go to Page</Link>  // Correct
+
+// ❌ Don't use Button for icon-only - use IconButton
+<Button><CloseIcon /></Button>  // Wrong
+<IconButton aria-label="Close"><CloseIcon /></IconButton>  // Correct
+
+// ❌ Don't use Button for toggles - use Switch
+<Button onClick={toggleDarkMode}>Dark Mode</Button>  // Wrong
+<Switch checked={isDarkMode} onCheckedChange={setDarkMode}>Dark Mode</Switch>  // Correct
+```
+
 ## Import
 
 ```typescript
@@ -12,13 +47,13 @@ import { Button } from '@discourser/design-system';
 
 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 |
+| 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
 
@@ -30,27 +65,27 @@ The Button component supports 5 Material Design 3 variants, each with specific u
 
 ## 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 |
+| 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 |
+| 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.
 
@@ -242,26 +277,26 @@ The Button component follows WCAG 2.1 Level AA standards:
 
 ## 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 |
+| 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 |
+| 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