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.| BEEQ provides | Use it for |
|---|---|
| Box shadow variables | Custom surfaces, elevated panels, and product-specific layers. |
| Tailwind preset mappings | Utility classes such as shadow-xs, shadow-s, shadow-m, and shadow-l when the preset is installed. |
| Component CSS variables | Scoped shadow customization for components such as panel, dialog, toast, tooltip, and notification. |
Shadow scale
The shadow scale moves from subtle interaction lift to pronounced floating surfaces. Use the smallest shadow that communicates the layer relationship.| Token | CSS variable | Tailwind key | Value | Common use |
|---|---|---|---|---|
xs | --bq-box-shadow--xs | shadow-xs | 0 2px 0 rgba(0, 0, 0, 0.016) | Subtle interactive lift on compact elements. |
s | --bq-box-shadow--s | shadow-s | 0 8px 24px rgba(0, 0, 0, 0.04) | Cards and stable elevated surfaces. |
m | --bq-box-shadow--m | shadow-m | 0 10px 48px -16px rgba(0, 0, 0, 0.12) | Panels, dropdowns, sticky bars, and raised containers. |
l | --bq-box-shadow--l | shadow-l | 0 20px 58px -16px rgba(0, 0, 0, 0.16) | Dialogs, toasts, notifications, and floating attention surfaces. |
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 asshadow-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.| Component | CSS variable | Default shadow | Typical role |
|---|---|---|---|
bq-panel | --bq-panel--box-shadow | var(--bq-box-shadow--m) | Dropdowns, popovers, side panels, and temporary panels. |
bq-dialog | --bq-dialog--box-shadow | var(--bq-box-shadow--l) | Modal dialogs and blocking overlays. |
bq-toast | --bq-toast--box-shadow | var(--bq-box-shadow--l) | Time-based floating messages. |
bq-notification | --bq-notification--box-shadow | var(--bq-box-shadow--l) | Non-blocking notifications and alerts. |
bq-tooltip | --bq-tooltip--box-shadow | var(--bq-box-shadow--m) | Contextual helper text above the current surface. |
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.| Use | Recommended shadow |
|---|---|
| Subtle hover or interactive lift | var(--bq-box-shadow--xs) |
| Card or stable elevated surface | var(--bq-box-shadow--s) |
| Dropdown, panel, sticky bar, or raised container | var(--bq-box-shadow--m) |
| Dialog, toast, notification, or floating attention layer | var(--bq-box-shadow--l) |
| Dense data, table rows, and flat page sections | No shadow; use stroke, spacing, or background instead. |
Usage guidelines
Use BEEQ shadow tokens
Use BEEQ shadow tokens
Use
--bq-box-shadow--* values instead of custom shadow values. The scale keeps elevation consistent across components and custom surfaces.Match elevation to layer depth
Match elevation to layer depth
Use stronger shadows only when the surface sits above another surface. Elevation should make the layer model easier to understand.
Use subtle shadows for stable surfaces
Use subtle shadows for stable surfaces
Use
xs or s for cards and low-emphasis surfaces. These shadows add separation without pulling attention away from content.Use stronger shadows for floating UI
Use stronger shadows for floating UI
Use
m or l for panels, dropdowns, dialogs, toasts, notifications, and other temporary layers.Do not use shadow as the only state cue
Do not use shadow as the only state cue
Pair shadow changes with text, color, icon, stroke, or focus treatment when a state must be understood.
Combine shadow with spacing, stroke, and radius
Combine shadow with spacing, stroke, and radius
A shadow works best when the surface also has enough padding, a clear edge, and a radius that matches its size.
Avoid stacking heavy shadows
Avoid stacking heavy shadows
Multiple large shadows in the same region create visual noise and weaken the hierarchy.
Keep shadows consistent across themes
Keep shadows consistent across themes
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: hiddenunless 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.