AI rules

Coding assistants reach for Tailwind utilities by default. Atlas would rather they reached for <x-atlas::button> and its tokens, so the package ships its conventions as agent rules you publish into your project.

Publishing the rules

php artisan atlas:rules

Under Radicle or another Acorn host:

wp acorn atlas:rules

Name agents to publish for just those — claude, cursor or copilot:

php artisan atlas:rules claude
php artisan atlas:rules claude cursor

A rules file that differs from Atlas current version is skipped, so an edit is never lost silently. After a package upgrade, add --force to replace the files with the latest rules. --remove takes Atlas rules out again.

Where the rules go

There is one set of rules. The command writes it to each assistant's own rules directory, with the frontmatter that assistant expects:

| Assistant | Name | File | How it is loaded | | --- | --- | --- | --- | | Claude Code | claude | .claude/rules/atlas.md | Claude loads every file in .claude/rules/ | | Cursor | cursor | .cursor/rules/atlas.mdc | alwaysApply: true | | GitHub Copilot | copilot | .github/instructions/atlas.instructions.md | The applyTo: '**' glob | | Any other assistant | agents | A block between <!-- atlas:rules --> markers in AGENTS.md | AGENTS.md |

agents is for assistants without their own rules directory — Codex, Windsurf, Zed and the like — and you have to ask for it:

php artisan atlas:rules agents

It is not published by default because Cursor and Copilot read AGENTS.md as well and would load the rules twice. Only the block between the markers belongs to Atlas; the rest of AGENTS.md is never touched.

The files go to the root of your repository — the nearest directory with a .git — because that is where assistants look. Under a Sage theme that means the project root, not the theme directory.

These files belong to Atlas: --force replaces them. Your own CLAUDE.md, AGENTS.md and .github/copilot-instructions.md are never touched.

Commit the rules

Commit the published files, the way you would a published config file. Your team then gets the rules on clone, assistants that run on GitHub — Copilot's coding agent and code review, Claude on GitHub, Cursor's background agents — see them too, and an upgrade with --force shows up as a diff you can review.

If your .gitignore excludes .claude/ or .cursor/ to keep local settings out, exclude their contents instead and let the rules through:

/.claude/*
!/.claude/rules/
/.cursor/*
!/.cursor/rules/

Upgrading from an earlier version? Delete .cursor/rules/figma.mdc (its rules are now part of atlas.mdc) and the @.claude/rules/atlas.md line in CLAUDE.md, which Claude no longer needs.

What the rules cover

The published rules encode the conventions this documentation describes, so an assistant working in your project follows them without being told each time:

• Compose from x-atlas:: components before writing markup by hand.
• Style through tokens. Never hard-code a color, spacing value or radius; override global theme tokens (e.g. --color-primary, --radius) or component hooks (--atlas-button-bg-color, --atlas-input-border-color) instead.
• Follow the BEM naming Atlas uses — .atlas-component, __element, --modifier — and keep component CSS inside @layer components.
• Write Tailwind v4 CSS-first: tokens in :root, bridged via @theme inline, no tailwind.config.js.
• Keep accessibility intact: label controls, preserve focus states, and keep the accessible name when a button becomes icon-only.
• Use kebab-case attributes in Blade (icon-position, not iconPosition).

Do not edit a published Atlas rules file — the next --force publish replaces it. Put project rules in a file of your own alongside it: CLAUDE.md, AGENTS.md, a new .cursor/rules/*.mdc or .claude/rules/*.md.

Customising components instead

When a component needs to differ in your project, publish it rather than fighting it in CSS:

php artisan atlas:publish button card
php artisan atlas:publish --all

Published components land in resources/views/atlas/ and take precedence over the package's own — Atlas registers your application's directory first, so a file you publish wins and the rest keep coming from the package. That path is also the escape hatch for patching a component you have not upgraded yet.