doom-design-system 0.4.15 → 0.4.17

package/.agent/skills/doom/components/accordion.md

@@ -0,0 +1,44 @@
+# Accordion Component
+
+## Import
+
+```tsx
+import { Accordion, AccordionItem } from "doom-design-system";
+```
+
+## Props
+
+### Accordion
+
+| Prop            | Type                     | Default    | Description                |
+| --------------- | ------------------------ | ---------- | -------------------------- |
+| `type`          | `"single" \| "multiple"` | `"single"` | Allow one or multiple open |
+| `defaultValue`  | `string \| string[]`     | —          | Initial open item(s)       |
+| `value`         | `string \| string[]`     | —          | Controlled value           |
+| `onValueChange` | `(value) => void`        | —          | Change callback            |
+
+### AccordionItem
+
+| Prop       | Type        | Description       |
+| ---------- | ----------- | ----------------- |
+| `value`    | `string`    | Unique identifier |
+| `trigger`  | `string`    | Header text       |
+| `children` | `ReactNode` | Panel content     |
+
+## Usage
+
+```tsx
+<Accordion type="single" defaultValue="item-1">
+  <AccordionItem value="item-1" trigger="Section 1">
+    Content for section 1
+  </AccordionItem>
+  <AccordionItem value="item-2" trigger="Section 2">
+    Content for section 2
+  </AccordionItem>
+</Accordion>
+```
+
+## Guidelines
+
+- Use `type="multiple"` for FAQ sections where users may want multiple open.
+- Use `type="single"` (default) for navigation or settings panels.

package/.agent/skills/doom/components/actionrow.md

@@ -0,0 +1,33 @@
+# ActionRow Component
+
+## Import
+
+```tsx
+import { ActionRow } from "doom-design-system";
+```
+
+## Props
+
+| Prop          | Type         | Description             |
+| ------------- | ------------ | ----------------------- |
+| `icon`        | `ReactNode`  | Icon on the left        |
+| `title`       | `string`     | Main label              |
+| `description` | `string`     | Optional secondary text |
+| `onClick`     | `() => void` | Click handler           |
+
+## Usage
+
+```tsx
+<ActionRow
+  icon={<Settings size={20} />}
+  title="Account Settings"
+  description="Manage your profile and preferences"
+  onClick={() => navigate("/settings")}
+/>
+```
+
+## Guidelines
+
+- Use for settings menus, navigation lists, or action items.
+- Always provide an icon for visual consistency.
+- Renders with a chevron indicator on the right.

package/.agent/skills/doom/components/alert.md

@@ -0,0 +1,35 @@
+# Alert Component
+
+## Import
+
+```tsx
+import { Alert } from "doom-design-system";
+```
+
+## Props
+
+| Prop          | Type                                          | Default  | Description                       |
+| ------------- | --------------------------------------------- | -------- | --------------------------------- |
+| `variant`     | `"info" \| "success" \| "warning" \| "error"` | `"info"` | Visual style                      |
+| `title`       | `string`                                      | required | Alert heading                     |
+| `description` | `ReactNode`                                   | —        | Additional content                |
+| `icon`        | `ReactNode`                                   | —        | Custom icon (defaults by variant) |
+
+## Usage
+
+```tsx
+<Alert
+  variant="error"
+  title="Invalid credentials"
+  description="Please check your email and password."
+/>
+
+<Alert variant="success" title="Changes saved!" />
+```
+
+## Guidelines
+
+- Use `error` for form validation, API errors.
+- Use `success` for confirmations.
+- Use `warning` for cautions/deprecations.
+- Use `info` for general notices.

package/.agent/skills/doom/components/avatar.md

@@ -0,0 +1,36 @@
+# Avatar Component
+
+## Import
+
+```tsx
+import { Avatar } from "doom-design-system";
+```
+
+## Props
+
+| Prop       | Type                           | Default    | Description                 |
+| ---------- | ------------------------------ | ---------- | --------------------------- |
+| `src`      | `string`                       | —          | Image URL                   |
+| `alt`      | `string`                       | `"Avatar"` | Alt text                    |
+| `fallback` | `ReactNode`                    | required   | Fallback (initials or icon) |
+| `size`     | `"sm" \| "md" \| "lg" \| "xl"` | `"md"`     | Avatar size                 |
+| `shape`    | `"circle" \| "square"`         | `"square"` | Shape                       |
+
+## Usage
+
+```tsx
+<Avatar
+  src="/avatars/user.jpg"
+  fallback="JD"
+  size="lg"
+  shape="circle"
+/>
+
+<Avatar fallback={<User size={20} />} />
+```
+
+## Guidelines
+
+- Always provide a `fallback` for when image fails to load.
+- String fallbacks are auto-truncated to 2 characters.
+- Use `shape="circle"` for user profiles.

