# Styled compositions

> Styled compositions package the visual grammar for common interactions while preserving the underlying primitive API.

Web: https://velvet-ui.watermelons.workers.dev/docs/styled-compositions

Start with a composition when its behavior matches the task. Drop to Sheet primitives only when the DOM, placement, tracks, or visual layers need a different contract.

## Decision table

| Need | Use |
| --- | --- |
| Mobile detail, picker, checkout, short task | BottomSheet |
| Tool or media control that must remain present | PersistentSheet |
| Hierarchical full-width navigation with backing-page depth | DepthSheet |
| A normal card that expands into a modal | CardExpansion |
| Immersive photo or media | Lightbox |
| Drawer, top sheet, modal, detached, full-screen, parallax | Sheet primitives |

## Compositions stay headless where it matters

Every Content forwards refs and DOM props. `viewProps`, `portalProps`, and part-specific prop bags reach the underlying primitive.

The supplied CSS establishes responsive geometry and safe-area behavior. Color and product layout remain overrideable through variables and classes.

## Imports

```tsx
import { BottomSheet } from "velvet-ui/bottom-sheet";
import { CardExpansion } from "velvet-ui/card-expansion";
import { DepthSheet } from "velvet-ui/depth-sheet";
import { Lightbox } from "velvet-ui/lightbox";
import { PersistentSheet } from "velvet-ui/persistent-sheet";
```