# TOK-3 — Corner radii come from the radius scale DESIGN.md defines (else the codebase's, else the shadcn default radius scale)

L1 · deterministic · Tokens & theming

**Fails when:** ad-hoc radius values · child radius larger than parent (non-concentric nesting) · peer containers of the same kind use different corner radii — anchor to the product's Card/base radius

## Requirement

Corner radii must be on the product's radius scale, and nesting must be concentric
(child radius ≤ parent radius). The working rule for a nested
element is `inner radius = outer radius − padding`: a card at `rounded-2xl` (16px)
with 8px of padding wants an inner control at `rounded-lg` (8px), not another 16px.
Mismatched radii on nested surfaces are the most common thing that makes a layout
feel off; snap the result to the nearest scale step. **Additionally**, peer containers
of the same kind (cards, sections, tiles) share a single corner radius, anchored by
default to the product's `Card` component radius / `--radius` token (0.5rem = 8px in
this site's `app/globals.css`).

## Where the values come from

The product's `DESIGN.md` defines the radius scale. Where it defines none, the
codebase's own radius tokens (for example, a `--radius` variable and the steps derived
from it) decide. Where neither does, the shadcn default radius scale applies:
{0, 2, 4, 6, 8, 12, 16, 24, 9999} px. This site's `DESIGN.md`, for example, sets
`--radius` to 0.5rem and uses `rounded-lg` as its one shape.

## Rationale

Two on-scale radii can still read as careless when peers disagree. A `rounded-lg`
(8px) section beside `rounded-3xl` (24px) cards looks inconsistent side by side, although
both are on scale and valid in isolation. Consistency across peers is what makes a
surface feel deliberate rather than assembled from independent parts. The product's
Card radius is the natural anchor because cards are the most common peer container.

## Fails when

- Ad-hoc or off-scale radius values (e.g. `border-radius: 10px` where 10 is not in
  the scale).
- Child radius larger than parent (non-concentric nesting).
- Peer containers of the same kind using different corner radii on the same surface
  with no deliberate hierarchy reason (e.g. a profile section at `rounded-lg` beside
  metric cards at `rounded-3xl`).

## How to verify

**Script (raw CSS values only):** `checks/token-audit <path>…` reads each raw
`border-radius` value in a CSS declaration or style context, one declaration at a
time, and flags a px or rem value outside the shadcn default set
{0, 2, 4, 6, 8, 12, 16, 24, 9999} px. A value that comes through a token (`var(--…)`)
passes unread. The set is fixed in the script and does not come from `DESIGN.md`.
When the product's scale differs from the default, a finding means only that the value
is off the default set: check it against the product's scale before you report it, and
check the raw values the script passes as well.

**Evaluator (no script coverage):** the script checks nothing else, so judge each of
these by hand against the product's scale.

- **Concentric nesting.** The script reads each value on its own and never compares a
  child with its parent. Compare nested radii in the source and the screenshots.
- **Tailwind radius utilities, arbitrary and named.** The script reads neither
  `rounded-[10px]` nor `rounded-4xl` (32px). Resolve each utility to its value and check
  it against the product's scale. Do not report TOK-3 as "mechanically clean" for a
  Tailwind product on the script's result alone. The same gap applies to TYP-3 (named
  size utilities) and TOK-2 (arbitrary and named spacing utilities).
- **Token values.** A `var(--…)` radius passes the script unread, so confirm the token
  resolves to a step on the product's scale.
- **Peer consistency.** No script compares two different elements' radii. Compare peer
  containers visible in the screenshots against the product's Card/`--radius` anchor.
  The reference anchor for this site is `--radius: 0.5rem` (`app/globals.css`).

## Evaluator guidance

**Flag:** peer cards, sections, or tiles on the same surface that use visibly
different corner radii without a deliberate hierarchy purpose — e.g. a summary card
at `rounded-3xl` beside a detail section at `rounded-lg`.

**Do not flag:** a deliberately different radius that signals a different element
*class* — e.g. a full-bleed hero image (no radius or `rounded-none`) beside inset
cards (standard card radius). Hierarchy is a reason; unexplained drift is not.