package/.agent/skills/doom/components/badge.md

@@ -0,0 +1,29 @@
+# Badge Component
+
+## Import
+
+```tsx
+import { Badge } from "doom-design-system";
+```
+
+## Props
+
+| Prop       | Type                                                                         | Default     | Description   |
+| ---------- | ---------------------------------------------------------------------------- | ----------- | ------------- |
+| `variant`  | `"primary" \| "success" \| "warning" \| "error" \| "secondary" \| "outline"` | `"primary"` | Visual style  |
+| `size`     | `"sm" \| "md" \| "lg"`                                                       | `"md"`      | Badge size    |
+| `children` | `ReactNode`                                                                  | required    | Badge content |
+
+## Usage
+
+```tsx
+<Badge variant="success">Active</Badge>
+<Badge variant="error" size="sm">Overdue</Badge>
+<Badge variant="outline">Draft</Badge>
+```
+
+## Guidelines
+
+- Use for status indicators, counts, or labels.
+- Keep content short (1-2 words max).
+- Use semantic colors: `success` for positive, `error` for negative, etc.

package/.agent/skills/doom/components/breadcrumbs.md

@@ -0,0 +1,33 @@
+# Breadcrumbs Component
+
+## Import
+
+```tsx
+import { Breadcrumbs, BreadcrumbItem } from "doom-design-system";
+```
+
+## Props
+
+### BreadcrumbItem
+
+| Prop        | Type        | Description          |
+| ----------- | ----------- | -------------------- |
+| `href`      | `string`    | Link destination     |
+| `isCurrent` | `boolean`   | Mark as current page |
+| `children`  | `ReactNode` | Link text            |
+
+## Usage
+
+```tsx
+<Breadcrumbs>
+  <BreadcrumbItem href="/">Home</BreadcrumbItem>
+  <BreadcrumbItem href="/products">Products</BreadcrumbItem>
+  <BreadcrumbItem isCurrent>Widget Pro</BreadcrumbItem>
+</Breadcrumbs>
+```
+
+## Guidelines
+
+- Last item should have `isCurrent` (no link, shows as text).
+- Separators are automatically rendered between items.
+- Use for navigation hierarchy in multi-level pages.

package/.agent/skills/doom/components/button.md

@@ -0,0 +1,43 @@
+# Button Component
+
+## Import
+
+```tsx
+import { Button } from "doom-design-system";
+```
+
+## Props
+
+| Prop       | Type                                                                        | Default     | Description                           |
+| ---------- | --------------------------------------------------------------------------- | ----------- | ------------------------------------- |
+| `variant`  | `"primary" \| "secondary" \| "ghost" \| "outline" \| "success" \| "danger"` | `"primary"` | Visual style                          |
+| `size`     | `"sm" \| "md" \| "lg"`                                                      | `"md"`      | Button size                           |
+| `loading`  | `boolean`                                                                   | `false`     | Show loading spinner, disables button |
+| `disabled` | `boolean`                                                                   | `false`     | Disable the button                    |
+
+Plus all standard `<button>` HTML attributes.
+
+## Usage
+
+```tsx
+<Button variant="primary" onClick={handleClick}>
+  Submit
+</Button>
+
+<Button loading variant="danger">
+  Deleting...
+</Button>
+
+<Button variant="ghost" size="sm">
+  Cancel
+</Button>
+```
+
+## Guidelines
+
+- Use `primary` for main actions (submit, save, confirm).
+- Use `secondary` for less prominent actions.
+- Use `ghost` for tertiary/cancel actions.
+- Use `danger` for destructive actions (delete, remove).
+- Use `success` sparingly for positive confirmations.
+- Always use `loading` prop instead of manually disabling + adding spinner.

package/.agent/skills/doom/components/card.md

