Corner Radius#
Principles#
- Corner radius is a system, not a per-element value: define a small token scale once per project and take every radius from it.
- Two rules cover all cases: continuous curvature on single surfaces, concentric curvature on nested surfaces.
- Apply both rules consistently. One corner rarely looks wrong on its own; mismatched corners next to each other are what look sloppy.
Token scale#
:root {
--radius-s: 6px;
--radius-m: 8px;
--radius-l: 12px;
--radius-xl: 20px;
--radius-full: 9999px;
}
- Every radius in the project comes from this scale. One-off values (
13px) bypass the shared tokens used to calculate nested radii, making inconsistent values harder to prevent.
- Adjacent steps must stay distinguishable (≥ 2px apart at these sizes).
Single surfaces: continuous corners#
border-radius alone joins straight edges to a circular arc; the sudden curvature change is what makes plain web corners read harder than Apple's continuous corners.
- Pair
corner-shape with the existing border-radius: border-radius keeps setting the corner size, corner-shape only changes the curve. Backgrounds, borders, outlines, shadows, overflow: hidden, and backdrop-filter all follow the resulting shape — no clip-path, no SVG masks.
- Use
squircle (= superellipse(2)) as the single project-wide value. The corner shape is part of the token system; do not vary it per element.
- Apply where the corner is a visible design decision: cards, sheets, dialogs, tiles, media, app-level surfaces (≥
--radius-l). Below ~6px the difference from round is invisible — do not set it there.
- Progressive enhancement only: as of late 2026, only Chromium-based browsers (139+) render
corner-shape; Safari and Firefox ignore it and fall back to ordinary round corners. That fallback is acceptable. Never ship a JS or SVG polyfill for it.
corner-shape has no effect when border-radius resolves to 0.
.card {
border-radius: var(--radius-xl);
corner-shape: squircle;
}
- Buttons, inputs, and selects default to the medium token (
--radius-m, about 8px on a 36–40px control). Shallow (--radius-s) is the acceptable lower bound for dense layouts.
- A medium radius keeps straight edge segments that align text and neighboring controls, and leaves room for hover and pressed states inside the control to stay concentric.
- Reserve fully round (
--radius-full) buttons for chips, tags, and identity elements (avatars, toggles). Do not use them for action buttons.
Nested surfaces: the concentric rule#
- When a layer sits
p px inside a surface with outer radius R, its radius must be r = R − p (clamped at 0). Both corners then share one center of curvature, making the inner layer look like part of the same surface.
- The rule applies to hover and pressed overlays (
::before / ::after), focus rings, badges on cards, media and controls inside padded surfaces, segmented controls, and tooltips.
- Equal inner and outer radii, or arbitrary inner values, break concentricity and make hover states and badges look disconnected from the surrounding surface.
Common cases#
- Overlay at
inset: 0: border-radius: inherit.
- Layer inset by the surface padding: compute with
calc() from the same tokens.
- Focus ring outside the control: use
outline or box-shadow — both track the outer radius automatically.
- Border of width
w on a rounded box: the inner edge is already drawn at R − w; never re-round it.
- Layer nested inside a surface with
corner-shape: set the same shape on the inner layer with corner-shape: inherit — the property does not inherit by default, and a plain round inner corner against a squircle outer corner breaks the concentric reading.
.button {
border-radius: var(--radius-m);
}
.button::before {
content: "";
position: absolute;
inset: 0;
border-radius: inherit;
}
.card {
--card-inset: 12px;
border-radius: var(--radius-xl);
corner-shape: squircle;
padding: var(--card-inset);
}
.card .media {
border-radius: calc(var(--radius-xl) - var(--card-inset));
corner-shape: inherit;
}
- When an exact match is impossible (arbitrary artwork, raster edges), err tighter: keep
r ≤ R − p. A slightly tight inner corner reads deliberate; a loose one reads broken.
Checks#
- Every radius in the diff comes from the token scale.
- Controls use the medium token; pill radii appear only on chips, tags, and identity elements.
- Every nested layer satisfies
r = R − p, inherits its radius, or uses outline / box-shadow.
- Layers nested inside a
corner-shape surface use the same corner shape (corner-shape: inherit).
corner-shape: squircle is set on ≥ --radius-l surfaces; no polyfills shipped for it.
Works with#
- Coding Standards — context: the token scale is an instance of the no-magic-values rule.
- Tailwind CSS — pairs-with (situational): when Tailwind is in use, express the scale as theme tokens; the concentric rule is unchanged.
- Liquid Glass Design — context: on Apple platforms, use the system's continuous-corner APIs instead of web approximations.