# AI Agents

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/docs/ai

mCSS is built to be easy for AI coding agents (Claude, Cursor, Copilot, etc.) to work with. The docs are available in machine-readable form, and this page includes a rules block you can paste into your project's agent instructions so generated markup follows mCSS methodology.

## Machine-readable docs

Three things exist specifically for agents:

- `/llms.txt`: an index of every docs and components page with one-line descriptions, following the [llms.txt](https://llmstxt.org) convention. Most agent tooling checks for this automatically.
- `/llms-full.txt`: the entire reference (docs and all components) concatenated into a single markdown file. Point an agent [here](/llms-full.txt) when it needs the whole framework in one fetch.
- **Markdown twins**: every docs and components page is also served as plain markdown at the same URL but with the `.md` extension. These are a fraction of the size of the HTML pages. Make sure you tell your agent to fetch the `.md` URLs, not the HTML.

## Add mCSS rules to your agent instructions

Paste the block below into your project's `CLAUDE.md`, `AGENTS.md`, or equivalent. It compresses the conventions that matter most when writing mCSS markup and CSS on top of it.

````md
## mCSS conventions

This project uses mCSS (https://mcss.dev), a CSS framework copied into the repo. There is no npm package: the files are project code, and the framework's defaults are overridden, never edited.
Full reference in one fetch: https://mcss.dev/llms-full.txt
Per-page docs: append `.md` to any mcss.dev docs or components URL (e.g. https://mcss.dev/components/card.md).

### Mental model: layers from default to deliberate

All framework CSS lives in native cascade layers, declared in `mcss.css` in priority order (later wins): `settings, base, elements, global, components, theme, helpers`.

- `settings` through `components` are the framework defaults: what things look like when nobody has an opinion. Never edit these files to restyle; override them from further up the order.
- `theme` holds at most one theme file: a deliberate opinion about the defaults. An empty theme layer IS the default look.
- Your own unlayered CSS is more deliberate still: it beats every layer, by design. Never use `!important` to win against the framework.
- `helpers` (`help.*` files: spacing, color, typography utilities) are the one exception: every declaration carries `!important`, which inverts the cascade, so they beat even unlayered CSS, like inline styles. Use sparingly. `!important` is banned everywhere else.

### Restyling, in order of preference

1. **Theme token overrides.** A theme is one file that reskins the whole site: `@layer theme { :root { ... } }` (self-layered, so it slots correctly however it's loaded). Copy `theme.default.css` to start one; activate exactly one from your CSS entry point, after `mcss.css` (which never imports themes itself). Anything the theme doesn't mention falls back to the defaults. Pick the blast radius per override: raw tokens (`--base-*`, `--text`) shift the whole palette or type scale, interface tokens (`--ui-border-color`, `--heading-font`) change every surface that shares the meaning, component tokens (`--bt-border-radius`, `--card-*`) turn one knob. Most themes never need a selector.
2. **Theme style rules**, only for what tokens can't express (pseudo-elements, `nth-child` rhythm, `text-decoration`). Theme files are the ONE place allowed to select component classes from outside. No `!important` in themes.
3. **Unlayered project CSS** for what belongs to your project rather than to the design: page layouts, one-off blocks.
4. **Helpers** for element-level one-offs.

Edit framework files only for structural change: adding a component, or adding a missing token or `<part>Class` prop to an existing one.

### Tokens

- `settings.tokens.css`: raw primitives (palettes, type scale, spacing, radii).
- `settings.ui.css`: interface tokens, the public API of every component (semantic aliases plus all component defaults). Interface tokens only ever take another token as value; raw values live in `settings.tokens.css`.
- Grammar: `--component-part-property`, longhand, kebab-case, no abbreviations: `--bt-background-color-hover`, `--notice-border-width`.
- Feedback colors: use the semantic aliases `--success-*`, `--danger-*`, `--warning-*`, not the raw scales they point at.

### Class naming (BEM-like, different separators)

- Block: `.componentName` (camelCase for multi-word names)
- Element: `.componentName_element` (underscore marks hierarchy inside one block; chains may nest as deep as the block's structure needs)
- Modifier: `.componentName-modifier` (hyphen), for build-time variants chosen in markup
- State: `.is-*` (`.is-active`, `.is-open`), only for things that change at runtime, always scoped inside the block (`.avatar.is-online`)
- Prefer styling an existing ARIA attribute over inventing a state class: `[aria-current]`, `[aria-expanded="true"]`, `[aria-disabled="true"]`
- A nested component starts its own block: `.themeToggle_text`, never `.header_nav_themeToggle_text`

### Never couple classes across components (CRITICAL)

A selector may only contain classes from its own block. Never write a selector that reaches into another component: not its block, not its elements. Instead, mix your own block's classes onto the component's markup and style those:

```html
<article class="card pricing_planCard">
  <h3 class="card_title pricing_planTitle">Pro</h3>
</article>
```

```css
/* Don't: couple your block to the card's classes */
.pricing .card { border-color: var(--primary-500); }
.pricing .card_title { color: var(--primary-500); }

/* Do: style the classes you mixed on */
.pricing_planTitle { color: var(--primary-500); }

/* Do: or turn the component's own token knobs from your class */
.pricing_planCard { --card-border-color: var(--primary-500); }
```

When the markup comes from a component you don't write inline, its `<part>Class` props (`titleClass`, `iconClass`, ...) mix your class onto the part the same way. If the prop or token you need doesn't exist, add it to the component; don't reach in with a selector.

Bare HTML tags, `.is-*` states, and ARIA attribute selectors are fine inside your own block. Theme files are the only sanctioned exception to this rule.

### Transitions

Never `transition: all`; list the properties that actually animate.
````

## MCP and tooling

There is no mCSS MCP server yet. For now, `llms-full.txt` plus the rules block above is the recommended setup. If your agent supports fetching URLs at runtime, the markdown twins are the cheapest way to pull a single component's markup reference into context.