Glossary

The vocabulary, defined once so we all mean the same thing when we say it.

A

App layer — Layer 3 in our architecture. The UpNext product code — pages, features, screens. Imports only from @/components/upnext. Never from @/components/ui/* (the lint rule prevents it).

B

Base layer — Layer 1. The shadcn primitives at components/ui/*. Installed by the shadcn CLI, never edited by us, never imported by the app.

C

class-variance-authority (cva) — The library we use to define a wrapper's variant set. It takes a base class string + a variant map and returns a function that resolves to a className. Looks like:

const buttonVariants = cva("base classes", {
  variants: { variant: { primary: "...", secondary: "..." } }
})

Consumer — Any code that uses a wrapper. App pages, features, even another wrapper. Consumers import from @/components/upnext.

D

Dark mode — A different set of semantic token mappings, not a different palette. Same ramps, different role assignments. Lives in the .dark { ... } block of globals.css.

data-upnext attribute — Every wrapper sets this on its root element (e.g. data-upnext="button"). Makes wrappers grep-able in browser inspector and gives tooling a stable anchor.

H

Hue — In oklch, the angle around the color wheel (0–360°). Our primary is at 263° (blue). Status colors sit at distinct hues so they read as different signals.

L

Living documentation — Docs that evolve alongside the code they describe. They live in the same repo, get updated in the same PRs, and are rendered next to the components they document.

N

Neutral — Our single gray ramp. Slightly cool (260° hue, very low chroma 0.002–0.011). The only gray in the system — one ramp, no parallel grays.

O

oklch() — The color format we use everywhere. Three parameters: lightness (0–1), chroma (0–~0.4), hue (0–360°). Compared to hex/rgb, oklch has perceptually-even lightness — oklch(0.5 ...) looks roughly half as bright as oklch(1 ...) to the human eye. Hex doesn't work that way; #888 doesn't look half as bright as #fff.

P

Palette — One of our six color ramps: Primary, Neutral, Error, Success, Warning, Info. Each has 11 steps (50, 100, …, 950).

Pattern-setter — A component that establishes the convention for an entire category. Button, Input, and Card are pattern-setters — they're built deeply right first, then every other wrapper copies their pattern.

Polish principles — A specific set of micro-detail rules we follow: concentric border radii, specific transition properties (never transition: all), scale-[0.96] on press, tabular numerals for live counts, optical alignment over geometric. See states-and-interaction.md.

Primitive — Layer 1: a raw shadcn component before we wrap it. Or: a Layer 1 token like --primary-500 before we semantically assign it. Context tells you which sense.

R

Ramp — An 11-step color scale (50 → 950). We have six: primary, neutral, error, success, warning, info.

S

Semantic token — A meaning-based token name like --primary or --success-subtle. References a primitive step. This is what wrappers use.

shadcn/ui — The component library we use as our base layer. Provides Radix-based primitives that handle accessibility, keyboard interaction, focus management. We wrap them; we don't edit them.

Source of truth — The single place a thing is defined. In this system, the wrapper layer (components/upnext/) is the source of truth for components, and globals.css is the source of truth for tokens. When something needs to change, it changes there — not in a usage site.

Status colors — The four "what's going on" signals: success (green), error (red), warning (amber), info (cyan/sky). Each has its own ramp and a full set of semantic tokens.

Step — One of the 11 entries in a ramp. primary-50, primary-100, …, primary-950. Lower numbers are lighter, higher are darker.

Subtle (token suffix) — A tinted, low-noise background of a color, used for alerts and badges (e.g. --success-subtle). Pairs with -ink (text) and -border.

T

Token — A named value. --primary, --radius-lg, --spacing-3. The whole DS philosophy reduces to: never use values directly, only use tokens.

V

Variant — A named style option on a wrapper. Buttons have variants like primary | secondary | ghost. Variants are the public API of a wrapper — adding a new one is a commitment.

W

Wrap-don't-use — The architectural rule that components in the app never use shadcn primitives directly. They use our wrappers. Enforced by the ESLint guardrail.

Wrapper — Layer 2: an UpNext component file at components/upnext/*.tsx that wraps a shadcn primitive, locks UpNext variants, and is the only API consumers see.