@archetypeai/ds-cli 0.12.1 → 0.14.0

package/files/AGENTS.md

@@ -70,6 +70,10 @@ Use semantic tokens for anything themed; standard Tailwind for layout.
 - Spacing scale: `xs sm md lg xl` work as `p-lg`, `gap-md`, `space-y-xl`, `mb-sm`
 - Chart series colors: `var(--chart-1)` … `var(--chart-5)`
 - Radius on interactive elements: `rounded-interactive`
+- Scrollbars are owned by the theme (`--scrollbar`, `--scrollbar-track`,
+  `--scrollbar-width`). Every `overflow-*` container is already on-brand in both
+  themes — write no scrollbar CSS at all. `bg-scrollbar` exists for a
+  custom-rendered thumb
 
 Standard Tailwind is fine for spacing/sizing (`p-4`, `w-full`, `gap-2`) and
 layout (`flex`, `grid`, `absolute`). Status colors communicate state — never
@@ -169,4 +173,8 @@ Compose project-specific components from package primitives in
   `sideBarSelection`, `lensTray*`, `backToDashboard`) exist in the package
   types but are internal to the Archetype AI console product — never use them
 - Keep the `@source` directives and the CSS import order exactly as above
+- Never style scrollbars in app code — no `::-webkit-scrollbar` rules, no
+  `scrollbar-color`/`scrollbar-width`. The theme sets both, and setting
+  `scrollbar-*` locally also silently disables the webkit pseudo-elements on
+  that element
 - `layerchart` stays pinned exactly

package/files/CLAUDE.md

@@ -70,6 +70,10 @@ Use semantic tokens for anything themed; standard Tailwind for layout.
 - Spacing scale: `xs sm md lg xl` work as `p-lg`, `gap-md`, `space-y-xl`, `mb-sm`
 - Chart series colors: `var(--chart-1)` … `var(--chart-5)`
 - Radius on interactive elements: `rounded-interactive`
+- Scrollbars are owned by the theme (`--scrollbar`, `--scrollbar-track`,
+  `--scrollbar-width`). Every `overflow-*` container is already on-brand in both
+  themes — write no scrollbar CSS at all. `bg-scrollbar` exists for a
+  custom-rendered thumb
 
 Standard Tailwind is fine for spacing/sizing (`p-4`, `w-full`, `gap-2`) and
 layout (`flex`, `grid`, `absolute`). Status colors communicate state — never
@@ -169,4 +173,8 @@ Compose project-specific components from package primitives in
   `sideBarSelection`, `lensTray*`, `backToDashboard`) exist in the package
   types but are internal to the Archetype AI console product — never use them
 - Keep the `@source` directives and the CSS import order exactly as above
+- Never style scrollbars in app code — no `::-webkit-scrollbar` rules, no
+  `scrollbar-color`/`scrollbar-width`. The theme sets both, and setting
+  `scrollbar-*` locally also silently disables the webkit pseudo-elements on
+  that element
 - `layerchart` stays pinned exactly

package/files/ds-manifest.json

