@jovertical/mise-design-system 1.0.0 → 1.1.0

package/README.md

@@ -92,6 +92,26 @@ Import `src/mise-theme.css` in place of `theme.css`. `emitThemeCss(config)`
 is exported from `/tokens` too, if you would rather call it in your own build
 script.
 
+## AI agents
+
+mise ships an agent skill, `skills/mise/`, that teaches a coding agent in your
+app which mise component does which job, every component's props and
+defaults, setup per stack, theming, and worked recipes. Install it with the
+[`skills` CLI](https://github.com/vercel-labs/skills):
+
+```sh
+npx skills add jovertical/mise-design-system --skill mise
+```
+
+The same skill is in the package at
+`node_modules/@jovertical/mise-design-system/skills/mise/`, matching the
+installed version. `npx skills experimental_sync` links it from there, so it
+updates with mise.
+
+The skill reads the app's setup with `npx mise-theme info --json`: the
+installed version, the stack, the theme config and the stylesheet that imports
+mise.
+
 ## Develop
 
 ```sh

package/bin/mise-theme.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
+import { readFile } from 'node:fs/promises'
+
 import { runThemeCli } from '../dist/tokens/cli.js'
 
-const { code, message } = await runThemeCli(process.argv.slice(2))
+const { version } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'))
+const { code, message } = await runThemeCli(process.argv.slice(2), process.cwd(), version)
 
 if (code === 0) console.log(message)
 else console.error(message)

package/dist/tokens/cli.d.ts

@@ -8,4 +8,4 @@ export interface CliResult {
  * `dist/styles/`, so the output matches the packaged stylesheet line for line,
  * apart from the theme.
  */
-export declare function runThemeCli(argv: string[], cwd?: string): Promise<CliResult>;
+export declare function runThemeCli(argv: string[], cwd?: string, version?: string): Promise<CliResult>;

package/dist/tokens/cli.js

@@ -2,7 +2,8 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { themeStylesheet } from './emit-web.js';
-const USAGE = 'Usage: mise-theme <config> -o <output.css>';
+import { projectInfo } from './info.js';
+const USAGE = 'Usage: mise-theme <config> -o <output.css>\n       mise-theme info [--json]';
 /**
  * A path rather than a `new URL(…)`, because a global `URL` that is not
  * Node's (jsdom's, in a test) is rejected by `fs`.
@@ -14,7 +15,9 @@ const COMPONENTS_CSS = join(dirname(fileURLToPath(import.meta.url)), '..', 'styl
  * `dist/styles/`, so the output matches the packaged stylesheet line for line,
  * apart from the theme.
  */
-export async function runThemeCli(argv, cwd = process.cwd()) {
+export async function runThemeCli(argv, cwd = process.cwd(), version = '0.0.0') {
+    if (argv[0] === 'info')
+        return runInfo(argv.includes('--json'), cwd, version);
     const [configPath, flag, outputPath] = argv;
     if (!configPath || flag !== '-o' || !outputPath)
         return { code: 1, message: USAGE };
@@ -35,3 +38,21 @@ export async function runThemeCli(argv, cwd = process.cwd()) {
         return { code: 1, message: error instanceof Error ? error.message : String(error) };
     }
 }
+/**
+ * `mise-theme info`: the facts about the app in `cwd` that the consumer skill
+ * reads before writing UI. `version` is mise's own, passed in by the binary.
+ */
+async function runInfo(json, cwd, version) {
+    try {
+        const info = await projectInfo(cwd, version);
+        const message = json
+            ? JSON.stringify(info, null, 2)
+            : Object.entries(info)
+                .map(([key, value]) => `${key}: ${value ?? '—'}`)
+                .join('\n');
+        return { code: 0, message };
+    }
+    catch (error) {
+        return { code: 1, message: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/tokens/info.d.ts

@@ -0,0 +1,10 @@
+export type ProjectInfo = {
+    version: string;
+    stack: 'sveltekit' | 'inertia' | 'vite';
+    svelte: string | null;
+    tailwind: string | null;
+    themeConfig: string | null;
+    stylesheet: string | null;
+    form: boolean;
+};
+export declare function projectInfo(cwd: string, version: string): Promise<ProjectInfo>;

package/dist/tokens/info.js

@@ -0,0 +1,62 @@
+/**
+ * What an agent needs to know about the app it is working in before it writes
+ * mise UI: which version, which stack, where the theme and the stylesheet are.
+ * Read-only. The consumer skill runs it on load through `mise-theme info --json`.
+ */
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+const THEME_CONFIGS = ['mise.theme.js', 'mise.theme.mjs', 'mise.theme.ts'];
+const SKIPPED = new Set([
+    'node_modules',
+    '.git',
+    'vendor',
+    'dist',
+    'build',
+    '.svelte-kit',
+    'storage',
+    'public',
+]);
+const IMPORT = /@import\s+['"]@jovertical\/mise-design-system\//;
+const MAX_DEPTH = 6;
+async function findStylesheet(cwd, dir = cwd, depth = 0) {
+    if (depth > MAX_DEPTH)
+        return null;
+    const entries = (await readdir(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        if (entry.isFile() &&
+            entry.name.endsWith('.css') &&
+            IMPORT.test(await readFile(path, 'utf8'))) {
+            return relative(cwd, path).split('\\').join('/');
+        }
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || SKIPPED.has(entry.name) || entry.name.startsWith('.'))
+            continue;
+        const found = await findStylesheet(cwd, join(dir, entry.name), depth + 1);
+        if (found)
+            return found;
+    }
+    return null;
+}
+export async function projectInfo(cwd, version) {
+    const manifestPath = join(cwd, 'package.json');
+    if (!existsSync(manifestPath))
+        throw new Error(`No package.json in ${cwd}`);
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    const dependencies = {
+        ...manifest.dependencies,
+        ...manifest.devDependencies,
+    };
+    const has = (name) => name in dependencies;
+    return {
+        version,
+        stack: has('@sveltejs/kit') ? 'sveltekit' : has('@inertiajs/svelte') ? 'inertia' : 'vite',
+        svelte: dependencies.svelte ?? null,
+        tailwind: dependencies.tailwindcss ?? null,
+        themeConfig: THEME_CONFIGS.find((name) => existsSync(join(cwd, name))) ?? null,
+        stylesheet: await findStylesheet(cwd),
+        form: has('formsnap') && has('sveltekit-superforms'),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jovertical/mise-design-system",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Svelte 5 components and a configurable Tailwind v4 theme for operations dashboards",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,7 @@
     "dist",
     "bin",
     "LICENSES",
+    "skills",
     "!dist/**/*.stories.svelte",
     "!dist/**/*.stories.svelte.d.ts",
     "!dist/**/*.test.*"
@@ -113,6 +114,7 @@
   "scripts": {
     "build": "svelte-kit sync && svelte-package && pnpm build:theme && publint",
     "build:theme": "tsx scripts/build-theme.ts",
+    "build:skill": "tsx scripts/build-skill.ts",
     "storybook": "pnpm build:theme && storybook dev -p 6006",
     "build:storybook": "pnpm build:theme && storybook build",
     "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --fail-on-warnings",

package/skills/mise/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: mise
+description: >-
+  Builds Svelte 5 UI in an app that uses @jovertical/mise-design-system: picking the mise
+  component for a job, its props and defaults, theming, and setting mise up. Activates when
+  writing or changing Svelte UI in an app that depends on @jovertical/mise-design-system, or
+  setting mise up in a new app; or when the user mentions mise, the design system, a mise
+  component, tone, variant, or mise-theme.
+---
+
+# mise
+
+mise is a library of Svelte 5 components and a Tailwind v4 theme for operations dashboards:
+locations, shifts, orders, stock. This skill is for an app that depends on it. Before writing
+any UI, find the mise component that does the job; write your own only when none does.
+
+## This app
+
+```json
+!`npx --no-install mise-theme info --json`
+```
+
+`stack` says how the app is wired (`sveltekit`, `inertia` or `vite`), `stylesheet` where mise's
+theme is imported, `themeConfig` whether the app has its own theme, and `form` whether
+`mise/form` can be used. If the command failed, mise is not installed here: follow
+[setup.md](setup.md).
+
+## Which copy to trust
+
+This skill may be newer or older than the mise the app has installed. When they disagree, read
+`node_modules/@jovertical/mise-design-system/skills/mise/` instead: that copy ships with the
+installed `version` above, and its `components/` files list exactly the props that version
+takes.
+
+## Rules
+
+- **Use a mise component before writing UI.** A badge, a card, a table, an empty state or a
+  confirmation dialog almost certainly exists; the index below says which.
+- **Compose before customising.** A card of facts is `Card` with `FactList` in it, not a styled
+  `div`. A dashboard is `PageLayout`, `PageHeader`, `CardGrid` and `StatTile`s.
+- **Props before classes.** Colour is `tone`: `neutral`, `primary`, `info`, `success`,
+  `warning` or `critical` (never `destructive`, `error` or `danger`). Treatment is `variant`.
+  Size is `size`: `sm`, `md` (the default) or `lg`. States are bare adjectives: `loading`,
+  `invalid`, `disabled`.
+- **Semantic colours only.** `bg-primary`, `text-muted-foreground`, `border-border`. Never a
+  palette class (`bg-blue-500`) or a `dark:` colour override: the theme handles dark mode.
+- **`class` is for layout**: margin, width, grid placement. Do not restyle a component's
+  colours, radius or type through `class`; change the theme ([theming.md](theming.md)).
+- **A neutral fill on the page** is `bg-foreground/[0.07]`, the same wash mise's neutral badges
+  use. `bg-muted` is the page canvas, so a `bg-muted` chip disappears on it.
+- **The app formats, mise displays.** Money, dates and statuses are formatted by the app.
+  `NumberInput` with `format="currency"` takes and reports integer cents.
+- **Every component** takes `class` and spreads other attributes onto its root, and every part
+  takes `bind:ref`. Overlays and inputs use `bind:open` and `bind:value`.
+- **For the app's own components**, mise exports `cn` (class merging), the `Tone` and `Size`
+  types, `TONES`, and the tone class maps (`TONE_SOFT_CLASS`, `TONE_SOLID_CLASS`,
+  `TONE_TEXT_CLASS`, `TONE_FILL_CLASS` and the rest), so a custom badge-like element matches
+  mise's colours.
+
+## Which component
+
+Each line is a job and the component that does it. The group files list every part, prop,
+type and default.
+
+**Actions** ([components/actions.md](components/actions.md))
+
+- A button, or a link that looks like one (`href`): `Button`
+- A menu of actions on a row or a page: `DropdownMenu`
+- A searchable list of commands or a palette (`CommandDialog`): `Command`
+- The light and dark switch: `ThemeToggle`, inside a `ThemeProvider`
+
+**Forms** ([components/forms.md](components/forms.md))
+
+- A label, description and error around any input: `Field` (with `Label`)
+- Text: `Input`; several lines: `Textarea`
+- An input with an icon, a prefix or a button inside it: `InputGroup`
+- A number, a price or a count: `NumberInput`, never `Input type="number"`
+- An amount and its unit (2.5 kg): `QuantityInput`
+- One choice from a few: `RadioGroup`; when each choice needs a description or media:
+  `ChoiceRow`
+- One choice from many: `Select`; searchable or several values: `Combobox`
+- On or off: `Switch`; with a label and description in a row: `SwitchField`; a tick:
+  `Checkbox`
+- A date: `DatePicker`; a calendar on the page: `Calendar`; a time: `TimePicker`
+- A one-time code: `InputOTP`
+- An image or file upload: `MediaDropzone`
+- Segmented buttons: `ToggleGroup`; one pressed state: `Toggle`; joined buttons and inputs:
+  `ButtonGroup`
+- A validated form in SvelteKit: `Form`, from `@jovertical/mise-design-system/form`. It needs
+  SvelteKit; in an Inertia or plain Vite app use `Field` with the app's own form state
+  ([recipes/form.md](recipes/form.md))
+
+**Navigation** ([components/navigation.md](components/navigation.md))
+
+- The app's side menu: `Sidebar`
+- Where am I: `Breadcrumb`
+- Sections of one page: `Tabs`
+- The steps of a flow: `Stepper`
+
+**Layout** ([components/layout.md](components/layout.md))
+
+- The page frame: `PageLayout`, with `PageHeader` for the title, description and actions
+- A surface: `Card`
+- Cards in a grid: `CardGrid`; rows inside one card: `CardList`
+- A collapsible card for a side column: `AsideCard`
+- What one step produced, read-only: `SummaryCard`
+- Show and hide a section: `Collapsible`
+- A rule: `Separator`
+
+**Overlays** ([components/overlays.md](components/overlays.md))
+
+- "Are you sure?": `AlertDialog`
+- A task in a modal: `Dialog`; in a side panel: `Sheet`; from the bottom on mobile: `Drawer`
+- A small floating panel: `Popover`; a preview on hover: `HoverCard`
+- A label on hover: `Tooltip`; a `?` that explains the thing beside it: `Hint`
+
+**Feedback** ([components/feedback.md](components/feedback.md))
+
+- A message in the page: `Alert`; a toast: `Toaster` once in the layout, then `toast(…)`
+- Loading: `Spinner` inline, `Skeleton` for the shape of what is coming, `LoadingState` for a
+  whole panel
+- Nothing here yet: `EmptyState`; to compose your own: `Empty` and its parts
+- An error page (not found, forbidden, failed): `ErrorState`
+- Progress: `Progress`; a route change: `NavigationProgress`
+- A feature the user cannot use yet: `FeaturePreview` for a whole page, `LockedOverlay` over
+  one card
+
+**Data display** ([components/data-display.md](components/data-display.md))
+
+- A status or a tag: `Badge`; a change up or down: `DeltaBadge`
+- A person's picture or initials: `Avatar`; a named thing with its mark and one line:
+  `EntityLabel`; a list row with media, text and actions: `Item`
+- An icon in a tinted square: `IconChip`
+- Label and value pairs: `FactList`
+- The headline number of a dashboard: `StatTile`. One figure per tile, with its delta, unit and
+  sparkline
+- One subject and several figures with a bar beneath: `MetricRow`
+- One measure drawn as a bar, in a ranked list: `MetricBar`; sub-groups to compare side by
+  side: `MetricGrid`
+- A share of a whole as a ring: `RadialStat`; as one segmented bar: `SegmentedBar`
+- A trend in a cell or a tile: `Sparkline`; a full chart: `ChartContainer` (LayerChart)
+- Rows of data: `Table`; with sorting, filtering, selection or pagination: `DataTable`
+- A history of events: `Timeline`
+- Setup steps: `Checklist`, and `ChecklistCard` for the summary card; what a page still needs
+  before going live: `ReadinessChecklist`
+- A code read off one screen and typed into another: `SegmentedCode`
+- A row in a nested list: `TreeLeaf`
+
+**Typography** ([components/typography.md](components/typography.md))
+
+- A heading: `Heading`; body text with size, muting and tone: `Text`
+
+## Read next
+
+- [setup.md](setup.md): install mise and wire it into SvelteKit, Laravel with Inertia, or Vite.
+- [theming.md](theming.md): presets, the brand colour, radius, fonts and dark mode.
+- [recipes/dashboard-page.md](recipes/dashboard-page.md): a dashboard page.
+- [recipes/form.md](recipes/form.md): a form, in Inertia and in SvelteKit.
+- [recipes/data-table.md](recipes/data-table.md): a data table with filters and row actions.

package/skills/mise/components/actions.md

@@ -0,0 +1,200 @@
+<!-- Generated by pnpm build:skill. Do not edit by hand. -->
+
+# Actions
+
+## Button
+
+`import { Button, buttonVariants, defaultButtonTone } from '@jovertical/mise-design-system'`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `'solid' \| 'soft' \| 'outline' \| 'ghost' \| 'link'` | `'solid'` |  |
+| `tone` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'critical'` |  | Defaults to `primary` for `solid` and `link`, `neutral` for the rest. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |  |
+| `iconOnly` | `boolean` | `false` | One glyph and no label: square, round, and it needs an `aria-label`. |
+| `children` | `Snippet` |  |  |
+
+Also takes: every `<button>` attribute; every `<a>` attribute.
+
+Also exports: `buttonVariants`, `defaultButtonTone`.
+
+Types: `ButtonSize` (`'sm' | 'md' | 'lg'`), `ButtonVariant` (`'solid' | 'soft' | 'outline' | 'ghost' | 'link'`).
+
+## Command
+
+`import { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut } from '@jovertical/mise-design-system'`
+
+A filterable, keyboard-navigable list, grouped by section: the shape a command palette is built on. Bare for an inline picker; `CommandDialog` puts it in a dialog.
+
+Also takes: bits-ui `Command.Root` props.
+
+### `CommandDialog`
+
+`Command` in a `Dialog`, for a palette that takes over the screen. The title and description are for a screen reader only.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | `'Command palette'` |  |
+| `description` | `string` | `'Search for a command to run.'` |  |
+| `showCloseButton` | `boolean` | `true` |  |
+| `class` | `string` |  |  |
+| `children` (required) | `Snippet` |  |  |
+
+Also takes: bits-ui `Dialog.Root` props except `children`, `child`; bits-ui `Command.Root` props except `children`, `child`.
+
+### `CommandEmpty`
+
+Shown when nothing matches what was typed.
+
+Also takes: bits-ui `Command.Empty` props.
+
+### `CommandGroup`
+
+A section of items, under a small muted heading.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `heading` | `string` |  |  |
+
+Also takes: bits-ui `Command.Group` props.
+
+### `CommandInput`
+
+The search field, with its glyph, ruled off from the list below.
+
+Also takes: bits-ui `Command.Input` props.
+
+### `CommandItem`
+
+One command. The highlighted row takes the muted wash, as a menu row does.
+
+Also takes: bits-ui `Command.Item` props.
+
+### `CommandList`
+
+The scrolling list of groups and items.
+
+Also takes: bits-ui `Command.List` props.
+
+### `CommandSeparator`
+
+A rule between groups.
+
+Also takes: bits-ui `Command.Separator` props.
+
+### `CommandShortcut`
+
+A keyboard shortcut, muted at the end of the item.
+
+Also takes: every `<span>` attribute.
+
+## DropdownMenu
+
+`import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger } from '@jovertical/mise-design-system'`
+
+Also takes: bits-ui `DropdownMenu.Root` props.
+
+### `DropdownMenuCheckboxItem`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `Snippet` |  |  |
+
+Also takes: bits-ui `DropdownMenu.CheckboxItem` props except `children`, `child`.
+
+### `DropdownMenuContent`
+
+`min-w-44` (176px) by default, the width menus kept asking for.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `portalProps` | `DropdownMenuPrimitive.PortalProps` |  |  |
+
+Also takes: bits-ui `DropdownMenu.Content` props.
+
+### `DropdownMenuGroup`
+
+Also takes: bits-ui `DropdownMenu.Group` props.
+
+### `DropdownMenuItem`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `inset` | `boolean` |  |  |
+| `variant` | `'default' \| 'destructive'` | `'default'` | `destructive` for an action that removes or ends something. |
+
+Also takes: bits-ui `DropdownMenu.Item` props.
+
+### `DropdownMenuLabel`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `inset` | `boolean` |  |  |
+
+Also takes: every `<div>` attribute.
+
+### `DropdownMenuPortal`
+
+Also takes: bits-ui `DropdownMenu.Portal` props.
+
+### `DropdownMenuRadioGroup`
+
+Also takes: bits-ui `DropdownMenu.RadioGroup` props.
+
+### `DropdownMenuRadioItem`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `Snippet` |  |  |
+
+Also takes: bits-ui `DropdownMenu.RadioItem` props except `children`, `child`.
+
+### `DropdownMenuSeparator`
+
+Also takes: bits-ui `DropdownMenu.Separator` props.
+
+### `DropdownMenuShortcut`
+
+Also takes: every `<span>` attribute.
+
+### `DropdownMenuSub`
+
+Also takes: bits-ui `DropdownMenu.Sub` props.
+
+### `DropdownMenuSubContent`
+
+Also takes: bits-ui `DropdownMenu.SubContent` props.
+
+### `DropdownMenuSubTrigger`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `inset` | `boolean` |  |  |
+
+Also takes: bits-ui `DropdownMenu.SubTrigger` props.
+
+### `DropdownMenuTrigger`
+
+Also takes: bits-ui `DropdownMenu.Trigger` props.
+
+## ThemeToggle
+
+`import { ThemeProvider, ThemeToggle, ThemeState, useTheme } from '@jovertical/mise-design-system'`
+
+Icon-only toggle between light and dark, inside a `ThemeProvider`.
+
+Also takes: everything `Button` takes except `children`, `onclick`.
+
+### `ThemeProvider`
+
+Applies a `light` / `dark` class to `<html>` and persists the choice. The class on the root is what Tailwind's `dark:` variant reads, so this touches the DOM directly rather than passing a value down alone.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `defaultTheme` | `'dark' \| 'light' \| 'system'` | `'system'` |  |
+| `storageKey` | `string` | `'vite-ui-theme'` | localStorage key. Distinct per app, so two apps on one host do not share a theme. |
+| `children` (required) | `Snippet` |  |  |
+
+Also exports: `ThemeState`, `useTheme`.
+
+Types: `Theme` (`'dark' | 'light' | 'system'`).