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: 10pxwhere 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-lgbeside metric cards atrounded-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]norrounded-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/
--radiusanchor. 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.