# Using the system

*Use*

NachoDS is published once and read many ways: as these pages in a browser, as one text file an AI tool reads, as a machine-readable layer a script joins, over MCP for an agent, as a pinned bundle a website loads, and as whole-page designs a developer ports. This page lays out each way in, who it is for, and what to take from it. Every way in reads the same published release, so every reader works from the same brand.

<!-- source: /use · id: use -->

## Who uses it, and how   `#audiences`

Each way in serves one kind of reader. Start from the row that describes you; the rest of this page explains each one.

| Reader | Way in | Start with |
| --- | --- | --- |
| **A person**: a designer, writer, marketer, or printer | These pages, in a browser | The Brand view, then the view for the surface at hand |
| **An AI assistant** that reads a URL | One text file with the brand essentials and the page index | [`/llms.txt`](/llms.txt) |
| **An agent with MCP** | The `timds-design-system-read` server | `get_consumer_guide`, then `describe_system` |
| **A script or pipeline** | The machine-readable layer beside the pages | [`/index.json`](/index.json), [`/tokens.json`](/tokens.json), [`/brand.json`](/brand.json) |
| **A website or app** | A pinned release and its consumer bundle | `timds.consumer.json` at the product's root |
| **A developer building a page** | The website designs: whole pages on the system's own stylesheets | The `/designs/` directory in the app bar |
| **A designer, or an agent changing the system** | The system's repository and its editing tools | `AGENTS.md` in the repository |

## Read it in a browser   `#browser`

These pages are the published artifact itself, built from the system's source on every release. Each view is one audience's slice of the system, and every page follows the same shape: an eyebrow, a title, a summary, then one block per topic.

| On the page | What it is |
| --- | --- |
| **A table** | The rules. Each row is one record every other way in can cite, so a specification or a do-and-don't lives in a table, never in prose. |
| **A note** | Guidance that is not a row: a reason, a caution, an exception. |
| **A code block** | Markup to copy as written. |
| **A preview** | A live sample of the thing described. Its sample text is illustration, never a rule. |
| **Planned** | A page declared in the navigation and not yet written. Nothing is published for it, so no reader receives placeholder guidance. |
| **The version in the app bar** | The release these pages belong to. Every merged change becomes a new patch release. |
| **Markdown** | The check writes a mirror of every page at `index.md` beside it, the same content as plain text. This page's is [`/use/index.md`](/use/index.md). |

## One URL for any AI tool   `#llms`

A person who wants an assistant to work on-brand pastes one address. The file opens with how to use it, so the tool needs no other instruction.

| File | Holds | Use it when |
| --- | --- | --- |
| [`/llms.txt`](/llms.txt) | How to use the file, then the brand essentials: every role color as hex, every font with its family and the files or service that provide it, every logo by variant with its URL, every asset format with its size, and then the page directory. | Pasting the system into a chat, or into any tool that reads a URL. |
| [`/llms-full.txt`](/llms-full.txt) | Every page's Markdown in one file. | A tool that reads a single URL and needs the whole system, not a directory to follow. |

> **Note.** Both files are generated from the built pages on every check, never written by hand, and the published copies carry absolute URLs, so either one can be handed around on its own.

## The machine-readable layer   `#machine`

The check (`npm run timds -- check`) reads the built HTML and CSS and writes these documents beside the pages, and every release publishes them; a plain dev build serves the pages without them. Nothing in them is maintained by hand, so they cannot drift from what the pages say. A script, a render pipeline, or a host reads them directly; the MCP server below serves the same documents.

| Document | Holds |
| --- | --- |
| [`index.json`](/index.json) | Every page as structured blocks: rules from its tables, one record per row, notes, code, and assets joined to their media records. |
| [`tokens.json`](/tokens.json) | Every CSS custom property the pages load, resolved, with the scope and kind of each, and the brand roles they fill. |
| [`brand.json`](/brand.json) | The brand kit: the role colors and fonts, each font with the files or service that provide it, every logo and image presented as brand material, and the guidance groups. |
| `formats.json` | Every print sheet and screen canvas with its size, bleed, and safe area, when the system keeps a format catalog. |
| `designs.json` | Every website design page and state as HTML, with the files it loads. |
| `bundle.json` | Every file in the consumer bundle with its size and digest, and the immutable copy of this version a website pins. |
| `index.md` | Beside every page, its Markdown mirror. |

| Brand role | Answers |
| --- | --- |
| `color.background`, `color.panel` | The page ground and the raised surface on it. |
| `color.accent` | The one color that signals an action or a highlight. |
| `color.text`, `color.muted` | Body text and secondary text. |
| `font.display`, `font.body`, `font.ui` | Headings, running text, and interface labels. |

> **Note.** Every record carries a stable id, such as `brand/voice#principles`: the page, then the block, then the row. Cite the id, and a reviewer can resolve it. A block's id is the citation, so it is never renamed casually.

> **Note.** Ask for a role, not a token name. A role resolves to the token that fills it and that token's value, so a consumer never has to know how this system names things. A role nothing fills is a gap the system reports, never a value to guess.

## Connect an agent over MCP   `#mcp`

The `timds-design-system-read` server serves the layer above to any MCP-capable agent. It is read-only apart from filing a gap, never sees authored source, and serves the current published release by default; `version` selects an earlier one. Every result names the version it was read from.

