# Opus Design System

The Opus design system is a white-label UI foundation for the manager dashboard.
It is built from a small set of theme drivers, semantic tokens, and reusable
React primitives. The source of truth is src/app/globals.css.

## Goals

- Keep product UI calm, mostly white, and content-first.
- Support tenant theming from a brand color and a canvas color.
- Use semantic tokens in components instead of raw hex, Tailwind grays, or one-off CSS.
- Keep status colors stable so meaning survives white-label branding.
- Make primitives feel consistent across dashboard, builder, docs, and training flows.

## Token Layers

1. Theme drivers — runtime values derived from the two tenant inputs (brand + canvas).
2. Foundation tokens — low-level colors, alpha, radius, shadows, type, status ramps.
3. Semantic tokens — product-facing roles consumed by components.

Components should only touch layer 3. Layers 1 and 2 exist for the theme engine.

## Theme Drivers

Defaults below are Opus brand #1D82FF on canvas #F9F8F6.

  --hue:       85       /* neutral surface + text hue (from canvas) */
  --c-bg:      0.003    /* neutral surface chroma / tint */
  --c-tx:      0.008    /* text + icon chroma tuning constant */
  --bg-l:      0.979    /* canvas lightness — anchors the off-white background */
  --contrast:  0.84     /* separation between surface / border / text steps */
  --brand-h:   257      /* brand hue */
  --brand-c:   0.195    /* brand chroma (0 = neutral dark primary) */
  --brand-l:   0.62     /* brand lightness */

## Neutral Ramp (OKLCH)

The neutral scale is an OKLCH grayscale tinted by the canvas hue — not a fixed
Tailwind gray. Surface steps stay near white and tint with the tenant; text
steps use the text chroma constant.

  --color-gray-0:    oklch(1 0 0)                                  /* pure white */
  --color-gray-25:   oklch(0.992 var(--c-bg) var(--hue))
  --color-gray-50:   oklch(var(--bg-l) var(--c-bg) var(--hue))     /* canvas */
  --color-gray-100:  oklch(calc(1 - 0.035 * var(--contrast)) var(--c-bg) var(--hue))
  --color-gray-200:  oklch(calc(1 - 0.055 * var(--contrast)) var(--c-bg) var(--hue))
  --color-gray-300:  oklch(calc(1 - 0.09  * var(--contrast)) var(--c-bg) var(--hue))
  --color-gray-400:  oklch(0.72 var(--c-tx) var(--hue))
  --color-gray-500:  oklch(0.58 var(--c-tx) var(--hue))
  --color-gray-600:  oklch(0.45 var(--c-tx) var(--hue))
  --color-gray-700:  oklch(0.36 var(--c-tx) var(--hue))
  --color-gray-800:  oklch(0.29 var(--c-tx) var(--hue))
  --color-gray-900:  oklch(0.22 var(--c-tx) var(--hue))
  --color-gray-950:  oklch(0.16 var(--c-tx) var(--hue))

## Alpha Ramp

Adaptive overlays for borders, states, and scrims.

  --color-alpha-dark-2:   oklch(0 0 0 / 0.02)
  --color-alpha-dark-4:   oklch(0 0 0 / 0.04)
  --color-alpha-dark-6:   oklch(0 0 0 / 0.06)
  --color-alpha-dark-8:   oklch(0 0 0 / 0.08)
  --color-alpha-dark-12:  oklch(0 0 0 / 0.12)
  --color-alpha-dark-16:  oklch(0 0 0 / 0.16)
  --color-alpha-light-4:  oklch(1 0 0 / 0.04)
  --color-alpha-light-8:  oklch(1 0 0 / 0.08)
  --color-alpha-light-12: oklch(1 0 0 / 0.12)
  --color-alpha-light-16: oklch(1 0 0 / 0.16)

## Brand

  --color-brand-primary: oklch(var(--brand-l) var(--brand-c) var(--brand-h))
  --color-brand-hover:   oklch(calc(var(--brand-l) - 0.05) var(--brand-c) var(--brand-h))
  --color-brand-active:  oklch(calc(var(--brand-l) - 0.09) var(--brand-c) var(--brand-h))
  --color-brand-bg:      oklch(var(--brand-l) var(--brand-c) var(--brand-h) / 0.10)
  --color-brand-border:  oklch(var(--brand-l) var(--brand-c) var(--brand-h) / 0.38)
  --color-brand-text:    oklch(calc(var(--brand-l) - 0.12) var(--brand-c) var(--brand-h))

## Semantic Colors

Backgrounds:

  bg-bg-canvas     -> --color-gray-50    /* lowest app background */
  bg-bg-primary    -> --color-gray-0     /* primary white surface */
  bg-bg-subtle     -> --color-gray-25    /* almost-white subtle background */
  bg-bg-secondary  -> --color-gray-100   /* grouped secondary surface */
  bg-bg-tertiary   -> --color-gray-200   /* recessed / inset surface */
  bg-bg-elevated   -> --color-gray-0     /* floating UI */

Text:

  text-text-primary    -> --color-gray-950
  text-text-secondary  -> --color-gray-600
  text-text-tertiary   -> --color-gray-500
  text-text-disabled   -> --color-gray-400
  text-text-inverse    -> --color-gray-0

Icons:

  text-icon-primary    -> --color-gray-800
  text-icon-secondary  -> oklch(0.50 var(--c-tx) var(--hue))
  text-icon-tertiary   -> oklch(0.64 var(--c-tx) var(--hue))
  text-icon-disabled   -> oklch(0.76 var(--c-tx) var(--hue))

