Flex
Flexbox container primitive supporting token gap scale, direction, alignment, justification, polymorphic tag rendering, and background media props (bgVideo, bgImage, bgOverlays, bgSize, bgVideoPaused).
// Plain markup
import { Flex } from "@shavin/ui";Row Flex Layout with Gap
<Flex direction="row" align="center" justify="between" gap="4">
<span>Left Label</span>
<Flex gap="2">
<Button size="sm" variant="outline">Cancel</Button>
<Button size="sm">Save</Button>
</Flex>
</Flex>Background Media
Flex accepts bgVideo, bgImage, bgOverlays, bgSize, and bgVideoPaused props. The media renders behind children with a relative z-10 content wrapper.bgOverlays supports comma-separated shorthand: presets (dark-50), hex colors (#ff5733/50), semantic tokens ((accent)/30), and gradients (linear(45deg, #000/0%, #000/100%)/80). Mix freely in one string. Use surface="dark" to ensure text legibility over dark media. The surface auto-inverts against the page theme — on a dark page, surface="dark"flips to light contrast so the section always stands out as a contrast band. Use surface="dark-always" to lock dark tokens regardless of page theme (for media backgrounds where text must stay readable against the media, not the page).
Background Video with Dark Overlay
A Flex column with a background video and dark-50 overlay. Content sits above the media via z-10 wrapper.
Build the Future
A zero-slop design system powered by tokens.
<Flex
direction="column"
align="center"
justify="center"
gap="4"
bgVideo="https://videos.pexels.com/video-files/39524985/16839566_1920_1080_24fps.mp4"
bgOverlays="dark-50"
surface="dark-always"
className="h-[400px] rounded-[var(--radius-panel)] overflow-hidden"
>
<Heading size="2xl">Build the Future</Heading>
<Text color="muted">A zero-slop design system powered by tokens.</Text>
<Button size="lg">Get Started Free</Button>
</Flex>Background Image with Multi-Layer Overlays
Multiple overlay layers via comma-separated shorthand — dark-20 base scrim plus gradient-bottom at 80% opacity for text legibility.
Mountain Escape
Multi-layer overlay: dark-20 base + gradient-bottom at 80% opacity
<Flex
direction="column"
justify="end"
gap="3"
bgImage="https://images.unsplash.com/photo-1789953067753-6a1fcefe07d8"
bgOverlays="dark-20, gradient-bottom/80"
surface="dark-always"
className="h-[300px] rounded-[var(--radius-panel)] overflow-hidden p-6"
>
<Heading size="lg">Mountain Escape</Heading>
<Text size="sm" color="muted">Multi-layer overlay: dark-20 base + gradient-bottom at 80% opacity</Text>
</Flex>Video Background with Gradient + Token Overlay
Custom linear gradient with hex stops and a semantic accent token overlay — no JSON needed for gradients.
Gradient + Accent
linear gradient + semantic accent token — shorthand only
<Flex
direction="column"
align="center"
justify="center"
gap="3"
bgVideo="https://www.pexels.com/download/video/38347119/"
bgOverlays="linear(180deg, #000/0%, #000/100%)/70, (accent)/15"
surface="dark-always"
className="h-[400px] w-full rounded-[var(--radius-panel)] overflow-hidden"
>
<Heading size="2xl">Gradient + Accent</Heading>
<Text color="muted">linear gradient + semantic accent token — shorthand only</Text>
<Button size="lg">Watch Now</Button>
</Flex>Overlay Presets
bgOverlays accepts comma-separated shorthand for all overlay types. Presets (below) are the simplest form. You can also use solid colors and gradients:
| Syntax | Example | Description |
|---|---|---|
| presetKey | "dark-50" | Named preset at 100% opacity. |
| presetKey/opacity | "scrim/90" | Named preset at custom opacity (0–100). |
| #hex/opacity | "#ff5733/50" | Solid hex color with optional opacity. |
| (token)/opacity | "(accent)/30" | Semantic token color with optional opacity. |
| linear(angle, stops)/opacity | "linear(45deg, #000/0%, #000/100%)/80" | Linear gradient with angle and color stops. Each stop: color/offset%. |
| radial(stops)/opacity | "radial((accent)/0%, (accent)/100%)/60" | Radial gradient with color stops. No angle needed. |
Combine multiple layers with commas. Mix presets, solids, and gradients freely:
bgOverlays="dark-20, (accent)/30, linear(90deg, #000/0%, #000/80%)/70"Preset keys below are shorthand for common scrim/gradient patterns. The preview column shows the overlay composited over a checkerboard.
| Preview | Preset | Description |
|---|---|---|
| dark-20 | Solid black at 20% opacity — subtle darkening for light readability. | |
| dark-30 | Solid black at 30% opacity — moderate darkening. | |
| dark-50 | Solid black at 50% opacity — strong darkening for white text legibility. | |
| dark-75 | Solid black at 75% opacity — heavy darkening for dramatic contrast. | |
| light-20 | Solid white at 20% opacity — subtle lightening for dark readability. | |
| light-30 | Solid white at 30% opacity — moderate lightening. | |
| light-50 | Solid white at 50% opacity — strong lightening for dark text legibility. | |
| gradient-bottom | Linear gradient from transparent (top) to 80% black (bottom) — for bottom-aligned text overlays. | |
| gradient-top | Linear gradient from transparent (bottom) to 80% black (top) — for top-aligned text overlays. | |
| gradient-radial | Radial gradient from transparent (center) to 85% black (edges) — focused-center vignette. | |
| vignette | Radial gradient from transparent (40% radius) to 85% black (edges) — classic vignette. | |
| scrim | Soft linear gradient from 10% (top) to 85% (bottom) black — gentle content scrim. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| bgVideo | string | — | Background video URL (mp4, webm, etc.). Renders an autoPlay/loop/muted <video> element behind children. |
| bgImage | string | — | Background image URL. Renders an <img> with object-cover (default) or object-contain. |
| bgSize | "cover" | "contain" | cover | Background media fit. "cover" fills the container (default), "contain" fits within. |
| bgOverlays | string | — | Comma-separated shorthand for overlay layers. Supports presets ("dark-50"), solid colors (#hex or (token)), and gradients (linear/radial). JSON array of OverlayLayer[] as fallback for advanced cases. Layers composite top-to-bottom. |
| bgVideoPaused | boolean | false | When true, pauses the background video (renders a static poster frame instead of autoplay). |
| as | ElementType | div | Polymorphic element tag: div, section, header, etc. Default "div". |
| translucent | boolean | — | Whether to apply translucent panel styling with data-panel attribute. |
| surface | Surface | — | Surface contrast scope intent. "dark"/"light" auto-invert against the page theme (contrast band). "dark-always"/"light-always" lock to one theme regardless of page (for media backgrounds). Undefined inherits page theme. |
| direction | "row" | "column" | "col" | "row-reverse" | "column-reverse" | "col-reverse" | "row" | — |
| align | "start" | "center" | "end" | "stretch" | "baseline" | "stretch" | — |
| justify | "start" | "center" | "end" | "between" | "around" | "start" | — |
| wrap | "nowrap" | "wrap" | "nowrap" | — |