> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 

## Overview

Retaintive is a vertical SaaS platform for gym and fitness studio operations — combining Conversation Intelligence (CI), Business Intelligence (BI), and AI-driven automation to optimize lead conversion and member retention through phone call analytics.

The design system serves **three distinct user personas**: Studio Owners (strategic overview), Managers (team performance), and Front-desk Staff (daily action queue). The visual language must simultaneously convey **data trustworthiness** (BI dashboards), **urgency clarity** (task prioritization), and **approachability** (daily-use tool, not an overwhelming analytics cockpit).

The style is **Modern Professional with Clarity Focus**: clean card-based layouts, generous whitespace, and a restrained 6-color semantic palette that maps directly to business outcomes — purple for brand/active, blue for informational, green for positive, yellow for caution, pink for urgent, and teal for neutral surfaces.

## Colors

The palette is built on **semantic meaning over decoration**. Every color has a specific business purpose — agents and developers should never reach for a color without knowing what it _communicates_.

- **Primary (Purple #A571FE)**: Brand identity, active states, primary CTA buttons, selected navigation items, and chart emphasis lines. Purple was chosen to differentiate from the sea of blue-and-green SaaS tools in the fitness industry (Mindbody=blue, Zenoti=green, Glofox=teal).

- **Secondary (Blue #32B6E3)**: Informational contexts — info cards, hyperlinks, secondary buttons, chart auxiliary data. Blue signals "this is context, not action."

- **Success (Green #1FD76F)**: Positive outcomes — completed tasks, upward trend indicators, "Ongoing" status badges, revenue increases. Only use for genuinely good outcomes.

- **Warning (Yellow #FCC609)**: Attention-needed states — "Due Soon" badges, medium-priority tasks, metrics approaching thresholds. Yellow means "not bad yet, but will be if ignored."

- **Alert (Pink #EF58AD)**: Urgent/negative states — overdue tasks, high-priority alerts, negative trends, conversion drops. Pink (not red) keeps urgency without the anxiety of traditional error-red in a tool used 8 hours/day.

- **Surface (Teal #A7E4E2)**: Neutral decorative backgrounds — card fills in data-dense areas, subtle hover states, chart background areas. Never use for semantic meaning.

Each color has a **5-stop tint scale** (10%, 30%, 50%, 100%, Dark) designed for layered usage: 10% for backgrounds/fills, 30% for borders/hover, 50% for icons/secondary elements, 100% for text/primary elements, Dark for text-on-light-tint contexts.

**Neutral scale** provides text and structure: `#030213` (primary text), `#717182` (secondary text), `#CBCED4` (borders), `#E9EBEF` (dividers), `#F3F4F6` (hover), `#F8F9FA` (page background), `#FFFFFF` (card surface).

## Typography

The system uses **Inter** — a typeface designed specifically for screen readability with open apertures and optimized for UI density. Inter provides excellent legibility at small sizes (critical for data-heavy dashboard tables) while maintaining personality at display sizes.

- **Display/Headlines**: Bold weights (700-800) with negative letter-spacing for density. Used sparingly — one display element per page maximum (e.g., the main KPI number).

- **Title**: Semi-bold (600) for section headers, card titles, and navigation labels. The workhorse of hierarchy — most screens use title-lg and title-md more than any other level.

- **Body**: Regular weight (400) at 14-16px for content text, table cell data, descriptions. Line-height of 1.43-1.5x ensures readability in dense data contexts without wasting vertical space.

- **Label**: Semi-bold to medium (500-600) at 11-14px with slight letter-spacing for metadata, badge text, column headers, timestamps. The subtle tracking increase prevents small text from feeling cramped.

**Rule**: Never use more than 3 typographic levels on a single card. A KPI card should be: one `headline-lg` for the number, one `label-md` for the metric name, one `body-md` for the trend description. Nothing more.

## Layout & Spacing

The layout follows a **sidebar + main content** model with a fixed left sidebar (240px collapsed to 64px) and a scrollable main area.

- **Spacing unit**: 4px base. All dimensions are multiples of 4px. Common gaps: 8px (between related items), 16px (between sections within a card), 24px (between cards), 32px (between page sections).

- **Card-based architecture**: Every piece of content lives in a card (`rounded-lg`, white background, 1px `outline-variant` border). Cards never have colored backgrounds — color only appears in badges, chart elements, and interactive states within cards.

- **Table density**: Tables are the primary data display pattern. Row height is 48px with 16px horizontal padding. Headers are sticky. Selected rows get `primary-10` background.

- **Page structure**: Page title (headline-lg) → Filter bar (if applicable) → Primary content area (cards in 1-3 column grid) → Pagination/footer. No more than 3 column widths on desktop; single column on tablet.

- **Whitespace philosophy**: "Breathable but not wasteful." Data-dense screens (Lead Tracker, Call List) use tighter spacing (sm/md). Overview screens (Dashboard) use generous spacing (lg/xl). The user's cognitive load determines the density.

## Elevation & Depth

This design system uses **flat design with subtle borders** rather than shadow-based depth. This is a deliberate choice for a data-heavy application — shadows add visual noise that competes with data comprehension.

- **Level 0 (Page)**: `background` (#F8F9FA) — the page canvas.
- **Level 1 (Cards)**: `card` (#FFFFFF) with 1px `outline-variant` border. No shadow by default.
- **Level 2 (Elevated)**: Dropdowns, popovers, modals use `shadow-lg` (0 10px 15px -3px rgba(0,0,0,0.1)) — the only place shadows appear.
- **Level 3 (Overlay)**: Modal backdrop with `rgba(0,0,0,0.4)` overlay.

**Exception**: Hover states on cards may add a subtle `shadow-sm` to signal interactivity. This is the only case where Level 1 elements gain shadow.

## Shapes

The shape language is **Softly Rounded** — not pill-shaped (too playful for B2B), not sharp (too aggressive for a daily-use tool). The radius scale increases with component size.

- **Small elements** (badges, chips): `rounded-full` (pill shape is acceptable at small sizes).
- **Inputs, buttons**: `rounded-DEFAULT` (8px) to `rounded-md` (12px) — structured but approachable.
- **Cards, panels**: `rounded-lg` (16px) — the dominant radius in the UI. Every card uses this.
- **Modals, popovers**: `rounded-xl` (24px) — slightly more rounded to feel "floating."

**Critical rule**: Never mix `rounded-lg` and `rounded-xl` for cards on the same screen. The old/new route inconsistency (rounded-lg in `/calls` vs rounded-xl in `/calls-v3`) is the #1 source of visual dissonance. Pick one per component type and enforce it everywhere.

## Components

### Buttons

Primary buttons (purple filled) are for the **single most important action** per section. Secondary buttons (white with border) are for all other actions. Ghost buttons (text-only with hover background) are for tertiary/destructive actions.

**Sizing**: Default height 36px. Use 32px for compact contexts (table row actions). Use 40px for hero CTAs (empty states, onboarding).

### Cards & Tables

Cards contain either a **metric summary** (KPI number + trend + label) or a **data table** (header + rows + pagination). A card never contains both a prominent metric AND a full table — split them.

Selected table rows use `primary-10` background with a 2px left border in `primary`. This is the mandatory "selection state" that prevents the "I don't know which row I clicked" problem (U8 in the UI audit).

### Badges & Status Indicators

Badges always use the `{color}-10` background with `{color}-dark` text. Never use full-saturation backgrounds for badges — they compete with buttons for attention.

| Status           | Background   | Text           | Example              |
| ---------------- | ------------ | -------------- | -------------------- |
| Ongoing/Active   | success-10   | success-dark   | Task in progress     |
| Due Soon         | warning-10   | warning-dark   | Approaching deadline |
| Overdue/Critical | alert-10     | alert-dark     | Missed SLA           |
| Info/Neutral     | secondary-10 | secondary-dark | Metadata tag         |

### Charts (ECharts)

The chart color sequence is: primary → secondary → success → warning → alert → surface. This ensures adjacent chart segments always have sufficient contrast. Never hardcode hex values in chart configs — reference the token names.

### Sidebar Navigation

Active item: `primary-10` background + `primary` text + `primary` left border (2px).
Hover item: `background-hover` background.
Default item: transparent background + `on-surface-secondary` text.

## Do's and Don'ts

**Do:**

- Use `primary` for the single most important action per visible section
- Use the 5-stop tint scale: 10% for backgrounds, Dark for text-on-light
- Keep card radius at exactly `rounded-lg` (16px) — no exceptions
- Use `outline-variant` (1px border) for card boundaries, not shadows
- Maintain minimum 4.5:1 contrast ratio for all text (WCAG AA)
- Use `label-md` (12px/600) for table headers and metadata — never body styles
- Show selection state (primary-10 bg + left border) on all interactive list/table rows

**Don't:**

- Don't use full-saturation colors as backgrounds (use -10 tints instead)
- Don't mix rounded-lg and rounded-xl cards on the same page
- Don't add shadows to cards (borders only; shadows are for elevated overlays)
- Don't use more than 3 semantic colors on a single card component
- Don't hardcode hex values in Vue components — use CSS tokens / Tailwind theme
- Don't create new color shades outside the 5-stop scale — the system is complete
- Don't use `surface` (teal) for status meaning — it's decorative only
- Don't use icon-only buttons without tooltip or aria-label (U10 audit finding)
- Don't style interactive chips identically to readonly badges (U11 audit finding)