@archetypeai/ds-cli 0.3.7

package/files/rules/components.md

@@ -0,0 +1,267 @@
+---
+paths:
+  - '**/components/**/*.svelte'
+  - '$lib/**/*.svelte'
+  - '**/primitives/**/*.svelte'
+  - '**/patterns/**/*.svelte'
+---
+
+# Component Authoring Rules
+
+## Props Pattern
+
+Every component should destructure props using `$props()` with this standard pattern:
+
+```svelte
+<script>
+  import { cn } from '$lib/utils.js';
+
+  let { ref = $bindable(null), class: className, children, ...restProps } = $props();
+</script>
+```
+
+Key points:
+
+- `ref = $bindable(null)` - enables parent to bind to DOM element
+- `class: className` - rename to avoid reserved word conflict
+- `children` - snippet for slot content
+- `...restProps` - capture remaining props for spreading
+
+## data-slot Attributes
+
+Add `data-slot` to root elements for identification and styling hooks:
+
+```svelte
+<div bind:this={ref} data-slot="card" class={cn('bg-card ...', className)} {...restProps}>
+  {@render children?.()}
+</div>
+```
+
+This enables parent styling like `*:data-[slot=card]:p-4`.
+
+## Class Merging with cn()
+
+Always use `cn()` for class composition - never raw string concatenation:
+
+```svelte
+<!-- Correct -->
+<div class={cn('bg-card text-card-foreground', className)}>
+
+<!-- Wrong -->
+<div class={`bg-card text-card-foreground ${className}`}>
+```
+
+`cn()` uses clsx + tailwind-merge to properly handle class conflicts.
+
+## bits-ui Wrapper Pattern
+
+When wrapping bits-ui primitives, import the primitive and wrap it:
+
+```svelte
+<script>
+  import { Select as SelectPrimitive } from 'bits-ui';
+  import { cn } from '$lib/utils.js';
+
+  let { ref = $bindable(null), class: className, children, ...restProps } = $props();
+</script>
+
+<SelectPrimitive.Trigger
+  bind:ref
+  data-slot="select-trigger"
+  class={cn('border-input bg-transparent ...', className)}
+  {...restProps}
+>
+  {@render children?.()}
+</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.
+
+## tailwind-variants (tv)
+
+Define variants in `<script module>` for reuse and export:
+
+```svelte
+<script module>
+  import { cn } from '$lib/utils.js';
+  import { tv } from 'tailwind-variants';
+
+  export const buttonVariants = tv({
+    base: 'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors',
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        destructive: 'bg-destructive text-white hover:bg-destructive/90',
+        outline: 'border bg-background hover:bg-accent',
+        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        ghost: 'hover:bg-accent hover:text-accent-foreground',
+        link: 'text-primary underline-offset-4 hover:underline'
+      },
+      size: {
+        default: 'h-9 px-4 py-2',
+        sm: 'h-8 px-3 rounded-md',
+        lg: 'h-10 px-6 rounded-md',
+        icon: 'size-9'
+      }
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default'
+    }
+  });
+</script>
+
+<script>
+  let { variant = 'default', size = 'default', class: className, ...restProps } = $props();
+</script>
+
+<button class={cn(buttonVariants({ variant, size }), className)} {...restProps}>
+  {@render children?.()}
+</button>
+```
+
+## Snippet Slots
+
+Use `{@render}` for slot content:
+
+```svelte
+<!-- Default slot -->
+{@render children?.()}
+
+<!-- Named snippets (passed as props) -->
+{#snippet icon()}
+  <ChevronDown />
+{/snippet}
+
+<Button {icon}>Click me</Button>
+
+<!-- In component, render the snippet prop -->
+{@render icon?.()}
+```
+
+## restProps Spreading
+
+Always spread `...restProps` on the root element to pass through attributes:
+
+```svelte
+<button
+  bind:this={ref}
+  data-slot="button"
+  class={cn(buttonVariants({ variant, size }), className)}
+  {type}
+  {disabled}
+  {...restProps}
+>
+  {@render children?.()}
+</button>
+```
+
+## Conditional Rendering
+
+Use standard Svelte `{#if}` blocks for conditional content:
+
+```svelte
+{#if href}
+  <a bind:this={ref} data-slot="button" {href} {...restProps}>
+    {@render children?.()}
+  </a>
+{:else}
+  <button bind:this={ref} data-slot="button" {...restProps}>
+    {@render children?.()}
+  </button>
+{/if}
+```
+
+## Icon Handling
+
+Icons from Lucide use consistent sizing classes:
+
+```svelte
+<script>
+  import ChevronDownIcon from '@lucide/svelte/icons/chevron-down';
+</script>
+
+<ChevronDownIcon class="size-4 opacity-50" />
+```
+
+Default icon sizing in buttons: `[&_svg:not([class*='size-'])]:size-4`
+
+## Example: Complete Card Component
+
+```svelte
+<script>
+  import { cn } from '$lib/utils.js';
+
+  let { ref = $bindable(null), class: className, children, ...restProps } = $props();
+</script>
+
+<div
+  bind:this={ref}
+  data-slot="card"
+  class={cn(
+    'bg-card text-card-foreground flex flex-col gap-6 rounded-md border py-6 shadow-sm',
+    className
+  )}
+  {...restProps}
+>
+  {@render children?.()}
+</div>
+```
+
+## Example: Dialog Content with bits-ui
+
+```svelte
+<script>
+  import { Dialog as DialogPrimitive } from 'bits-ui';
+  import DialogPortal from './dialog-portal.svelte';
+  import XIcon from '@lucide/svelte/icons/x';
+  import * as Dialog from './index.js';
+  import { cn } from '$lib/utils.js';
+
+  let {
+    ref = $bindable(null),
+    class: className,
+    portalProps,
+    children,
+    showCloseButton = true,
+    ...restProps
+  } = $props();
+</script>
+
+<DialogPortal {...portalProps}>
+  <Dialog.Overlay />
+  <DialogPrimitive.Content
+    bind:ref
+    data-slot="dialog-content"
+    class={cn(
+      'bg-background fixed top-[50%] left-[50%] z-50 w-full max-w-lg translate-x-[-50%] translate-y-[-50%] rounded-lg border p-6 shadow-lg',
+      'data-[state=open]:animate-in data-[state=closed]:animate-out',
+      className
+    )}
+    {...restProps}
+  >
+    {@render children?.()}
+    {#if showCloseButton}
+      <DialogPrimitive.Close class="absolute end-4 top-4 rounded-xs opacity-70 hover:opacity-100">
+        <XIcon />
+        <span class="sr-only">Close</span>
+      </DialogPrimitive.Close>
+    {/if}
+  </DialogPrimitive.Content>
+</DialogPortal>
+```

package/files/rules/design-principles.md

@@ -0,0 +1,56 @@
+# Physical AI Design Principles
+
+## Scope
+
+This design system targets the **Measure** and **Reason** layers of the Physical AI stack. Interfaces built with it should support **augmentation** (helping humans perceive the physical world) and **dialogue** (helping humans reason about it). Operation and cooperation — where AI takes action in the world — are out of scope currently but will become relevant in the future.
+
+## The Physical AI Stack
+
+Physical AI capabilities form a dependency stack where each layer builds on the one below:
+
+1. **Interpret** — Make the physical world legible by surfacing signals, anomalies, and structures from sensor data
+2. **Reason** — Enable shared reasoning between humans and AI: explore hypotheses, compare alternatives, support decisions
+3. **Operate** — Delegated action: human sets intent, system executes within defined boundaries (future scope)
+4. **Co-operate** — Joint action: shared agency through mutual adjustment between humans and AI (future scope)
+
+## Agency
+
+### Human Agency Comes First
+
+At the Measure layer, the AI augments human perception — it surfaces what would otherwise remain invisible. The human retains full responsibility to interpret and act. Interfaces should present information without prescribing conclusions.
+
+At the Reason layer, interaction is dialogic. The AI contributes explanations and comparisons, but the human drives inquiry and judgment. Interfaces should enable exploration, not deliver verdicts.
+
+At the Operate layer, humans shift from direct control to goal-setting and supervision. The AI executes within defined boundaries, and responsibility becomes distributed. Interfaces should make intent, constraints, and system behavior transparent.
+
+At the Co-operate layer, humans and AI act as coordinated participants. Action is jointly negotiated, and intent, context, and responsibility are shared and continuously adjusted. Interfaces should support mutual awareness and fluid handoffs.
+
+### Interaction Is Situated
+
+Interaction unfolds within a three-way relationship: **person, system, and physical world**. Meaning arises from how sensor data, context, and human intent come together in a specific place and moment. Interfaces must maintain this connection to the physical context being observed — sensor sources, locations, time ranges, environmental conditions. Do not abstract away the situational grounding.
+
+## Design Implications
+
+### Make the World Legible
+
+- Prioritize data clarity: visualizations should reveal structure in sensor data — trends, anomalies, distributions, correlations
+- Use semantic tokens (e.g. `text-atai-good`, `text-atai-warning`, `text-atai-critical`) to communicate meaningful states, not for decorative emphasis
+- Design for continuous monitoring: prefer dashboards and live views over static reports
+
+### Support Dialogue, Not Monologue
+
+- Provide entry points for inquiry: interfaces should invite questions, comparisons, and hypothesis exploration
+- Frame AI output as contribution, not conclusion — use language and layout that position AI reasoning as input to human judgment
+- Enable iterative refinement: conversational flows, follow-up exploration, adjustable parameters
+
+### Preserve Physical Context
+
+- Show provenance: which sensors, what time range, what conditions produced the data being displayed
+- Ground abstract representations in physical reality — link charts to sensor locations, timestamps to real events
+- Consider operational environments: interfaces may be used in the field, not only at a desk
+
+### Respect the Stack Boundary
+
+- 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

package/files/rules/linting.md

@@ -0,0 +1,31 @@
+# Linting & Formatting
+
+## Commands
+
+| Command                | Description                      |
+| ---------------------- | -------------------------------- |
+| `npm run lint`         | Check for linting errors         |
+| `npm run lint:fix`     | Auto-fix linting errors          |
+| `npm run format`       | Format all files with Prettier   |
+| `npm run format:check` | Check formatting without changes |
+
+## Stack
+
+- **ESLint** - Flat config (v9+) with `eslint-plugin-svelte`
+- **Prettier** - Code formatting
+- **prettier-plugin-svelte** - Svelte file formatting
+- **prettier-plugin-tailwindcss** - Auto-sorts Tailwind classes
+
+## Workflow
+
+Run linting and formatting before committing:
+
+```bash
+npm run lint:fix && npm run format
+```
+
+Or check without auto-fixing:
+
+```bash
+npm run lint && npm run format:check
+```