@discourser/design-system 0.4.0 → 0.5.0

package/guidelines/components/input.md

@@ -2,6 +2,61 @@
 
 **Purpose:** Text input field with built-in label, validation, and helper text following Material Design 3 patterns.
 
+## When to Use This Component
+
+Use Input when you need **single-line text entry** from the user (names, emails, search terms, etc.).
+
+**Decision Tree:**
+
+| Scenario                                           | Use This                             | Why                                        |
+| -------------------------------------------------- | ------------------------------------ | ------------------------------------------ |
+| Single-line text (name, email, username, search)   | Input ✅                             | Optimized for single-line entry            |
+| Multi-line text (comments, descriptions, messages) | Textarea                             | Allows line breaks, expandable height      |
+| Select from predefined options (4+ choices)        | Select                               | More efficient than typing, prevents typos |
+| Select from 2-3 options                            | RadioGroup                           | Visual comparison of all options           |
+| Binary choice (yes/no, on/off)                     | Switch or Checkbox                   | Visual metaphor for state                  |
+| Date selection                                     | Input with type="date" or DatePicker | Structured date entry                      |
+| Number entry                                       | Input with type="number"             | Numeric keyboard on mobile                 |
+
+**Component Comparison:**
+
+```typescript
+// ✅ Use Input for single-line text
+<Input label="Email address" type="email" />
+<Input label="Username" />
+<Input label="Search products" type="search" />
+
+// ❌ Don't use Input for multi-line text - use Textarea
+<Input label="Comments" />  // Wrong - can't enter line breaks
+
+<Textarea label="Comments" />  // Correct
+
+// ❌ Don't use Input when Select would be clearer
+<Input label="Country" placeholder="Enter country name" />  // Wrong - prone to typos
+
+<Select.Root collection={countries}>
+  <Select.Label>Country</Select.Label>
+  <Select.Control>
+    <Select.Trigger>
+      <Select.ValueText placeholder="Select country" />
+    </Select.Trigger>
+  </Select.Control>
+  <Select.Content>
+    {/* country options */}
+  </Select.Content>
+</Select.Root>  // Correct
+
+// ❌ Don't use Input for binary choices - use Switch
+<Input label="Enable notifications" type="checkbox" />  // Wrong - not an Input use case
+
+<Switch.Root>
+  <Switch.Label>Enable notifications</Switch.Label>
+  <Switch.Control>
+    <Switch.Thumb />
+  </Switch.Control>
+</Switch.Root>  // Correct
+```
+
 ## Import
 
 ```typescript
@@ -12,10 +67,10 @@ import { Input } from '@discourser/design-system';
 
 The Input component supports 2 Material Design 3 variants:
 
-| Variant | Visual Style | Usage | When to Use |
-|---------|-------------|-------|-------------|
-| `outlined` | Outlined border around input | Default text inputs | Most common, clear boundaries |
-| `filled` | Filled background with bottom border | Alternative style | When you want less visual weight |
+| Variant    | Visual Style                         | Usage               | When to Use                      |
+| ---------- | ------------------------------------ | ------------------- | -------------------------------- |
+| `outlined` | Outlined border around input         | Default text inputs | Most common, clear boundaries    |
+| `filled`   | Filled background with bottom border | Alternative style   | When you want less visual weight |
 
 ### Visual Characteristics
 
@@ -24,28 +79,28 @@ The Input component supports 2 Material Design 3 variants:
 
 ## Sizes
 
-| Size | Height | Font Size | Usage |
-|------|--------|-----------|-------|
-| `sm` | 40px | bodySmall | Compact forms, dense layouts |
-| `md` | 56px | bodyLarge | Default, most use cases |
+| Size | Height | Font Size | Usage                        |
+| ---- | ------ | --------- | ---------------------------- |
+| `sm` | 40px   | bodySmall | Compact forms, dense layouts |
+| `md` | 56px   | bodyLarge | Default, most use cases      |
 
 ## Props
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `label` | `string` | - | Label text (highly recommended for accessibility) |
-| `helperText` | `string` | - | Helper text displayed below input |
-| `errorText` | `string` | - | Error message (also sets error state) |
-| `variant` | `'outlined' \| 'filled'` | `'outlined'` | Visual style variant |
-| `size` | `'sm' \| 'md'` | `'md'` | Input size |
-| `state` | `'error'` | - | Visual state (auto-set if errorText provided) |
-| `disabled` | `boolean` | `false` | Disable input |
-| `value` | `string` | - | Controlled value |
-| `defaultValue` | `string` | - | Uncontrolled default value |
-| `onChange` | `(event: ChangeEvent) => void` | - | Change handler |
-| `placeholder` | `string` | - | Placeholder text |
-| `type` | `string` | `'text'` | HTML input type (text, email, password, etc.) |
-| `required` | `boolean` | `false` | Mark as required field |
+| Prop           | Type                           | Default      | Description                                       |
+| -------------- | ------------------------------ | ------------ | ------------------------------------------------- |
+| `label`        | `string`                       | -            | Label text (highly recommended for accessibility) |
+| `helperText`   | `string`                       | -            | Helper text displayed below input                 |
+| `errorText`    | `string`                       | -            | Error message (also sets error state)             |
+| `variant`      | `'outlined' \| 'filled'`       | `'outlined'` | Visual style variant                              |
+| `size`         | `'sm' \| 'md'`                 | `'md'`       | Input size                                        |
+| `state`        | `'error'`                      | -            | Visual state (auto-set if errorText provided)     |
+| `disabled`     | `boolean`                      | `false`      | Disable input                                     |
+| `value`        | `string`                       | -            | Controlled value                                  |
+| `defaultValue` | `string`                       | -            | Uncontrolled default value                        |
+| `onChange`     | `(event: ChangeEvent) => void` | -            | Change handler                                    |
+| `placeholder`  | `string`                       | -            | Placeholder text                                  |
+| `type`         | `string`                       | `'text'`     | HTML input type (text, email, password, etc.)     |
+| `required`     | `boolean`                      | `false`      | Mark as required field                            |
 
 **Note:** Input extends `InputHTMLAttributes<HTMLInputElement>` (excluding 'size'), so all standard HTML input attributes are supported.
 
@@ -414,23 +469,23 @@ const formik = useFormik({
 
 ## Variant Selection Guide
 
-| Scenario | Recommended Variant | Reasoning |
-|----------|-------------------|-----------|
-| Standard forms | `outlined` | Clear boundaries, default choice |
-| Dense forms | `outlined` + `size="sm"` | Compact while maintaining clarity |
-| Minimal UI | `filled` | Lighter visual weight |
-| Search bars | `outlined` or `filled` | Either works, depends on design |
-| Settings forms | `outlined` | Clear separation of fields |
+| Scenario       | Recommended Variant      | Reasoning                         |
+| -------------- | ------------------------ | --------------------------------- |
+| Standard forms | `outlined`               | Clear boundaries, default choice  |
+| Dense forms    | `outlined` + `size="sm"` | Compact while maintaining clarity |
+| Minimal UI     | `filled`                 | Lighter visual weight             |
+| Search bars    | `outlined` or `filled`   | Either works, depends on design   |
+| Settings forms | `outlined`               | Clear separation of fields        |
 
 ## State Behaviors
 
-| State | Visual Change | Behavior |
-|-------|---------------|----------|
-| **Default** | Normal border/background | Ready for input |
-| **Hover** | Border darkens or background changes | Visual feedback |
-| **Focus** | 2px border, primary color | Active input state |
-| **Error** | Error color border, error message shown | Validation failed |
-| **Disabled** | 38% opacity, no interaction | Cannot be edited |
+| State        | Visual Change                           | Behavior           |
+| ------------ | --------------------------------------- | ------------------ |
+| **Default**  | Normal border/background                | Ready for input    |
+| **Hover**    | Border darkens or background changes    | Visual feedback    |
+| **Focus**    | 2px border, primary color               | Active input state |
+| **Error**    | Error color border, error message shown | Validation failed  |
+| **Disabled** | 38% opacity, no interaction             | Cannot be edited   |
 
 ## Responsive Considerations
 

package/guidelines/components/popover.md

@@ -2,6 +2,77 @@
 
 **Purpose:** A floating panel that appears near a trigger element to display contextual content, menus, forms, or additional information. Built on Ark UI's Popover primitive with intelligent positioning and smooth animations.
 
+## When to Use This Component
+
+Use Popover when you need to **display rich contextual content or interactive elements near a trigger** without navigating away from the current page.
+
+### Decision Tree
+
+| Scenario                                   | Use Popover? | Alternative | Reasoning                                          |
+| ------------------------------------------ | ------------ | ----------- | -------------------------------------------------- |
+| Contextual menus with actions              | ✅ Yes       | -           | Popover shows rich content near the trigger        |
+| Forms or color pickers attached to element | ✅ Yes       | -           | Perfect for inline editing without page navigation |
+| User profile preview on hover/click        | ✅ Yes       | -           | Shows detailed info without full page load         |
+| Simple text hints or labels                | ❌ No        | Tooltip     | Tooltip is lighter and better for brief help text  |
+| Critical actions requiring focus           | ❌ No        | Dialog      | Dialog centers attention and is modal              |
+| Navigation menus (mobile)                  | ❌ No        | Drawer      | Drawer slides from edge, better for mobile menus   |
+
+### Component Comparison
+
+```typescript
+// ✅ Popover - Rich contextual menu with form
+<Popover.Root>
+  <Popover.Trigger asChild>
+    <Button>Add Comment</Button>
+  </Popover.Trigger>
+  <Popover.Positioner>
+    <Popover.Content>
+      <Popover.Title>New Comment</Popover.Title>
+      <Popover.Description>Add your thoughts below</Popover.Description>
+      <Textarea placeholder="Type your comment..." />
+      <Button>Submit</Button>
+    </Popover.Content>
+  </Popover.Positioner>
+</Popover.Root>
+
+// ❌ Don't use Popover for simple hints - Use Tooltip
+<Popover.Root>
+  <Popover.Trigger asChild>
+    <IconButton><InfoIcon /></IconButton>
+  </Popover.Trigger>
+  <Popover.Positioner>
+    <Popover.Content>
+      This is a simple hint
+    </Popover.Content>
+  </Popover.Positioner>
+</Popover.Root>
+
+// ✅ Better: Use Tooltip for brief hints
+<Tooltip content="This is a simple hint">
+  <IconButton><InfoIcon /></IconButton>
+</Tooltip>
+
+// ❌ Don't use Popover for critical modals - Use Dialog
+<Popover.Root>
+  <Popover.Content>
+    <Popover.Title>Delete Account?</Popover.Title>
+    <Button>Confirm Delete</Button>
+  </Popover.Content>
+</Popover.Root>
+
+// ✅ Better: Use Dialog for important confirmations
+<Dialog.Root>
+  <Dialog.Content>
+    <Dialog.Title>Delete Account?</Dialog.Title>
+    <Dialog.Description>This cannot be undone.</Dialog.Description>
+    <Dialog.Footer>
+      <Button variant="outlined">Cancel</Button>
+      <Button colorPalette="error">Delete</Button>
+    </Dialog.Footer>
+  </Dialog.Content>
+</Dialog.Root>
+```
+
 ## Import
 
 ```typescript

