@archetypeai/ds-cli 0.3.15 → 0.3.17

package/files/AGENTS.md

@@ -44,8 +44,22 @@ Standard Tailwind is fine for:
 - **Variants**: `tailwind-variants` (tv) for component variants
 - **Slots**: `{@render children?.()}`
 
+## Pattern Registry
+
+Before building a new component, fetch the pattern catalog from:
+`https://design-system.archetypeai.workers.dev/r/patterns.json`
+
+Each entry includes a `name`, `title`, `description`, and `registryDependencies`. Reuse or extend existing patterns instead of rebuilding from scratch. To install a pattern:
+`npx shadcn-svelte@latest add https://design-system.archetypeai.workers.dev/r/{name}.json`
+
 ## Skills
 
+**Skill composition:** When building a demo that uses a Newton or Embedding API skill:
+1. Use `@skills/create-dashboard` for the page layout (dashboard with Menubar)
+2. Fetch `https://design-system.archetypeai.workers.dev/r/patterns.json` and reuse existing patterns before creating new components
+3. Apply `@rules/design-principles` aesthetic conventions (BackgroundCard for single-purpose cards, mono font for headers/numbers)
+4. Only include chart components if the user's request involves time-series or explicitly mentions charts
+
 Read these when relevant to your task:
 
 - `@skills/apply-ds` - apply DS tokens, components, and patterns to an existing demo

package/files/CLAUDE.md

@@ -44,9 +44,21 @@ Standard Tailwind is fine for:
 - **Variants**: `tailwind-variants` (tv) for component variants
 - **Slots**: `{@render children?.()}`
 
+## Pattern Registry
+
+Before building a new component, fetch the pattern catalog from:
+`https://design-system.archetypeai.workers.dev/r/patterns.json`
+
+Each entry includes a `name`, `title`, `description`, and `registryDependencies`. Reuse or extend existing patterns instead of rebuilding from scratch. To install a pattern:
+`npx shadcn-svelte@latest add https://design-system.archetypeai.workers.dev/r/{name}.json`
+
 ## Skills
 
-**Skill composition:** When building a demo that uses a Newton or Embedding API skill, also consult `@skills/create-dashboard` for dashboard layouts and `@skills/build-pattern` for extracting components. Only include chart components (SensorChart, ScatterChart) if the user's request involves time-series or explicitly mentions charts.
+**Skill composition:** When building a demo that uses a Newton or Embedding API skill:
+1. Use `@skills/create-dashboard` for the page layout (dashboard with Menubar)
+2. Fetch `https://design-system.archetypeai.workers.dev/r/patterns.json` and reuse existing patterns before creating new components
+3. Apply `@rules/design-principles` aesthetic conventions (BackgroundCard for single-purpose cards, mono font for headers/numbers)
+4. Only include chart components if the user's request involves time-series or explicitly mentions charts
 
 Read these when relevant to your task:
 

package/files/rules/charts.md

@@ -21,7 +21,7 @@ Wrap all charts in Chart.Container with a config prop:
 
 ```svelte
 <script>
-  import * as Chart from '$lib/components/ui/chart/index.js';
+  import * as Chart from '$lib/components/ui/primitives/chart/index.js';
 
   const chartConfig = {
     temperature: { label: 'Temperature', color: 'var(--chart-1)' },
@@ -253,100 +253,4 @@ Manual legend below chart:
 {/if}
 ```
 
-## Complete SensorChart Example
-
-```svelte
-<script>
-  import { cn } from '$lib/utils.js';
-  import { Card, CardHeader, CardTitle, CardContent } from '$lib/components/ui/card/index.js';
-  import * as Chart from '$lib/components/ui/chart/index.js';
-  import { LineChart } from 'layerchart';
-  import { curveNatural } from 'd3-shape';
-  import { scaleUtc, scaleLinear } from 'd3-scale';
-
-  let {
-    title = 'SENSOR',
-    icon: Icon = undefined,
-    data = [],
-    signals = {},
-    xKey = 'timestamp',
-    maxPoints = undefined,
-    yMin,
-    yMax,
-    yTicks,
-    class: className,
-    ...restProps
-  } = $props();
-
-  const chartColors = [
-    'var(--chart-1)',
-    'var(--chart-2)',
-    'var(--chart-3)',
-    'var(--chart-4)',
-    'var(--chart-5)'
-  ];
-
-  let displayData = $derived(maxPoints && data.length > maxPoints ? data.slice(-maxPoints) : data);
-
-  let indexedData = $derived(displayData.map((d, i) => ({ ...d, _index: i })));
-
-  let series = $derived(
-    Object.entries(signals).map(([key, label], i) => ({
-      key,
-      label,
-      color: chartColors[i % chartColors.length]
-    }))
-  );
-
-  let chartConfig = $derived(
-    Object.fromEntries(series.map((s) => [s.key, { label: s.label, color: s.color }]))
-  );
-
-  let useIndexX = $derived(maxPoints !== undefined);
-  let xDomain = $derived(useIndexX ? [0, (maxPoints || displayData.length) - 1] : undefined);
-</script>
-
-<Card class={cn('p-4', className)} {...restProps}>
-  <CardHeader class="flex flex-row items-center justify-between p-0">
-    <CardTitle class="text-foreground font-mono text-base uppercase">
-      {title}
-    </CardTitle>
-    {#if Icon}
-      <Icon strokeWidth={1.25} class="text-muted-foreground size-6" />
-    {/if}
-  </CardHeader>
-
-  <CardContent class="flex flex-col gap-6 p-0">
-    <Chart.Container config={chartConfig} class="aspect-auto h-[220px] w-full">
-      <LineChart
-        data={indexedData}
-        x={useIndexX ? '_index' : xKey}
-        xScale={useIndexX ? scaleLinear() : scaleUtc()}
-        {xDomain}
-        yScale={scaleLinear()}
-        yDomain={[yMin, yMax]}
-        {series}
-        tooltip={false}
-        props={{
-          spline: { curve: curveNatural, strokeWidth: 1.5 },
-          yAxis: { ticks: yTicks }
-        }}
-      />
-    </Chart.Container>
-
-    {#if series.length > 0}
-      <div class="flex items-center justify-center gap-10">
-        {#each series as s (s.key)}
-          <div class="flex items-center gap-2">
-            <div
-              class="size-2 rounded-full bg-(--legend-color)"
-              style:--legend-color={s.color}
-            ></div>
-            <span class="text-foreground text-sm">{s.label}</span>
-          </div>
-        {/each}
-      </div>
-    {/if}
-  </CardContent>
-</Card>
-```
+For a complete chart pattern example, see the `sensor-chart` pattern source in `$lib/components/ui/patterns/sensor-chart/`.

