@archetypeai/ds-ui-svelte-console

Console primitives of the Archetype AI design system. Svelte 5 primitives built on bits-ui, styled with Tailwind v4 and tailwind-variants, and wired to the @archetypeai/ds-lib-tokens theme. TypeScript source ships as .svelte files (no precompilation) so consumers get full type-checking and IDE go-to-definition.

Install

npm i @archetypeai/ds-ui-svelte-console

Then install all peer dependencies:

npm i svelte tailwindcss bits-ui tailwind-variants tailwind-merge clsx @lucide/svelte @archetypeai/ds-lib-tokens mode-watcher svelte-sonner shiki yaml @cfworker/json-schema

Tailwind v4 setup (mandatory)

Tailwind v4 does not scan node_modules by default. Without the @source directive below, every class in this package is purged at consumer build time and components render unstyled — this is the single most common silent failure.

In your consumer's app.css, in this order:

@import 'tailwindcss';
@import '@archetypeai/ds-lib-tokens/theme.css';
@source "../node_modules/@archetypeai/ds-ui-svelte-console/dist";

Order matters:

• tailwindcss registers the engine.
• @archetypeai/ds-lib-tokens/theme.css declares the CSS variables that component classes consume (atai-neutral, bg-card, stroke-icon-default, etc.).
• @source makes Tailwind scan this package's .svelte files so utility classes used inside the package are emitted into your consumer bundle.

Adjust the @source path if your app.css lives elsewhere — it must resolve to the package's dist/ directory.

TypeScript setup

In your consumer's tsconfig.json (or jsconfig.json), set:

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

"node16" and "nodenext" also work. Without one of these, the types condition in this package's exports map is bypassed, types fall back to the default JS file, and editor features degrade.

Usage

Each primitive lives at its own subpath. There is no barrel import { Button } from '@archetypeai/ds-ui-svelte-console' — subpaths keep mode-watcher, svelte-sonner, shiki, yaml, and @cfworker/json-schema out of bundles for consumers who never touch the codeblock or sonner primitives.

<script lang="ts">
  import { Button } from '@archetypeai/ds-ui-svelte-console/primitives/button'
  import { Badge } from '@archetypeai/ds-ui-svelte-console/primitives/badge'

  let buttonRef: HTMLButtonElement | null = $state(null)
</script>

<Badge variant="default">Hello</Badge>
<Button bind:ref={buttonRef} variant="primary" size="md">Click me</Button>

Per-primitive subpaths

| Primitive | Import path | |---|---| | Badge | @archetypeai/ds-ui-svelte-console/primitives/badge | | Button | @archetypeai/ds-ui-svelte-console/primitives/button | | Card | @archetypeai/ds-ui-svelte-console/primitives/card | | Checkbox | @archetypeai/ds-ui-svelte-console/primitives/checkbox | | CodeBlock | @archetypeai/ds-ui-svelte-console/primitives/codeblock | | Collapsible | @archetypeai/ds-ui-svelte-console/primitives/collapsible | | Dialog | @archetypeai/ds-ui-svelte-console/primitives/dialog | | DropdownMenu | @archetypeai/ds-ui-svelte-console/primitives/dropdown-menu | | DropZone | @archetypeai/ds-ui-svelte-console/primitives/dropzone | | EmptyState | @archetypeai/ds-ui-svelte-console/primitives/empty-state | | Input | @archetypeai/ds-ui-svelte-console/primitives/input | | InputGroup | @archetypeai/ds-ui-svelte-console/primitives/input-group | | Item | @archetypeai/ds-ui-svelte-console/primitives/item | | Label | @archetypeai/ds-ui-svelte-console/primitives/label | | Select | @archetypeai/ds-ui-svelte-console/primitives/select | | Separator | @archetypeai/ds-ui-svelte-console/primitives/separator | | Sonner | @archetypeai/ds-ui-svelte-console/primitives/sonner | | Spinner | @archetypeai/ds-ui-svelte-console/primitives/spinner | | Table | @archetypeai/ds-ui-svelte-console/primitives/table | | Tabs | @archetypeai/ds-ui-svelte-console/primitives/tabs | | Textarea | @archetypeai/ds-ui-svelte-console/primitives/textarea | | Tooltip | @archetypeai/ds-ui-svelte-console/primitives/tooltip |

The cn() helper and shared TS type helpers (WithElementRef, WithoutChild, WithoutChildren, WithoutChildrenOrChild) are exported from @archetypeai/ds-ui-svelte-console/primitives/utils.

Composition patterns will arrive at @archetypeai/ds-ui-svelte-console/patterns/<name> in a later release without breaking any of the primitive paths above.

API conventions

• bind:ref for element handles. Every primitive exposes ref as a $bindable prop. Use <Button bind:ref={el} /> to capture the underlying DOM element.
• data-* attributes are public API. Every variant slot carries data-slot plus variant attributes (data-variant, data-size, data-state, data-typography, etc.). Use them as descendant-selector hooks. Renaming requires a major version bump.
• Composite primitives compose by sub-part. Card, Dialog, Item, Select, DropdownMenu, Tabs, Collapsible, Tooltip, InputGroup, and DropZone export their sub-parts (e.g. Dialog.Trigger, Dialog.Content). Pass class to each sub-part directly — there is no headerClass/contentClass shorthand on the root.
• child snippet on Item is the bits-ui asChild render-prop pattern, not a typo for children.
• Variant configs are exported. Each index.ts re-exports its tv() configs (e.g. buttonVariants, inputGroupButtonVariants) so consumers can compose variants without forking source.

License

MIT. See LICENSE.