Skip to main content

Using AI assistants

Coding assistants do not know this library's component contracts by default. Without the library guidance, they may invent props, reach for a raw <div> instead of a component, or copy patterns from a different design system.

Add the generated project guidance for your tool below. It gives the assistant the component map and house rules; use the linked component docs for the full API and use the migration guide for v1 applications.

For GitHub Copilot, put the generated guidance at .github/copilot-instructions.md. Copilot loads that file for work in the repository; this is the Copilot-specific path.

mkdir -p .github
cp node_modules/@takeoff-ui/react-spar/agents/AGENTS.template.md \
   .github/copilot-instructions.md

If the file already exists, merge the generated Rules and Components sections into it instead of overwriting the repository's instructions. Commit the resulting instructions file so the whole team gets the same guidance.

Copilot's agent mode can also use an AGENTS.md file at the repository root. Inline completions do not load either file as a complete project guide; they mainly use the current editor context.

Check it worked: open Copilot Chat and ask it to "add a primary button that shows a loading spinner". You should get Button from @takeoff-ui/react-spar with a loading prop — not a hand-rolled <button>.

Package version note​

Requires 0.4.0 or newer. If the agents/ directory isn't in your node_modules, you're on an older version — upgrade, or copy from the template on GitHub.

Already have that file? Don't overwrite it — paste the Rules and Components sections from the template into what you have.

Migrating a v1 application​

For a v1-to-v2 migration, use the AI assistant as the primary operator for the repetitive work instead of manually rewriting every screen. The migration skill ships in the package, so there is nothing to clone:

ls node_modules/@takeoff-ui/react-spar/agents/migrate-takeoff-v1/

SKILL.md is the entry point; the references/ directory beside it holds the inventory commands, the v1-to-v2 component map, the prop and event translation, the one-time setup, and the known coverage gaps. To keep it beside the guidance your assistant already loads, copy it into the repository:

mkdir -p .agents/skills
cp -R node_modules/@takeoff-ui/react-spar/agents/migrate-takeoff-v1 \
   .agents/skills/migrate-takeoff-v1

migrate v1 ./src is a request to an AI assistant in Chat or Agent mode. It is not a shell command and there is no migrate executable installed by the npm package. Open the consumer repository as the assistant's workspace, then send the request there:

Read node_modules/@takeoff-ui/react-spar/agents/migrate-takeoff-v1/SKILL.md and
migrate the React app at ./src from @takeoff-ui/react v1 to
@takeoff-ui/react-spar v2. Start with the inventory in references/inventory.md.
If the v2 packages, provider, or token CSS are missing, apply the one-time setup
before migrating a screen. Then migrate one bounded screen at a time, use the v2
component-specific API docs, keep v1 and v2 installed together, run focused
typecheck/tests after each screen, and report remaining gaps before continuing.

For a large application, continue with a route or screen boundary:

Migrate the /settings screen from the v1 inventory. Keep documented v1-only
gaps in place and show the diff plus validation results.

The assistant must not silently replace a v1-only gap component or remove v1 packages before the inventory confirms that only explicitly approved gaps remain. See Migrating from v1 for the complete workflow.

Giving it the full API​

The file you just copied is an index: every component, what it's for, and the house rules. It deliberately doesn't include full prop tables — that would be too large to keep in context.

When an assistant needs the complete API for a component, point it at the Markdown docs. Every page is available by appending .md to its URL:

URLUse it for
/docs/components/<name>.mdOne component. Start here — smallest payload.
/llms-full.txtThe entire library, in one file.
/llms.txtAn index of every page, for tools that crawl.

These include guidance the API tables alone don't carry: when to reach for a component, and which neighbouring component to use instead when it isn't the right fit.