package/files/rules/components.md

@@ -75,22 +75,7 @@ When wrapping bits-ui primitives, import the primitive and wrap it:
 </SelectPrimitive.Trigger>
 ```
 
-Common bits-ui primitives:
-
-- `Dialog` - Dialog.Root, Dialog.Portal, Dialog.Content, Dialog.Trigger, Dialog.Close
-- `AlertDialog` - AlertDialog.Root, AlertDialog.Trigger, AlertDialog.Content, AlertDialog.Action, AlertDialog.Cancel
-- `Select` - Select.Root, Select.Trigger, Select.Content, Select.Item
-- `Popover` - Popover.Root, Popover.Portal, Popover.Content, Popover.Trigger
-- `HoverCard` - HoverCard.Root, HoverCard.Trigger, HoverCard.Content
-- `Tooltip` - Tooltip.Root, Tooltip.Trigger, Tooltip.Content
-- `DropdownMenu` - DropdownMenu.Root, DropdownMenu.Trigger, DropdownMenu.Content, DropdownMenu.Item
-- `ContextMenu` - ContextMenu.Root, ContextMenu.Trigger, ContextMenu.Content, ContextMenu.Item
-- `Accordion` - Accordion.Root, Accordion.Item, Accordion.Trigger, Accordion.Content
-- `Tabs` - Tabs.Root, Tabs.List, Tabs.Trigger, Tabs.Content
-- `Collapsible` - Collapsible.Root, Collapsible.Trigger, Collapsible.Content
-- `Command` - Command.Root, Command.Input, Command.List, Command.Item
-
-Additional bits-ui primitives: Calendar, RangeCalendar, Checkbox, Switch, Slider, Toggle, ToggleGroup, RadioGroup, Menubar, NavigationMenu, Pagination, InputOTP, Sidebar, Progress, Label, Separator, AspectRatio, Avatar, ScrollArea, Sheet. Check the source files for their wrapper patterns.
+For the full primitives catalog with import paths, see `@skills/build-pattern`.
 
 ## tailwind-variants (tv)
 

package/files/rules/design-principles.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - '**/*.svelte'
+  - '**/+page.svelte'
+---
+
 # Physical AI Design Principles
 
 ## Scope
@@ -53,4 +59,13 @@ Interaction unfolds within a three-way relationship: **person, system, and physi
 
 - Default to interfaces that support perception and reasoning rather than autonomous AI action
 - Where possible, distinguish between "the system shows" (Measure) and "the system suggests" (Reason)
-- Prefer framing AI output as observations or suggestions rather than commands or decisions
+- Prefer framing AI output as observations or suggestions rather than commands or decisions
+
+## Aesthetic Conventions
+
+### Typography
+- Use mono font (`font-mono`) with careful consideration: prefer it on badges, buttons, card headers, and numeric values. Do not apply mono to body text or descriptions.
+
+### Card Defaults
+- For single-purpose card components (status display, score, chart), use BackgroundCard as the default container.
+- Status cards showing a single metric or state often do not need a CardHeader — omit when content is self-explanatory.

package/files/rules/frontend-architecture.md

@@ -23,11 +23,11 @@ Common extraction candidates: media inputs, status displays, result/summary view
 
 The project includes pattern components that demonstrate these conventions. Study them before building new ones:
 
-- `$lib/components/ui/VideoPlayer.svelte` — media playback with controls, composes Card + AspectRatio + Button + Slider
-- `$lib/components/ui/ExpandableLog.svelte` — streaming log display, composes Collapsible + Item + Badge
-- `$lib/components/ui/StatusBadge.svelte` — health indicator with derived state, composes Badge + Avatar
-- `$lib/components/ui/HealthscoreCard.svelte` — score card with derived state, composes Card sub-components
-- `$lib/components/ui/Menubar.svelte` — branded header with snippet slots
+- `$lib/components/ui/patterns/video-player/video-player.svelte` — media playback with controls, composes Card + AspectRatio + Button + Slider
+- `$lib/components/ui/patterns/expandable-log/expandable-log.svelte` — streaming log display, composes Collapsible + Item + Badge
+- `$lib/components/ui/patterns/status-badge/status-badge.svelte` — health indicator with derived state, composes Badge + Avatar
+- `$lib/components/ui/patterns/healthscore-card/healthscore-card.svelte` — score card with derived state, composes Card sub-components
+- `$lib/components/ui/patterns/menubar/menubar.svelte` — branded header with snippet slots
 
 Check if an existing pattern fits before building a new one. Use `@skills/build-pattern` to create new patterns that follow these same conventions.
 

package/files/rules/state.md

@@ -330,50 +330,18 @@ Log when values change (removed in production builds):
 
 ### Async Code Doesn't Track Dependencies
 
-```svelte
-<script>
-  let color = $state('red');
-  let size = $state(100);
-
-  $effect(() => {
-    // color is tracked (read synchronously)
-    console.log(color);
-
-    setTimeout(() => {
-      // size is NOT tracked (read async)
-      console.log(size);
-    }, 100);
-  });
-</script>
-```
+Only synchronously-read state inside `$effect` is tracked. State read inside `setTimeout`, `await`, or callbacks is not tracked.
 
 ### Exporting Reassigned State
 
-Can't directly export state that gets reassigned:
+Can't directly export state that gets reassigned. Wrap in an object instead:
 
 ```javascript
 // state.svelte.js
