Principles
Caret is small enough to fit inside ten rules. Every component, every token, every CLI flag traces back to one of them. When the rules say "no", the code says no — even when it would be easier to add a flag and look the other way.
01 You own the code
caret add prompt copies the component into your repo. Modify, fork, or delete it. Caret is a starting point, not a dependency.
02 Beautiful by default
Caret has one strong opinion about how things should look. You shouldn't need to configure anything to ship a CLI that looks like Vercel or Linear built it.
03 Transactional first
Caret is optimized for CLIs that run a command and exit. Output is inline — scrollback-friendly, log-friendly, copy-paste-friendly. Fullscreen modes exist, but they are opt-in.
04 Never touch the background
Your terminal has a background. Caret does not set it. Ever. A Caret CLI works on light themes, dark themes, Solarized, Dracula, and anything else — because it doesn't fight the user's environment.
05 Respect the user's theme
Foreground text uses the terminal's own foreground color. Semantic colors — success, warning, danger, info — are emitted as ANSI names so they harmonize with the user's theme. Brand colors are truecolor and fixed — that's Caret's visual signature.
06 Color is a bonus, not a requirement
Every semantic state has a symbol: ✓ ✗ ⚠ ℹ. Hierarchy uses bold, dim, and italic before color. NO_COLOR, piped output, dumb terminals, and screen readers all get a first-class Caret experience.
07 Correctness is not opt-in
Caret respects NO_COLOR, detects isatty, adapts to narrow terminals, and gracefully falls back through truecolor → 256 → ANSI 16 → plain. You don't enable any of this. You would have to go out of your way to break it.
08 AI-native from day one
Caret assumes AI tools write most of tomorrow's CLIs. A caret.md instruction file ships with the project so Cursor, Claude Code, and Copilot produce correct Caret code on the first try.
09 Motion has meaning
Every state transition is a designed moment. Spinners resolve into checkmarks, selections slide, progress pulses, errors reveal. Transitions are bounded (≤300ms), inline-safe, and disabled outside a live terminal or when the user prefers reduced motion.
10 Notifications, not beeps
For long-running tasks, Caret can dispatch system notifications via the OS native API. Never terminal bell. Never custom sounds. Notifications are opt-in, threshold-gated (default 10s), respect Do Not Disturb, and fall back silently when unavailable.
Continue with Tokens for the visual vocabulary these principles produce, or AI-native workflow for how the manifesto is enforced when an LLM is writing your CLI.