On this page

On this page

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;       /* dense rows, chips */
  --radius-m: 8px;       /* buttons, inputs — the default control radius */
  --radius-l: 12px;      /* popovers, menus */
  --radius-xl: 20px;     /* cards, sheets, dialogs */
  --radius-full: 9999px; /* circles, pills */
}
  • 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 and controls: medium radius

  • 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 {
  /* hover fill */
  content: "";
  position: absolute;
  inset: 0;
  border-radius: inherit; /* concentric by construction */
}

.card {
  --card-inset: 12px;
  border-radius: var(--radius-xl);
  corner-shape: squircle;
  padding: var(--card-inset);
}
.card .media {
  /* 20 - 12 = 8: same center of curvature and same curve family as the card */
  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.