Baseline UI — Design System Reference
When invoked, read and reference these canonical source files before answering any design question:
There is no single token file. The tokens resolve through a three-layer cascade, and the LAST layer wins. Read all three, in this order:
frontend/src/styles/tokens.css— 101 custom properties on:root. Reached viaglobal.css, which@imports it. Imported atindex.tsx:23.frontend/src/styles/brand-bridge.css— redefines 21 of those same properties on:root, and is imported atindex.tsx:26, AFTERglobal.css. Same selector, same specificity, later source order, so for those 21 this file is what renders.frontend/src/colaberry/tokens/*.css(colors.css,fonts.css, …) — what layer 2 pointsvar()at, and therefore where the literal value actually lives.
Also: frontend/src/styles/responsive.css (breakpoints, accessibility rules) and
frontend/src/components/Layout/AdminLayout.tsx (admin shell layout).
Color Palette (CSS Custom Properties)
Use the RENDERS column. The tokens.css column is what that one file says and is kept
here only so the difference is visible — it is not what the browser paints.
| Token | RENDERS AS | tokens.css says |
Usage |
|---|---|---|---|
--color-primary |
#FB2832 |
#FB2832 |
Colaberry cherry — headings and brand. White text on it is 3.85:1 and FAILS WCAG AA. Do not use it as a fill behind white text; see the contrast table below |
--color-primary-light |
#FD5760 |
#C20E1E |
Links, hover, focus outlines. A light coral, not a deep cherry. White on it is 3.13:1, the worst ratio in the system |
--color-secondary |
#E5121D |
#e53e3e |
CTAs, warnings, destructive actions |
--color-accent |
#5BA63C |
#38a169 |
Green — success states, positive indicators |
--color-bg |
#FFFFFF |
#ffffff |
Page background |
--color-bg-alt |
#F8F8F7 |
#f7fafc |
Alternate section backgrounds |
--color-text |
#2B2B2B |
#2d3748 |
Body text. Neutral, not blue-tinted slate |
--color-text-light |
#6B6B6B |
#718096 |
Muted/secondary text |
--color-border |
#E4E4E3 |
#e2e8f0 |
Card borders, dividers |
--color-muted |
#6B6B6B |
#9ca3af |
Identical to --color-text-light at runtime — the two are no longer distinguishable, so do not rely on the contrast between them |
Only --color-primary and --color-bg survive the cascade unchanged. The other nine are
re-pointed, and the neutrals shift from blue-tinted slate to true grey.
White text on a brand red — the ratios, because a hex alone is not enough
This table has been wrong twice, and both times the cause was publishing a value with no evidence attached. A colour can be correctly published and still unusable as a text background.
| Fill | Ratio under white text | Verdict |
|---|---|---|
--red-400 #FD5760 (--color-primary-light, the Bootstrap hover) |
3.13:1 | FAILS AA and AA-large |
--red-500 #FB2832 (--color-primary, --action-bg, what ships) |
3.85:1 | FAILS AA (needs 4.5:1) |
--red-600 #E5121D (--color-secondary, --action-bg-hover) |
4.73:1 | Passes |
--red-700 #C20E1E (--cherry-deep, --action-bg-press) |
6.22:1 | Passes |
Both passing values are already in this product, so an accessible filled button needs no new
colour. Note that red-600 is #E5121D in Colaberry's own ramp, not Tailwind's #DC2626,
which appears nowhere in the brand and would introduce a foreign hue.
Normal-size text needs 4.5:1 (WCAG 1.4.3); the 3:1 allowance is only for 18.66px bold or 24px normal, which almost no button label in this product reaches. Icons and focus rings need 3:1 (WCAG 1.4.11).
This is measured, not asserted. frontend/src/styles/__tests__/actionContrast.test.ts
recomputes every one of these from the real stylesheets on each run and holds a pinned inventory
of the surfaces that currently fail, so a new failure breaks the build. The recolour itself
(AF12.6 step 2) is Aleem's and Ali's decision and has not happened — which is why the failing
values above are still what ships.
Brand palette (in tokens.css, used by the cherry/leaf/berry designs). These four are
NOT redefined by brand-bridge.css, so unlike the table above, tokens.css is the
rendered value here. Note the trap: --cherry-deep really is #C20E1E, while
--color-primary-light — which this file used to label "Cherry deep" — is not:
| Token | Value | Usage |
|---|---|---|
--cherry |
#FB2832 |
Same as --color-primary |
--cherry-deep |
#C20E1E |
Pressed/active states |
--cherry-bg |
#FFF0F1 |
Tinted backgrounds, active nav items |
--leaf |
#77BB4A |
Positive progress bars |
Rule: Never hardcode hex values. Always use var(--color-*) in CSS or reference Bootstrap utility classes that map to these values.
This table has now been wrong twice, and the second time was caused by the fix to the first.
Until 2026-08-25 it listed
--color-primary: #1a365d(navy) — values that appear nowhere intokens.css. The correction told readers to "verify againsttokens.cssrather than trusting this table; a summary can go stale, the source file cannot."That advice is the second bug.
tokens.cssis a source file and it is stale: nine of the ten colours above, and the entire font stack, are overridden at runtime bybrand-bridge.css, which loads three lines later inindex.tsx. So anyone who followed the 2026-08-25 instruction read one real file, correctly, and still got the wrong colour —#C20E1Ewhere the browser paints#FD5760.A single source file is not evidence of a rendered value when more than one file defines the same property. Resolve the whole cascade in load order, or read the computed value off a real page. Corrected 2026-11-09, from a drift audit Mihret Netsereab ran on
product_experience; her three-layer finding is what exposed it.
Typography
- Font stack:
'Roboto', system-ui, -apple-system, 'Segoe UI', sans-serif—brand-bridge.css:48-49sets--font-headingand--font-body, overriding the'Segoe UI'-first stack intokens.css. The product renders in Roboto, not Segoe UI. Monospace is'Roboto Mono', ui-monospace, 'Consolas', 'Monaco', monospace. - Headings:
font-weight: 700,line-height: 1.2,color: var(--color-primary) - Body:
line-height: 1.6,color: var(--color-text) - Links:
color: var(--color-primary-light), underline on hover
Spacing & Layout
- Max width:
--max-width: 1200px - Section padding:
4rem 0(desktop),2.5rem 0(mobile),3rem 0(tablet) - Container:
max-width: var(--max-width),padding: 0 1rem - Admin shell: Dark navbar (
navbar-dark bg-dark),bg-lightmain area,container py-4content wrapper
Bootstrap 5 Component Patterns
These are the canonical patterns used throughout the admin UI:
Cards
<div class="card border-0 shadow-sm mb-4">
<div class="card-header bg-white fw-semibold">Title</div>
<div class="card-body">Content</div>
</div>KPI Stat Cards
<div class="col-md-3">
<div class="card border-0 shadow-sm">
<div class="card-body text-center p-3">
<div class="fs-4 fw-bold text-primary">42</div>
<div class="text-muted small">Metric Label</div>
</div>
</div>
</div>Data Tables
<div class="table-responsive">
<table class="table table-hover mb-0">
<thead class="table-light">...</thead>
<tbody>...</tbody>
</table>
</div>Tab Navigation
<ul class="nav nav-tabs mb-4">
<li class="nav-item">
<button class="nav-link active" onClick={...}>Tab Label</button>
</li>
</ul>Badges
<span class="badge bg-success">active</span>
<span class="badge bg-warning">paused</span>
<span class="badge bg-info">completed</span>
<span class="badge bg-secondary">draft</span>
<span class="badge bg-danger">TEST MODE</span>Filter Bars
<div class="d-flex gap-2 mb-3 flex-wrap align-items-center">
<input class="form-control form-control-sm" style="max-width: 250px" placeholder="Search..." />
<select class="form-select form-select-sm" style="max-width: 150px">...</select>
<div class="ms-auto d-flex gap-2">
<button class="btn btn-outline-primary btn-sm">Action</button>
</div>
</div>Buttons
A filled
.btn-primaryis 3.85:1 under white text and fails WCAG AA today. Two independent paths paint it:global.csssets.btn-primary { background-color: var(--color-primary) !important }, which beatsbrand-bridge.cssregardless of load order, and the vendored design system ships its own.cb-btnonvar(--action-bg). Editing tokens alone changes neither. For new work needing a filled action button, use--color-secondary(#E5121D, 4.73:1) as Aleem instructed, until the ramp is corrected upstream.
<button class="btn btn-primary btn-sm">Primary</button>
<button class="btn btn-outline-secondary btn-sm">Secondary</button>
<button class="btn btn-outline-danger btn-sm">Danger</button>
<button class="btn btn-success btn-sm">Success</button>Form Controls
<label class="form-label small fw-medium">Label</label>
<input class="form-control form-control-sm" />
<div class="form-text">Helper text</div>
<!-- Toggle switch -->
<div class="form-check form-switch">
<input class="form-check-input" type="checkbox" id="sw-id" />
<label class="form-check-label small" for="sw-id">
<span class="fw-medium">Title</span><br />
<span class="text-muted">Description</span>
</label>
</div>Modal Overlays
<div class="modal show d-block" style="backgroundColor: 'rgba(0,0,0,0.5)'">
<div class="modal-dialog modal-lg">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title">Title</h5>
<button class="btn-close" onClick={onClose} />
</div>
<div class="modal-body" style="max-height: 500px; overflow: auto">...</div>
<div class="modal-footer">...</div>
</div>
</div>
</div>Custom CSS Classes (from global.css)
| Class | Purpose |
|---|---|
.card-lift |
Hover: translateY(-4px) + deeper shadow |
.fade-in-section |
Scroll-triggered fade + slide-up animation |
.badge-label |
Small-caps uppercase label badge |
.agent-card |
Bordered card with hover lift for agent/feature cards |
.callout-box |
Left-bordered gradient callout for emphasis |
.timeline-horizontal |
Horizontal step timeline |
.skip-nav |
Skip navigation link for accessibility |
.hero-bg |
Hero section with gradient overlay |
.btn-accent |
Secondary red CTA button |
Responsive Breakpoints
| Breakpoint | Range | Key adjustments |
|---|---|---|
| Mobile | < 576px |
Smaller headings, reduced padding, stacked layouts |
| Tablet | 576px – 992px |
Medium headings, intermediate padding |
| Desktop | > 992px |
Full layout, default spacing |
| Touch targets | < 992px |
Min 44px height/width on buttons, inputs, links |
| iOS zoom prevention | < 992px |
font-size: 16px on form controls |
Accessibility Patterns
- Focus:
outline: 3px solid var(--color-primary-light),outline-offset: 2pxon:focus-visible - Reduced motion: All animations/transitions →
0.01mswhenprefers-reduced-motion: reduce - High contrast: Cards get
2px solidborders,.text-mutedbecomes full contrast, outline buttons get2pxborders
Existing Reusable Components
| Component | Path | Usage |
|---|---|---|
TemperatureBadge |
frontend/src/components/TemperatureBadge.tsx |
Color-coded lead temperature pill (cold/cool/warm/hot/qualified) |
LeadDetailModal |
frontend/src/components/campaign/LeadDetailModal.tsx |
Per-lead drill-down with timeline + temperature history |
AdminLayout |
frontend/src/components/Layout/AdminLayout.tsx |
Admin page shell with dark navbar |