-
-// BAD - won't work across modules
-export let count = $state(0);
-export function increment() {
-  count++;
-}
-
-// GOOD - wrap in object
 export const counter = $state({ count: 0 });
 export function increment() {
   counter.count++;
 }
-
-// GOOD - use getters
-let count = $state(0);
-export function getCount() {
-  return count;
-}
-export function increment() {
-  count++;
-}
 ```
 
 ### Effects Only Run in Browser

package/files/rules/styling.md

@@ -6,68 +6,17 @@ paths:
 
 # Styling Rules
 
-## Semantic Token Reference
-
-### Background & Foreground Colors
-
-| Token                     | Usage                        |
-| ------------------------- | ---------------------------- |
-| `bg-background`           | Page/app background          |
-| `text-foreground`         | Primary text color           |
-| `bg-card`                 | Card backgrounds             |
-| `text-card-foreground`    | Text on cards                |
-| `bg-popover`              | Popover/dropdown backgrounds |
-| `text-popover-foreground` | Text in popovers             |
-| `bg-muted`                | Muted/subtle backgrounds     |
-| `text-muted-foreground`   | Secondary/muted text         |
-
-### Interactive Colors
-
-| Token                       | Usage                         |
-| --------------------------- | ----------------------------- |
-| `bg-primary`                | Primary buttons, links        |
-| `text-primary-foreground`   | Text on primary backgrounds   |
-| `bg-secondary`              | Secondary buttons             |
-| `text-secondary-foreground` | Text on secondary backgrounds |
-| `bg-accent`                 | Hover states, highlights      |
-| `text-accent-foreground`    | Text on accent backgrounds    |
-| `bg-destructive`            | Delete/error actions          |
-
-### Border & Input Colors
-
-| Token           | Usage                |
-| --------------- | -------------------- |
-| `border-border` | Default border color |
-| `border-input`  | Input field borders  |
-| `ring-ring`     | Focus ring color     |
-
-### Chart Colors
-
-| Token       | Usage                            |
-| ----------- | -------------------------------- |
-| `--chart-1` | First series color (purple)      |
-| `--chart-2` | Second series color (red-orange) |
-| `--chart-3` | Third series color (green)       |
-| `--chart-4` | Fourth series color (yellow)     |
-| `--chart-5` | Fifth series color (coral)       |
-
-### ATAI Brand Colors
-
-| Token                | Usage                 |
-| -------------------- | --------------------- |
-| `bg-atai-neutral`    | Brand blue accent     |
-| `text-atai-good`     | Success/healthy state |
-| `text-atai-warning`  | Warning state         |
-| `text-atai-critical` | Critical/error state  |
-
-### Sidebar Colors
-
-| Token                     | Usage                |
-| ------------------------- | -------------------- |
-| `bg-sidebar`              | Sidebar background   |
-| `text-sidebar-foreground` | Sidebar text         |
-| `bg-sidebar-accent`       | Sidebar hover/active |
-| `border-sidebar-border`   | Sidebar borders      |
+## Semantic Tokens
+
+For the complete token reference including dark mode overrides, type scale (h1–h6, p, small), and spacing definitions, read `node_modules/@archetypeai/ds-lib-tokens/theme.css`.
+
+Token naming pattern: `bg-{token}`, `text-{token}-foreground`, `border-{token}`.
+
+Core tokens: `background`, `foreground`, `primary`, `secondary`, `muted`, `card`, `accent`, `destructive`, `border`, `input`, `ring`.
+
+ATAI brand tokens: `atai-neutral`, `atai-good`, `atai-warning`, `atai-critical`.
+
+Chart series: `--chart-1` through `--chart-5` (see `@rules/charts`).
 
 ## When to Use Semantic vs Standard Tailwind
 
@@ -126,33 +75,7 @@ For custom dark mode overrides, use the `dark:` prefix:
 <div class="bg-white dark:bg-slate-900">  <!-- custom dark override -->
 ```
 