| Where it runs | How to connect |
| --- | --- |
| **Hosted** | The TimDS portal serves it over HTTP, authorized with an access token. In a product, `timds consumer init` writes the entry into `.mcp.json`. |
| **Against a checkout** | `npm run timds -- mcp read` in the system's repository, after a check has built the layer. |
| **Against the published copy** | `npm run timds -- mcp read --published URL`, with the system's published root. |

| Tool | Gives |
| --- | --- |
| `get_consumer_guide` | How to use a system to produce on-brand work. Read it first. |
| `list_design_systems`, `describe_system` | What is in scope; the served, published, and pinned versions; the page directory; the consumer bundle and its immutable copy. |
| `resolve_role` | A brand role to the token that fills it and its value. An unfilled role is a reported gap, never a guess. |
| `get_tokens` | Resolved custom properties by name, kind, or scope, such as a dark theme. |
| `get_brand` | The roles, each font with its sources, the logos, the imagery, and the guidance groups. |
| `list_formats` | The asset format catalog: every sheet and canvas with its size, bleed, and safe margin. |
| `list_pages`, `read_page` | The page directory, and one page or one block as Markdown or as structured blocks. |
| `list_designs`, `read_design` | The website designs, and one page state's HTML with the files it loads. |
| `search_guidance` | The blocks that answer a question, guidance groups first, every result cited by page and block. |
| `list_media` | The published media catalog by tag or kind, each with a stable public URL. |
| `report_gap` | Files one gap into the system's request intake, when the host provides one. |

> **Note.** The resources `timds://brand.json`, `timds://tokens.json`, `timds://index.json`, `timds://llms.txt`, `timds://formats.json`, `timds://bundle.json`, and `timds://guidance/{group}` serve the same documents to a client that reads resources rather than calling tools.

## Pin it in a website or app   `#products`

A product never copies the system. It pins a release in `timds.consumer.json` at its root and installs that release's consumer bundle: the stylesheets, scripts, and small assets the system names in `bundle.include`, fetched into the product's ignored `design-system/` directory under the same paths they have here, every digest verified. A clone and an install is all a product, or an agent working in it, needs.

| Step | Command | What it does |
| --- | --- | --- |
| **Adopt** | `npm run timds -- consumer init --system ID` | Writes the manifest with a published pin, wires the sync into `postinstall`, and installs the consumer skill, the preview workflows, and the hosted MCP entry. |
| **Install** | `npm ci` | Fetches the pinned bundle and verifies it. |
| **Move the pin** | `npm run timds -- consumer update VERSION` | Moves to a version, or without one to the current release. A pin of `current` follows every release at the next install. |
| **Check** | `npm run timds -- consumer check` | Validates the manifest and the pin, and that a branch stays inside the product's declared design surface. |
| **Review** | `npm run timds -- consumer preview --app NAME` | Captures each route at desktop and phone widths in both color schemes, with the paired design beside it. |

> **Note.** A pin names an immutable copy of the release, so a later release never changes what a pinned product loads. In product CSS use a token by name, never by its literal value, so the product follows the pin. The `timds-consume-design-system` skill the adoption installs tells an agent how to make a design change in the product; when the system lacks what a change needs, the fix is a pull request to the system, never a product-side workaround.

## Port the website designs   `#designs`

The system is designer-owned down to the pages. A designer authors whole pages in HTML on the system's own stylesheets, the build writes them to `/designs/`, and the app bar links there. A named state is a file beside its page, so every state a developer must build is a page they can open.

| Rule | In practice |
| --- | --- |
| **The design is the reference** | A port matches it on the product's own stack with the system's stylesheets. The design file is never copied into the product as a page, and never restyled. |
| **Every state is a file** | Port each one. A state the product cannot express is a developer change to raise, not an omission. |
| **Pair the route** | In the product's manifest, a route is paired with its design so a review shows the two side by side. |
| **Read it as data** | `designs.json`, and `list_designs` and `read_design` over MCP, carry every page state's HTML with the files it loads. |

## Change the system   `#change`

Nothing above is edited in place. The system is a repository, every change is a pull request there, and merging releases a patch version that every reader above picks up on its next read.

| Who | Where | How |
| --- | --- | --- |
| **A designer, or an agent acting for one** | The system's repository | `AGENTS.md` is the working contract and the `timds-edit-design-system` skill holds the procedure. `npm run timds -- check` validates the change and `submit` opens the draft pull request. |
| **An agent without a checkout** | The `timds-design-system` editing server, `npm run timds -- mcp` | Guarded reads and writes of the authored surface, a check as structured findings, and the derived layer. Protected tooling is refused, not merely discouraged. |
| **A product that found a gap** | `report_gap` over MCP, or a pull request to the system | A missing token, role, component, or rule is fixed in the system, and the product waits for the next release. |
| **Video, when the system declares it** | The same repository | The `timds-create-video` skill and the `video` commands, on the client's own video contract. |

## Versions   `#versions`

Three versions matter to a reader, and every document and tool result says which one it carries.

| Version | Meaning |
| --- | --- |
| **Served** | The release a read returned. Every derived document and every MCP result names it. |
| **Published** | The current release, and the default for every way in on this page. |
| **Pinned** | The release a product is built against. It trails the published release until a developer moves the pin. |

> **Note.** Each merged change becomes a patch release, published to the portal and to the stable address every way in on this page reads from. The number in the app bar is the release these pages belong to; this copy is 0.1.0.