---
name: octopus-ui
description: >-
  Build and refactor UI with the Octopus UI design system (@aistrike-dev/ui):
  which component to use, which variant, and what never to hand-roll. Use
  whenever generating, revamping or refactoring any user interface in a project
  that depends on @aistrike-dev/ui.
---

<!-- Generated by scripts/build-agent-kit.ts for @aistrike-dev/ui@5.0.1. Do not edit. -->

# Octopus UI

The design system for this project is `@aistrike-dev/ui`. Every component, theme and token comes
from it. The rules below are non-negotiable; the detail is in the reference files, which live inside
the installed package.

## Before you write any UI

1. Read `references/core-rules.md` - the global contract. Always.
2. If several components could fit and they look alike in a mockup (a row of labels, an overlay, a
   text input, an empty region), open `references/choosing.md`. It is a short index: find the row
   matching your decision and read that one guide from `references/choosing/`.
3. Look up each component you intend to use in `references/components.md`: check `llmSafe`,
   its required props, its **Rules**, and its **Don't** list.
4. For any surface colour, severity, spacing, or type variant, read `references/tokens.md`.
   Never write a hex or font-size literal.

## The rules you must not break

- Import every component, layout, theme and token from `@aistrike-dev/ui`. Never from
  `@mui/material`, and never from a repo-internal `@/...` path.
- The only permitted MUI imports are icon glyphs from `@mui/icons-material` and the layout
  primitives `Box`, `Stack`, `Grid`.
- Never hand-roll a component the system ships: no custom-styled `<button>`, no pill `<span>`, no
  `<div>` card, no `TextField` with a magnifier adornment instead of `Search`.
- Never auto-generate a component marked `llmSafe: false`; use the alternative its entry names.
- When you cannot confidently choose, stop and ask, naming the options and the one you lean toward.

## Reference files

| File | Contents |
|---|---|
| `references/core-rules.md` | The global contract: imports, atomic level, tokens, accessibility, when to ask |
| `references/components.md` | Every component: import path, required props, rules, anti-patterns, a11y |
| `references/choosing.md` | Index of the decision guides; each guide is a file in `references/choosing/` |
| `references/tokens.md` | Surface, severity, spacing, and typography-variant tokens with their roles |
| `registry/llm-components.json` | The same component data, machine-readable |