-## cn() Utility
-
-Import and use for all class composition:
-
-```javascript
-import { cn } from '$lib/utils.js';
-```
-
-```svelte
-<div class={cn(
-  'base-classes here',
-  conditional && 'conditional-classes',
-  className
-)}>
-```
-
-The utility:
-
-- Uses `clsx` for conditional class joining
-- Uses `tailwind-merge` to resolve conflicts (last wins)
-
-Example conflict resolution:
-
-```javascript
-cn('p-4', 'p-2'); // → 'p-2' (later wins)
-cn('bg-red-500', 'bg-background'); // → 'bg-background' (later wins)
-```
+For class merging with `cn()`, see `@rules/components`.
 
 ## CSS Import Order
 
@@ -212,34 +135,6 @@ Prefer Tailwind classes directly in markup. Use @apply only in base layer CSS:
 
 ## Common Patterns
 
-### Focus States
-
-```svelte
-<button class="focus-visible:ring-ring focus-visible:ring-2 focus-visible:ring-offset-2 outline-none">
-```
-
-### Disabled States
+For focus ring, disabled state, and data-state animation CSS patterns, see `@rules/accessibility`.
 
-```svelte
-<button class="disabled:pointer-events-none disabled:opacity-50">
-```
-
-### Data State Animations
-
-```svelte
-<div class="data-[state=open]:animate-in data-[state=closed]:animate-out">
-```
-
-### Responsive Design
-
-```svelte
-<div class="w-full max-w-[calc(100%-2rem)] sm:max-w-lg">
-<div class="flex flex-col sm:flex-row">
-```
-
-### Icon Sizing
-
-```svelte
-<!-- Default icon sizing utility -->
-<button class="[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4">
-```
+For icon sizing conventions, see `@rules/components`.

package/files/skills/apply-ds/SKILL.md

@@ -68,15 +68,15 @@ Swap native HTML elements for their DS component equivalents. Add imports as nee
 
 | Native Element | DS Component | Import From |
 | --- | --- | --- |
-| `<button>` | `<Button>` | `$lib/components/ui/button` |
-| `<input>` | `<Input>` | `$lib/components/ui/input` |
-| `<textarea>` | `<Textarea>` | `$lib/components/ui/textarea` |
-| `<select>` | `<Select.Root>` + `<Select.Trigger>` + `<Select.Content>` + `<Select.Item>` | `$lib/components/ui/select` |
-| `<table>` | `<Table.Root>` + `<Table.Header>` + `<Table.Row>` + `<Table.Head>` + `<Table.Body>` + `<Table.Cell>` | `$lib/components/ui/table` |
-| `<dialog>` | `<Dialog.Root>` + `<Dialog.Content>` + `<Dialog.Header>` + `<Dialog.Title>` | `$lib/components/ui/dialog` |
-| `<hr>` | `<Separator>` | `$lib/components/ui/separator` |
-| `<label>` | `<Label>` | `$lib/components/ui/label` |
-| `<a>` (styled as button) | `<Button variant="link">` or `<Button>` with `href` | `$lib/components/ui/button` |
+| `<button>` | `<Button>` | `$lib/components/ui/primitives/button` |
+| `<input>` | `<Input>` | `$lib/components/ui/primitives/input` |
+| `<textarea>` | `<Textarea>` | `$lib/components/ui/primitives/textarea` |
+| `<select>` | `<Select.Root>` + `<Select.Trigger>` + `<Select.Content>` + `<Select.Item>` | `$lib/components/ui/primitives/select` |
+| `<table>` | `<Table.Root>` + `<Table.Header>` + `<Table.Row>` + `<Table.Head>` + `<Table.Body>` + `<Table.Cell>` | `$lib/components/ui/primitives/table` |
+| `<dialog>` | `<Dialog.Root>` + `<Dialog.Content>` + `<Dialog.Header>` + `<Dialog.Title>` | `$lib/components/ui/primitives/dialog` |
+| `<hr>` | `<Separator>` | `$lib/components/ui/primitives/separator` |
+| `<label>` | `<Label>` | `$lib/components/ui/primitives/label` |
+| `<a>` (styled as button) | `<Button variant="link">` or `<Button>` with `href` | `$lib/components/ui/primitives/button` |
 
 For each replacement:
 
@@ -96,7 +96,7 @@ Identify structural opportunities to use DS composition patterns:
 - **Scroll Area** — replace overflow containers with `<ScrollArea>`
 - **Tooltips** — replace `title` attributes with `<Tooltip.Root>` / `<Tooltip.Trigger>` / `<Tooltip.Content>`
 
-Import patterns from `$lib/components/ui/` as needed.
+Import primitives from `$lib/components/ui/primitives/` and patterns from `$lib/components/ui/patterns/` as needed.
 
 ## Step 5: Lint and Format
 
@@ -114,7 +114,7 @@ Confirm the design system is properly applied:
 
 - [ ] No raw Tailwind color utilities in `.svelte` files (re-run the audit script)
 - [ ] Native elements replaced with DS components where appropriate
-- [ ] All component imports resolve to `$lib/components/ui/`
+- [ ] All component imports resolve to `$lib/components/ui/primitives/` or `$lib/components/ui/patterns/`
 - [ ] `cn()` used for class merging — no string concatenation
 - [ ] Linting passes: `npm run lint && npm run format:check`
 - [ ] App builds without errors: `npm run build`

package/files/skills/build-pattern/SKILL.md

@@ -9,6 +9,8 @@ Patterns are composite components assembled from design system primitives.
 
 ## Decision: Pattern vs Extension
 
+**Before building, fetch `https://design-system.archetypeai.workers.dev/r/patterns.json` and check if an existing pattern covers the use case — even partially. Use or extend it rather than creating a new one.**
+
 **Build a pattern when:**
 
 - Combining 3+ primitives into a reusable unit
