Shadows

Overview

Shadows in the Rogo design system create visual hierarchy by simulating elevation. Elements with shadows appear to float above the surface, drawing attention and establishing spatial relationships. The shadow scale progresses from subtle to prominent, with each level serving specific UI patterns.

Choose elevation based on the element's importance and how far it should appear from the background. Every shadow-ring-* class bakes a theme-aware 1px hairline into the shadow as its final layer, so an elevated surface gets its edge for free. See Shadow + Ring.

Shadow Scale

The shadow scale provides six levels of elevation, from barely perceptible to highly prominent.

Component Mapping

Different UI patterns call for specific shadow levels. Use this guide to choose the right elevation.

Shadow + Ring

Every elevated surface draws a single edge that morphs into its shadow. Pick by whether the element is elevated:

Depth (recessed surfaces)

Where shadow-ring-* lifts a surface above the page, depth sinks one into it. The single class steps the background down one level (--background-secondary) and keeps the inside edge lit with an inner ring. The edges adapt per theme: in light mode the ring is paper-colored (--background-primary) and the outside edge gets the same hairline-into-shadow treatment as shadow-ring-xs; in dark mode the rim is translucent white (5%) and the hairline drops entirely, leaving only the soft shadow, since a page-colored ring would read as a groove there instead of a lit rim.

Use it only where a recessed reading is justified: inset CTA cards, discover cards, containers embedded in a page (the agent library's discover cards and scheduled-agents container are the reference uses). The whole effect ships in the one class: never add border, ring-*, or shadow-* to the same element, since they collide with the baked-in ring and hairline. hover:bg-* overrides compose fine.

Never combine shadow-ring-* with a border/ring on the same element. The hairline is already in the shadow, so a manual border draws the edge twice. It reads washed/greyed, worst in dark mode. That doubling is exactly what the shadow-ring-* classes exist to prevent.

Tuning the hairline

The hairline defaults to a subtle, theme-aware neutral, the right choice for almost every surface. If one needs a touch more definition, override it with the hairline-* utility and an opacity modifier; only the 1px ring changes.

// A slightly stronger edge than the default hairline
<div className="shadow-ring-md hairline-black/10">…</div>

hairline-* takes any theme color, so a tint works the same way (shadow-ring-md hairline-red-500/30), but reserve color for intentional accents, like a destructive or selected state, not as a default. Semantic tokens (hairline-brand-primary) follow the theme and adapt between light and dark like the default hairline; a raw palette color or literal (hairline-red-500, hairline-black/10) is fixed and won't.

Hover States

Increasing shadow on hover creates a "lift" effect that signals interactivity.

// Interactive elevated card: the ring stays consistent as elevation lifts
<div className="shadow-ring-xs hover:shadow-ring-md active:shadow-ring-xs transition-shadow">
  Card content
</div>

Usage Guidelines

Do

• Use shadow-ring-* for any elevated surface, since it carries its own hairline edge
• Increase elevation on hover to indicate interactivity (shadow-ring-xs → shadow-ring-md)
• Use shadow-ring-md for dropdowns/menus, shadow-ring-xl for modals and dialogs
• Add transition-shadow when elevation changes on interaction
• Use a standalone border/ring (no shadow) for non-elevated dividers and sidebars

Don't

• Don't combine a border (or ring) with a shadow on the same element. Drop the border and use the combined shadow-ring-* class instead (switch it over if it isn't already)
• Don't use shadow-ring-2xl for standard UI elements. Reserve for critical alerts
• Don't apply shadows to inline elements or text
• Don't use shadows on elements that don't need elevation (e.g., page sections)
• Don't skip elevation levels dramatically on hover (e.g., shadow-ring-xs → shadow-ring-xl)
• Don't forget transitions when elevation changes. Abrupt changes feel broken
• Don't use shadows as the only way to indicate interactivity; combine with color or other cues