## Clinia — DESIGN.md

> A plain-text design system for AI agents and engineers. Read this before generating any Clinia interface. It encodes the Clinia brand — color, type, shape, motion — as one shared color truth with two pluggable shape systems (**Sera** for brand/editorial surfaces, **Luma** for product/clinical apps).
>
> **Source of truth:** the raw [`ui.clinia.dev/DESIGN.md`](https://ui.clinia.dev/DESIGN.md).

---

## 1. Visual Theme & Atmosphere

Clinia feels **calm, clear, and human** — trustworthy and precise without ever turning cold. Everything is designed to **close the loop**: connect providers and patients, resolve their tasks with clarity, and bring people closer to answers and peace of mind. Deep near-black (`Infinite`) anchors the system; a warm cream (`Serene`) replaces harsh white so surfaces feel soft; a single hot orange (`Vital`) carries emphasis and appears sparingly. Purple and tan families provide quiet supporting range.

Two registers, one brand:

- **Sera** — typography-first, print-inspired. Square corners, hairline borders, no shadows, tracked/uppercase controls. For the marketing site and editorial content where the Gothia Serif + CircularXX pairing does the work.
- **Luma** — rounded geometry, soft real elevation, breathable spacing, calm motion. For clinical workflows, search consoles, login, settings, dashboards. **This is the default for generated product UI.**

Guiding feel: confident and quiet. Let negative space and one accent do the talking. Never busy, never loud, never more than one Vital moment per view.

---

## 2. Color Palette & Roles

### 2.1 Semantic tokens (use these — never raw brand hex)

Components reference roles, not colors. Roles adapt automatically across light/dark. Tailwind utilities: `bg-primary`, `text-foreground`, `border-border`, etc.

| Token | Role | Light | Dark |
| --- | --- | --- | --- |
| `background` | Page / app background | `#fffdf9` Serene | `#1a1a1e` Infinite |
| `foreground` | Default text | `#1a1a1e` Infinite | `#fffdf9` Serene |
| `card` / `popover` | Raised surface | `#ffffff` | `#232327` |
| `card-foreground` | Text on cards | `#1a1a1e` | `#fffdf9` |
| `primary` | Primary action fill | `#1a1a1e` Infinite | `#fffdf9` Serene |
| `primary-foreground` | Text on primary | `#fffdf9` | `#1a1a1e` |
| `secondary` | Low-emphasis surface | `#fcf8ef` Remedy | `#333333` Infinite-5 |
| `secondary-foreground` | Text on secondary | `#1a1a1e` | `#fffdf9` |
| `muted` | Muted surface | `#fcf8ef` Remedy | `#333333` |
| `muted-foreground` | Captions, placeholders | `#666666` Infinite-4 | `#cdcdcd` Infinite-2 |
| `accent` | **Brand emphasis (Vital)** | `#ff5c00` Vital | `#ff5c00` Vital |
| `accent-foreground` | Text on accent | `#1a1a1e` **(dark, never white)** | `#1a1a1e` |
| `destructive` | Error / danger | `#b91c1c` | `#ef6b5c` |
| `success` | Positive feedback | `#2d7d5e` | `#4ea985` |
| `warning` | Caution | `#cca44f` Noble | `#dbbe87` Beige-5 |
| `border` / `input` | Hairlines, field edges | `#e2e2e2` Infinite-1 | `#333333` Infinite-5 |
| `ring` | Focus ring | `#ff5c00` Vital | `#ff5c00` Vital |

Chart palette: `chart-1..5` draw across the brand families (Vital, Thistle, Noble, Trust, Purple-5 in light).

### 2.2 Raw brand palette (24 swatches, 4 families)

Access via `--clinia-*` variables or `bg-brand-vital` etc. **only when semantic tokens genuinely can't express the intent.**

**Foundation (Infinite)** — anchors the system
`#1a1a1e` Infinite · `#333333` Infinite-5 · `#666666` Infinite-4 · `#999999` Infinite-3 · `#cdcdcd` Infinite-2 · `#e2e2e2` Infinite-1

**Beige / Tan** — warm neutrals
`#fffdf9` Serene · `#fcf8ef` Remedy · `#f1e3cb` Beige-3 · `#ecd9b9` Remedy-dark · `#dbbe87` Beige-5 · `#cca44f` Noble

**Purple** — cool accent family
`#faf7ff` Purple-1 · `#f8f1ff` Aura · `#ede5f6` Purple-3 · `#e3daed` Thistle · `#cabbdb` Purple-5 · `#b3a0ae` Purple-6

**Peach / Orange** — warm accent family
`#ffccaf` Mend · `#fd945f` Peach-2 · `#ff5c00` **Vital** · `#cb6a3d` Peach-4 · `#b3724c` Peach-5 · `#95795c` Trust

### 2.3 The Vital rule (critical)

**Vital orange (`#ff5c00`) is always paired with dark `Infinite` text — never white.**
White-on-Vital ≈ 3.1:1 (fails WCAG AA for normal text). Infinite-on-Vital ≈ 5.6:1 (passes). This is why `accent-foreground` is dark in both themes.

All 20 semantic foreground/background pairs are verified WCAG AA in both themes (12 reach AAA).

---

## 3. Typography Rules

Three licensed families (self-hosted `.woff2`; fallbacks tuned to minimize layout shift):

| Family | Role | Stack | Weights used |
| --- | --- | --- | --- |
| **Display** | Hero, editorial headlines | `"Gothia Serif", "GT Sectra", "Tiempos Headline", Georgia, serif` | Book 400 (Display XL/L), Regular 500 (Display M/S) |
| **Sans (UI)** | Everything else | `"CircularXX", "Inter", -apple-system, …, sans-serif` | Book 400 (body), Regular 450 (titles), Medium 500 (labels) |
| **Mono** | Eyebrow labels, code, dev body | `"CircularXX Mono", "JetBrains Mono", ui-monospace, …` | Regular 400 |

Utilities: `font-display`, `font-sans`, `font-mono`.

### Type scale (names mirror the brand text styles)

| Token | Size | Typical use |
| --- | --- | --- |
| `text-display-xl` | 96px | Hero (Gothia) |
| `text-display-l` | 88px | Hero (Gothia) |
| `text-display-m` | 72px | Section hero |
| `text-display-s` | 56px | Large headline |
| `text-title-xl` | 80px | Page title |
| `text-title-l` | 64px | Page title |
| `text-title-m` | 40px | Section title |
| `text-title-s` | 32px | Subsection |
| `text-title-xs` | 24px | Card title |
| `text-body-xl` | 32px | Lead paragraph |
| `text-body-l` | 24px | Intro copy |
| `text-body-m` | 16px | **Default body** |
| `text-body-s` | 14px | Secondary / UI |
| `text-body-xs` | 12px | Fine print |
| `text-eyebrow-l` | 16px | Eyebrow label |
| `text-eyebrow-s` | 10px | Eyebrow label |

### Rules

- **Headlines set `font-display` (Gothia Serif); body sets `font-sans` (CircularXX).** Never body copy in the serif.
- **Eyebrows** are mono, uppercase, letter-spaced: `font-mono uppercase tracking-widest text-muted-foreground`. Tracking = `--tracking-eyebrow` (0.18em in Sera, 0.08em in Luma).
- Heading tracking is slightly negative in Luma (`-0.015em`) and neutral in Sera; use `tracking-tight` on large display type.
- Line-height: tight on display (~1.05), 1.7 on body (`leading-7`).

---

## 4. Brand Assets & Brand World

The shipped brand assets live in the web app's `public/` and install via the registry. **Never redraw the mark or the band geometry — always re-export from the brand file.** Monochrome brand SVGs are single-color `currentColor`: recolor with CSS (`text-*`), or a CSS `mask` when the SVG is loaded through `<img>` (an `<img>`-referenced SVG can't inherit `currentColor`). One file per asset — no per-color duplicates.