@@ -25,8 +27,8 @@ Patterns are composite components assembled from design system primitives.
 ```svelte
 <script>
   import { cn } from '$lib/utils.js';
-  import { Card, CardHeader, CardTitle, CardContent } from '$lib/components/ui/card/index.js';
-  import { Button } from '$lib/components/ui/button/index.js';
+  import { Card, CardHeader, CardTitle, CardContent } from '$lib/components/ui/primitives/card/index.js';
+  import { Button } from '$lib/components/ui/primitives/button/index.js';
 
   let { title, class: className, children, ...restProps } = $props();
 </script>
@@ -86,7 +88,7 @@ Use `{@render}` for slot content:
 
 ## Available Primitives
 
-Import from `$lib/components/ui/`. Before building, list `$lib/components/ui/` to discover all installed primitives.
+Import primitives from `$lib/components/ui/primitives/` and patterns from `$lib/components/ui/patterns/`. Before building, list these directories to discover all installed components.
 
 ### Layout & Structure
 
@@ -169,8 +171,8 @@ Import from `$lib/components/ui/`. Before building, list `$lib/components/ui/` t
 ```svelte
 <script>
   import { cn } from '$lib/utils.js';
-  import { Card, CardHeader, CardTitle, CardContent } from '$lib/components/ui/card/index.js';
-  import * as Chart from '$lib/components/ui/chart/index.js';
+  import { Card, CardHeader, CardTitle, CardContent } from '$lib/components/ui/primitives/card/index.js';
+  import * as Chart from '$lib/components/ui/primitives/chart/index.js';
 
   let { title = 'SENSOR', icon: Icon, data = [], class: className, ...restProps } = $props();
 </script>

package/files/skills/create-dashboard/SKILL.md

@@ -13,7 +13,7 @@ Scaffold a full-viewport dashboard with a branded menubar and panel-based conten
 
 Before building, check which components are installed in the project:
 
-1. List `$lib/components/ui/` to discover available primitives (subdirectories with `index.js`) and patterns (PascalCase `.svelte` files)
+1. List `$lib/components/ui/primitives/` and `$lib/components/ui/patterns/` to discover available primitives and patterns (each in a kebab-case subdirectory with `index.js`)
 2. Only use components that actually exist in the project
 3. If a required component is missing, ask the user to install it (via `npx shadcn-svelte@latest add`) or build it (via `@skills/build-pattern`)
 4. **Never inline raw markup as a substitute for a missing component**
@@ -44,8 +44,8 @@ Use the `Menubar` pattern. It renders a branded `<header>` with the Archetype AI
 
 ```svelte
 <script>
-  import Menubar from '$lib/components/ui/Menubar.svelte';
-  import { Button } from '$lib/components/ui/button/index.js';
+  import Menubar from '$lib/components/ui/patterns/menubar/index.js';
+  import { Button } from '$lib/components/ui/primitives/button/index.js';
 </script>
 
 <Menubar>
@@ -61,7 +61,7 @@ For co-branding, pass a `partnerLogo` snippet to replace the default placeholder
   {#snippet partnerLogo()}
     <img src="/partner-logo.svg" alt="Partner" class="h-6" />
   {/snippet}
-  <!-- additive example — append to existing children, don't replace them -->
+  <!-- additive example — append to existing children, don't replace them  -->
   <Button variant="link" class="text-muted-foreground">Send Report</Button>
 </Menubar>
 ```
@@ -77,8 +77,8 @@ For co-branding, pass a `partnerLogo` snippet to replace the default placeholder
 
 ```svelte
 <script>
-  import Menubar from '$lib/components/ui/Menubar.svelte';
-  import { Button } from '$lib/components/ui/button/index.js';
+  import Menubar from '$lib/components/ui/patterns/menubar/index.js';
+  import { Button } from '$lib/components/ui/primitives/button/index.js';
 </script>
 
 <div class="bg-background grid h-screen w-screen grid-rows-[auto_1fr] overflow-hidden">
@@ -150,9 +150,9 @@ For co-branding, pass a `partnerLogo` snippet to replace the default placeholder
 ```svelte
 <!-- src/routes/+page.svelte -->
 <script>
-  import Menubar from '$lib/components/ui/Menubar.svelte';
-  import { Button } from '$lib/components/ui/button/index.js';
-  import { Card, CardHeader, CardTitle, CardContent } from '$lib/components/ui/card/index.js';
+  import Menubar from '$lib/components/ui/patterns/menubar/index.js';
+  import { Button } from '$lib/components/ui/primitives/button/index.js';
+  import { Card, CardHeader, CardTitle, CardContent } from '$lib/components/ui/primitives/card/index.js';
 </script>
 
 <div
@@ -187,7 +187,7 @@ For co-branding, pass a `partnerLogo` snippet to replace the default placeholder
 
 Panels should contain pattern components, not raw markup. Before building new components:
 
-1. Check if existing patterns fit the need — `VideoPlayer`, `ExpandableLog`, `StatusBadge`, `HealthscoreCard`, `SensorChart`, `ScatterChart`
+1. Fetch `https://design-system.archetypeai.workers.dev/r/patterns.json` to discover available patterns. Each has a `description` summarizing its purpose. If one fits, use it.
 2. If no existing pattern fits, create one via `@skills/build-pattern`
 3. Each panel should contain one primary component with clear props for data flow
 

package/files/skills/embedding-from-file/SKILL.md

