Adoption Guide

Clarx is designed to be adopted in layers. You do not have to replace your current component library to benefit from it.

Three adoption paths

Option 1 — Philosophy only

Use the manifesto, principles, and vocabulary as a shared framework for how your team talks about UI decisions.

This is useful for teams that want to align on semantic thinking without changing any code. It helps design and engineering converge on the same language — "what does this communicate?" before "what does this look like?" — even when the implementation stays with an existing system.

What to do:

• Read the Manifesto and Principles
• Share them with your team as a design review checklist
• Use the vocabulary (intent, appearance, emphasis) in design handoffs and code review

Option 2 — AI rules only

Add the AI rules layer to your existing codebase so that AI tools start generating more semantic, consistent UI immediately.

This works even if you use a completely different component library. The rules teach AI assistants to prefer system-level semantics over ad hoc styling — which improves output quality regardless of which components are available.

What to do:

• Add a CLAUDE.md template to your repo root
• Add Cursor rules to .cursor/rules/
• Add an AGENTS.md snippet if you use other agent tools

Option 3 — Full adoption

Use the philosophy, the AI rules layer, and the reference components together.

This is the highest-leverage path. The components demonstrate what intention-driven APIs look like in practice. The AI rules layer ensures that AI tools generate code that uses those components correctly. The philosophy gives your team a shared framework for evolving the system over time.

What to do:

1. Follow the Installation guide to copy components into your project
2. Add the AI rules files to your repo
3. Review the Migration examples to see how to convert override-heavy patterns

---

For teams with existing design systems

If your team already has a component library and cannot replace it, you can still adopt Clarx as an extension layer:

• Use the vocabulary and principles when reviewing or extending your existing components
• Add the AI rules so that AI generates code aligned with your system instead of inventing patterns
• Copy individual components (like Badge, Alert, ToolCall) that your system does not yet have
• Use the semantic prop pattern as a model for new components you build

Many teams will not adopt the reference components wholesale. That is fine. The most portable part of Clarx is the thinking, not the files.