@@ -0,0 +1,41 @@
+# Card Component
+
+## Import
+
+```tsx
+import { Card } from "doom-design-system";
+```
+
+## Props
+
+| Prop        | Type          | Default  | Description            |
+| ----------- | ------------- | -------- | ---------------------- |
+| `as`        | `ElementType` | `"div"`  | HTML element to render |
+| `children`  | `ReactNode`   | required | Card content           |
+| `className` | `string`      | —        | Additional classes     |
+
+Plus all standard HTML attributes for the rendered element.
+
+## Usage
+
+```tsx
+<Card>
+  <Text variant="h4">Card Title</Text>
+  <Text>Card content goes here.</Text>
+</Card>
+```
+
+## Styling
+
+Card provides:
+
+- Background: `var(--card-bg)`
+- Border: `var(--border-width) solid var(--card-border)`
+- Shadow: `var(--shadow-hard)`
+- Padding: Inherited from component (add your own)
+
+## Guidelines
+
+- Card is a generic container—use it to group related content.
+- Cards do not have built-in padding; add your own with Layout components or SCSS.
+- Use `as="article"` or `as="section"` for semantic HTML when appropriate.

package/.agent/skills/doom/components/chart.md

@@ -0,0 +1,71 @@
+# Chart Component
+
+## Import
+
+```tsx
+import { Chart } from "doom-design-system";
+```
+
+## Props
+
+| Prop            | Type                        | Default  | Description                |
+| --------------- | --------------------------- | -------- | -------------------------- |
+| `data`          | `T[]`                       | required | Data array                 |
+| `config`        | `ChartConfig`               | required | Series configuration       |
+| `type`          | `"line" \| "area" \| "bar"` | —        | Chart type (shorthand API) |
+| `xKey`          | `string`                    | required | X-axis data key            |
+| `height`        | `number`                    | `300`    | Chart height               |
+| `title`         | `string`                    | —        | Chart title                |
+| `subtitle`      | `string`                    | —        | Chart subtitle             |
+| `withLegend`    | `boolean`                   | —        | Show legend                |
+| `render`        | `(ctx) => ReactNode`        | —        | Custom render function     |
+| `renderTooltip` | `(ctx) => ReactNode`        | —        | Custom tooltip             |
+
+## Config
+
+```tsx
+const config = {
+  revenue: {
+    label: "Revenue",
+    color: "var(--primary)",
+  },
+  profit: {
+    label: "Profit",
+    color: "var(--success)",
+  },
+};
+```
+
+## Usage
+
+### Shorthand API
+
+```tsx
+<Chart
+  type="line"
+  data={data}
+  config={config}
+  xKey="month"
+  title="Monthly Revenue"
+  withLegend
+/>
+```
+
+### Composition API
+
+```tsx
+<Chart.Root data={data} config={config} xKey="month">
+  <Chart.Header title="Sales" subtitle="Last 12 months">
+    <Chart.Legend />
+  </Chart.Header>
+  <Chart.Plot type="area" />
+  <Chart.Footer>Custom footer</Chart.Footer>
+</Chart.Root>
+```
+
+## Guidelines
+
+- Use shorthand API for simple charts.
+- Use composition API for custom layouts.
+- Built on D3.js; supports line, area, and bar charts.
+- Supports gradients with `withGradient` prop on Plot.

package/.agent/skills/doom/components/checkbox.md

@@ -0,0 +1,38 @@
+# Checkbox Component
+
+## Import
+
+```tsx
+import { Checkbox } from "doom-design-system";
+```
+
+## Props
+
+| Prop             | Type          | Default | Description                |
+| ---------------- | ------------- | ------- | -------------------------- |
+| `label`          | `string`      | —       | Label text                 |
+| `error`          | `boolean`     | —       | Error state                |
+| `checked`        | `boolean`     | —       | Controlled checked state   |
+| `defaultChecked` | `boolean`     | —       | Uncontrolled initial state |
+| `disabled`       | `boolean`     | —       | Disabled state             |
+| `onChange`       | `(e) => void` | —       | Change handler             |
+
+Plus all standard `<input type="checkbox">` attributes.
+
+## Usage
+
+```tsx
+<Checkbox label="I agree to the terms" />
+
+<Checkbox
+  label="Subscribe to newsletter"
+  checked={subscribed}
+  onChange={(e) => setSubscribed(e.target.checked)}
+/>
+```
+
+## Guidelines
+
+- Use `label` prop for accessibility (auto-binds label to input).
+- Use for binary choices or multi-select lists.
+- Use `RadioGroup` for single-select from multiple options.