@@ -8,7 +8,20 @@ argument-hint: [csv-file-path]
 
 Generate a script that streams time-series data from a CSV file to the Archetype AI Embedding Lens and collects embedding vectors. Supports both Python and JavaScript/Web.
 
-> **Frontend architecture:** When building a web UI for this skill, decompose into components (file input, status display, visualization) rather than a monolithic page. Extract API/streaming logic into `$lib/api/`. See `@rules/frontend-architecture` for conventions and `@skills/create-dashboard` / `@skills/build-pattern` for layout and component patterns.
+## Frontend Architecture
+
+Decompose the UI into components. See `@rules/frontend-architecture` for conventions.
+
+### Recommended decomposition
+
+| UI Area | Component | Pattern/Primitives | Key Props |
+|---------|-----------|-------------------|-----------|
+| File input | `DataInput.svelte` | BackgroundCard, Button, Input | `onselect`, `status` |
+| Scatter plot | Reuse ScatterChart pattern | BackgroundCard, Chart | `data[]`, `categories` |
+| Progress | `StreamProgress.svelte` | BackgroundCard, Progress | `current`, `total` |
+
+- Use `@skills/create-dashboard` for the page layout
+- Extract streaming and session logic into `$lib/api/embeddings.js`
 
 ---
 

package/files/skills/embedding-from-sensor/SKILL.md

@@ -8,7 +8,20 @@ argument-hint: [source-type]
 
 Generate a script that streams real-time IMU sensor data to the Archetype AI Embedding Lens for live embedding extraction. Supports both Python and JavaScript/Web.
 
-> **Frontend architecture:** When building a web UI for this skill, decompose into components (sensor connection, status display, embedding visualization) rather than a monolithic page. Extract sensor and API logic into `$lib/api/`. See `@rules/frontend-architecture` for conventions and `@skills/create-dashboard` / `@skills/build-pattern` for layout and component patterns.
+## Frontend Architecture
+
+Decompose the UI into components. See `@rules/frontend-architecture` for conventions.
+
+### Recommended decomposition
+
+| UI Area | Component | Pattern/Primitives | Key Props |
+|---------|-----------|-------------------|-----------|
+| Sensor input | `DataInput.svelte` | BackgroundCard, Button, Input | `onselect`, `status` |
+| Scatter plot | Reuse ScatterChart pattern | BackgroundCard, Chart | `data[]`, `categories` |
+| Progress | `StreamProgress.svelte` | BackgroundCard, Progress | `current`, `total` |
+
+- Use `@skills/create-dashboard` for the page layout
+- Extract streaming and session logic into `$lib/api/embeddings.js`
 
 ---
 

package/files/skills/embedding-upload/SKILL.md

@@ -8,7 +8,20 @@ argument-hint: [csv-file-path]
 
 Generate a script that uploads a CSV file to the Archetype AI platform and extracts embeddings server-side. The server reads the file directly — no local streaming loop required. Supports both Python and JavaScript/Web.
 
-> **Frontend architecture:** When building a web UI for this skill, decompose into components (file upload, status display, results view) rather than a monolithic page. Extract API logic into `$lib/api/`. See `@rules/frontend-architecture` for conventions and `@skills/create-dashboard` / `@skills/build-pattern` for layout and component patterns.
+## Frontend Architecture
+
+Decompose the UI into components. See `@rules/frontend-architecture` for conventions.
+
+### Recommended decomposition
+
+| UI Area | Component | Pattern/Primitives | Key Props |
+|---------|-----------|-------------------|-----------|
+| File upload | `DataInput.svelte` | BackgroundCard, Button, Input | `onselect`, `status` |
+| Scatter plot | Reuse ScatterChart pattern | BackgroundCard, Chart | `data[]`, `categories` |
+| Progress | `StreamProgress.svelte` | BackgroundCard, Progress | `current`, `total` |
+
+- Use `@skills/create-dashboard` for the page layout
+- Extract upload and session logic into `$lib/api/embeddings.js`
 
 ---
 

package/files/skills/newton-activity-monitor-lens-on-video/SKILL.md

