@misoto22/design 0.6.1 → 0.8.0

package/llms.txt

@@ -0,0 +1,35 @@
+# @misoto22/design
+
+> A monochrome design system for software, writing and photography: portable CSS
+> tokens and accessible React 19 primitives, charts and diagrams. Components ship
+> compiled — import them, do not copy them.
+
+This file is a stub on purpose. It carries no prop tables and no version, so it
+cannot go stale between releases; everything it points at is generated from the
+source in this same tarball at build time.
+
+## In this package, offline
+
+- [dist/agent/index.md](./dist/agent/index.md): every component, one line each, plus the theme axes read out of the stylesheets.
+- [dist/agent/<Component>.md](./dist/agent/): one component in full — every prop with its type and default, the exported unions, the keyboard contract, the accessibility promises, the examples.
+- [skills/misoto22-design/SKILL.md](./skills/misoto22-design/SKILL.md): the conventions an agent gets wrong from habit — the names that diverge from shadcn/ui, and colour that is never a raw class.
+- [AGENTS.md](./AGENTS.md): the short version of this, plus what to know when working on the package itself.
+
+Prefer the CLI over reading these by path — it resolves parts and types, not
+just components:
+
+```bash
+npx misoto22-design docs Button
+npx misoto22-design docs --installed
+```
+
+## On the web
+
+- [https://ui.misoto22.com/llms.txt](https://ui.misoto22.com/llms.txt): the site's index.
+- [https://ui.misoto22.com/llms-full.txt](https://ui.misoto22.com/llms-full.txt): every component inline, in one file.
+- [https://ui.misoto22.com](https://ui.misoto22.com): the rendered documentation.
+
+## Optional
+
+- [README.md](./README.md): install, theming, and the same three commands for a human reader.
+- [CHANGELOG.md](./CHANGELOG.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misoto22/design",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "private": false,
   "description": "Monochrome design system — CSS tokens and accessible React primitives",
   "license": "MIT",
@@ -13,6 +13,9 @@
     "dist",
     "skills",
     "bin",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "llms.txt",
     "LICENSE",
     "README.md"
   ],
@@ -28,6 +31,10 @@
       "types": "./dist/charts/index.d.ts",
       "import": "./dist/charts/index.js"
     },
+    "./diagrams": {
+      "types": "./dist/diagrams/index.d.ts",
+      "import": "./dist/diagrams/index.js"
+    },
     "./styles.css": "./dist/styles.css",
     "./tokens.css": "./dist/tokens.css",
     "./semantic.css": "./dist/semantic.css",
@@ -139,7 +146,7 @@
   },
   "scripts": {
     "build:fonts": "node scripts/vendor-fonts.mjs",
-    "build:js": "NODE_OPTIONS=--max-old-space-size=6144 tsup",
+    "build:js": "NODE_OPTIONS=--max-old-space-size=8192 tsup",
     "build:css": "tailwindcss -i ./src/styles/index.css -o ./dist/styles.css --minify && node scripts/copy-portable-css.mjs && node scripts/emit-tokens.mjs",
     "build:agent": "node scripts/emit-agent.mjs",
     "build": "pnpm run build:fonts && pnpm run build:js && pnpm run build:css && pnpm run build:agent",

package/skills/misoto22-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: misoto22-design
-description: Builds UI with @misoto22/design — a monochrome design system of CSS tokens and 72 accessible React primitives, charts included. Use when a project imports '@misoto22/design' or '@misoto22/design/charts', sets data-mode / data-surface / data-radius / data-density, or uses cn(), CONTROL_BASE, or isInvalid. Also applies when adding a component, theming, plotting data, or fixing a form, table, dialog, or toast in such a project.
+description: Builds UI with @misoto22/design — a monochrome design system of CSS tokens and 83 accessible React primitives, charts and diagrams included. Use when a project imports '@misoto22/design', '@misoto22/design/charts' or '@misoto22/design/diagrams', sets data-mode / data-surface / data-radius / data-density, or uses cn(), CONTROL_BASE, or isInvalid. Also applies when adding a component, theming, plotting data, drawing an architecture, workflow, sequence, data-flow or lifecycle diagram, or fixing a form, table, dialog, or toast in such a project.
 allowed-tools: Bash(npx misoto22-design *), Bash(pnpm exec misoto22-design *), Bash(bunx misoto22-design *)
 ---
 
@@ -14,16 +14,19 @@ import { Button, Field, Input } from '@misoto22/design'
 import '@misoto22/design/styles.css'
 ```
 
-## Two entry points
+## Three entry points
 
-The root entry has no dependencies a consumer has to install. Everything that
-plots data lives behind a second specifier, because it needs a rendering engine
-and an animation runtime that nothing else in the package does:
+The root entry has no dependencies a consumer has to install. Two groups live
+behind their own specifier instead, each for weight the root should not carry:
 
 ```tsx
 import { AreaChart, BarList, BigNumber } from '@misoto22/design/charts'
+import { ArchitectureFigure, DiagramCanvas } from '@misoto22/design/diagrams'
 ```
 
+Charts need a rendering engine and an animation runtime that nothing else in
+the package does:
+
 ```bash
 pnpm add recharts motion      # optional peers, only for the charts entry
 ```
@@ -39,6 +42,16 @@ Some of the charts need no engine at all — `Heatmap` is a `<table>`,
 HTML — but they ship from the charts entry all the same, so the boundary stays
 one line rather than a list to memorise.
 
+Diagrams need no peer at all; they carry an orthogonal routing engine instead,
+which has no business in a bundle that renders a Badge. Reach for that entry
+when the task is to DRAW a system rather than to build a screen:
+`ArchitectureFigure` for what talks to what, `WorkflowFigure` for a process in
+lanes, `SequenceFigure` for a call chain over time, `DataflowFigure` for a
+pipeline, `LifecycleFigure` for a state machine. Each takes a typed JSON
+specification and renders on a server. `Diagram` is a different thing and stays
+on the root: a nesting CSS diagram for an article, not an SVG figure with
+routed edges.
+
 One more, for surfaces that cannot read a custom property — an OpenGraph card, a
 `theme-color`, a canvas:
 
@@ -66,8 +79,9 @@ npx misoto22-design docs Button
 
 Run that before writing against a component you have not used in this session.
 The median component is ~500 tokens and the largest is ~1,300, against far more
-for all seventy-two. It is generated from the installed source, so it cannot be
-out of date the way the website can.
+for all eighty-three. It is generated from the installed source, so it cannot be
+out of date the way the website can — and each file names the specifier it
+ships from on its `Import:` line, which is the half that matters below.
 
 It also resolves parts and types, not just components: `docs CardBody`,
 `docs TH` and `docs ButtonVariant` all land on the right file. When an import

package/skills/misoto22-design/evals/evals.json

@@ -0,0 +1,84 @@
+{
+  "$comment": "Prompts a real agent runs against this skill, and what its output has to show. This is the half `claims.json` cannot reach: that file proves the rules match the package, which is necessary and does not prove an agent given the rules writes correct code. Each `must_use` identifier is checked for existence by `skill.test.ts`, so an eval cannot quietly start expecting something the package no longer exports.",
+  "skill_name": "misoto22-design",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Using @misoto22/design, build a settings form with fields for full name and email address, and show a validation error under email when it is invalid.",
+      "expected_output": "A React component using one Field per control, the error prop rather than a red border, and gap-* on the form.",
+      "must_use": ["Field", "Input", "Button"],
+      "must_not_contain": ["space-y-", "border-red", "text-red-", "<label", "aria-describedby="],
+      "expectations": [
+        "Wraps each control in its own Field with a label, not a hand-rolled <label> plus input plus error div",
+        "Puts the validation message in Field's error prop, which sets aria-invalid on the control for it",
+        "Does not also pass invalid on the Input inside a Field with an error — that is redundant",
+        "Never a wrapper div between Field and its control, which would wire the div instead",
+        "Lays the form out with flex and gap-*, not space-y-*"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Using @misoto22/design, add a confirmation dialog for deleting a project. It needs a heading, an explanation, and Cancel and Delete buttons.",
+      "expected_output": "A Dialog whose title and description are props on DialogContent, with a danger-variant Delete button.",
+      "must_use": ["Dialog", "DialogTrigger", "DialogContent", "Button"],
+      "must_not_contain": ["DialogTitle", "DialogHeader", "DialogDescription", "DialogFooter"],
+      "expectations": [
+        "Passes title and description as props on DialogContent — there is no DialogTitle or DialogHeader export here",
+        "Uses variant=\"danger\" for the destructive action",
+        "Wraps the trigger with asChild rather than nesting a button inside a button",
+        "Sets no z-index: the overlay handles its own stacking"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Using @misoto22/design, render a table of open invoices with client, due date and amount, with the amount column right-aligned.",
+      "expected_output": "A Table with a real caption and the short part names, amount aligned with the align prop.",
+      "must_use": ["Table", "THead", "TBody", "TR", "TH", "TD"],
+      "must_not_contain": ["TableHeader", "TableBody", "TableRow", "TableHead", "TableCell", "text-right"],
+      "expectations": [
+        "Uses THead / TBody / TR / TH / TD — the shadcn/ui names are not exported here",
+        "Gives caption a real sentence saying what the table lists, not an empty string and not the word \"Table\"",
+        "Right-aligns with align=\"end\" on TH and TD, not a text-right class, so the table stays RTL-correct"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "Using @misoto22/design, build a dashboard row of four stat cards. Each shows a title, a big number, a change badge, and a loading state.",
+      "expected_output": "Full Card composition, Skeleton for loading, Badge for the change, semantic tokens throughout.",
+      "must_use": ["Card", "CardHeader", "CardTitle", "CardBody", "Badge", "Skeleton"],
+      "must_not_contain": ["CardContent", "animate-pulse", "bg-green-", "text-red-", "dark:"],
+      "expectations": [
+        "Uses CardBody, not CardContent",
+        "Composes CardHeader and CardTitle rather than putting everything in one block",
+        "Uses Skeleton for the loading placeholder, not a custom animate-pulse div",
+        "Uses Badge for the change rather than a styled span",
+        "Writes no raw colour and no dark: variant — semantic tokens resolve in both modes"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "Using @misoto22/design, add a small area chart of monthly revenue above the stat cards.",
+      "expected_output": "A chart imported from the charts entry point, with the peers named.",
+      "must_use": ["AreaChart"],
+      "must_not_contain": ["from '@misoto22/design'\nimport { AreaChart"],
+      "expectations": [
+        "Imports the chart from '@misoto22/design/charts', not from the root specifier — the root does not export it and the import throws",
+        "Mentions that recharts and motion are peer dependencies the project needs installed",
+        "Does not reach for recharts directly to build the chart by hand"
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "Using @misoto22/design, add an icon-only button that copies the current URL, and a toast confirming it.",
+      "expected_output": "An iconOnly Button with an accessible name, and toast imported from this package.",
+      "must_use": ["Button", "toast", "Toaster"],
+      "must_not_contain": ["from 'sonner'"],
+      "expectations": [
+        "Gives the iconOnly Button an aria-label naming the action — without one it is announced as \"button\" and nothing else",
+        "Imports toast from '@misoto22/design', not from sonner",
+        "Renders Toaster once at the app root rather than beside the button",
+        "Puts no sizing class on the icon"
+      ]
+    }
+  ]
+}

package/skills/misoto22-design/rules/a11y.md

@@ -38,6 +38,52 @@ caption still reaches assistive tech.
 
 ## An icon-only control needs a name
 
+Development warns on both failures in this section rather than leaving them to
+review: `BUTTON_ICON_ONLY_UNNAMED` when an `iconOnly` Button has neither
+`aria-label` nor `aria-labelledby`, and `REQUIRED_NAME_BLANK` when a name that
+is required for accessibility is an empty string. Each names the field and the
+fix, so a failed render tells you what to change.
+
+They are two of nineteen. The whole set, so a code you meet in a console is
+findable:
+
+| Code | Fires when |
+| --- | --- |
+| `ARTICLE_HTML_AND_CHILDREN` | `Article` is given both `html` and `children`. |
+| `BREADCRUMB_CRUMB_NOT_LINKED` | A crumb before the last carries no `href`. |
+| `BUTTON_ICON_ONLY_UNNAMED` | An icon-only `Button` has no accessible name. |
+| `DIALOG_TITLE_MISSING` | `DialogContent` has no `title`. |
+| `FIELD_CONTROL_NOT_LABELLABLE` | A `Field`'s child is a host element that cannot take a label. |
+| `FIELD_CONTROL_NOT_WIRED` | A `Field`'s child is not a single element, so nothing was wired. |
+| `REQUIRED_NAME_BLANK` | A name required for accessibility is an empty string. |
+| `SEARCHABLE_MENU_LABEL_UNREADABLE` | A `SearchableMenu` action's label has no text and no `keywords`, so typing can never find it. |
+
+`Diagram` checks the spec it was handed, because a figure that ignores an edge
+still renders beautifully:
+
+| Code | Fires when |
+| --- | --- |
+| `DIAGRAM_ACCENT_ON_CONTAINER` | `accent` on a node with children, drawn as a band with no fill to take. |
+| `DIAGRAM_DIRECTION_ON_LEAF` | `direction` on a node with no children. |
+| `DIAGRAM_DUPLICATE_ID` | Two nodes carry the same `id`. |
+| `DIAGRAM_EDGE_NOT_ADJACENT` | An edge names two nodes that are never consecutive siblings. |
+| `DIAGRAM_EDGE_UNKNOWN_NODE` | An edge names an `id` no node carries. |
+
+And the figures in `@misoto22/design/diagrams` check theirs:
+
+| Code | Fires when |
+| --- | --- |
+| `DIAGRAM_CELL_COLLISION` | Two nodes land at the same coordinate, so one plate is drawn on top of the other. |
+| `DIAGRAM_EDGE_DANGLING` | A relationship names an id the specification does not declare, so it is left out of the picture and the summary. |
+| `DIAGRAM_LANE_UNKNOWN` | A node names a lane no lane in the specification declares; it falls back to the first. |
+| `DIAGRAM_REF_UNKNOWN` | A field references an id no node in the specification declares. |
+| `DIAGRAM_SPEC_MUTATED` | The same spec object arrives with different contents; the model is memoised on identity, so the figure still draws the first. |
+| `DIAGRAM_STAGE_OUT_OF_RANGE` | A node's `stage` falls past the last declared stage, so it is drawn in a column the axis does not label. |
+
+All of them are development-only — every call site is behind
+`process.env.NODE_ENV`, so nothing here reaches a production bundle — and each
+prints once per problem, the field that caused it, and an imperative fix.
+
 ```tsx
 // Incorrect — reads as "button"
 <Button iconOnly><TrashIcon /></Button>
@@ -93,9 +139,15 @@ where a hand-rolled component quietly becomes unusable with a keyboard. `Dialog`
 
 ## Motion is gated
 
-Anything animated is behind `motion-safe` and carries `data-m22-animated`, so
-the one reduced-motion rule in the package can reach it. If you animate
-something yourself, do both.
+Anything animated is behind `motion-safe` and carries `data-m22-animated`. Do
+both when you animate something yourself — but know what each one buys. The
+GUARANTEE is a universal rule in `keyframes.css`: under
+`prefers-reduced-motion: reduce`, `animation-duration` and `transition-duration`
+are clamped to 0.01ms on `*`, so your animation is covered whether or not you
+remember the attribute. `data-m22-animated` goes further, removing the
+animation outright rather than running an instant frame of it — read it as the
+component asserting its motion is decorative, not as the thing that does the
+cancelling.
 
 ```tsx
 // Correct — the package's keyframes are all prefixed `m22-`

package/skills/misoto22-design/rules/forms.md

@@ -55,6 +55,11 @@ field is wrong, the thing to read is what is wrong with it.
 
 ## One control per `Field`
 
+`Field` warns in development when it cannot wire a control, so you do not have
+to spot this by reading. `FIELD_CONTROL_NOT_LABELLABLE` means the child is a
+wrapper and the label went onto the box; `FIELD_CONTROL_NOT_WIRED` means there
+was no single element to wire at all. Both print the fix.
+
 The wiring clones a **single** element child. Two children, or a wrapper div,
 and nothing is wired — the label points at an id that is on nothing.