Foundations
Color and semantic roles
Use the native zinc and violet palette with labeled status feedback; keep identity colors separate from operational state.
On this page
Source model
app/globals.css defines background and foreground for each theme. Most surfaces, borders, text, actions and states come from Tailwind v4 utility classes in the components. The exported role mapping makes that implementation understandable without pretending the source already contains a semantic token package.
Role mapping
| Role | Light | Dark | Usage |
|---|---|---|---|
| Canvas | #fafafa / zinc-50 | #09090b / zinc-950 | App body and work area |
| Surface | white | zinc-900 | Cards, fields, dialogs and menus |
| Strong text | zinc-900 / zinc-950 | zinc-100 / white | Titles and primary information |
| Secondary text | zinc-500 | zinc-400 | Descriptions and message metadata |
| Primary action | violet-600 + white | violet-600 + white | New message, submit and selected icon tiles |
| Accent text | violet-700 | violet-300 | Selected supporting controls |
| Border | zinc-200 | zinc-700 / zinc-800 | Control and grouping boundaries |
| Queue selection | zinc-950 + white | white + zinc-950 | Current queue and workspace scope |
Status versus identity
| Family | Meaning | Rule |
|---|---|---|
| Amber | Waiting / follow-up / action needed | Include explicit text and time context. |
| Emerald | Customer / active / ready / delivered | Do not interpret fixture green as verified integration. |
| Red | Junk action / failed / blocked | Pair with explanation and a recovery action when supported. |
| Blue | Prospect / sent | A sent message is not proof of delivery. |
| Company/product/avatar colors | Identity and grouping | Keep name and initials; color is not a permission or urgency signal. |
Composition rules
- Keep theme-specific text and surface classes together.
- Preserve dark alpha surfaces such as violet-500/15; a flat replacement changes the source treatment.
- Do not use the portfolio’s palette inside native specimens or introduce Sonarist colors into portfolio navigation.
- Review muted zinc-400 labels carefully: some light-mode text falls below normal-text contrast requirements.
Source references
| File | Responsibility |
|---|---|
| app/globals.css | Native variables and dark selector |
| components/ui/primitives.tsx | Action, badge, avatar and field classes |
Source palette
- --background
- #fafafa
- --foreground
- #18181b
- --surface
- #ffffff
- --surface-subtle
- oklch(98.5% 0 none)
- --text
- oklch(21% 0.006 285.885)
- --text-secondary
- oklch(55.2% 0.016 285.938)
- --border
- oklch(92% 0.004 286.32)
- --accent
- oklch(54.1% 0.281 293.009)
- --accent-text
- oklch(49.1% 0.27 292.581)
- --accent-surface
- oklch(96.9% 0.016 293.756)
- --on-accent
- #ffffff
Examples from the app
Actual Sonarist components with fictional conversations, people, example.com addresses and simulated operational states. Captured at 2× resolution or higher. Select an image to inspect it full size.
Related topics
Source audit: 2026-10-08 · Revision 10f45d1377b5 · Documentation v1.0.0