Borders + states:

  border-border-primary    -> --color-alpha-dark-8
  border-border-secondary  -> --color-alpha-dark-12
  border-border-tertiary   -> --color-alpha-dark-16
  bg-state-hover           -> --color-alpha-dark-4
  bg-state-pressed         -> --color-alpha-dark-8
  bg-state-selected        -> --color-brand-bg
  ring-state-focus         -> --color-brand-primary
  overlay scrim            -> oklch(0 0 0 / 0.46)

Accent:

  accent-primary             -> --color-brand-primary
  accent-primary-hover       -> --color-brand-hover
  accent-primary-active      -> --color-brand-active
  accent-primary-foreground  -> --color-gray-0
  action-secondary             -> --color-alpha-dark-4
  action-secondary-hover       -> --color-alpha-dark-8
  action-secondary-active      -> --color-alpha-dark-12
  action-secondary-foreground  -> --color-text-primary
  action-destructive             -> --color-status-error-bg
  action-destructive-hover       -> error bg mixed 10% toward error text
  action-destructive-active      -> error bg mixed 16% toward error text
  action-destructive-foreground  -> --color-status-error-text

## Status Colors (fixed, not brand-derived)

  success  bg green-2      text green-11      border green-5
  warning  bg yellow-2     text yellow-11     border yellow-5
  error    bg red-2        text red-11        border red-5
  info     bg teal-2       text teal-11       border teal-5
  remediation bg orange-3  text orange-11     border orange-6
  ai       bg ai-1/10      text ai-1         border ai-1/28

Status is always paired with an icon + label so it survives a red brand.

## Typography

Families:

  --font-sans  Inter Variable   /* product UI + display */
  --font-mono  Geist Mono       /* code, token names, kbd */

Size tokens (name -> rem / px / line-height):

  micro     0.6875rem  11px  1.35
  mini      0.75rem    12px  1.35
  small     0.875rem   14px  1.4
  regular   1rem       16px  1.45    /* body default */
  large     1.125rem   18px  1.4
  title3    1.25rem    20px  1.3
  title2    1.5rem     24px  1.25
  title1    2.25rem    36px  1.1

Weights:

  light 300   normal 450   medium 500   semibold 600   bold 700

Composite utilities:

  title-display       opsz 32, 20px, weight 500, -0.015em
  title-display-bold  opsz 32, 24px, weight 700, -0.02em
  screen-body         opsz 32, 18px, weight 450, -0.01em

## Radius

  --radius:          0.5rem    /* 8px base */
  --radius-control:  0.625rem  /* 10px — compact controls */
  rounded-sm   -> base - 4px   /* 4px  */
  rounded-md   -> base - 2px   /* 6px  */
  rounded-lg   -> base         /* 8px  */
  rounded-xl   -> base + 4px   /* 12px */
  rounded-2xl  -> base * 1.8   /* ~14px */
  rounded-3xl  -> base * 2.2
  rounded-4xl  -> base * 2.6
  rounded-full -> 9999px       /* pills, tabs, buttons */

## Elevation

Base family (pure shadow):

  --shadow-bas-sm:  0 4px 12px rgba(25,25,25,.027), 0 1px 2px rgba(25,25,25,.02)
  --shadow-bas-md:  0 8px 12px rgba(25,25,25,.027), 0 2px 6px rgba(25,25,25,.027)
  --shadow-bas-lg:  0 20px 24px rgba(25,25,25,.05),  0 5px 8px rgba(25,25,25,.027)
  --shadow-bas-dif: 0 12px 32px rgba(25,25,25,.027)
  --shadow-bas-scr: 0 24px 48px rgba(25,25,25,.24),  0 4px 12px rgba(25,25,25,.14)

Outlined family (shadow + 1px hairline ring):

  --shadow-out-sm:  0 2px 4px rgba(0,0,0,.04),       0 0 0 0.5px rgba(42,28,0,.07)
  --shadow-out-md:  0 8px 12px rgba(25,25,25,.027),  0 0 0 0.5px rgba(42,28,0,.07)
  --shadow-out-lg:  0 20px 24px rgba(25,25,25,.05),  0 0 0 0.5px rgba(42,28,0,.07)
  --shadow-out-dif: 0 12px 32px rgba(25,25,25,.027), 0 0 0 0.5px rgba(42,28,0,.07)
  --shadow-out-scr: 0 24px 48px rgba(25,25,25,.24),  0 0 0 0.5px rgba(42,28,0,.07)

Use the smallest shadow that communicates the layer.

## Motion

Use motion only when it clarifies a change, never for decoration. Most
interactions should feel instant: a duration of `0ms` is often the snappiest
and best choice, and the call is context-dependent.

When motion genuinely helps, such as revealing or moving an element, keep it
short and physical with the easing `cubic-bezier(0.175, 0.885, 0.32, 1.1)`:
roughly 150ms for state changes, 200ms for popovers and tooltips, and 300ms for
overlays and modals.

Avoid long, looping, or attention-grabbing animation, and honor
`prefers-reduced-motion` by dropping nonessential motion.

## Components

Avatar, Badge, Button, Card, Checkbox, Divider, Label, Progress, Select,
Tabs, Text Field, Toggle, Tooltip.

Button rule: primary/default buttons must include a visible text label. Do not
use the primary/default variant for icon-only buttons; use secondary, outline,
ghost, or destructive with an aria-label instead.

## Engineering Rules

- Prefer semantic classes over raw CSS variables in component markup.
- Do not hardcode hex values in product UI.
- Do not use raw Tailwind neutral classes for product surfaces.
- Keep shadcn compatibility tokens (--background, --card, etc.) as an adapter layer.
- Status colors stay semantic and fixed across tenants.
- Components should be reusable without tenant-specific branches.