@@ -1,6 +1,6 @@
 {
 	"name": "archetypeai-design-system",
-	"version": "0.12.1",
+	"version": "0.14.0",
 	"components": [
 		{
 			"name": "alert",
@@ -38,6 +38,39 @@
 				"`<AspectRatio ratio={16 / 9}>` wrapping an image, video, or bg-muted placeholder."
 			]
 		},
+		{
+			"name": "avatar",
+			"import": "@archetypeai/ds-ui-svelte-console/primitives/avatar",
+			"source": "https://design-system-console.archetypeai.workers.dev/r/avatar.json",
+			"description": "User or entity avatar with an image and an initials fallback.",
+			"usage": [
+				"Always compose Root + Fallback: `Avatar.Root` on its own renders an empty circle. The fallback is what shows while the image loads, when there is no `src`, and when the image 404s — so initials (`{user.name.split(' ').map((p) => p[0]).join('')}`) belong there even when you expect a photo.",
+				"Image: `Avatar.Image src={user.avatarUrl} alt={user.name}` — it is a real `<img>`, so `alt` is yours to pass and a missing one is an accessibility violation. Use the person's name, not \"avatar\".",
+				"Size: `sm` (28px) for dense chrome like the side-nav profile row, `default` (36px) for lists and headers, `lg` (48px) for a profile or detail header. The size lands on `data-size` and the fallback's type scales off it through `group-data-[size=…]/avatar`, so overriding the root's `size-*` by hand desynchronises the two — add a size variant instead.",
+				"Shape: `circle` for people, `squircle` (12px radius at every size) for non-human entities (an org, a workspace, a model) so the two read apart at a glance. The radius is deliberately generous — at `sm` the squircle sits close to a circle, which is the intended look.",
+				"Skipping the loading flash: pass `loadingStatus=\"loaded\"` when the image is already cached or inlined, which shows it immediately instead of flashing the fallback. It is bindable, so `bind:loadingStatus` also reads the outcome (`loading` | `loaded` | `error`) if the caller needs to react to a broken image.",
+				"Stacking (“who is on this session”): a `flex -space-x-2` row plus `*:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background *:data-[slot=avatar]:border-0` on the container. The ring is what cuts each avatar out of the one behind it, and it hangs off `data-slot`, so separation stays a container concern rather than a prop. Drop the border in a stack: the root's `border-border` sits just inside the ring, so leaving it on renders a grey rim against a white gap against the next rim, and the overlap reads muddy. Stack images, not initials — the overlap covers each avatar's trailing edge, which a face survives and two letters do not."
+			],
+			"variants": {
+				"avatarVariants": {
+					"axes": {
+						"size": [
+							"sm",
+							"default",
+							"lg"
+						],
+						"shape": [
+							"circle",
+							"squircle"
+						]
+					},
+					"defaults": {
+						"size": "default",
+						"shape": "circle"
+					}
+				}
+			}
+		},
 		{
 			"name": "badge",
 			"import": "@archetypeai/ds-ui-svelte-console/primitives/badge",
@@ -46,7 +79,8 @@
 			"usage": [
 				"Status: `variant=\"status\"` colored via status tokens, e.g. class=\"text-atai-good border-atai-good\" (Completed), atai-critical (Failed), atai-warning (Interrupted), atai-neutral (Running), muted-foreground (Pending).",
 				"Size: `size=\"sm\"` gives the status pill smaller type and tighter spacing for tight spaces (cards, tables) or inline with text; defaults to `size=\"default\"`.",
-				"Selection: `variant=\"selection\"` for dismissible picks, with an embedded `Button variant=\"ghost\" size=\"inline\" visibility=\"dimmed\"` X icon to remove."
+				"Selection: `variant=\"selection\"` for dismissible picks, with an embedded `Button variant=\"ghost\" size=\"inline\" visibility=\"dimmed\"` X icon to remove.",
+				"Spacing: the badge carries no outer margin — the container owns the gap (e.g. `flex gap-2`). For the rare trailing-edge case, add `class=\"-mr-1\"` at the call site."
 			],
 			"variants": {
 				"badgeVariants": {
@@ -154,6 +188,7 @@
 			"usage": [
 				"Detail panel: `variant=\"info\"` + Card.Header (Card.Title + Card.Action icon) + Card.Content layout=\"stack\" holding Label sectionHeader → mono value pairs (Job Details, dialog notes).",
 				"Grid tile: `variant=\"status\"` for clickable job/model status cards in dashboard grids (pass href); `variant=\"intro\"` for hero/landing cards.",
+				"Card.Title capitalizes by default. Pass `titleCase={false}` when the title is user-authored and must render verbatim (agent names, filenames) — never reach in with `[&_[data-slot=card-title]]:normal-case`.",
 				"Single-metric status cards often need no CardHeader — omit when content is self-explanatory."
 			],
 			"variants": {
@@ -164,10 +199,15 @@
 							"intro",
 							"status",
 							"info"
+						],
+						"titleCase": [
+							"true",
+							"false"
 						]
 					},
 					"defaults": {
-						"variant": "default"
+						"variant": "default",
+						"titleCase": "true"
 					}
 				},
 				"cardContentVariants": {
@@ -243,6 +283,49 @@
 			"source": "https://design-system-console.archetypeai.workers.dev/r/console-utils.json",
 			"description": "className merge helper cn() (clsx + tailwind-merge with the rounded-interactive extension). Re-exported as $lib/utils in scaffolded apps."
 		},
+		{
+			"name": "copy-button",
+			"import": "@archetypeai/ds-ui-svelte-console/primitives/copy-button",
+			"source": "https://design-system-console.archetypeai.workers.dev/r/copy-button.json",
+			"description": "Copy-to-clipboard control that owns its own copied state.",
+			"usage": [
+				"Icon beside a value: `CopyButton value={job.id} label=\"Copy job ID\" title={job.id}` — `label` is the accessible name, so say what is being copied rather than \"Copy\", and pass the full value as `title` whenever the visible text is truncated.",
+				"Value inside the control: pass the value as children (`<CopyButton value={id} label=\"Copy blueprint ID\">{id}</CopyButton>`) and the whole thing becomes one copy target with one hover, instead of a 16px icon beside plain text. The hit area follows automatically — children give the `inline` size, icon-only gives the 36px `icon` size.",
+				"Feedback: a check mark replaces the glyph for 1500ms (`feedbackDuration`) and a toast fires on both success and failure, so a mounted `<Toaster />` is a prerequisite. Pass `toast={false}` where the inline check is feedback enough — a table of IDs, where a toast per copy is noise — and the component announces the copy to screen readers itself instead. `successMessage` / `errorMessage` override the wording; `onCopy(copied)` hooks anything else.",
+				"Inside a row that navigates: `stopPropagation` keeps the click off the row's own handler (and off an enclosing anchor). Reveal-on-hover is the Button axis, `visibility=\"hover\"`, which needs `group` on the row — but not when the value is inside the control, since it would fade the value too.",
+				"Copying without a button: `copyText(text)` is exported from the same subpath for a labelled action that happens to copy (a \"Copy CSV\" button in a dialog footer). It resolves to whether the write landed."
+			]
+		},
+		{
+			"name": "counter",
+			"import": "@archetypeai/ds-ui-svelte-console/primitives/counter",
+			"source": "https://design-system-console.archetypeai.workers.dev/r/counter.json",
+			"description": "Odometer pill for a numeric count.",
+			"usage": [
+				"Count: `Counter value={412}` rolls only the digit places that changed; past 999 it abbreviates (`1.2K`, `123K`, `1.2M`) so it never grows a fifth column, and the exact number stays in its title + accessible label.",
+				"Absent vs zero vs loading: omit the component entirely when there is no count, pass `value={0}` for an empty one, and `value={null}` while it is still loading (reserves the same width so nothing reflows when it arrives).",
+				"At least, for a list you cannot size: `Counter value={103} atLeast` renders `103+` when the caller has loaded 103 rows and knows only that more exist (keyset pagination, a capped query). The number is the caller's own, not a rounded threshold, and the accessible label reads \"at least 103\". Past 999 the abbreviation truncates instead of rounding, so `1250` shows `1.2K+` and never claims rows nobody loaded. `atLeast` is ignored on `value={0}`, where it would state nothing.",
+				"Tone & size: `tone=\"muted\"` for a quieter pill against busy chrome; `size=\"sm\"` for dense rows (tables, list items). Inside a tab strip use `Tabs.Count`, which re-colors it for the active/inactive trigger."
+			],
+			"variants": {
+				"counterVariants": {
+					"axes": {
+						"tone": [
+							"solid",
+							"muted"
+						],
+						"size": [
+							"default",
+							"sm"
+						]
+					},
+					"defaults": {
+						"tone": "solid",
+						"size": "default"
+					}
+				}
+			}
+		},
 		{
 			"name": "dialog",
 			"import": "@archetypeai/ds-ui-svelte-console/primitives/dialog",
@@ -905,7 +988,8 @@
 			"description": "Data table.",
 			"usage": [
 				"Log/event tables: width-classed Table.Head columns, `Table.Body class=\"font-sans text-xs\"`, level cells colored with status tokens (text-atai-critical for error rows).",
-				"Mono body (`typography=\"mono\"` on Table.Body) for id-heavy tables; pair with `EmptyState variant=\"list\"` when empty."
+				"Mono body (`typography=\"mono\"` on Table.Body) for id-heavy tables; pair with `EmptyState variant=\"list\"` when empty.",
+				"Header rows never take the data-row hover — `Table.Header` neutralizes it; don't cancel `hover:bg-*` from consumer code."
 			],
 			"variants": {
 				"tableBodyVariants": {
@@ -929,7 +1013,9 @@
 			"usage": [
 				"Icon view toggle (list/grid): `Tabs.List variant=\"toggle\"` + `Tabs.Trigger variant=\"icon\"` with an icon + title.",
 				"Segmented source switch (Library | File IDs | Upload): `variant=\"toggle\"` list + triggers `size=\"pill\" typography=\"mono\"`.",
-				"Page-section tabs (Progress | Logs | Artifacts): `Tabs.List variant=\"line\"` with plain text triggers; always `Tabs.Root bind:value`."
+				"Page-section tabs (Progress | Logs | Artifacts): `Tabs.List variant=\"line\"` with plain text triggers; always `Tabs.Root bind:value`.",
+				"Count on a trigger: `<Tabs.Trigger value=\"logs\">Logs <Tabs.Count value={logCount} /></Tabs.Trigger>` — an odometer pill that abbreviates past 999 (`1.2K`) so the strip never reflows. Pass `value={null}` while the count is still loading (it reserves the width), `value={0}` for an empty tab, and omit `Tabs.Count` entirely for a tab that has no count at all.",
+				"Count on a tab that cannot be sized: `<Tabs.Count value={loaded} atLeast />` renders `103+` for a keyset-paginated tab that knows only how many rows it has so far. Prefer it over dropping the count entirely, which reads as \"none\"."
 			],
 			"variants": {
 				"tabsListVariants": {

package/package.json

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