package/guidelines/components/progress.md

@@ -2,6 +2,69 @@
 
 **Purpose:** Visual indicator that displays the completion status of a task or operation, providing feedback to users about ongoing processes following Material Design 3 patterns.
 
+## When to Use This Component
+
+Use Progress when you need to **visually indicate the completion percentage of a determinate process** where progress can be measured.
+
+### Decision Tree
+
+| Scenario                          | Use Progress? | Alternative         | Reasoning                                 |
+| --------------------------------- | ------------- | ------------------- | ----------------------------------------- |
+| File upload with known progress   | ✅ Yes        | -                   | Progress bar shows percentage complete    |
+| Multi-step form progress          | ✅ Yes        | -                   | Visual indicator of completion            |
+| Task completion tracking          | ✅ Yes        | -                   | Shows how much work remains               |
+| Unknown duration loading          | ❌ No         | Spinner or Skeleton | Progress needs measurable completion      |
+| Page content loading              | ❌ No         | Skeleton            | Skeleton preserves layout during load     |
+| Quick operations (under 1 second) | ❌ No         | Nothing or Spinner  | Progress is too heavy for instant actions |
+
+### Component Comparison
+
+```typescript
+// ✅ Progress - File upload with percentage
+const [progress, setProgress] = useState(0);
+
+<Progress.Root value={progress} striped animated>
+  <Progress.Label>Uploading {fileName}</Progress.Label>
+  <Progress.Track>
+    <Progress.Range />
+  </Progress.Track>
+  <Progress.ValueText />
+</Progress.Root>
+
+// ❌ Don't use Progress for unknown duration - Use Spinner
+<Progress.Root value={null}>
+  <Progress.Track>
+    <Progress.Range />
+  </Progress.Track>
+</Progress.Root>
+
+// ✅ Better: Use Spinner for indeterminate loading
+<Spinner size="lg" />
+
+// ❌ Don't use Progress for content loading - Use Skeleton
+<Progress.Root value={null} size="sm">
+  <Progress.Track>
+    <Progress.Range />
+  </Progress.Track>
+</Progress.Root>
+{/* Then content loads */}
+
+// ✅ Better: Use Skeleton for content placeholders
+<SkeletonText noOfLines={3} />
+
+// ✅ Progress - Multi-step form
+const currentStep = 2;
+const totalSteps = 4;
+const progress = (currentStep / totalSteps) * 100;
+
+<Progress.Root value={progress}>
+  <Progress.Label>Step {currentStep} of {totalSteps}</Progress.Label>
+  <Progress.Track>
+    <Progress.Range />
+  </Progress.Track>
+</Progress.Root>
+```
+
 ## Import
 
 ```typescript

package/guidelines/components/radio-group.md

@@ -2,6 +2,101 @@
 
 **Purpose:** Provides mutually exclusive selection between multiple options, allowing users to choose exactly one item from a set of choices.
 
+## When to Use This Component
+
+Use RadioGroup when the user must **select exactly one option from a visible set of mutually exclusive choices** (typically 2-7 options).
+
+### Decision Tree
+
+| Scenario                                                   | Use RadioGroup? | Alternative              | Reasoning                                                |
+| ---------------------------------------------------------- | --------------- | ------------------------ | -------------------------------------------------------- |
+| User must pick exactly one option from 2-7 visible choices | ✅ Yes          | -                        | RadioGroup shows all options at once for easy comparison |
+| Single selection from many options (8+)                    | ❌ No           | Select                   | Dropdown saves vertical space for long lists             |
+| User can select multiple items                             | ❌ No           | Checkbox                 | Checkboxes allow multiple selections                     |
+| Single choice with on/off state only                       | ❌ No           | Switch                   | Switch is clearer for binary toggles                     |
+| Optional single selection (can select none)                | ⚠️ Maybe        | Select with empty option | RadioGroup typically requires a selection                |
+| Navigation between views                                   | ❌ No           | Tabs                     | Tabs are designed for view switching                     |
+
+### Component Comparison
+
+```typescript
+// ✅ RadioGroup - Single choice from visible options
+<RadioGroup.Root defaultValue="email">
+  <RadioGroup.Label>Notification Method</RadioGroup.Label>
+  <RadioGroup.Item value="email">
+    <RadioGroup.ItemControl>
+      <RadioGroup.Indicator />
+    </RadioGroup.ItemControl>
+    <RadioGroup.ItemText>Email notifications</RadioGroup.ItemText>
+    <RadioGroup.ItemHiddenInput />
+  </RadioGroup.Item>
+  <RadioGroup.Item value="sms">
+    <RadioGroup.ItemControl>
+      <RadioGroup.Indicator />
+    </RadioGroup.ItemControl>
+    <RadioGroup.ItemText>SMS notifications</RadioGroup.ItemText>
+    <RadioGroup.ItemHiddenInput />
+  </RadioGroup.Item>
+  <RadioGroup.Item value="none">
+    <RadioGroup.ItemControl>
+      <RadioGroup.Indicator />
+    </RadioGroup.ItemControl>
+    <RadioGroup.ItemText>No notifications</RadioGroup.ItemText>
+    <RadioGroup.ItemHiddenInput />
+  </RadioGroup.Item>
+</RadioGroup.Root>
+
+// ❌ Don't use RadioGroup for many options - Use Select instead
+<RadioGroup.Root defaultValue="country">
+  <RadioGroup.Item value="us">United States</RadioGroup.Item>
+  <RadioGroup.Item value="uk">United Kingdom</RadioGroup.Item>
+  {/* ...50 more countries - too many for radio buttons */}
+</RadioGroup.Root>
+
+// ✅ Better: Use Select for long lists
+<Select.Root>
+  <Select.Trigger>
+    <Select.ValueText placeholder="Select country" />
+  </Select.Trigger>
+  <Select.Content>
+    {countries.map((country) => (
+      <Select.Item key={country.value} item={country.value}>
+        <Select.ItemText>{country.label}</Select.ItemText>
+      </Select.Item>
+    ))}
+  </Select.Content>
+</Select.Root>
+
+// ❌ Don't use RadioGroup for multiple selections - Use Checkbox instead
+<RadioGroup.Root>
+  <RadioGroup.Label>Select features (can't pick multiple)</RadioGroup.Label>
+  <RadioGroup.Item value="feature1">Feature 1</RadioGroup.Item>
+  <RadioGroup.Item value="feature2">Feature 2</RadioGroup.Item>
+</RadioGroup.Root>
+
+// ✅ Better: Use Checkbox for multiple selections
+<Stack gap="2">
+  <Checkbox value="feature1">Feature 1</Checkbox>
+  <Checkbox value="feature2">Feature 2</Checkbox>
+  <Checkbox value="feature3">Feature 3</Checkbox>
+</Stack>
+
+// ❌ Don't use RadioGroup for binary on/off - Use Switch instead
+<RadioGroup.Root defaultValue="off">
+  <RadioGroup.Label>Notifications</RadioGroup.Label>
+  <RadioGroup.Item value="on">Enable notifications</RadioGroup.Item>
+  <RadioGroup.Item value="off">Disable notifications</RadioGroup.Item>
+</RadioGroup.Root>
+
+// ✅ Better: Use Switch for binary toggle
+<Switch.Root>
+  <Switch.Label>Enable notifications</Switch.Label>
+  <Switch.Control>
+    <Switch.Thumb />
+  </Switch.Control>
+</Switch.Root>
+```
+
 ## Import
 
 ```typescript