package/.agent/skills/doom/components/chip.md

@@ -0,0 +1,35 @@
+# Chip Component
+
+## Import
+
+```tsx
+import { Chip } from "doom-design-system";
+```
+
+## Props
+
+| Prop        | Type                                                          | Default     | Description                       |
+| ----------- | ------------------------------------------------------------- | ----------- | --------------------------------- |
+| `variant`   | `"default" \| "primary" \| "success" \| "warning" \| "error"` | `"default"` | Visual style                      |
+| `size`      | `"xs" \| "sm" \| "md" \| "lg" \| "xl"`                        | `"md"`      | Chip size                         |
+| `onDismiss` | `() => void`                                                  | —           | Shows X button, called on dismiss |
+| `onClick`   | `() => void`                                                  | —           | Makes chip clickable              |
+| `disabled`  | `boolean`                                                     | `false`     | Disabled state                    |
+
+## Usage
+
+```tsx
+<Chip>Default</Chip>
+
+<Chip variant="primary" onDismiss={() => removeFilter()}>
+  Filter: Active
+</Chip>
+
+<Chip onClick={() => toggleTag()}>Clickable Tag</Chip>
+```
+
+## Guidelines
+
+- Use for tags, filters, or selectable items.
+- `onDismiss` adds a dismiss button (X) on the right.
+- `onClick` makes the entire chip interactive.

package/.agent/skills/doom/components/combobox.md

@@ -0,0 +1,50 @@
+# Combobox Component
+
+## Import
+
+```tsx
+import { Combobox } from "doom-design-system";
+```
+
+## Props
+
+| Prop          | Type                                 | Default       | Description                       |
+| ------------- | ------------------------------------ | ------------- | --------------------------------- |
+| `options`     | `{ value: string, label: string }[]` | required      | Available options                 |
+| `value`       | `string \| string[]`                 | —             | Selected value(s)                 |
+| `onChange`    | `(value) => void`                    | required      | Change handler                    |
+| `placeholder` | `string`                             | `"Select..."` | Placeholder text                  |
+| `multiple`    | `boolean`                            | `false`       | Allow multiple selection          |
+| `searchable`  | `boolean`                            | `true`        | Enable search/filter              |
+| `size`        | `"sm" \| "md"`                       | `"md"`        | Trigger size                      |
+| `disabled`    | `boolean`                            | `false`       | Disabled state                    |
+| `inline`      | `boolean`                            | `false`       | Render dropdown only (no trigger) |
+
+## Usage
+
+```tsx
+<Combobox
+  options={[
+    { value: "red", label: "Red" },
+    { value: "blue", label: "Blue" },
+  ]}
+  value={color}
+  onChange={setColor}
+  placeholder="Select color"
+/>
+
+// Multi-select
+<Combobox
+  multiple
+  options={tags}
+  value={selectedTags}
+  onChange={setSelectedTags}
+/>
+```
+
+## Guidelines
+
+- Use for large option lists (virtualized for performance).
+- Use `multiple` for tag/filter selection.
+- Press Enter in search to select all filtered results (multi-select).
+- "All" option automatically manages select/deselect all.

package/.agent/skills/doom/components/drawer.md

