Foundations

Working with AI

The package documents itself twice. This is the half a browser cannot open.

There are two audiences for this package and only one of them can open a browser. The second one has usually installed it — which means the version it is writing against is sitting in node_modules, while the documentation it would otherwise read is on a website that has moved on. Everything below is generated from the source in the same tarball, so it describes the version you actually have rather than whatever shipped last.

This matters most exactly where a model is most confident. The names diverge from shadcn/ui in a handful of places a model writing from habit gets wrong — CardBody not CardContent, THead/TBody/TR/TH/TD not TableHeader and friends, title as a prop on DialogContent rather than a DialogTitle child. Guessing produces imports that do not exist, and the fastest fix is to stop guessing.

In the terminal

The package ships a binary. docs <Component> prints one component in full — every prop with its type and default, the exported unions, the keyboard contract, the accessibility promises, and the @example blocks off the component’s own JSDoc.

It resolves parts and types, not only components: docs CardBody, docs TH and docs ButtonVariant all land on the right file, and it says which component owns the name it redirected you to. That is the command to reach for when an import has just failed, because the identifier you are holding is usually a part rather than the thing that exports it.

docs --installed is the cheap half of the deal: the resolved version and the names, grouped, with no prop tables. It is what belongs at the top of a session. --json gives the same thing machine-readably, including the four stylesheet specifiers.

terminal — docs

npx misoto22-design docs Button          # one component, in full
npx misoto22-design docs CardBody        # resolves a part to its owner
npx misoto22-design docs ButtonVariant   # …and an exported type
npx misoto22-design docs --list          # every component, one line each
npx misoto22-design docs --installed     # version + names, no prop tables
npx misoto22-design docs --installed --json

Install the skill

The package carries an agent skill under skills/misoto22-design/, and init copies it into your project at .claude/skills/misoto22-design/. --agents-md also appends a short section to your AGENTS.md pointing at it, and leaves the file alone if it already mentions the package.

The skill is progressive on purpose. Its name and description are all that sit in a session until something actually touches this package; the body loads when the work reaches it, and five rule files — tokens, composition, forms, accessibility, naming — load one at a time after that. It leads with the shadcn/ui naming table, and the package’s own test suite fails the build if any row of it stops being true.

Re-run it after upgrading. The skill is a copy, not a link, so a project that installed it once is holding whatever the version at that time said.

terminal — init

npx misoto22-design init              # writes .claude/skills/misoto22-design/
npx misoto22-design init --agents-md  # …and points AGENTS.md at it

On the web

The same content is served as plain text from this site, for an agent that can fetch a URL but has not installed anything. Three shapes, and the choice between them is a budget: the index is a page, one component is a page, and everything inline is the whole system.

Prefer the CLI when the package is installed. The site documents whatever shipped last; node_modules holds what your code is actually compiled against, and neither side can see the disagreement.

ui.misoto22.com/llms.txt: The index — what the system is, the eight laws, the theming axes, and a line per component.
ui.misoto22.com/components/<slug>/llms.txt: One component: props, types, keyboard, accessibility, examples. One fetch, one component.
ui.misoto22.com/llms-full.txt: The index followed by every component inline. Reach for it only when you genuinely need all of them.

What is in the tarball

The generated documentation is a build artifact and ships inside the published package, so none of it needs a network. dist/agent/ holds one Markdown file per component, an index.md with a name and a line each, and a catalog.json the CLI reads to resolve a part or a type back to its owner. The CLI is a thin reader over that directory; in a source checkout it is built by pnpm build:agent and the CLI says so rather than printing nothing.

skills/misoto22-design/ ships alongside it, which is what init copies. Both are listed in the package’s files field, so npm pack carries them.