# Chronis AI — Design System & UX Guide **For:** `chronis-ai-agents` (Laravel + Livewire 3 + Alpine + Tailwind) **Purpose:** Single source of truth so every screen Cursor builds is visually and behaviourally consistent. --- ## 1. Design Principles 1. **Calm, dense, operational.** This is a control room, not a marketing site. Information density is good; decoration is not. 2. **Approval is the hero.** The approval flow is the most-used surface. It must be fast, scannable, and never ambiguous about what's about to happen. 3. **State is always visible.** Every agent, task, and approval shows its status at a glance (colour + label, never colour alone — accessibility). 4. **No surprises.** Destructive or external actions (send, reject, delete) always show what will happen and to whom before confirming. 5. **Flat & quiet.** No gradients, no drop shadows beyond functional focus rings, no glow. Borders do the work. --- ## 2. Colour Tokens Define as CSS variables (and mirror in `tailwind.config.js` under `theme.extend.colors`). All must work in light AND dark mode — never hardcode hex in components. ### Brand / neutral ``` --c-bg-page: #F7F6F2 (dark: #1A1A18) --c-bg-surface: #FFFFFF (dark: #242422) --c-bg-subtle: #F1EFE8 (dark: #2C2C2A) --c-border: rgba(0,0,0,0.12) (dark: rgba(255,255,255,0.14)) --c-border-strong: rgba(0,0,0,0.22) (dark: rgba(255,255,255,0.26)) --c-text: #1F1F1D (dark: #F2F0EB) --c-text-muted: #5F5E5A (dark: #A8A69E) --c-text-faint: #888780 (dark: #76746D) ``` ### Semantic (status) ``` success / active fill #E1F5EE text #0F6E56 border #5DCAA5 (dark: fill #085041 text #9FE1CB) info / contacted fill #E6F1FB text #185FA5 border #85B7EB warning / draft fill #FAEEDA text #854F0B border #EF9F27 danger / reject fill #FCEBEB text #A32D2D border #F09595 neutral / paused fill #F1EFE8 text #5F5E5A border #B4B2A9 ``` ### Agent accent colours (one per agent type, used for icon chips only) ``` sales teal fill #E1F5EE text #0F6E56 marketing blue fill #E6F1FB text #185FA5 lead_gen amber fill #FAEEDA text #854F0B retention purple fill #EEEDFE text #3C3489 pr pink fill #FBEAF0 text #72243E deliverability green fill #EAF3DE text #3B6D11 ``` **Rule:** text on any coloured fill uses the dark stop from the SAME family — never black or generic grey. --- ## 3. Typography - **Font:** system UI stack or a single self-hosted sans (e.g. "Inter Tight" or "General Sans"). One family only. No serif except optional empty-state quotes. - **Two weights only:** 400 regular, 500 medium. Never 600/700 — too heavy against the quiet UI. - **Scale:** h1 22px · h2 18px · h3 16px · body 14px · small 13px · micro 12px (never below 11px). - **Line-height:** 1.6 body, 1.3 headings. - **Case:** sentence case everywhere. Never Title Case, never ALL CAPS (except 1px-tracked section eyebrows at 10–11px if needed). - Numbers in metrics: tabular figures, always rounded for display. --- ## 4. Spacing & Layout - Base unit 4px. Use 4 / 8 / 12 / 16 / 24 / 32. - **App shell:** fixed left sidebar 220px + fluid main. Main has a sticky 56–64px topbar + scrollable content (padding 24px). - **Card:** surface bg, 0.5px border, `border-radius: 12px`, padding 16–20px. - **Metric card:** subtle bg, no border, `border-radius: 8px`, padding 14–16px. Muted 12–13px label above, 22–24px/500 value below. - Grids: `repeat(auto-fit, minmax(160px, 1fr))`, gap 12px. --- ## 5. Corner Radius ``` --radius-sm: 6px (pills, badges, small buttons) --radius-md: 8px (inputs, buttons, metric cards) --radius-lg: 12px (cards, panels) --radius-xl: 16px (modals, large containers) ``` Never put rounded corners on single-sided borders (e.g. `border-left` accent → `border-radius: 0`). --- ## 6. Components ### Buttons - **Primary:** solid `--c-text` bg, surface-colour text. Hover: opacity .88. Used once per view max (the main action). - **Secondary:** transparent bg, 0.5px `--c-border-strong`, `--c-text`. Hover: `--c-bg-subtle`. - **Destructive:** danger fill + danger text. Always behind a confirm step. - Height 36px, radius-md, 13–14px label, 6px icon gap. Active: `scale(0.98)`. ### Status badge Pill, radius-sm, 11–12px/500, semantic fill + same-family dark text. Always pair an icon or label with colour (never colour alone). ### Agent card Card + 36px icon chip (agent accent colour) + name (14px/500) + 2-line muted description + footer row (status dot + label + task count). Featured/active card: 2px info border (only allowed 2px border). ### Approval item (most important component) Row: avatar/initials chip · recipient name + role + company · ICP score pill · meta line (channel · industry · size · location) · draft preview block (subtle bg, 2px left border, monospace optional for subject) · action row [Approve · Edit · Reject]. Approve = success style, Reject = danger style, Edit = secondary. ### Tables 14px, 0.5px row borders, no zebra. `table-layout: fixed` in constrained widths. Right-align numbers. Row hover: `--c-bg-subtle`. ### Forms 36px inputs, radius-md, 0.5px border, focus = 2px info ring (`box-shadow: 0 0 0 2px`). Labels 13px muted above field. Never use native browser default styling. ### Empty states Centred, faint icon (32px), one-line muted explanation, single primary action. No illustrations. --- ## 7. Motion - Transitions 120–160ms ease-out on hover/focus/colour only. - One staggered reveal on initial dashboard load is fine; nothing more. - No spinners longer than necessary — agent runs are async, so show task rows entering `running` state, not a blocking loader. - Never animate layout-shifting properties on scroll. --- ## 8. UX Rules 1. **Confirm external actions.** Send / reject / delete always shows recipient + content summary before commit. 2. **Show the why.** Every agent decision (skip, score, draft) records a human-readable reason; surface it on hover/expand. 3. **Approvals expire.** Show a countdown; expired items move to a clearly-labelled state, never vanish. 4. **Cost is always in view.** Each agent shows spend vs daily budget; warn at 80%, block at 100%. 5. **One primary action per screen.** Everything else is secondary. 6. **Optimistic where safe, confirmed where not.** Toggling a skill on/off can be optimistic; sending an email cannot. 7. **Never hide destructive actions behind colour alone.** --- ## 9. Accessibility (WCAG 2.2 AA target) - Contrast ≥ 4.5:1 body, ≥ 3:1 large text & UI borders. Test both themes. - Status conveyed by icon/label + colour, never colour alone. - All interactive elements keyboard-reachable; visible focus ring (2px info, never `outline: none` without replacement). - `aria-label` on icon-only buttons; `aria-live="polite"` on the approvals queue so new items announce. - Forms: every input has a `