AI assistants
An assistant writes better TaishoDS Core markup when it reads the system instead of guessing at it. This guide covers what the site publishes for that, how to hand it over, and how to connect the MCP server that ships in the package.
The llms.txt
llms.txt is a convention: a Markdown text file at a fixed address that summarizes a site for
language models. TaishoDS Core’s says what the system is and carries the rules for writing markup (the ts key class, the closed vocabulary, spacing, colors, variants), the installation steps, and
the list of components and guides, each with a link. One sheet per component has HTML that is ready to copy.
| URL | Language | What it has |
|---|---|---|
| https://taisho.design/es/llms.txt | Spanish | The index: what the Core is, the rules for writing markup, installation, and the list of components and guides, each with a link. |
| https://taisho.design/llms.txt | English | The index: what the Core is, the rules for writing markup, installation, and the list of components and guides, each with a link. |
| https://taisho.design/es/llms-full.txt | Spanish | Everything in the index plus every component sheet, with one example, and the utilities table. |
| https://taisho.design/llms-full.txt | English | Everything in the index plus every component sheet, with one example, and the utilities table. |
| https://taisho.design/docs/<slug>.md | Spanish | One component sheet: when to use it and when not to, its classes, the JavaScript it needs, keyboard behavior, and all its HTML examples. |
| https://taisho.design/en/docs/<slug>.md | English | One component sheet: when to use it and when not to, its classes, the JavaScript it needs, keyboard behavior, and all its HTML examples. |
The index is short and reads in one go. The full file is much longer and is only worth it when the assistant has
plenty of context to spare; otherwise the index plus the sheets of the components in use is enough. Spanish sheets
are also available, without the /en prefix.
How to hand it to an assistant
By address
If the assistant can open links, naming the file in the request is enough.
Using https://taisho.design/llms.txt as the reference, build a sign-in screen with TaishoDS Core.Inside the project
To make every session start from the same place, save the index and the sheets you use in a project folder, and
point the assistant’s instructions file (whichever it reads: AGENTS.md, CLAUDE.md, Cursor rules) at them.
mkdir -p docs
curl -o docs/taisho-llms.txt https://taisho.design/llms.txt
curl -o docs/taisho-button.md https://taisho.design/en/docs/button.mdTo write TaishoDS Core markup, follow the rules in docs/taisho-llms.txt
and copy components from their sheet (docs/taisho-<component>.md).
When done, run `npx taisho check` and fix until it reports 0 warnings.Saved files stay as they were that day: download them again to pick up changes to the system.
Checking what it writes
The vocabulary is closed: a class that doesn’t exist does nothing, and the browser doesn’t complain either. That’s why
the index asks the assistant to run npx taisho check when it finishes. With --format json, each warning carries the rule, the location and, when there is a clear
replacement, a suggestion, so an assistant can read it and fix the code on its own.
npx taisho check --format json src{
"version": 1,
"files": 1,
"warnings": [
{
"file": "src/login.html",
"line": 1,
"column": 23,
"rule": "unknown-class",
"severity": "error",
"code": "unknown-class",
"params": { "class": "bg-brnad-500", "suggestion": "bg-brand-500" },
"message": "\"bg-brnad-500\" isn't a DS class, so it isn't emitted. Did you mean \"bg-brand-500\"?",
"suggestion": "bg-brand-500"
}
]
}Exit codes and the rest of the rules are in Command line.
The MCP server
The llms.txt is text the assistant reads. The MCP (Model Context Protocol) server is a program
the assistant queries while it works: which components exist, what one looks like, whether a class exists, which colors
the project has. It ships in the package and starts with npx taisho mcp; the client (Claude Code,
Claude Desktop, Cursor, VS Code, and others that speak MCP) launches it on its own.
Local and read-only
taisho.config.ts and the data that ships in the package: it writes no files, makes no network
calls, and sends no telemetry.Setting it up in a client
With @taishods/core installed in the project, declare the server in the client’s configuration,
at the project root (Claude Code reads .mcp.json; Cursor, .cursor/mcp.json; each client documents its own file).
{
"mcpServers": {
"taisho": { "command": "npx", "args": ["taisho", "mcp"] }
}
}VS Code uses a different key and asks for the type, in .vscode/mcp.json:
{
"servers": {
"taisho": { "type": "stdio", "command": "npx", "args": ["taisho", "mcp"] }
}
}VS Code only offers the server in a trusted folder. If the file shows no action to start it, start it from the
Command Palette: “MCP: List Servers”, then the taisho server and “Start Server”.
A client with global configuration doesn’t know which project it is in. Point it there with --config, and use the absolute path to the installed command so it doesn’t depend on the
folder it starts from. The config’s folder becomes the project root.
{
"mcpServers": {
"taisho": {
"command": "node",
"args": [
"/ruta/al/proyecto/node_modules/@taishods/core/bin/taisho",
"mcp",
"--config",
"/ruta/al/proyecto/taisho.config.ts"
]
}
}
}--lang es or --lang en picks the language of the sheets and messages;
without it, the config’s lang is used and, failing that, the system’s. If the config
changes, the server rereads it on its own. Without a taisho.config.ts it uses the default
theme, and get_theme says so.
What it offers
On connecting, the server hands the assistant the same rules as the llms.txt as instructions,
and offers six tools. Five are explained here; the sixth moves code from another system to TaishoDS and is in the
migration guide, under Foundations.
| Tool | What it’s for |
|---|---|
| list_components | Lists the Core components with the total, and for each one its name, root classes, whether it needs JavaScript, and a summary. |
| get_component | Returns one component’s sheet: when to use it, its classes, keyboard behavior, and HTML examples to copy. |
| search_utilities | Searches utilities by name or by CSS in the project’s vocabulary, including its own, and says how many matched and how many it returned. |
| validate_markup | Checks a markup fragment the way taisho check does and says whether it is valid. |
| get_theme | Returns the project theme’s colors, shades, spacing, dark mode, and CSS variables. |
The examples below are real responses, shortened with …. Each → line
is what the assistant asks and each ←, what it gets back.
→ list_components
← {
"count": 56,
"components": [
{ "slug": "accordion", "name": "Accordion", "blocks": ["accordion", "accordion-item"], "needsJs": true,
"summary": "A list of collapsible sections that coordinate with each other." },
{ "slug": "alert-dialog", "name": "AlertDialog", "blocks": [], "needsJs": true,
"summary": "A dialog that forces a decision before moving on." },
…
]
}→ get_component { "slug": "badge" }
← # Badge
A compact label for statuses, categories, or counts. …
## When to use it
- Showing something’s status in one word, like “Active,” “Beta,” or “Expired.”
…
## Classes
- Root: `ts badge`
- Modifiers: `size-md`, `fill-subtle`, `variant-default`, `variant-success`, …
…
## Examples
### Deployment status: ready
```html
<span class="ts badge size-md fill-subtle variant-success"> Ready </span>
```→ search_utilities { "query": "gap base", "limit": 3 }
← {
"total": 5, "returned": 3,
"results": [
{ "class": "gap-base", "css": "gap: var(--ts-gap-base);" },
{ "class": "gap-x-base", "css": "column-gap: var(--ts-gap-base);" },
{ "class": "gap-y-base", "css": "row-gap: var(--ts-gap-base);" }
]
}→ validate_markup { "markup": "<div class=\"flex gap-base bg-brnad-500\">Hello</div>", "filename": "login.html" }
← {
"version": 1, "files": 1, "valid": false,
"warnings": [
{ "file": "login.html", "line": 1, "column": 6, "rule": "missing-ts", "severity": "error",
"message": "<div> uses DS classes (\"gap-base\") but doesn't have the `ts` scope class, so it gets no styles." },
{ "file": "login.html", "line": 1, "column": 27, "rule": "unknown-class", "severity": "error",
"message": "\"bg-brnad-500\" isn't a DS class, so it isn't emitted. Did you mean \"bg-brand-500\"?",
"suggestion": "bg-brand-500" }
]
}→ get_theme
← {
"configFile": "taisho.config.ts",
"language": "en",
"themes": ["main"],
"colors": { "gray": "neutral", "brand": "#4F46E5", "success": "#16A34A", "warning": "#D97706", "info": "#2563EB", "danger": "#D42424" },
"shades": ["100", "200", "300", "400", "500", "600", "700", "800", "900", "1000"],
"rhythm": ["none", "quarter", "half", "base", "section", "double"],
"darkMode": "class",
"cssVars": ["--_card-pad-lg", "--_card-pad-md", "--_card-pad-sm", …]
}validate_markup does what taisho check does on a fragment, and adds valid. Unlike the command, it always includes other-scale warnings
(p-4 is 4 px here), which are reminders: they don’t make the markup invalid. A tool that
fails, for instance with a slug that doesn’t exist, replies with the error and the list of
valid ones.
What the llms.txt doesn’t know
It describes the Core’s default theme. A project’s own colors, its own utilities, and its taisho.config.ts aren’t in it; npx taisho check does know them, because it
reads the project’s configuration, which is why it’s the step that closes the work; the MCP server knows them too. Following the rules doesn’t
guarantee an assistant won’t make mistakes either: reviewing the result is still up to whoever uses it.
A component sheet
/en/docs/button.md. It is the same content
the assistant reads, without the page design.