doom-design-system 0.4.17 → 0.5.1

package/.agent/skills/doom/a2ui/a2ui-examples.md

@@ -0,0 +1,289 @@
+# A2UI Examples
+
+## ⚠️ Text Prop Usage
+
+**IMPORTANT**: Not all components support `text: { literalString }`. Check which prop to use:
+
+| Component                                          | ✅ Correct Prop           | ❌ Don't Use |
+| -------------------------------------------------- | ------------------------- | ------------ |
+| `text`, `button`, `badge`, `chip`, `label`, `link` | `text: { literalString }` | -            |
+| `slat`                                             | `label`, `secondaryLabel` | `text`       |
+| `alert`                                            | `title`, `description`    | `text`       |
+| `input`                                            | `label`, `placeholder`    | `text`       |
+
+---
+
+## Example 1: Login Card
+
+**User Request**: "A login card with email and password fields, and a submit button."
+
+```json
+{
+  "surfaceId": "login",
+  "components": [
+    {
+      "id": "root",
+      "component": {
+        "card": {
+          "className": "p-6 w-full",
+          "style": { "maxWidth": "24rem" },
+          "child": "content"
+        }
+      }
+    },
+    {
+      "id": "content",
+      "component": {
+        "stack": {
+          "gap": 4,
+          "children": {
+            "explicitList": ["title", "email", "password", "submit"]
+          }
+        }
+      }
+    },
+    {
+      "id": "title",
+      "component": {
+        "text": { "variant": "h3", "text": { "literalString": "Login" } }
+      }
+    },
+    {
+      "id": "email",
+      "component": {
+        "input": { "label": "Email", "placeholder": "you@example.com" }
+      }
+    },
+    {
+      "id": "password",
+      "component": {
+        "input": { "label": "Password", "type": "password" }
+      }
+    },
+    {
+      "id": "submit",
+      "component": {
+        "button": {
+          "variant": "primary",
+          "className": "w-full",
+          "text": { "literalString": "Sign In" }
+        }
+      }
+    }
+  ]
+}
+```
+
+## Example 2: Dashboard with Slats and Alerts
+
+**User Request**: "Dashboard stats using slat components and a warning alert."
+
+```json
+{
+  "surfaceId": "dashboard",
+  "components": [
+    {
+      "id": "root",
+      "component": {
+        "stack": {
+          "gap": 4,
+          "children": { "explicitList": ["stats-grid", "warning"] }
+        }
+      }
+    },
+    {
+      "id": "stats-grid",
+      "component": {
+        "grid": {
+          "columns": 3,
+          "gap": 4,
+          "children": {
+            "explicitList": ["users-slat", "revenue-slat", "growth-slat"]
+          }
+        }
+      }
+    },
+    {
+      "id": "users-slat",
+      "component": {
+        "slat": {
+          "label": "Total Users",
+          "secondaryLabel": "1,234"
+        }
+      }
+    },
+    {
+      "id": "revenue-slat",
+      "component": {
+        "slat": {
+          "label": "Revenue",
+          "secondaryLabel": "$45.2k"
+        }
+      }
+    },
+    {
+      "id": "growth-slat",
+      "component": {
+        "slat": {
+          "variant": "success",
+          "label": "Growth",
+          "secondaryLabel": "+12%"
+        }
+      }
+    },
+    {
+      "id": "warning",
+      "component": {
+        "alert": {
+          "variant": "warning",
+          "title": "Maintenance Scheduled",
+          "description": "System will be down for maintenance at 2:00 AM UTC."
+        }
+      }
+    }
+  ]
+}
+```
+
+## Example 3: Data Binding
+
+**User Request**: "A user greeting that displays the user's name from data."
+
+```json
+{
+  "surfaceId": "greeting",
+  "components": [
+    {
+      "id": "root",
+      "component": {
+        "card": {
+          "className": "p-6",
+          "children": { "explicitList": ["welcome", "name"] }
+        }
+      }
+    },
+    {
+      "id": "welcome",
+      "component": {
+        "text": {
+          "variant": "small",
+          "className": "text-muted",
+          "text": { "literalString": "Welcome back," }
+        }
+      }
+    },
+    {
+      "id": "name",
+      "component": {
+        "text": {
+          "variant": "h2",
+          "text": { "path": "/user/name" }
+        }
+      }
+    }
+  ]
+}
+```
+
+**Data Model:**
+
+```json
+{
+  "user": { "name": "Alice Chen" }
+}
+```
+
+## Example 4: Navigation with Tabs
+
+**User Request**: "A tabbed interface with Overview and Settings tabs."
+
+```json
+{
+  "surfaceId": "tabbed-ui",
+  "components": [
+    {
+      "id": "root",
+      "component": {
+        "tabs": {
+          "defaultValue": "overview",
+          "children": { "explicitList": ["tab-list", "tab-body"] }
+        }
+      }
+    },
+    {
+      "id": "tab-list",
+      "component": {
+        "tabs-list": {
+          "children": { "explicitList": ["tab-overview", "tab-settings"] }
+        }
+      }
+    },
+    {
+      "id": "tab-overview",
+      "component": {
+        "tabs-trigger": {
+          "value": "overview",
+          "text": { "literalString": "Overview" }
+        }
+      }
+    },
+    {
+      "id": "tab-settings",
+      "component": {
+        "tabs-trigger": {
+          "value": "settings",
+          "text": { "literalString": "Settings" }
+        }
+      }
+    },
+    {
+      "id": "tab-body",
+      "component": {
+        "tabs-body": {
+          "children": {
+            "explicitList": ["content-overview", "content-settings"]
+          }
+        }
+      }
+    },
+    {
+      "id": "content-overview",
+      "component": {
+        "tabs-content": { "value": "overview", "child": "overview-text" }
+      }
+    },
+    {
+      "id": "overview-text",
+      "component": {
+        "text": { "text": { "literalString": "This is the overview content." } }
+      }
+    },
+    {
+      "id": "content-settings",
+      "component": {
+        "tabs-content": { "value": "settings", "child": "settings-text" }
+      }
+    },
+    {
+      "id": "settings-text",
+      "component": {
+        "text": { "text": { "literalString": "This is the settings content." } }
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Quick Reference
+
+**Supports `text` prop (→ children):**
+`text`, `label`, `button`, `badge`, `chip`, `link`, `tabs-trigger`, `breadcrumb-item`
+
+**Use specific props instead:**
+
+- `slat` → `label` + `secondaryLabel`
+- `alert` → `title` + `description`
+- `input` → `label` + `placeholder`
+- `avatar` → `fallback`

package/.agent/skills/doom/a2ui/a2ui-principles.md

@@ -0,0 +1,49 @@
+# A2UI Principles
+
+## 1. Aesthetic
+
+- **Borders**: All interactive elements (cards, buttons, inputs) already have borders built-in. Do not add `border` classes manually.
+- **Shadows**: Use `shadow-hard` for a brutalist look if you are creating a custom container, but prefer using `<Card>` which handles this for you.
+- **Radius**: Default radius is `4px`. Avoid `rounded-full` unless creating a badge or avatar.
+
+## 2. Layout & Spacing
+
+- **Do NOT** use `margin` or `padding` on individual items to space them out.
+- **DO** use `Stack` (vertical) or `Flex` (horizontal) with the `gap` prop.
+  - `gap={1}` = 4px
+  - `gap={4}` = 16px (Standard)
+  - `gap={6}` = 24px (Section separation)
+- Use `Grid` for complex 2D layouts. `columns` prop accepts numbers (`3`) or CSS strings (`"1fr 2fr"`).
+
+## 3. Typography
+
+- Use the `<Text>` component for all text.
+- **Variants**:
+  - `h1`-`h3`: Page/Section titles (Bold, Uppercase)
+  - `body`: Default text
+  - `small`: Metadata/Labels (Muted)
+- Do not use `<h1>` tags inside HTML strings.
+
+## 4. Colors & Variables
+
+- Use CSS variables for all custom styling.
+- **Primary**: `var(--primary)` (Brand color)
+- **Backgrounds**: `var(--card-bg)`, `var(--background)`
+- **Text**: `var(--foreground)`, `var(--muted-foreground)`
+- **Status**: `var(--success)`, `var(--error)`, `var(--warning)`
+
+## 5. Components
+
+- **Inputs**: Always provide a `label`.
+- **Buttons**: Use `variant="ghost"` for secondary/tertiary actions to reduce visual noise.
+- **Charts**: Use the `style` prop to set explicit height (e.g., `{ height: 400 }`).
+
+## 6. Utilities
+
+- **WE ARE NOT A TAILWIND SYSTEM**. Do not use generic Tailwind classes (e.g., `max-w-sm`, `bg-red-500`, `rounded-lg`).
+- **ONLY** use the specific utility classes defined in the Doom system:
+  - Spacing: `p-0` to `p-10`, `m-0` to `m-10` (4px increments)
+  - Sizing: `w-full`, `h-full`, `h-screen`
+  - Flex: `flex`, `flex-col`, `items-center`, `justify-between`
+  - Typography: `text-{size}`, `text-{color}`, `uppercase`, `text-center`, `text-left`, `text-right`
+- For specific visuals not covered by utilities, use the `style` prop.

package/.agent/skills/doom/a2ui/a2ui-protocol.md

@@ -0,0 +1,191 @@
+# A2UI Protocol Reference
+
+## Message Schema
+
+A2UI uses a flat adjacency list format where components reference children by ID.
+
+### Component Structure
+
+```json
+{
+  "surfaceId": "main",
+  "components": [
+    {
+      "id": "unique-id",
+      "component": {
+        "component-type": {
+          "propName": "value",
+          "text": { "literalString": "Static text" },
+          "children": { "explicitList": ["child-id-1", "child-id-2"] }
+        }
+      }
+    }
+  ]
+}
+```
+
+### Value Types
+
+| Type              | Format                       | Example                          |
+| ----------------- | ---------------------------- | -------------------------------- |
+| Literal String    | `{ "literalString": "..." }` | `{ "literalString": "Hello" }`   |
+| Data Binding      | `{ "path": "/..." }`         | `{ "path": "/user/name" }`       |
+| Single Child      | `"child-id"`                 | `"header-component"`             |
+| Multiple Children | `{ "explicitList": [...] }`  | `{ "explicitList": ["a", "b"] }` |
+
+---
+
+## Text Content: IMPORTANT
+
+**Not all components use `text` prop.** Only components marked with ✅ below support `text: { literalString }` or `text: { path }`:
+
+| Supports `text` prop | Component         | Text Prop                      |
+| :------------------: | ----------------- | ------------------------------ |
+|          ✅          | `label`           | `text`                         |
+|          ✅          | `text`            | `text` → maps to children      |
+|          ✅          | `button`          | `text` → maps to children      |
+|          ✅          | `badge`           | `text` → maps to children      |
+|          ✅          | `chip`            | `text` → maps to children      |
+|          ✅          | `link`            | `text` → maps to children      |
+|          ✅          | `tabs-trigger`    | `text` → maps to children      |
+|          ✅          | `breadcrumb-item` | `text` → maps to children      |
+|          ❌          | `slat`            | Use `label` + `secondaryLabel` |
+|          ❌          | `alert`           | Use `title` + `description`    |
+|          ❌          | `input`           | Use `label` + `placeholder`    |
+|          ❌          | `avatar`          | Use `fallback` for initials    |
+
+### Common Mistakes
+
+```json
+// ❌ WRONG - slat doesn't support text prop
+{ "slat": { "label": "Trips", "text": { "literalString": "4" } } }
+
+// ✅ CORRECT - use secondaryLabel
+{ "slat": { "label": "Trips", "secondaryLabel": "4" } }
+
+// ❌ WRONG - alert doesn't support text prop
+{ "alert": { "variant": "warning", "text": { "literalString": "Warning message" } } }
+
+// ✅ CORRECT - use title and description
+{ "alert": { "variant": "warning", "title": "Warning", "description": "Message details" } }
+```
+
+---
+
+## Component Reference
+
+### Primitives
+
+| Type       | Key Props                            | Notes                          |
+| ---------- | ------------------------------------ | ------------------------------ |
+| `label`    | `text` ✅                            | Simple text label              |
+| `text`     | `variant`, `text` ✅                 | Typography: h1-h6/body/small   |
+| `button`   | `variant`, `text` ✅                 | primary/secondary/ghost/danger |
+| `badge`    | `variant`, `text` ✅                 | Status indicator               |
+| `chip`     | `variant`, `text` ✅                 | Tag element                    |
+| `avatar`   | `src`, `fallback`, `size`            | User avatar                    |
+| `alert`    | `title` ⚠️, `description`, `variant` | title is REQUIRED              |
+| `card`     | `className`, `child`/`children`      | Container                      |
+| `input`    | `label`, `placeholder`, `value`      | Text field                     |
+| `textarea` | `label`, `placeholder`, `rows`       | Multi-line                     |
+| `checkbox` | `label`, `checked`                   | Checkbox                       |
+| `switch`   | `label`, `checked`                   | Toggle                         |
+| `link`     | `href`, `text` ✅                    | Hyperlink                      |
+| `spinner`  | `size`                               | Loading indicator              |
+
+### Layout
+
+| Type        | Key Props                                          |
+| ----------- | -------------------------------------------------- |
+| `flex`      | `direction`, `gap`, `align`, `justify`, `children` |
+| `stack`     | `gap`, `children`                                  |
+| `grid`      | `columns`, `gap`, `children`                       |
+| `container` | `size`, `children`                                 |
+| `box`       | `className`, `children`                            |
+
+### Data Display
+
+| Type             | Key Props                               | Notes                           |
+| ---------------- | --------------------------------------- | ------------------------------- |
+| `slat`           | `label` ⚠️, `secondaryLabel`, `variant` | label is REQUIRED, NO text prop |
+| `table`          | `data`, `columns`                       | Each column needs `accessorKey` |
+| `chart`          | `type`, `data`, `xKey`, `yKey`          | line/area/bar                   |
+| `accordion`      | `type`, `defaultValue`, `children`      | single/multiple                 |
+| `accordion-item` | `value`, `trigger`, `children`          |                                 |
+| `image`          | `src`, `alt`                            |                                 |
+
+### Navigation
+
+| Type              | Key Props                   |
+| ----------------- | --------------------------- |
+| `tabs`            | `defaultValue`, `children`  |
+| `tabs-list`       | `children`                  |
+| `tabs-trigger`    | `value`, `text` ✅          |
+| `tabs-body`       | `children`                  |
+| `tabs-content`    | `value`, `child`/`children` |
+| `breadcrumbs`     | `children`                  |
+| `breadcrumb-item` | `href`, `text` ✅           |
+
+### Feedback
+
+| Type           | Key Props          |
+| -------------- | ------------------ |
+| `progress-bar` | `value`, `variant` |
+| `skeleton`     | `width`, `height`  |
+
+### Actions
+
+| Type           | Key Props  |
+| -------------- | ---------- |
+| `action-row`   | `children` |
+| `split-button` | `options`  |
+
+---
+
+## Complete Example
+
+```json
+{
+  "surfaceId": "demo",
+  "components": [
+    {
+      "id": "root",
+      "component": {
+        "card": {
+          "className": "p-6",
+          "children": { "explicitList": ["header", "stats", "warning"] }
+        }
+      }
+    },
+    {
+      "id": "header",
+      "component": {
+        "text": {
+          "variant": "h2",
+          "text": { "literalString": "Dashboard" }
+        }
+      }
+    },
+    {
+      "id": "stats",
+      "component": {
+        "slat": {
+          "label": "Active Users",
+          "secondaryLabel": "1,234",
+          "variant": "success"
+        }
+      }
+    },
+    {
+      "id": "warning",
+      "component": {
+        "alert": {
+          "variant": "warning",
+          "title": "Maintenance Scheduled",
+          "description": "System will be down at 2:00 AM UTC."
+        }
+      }
+    }
+  ]
+}
+```

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

@@ -0,0 +1,46 @@
+# A2UI
+
+The `A2UI` component renders a UI tree from a declarative JSON structure, enabling AI agents and external sources to generate Doom Design System interfaces dynamically.
+
+## Import
+
+```tsx
+import { A2UI } from "doom-design-system";
+```
+
+## Usage
+
+Pass the JSON tree to the `data` prop. The JSON must adhere to the [A2UI Protocol Schema](a2ui-protocol.md).
+
+```tsx
+const data = {
+  type: "card",
+  props: { className: "p-6" },
+  children: [
+    {
+      type: "button",
+      props: { variant: "primary" },
+      children: ["Rendered from JSON"],
+    },
+  ],
+};
+
+return <A2UI data={data} />;
+```
+
+## Props
+
+| Prop   | Type       | Description                                  |
+| ------ | ---------- | -------------------------------------------- |
+| `data` | `A2UINode` | The JSON tree root node to render. Required. |
+
+## Types
+
+```tsx
+interface A2UINode {
+  id?: string;
+  type: string;
+  props?: Record<string, unknown>;
+  children?: (A2UINode | string)[];
+}
+```