@@ -0,0 +1,69 @@
+# Drawer Component
+
+## Import
+
+```tsx
+import { Drawer } from "doom-design-system";
+```
+
+## Props
+
+| Prop       | Type                   | Default     | Description         |
+| ---------- | ---------------------- | ----------- | ------------------- |
+| `isOpen`   | `boolean`              | required    | Controls visibility |
+| `onClose`  | `() => void`           | required    | Close callback      |
+| `title`    | `ReactNode`            | —           | Header title        |
+| `side`     | `"left" \| "right"`    | `"right"`   | Slide direction     |
+| `children` | `ReactNode`            | required    | Drawer content      |
+| `footer`   | `ReactNode`            | —           | Footer content      |
+| `variant`  | `"default" \| "solid"` | `"default"` | Visual style        |
+
+## Usage Patterns
+
+### Shorthand API (simple drawers)
+
+```tsx
+<Drawer
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  title="Settings"
+  footer={<Button onClick={save}>Save</Button>}
+>
+  <Stack gap={4}>{/* Settings form */}</Stack>
+</Drawer>
+```
+
+### Composition API (custom layouts)
+
+```tsx
+<Drawer isOpen={isOpen} onClose={onClose} side="right">
+  <Drawer.Header>
+    <Text variant="h3">Custom Title</Text>
+  </Drawer.Header>
+  <Drawer.Body>
+    <Stack gap={4}>{/* Custom content */}</Stack>
+  </Drawer.Body>
+  <Drawer.Footer>
+    <Button variant="ghost" onClick={onClose}>
+      Cancel
+    </Button>
+    <Button onClick={handleSave}>Save</Button>
+  </Drawer.Footer>
+</Drawer>
+```
+
+## Sub-components
+
+| Component       | Description              |
+| --------------- | ------------------------ |
+| `Drawer.Header` | Header with close button |
+| `Drawer.Body`   | Scrollable content area  |
+| `Drawer.Footer` | Action buttons area      |
+
+## Guidelines
+
+- Use for side panels, settings, or detail views.
+- `side="left"` for navigation drawers, `side="right"` for actions/details.
+- Closes on Escape key and overlay click.
+- Use `variant="solid"` for high-emphasis content.
+- Use composition API when you need custom header content (icons, badges, etc.).

package/.agent/skills/doom/components/dropdown.md

@@ -0,0 +1,33 @@
+# Dropdown Component
+
+## Import
+
+```tsx
+import { Dropdown } from "doom-design-system";
+```
+
+## Props
+
+| Prop           | Type                                       | Default     | Description  |
+| -------------- | ------------------------------------------ | ----------- | ------------ |
+| `triggerLabel` | `string`                                   | required    | Button text  |
+| `items`        | `{ label: string, onClick: () => void }[]` | required    | Menu items   |
+| `variant`      | `"primary" \| "secondary"`                 | `"primary"` | Button style |
+
+## Usage
+
+```tsx
+<Dropdown
+  triggerLabel="Actions"
+  items={[
+    { label: "Edit", onClick: handleEdit },
+    { label: "Delete", onClick: handleDelete },
+  ]}
+/>
+```
+
+## Guidelines
+
+- Use for action menus or overflow menus.
+- For split primary/secondary actions, use `SplitButton` instead.
+- Menu closes automatically after item click.

package/.agent/skills/doom/components/fileupload.md

@@ -0,0 +1,49 @@
+# FileUpload Component
+
+## Import
+
+```tsx
+import { FileUpload } from "doom-design-system";
+```
+
+## Props
+
+| Prop           | Type                      | Default | Description                             |
+| -------------- | ------------------------- | ------- | --------------------------------------- |
+| `label`        | `string`                  | —       | Upload area label                       |
+| `helperText`   | `string`                  | —       | Helper text                             |
+| `accept`       | `string`                  | —       | Accepted file types (e.g., `"image/*"`) |
+| `maxSize`      | `number`                  | —       | Max file size in bytes                  |
+| `multiple`     | `boolean`                 | `false` | Allow multiple files                    |
+| `defaultFiles` | `File[]`                  | `[]`    | Initial files                           |
+| `disabled`     | `boolean`                 | `false` | Disabled state                          |
+| `error`        | `boolean`                 | `false` | Error state                             |
+| `errorMessage` | `string`                  | —       | Error message                           |
+| `required`     | `boolean`                 | `false` | Required field                          |
+| `showPreview`  | `boolean`                 | `false` | Show image thumbnails                   |
+| `onChange`     | `(files: File[]) => void` | —       | Change callback                         |
+
+## Usage
+
+```tsx
+<FileUpload
+  label="Upload Documents"
+  accept=".pdf,.doc,.docx"
+  maxSize={5 * 1024 * 1024} // 5MB
+  multiple
+  onChange={setFiles}
+/>
+
+<FileUpload
+  label="Profile Photo"
+  accept="image/*"
+  showPreview
+/>
+```
+
+## Guidelines
+
+- Supports drag-and-drop and click-to-browse.
+- `showPreview` displays image thumbnails for image files.
+- Files can be removed individually via the X button.
+- File size validation with clear error messages.