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.

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.

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):

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

Type scale (names mirror the brand text styles)

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.

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.

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.

• 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

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

/* app/globals.css */
@import "@clinia/tailwindcss";
@import "./style-luma.css"; /* product apps */

<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 convention.