Skip to main content
Shadows help users understand which surfaces sit above others. In BEEQ, shadows are used for elevation, temporary layers, overlays, and subtle separation when a border alone would feel too flat. Use shadows with intention. A stronger shadow should usually mean a stronger layer relationship, not a stronger state by itself.

​
What BEEQ provides

BEEQ provides a four-step box-shadow scale. The values are exposed as CSS custom properties and mapped into the BEEQ Tailwind preset when the preset is installed. Components that need elevation expose component-level shadow variables. Prefer those component variables when the shadow belongs to a BEEQ component, and use global shadow tokens for custom surfaces.

​
Shadow scale

The shadow scale moves from subtle interaction lift to pronounced floating surfaces. Use the smallest shadow that communicates the layer relationship.

​
Elevation and layering

Elevation should describe a surface relationship. A card can sit above the page. A panel can sit above the card. A dialog, toast, or notification can sit above the rest of the interface. Shadows should not be used as decoration. When every surface is elevated, users lose the visual hierarchy that elevation is meant to create.

​
How shadows work in code

Use CSS variables directly when you build custom UI. Use component CSS variables when the elevated surface belongs to a BEEQ component. If your project uses the BEEQ Tailwind preset, utilities such as shadow-xs, shadow-s, shadow-m, and shadow-l map to the same shadow variables.

​
Component shadow customization

Components that own elevated surfaces expose CSS variables for their shadow. Use those variables instead of targeting internal classes.

​
Components without shadow variables

Some components do not expose a dedicated box-shadow variable. Use their documented shadow parts when a product-specific design needs elevation. Keep this restrained: a card or button shadow should support hierarchy or affordance, not make every action compete for attention.

​
Choosing shadow

Choose shadow based on how far a surface sits from the page, not how important the content feels.

​
Usage guidelines

Use --bq-box-shadow--* values instead of custom shadow values. The scale keeps elevation consistent across components and custom surfaces.
Use stronger shadows only when the surface sits above another surface. Elevation should make the layer model easier to understand.
Use xs or s for cards and low-emphasis surfaces. These shadows add separation without pulling attention away from content.
Use m or l for panels, dropdowns, dialogs, toasts, notifications, and other temporary layers.
Pair shadow changes with text, color, icon, stroke, or focus treatment when a state must be understood.
A shadow works best when the surface also has enough padding, a clear edge, and a radius that matches its size.
Multiple large shadows in the same region create visual noise and weaken the hierarchy.
Use BEEQ tokens so shadows keep the intended weight in light and dark mode.

​
Accessibility and constraints

Shadows are visual cues. They can support hierarchy, but they cannot carry meaning alone.
  • Do not rely on shadow alone to indicate focus, selection, error, success, or disabled states.
  • Keep focus indicators visible when an elevated surface contains interactive elements.
  • Avoid shadows that make text or controls harder to read against nearby surfaces.
  • Use overlays, aria patterns, and focus management for blocking layers such as dialogs; shadow does not define modality.
  • Check zoomed and narrow layouts. Large shadows can make dense UI feel crowded or clipped.
  • Avoid clipping shadows with overflow: hidden unless the clipped edge is intentional.

​
Resources

Global CSS variables

Review the box-shadow variables used by BEEQ themes.

Tailwind preset source

See how BEEQ maps shadow tokens into Tailwind utilities.

Root token source

See the source that defines the BEEQ shadow values.