Working with AI

Give a coding agent the contracts from the version your project uses, then have it check the markup it changes. The contract supplies class names, required elements, state attributes and public custom properties; the checker catches common structural mistakes without rendering the page.

Before an edit, the agent should inspect how your project imports Master UI, which theme it uses and whether master-ui.json records locally owned components. Those local contracts take precedence over the package's defaults. After the edit, static checks and a browser review answer different questions: valid markup can still have the wrong layout, an inaccessible interaction or a missing behavior script.

#The skill

The master-ui skill is for an agent working in a project that uses the library. Install it with:

npx skills add master-co/ui --skill master-ui

The skill tells the agent to use Master UI where a project already imports it. It does not introduce the library into a project that uses another one.

#What the site publishes for programs

The site publishes structured data and portable Markdown. Component Markdown is generated from contracts; guides, layouts, blocks and pages are exported from their authored pages. These outputs provide text and code rather than an interactive copy of the site.

An agent without a shell starts at llms.txt and reads the relevant component page, such as https://ui.master.co/components/dialog.md. The public site describes its deployed library version, which may differ from a project's installed version. With the package available, prefer its @master/ui/contracts.json and @master/ui/theme.json, or the CLI below when the project has local contracts.

#Look up a contract

Run the CLI from the project root after installing the package. It reads contracts from that installed package and the project; do not let an uninstalled command fetch an unrelated version as part of a lookup.

npx master-ui list             # every contract, one line eachnpx master-ui contract dialog  # one contract as JSON

A class name works as the name, so npx master-ui contract btn-primary prints the button's contract. npx master-ui list --json prints the list as data.

Both commands also read the directory and additional contract paths configured in master-ui.json (ui/ by default). A component the project owns is described by its copy, and a component the project wrote is listed beside the library's.

#Check the markup

npx master-ui check reads markup and reports where it breaks a contract. For example, this file has three errors and one warning:

<button type="button" class="btn-primary">Save changes</button><button type="button" class="btn btn-outline">Cancel</button><button type="button" class="btn btn-square">  <svg aria-hidden="true" viewBox="0 0 16 16"><path d="M4 4l8 8M12 4l-8 8"/></svg></button><div class="dialog">  <h2 class="dialog-title">Delete this project?</h2></div>

npx master-ui check page.html

page.html:1:1 error missing-base "btn-primary" modifies "btn": write class="btn btn-primary".page.html:2:1 warning unknown-class "btn-outline" is not a class of btn. It has: btn, btn-primary, btn-quiet, btn-brand, btn-danger, btn-sm, btn-lg, btn-square, btn-pill, btn-group.page.html:3:1 error label "btn-square" needs an accessible name: text of its own, aria-label, aria-labelledby, or a <label> that wraps or points at it.page.html:6:1 error element "dialog" goes on <dialog>, not <div>.1 files checked: 3 errors, 1 warnings.

Each line gives the place, the severity, a code and what to write instead, so an agent can fix the markup and run the command again until it is clean. Contracts lists every code.

• Paths. Without arguments it checks every .html, .htm, .astro, .svelte, .vue, .jsx, .tsx, .mdx, .erb, .php, .njk, .liquid and .hbs file under the working directory, outside node_modules and build output. Pass files, directories or globs to narrow it.
• What it leaves alone. It reads tags, classes and attributes without running a browser. What it cannot know, such as a class that comes from an expression or a part whose root is in another file, it does not report.
• --json prints the result as data: the number of files, and for each file with a finding its diagnostics, each with code, severity, className, contract, message, line and column.
• --strict reports unknown-class as an error. A class that starts with a component's root class and a dash, and is in no contract, is a warning by default, because it may be a utility. When the project has Master CSS installed, the checker recognizes preset utilities. Review diagnostics for project-defined classes too; a clean result does not validate every custom utility or dynamically computed class.

The command exits with code 1 when it finds an error, so it fails a CI step as it stands:

{  "scripts": {    "check:ui": "master-ui check --strict"  }}

For programmatic checking, use @master/ui/check; Contracts documents the data the checker reads. Keep browser checks in the agent's completion criteria: test the affected keyboard actions, states, narrow layout and color schemes, including any required behavior attachment.

#Tell your agent

An agent follows the project's own instructions first. Paste this into AGENTS.md, or the file your agent reads:

## Master UIThis project builds its interface with Master UI: classes on native elements, each described by a contract.- Read the contract before writing a component's markup: `npx master-ui contract <name>`, and `npx master-ui list` to find one. Do not write markup from memory.- Never invent a Master UI component class. Use the installed or locally owned contract, and keep project-defined classes outside the library's class families.- Mark a state with the attribute the contract lists (`disabled`, `aria-pressed="true"`, `open`). Never add a class for a state.- A component is a class on a native element in any framework. Do not wrap one in a component to rename it. The patterns that hold state have a component to copy: `npx master-ui add` lists them, and `ui/` may already hold one.- To change how something looks, take the lowest step that works: a utility on the element, a theme token, a public custom property, a theme file, and only then `npx master-ui own <name>`. A project rule may select a library class to set its documented custom properties; change its implementation through owned source.- Run `npx master-ui check` after changing markup. Fix every error and read each warning. Check the affected interactions in a browser, including the keyboard, a narrow viewport and both color schemes.

#MCP

The Master UI package provides the CLI and contract files described above. If your agent also connects to a Master CSS MCP server, inspect that connection's available tools before relying on component-contract lookup. Tool availability depends on the connected server; the installed CLI remains a direct way to read the project's effective contracts.

#In a chat sandbox or an artifact

For a chat artifact or static HTML prototype with no CSS compilation, link the site's compiled stylesheet. Include its base reset if the environment does not provide one:

<link rel="stylesheet" href="https://ui.master.co/base.css"><link rel="stylesheet" href="https://ui.master.co/standalone.css"><button type="button" class="btn btn-primary">Save changes</button>

These URLs track the deployed site, so they suit a disposable prototype. For a maintained project, serve the compiled files from a pinned package and read contracts from that same version. Loading CSS does not attach behavior scripts; patterns that need them still require a browser module or a framework component.

Utilities are not available there. A class such as flex or gap-md needs Master CSS to generate it, so lay the page out with CSS of its own, in a style attribute or a small style block. The theme's tokens work, because they are custom properties: color: var(--color-text-muted) reads the theme.