@@ -78,7 +78,7 @@ Decompose the UI into components rather than building a monolithic `+page.svelte
 | Video input | `VideoUpload.svelte` (or reuse VideoPlayer pattern) | Card, Button | `onupload`, `status`, `videoUrl` |
 | Status | `ProcessingStatus.svelte` | Card, Badge, Spinner | `status`, `message` |
 | Summary | `AnalysisSummary.svelte` | Card | `title`, `summary` |
-| Log | Reuse ExpandableLog pattern | Collapsible, Badge, Item | `title`, `logs[]`, `count` |
+| Log | Use FlatLogItem pattern in ScrollArea | FlatLogItem, ScrollArea | `status`, `message`, `detail` |
 
 ### Layout and API logic
 

package/files/skills/newton-camera-frame-analysis/SKILL.md

@@ -9,7 +9,20 @@ allowed-tools: Bash(python *), Read
 
 Capture live webcam frames, encode as base64 JPEG, and send to Newton's vision model via `model.query` (synchronous request/response). Supports Python (OpenCV) and JavaScript (getUserMedia + canvas).
 
-> **Frontend architecture:** When building a web UI for this skill, decompose into components (webcam input, status display, results view) rather than a monolithic page. Extract API logic into `$lib/api/`. See `@rules/frontend-architecture` for conventions and `@skills/create-dashboard` / `@skills/build-pattern` for layout and component patterns.
+## Frontend Architecture
+
+Decompose the UI into components. See `@rules/frontend-architecture` for conventions.
+
+### Recommended decomposition
+
+| UI Area | Component | Pattern/Primitives | Key Props |
+|---------|-----------|-------------------|-----------|
+| Camera feed | `WebcamView.svelte` | Card, AspectRatio | `stream`, `status` |
+| Status | `ConnectionStatus.svelte` | StatusBadge pattern | `status`, `label` |
+| Results | Use FlatLogItem pattern in ScrollArea | FlatLogItem, ScrollArea | `status`, `message`, `detail` |
+
+- Use `@skills/create-dashboard` for the page layout
+- Extract webcam capture and API logic into `$lib/api/camera-analysis.js`
 
 **This skill is for LIVE WEBCAM input only.** For analyzing uploaded video files, use `/activity-monitor-lens-on-video` instead.
 

package/files/skills/newton-direct-query/SKILL.md

@@ -9,6 +9,15 @@ allowed-tools: Bash(python *), Read
 
 Send a text query directly to Newton via `POST /v0.5/query`. No lens registration, no session, no SSE — just a simple request/response. Use for API testing, text Q&A, or post-processing results from other lenses.
 
+## Frontend Architecture
+
+| UI Area | Component | Pattern/Primitives | Key Props |
+|---------|-----------|-------------------|-----------|
+| Query input | `QueryInput.svelte` | BackgroundCard, Input, Button | `onsubmit`, `loading` |
+| Response | `QueryResponse.svelte` | BackgroundCard | `response`, `loading` |
+
+- Use `@skills/create-dashboard` for the page layout
+
 ---
 
 ## API Endpoint

package/files/skills/newton-machine-state-from-file/SKILL.md

@@ -8,7 +8,21 @@ argument-hint: [csv-file-path]
 
 Generate a script that streams time-series data from a CSV file to the Archetype AI Machine State Lens for n-shot state classification. Supports both Python and JavaScript/Web.
 
-> **Frontend architecture:** When building a web UI for this skill, decompose into components (file input, status display, results view) rather than a monolithic page. Extract API/streaming logic into `$lib/api/`. See `@rules/frontend-architecture` for conventions and `@skills/create-dashboard` / `@skills/build-pattern` for layout and component patterns.
+## Frontend Architecture
+
+Decompose the UI into components. See `@rules/frontend-architecture` for conventions.
+
+### Recommended decomposition
+
+| UI Area | Component | Pattern/Primitives | Key Props |
+|---------|-----------|-------------------|-----------|
+| File input | `DataInput.svelte` | BackgroundCard, Button, Input | `onselect`, `status` |
+| Classification | `StateDisplay.svelte` | BackgroundCard, Badge | `currentState`, `confidence` |
+| Time series | Reuse SensorChart pattern | BackgroundCard, Chart | `data[]`, `signals` |
+| Results | Use FlatLogItem pattern in ScrollArea | FlatLogItem, ScrollArea | `status`, `message`, `detail` |
+
+- Use `@skills/create-dashboard` for the page layout
+- Extract streaming and session logic into `$lib/api/machine-state.js`
 
 ---
 

package/files/skills/newton-machine-state-from-sensor/SKILL.md

@@ -8,7 +8,21 @@ argument-hint: [source-type]
 
 Generate a script that streams real-time IMU sensor data to the Archetype AI Machine State Lens for live n-shot state classification. Supports both Python and JavaScript/Web.
 
-> **Frontend architecture:** When building a web UI for this skill, decompose into components (sensor connection, status display, results view) rather than a monolithic page. Extract sensor and API logic into `$lib/api/`. See `@rules/frontend-architecture` for conventions and `@skills/create-dashboard` / `@skills/build-pattern` for layout and component patterns.
+## Frontend Architecture
+
+Decompose the UI into components. See `@rules/frontend-architecture` for conventions.
+
+### Recommended decomposition
+
+| UI Area | Component | Pattern/Primitives | Key Props |
+|---------|-----------|-------------------|-----------|
+| Sensor input | `DataInput.svelte` | BackgroundCard, Button, Input | `onselect`, `status` |
+| Classification | `StateDisplay.svelte` | BackgroundCard, Badge | `currentState`, `confidence` |
+| Time series | Reuse SensorChart pattern | BackgroundCard, Chart | `data[]`, `signals` |
+| Results | Use FlatLogItem pattern in ScrollArea | FlatLogItem, ScrollArea | `status`, `message`, `detail` |
+
+- Use `@skills/create-dashboard` for the page layout
+- Extract streaming and session logic into `$lib/api/machine-state.js`
 
 ---
 

package/files/skills/setup-chart/SKILL.md

@@ -11,7 +11,7 @@ Build charts using layerchart wrapped in the Chart.Container primitive.
 
 Before building, check which components are installed in the project already:
 
-1. List `$lib/components/ui/` to discover available primitives and patterns
+1. List `$lib/components/ui/primitives/` and `$lib/components/ui/patterns/` to discover available primitives and patterns
 2. Only use components that actually exist in the project
 3. Charts require at minimum: `chart`. For card-wrapped charts: `card`, `chart`
 

package/files/skills/setup-chart/references/scatter-chart.md

@@ -75,7 +75,7 @@ The `embedding.csv` contains dimensionality-reduced coordinates. To prepare it f
 
 ```svelte
 <script>
