rule-design-systemlisted

## Never Do - Inline colors: `text-white`, `bg-black`, `text-gray-500` - Hardcoded values in components - Custom one-off styles **Exception:** Hardcoded colors (`text-white`, `bg-black`) are valid on dynamic gradient backgrounds or explicitly themed surfaces where the background is not a standard theme token. ## Always Do - Define in tailwind.config.ts or index.css first - Use semantic tokens: `text-foreground`, `bg-background`, `text-muted-foreground` - Create component variants for reuse ## Magic UI is the motion layer, and it obeys the tokens above `[measured 2026-09-03]` `magicuidesign/magicui`: MIT, a shadcn registry named `magicui` carrying 247 items typed `registry:ui`. It installs the way the rest of the components do, the code lands in the tree, so it is OURS to gate rather than a dependency to trust. **Everything on this page still applies to it.** A pasted effect arrives carrying literal colors, because a registry cannot know your tokens. Convert them to semantic tokens on the way in, in the same commit, or the first Magic UI component becomes the exception that retires the whole rule. The gradient carve-out above is the only licence, and an animated surface is exactly where somebody will claim it without checking whether an opaque surface sits underneath. **Use it for MOTION and signature moments, never for ordinary controls.** Buttons, inputs, dialogs, menus stay shadcn. Two sources on the same control is how a screen stops reading as one product. **Six ef