### Logo

- **Logomark** (the "C") and **logotype** (the "Clinia" wordmark) — single-color only, never multi-color or gradient. Use the wordmark where there's room; fall back to the mark in tight/square contexts (avatars, favicons).
- Default color: **Infinite** on light, **Serene** on dark. The mark may take any single brand color (colorway) on a contrasting approved background (Serene / Remedy / Infinite) — never on Vital, busy imagery, or a low-contrast tint.
- Minimum size: mark **16px**, wordmark **80px**. Clear space ≥ the height of the "C" opening.
- `public/logomark.svg` · `public/logotype.svg` — install `@clinia/brand-logo` — guide [`/docs/brand-assets`](https://ui.clinia.dev/docs/brand-assets).

### Favicon & avatars

- **Favicon:** the mark in a Remedy circle, identical on light and dark browser chrome. The committed RealFaviconGenerator set in `public/` (`favicon.svg`/`.ico`, `apple-touch-icon.png`, `web-app-manifest-{192,512}.png`, `site.webmanifest`) is the source of truth any Clinia app copies wholesale; regenerate from `public/favicon.svg`.
- **Avatars:** Infinite mark on Remedy (light) / Serene mark on Infinite (dark), in square and circle crops — `public/brand/avatars/avatar-{light,dark}.{svg,png}`.

### The Infinity Band — line & shape

Clinia's visual world beyond the logo. One form, two expressions:

- **Line language** — 2D linework: uniform stroke, overlapping, tapering; keep the **tapered twist** as the focal point. `currentColor` SVGs (`public/bands/line-1…10.svg`).
- **Shape language** — 3D dimensional bands, brand-color gradients only, shown within a full 3D environment. **Renders best on a background of color scheme Infinite.** (`public/bands/shape-1…7.webp`.)
- **Closing the loop** — the signature lockup: the open loop (C) resolving into the closed loop (O), echoing the mark's closed "C". `public/brand/closing-the-loop.svg` (+ `closing-the-loop/1…4.svg` glyphs).
- Install `@clinia/infinity-band` — guide [`/docs/line-and-shape`](https://ui.clinia.dev/docs/line-and-shape).

### Icons

Functional UI icons ship configured as **HugeIcons** (`iconLibrary: "hugeicons"` in `components.json`, set by `@clinia/base`) — the default for controls, navigation, and product surfaces. This is only a default: apps aren't locked in and may use **lucide** or another richer icon library. Clinia ships **no custom product icons** and none are planned — reach for an established library rather than drawing your own.

---

## 5. Component Stylings

Concrete values from the shipped components. Interactive elements **always** carry a visible focus ring and honor `aria-invalid`.

### Buttons

- Shape: fully rounded (`rounded-4xl` → pill). Weight `font-medium`, `text-sm`.
- Sizes: `xs` h-24px · `sm` h-32px · `default` h-36px · `lg` h-40px · plus square `icon` variants (24–40px).
- Press feedback: `active:translate-y-px`. Disabled: `opacity-50`, no pointer events.
- Focus: `focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/30`.
- Variants:
  - `default` — `bg-primary text-primary-foreground`, hover `bg-primary/80` (Infinite fill in light, Serene in dark).
  - `outline` — `border-border bg-background`, hover `bg-muted`.
  - `secondary` — `bg-secondary` warm cream, subtle hover mix.
  - `ghost` — transparent, hover `bg-muted`.
  - `destructive` — tinted `bg-destructive/10 text-destructive` (not a solid red fill).
  - `link` — `text-primary underline-offset-4 hover:underline`.
- **Sera** adds `text-transform: uppercase; letter-spacing: 0.08em` to buttons; **Luma** keeps them sentence-case with soft 180ms hover transitions.
- **Vital as a button fill** must use `text-accent-foreground` (dark). Prefer `primary` for the main action and reserve Vital for a single high-emphasis moment.

### Cards

- `rounded-xl border border-border bg-card text-card-foreground shadow-sm`, padding `p-6`, header/content gap `1.5`.
- Sera: no shadow — separation is a 1px border only. Luma: real soft elevation (`shadow-sm/md/lg`), dark mode bumps shadow opacity so lift still reads.

### Inputs / textareas / selects

- `h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm`.
- Placeholder: `text-muted-foreground`. Disabled: `opacity-60`, not-allowed cursor.
- Focus: `ring-2 ring-ring ring-offset-2` (Vital ring, 2px offset).
- Invalid: `aria-invalid="true"` → `border-destructive` and destructive focus ring.
- Luma adds an inner hairline shadow at rest; Sera strips all inner shadow.

### Badges

- `rounded-full border px-2.5 py-0.5 text-xs font-medium`. Variants: `default` (primary), `secondary`, `accent` (Vital + dark text), `outline`, `destructive` (solid).

### Focus (global)

Every interactive element gets `outline: 2px solid var(--ring)` (Vital) with `outline-offset: 2px` via `:focus-visible`. Visible on any surface in either theme. Never remove it.

---

## 6. Layout Principles

- **Spacing** follows Tailwind's 4px scale. Section rhythm is generous — brand pages breathe (`py-20`+, section gaps `mb-24`); product surfaces are denser but still calm.
- **Container widths:** marketing content `max-w-5xl`; docs/reading column `max-w-3xl`; app shells `max-w-7xl` with a sidebar.
- **Grid:** simple responsive grids (`grid gap-6 sm:grid-cols-2 md:grid-cols-3`). Avoid nested cards-in-cards.
- **Whitespace is a feature.** When in doubt, add space, not borders. One clear focal point per view.
- **Radius scale** (derived from one `--radius` base): `sm = base−4px`, `md = base−2px`, `lg = base`, `xl = base+4px`, up to `4xl`. Base is `0.5rem` neutral, `0` in Sera, `0.875rem` in Luma.

---

## 7. Depth & Elevation

Elevation is a **shape-layer** decision, not a color one.

| Level | Neutral (default) | Sera | Luma |
| --- | --- | --- | --- |
| `shadow-sm` | `0 1px 2px rgb(0 0 0 / .04)` | `0 0 0 1px border` (hairline) | soft 2-layer, elevated |
| `shadow-md` | light 2-layer | hairline | `0 2px 4px / 0 4px 12px` |
| `shadow-lg` | `0 8px 24px -8px / .10` | hairline | `0 8px 24px / 0 16px 48px` |

- **Sera** has no shadows — depth is expressed only through 1px borders and negative space.
- **Luma** uses real but subtle elevation; cards earn `sm`, popovers/dialogs earn more. Dark mode raises shadow opacity (0.30–0.40) so lift stays legible.
- Surface hierarchy in dark mode: `background #1a1a1e` → `card #232327` (one stop up) → borders `#333333`.

---

## 8. Do's and Don'ts

**Do**
- Use semantic tokens (`bg-primary`, `text-muted-foreground`), never raw brand hex in components.
- Pair Vital with dark `Infinite` text (`accent-foreground`), always.
- Reserve Vital for a single emphasis moment per view; let Infinite/Serene carry the rest.
- Set `font-display` on headlines, `font-sans` on body, `font-mono` on eyebrows.
- Keep `focus-visible:ring-2 focus-visible:ring-ring` on every interactive element.
- Pick one shape system per surface: Sera for brand, Luma for product.
- Provide `alt` on images and an `AvatarFallback` for avatars.

**Don't**
- ❌ White text on Vital orange (fails WCAG AA).
- ❌ Body copy set in Gothia Serif, or headlines in mono.
- ❌ Raw values like `bg-[#ff5c00]` when `bg-accent` exists.
- ❌ Shadows in Sera, or square hairline-only cards in Luma — don't cross the shape layers.
- ❌ Multiple competing accent colors in one view.
- ❌ Removing focus outlines or ignoring `prefers-reduced-motion`.
- ❌ Pure `#ffffff` page backgrounds — use `Serene` (`background`).

---

## 9. Responsive Behavior

- **Breakpoints:** Tailwind defaults — `sm 640` · `md 768` · `lg 1024` · `xl 1280` · `2xl 1536`.
- **Type scales down:** large display type steps down at each breakpoint (e.g. `text-5xl md:text-6xl lg:text-7xl` for heroes). Body stays `16px`.
- **Layout:** single column on mobile; introduce sidebars/multi-column at `md`+. Marketing hero stacks vertically on mobile, splits at `md`.
- **Touch targets:** default control height is 36–40px; on touch-primary surfaces bump interactive targets toward **44px minimum**. Icon buttons ≥ `icon-sm` (32px) on touch.
- **Motion:** `prefers-reduced-motion: reduce` is honored globally — all animation/transition durations collapse to ~0ms. Never bypass it.

---

## 10. Agent Prompt Guide

Copy-paste rules for generating Clinia UI.

**Setup**
```bash
pnpm dlx shadcn@latest init https://ui.clinia.dev/r/base.json
pnpm dlx shadcn@latest add @clinia/theme
# product surfaces → apply the Luma shape layer:
pnpm dlx shadcn@latest add --registry https://ui.clinia.dev/r style-luma
```
```css
/* app/globals.css */
@import "@clinia/tailwindcss";
@import "./style-luma.css"; /* product apps */
```
```html
<html class="dark" data-style="luma"> … </html>
<!-- data-style: "luma" (product, default) | "sera" (brand) | omit for neutral -->
<!-- class="dark" toggles dark mode; light is default -->
```

**Non-negotiable rules**
1. Style with **semantic Tailwind tokens** only: `bg-background text-foreground`, `bg-primary text-primary-foreground`, `bg-card`, `border-border`, `text-muted-foreground`, `bg-accent text-accent-foreground`.
2. **Never** put white text on `accent`/Vital — its foreground is dark `Infinite`.
3. Headlines → `font-display` (Gothia Serif). Body → `font-sans`. Eyebrows → `font-mono uppercase tracking-widest text-muted-foreground`.
4. Every interactive element → `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`.
5. Default action → `primary`. Use Vital `accent` for **one** emphasis moment per view.
6. Page background is `Serene` (`bg-background`), not pure white.
7. Product = Luma (rounded, soft shadows). Brand = Sera (square, hairlines, uppercase tracked controls). Don't mix within one surface.
8. Respect `prefers-reduced-motion`; provide `alt` text and avatar fallbacks.

**Token cheat-sheet**
`Vital #ff5c00` (accent, dark text) · `Infinite #1a1a1e` (primary/foreground) · `Serene #fffdf9` (background) · `Remedy #fcf8ef` (secondary/muted) · `#666666` muted text (light) · borders `#e2e2e2` (light) / `#333333` (dark) · radius `0` Sera / `0.875rem` Luma.

---

*Generated from `@clinia/tailwindcss` (`tokens.css`, `theme.css`, `style-sera.css`, `style-luma.css`). When tokens change, update this file. Format follows the [DESIGN.md](https://github.com/VoltAgent/awesome-design-md) convention.*