Shadow & Status

Shadows and status treatments work together to communicate depth (what's floating above what) and state (what's happening right now — hover, focus, success, error). Used consistently, they let people read an interface without having to think about it.

Elevation (shadow)Copy Anchor Link

Shadows describe how far an element sits above the surface behind it. We use a small, deliberate set of elevations rather than arbitrary blur/spread values, so depth stays predictable across the product. Always build shadows from tokens, never from raw rgba()/pixel values. The shadow color gets more opaque in dark mode — the same low-opacity value used in light mode would be invisible against a dark page, since the shadow is cast onto whatever sits behind the element, not onto the element itself.

Both previews are locked — they don't follow the page theme switcher.

GuidelinesCopy Anchor Link

• Use only one elevation level at a time per surface — don't stack multiple shadow tokens on the same element.
• Prefer first-floor-shadow as the default for anything that overlays page content; reserve second-floor-shadow for the small number of cases where something floats above another floating surface.
• Shadows always use the same neutral color pair (--palette-surface-900-1 light / --palette-surface-1000-1 dark, matching --nm-dropdown-shadow) — don't tint shadows with brand or status colors, and don't reuse the light value in dark mode or the shadow will be invisible against a dark page.
• Shadow communicates hierarchy, not decoration. If an element doesn't need to be perceived as "above" something else, it doesn't need a shadow.

Interaction ringsCopy Anchor Link

Two tokens express interaction state as an outline — not a border, not a drop shadow. An outline sits outside the element's box without affecting its size, and it's a different CSS property than border, so it never conflicts with a status border on the same element (see below). Both tokens are 2px and swap palette step between light and dark mode:

Both previews are locked — they don't follow the page theme switcher.

GuidelinesCopy Anchor Link

• focus must always be visible for keyboard navigation — never remove it without providing an equivalent replacement (accessibility requirement, not a style preference).
• Don't combine focus and active on the same element at the same time; treat them as mutually exclusive interaction states.
• These are applied as outline, not border or box-shadow, so they don't shift layout when the state changes.
• The gap created by outline-offset on focus is transparent — it reveals whatever sits behind the element, it's not a painted white layer. Don't reimplement it as a second box-shadow with a hardcoded white color; that would look wrong on dark or colored backgrounds.

Feedback StatusCopy Anchor Link

Status is expressed as a border, not an outline or a fill — it's part of the element's own box, colored to signal its state (valid, informational, needs attention, invalid) without changing the background. Because it's a border and interaction rings are an outline, the two are independent properties and can be shown together on the same element — e.g. an invalid field keeps its negative border even while it also shows the focus outline. Status colors are constant across light and dark mode. It follows standard conventions: green for success, blue for info, orange/amber for warning, red for error. For the underlying color values, see Color System; this section is about how those colors get applied as state.

Both previews are locked — they don't follow the page theme switcher.

Status border combined with the focus interaction ring on the same element — the two don't conflict:

Both previews are locked — they don't follow the page theme switcher.

GuidelinesCopy Anchor Link

• Never rely on color alone to convey status — pair the border with an icon or text label so the meaning holds for color-blind users.
• Use the same status color consistently across an entire flow (e.g. don't pair a negative icon with a warning border for the same field).
• A status border and an interaction ring can and should coexist when both are true at once (e.g. a focused, invalid field) — they're different CSS properties by design.
• Status borders follow the same contrast requirements as the rest of the palette: at least 3:1 against the adjacent background, since a border is a UI component boundary, not text (WCAG 2.1 — 1.4.11).