<!-- https://getkonjo.com/design/foundations/borders · source: docs/design/foundations/borders.md -->

# Radius and borders

Two border tokens with two jobs, and the five radii.

> Part of the [Konjo design language](../konjo-design-language.md). The laws in the spine apply here unless this chapter contradicts them.

| Token | Value | Use |
|---|---|---|
| `radius.small` | 4 | Corners on a control under ~20pt — a Studio checkbox, a belt swatch's rounded square |
| `radius.input` | 8 | Inputs, select triggers |
| `radius.card` | 16 | Cards, tiles (Kata V4; was 12) |
| `radius.large` | 16 | Full-width feature blocks |
| `radius.sheet` | 24 | Bottom sheets |
| `radius.pill` | 999 | **Buttons**, chips, pills, avatars, segmented tracks |

**`radius.small` is for small controls only, never a surface.** 8 on a 16pt box is a circle,
which is why sub-20pt corners were being typed as a raw `4` — the scale had no step for them.
It is not a "tighter card"; a card is 16 at every size.

**Buttons and chips are `radius.pill`** — pill buttons with soft 16 cards is the Kata shape
language (V4), chosen over crisp 8, balanced 12 and very round 24 cards. Inputs stay
`radius.input` 8: a field is a container for typing, not a button.

Five values. There are currently **29 distinct raw `borderRadius` values** in the tree,
including 42, 44, 66, 19, 11, 7, 5, 3, 1. Everything rounds to the nearest token.

**`borderWidth.hairline` 1 is the default and almost always the answer.** `0.5` is banned
(356 uses to migrate).

**`borderWidth.emphasis` 2 exists and has exactly three uses**, listed here so a fourth has to
argue for itself. This paragraph said "one value" for a long time while the token source shipped
two, and four chapters said 2px was "the one sanctioned exception to the 1px rule" while two
shipped things already used it:

| 2px is legal for | Where |
|---|---|
| The focus ring | `border.focus`, or `border.focusOnHero` on an ink surface — [accessibility](accessibility.md) |
| The active navigation edge | Studio's rail item, `brand.red` — [Studio metrics](../studio/metrics.md) |
| A dragged object's edge | `border.control`, while a drag is in flight — [direct manipulation](../patterns/direct-manipulation.md) |

What the three have in common is that each marks a **transient or navigational state**, not a
boundary. A border that is 2px because the designer wanted it heavier is the thing this rule
forbids, and it always was.