-  import ScatterChart from '$lib/components/ui/ScatterChart.svelte';
+  import ScatterChart from '$lib/components/ui/patterns/scatter-chart/index.js';
   import ScatterChartIcon from '@lucide/svelte/icons/scatter-chart';
   import embeddingCsv from '$lib/data/embedding.csv?raw';
 
@@ -135,7 +135,7 @@ The `embedding.csv` contains dimensionality-reduced coordinates. To prepare it f
 ```svelte
 <script>
   import { onMount, onDestroy } from 'svelte';
-  import ScatterChart from '$lib/components/ui/ScatterChart.svelte';
+  import ScatterChart from '$lib/components/ui/patterns/scatter-chart/index.js';
   import ScatterChartIcon from '@lucide/svelte/icons/scatter-chart';
 
   let streamData = $state([]);
@@ -185,7 +185,7 @@ If the `scatter-chart` pattern is not installed, use `card` + `chart` primitives
 
 ```svelte
 <script>
-  import * as Chart from '$lib/components/ui/chart/index.js';
+  import * as Chart from '$lib/components/ui/primitives/chart/index.js';
   import { ScatterChart } from 'layerchart';
   import { scaleLinear } from 'd3-scale';
 

package/files/skills/setup-chart/references/sensor-chart.md

@@ -38,7 +38,7 @@ This installs `SensorChart.svelte` and its dependencies (`card`, `chart`, `utils
 
 ```svelte
 <script>
-  import SensorChart from '$lib/components/ui/SensorChart.svelte';
+  import SensorChart from '$lib/components/ui/patterns/sensor-chart/index.js';
   import AudioWaveformIcon from '@lucide/svelte/icons/audio-waveform';
   import timeseriesCsv from '$lib/data/timeseries.csv?raw';
 
@@ -86,7 +86,7 @@ For real-time data with a sliding window, use the `maxPoints` prop and feed data
 ```svelte
 <script>
   import { onMount, onDestroy } from 'svelte';
-  import SensorChart from '$lib/components/ui/SensorChart.svelte';
+  import SensorChart from '$lib/components/ui/patterns/sensor-chart/index.js';
   import ThermometerIcon from '@lucide/svelte/icons/thermometer';
 
   let streamingData = $state([]);
@@ -126,7 +126,7 @@ If the `sensor-chart` pattern is not installed, build the equivalent using `card
 
 ```svelte
 <script>
-  import * as Chart from '$lib/components/ui/chart/index.js';
+  import * as Chart from '$lib/components/ui/primitives/chart/index.js';
   import { LineChart } from 'layerchart';
   import { scaleUtc, scaleLinear } from 'd3-scale';
   import { curveNatural } from 'd3-shape';

package/lib/scaffold-ds-svelte-project.js

@@ -256,20 +256,40 @@ export async function installComponents(pm, projectPath, componentUrls) {
   }
 }
 
-// add a demo page with Button examples to app
+// add a demo page with design system examples to app
 export function createDemoPage(projectPath) {
   const pagePath = join(projectPath, 'src/routes/+page.svelte');
   const demoContent = `<script>
-\timport Button from "$lib/components/ui/button/button.svelte";
+\timport Menubar from '$lib/components/ui/patterns/menubar/index.js';
+\timport { Button } from '$lib/components/ui/primitives/button/index.js';
+\timport BackgroundCard from '$lib/components/ui/patterns/background-card/index.js';
+\timport ActivityIcon from '@lucide/svelte/icons/activity';
+\timport CpuIcon from '@lucide/svelte/icons/cpu';
+\timport GaugeIcon from '@lucide/svelte/icons/gauge';
+\timport ThermometerIcon from '@lucide/svelte/icons/thermometer';
 </script>
 
-<div class="flex flex-col items-center justify-center min-h-screen space-y-xl">
-  <Button variant="default">Default</Button>
-  <Button variant="ghost">Ghost</Button>
-  <Button variant="outline">Outline</Button>
-  <Button variant="secondary">Secondary</Button>
-  <Button variant="destructive">Destructive</Button>
-  <Button variant="link">Link</Button>
+<div
+\tclass="bg-background text-foreground grid h-screen w-screen grid-rows-[auto_1fr] overflow-hidden"
+>
+\t<Menubar>
+\t\t<Button variant="link" class="text-muted-foreground">Send Report</Button>
+\t</Menubar>
+
+\t<main class="grid grid-cols-2 grid-rows-2 gap-4 overflow-hidden p-4">
+\t\t<BackgroundCard title="Panel 1" icon={ActivityIcon} class="max-h-full">
+\t\t\t<p class="text-muted-foreground text-sm">Placeholder content</p>
+\t\t</BackgroundCard>
+\t\t<BackgroundCard title="Panel 2" icon={CpuIcon} class="max-h-full">
+\t\t\t<p class="text-muted-foreground text-sm">Placeholder content</p>
+\t\t</BackgroundCard>
+\t\t<BackgroundCard title="Panel 3" icon={GaugeIcon} class="max-h-full">
+\t\t\t<p class="text-muted-foreground text-sm">Placeholder content</p>
+\t\t</BackgroundCard>
+\t\t<BackgroundCard title="Panel 4" icon={ThermometerIcon} class="max-h-full">
+\t\t\t<p class="text-muted-foreground text-sm">Placeholder content</p>
+\t\t</BackgroundCard>
+\t</main>
 </div>
 `;
   writeFile(pagePath, demoContent);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archetypeai/ds-cli",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "description": "Archetype AI Design System CLI Tool",
   "type": "module",
   "bin": {