# @volverjs/style

A CSS/SCSS design system: BEM components (`.vv-button`, `.vv-button__label`,
`.vv-button--primary`), Tailwind-like utilities (`p-md`, `flex`, `grid-cols-3`), design
tokens as CSS custom properties, and an SCSS layer that generates all of it from maps.
Every selector is wrapped in `:where()`, so it has zero specificity and any CSS you write
wins without `!important`.

The vocabulary is close enough to Tailwind that guessing feels safe. It is not: a class
that does not exist fails silently, and about a third of the classes an agent tends to
guess (`display-flex`, `md:p-16`, `z-10`, `rounded-2xl`, `text-uppercase`, `hidden`) are
not in this library. Work from the reference files, not from memory.

## Workflow

1. **Locate the installed library.** In a consuming project it is
   `node_modules/@volverjs/style/` (the package ships `src/`, `dist/` and
   `design-tokens.json`). Inside the library repo itself use `./src` and `./dist`
   (`pnpm build` regenerates `dist`).
2. **Read the reference for what you are about to write** (all in `references/`):
   - [utilities.md](references/utilities.md): every utility class with its exact value
     set and whether it has responsive variants.
   - [components.md](references/components.md): canonical markup, elements, modifiers and
     states for all 55 components, plus how states are expressed.
   - [tokens.md](references/tokens.md): custom properties, CSS-only overrides, dark theme.
   - [scss.md](references/scss.md): import paths, context configuration, extending and
     creating components, mixins, cascade layers.
3. **Verify anything not in the references** against the compiled CSS before using it:

   ```bash
   # does a utility exist? (responsive form: escape the colon)
   grep -c -F '.gap-md' node_modules/@volverjs/style/dist/utilities.css
   grep -c -F '.md\:grid-cols-3' node_modules/@volverjs/style/dist/utilities.css
   # which modifiers does a component have?
   grep -oE '\.vv-alert--[a-z-]+' node_modules/@volverjs/style/dist/components/vv-alert.css | sort -u
   # the full map of a component (elements, modifiers, states, aliases)
   cat node_modules/@volverjs/style/src/settings/components/_vv-alert.scss
   ```

4. **Prefer the library's idiom over custom CSS**: a token override or a modifier from the
   map beats a new rule, and stays coherent with the dark theme.

## Where it differs from Tailwind

These are the mistakes that recur. Each row is verified against the compiled CSS.

| Habit | In @volverjs/style |
|---|---|
| `display-flex`, `hidden` | Bare names: `flex` `grid` `block` `inline-flex` `none` (there is no `hidden`) |
| `relative`, `absolute` | Same bare names, fine |
| `md:p-16`, `lg:gap-8` | Spacing and gap have **no responsive variants**. Use the dynamic tokens `xs sm md lg xl` (`p-md`, `gap-lg`), which grow with the viewport by themselves |
| `xxs:` prefix, `2xl:` | Prefixes are `xs: sm: md: lg: xl: xxl: xxxl:` (360, 576, 992, 1024, 1280, 1440, 1536px) and only display, position, visibility, flex/grid, sizing, text size/align, border width/style, aspect and columns accept them |
| `@md:flex-row` with no container | Container prefixes `@xs:` `@sm:` `@md:` `@lg:` `@xl:` `@xxl:` `@xxxl:` (20, 24, 28, 32, 36, 42, 48rem) read the nearest ancestor with the `@container` class and match nothing without one. Only display, flex direction and wrap, justify/align content and items, `grid-cols-`, `col-` and text align have them |
| `hover:bg-…`, `dark:text-…`, `focus:` | No state or theme variants at all. Use component states, tokens, or your own CSS |
| `max-w-md`, `max-w-2xl` | `max-w-screen-md` … `max-w-screen-xxxl`, `max-w-prose`, or `container`. `max-w-md` exists, but it is the dynamic spacing step (12 to 16px) |
| `z-10` … `z-50` | Semantic: `z-sticky` `z-fixed` `z-dropdown` `z-modal-backdrop` `z-modal` `z-popover` `z-tooltip` `z-toast` (plus `z-1`, `z-auto`) |
| `aspect-video` | `aspect-wide` (16/9); also `square` `photo` `tv` `ultrawide` |
| `rounded-2xl`, `rounded-3xl` | `rounded-xxl`, `rounded-xxxl` (shadows do use `shadow-2xl`) |
| `text-xl`, `text-4xl`, `text-40` | Dynamic `text-xs`…`text-xl` (responsive by design) or static `text-12 14 16 18 20 22 24 26 28 30 32 34 36 48 60 72 96 128`. No 40, 44, 56, 64, 80 |
| `font-italic`, `text-uppercase`, `tracking-loose` | Bare `italic` `non-italic` `uppercase` `lowercase` `capitalize`; `tracking-tighter/tight/normal/wide/wider/widest` |
| `text-blue-500`, `bg-gray-100` | Semantic palette: `text-word` `text-word-2` `bg-surface-1` `border-surface-3` `bg-surface-brand`, and for text in a color a role, `text-brand-readable` `text-danger-readable`, never a shade |
| `space-y-4`, `divide-y` | Not available: use `flex flex-col gap-md` |
| `w-1/2` | Exists, written literally: `w-1/2`, `col-span-6` |
| `border-none` to remove a border | `border-0` (`border-none` is `border-style: none`) |
| `p-30`, `m-11` | The scale has no 11, 15, 30, 60, 72: see the list in utilities.md |

Color semantics: `word` is text (`word-1`…`word-5` progressively fainter), `surface` is
background (`surface-1`…`surface-5` progressively deeper), `surface-{brand,success,…}`
are tinted backgrounds for badges and callouts, `alpha-*` are translucent overlays.
Every palette color has `-lighten-1..5` and `-darken-1..5`, which are fills, plus roles
that stay legible whatever color is set at runtime, in both themes:

| What you are painting | Token, for brand (same for accent, success, danger, info, warning) |
|---|---|
| Text on the page, down to `surface-2` | `text-brand-readable`; a step further, a pressed link: `text-brand-readable-strong` |
| Text on a tinted surface | `bg-surface-brand text-surface-brand-readable` |
| Text on a fill | `bg-brand text-brand-contrast`, `bg-brand-darken-1 text-brand-darken-1-contrast` |
| A bar, a focus ring, a border that shows a state | `bg-brand-graphic`, `border-brand-graphic` (3:1, not text) |

A shade written as text (`text-brand`, `text-danger-darken-1`) reads only by chance: with a
light tenant brand, or in the dark theme, it can fall to 1.5:1.

## Layout recipes (verified)

```html
<main class="container mx-auto px-md py-lg">…</main>

<div class="grid md:grid-cols-2 xl:grid-cols-3 gap-lg">…</div>

<div class="grid lg:grid-cols-12 gap-lg">
  <aside class="lg:col-span-3">…</aside>
  <section class="lg:col-span-9">…</section>
</div>

<div class="flex items-center justify-between gap-sm flex-wrap">…</div>   <!-- toolbar -->
<div class="flex flex-col gap-md">…</div>                                  <!-- stack -->
<div class="flex items-center justify-center min-h-screen">…</div>         <!-- centered -->
<nav class="none md:flex gap-sm">…</nav>                                    <!-- desktop only -->

<h2 class="text-lg font-semibold text-word">Title</h2>
<p class="text-14 text-word-2 leading-relaxed">Secondary copy</p>
<span class="truncate">Long text</span>
```

## Components

Naming: block `.vv-{name}`, element `.vv-{name}__{el}`, modifier `.vv-{name}--{mod}`.
Available: `vv-button` `vv-button-group` `vv-input-text` `vv-textarea` `vv-select`
`vv-checkbox` `vv-radio` `vv-checkbox-group` `vv-radio-group` `vv-input-file`
`vv-input-range` `vv-card` `vv-dialog` `vv-alert` `vv-alert-group` `vv-dropdown`
`vv-dropdown-action` `vv-dropdown-option` `vv-dropdown-optgroup` `vv-nav` `vv-tab`
`vv-accordion` `vv-accordion-group` `vv-table` `vv-badge` `vv-avatar` `vv-avatar-group`
`vv-tooltip` `vv-progress` `vv-skeleton` `vv-spinner` `vv-breadcrumb` `vv-text`
`vv-empty` `vv-separator` `vv-item` `vv-item-group` `vv-field` `vv-prose` `vv-pagination`
`vv-message` `vv-bubble` `vv-bubble-group` `vv-message-scroller` `vv-attachment`
`vv-attachment-group` `vv-marker` `vv-questionnaire` `vv-kbd` `vv-kbd-group`
`vv-popover` `vv-command` `vv-input-otp` `vv-sidebar` `vv-calendar`.

Three facts shape the markup; components.md has the full structure of each component.

**Semantic children replace element classes.** Most elements have an alias, so the
natural tag is styled with no class: `.vv-input-text > label`, `.vv-button > svg`,
`.vv-card > header`, `.vv-dialog > article`, `.vv-accordion > summary`. Elements without
an alias (`__wrapper`, `__content`, `__close`, `__hint` on a `<small>`) need the class.

**States come from the DOM, not from classes.** Each state also has a natural selector:
`[disabled]` or `[aria-disabled="true"]`, `[readonly]`, `[open]`, `[aria-pressed="true"]`,
`[aria-selected="true"]`, `:hover`, `:focus-visible`. Write `<button class="vv-button"
disabled>`; the `--disabled`/`.disabled` classes exist only to freeze a look in docs.
Exception: `current` (nav, tab) is class only.

**Form fields share one skeleton and one token set.** A block `<div>` with a direct-child
`<label>`, a `__wrapper` around the control, a direct-child `<small class="…__hint">`.
`valid`, `invalid`, `loading`, `floating`, `icon-before`, `icon-after` are modifiers on
the block. `disabled` always propagates from the control's attribute through a `:has()`
rule naming that component's own control: `:has(input[disabled])` for a text, file or range
field, `:has(textarea[disabled])` for a textarea, `:has(select[disabled])` for a select.
`readonly`
propagates the same way, but HTML only gives the attribute to a text-type input and a
textarea, so only `vv-input-text` and `vv-textarea` can use it. Everywhere else the recipe
is the same: disable the control, add `tabindex="-1"` and the `--readonly` modifier, which
undoes the disabled dimming. A disabled control submits nothing, so add a hidden input when
the value has to reach the server. Restyle all fields at once with `--input-*` tokens.

```html
<button type="button" class="vv-button vv-button--primary">Save</button>
<button type="button" class="vv-button vv-button--icon-only vv-button--rounded" aria-label="Edit"><svg>…</svg></button>

<div class="vv-input-text vv-input-text--invalid">
  <label for="email">Email</label>
  <div class="vv-input-text__wrapper">
    <input id="email" type="email" name="email" aria-invalid="true" aria-describedby="email-hint" />
  </div>
  <small id="email-hint" class="vv-input-text__hint">Enter a valid address</small>
</div>

<article class="vv-card">
  <header>Title</header>
  <div class="vv-card__content">…</div>
  <footer class="flex justify-end gap-sm">…</footer>
</article>

<dialog class="vv-dialog vv-dialog--small">
  <article class="vv-dialog__wrapper">
    <header class="vv-dialog__header">Title <button type="button" class="vv-dialog__close" aria-label="Close"></button></header>
    <div class="vv-dialog__content">…</div>
    <footer class="vv-dialog__footer"><div class="vv-button-group" role="group">…</div></footer>
  </article>
</dialog>

<div class="vv-alert vv-alert--success vv-alert--dismissable" role="alert">
  <div class="vv-alert__header">
    <svg>…</svg><strong class="vv-alert__title">Saved</strong>
    <button type="button" class="vv-alert__close" aria-label="Close"></button>
  </div>
  <div class="vv-alert__content">Your changes are live.</div>
</div>
```

Button modifiers: `primary` `secondary` `danger` `ghost` `link` `action` `action-quiet`
`static-light` `static-dark` `icon-only` `rounded` `block` `reverse` `column` `full-bleed`.
The default button is the brand accent; there is no `accent`, `loading` or size modifier.

Traps: `vv-dialog` needs the `<article class="vv-dialog__wrapper">` panel (the
`<dialog>` itself is the backdrop) and has no `__title`; `vv-alert` has no
`__description`/`__action`, icon and title live in `__header`; `vv-card__picture` goes
on the `<img>`; `vv-alert-group` wraps its alerts in `<div role="group">`; the checkbox
switch is `vv-checkbox--switch`; `vv-input-range` needs
`style="--input-range-progress: 45%"` on the block or the track renders empty.

## Tokens and theming

Tokens live on `:where(:host, :root, .theme)`, so `:root { --color-brand: #45cb85 }`
recolors the whole palette (shades derive with relative color syntax; there are no
`--color-brand-hue/saturation/lightness` channels). Component properties are prefixed
with the block: `--vv-button-background`, `--vv-button-state-hover-background`,
`--vv-button-modifier-primary-background`. Fields share `--input-*`.

```css
:root, :host, .theme { --color-brand: #45cb85; --color-tint: #45cb85; --rounded: 0.5rem; }
```

`--rounded` is the base of the radius scale: `--rounded-sm` … `--rounded-xxxl` are multiples
of it, so it rescales every corner (`none` and `full` stay). `--color-tint` gives the brand hue to gray, word and surface too; leave it out to keep the
neutrals. The readable, contrast and graphic roles follow the new brand by themselves. A
new button variant goes through the SCSS map (see scss.md) or, in plain CSS, names the
hover state itself, since a class beats the zero specificity of the library's state
rules: the recipe is in tokens.md.

Dark theme is a separate stylesheet (`@import '@volverjs/style/themes/dark'` or
`@use '@volverjs/style/scss/themes/dark'`) loaded after the base. With it loaded the page
follows `prefers-color-scheme`; force with `class="theme theme--dark"` or
`class="theme theme--light"` on `<html>` or on any subtree. Both classes are required;
there is no `data-theme`. Keep custom colors as `var(--color-…)` so they follow the theme.

## SCSS

```scss
@use '@volverjs/style/scss/context' with (
  $color-brand: #45cb85,
  $font-family-sans: "'Inter', sans-serif",   // one quoted string, or it will not compile
  $use-css-layers: true
);
@use '@volverjs/style/scss';
@use '@volverjs/style/scss/themes/dark';
```

Extend a component by deep-merging its map before the library is emitted
(`ctx.$vv-button: map.deep-merge(ctx.$vv-button, (modifier: (success: (…))))`), create
one with `spread-map-into-bem`, and query breakpoints with `@include ctx.bp-up(md)`, the nearest `@container` with
`@include ctx.cq-up(md)`.
When cherry-picking, alias modules that share a basename (`props/spacing` and
`utilities/spacing` collide) and take `scss/props` whole with any component. Layers are
emitted as `volver.reset`, `volver.utilities`, … Details and signatures in scss.md.

## With @volverjs/ui-vue

Vue components render these classes; `modifiers="primary"` becomes `.vv-button--primary`,
so valid modifier names are the ones in components.md. Utilities go on wrappers and
slots as usual (`<VvCard class="mb-lg">`). Import `@volverjs/style` once in the entry
file and the dark theme next to it; toggle `theme theme--dark` on `<html>` (the library
docs use `useDark({ attribute: 'class', valueDark: 'theme theme--dark', valueLight: 'theme theme--light' })`).

## Before you finish

- Every class you wrote is in the references or was confirmed with grep.
- Responsive prefixes only on groups that support them; spacing uses dynamic tokens.
  A `@` container prefix also needs an ancestor with the `@container` class.
- Disabled comes from the attribute, and readonly too where HTML has one; elsewhere
  readonly is the modifier. Hints are linked with `aria-describedby`, labels have `for`.
- Dialogs have the `__wrapper` article; range inputs have `--input-range-progress`.
- Colors are tokens, not hex, so the dark theme keeps working.
- Text in a color is a `-readable` role, text on a fill its `-contrast`, a bar or a ring
  its `-graphic`: never a shade, which stops reading with a light brand or in the dark.

---

# Utility classes

Every class below was verified against `src/settings/*.scss`, `src/utilities/*.scss`
and the compiled `dist/utilities/*.css`. If a class is not in this file, assume it
does not exist and check `node_modules/@volverjs/style/dist/utilities/<group>.css`
before using it.

## How names are built

- `{prefix}-{value}` for most groups: `p-16`, `gap-md`, `text-brand`, `w-1/2`.
- **Bare value names** (no prefix) for display, position, visibility, font style,
  text transform, text decoration line, font smoothing and font-variant-numeric:
  `flex`, `grid`, `none`, `relative`, `invisible`, `italic`, `uppercase`, `underline`.
- Responsive variant: `{breakpoint}:{class}`, mobile-first (`min-width`), **only for
  the groups marked "Responsive: yes" below**. Prefixes: `xs:` `sm:` `md:` `lg:` `xl:`
  `xxl:` `xxxl:`. There is no `xxs:` prefix (xxs is 0px, the unprefixed class).

| Breakpoint | xs | sm | md | lg | xl | xxl | xxxl |
|---|---|---|---|---|---|---|---|
| min-width | 360px | 576px | 992px | 1024px | 1280px | 1440px | 1536px |

- Container variant: `@{step}:{class}` (`@md:flex-row`), the width of the nearest ancestor
  with the `@container` class (`container-type: inline-size`); with none it never applies.
  Only for display, `flex-` direction and wrap, `justify-` `content-` `justify-items-`
  `items-`, `grid-cols-`, `col-` (span, auto, full) and `text-` align. Emitted after the
  responsive classes of the same utility, so it wins when both apply.

| Container step | @xs | @sm | @md | @lg | @xl | @xxl | @xxxl |
|---|---|---|---|---|---|---|---|
| min-width | 20rem | 24rem | 28rem | 32rem | 36rem | 42rem | 48rem |

## Scales shared by several groups

**Static spacing scale** (used by margin, padding, gap, inset, sizing):

```text
0 px 1 2 3 4 5 6 7 8 9 10 12 14 16 18 20 22 24 26 28 32 34 36 38 40 44 48 50 52 56 64
80 96 100 112 128 144 150 160 176 192 208 224 240 256 288 300 320 384
```

There is no 11, 15, 30, 60 or 72 step. `px` is 1px.

**Dynamic spacing scale**: `xs` `sm` `md` `lg` `xl`. Each one resolves to a different
static step per viewport, so the same class breathes on larger screens:

| token | < 576px | ≥ 576px | ≥ 1024px |
|---|---|---|---|
| xs | 6 | 8 | 10 |
| sm | 10 | 12 | 14 |
| md | 12 | 14 | 16 |
| lg | 16 | 22 | 36 |
| xl | 24 | 36 | 48 |

Prefer the dynamic tokens for layout rhythm (`p-md`, `gap-lg`, `mb-xl`) and static
numbers only for pixel-exact needs. Spacing utilities have **no** responsive
variants, so `md:p-16` does nothing: the dynamic tokens are how spacing adapts.

**Color names** (used by `text-`, `bg-`, `border-`, `decoration-`):

```text
brand accent success danger info warning gray      each also -lighten-1..5 and -darken-1..5
brand-contrast accent-contrast success-contrast     white or black, the text that reads on that fill,
danger-contrast info-contrast warning-contrast      also -darken-1..5-contrast, text- only (no gray-contrast)
brand-readable brand-readable-strong               the color as text on the surface, text- only
surface-brand-readable surface-success-readable ...  the color as text on its tinted surface, text- only
brand-graphic accent-graphic ...                    the color as a bar, ring or state border, 3:1
word word-1..word-5                                 text colors, from strongest to faintest
surface surface-1..surface-5                        backgrounds, from page to deepest inset
surface-brand surface-accent surface-success surface-danger surface-info surface-warning
alpha alpha-1..alpha-5                              translucent overlays
white black transparent shadow backdrop
```

## Spacing (not responsive)

| Class | Values | Notes |
|---|---|---|
| `m-` `mx-` `my-` `mt-` `mr-` `mb-` `ml-` | spacing scale + dynamic | margin |
| `p-` `px-` `py-` `pt-` `pr-` `pb-` `pl-` | spacing scale + dynamic | padding |
| `n-` `nx-` `ny-` `nt-` `nr-` `nb-` `nl-` | spacing scale + dynamic | **negative** margin (`n-16` = `margin: -16`) |
| `m-auto` `mx-auto` `my-auto` `mt-auto` `mr-auto` `mb-auto` `ml-auto` | | margin only, no `p-auto` |

## Layout

| Class | Values | Responsive |
|---|---|---|
| display (bare) | `block` `inline-block` `inline` `flex` `inline-flex` `grid` `inline-grid` `none` | yes |
| display (bare) | `table` `inline-table` `table-caption` `table-cell` `table-column` `table-column-group` `table-footer-group` `table-header-group` `table-row-group` `table-row` `flow-root` `contents` `list-item` | no |
| position (bare) | `static` `fixed` `absolute` `relative` `sticky` | yes |
| visibility (bare) | `visible` `invisible` | yes |
| `inset-` `inset-x-` `inset-y-` `top-` `right-` `bottom-` `left-` | spacing scale + dynamic + `1/2` `1/3` `2/3` `1/4` `2/4` `3/4` `full` `auto` | no |
| `z-` | `1` `sticky` `fixed` `dropdown` `modal-backdrop` `modal` `confirm-backdrop` `confirm` `popover` `tooltip` `toast` `notification-alert` `auto` | no |
| `overflow-` `overflow-x-` `overflow-y-` | `visible` `hidden` `scroll` `auto` | no |
| `scrollbar-` | `thin` (thin, `word-5` thumb on a transparent track) `none` (hidden, still scrolls) | no |
| `container` | | width 100%, max-width follows the current breakpoint, the whole width below `xs` (360px); no size suffixes |
| `@container` | | `container-type: inline-size`, the box the `@` variants measure; it stops taking its width from its content, so not on an `inline-flex` or a flex item with no basis; no prefixes |
| `aspect-` | `auto` `square` `photo` (3/2) `tv` (4/3) `wide` (16/9) `ultrawide` (21/9) | yes |
| `object-` (fit) | `fill` `contain` `cover` `none` `scale-down` | no |
| `object-` (position) | `top` `bottom` `left` `right` `center` `left-top` `left-bottom` `right-top` `right-bottom` | no |
| `columns-` | `1`..`12` | yes |
| `break-after-` `break-before-` | `auto` `avoid` `all` `avoid-page` `page` `left` `right` `column` | no |
| `break-inside-` | `auto` `avoid` `avoid-page` `avoid-column` | no |

The z-index scale is semantic and stacks in the order listed (1, 1010, 1020, 1025,
1030, 1040, 1050, 1060, 1070, 1080, 1090, 1100). There is no `z-10`/`z-50`.
`display: none` is the class `none`; there is no `hidden` class.

## Flexbox

| Class | Values | Responsive |
|---|---|---|
| `flex-` (direction) | `row` `col` `row-reverse` `col-reverse` | yes |
| `flex-` (wrap) | `wrap` `nowrap` `wrap-reverse` | yes |
| `flex-` (size) | `1` `auto` `initial` `none` | yes |
| `grow` `grow-0` `shrink` `shrink-0` | | no |
| `order-` | `1`..`12` `first` `last` `none` | yes |
| `justify-` | `start` `end` `center` `between` `around` `evenly` | yes |
| `justify-items-` | `start` `end` `center` `baseline` `stretch` | yes |
| `justify-self-` | `auto` `start` `end` `center` `baseline` `stretch` | yes |
| `items-` | `start` `end` `center` `baseline` `stretch` | yes |
| `self-` | `auto` `start` `end` `center` `baseline` `stretch` | yes |
| `content-` (align-content) | `start` `end` `center` `between` `around` `evenly` | yes |
| `gap-` `gap-x-` `gap-y-` | spacing scale + dynamic | **no** |

## Grid

All grid utilities are responsive.

| Class | Values |
|---|---|
| `grid-cols-` | `1`..`12` `none` |
| `grid-rows-` | `1`..`6` `none` |
| `col-span-` | `1`..`12` `full`; plus `col-auto` |
| `row-span-` | `1`..`6` `full`; plus `row-auto` |
| `col-start-` `col-end-` | `1`..`13` `auto` |
| `row-start-` `row-end-` | `1`..`7` `auto` |
| `grid-flow-` | `row` `col` `dense` `row-dense` `col-dense` |
| `auto-cols-` `auto-rows-` | `auto` `min` `max` `fr` |

`gap-*` is shared with flexbox and is not responsive.

## Sizing (all responsive)

| Class | Values |
|---|---|
| `w-` | spacing scale, `auto` `full` `screen` `min` `max` `fit`, fractions `1/2` `1/3` `2/3` `1/4` `2/4` `3/4` `1/5`..`4/5` `1/6`..`5/6` `1/12`..`11/12` |
| `h-` | spacing scale, `auto` `full` `screen` `min` `max` `fit`, fractions `1/2`..`5/6` (no twelfths) |
| `max-w-` | spacing scale, `0` `none` `full` `min` `max` `fit` `prose` (65ch), `screen-xs` `screen-sm` `screen-md` `screen-lg` `screen-xl` `screen-xxl` `screen-xxxl` |
| `max-h-` | spacing scale, `full` `screen` `min` `max` `fit` |
| `min-w-` | spacing scale, `0` `full` `min` `max` `fit` |
| `min-h-` | spacing scale, `0` `full` `screen` `min` `max` `fit` |

`screen` uses `100dvw`/`100dvh`. The spacing scale includes the dynamic steps
(`w-md`, `h-lg`), which grow with the viewport like the spacing does. So the Tailwind
container idiom `max-w-md` is 12 to 16px here, not a container width: use
`max-w-screen-md` or `container`. Fractions are written literally in the markup
(`class="w-1/2"`).

## Typography

| Class | Values | Responsive |
|---|---|---|
| `text-` (size, static) | `smaller` `larger` `6` `8` `10` `12` `14` `16` `18` `20` `22` `24` `26` `28` `30` `32` `34` `36` `48` `60` `72` `96` `128` | yes |
| `text-` (size, dynamic) | `xs` `sm` `md` `lg` `xl` | yes |
| `text-` (align) | `left` `center` `right` `justify` `start` `end` | yes |
| `text-` (color) | color names | no |
| `text-ellipsis` `text-clip` `text-balance` | | no |
| `font-` (family) | `sans` `serif` `mono` | no |
| `font-` (weight) | `thin` `extralight` `light` `normal` `medium` `semibold` `bold` `extrabold` `black` | no |
| font style (bare) | `italic` `non-italic` | no |
| `leading-` | `none` `tight` `snug` `normal` `relaxed` `loose` | no |
| `tracking-` | `tighter` `tight` `normal` `wide` `wider` `widest` | no |
| text transform (bare) | `uppercase` `lowercase` `capitalize` `normal-case` | no |
| decoration line (bare) | `underline` `overline` `line-through` `no-underline` | no |
| `decoration-` | color names; style `solid` `double` `dotted` `dashed` `wavy`; thickness `auto` `from-font` `0` `1` `2` `4` `8` | no |
| `underline-offset-` | `auto` `from-font` `0` `1` `2` `4` `8` | no |
| `whitespace-` | `normal` `nowrap` `pre` `pre-line` `pre-wrap` | no |
| word break | `break-normal` `break-words` `break-all` `truncate` | no |
| `align-` (vertical-align) | `baseline` `top` `middle` `bottom` `text-top` `text-bottom` `sub` `super` | no |
| `list-` | `none` `disc` `decimal` `lower-latin` `upper-latin` `lower-roman` `upper-roman` `inside` `outside` | no |
| font smoothing (bare) | `antialiased` `subpixel-antialiased` | no |
| numeric variants (bare) | `normal-nums` `ordinal` `slashed-zero` `lining-nums` `oldstyle-nums` `proportional-nums` `tabular-nums` `diagonal-fractions` `stacked-fractions` | no |

Dynamic text sizes resolve per viewport like dynamic spacing:

| token | < 576px | ≥ 576px | ≥ 1024px |
|---|---|---|---|
| xs | 10 | 12 | 14 |
| sm | 12 | 14 | 16 |
| md | 14 | 16 | 18 |
| lg | 16 | 18 | 20 |
| xl | 18 | 20 | 22 |

There is no `text-40`, `text-44`, `text-56`, `text-64` or `text-80`; the scale jumps
36 → 48 → 60 → 72 → 96 → 128.

## Colors and backgrounds (not responsive)

| Class | Values |
|---|---|
| `text-` `bg-` `border-` `decoration-` | color names (see shared scales) |
| `bg-` (size) | `auto` `cover` `contain` |
| `bg-` (position) | `top` `bottom` `left` `right` `center` `left-top` `left-bottom` `right-top` `right-bottom` |
| `bg-` (repeat) | `repeat` `no-repeat` `repeat-x` `repeat-y` `repeat-round` `repeat-space` |
| `bg-` (attachment) | `fixed` `local` `scroll` |
| `bg-clip-` | `border` `padding` `content` `text` |
| `bg-origin-` | `border` `padding` `content` |
| `bg-gradient-` | `1`..`30`, `brand` `accent` `success` `danger` `info` `warning` `gray` |
| `bg-noise-` | `1`..`5` |
| `bg-` (patterns) | `grid` `chessboard` `check` `chevron` `close` `minus` `none` |

`bg-` is overloaded: `bg-center`, `bg-cover`, `bg-fixed`, `bg-none` are not colors.

Text on a filled color takes the `-contrast` of that color, not `text-white`:
`<span class="bg-brand text-brand-contrast">` stays readable when the brand turns light.
On a darker shade take the contrast of that shade: `bg-warning-darken-5
text-warning-darken-5-contrast`. The contrast colors are `text-` classes only. There is
no `text-tint`: `--color-tint` has no utilities.

Text written in a color takes a readable role, not a shade: `text-brand-readable` on the
page, `text-brand-readable-strong` for a stronger one, and on a tinted surface the role of
that surface, `<div class="bg-surface-success text-surface-success-readable">`. A role is
the color itself while it reads and moves only when it would not reach 4.6:1, darker in the
light theme and brighter in the dark one. They are `text-` classes only: there is no
`bg-brand-readable`, and no `text-brand-darken-1-readable`.

## Borders

| Class | Values | Responsive |
|---|---|---|
| `border` `border-0` `border-2` `border-4` `border-8` | width (bare `border` = 1px) | yes |
| `border-x-` `border-y-` `border-t-` `border-r-` `border-b-` `border-l-` | `0` `2` `4` `8`; bare side (`border-t`) = 1px | yes |
| `border-` (style) | `solid` `dashed` `dotted` `double` `hidden` `none` | yes |
| `border-` (color) | color names | no |
| `rounded` `rounded-` | `none` `sm` (bare `rounded` = .25rem) `md` `lg` `xl` `xxl` `xxxl` `full` | no |
| `rounded-t-` `rounded-b-` `rounded-tl-` `rounded-tr-` `rounded-bl-` `rounded-br-` | same radius names; bare corner (`rounded-tl`) = .25rem | no |

`border-none` sets `border-style: none`; to remove a border width use `border-0`.
The radius scale is `xxl`/`xxxl`, not `2xl`/`3xl`.

## Effects, filters, transitions (not responsive)

| Class | Values |
|---|---|
| `shadow` `shadow-` | `sm` (bare `shadow` = default) `md` `lg` `xl` `2xl` `inner` `none` |
| `opacity-` | `0` `5` `10` … `95` `100` (every multiple of 5) |
| `mix-blend-` `bg-blend-` | CSS blend mode names (`multiply` `screen` `overlay` …) |
| `blur` `blur-` | `none` `sm` (4px) `md` (12px) `lg` (16px) `xl` (24px) `xxl` (40px) `xxxl` (64px); bare `blur` = 8px |
| `backdrop-blur` `backdrop-blur-` | `none` `sm` `md` `lg` `xl` `xxl` `xxxl`; bare `backdrop-blur` = 8px (`backdrop-blur-blur` is kept as an alias) |
| `brightness-` | `0` `50` `75` `90` `95` `100` `105` `110` `125` `150` `200` `250` `500` `1000` |
| `contrast-` | `0` `50` `75` `100` `125` `150` `200` `300` |
| `saturate-` | `0` `50` `100` `150` `200` |
| `transition-` | `none` `all` `colors` `opacity` `shadow` `transform` (each sets duration 300 and ease-in-out) |
| `transition-property-` | same names, property only |
| `duration-` `delay-` | `75` `100` `150` `200` `300` `500` `700` `1000` |
| `ease-` | `linear` `in` `out` `in-out` |

Transition and duration tokens are `0s` unless the user has
`prefers-reduced-motion: no-preference`, so motion switches itself off for users
who asked for it, and the `duration-` and `delay-` classes read them. The shadow,
opacity, filter, `transition-property-` and `ease-` classes read their tokens too, with
the value as a fallback, so a token set on the page reaches them. There are no `animate-*` utilities; animation keyframes exist only
as `--animation-*` custom properties.

## Transforms (not responsive)

| Class | Values |
|---|---|
| `scale-` `scale-x-` `scale-y-` | `0` `50` `75` `90` `95` `100` `105` `110` `125` `150` |
| `rotate-` | `0` `1` `2` `3` `6` `12` `45` `90` `180` |
| `translate-` `translate-x-` `translate-y-` | `1/2` `1/3` `2/3` `1/4` `2/4` `3/4` `full` |
| `-translate-` `-translate-x-` `-translate-y-` | same, negative |
| `origin-` | `center` `top` `top-right` `top-left` `bottom` `bottom-right` `bottom-left` `right` `left` |

## Interactivity and tables (not responsive)

| Class | Values |
|---|---|
| `cursor-` | `auto` `default` `pointer` `wait` `text` `move` `help` `not-allowed` `none` `grab` `grabbing` `zoom-in` `zoom-out` `progress` `crosshair` `copy` `alias` `cell` `context-menu` `no-drop` `vertical-text` `all-scroll` `col-resize` `row-resize` `n-resize` `e-resize` `s-resize` `w-resize` `ne-resize` `nw-resize` `se-resize` `sw-resize` `ew-resize` `ns-resize` `nesw-resize` `nwse-resize` |
| `pointer-events-` | `none` `auto` |
| `user-select-` | `none` `text` `all` `auto` |
| table (bare) | `border-collapse` `border-separate` `table-auto` `table-fixed` |

---

# Components

Verified against `src/settings/components/_vv-*.scss`, `dist/components/*.css` and the
canonical examples in `docs/contents/components/`. Every class named here exists;
markup shown is the documented structure.

## Rules that apply to every component

**Naming.** Block `.vv-{name}`, element `.vv-{name}__{element}`, modifier
`.vv-{name}--{modifier}`. The `vv` prefix follows `$components-prefix`.

**Semantic children replace element classes.** Many elements carry an alias, so the
library styles the natural HTML child and the BEM class is optional. Marked with † in
the tables below. Examples: `.vv-input-text > label` (no `__label` needed),
`.vv-button > svg`, `.vv-card > header`, `.vv-dialog > article`. Elements without an
alias (`__wrapper`, `__content`, `__close`, `__hint` on `<small>`... see tables) need
the class. Using the alias form keeps markup lean; using the class is never wrong.

**States have three equivalent hooks.** For each state the library emits the BEM class
(`.vv-button--disabled`), a bare class (`.vv-button.disabled`) and the natural selector
(`[disabled]`, `:hover`, `[open]`, `[aria-pressed="true"]`...). Use the natural one in
real markup; the classes exist to freeze a look for docs and tests.

| state | natural selector |
|---|---|
| disabled | `[disabled]` or `[aria-disabled="true"]` |
| readonly | `[readonly]` |
| checked / indeterminate | `:checked` / `:indeterminate` |
| open / close | `[open]` / `:not([open])` |
| pressed | `[aria-pressed="true"]` |
| selected | `[aria-selected="true"]` |
| dirty | `:not(:has(*:placeholder-shown))` |
| popover | `[popover]` |
| hover, active, focus-visible, focus-within, target, empty | the pseudo-class itself |
| current (nav, tab) | **class only**: `class="vv-nav__item-label current"` |

**Form components share one pattern.** `vv-input-text`, `vv-textarea`, `vv-select`,
`vv-input-file`, `vv-input-range`: a block `<div>` containing, in order, a direct-child
`<label>`, a `__wrapper` holding the control, and a direct-child `<small class="…__hint">`.
On these components:

- `valid`, `invalid`, `loading`, `floating`, `icon-before`, `icon-after` are **modifier
  classes** on the block. `aria-invalid` is good a11y but styles nothing.
- `disabled` propagates from the attribute on the control, through a `:has()` rule naming
  that component's own control, so no class is needed (`vv-input-text--disabled` also
  works). The rule is `:has(input[disabled])` for `vv-input-text`, `vv-input-file` and
  `vv-input-range`, `:has(textarea[disabled])` for `vv-textarea` and
  `:has(select[disabled])` for `vv-select`.
- `readonly` propagates the same way, but only where HTML has the attribute, which is a
  text-type input and a textarea: `vv-input-text` and `vv-textarea`, through
  `:has(input[readonly])` and `:has(textarea[readonly])`.

  Everywhere else the attribute does not exist, so the read-only look is a modifier and the
  recipe is the same for all of them: disable the control, add `tabindex="-1"` and
  `--readonly`, which undoes the disabled dimming. It applies to `vv-select`,
  `vv-input-range`, `vv-checkbox`, `vv-radio` and `vv-input-file`, whose readonly state
  hides the drop area and freezes the wrapper background. `vv-input-file` does carry a
  `:has(input[readonly])` hook, but `readonly` is not valid on a file input, so reach it
  through the modifier rather than writing the attribute.

  A disabled control contributes nothing to form submission, so pair it with a hidden input
  carrying the same name when the value has to reach the server.
- Their look comes from the shared `--input-*` tokens (`--input-background-color`,
  `--input-color`, `--input-min-height`, `--input-label-*`, `--input-hint-*`,
  `--input-valid-color`, `--input-invalid-color`); override those to restyle every field
  at once.

## vv-button

Only `a[href]`, `button`, `input[type=button|submit|reset]` receive the block styles; a
`<div class="vv-button">` or an `<a>` without `href` stays unstyled. Icons are direct
children (`svg` or `[data-icon]`), no class needed. Default look is the brand accent.

```html
<button type="button" class="vv-button">Save</button>
<button type="button" class="vv-button vv-button--primary">Primary</button>
<button type="button" class="vv-button vv-button--secondary">Secondary</button>
<button type="button" class="vv-button vv-button--danger">Delete</button>
<button type="button" class="vv-button vv-button--ghost">Ghost</button>
<a href="/docs" class="vv-button vv-button--link">Link</a>

<!-- icon + label; __label only when the text must truncate -->
<button type="button" class="vv-button">
  <svg>…</svg>
  <span class="vv-button__label">Long label that may truncate</span>
</button>

<!-- icon only, round -->
<button type="button" class="vv-button vv-button--icon-only vv-button--rounded" aria-label="Edit">
  <svg>…</svg>
</button>

<button type="button" class="vv-button" disabled>Disabled</button>
<button type="button" class="vv-button vv-button--action" aria-pressed="true">Toggled</button>
```

| elements | modifiers | states |
|---|---|---|
| icon† `> svg, [data-icon]`, label | `primary` `secondary` `danger` `ghost` `link` `static-light` `static-dark` `action` `action-quiet` `icon-only` `rounded` `block` `reverse` `column` `full-bleed` | focus-visible, hover, active, pressed, disabled |

There is no `accent` (it is the default), no `loading`, no `sm`/`lg` size modifier.

## vv-button-group

```html
<div class="vv-button-group" role="group">
  <button type="button" class="vv-button vv-button--secondary">Cancel</button>
  <button type="button" class="vv-button">Confirm</button>
</div>
```

Modifiers: `block` `vertical` `compact`.

## vv-input-text

```html
<div class="vv-input-text">
  <label for="name">Name</label>
  <div class="vv-input-text__wrapper">
    <input id="name" type="text" name="name" placeholder="Jane Doe" aria-describedby="name-hint" />
  </div>
  <small id="name-hint" class="vv-input-text__hint">Shown on your profile</small>
</div>

<!-- icon: unclassed direct child of the wrapper, before or after the input -->
<div class="vv-input-text vv-input-text--icon-before">
  <label for="search">Search</label>
  <div class="vv-input-text__wrapper">
    <svg>…</svg>
    <input id="search" type="search" name="search" placeholder="Search" />
  </div>
</div>

<!-- floating label: label stays outside the wrapper, the input needs a placeholder -->
<div class="vv-input-text vv-input-text--floating">
  <label for="email">Email</label>
  <div class="vv-input-text__wrapper">
    <input id="email" type="email" name="email" placeholder="you@example.com" />
  </div>
</div>

<div class="vv-input-text vv-input-text--invalid">
  <label for="pwd">Password</label>
  <div class="vv-input-text__wrapper">
    <input id="pwd" type="password" name="pwd" aria-invalid="true" aria-describedby="pwd-hint" />
  </div>
  <small id="pwd-hint" class="vv-input-text__hint">At least 8 characters</small>
</div>

<!-- disabled: the attribute is enough -->
<div class="vv-input-text">
  <label for="ro">Code</label>
  <div class="vv-input-text__wrapper"><input id="ro" type="text" value="ABC-123" disabled /></div>
</div>
```

| elements | modifiers | states |
|---|---|---|
| label† `> label`, wrapper, inner, input† `input`, input-before, input-after, number† `input[type=number]`, icon†, icon-after†, actions-group, action, action-chevron, action-chevron-up, hint† `> small`, limit, unit | `icon-before` `icon-after` `valid` `invalid` `loading` `floating` `auto-width` | disabled, readonly, dirty; wrapper: hover, focus-within |

`__unit`, `__limit`, `__actions-group`/`__action` (number stepper, clear button) live
inside the wrapper next to the input. `__inner` is only relevant with `--auto-width`.

## vv-textarea

Same structure as vv-input-text with a `<textarea>` in the wrapper.

| elements | modifiers | states |
|---|---|---|
| label†, wrapper, inner, input† `textarea`, input-before, input-after, icon†, icon-after†, actions-group, hint†, limit | `icon-before` `icon-after` `resizable` `valid` `invalid` `loading` `floating` | disabled, readonly, dirty |

## vv-select

```html
<div class="vv-select">
  <label for="country">Country</label>
  <div class="vv-select__wrapper">
    <select id="country" name="country">
      <option value="">Choose…</option>
      <option value="it">Italy</option>
    </select>
  </div>
  <small class="vv-select__hint">Used for shipping</small>
</div>
```

| elements | modifiers | states |
|---|---|---|
| label†, wrapper, inner, value, input† `select`, input-before, input-after, option†, icon†, icon-after†, action, hint† | `readonly` `dirty` `multiple` `icon-before` `icon-after` `valid` `invalid` `loading` `floating` | disabled; wrapper: hover, focus-within, open |

## vv-checkbox and vv-radio

The block is the `<label>` wrapping the control.

```html
<label class="vv-checkbox">
  <input type="checkbox" name="terms" />
  I accept the terms
  <small>Required</small>
</label>

<label class="vv-checkbox vv-checkbox--switch">
  <input type="checkbox" name="notify" checked />
  Notifications
</label>

<label class="vv-radio">
  <input type="radio" name="plan" value="pro" />
  Pro
</label>
```

| component | elements | modifiers | states |
|---|---|---|---|
| vv-checkbox | input† `> input[type=checkbox]`, label† `> span:not([class])`, hint† `> small` | `readonly` `switch` `segment` `card` `valid` `invalid` | disabled; input: checked, indeterminate, focus-visible; segment and card: checked-within |
| vv-radio | input† `> input[type=radio]`, label† `> span:not([class])`, hint† | `readonly` `segment` `card` `valid` `invalid` | disabled; input: checked, focus-visible; segment and card: checked-within |

The switch modifier is `switch`, not `toggle`. `segment` is one option of a segmented
control (the group takes `--segmented`): the native input is not painted, the tile is the
control, and the keyboard focus draws an outline on the tile through `focus-visible-within`.
`card` draws the option as a bordered tile with the control at the start (the group takes
`--cards`). Both work on a checkbox too, for a choice where more than one option can be on.

```html
<fieldset class="vv-radio-group vv-radio-group--segmented">
  <legend>View</legend>
  <div class="vv-radio-group__wrapper">
    <label class="vv-radio vv-radio--segment"><input type="radio" name="v" checked /><span>Day</span></label>
    <label class="vv-radio vv-radio--segment"><input type="radio" name="v" /><span>Week</span></label>
  </div>
</fieldset>

<label class="vv-radio vv-radio--card">
  <input type="radio" name="plan" value="team" />
  <span><strong class="block">Team</strong> Unlimited agents.</span>
</label>
```

## vv-checkbox-group and vv-radio-group

Identical maps. The block is a `<fieldset>`; vertical is the default (there is no
`--vertical`).

```html
<fieldset class="vv-checkbox-group vv-checkbox-group--horizontal">
  <legend>Channels</legend>
  <div class="vv-checkbox-group__wrapper">
    <label class="vv-checkbox"><input type="checkbox" name="ch" value="email" /> Email</label>
    <label class="vv-checkbox"><input type="checkbox" name="ch" value="sms" /> SMS</label>
  </div>
  <small>Pick at least one</small>
</fieldset>
```

| elements | modifiers |
|---|---|
| legend† `> legend`, wrapper, hint† `> small` | `horizontal` `segmented` `cards` `valid` `invalid` |

## vv-field

The shell of a field around a control the library does not draw (a code editor, a
contenteditable, a button that opens a picker, a switch). Label, box, hint, `valid`,
`invalid`, `loading` and the disabled and readonly states are those of `vv-input-text`.

```html
<div class="vv-field">
  <label id="prompt-label">System prompt</label>
  <div class="vv-field__wrapper">
    <span class="vv-field__before"><svg>…</svg></span>
    <div class="vv-field__control" contenteditable="true" role="textbox" aria-labelledby="prompt-label"></div>
    <span class="vv-field__after">tokens</span>
    <div class="vv-field__toolbar"><button type="button" class="vv-button vv-button--action-quiet">…</button></div>
  </div>
  <small class="vv-field__hint">Markdown is allowed.</small>
</div>
```

| elements | modifiers | states |
|---|---|---|
| label† `> label`, wrapper, control, before, after, toolbar (a row under the control), hint† `> small` | `valid` `invalid` `loading` | disabled and readonly through `:has(.vv-field__control[disabled])` / `[readonly]`, or on the block |

A switch framed like a field is `<label class="vv-checkbox vv-checkbox--switch vv-field__control">`
inside the wrapper.

## vv-input-range

CSS cannot read the value of a range input, so the filled part of the track comes from
`--input-range-progress` set inline on the block as `(value - min) / (max - min)` in
percent. Without it the track renders empty.

```html
<div class="vv-input-range" style="--input-range-progress: 45%">
  <label for="temp">Temperature</label>
  <div class="vv-input-range__wrapper">
    <input id="temp" type="range" name="temp" min="0" max="40" value="18"
           aria-describedby="temp-hint" />
    <div class="vv-input-range__value">18 <span class="vv-input-range__unit">°C</span></div>
  </div>
  <small id="temp-hint" class="vv-input-range__hint">Drag to set the target</small>
</div>

<!-- HTML has no readonly range: disable the input, drop it out of the tab order and
     add the modifier, which undoes the disabled dimming. The hidden input carries the
     value to the server, which a disabled control never does. -->
<div class="vv-input-range vv-input-range--readonly" style="--input-range-progress: 45%">
  <div class="vv-input-range__wrapper">
    <input type="range" min="0" max="40" value="18" disabled tabindex="-1" />
  </div>
  <input type="hidden" name="temp" value="18" />
</div>
```

| elements | modifiers | states |
|---|---|---|
| label†, wrapper, input-before, input† `input[type=range]`, input-after, value, unit, hint† | `valid` `invalid` `readonly` | disabled (attribute or `:has(input[disabled])`) |

Tokens: `--input-range-accent-color`, `--input-range-track-color`,
`--input-range-track-height`, `--input-range-thumb-size`, `--input-range-thumb-shadow`.

## vv-input-file

Same label/wrapper/hint skeleton as vv-input-text with `<input type="file">`. Extra
elements build the drop zone and the file list; read
`docs/contents/components/input-file/` or the settings map before using them.

| elements | modifiers | states |
|---|---|---|
| label†, wrapper, inner, input† `input[type=file]`, input-before, input-after, icon†, icon-after†, hint†, drop-area, drop-area-action, preview, progress, list, item, item-name, item-info, item-link, item-icon, item-action, item-remove | `icon-before` `icon-after` `with-progress` `valid` `invalid` `loading` `hidden` `dragging` `square` `circle` | disabled, readonly |

## vv-card

`__picture` goes on the `<img>`, not on a wrapper. `<header>` and `<footer>` direct
children are styled without a class.

```html
<article class="vv-card">
  <header>Title</header>
  <picture><img class="vv-card__picture aspect-photo" src="…" alt="…" /></picture>
  <div class="vv-card__content">Body copy</div>
  <footer class="flex items-center gap-sm">
    <button type="button" class="vv-button vv-button--secondary">Action</button>
  </footer>
</article>

<article class="vv-card vv-card--glass">…</article>
```

| elements | modifiers |
|---|---|
| header† `> header`, picture† `> picture > img`, content, footer† `> footer` | `glass` |

## vv-alert

Icon and title live inside `__header`; the close button is an empty `<button>` whose
glyph is a background image. There is no `__description` or `__action`.

```html
<div class="vv-alert vv-alert--danger vv-alert--dismissable" role="alert">
  <div class="vv-alert__header">
    <svg>…</svg>
    <strong class="vv-alert__title">Operation failed</strong>
    <button type="button" class="vv-alert__close" aria-label="Close"></button>
  </div>
  <div class="vv-alert__content">The server rejected the request.</div>
  <div class="vv-alert__footer">
    <div class="vv-button-group" role="group">
      <button type="button" class="vv-button vv-button--secondary">Retry</button>
    </div>
  </div>
</div>
```

Use `role="alertdialog"` with `aria-labelledby`/`aria-describedby` when the alert has
controls.

| elements | modifiers |
|---|---|
| header, title, content, footer, close, icon, close-mask | `success` `danger` `warning` `info` `accent` `brand` `dismissable` `nowrap` `notification` `callout` `auto-close`; transitions `fade` `fade-inline-end` `fade-inline-start` `fade-block-top` `fade-block-bottom` |

### vv-alert-group

Positioned stacks of notifications. The alerts sit in an inner `<div role="group">`.

```html
<div class="vv-alert-group vv-alert-group--fixed vv-alert-group--top-end">
  <div role="group">
    <div class="vv-alert vv-alert--notification vv-alert--success">…</div>
  </div>
</div>
```

Modifiers: `fixed` `absolute` `reverse` `stack` `full-bleed`, position `top-start`
`top-middle` `top-end` `center-start` `center-middle` `center-end` `bottom-start`
`bottom-middle` `bottom-end`.

## vv-dialog

The `<dialog>` block is the backdrop; the panel is the mandatory `<article>` child
(`__wrapper`). The header holds the title text directly (no `__title`). Opened with
`showModal()` it fades in and closes at once; the `fade-*`, `scale` and `slide-*` modifiers
are the classes of a Vue `<Transition>`.

```html
<dialog class="vv-dialog vv-dialog--small" id="confirm">
  <article class="vv-dialog__wrapper">
    <header class="vv-dialog__header">
      Delete item?
      <button type="button" class="vv-dialog__close" aria-label="Close"></button>
    </header>
    <div class="vv-dialog__content"><p>This cannot be undone.</p></div>
    <footer class="vv-dialog__footer">
      <div class="vv-button-group" role="group">
        <button type="button" class="vv-button vv-button--secondary">Cancel</button>
        <button type="button" class="vv-button vv-button--danger">Delete</button>
      </div>
    </footer>
  </article>
</dialog>
```

| elements | modifiers | states |
|---|---|---|
| wrapper† `> article`, header† `> article > header`, close, content, footer† `> article > footer` | `small` `fullscreen` `drawer` (inline end) `drawer-start` `drawer-top` `drawer-bottom` (the bottom sheet of a phone); transitions `fade-block` `fade-inline` `scale` `slide-inline-end` `slide-inline-start` `slide-block-start` `slide-block-end` (pair each drawer with the slide from its side) | open `[open]`, close `:not([open])` |

## vv-dropdown family

`vv-dropdown` is a popover container (`[popover]`) positioned by script in
`@volverjs/ui-vue`. Its list is a `div[role=menu]` or `div[role=listbox]` (a `<ul>` needs
the `__list` class). Items are `vv-dropdown-action` (buttons) or `vv-dropdown-option`
(selectable, `aria-selected`), grouped by `vv-dropdown-optgroup`.

```html
<div class="vv-dropdown vv-dropdown--rounded" popover id="menu">
  <div role="menu">
    <button type="button" class="vv-dropdown-action">Rename</button>
    <button type="button" class="vv-dropdown-action" disabled>Archive</button>
  </div>
</div>
```

| component | elements | modifiers | states |
|---|---|---|---|
| vv-dropdown | list†, item†, item-first†, item-last†, item-not-last†, search, arrow | `rounded` `block` `bottom` `top` `full-bleed` `dialog` `mobile` | popover |
| vv-dropdown-action | | | disabled, hover, focus-visible, pressed |
| vv-dropdown-option | hint, label | `unselectable` `inert` | disabled, focus-visible, selected |
| vv-dropdown-optgroup | | | |

## vv-nav

```html
<nav class="vv-nav">
  <ul>
    <li><a href="/" class="current">Home</a></li>
    <li><a href="/docs">Docs</a></li>
    <li role="separator"></li>
    <li><button type="button">Sign out</button></li>
  </ul>
</nav>
```

| elements | modifiers | states |
|---|---|---|
| menu† `ul`, item† `li`, item-label† `li > :is(a, button)`, heading-label, separator† `li[role=separator]` | `sidebar` `aside` `tabs` `full` | item-label: hover, current (class only), disabled |

## vv-tab

Panels toggle on `:target` or the `target` class.

| elements | states |
|---|---|
| panel | panel: target |

## vv-accordion

The height of the content animates where the browser has `::details-content` and
`interpolate-size` (Chrome); elsewhere the accordion opens at once.

```html
<details class="vv-accordion vv-accordion--bordered">
  <summary>Shipping</summary>
  <div>Delivered in 3 to 5 days.</div>
</details>

<div class="vv-accordion-group vv-accordion-group--condensed">
  <details class="vv-accordion" name="faq">…</details>
  <details class="vv-accordion" name="faq">…</details>
</div>
```

| component | elements | modifiers | states |
|---|---|---|---|
| vv-accordion | summary† `> summary`, content† `> summary + *` | `marker-right` `bordered` `square` | open `[open]`, disabled |
| vv-accordion-group | not-last-child† | `condensed` | |

## vv-table

Plain semantic table, no cell classes needed.

```html
<table class="vv-table vv-table--bordered">
  <caption>Orders</caption>
  <thead><tr><th>Id</th><th>Total</th></tr></thead>
  <tbody><tr><td>1042</td><td>€ 120</td></tr></tbody>
</table>
```

Modifiers: `inline-spacing` `bordered`. Body rows take `selected` (`aria-selected="true"`) and
`current` (class on the `tr`: the row looked at in a master list, a bar along the start). A
sortable column carries `aria-sort="none|ascending|descending"` on the `th` and a
`<button type="button" class="vv-table__sort">` inside it; the chevron indicator is drawn
after the button.

## vv-pagination

```html
<nav class="vv-pagination" aria-label="Pages">
  <span class="vv-pagination__summary">21-40 of 240</span>
  <ul class="vv-pagination__list">
    <li><a class="vv-pagination__page" href="?p=1">1</a></li>
    <li><a class="vv-pagination__page" href="?p=2" aria-current="page">2</a></li>
    <li><span class="vv-pagination__ellipsis" aria-hidden="true">…</span></li>
  </ul>
</nav>
```

Elements: list† `> :is(ol, ul)` (give the list its class inside `.preflight`, where a bare list is dressed), page, ellipsis, summary. The current page is read from
`aria-current="page"` (state `current-page`); a page that cannot be reached is `disabled` or
`aria-disabled="true"`.

## vv-badge, vv-avatar, vv-avatar-group

```html
<span class="vv-badge vv-badge--success">Paid</span>
<span class="vv-badge vv-badge--outline vv-badge--sm">Draft</span>
<span class="vv-badge vv-badge--action">Tag <button type="button" aria-label="Remove"></button></span>

<img class="vv-avatar vv-avatar--rounded" src="…" alt="Jane" />
<div class="vv-avatar vv-avatar--lg vv-avatar--ring">
  <img src="…" alt="Jane" />
  <sup>3</sup>
</div>

<div class="vv-avatar-group vv-avatar-group--tight">
  <img class="vv-avatar vv-avatar--rounded" src="…" alt="" />
  <img class="vv-avatar vv-avatar--rounded" src="…" alt="" />
</div>
```

| component | elements | modifiers |
|---|---|---|
| vv-badge | button† `> button` | `action` `sm` `rounded` `white` `black` `danger` `success` `warning` `info` `accent` `gray` `outline` `ghost` (brand is the default) |
| vv-avatar | badge† `> sup`, badge-bottom† `> sub`, image† `> img` | `rounded` `square` `bordered` `md` `lg` `transparent` `surface` `danger` `success` `warning` `info` `accent` `gray` `ring` |
| vv-avatar-group | item† `> *`, item-not-first† | `tight` `relaxed` |

## vv-tooltip, vv-progress, vv-skeleton, vv-breadcrumb, vv-text

```html
<button type="button" class="vv-button">
  Save
  <span class="vv-tooltip vv-tooltip--top" role="tooltip" inert>Ctrl+S</span>
</button>

<progress class="vv-progress" value="40" max="100"></progress>
<progress class="vv-progress"></progress> <!-- indeterminate -->

<div class="vv-skeleton"><div class="vv-skeleton__item"></div></div>

<nav class="vv-breadcrumb" aria-label="Breadcrumb">
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/docs">Docs</a></li>
    <li>Buttons</li>
  </ol>
</nav>

<h1 class="vv-text vv-text--headline vv-text--size-1">Title</h1>
<p class="vv-text vv-text--copy">Body copy</p>
<a href="#" class="vv-text vv-text--link">Read more</a>
```

| component | elements | modifiers | states |
|---|---|---|---|
| vv-tooltip | | `visible` `top` `bottom` `left` (default inline-end) | |
| vv-progress | | | indeterminate |
| vv-skeleton | item | | |
| vv-breadcrumb | list† `> ol`, item† `li:has(a)`, item-active† `li:not(:has(a))`, link† `li > a` | `multiline` | link: hover, focus-within, active |
| vv-text | | `headline` `copy` `link` `quote` `size-1`..`size-6` | link: focus-visible, hover, active, disabled |

## vv-empty, vv-separator, vv-spinner

```html
<div class="vv-empty">
  <div class="vv-empty__media"><svg width="1em" height="1em">…</svg></div>
  <h3 class="vv-empty__title">No messages yet</h3>
  <p class="vv-empty__description">When someone writes to you, it shows up here.</p>
  <div class="vv-empty__actions"><button type="button" class="vv-button">New message</button></div>
</div>

<hr class="vv-separator" />
<div class="vv-separator"><span>or</span></div>
<div class="vv-separator vv-separator--vertical" role="separator" aria-orientation="vertical"></div>

<span class="vv-spinner" role="status" aria-label="Loading"></span>
<button type="button" class="vv-button" disabled><span class="vv-spinner" aria-hidden="true"></span> Saving</button>
```

| component | elements | modifiers | tokens |
|---|---|---|---|
| vv-empty | media, title, description, actions | `compact` (inside a list, a table or a card) `bordered` (dashed frame, drop zone) | |
| vv-separator | label† `> span` | `vertical` | the line takes the block's `border-color`: set it on the block, or `--vv-separator-border-color` when components use custom properties |
| vv-spinner | | | `--spinner-duration`, `--spinner-thickness`, read on the block |

The icon in `vv-empty__media` is sized by the font size, so give it `1em`. The spinner is
`1em` in `currentcolor`: size and colour it with text utilities (`text-24 text-brand-graphic`,
the graphic role, which keeps 3:1 with any brand). Under
`prefers-reduced-motion` it keeps turning, slower, instead of stopping.

## vv-item, vv-item-group

A row of a list, and the list. The row is not the button: its `__entry` is (a `<button>` or
an `<a>`), because the row can hold other controls beside it.

```html
<div class="vv-item-group vv-item-group--framed">
  <div class="vv-item-group__header"><nav class="vv-breadcrumb">…</nav></div>
  <ul class="vv-item-group__list">
    <li class="vv-item">
      <button type="button" class="vv-item__entry" aria-pressed="true">
        <span class="vv-item__media"><svg>…</svg></span>
        <span class="vv-item__title">Contracts</span>
        <svg class="vv-item__check">…</svg>
      </button>
      <button type="button" class="vv-item__open" aria-label="Open"><svg>…</svg></button>
    </li>
    <li class="vv-item vv-item--roomy vv-item--current">
      <a href="#" class="vv-item__entry" aria-current="true">
        <span class="vv-item__content">
          <span class="vv-item__title">Invoice reminder</span>
          <span class="vv-item__description">Sent to 42 customers.</span>
        </span>
      </a>
      <div class="vv-item__actions"><button type="button" class="vv-button vv-button--action-quiet vv-button--icon-only" aria-label="More">…</button></div>
    </li>
  </ul>
</div>
```

| component | elements | modifiers | states |
|---|---|---|---|
| vv-item | entry, media, content, title, description, note, check, chevron, actions, open | `roomy` `top` `plain` | hover; pressed-within (entry `[aria-pressed="true"]`: the chosen row of a picker); current (class only: the row looked at in a master list); entry: focus-visible, disabled |
| vv-item-group | header, list | `framed` `fill` `raised` | |

Selection is surface, weight and a check, never a colour. A title over a description is
semibold on every row, and there the surface and the bar carry the state alone. The group
sets `--item-divider`, `--item-hover`, `--item-chosen` and `--item-current`; rows read them
with a fallback, so a row works outside a group too. An empty list shows a
`vv-empty vv-empty--compact`; a row still loading is a `vv-item--plain` holding
`vv-skeleton__item` bars.

## vv-prose

Rich text that arrives as plain tags (rendered markdown, editor output). No class on the
children: headings, paragraphs, lists, links, `blockquote`, inline `code`, `pre`, `kbd`,
`table`, `hr`, `img`, `details`, and the inline tags whose meaning the reset removes (`em`,
`del`, `u`, `sub`, `sup`, `small`, `mark`, `abbr`).

```html
<div class="vv-prose">
  <h2>Getting started</h2>
  <p>Connect a <a href="#">knowledge base</a>.</p>
  <ul><li>Pick a folder</li></ul>
</div>
<div class="vv-prose vv-prose--compact text-14">…</div>
```

Sizes are in `em` (headings follow the text around them); the rhythm is a margin on every
child after the first, so the block has no outer margin. `compact` sets headings at text size
and halves the gaps. Inside `.preflight` the content of a prose block is left to it.

## Conversation: vv-message, vv-bubble, vv-bubble-group, vv-message-scroller, vv-attachment, vv-attachment-group, vv-marker, vv-questionnaire

```html
<div class="vv-message-scroller" role="log" aria-live="polite">
  <div class="vv-message">
    <span class="vv-avatar vv-avatar--rounded vv-message__avatar">AI</span>
    <div class="vv-message__content">
      <div class="vv-message__header"><strong>Assistant</strong><span class="vv-message__meta">10:42</span></div>
      <div class="vv-bubble-group">
        <div class="vv-bubble">Hi!</div>
        <div class="vv-bubble vv-bubble--reacted">How can I help? <span class="vv-bubble__reactions" role="img" aria-label="2 likes">👍 2</span></div>
      </div>
    </div>
  </div>
  <div class="vv-message vv-message--end">
    <div class="vv-message__content"><div class="vv-bubble vv-bubble--end">An invoice, please.</div></div>
  </div>
  <div class="vv-marker"><span class="vv-marker__content">Maria joined</span></div>
  <button type="button" class="vv-message-scroller__jump" aria-label="Latest message">…</button>
</div>
```

| component | elements | modifiers |
|---|---|---|
| vv-message | avatar, content, header, footer, meta (hover/focus only, always without hover) | `end` (the one reading) `wide` (content takes the row) |
| vv-bubble | reactions | `end` `plain` (no surface) `reacted` (room for reactions); colours from `--bubble-background`, `--bubble-color`, `--bubble-border-color` and the `--bubble-end-*` trio, read with a fallback, so one value on the conversation paints a side |
| vv-bubble-group | joined† `> :not(:first-child)` (load after `vv-bubble`) | `end` |
| vv-message-scroller | jump (sticky, hide with `hidden`) | `fade` |
| vv-attachment | media, picture† `img`, content, title, description, actions, remove | `image` `invalid` `loading` |
| vv-attachment-group | | |
| vv-marker | icon, content | `bordered` |
| vv-questionnaire | header, progress (`--questionnaire-progress` on the block), item, title (the `legend` of a choice), description, error, actions | |

A date between two days of messages is a `vv-separator` with a label; the choices of a
questionnaire are `vv-radio--card` / `vv-checkbox--card` or a text field.

## vv-kbd, vv-popover, vv-command, vv-input-otp, vv-sidebar, vv-calendar

```html
<span class="vv-kbd-group"><kbd class="vv-kbd">Ctrl</kbd>+<kbd class="vv-kbd">K</kbd></span>

<button type="button" popovertarget="share">Share</button>
<div id="share" class="vv-popover" popover><p class="vv-popover__title">Share</p>…<div class="vv-popover__footer">…</div></div>

<div class="vv-command">
  <div class="vv-command__search"><input class="vv-command__input" role="combobox" aria-expanded="true" /></div>
  <ul class="vv-command__list" role="listbox">
    <li class="vv-command__heading" role="presentation">Documents</li>
    <li class="vv-command__option" role="option" aria-selected="true">New <span class="vv-command__shortcut"><kbd class="vv-kbd">N</kbd></span></li>
  </ul>
</div>

<div class="vv-input-otp" role="group" aria-label="Code">
  <div class="vv-input-otp__group"><input class="vv-input-otp__slot" maxlength="1" /></div>
  <span class="vv-input-otp__separator" aria-hidden="true">–</span>
</div>

<aside class="vv-sidebar vv-sidebar--collapsed">
  <div class="vv-sidebar__header">… <span class="vv-sidebar__label">Product</span></div>
  <nav class="vv-sidebar__content">…</nav>
  <div class="vv-sidebar__footer">…</div>
</aside>

<div class="vv-calendar">
  <div class="vv-calendar__header"><button class="vv-calendar__nav">‹</button><span class="vv-calendar__title">September 2026</span><button class="vv-calendar__nav">›</button></div>
  <table class="vv-calendar__grid" role="grid">
    <thead><tr><th>Mo</th>…</tr></thead>
    <tbody><tr><td aria-selected="true"><button class="vv-calendar__day" aria-pressed="true">10</button></td>…</tr></tbody>
  </table>
</div>
```

| component | elements | modifiers / states |
|---|---|---|
| vv-kbd, vv-kbd-group | | sized in `em` |
| vv-popover | title, footer | `center`; on `[popover]`, placed by a script or anchor positioning, top left without one; fades in and out (`@starting-style`, `allow-discrete`; Safari 17 hides it at once) |
| vv-command | search (focus-within), input, list, heading, option, shortcut, empty | option: `aria-selected="true"`, disabled; groups are `role="group"` labelled by a heading |
| vv-input-otp | group, slot, separator | `invalid` |
| vv-sidebar | header, content, footer, label | `collapsed` (hides `label` from sight, not from AT, and centres the icons of header, content and footer on the rail: wrap every text of the nav in `label`); `--sidebar-width`, `--sidebar-collapsed-width` |
| vv-calendar | header, title, nav, grid† `table`, weekday† `th`, cell† `td`, day | day: `aria-pressed` (chosen, range ends), `aria-current="date"` (today), disabled, a focus ring that also holds for `tabindex="-1"` (roving); cell: `aria-selected` (range) |

---

# Design tokens, CSS-only customization, dark theme

All tokens are CSS custom properties declared on `:where(:host, :root, .theme)`, which
has zero specificity: a plain `:root, :host, .theme { … }` in your stylesheet overrides
any of them without `!important`. `:root` alone does not reach inside an element with the
`theme` class, which declares every token again. The machine-readable copy is
`node_modules/@volverjs/style/design-tokens.json` (keys `volver` and `volver-dark`,
entries shaped `{ value, type }`; read it by path, it has no `exports` entry).

## Token groups

| Group | Custom properties |
|---|---|
| Palette | `--color-{brand,accent,success,danger,info,warning,gray}` each with `-lighten-1..5` and `-darken-1..5` |
| Text on a fill | `--color-{brand,accent,success,danger,info,warning}-contrast` and `--color-{name}-darken-{1..5}-contrast`: pure white or pure black, whichever has the higher WCAG contrast on that shade, so take the one of the shade you fill with (no `--color-gray-contrast`) |
| Text in a color | `--color-{brand,accent,success,danger,info,warning}-readable` (on the neutral surfaces down to `--color-surface-2`: links, outlined badges, tabs, hints), `--color-{name}-readable-strong` (a step further: a pressed link) and `--color-surface-{name}-readable` (on `--color-surface-{name}`: alerts, ring avatars, selected options): the color itself when it already reads, otherwise moved just far enough to keep 4.6:1 (darker in the light theme, brighter and as vivid as it can in the dark one, which redeclares them); the bounds hold for any hue of the tint and of the tinted surface. There are no readable shades: write text in one of the three roles |
| A color seen, not read | `--color-{brand,accent,success,danger,info,warning}-graphic`: the bar of `vv-progress`, a focus ring, a state border. The color itself when it already keeps 3:1 on the neutral surfaces down to `--color-surface-2`, otherwise moved just far enough, closer to the color than a readable role. Every color utility exists (`bg-brand-graphic`, `border-brand-graphic`) |
| Covers | `--color-{brand,...}-cover` and `--color-{name}-darken-{1..5}-cover`: the shade where its contrast text turns dark, transparent otherwise; laid by `vv-button` over its emboss; no utilities |
| Tint | `--color-tint`: the color gray, word, surface, shadow and backdrop take their hue from; the light brand unless set; not redeclared by the dark theme; no utilities |
| Text | `--color-word`, `--color-word-1..5` (progressively fainter) |
| Surfaces | `--color-surface`, `--color-surface-1..5` (progressively deeper), `--color-surface-{brand,accent,success,danger,info,warning}` (tinted) |
| Overlays | `--color-alpha`, `--color-alpha-1..5`, `--color-shadow`, `--color-backdrop`, `--color-transparent`, `--color-white`, `--color-black`, `--color-scheme` |
| Spacing | `--spacing-{0,px,1..384 static steps}`, dynamic `--spacing-{xs,sm,md,lg,xl}` |
| Font family | `--font-sans`, `--font-serif`, `--font-mono` |
| Font weight | `--font-{thin,extralight,light,normal,medium,semibold,bold,extrabold,black}` |
| Font size | `--text-{6..128 static steps}`, `--text-smaller`, `--text-larger`, dynamic `--text-{xs,sm,md,lg,xl}` |
| Line height, tracking | `--leading-{none,tight,snug,normal,relaxed,loose}`, `--tracking-{tighter,tight,normal,wide,wider,widest}` |
| Borders | `--border` (1px), `--border-{0,2,4,8}`, `--rounded`, `--rounded-{none,sm,md,lg,xl,xxl,xxxl,full}`; `sm` … `xxxl` are `calc(var(--rounded) * n)`, so `--rounded` rescales them, declared on the root or on a `.theme` |
| Breakpoints | `--breakpoint-{xs,sm,md,lg,xl,xxl,xxxl}` (no xxs); `--breakpoint-key` and `--breakpoint-value` are re-declared inside each media query and always hold the current breakpoint |
| Layout | `--z-{1,sticky,fixed,dropdown,modal-backdrop,modal,confirm-backdrop,confirm,popover,tooltip,toast,notification-alert,auto}`, `--aspect-*`, `--w-*`, `--h-*` |
| Direction | `--direction`: `1` where the inline axis runs left to right, `-1` where it runs the other way |
| Effects | `--shadow`, `--shadow-{sm,md,lg,xl,2xl,inner,none}`, `--opacity-{0..100 step 5}`, `--blur*`, `--brightness-*`, `--contrast-*`, `--saturate-*` |
| Motion | `--duration-{75..1000}`, `--ease-{linear,in,out,in-out}`, `--transition-{none,all,colors,opacity,shadow,transform}`, `--transition-property-*`, `--animation-{none,indeterminate,progress-indeterminate,spin,ping,pulse,bounce,shine,clippath}` |
| Backgrounds | `--bg-*` (patterns and glyphs such as `--bg-close`, `--bg-chevron`), `--gradient-*` |
| Form fields | `--input-*`: `--input-background-color`, `--input-color`, `--input-min-height`, `--input-gap`, `--input-font-size`, `--input-placeholder-color`, `--input-label-color`, `--input-label-font-size`, `--input-hint-color`, `--input-valid-color`, `--input-invalid-color` (bars and borders, `--color-success-graphic` and `--color-danger-graphic`; the hint text reads `--input-valid-text-color`, `--input-invalid-text-color`, which are `--color-success-readable` and `--color-danger-readable`), `--input-range-*` … |
| Components | `--vv-{block}-{attribute}`, `--vv-{block}-element-{element}-{attribute}`, `--vv-{block}-modifier-{modifier}-{attribute}`, `--vv-{block}-state-{state}-{attribute}` |

Motion tokens (`--duration-*`, `--transition-*`) are `0s`/`none` unless the user has
`prefers-reduced-motion: no-preference`; motion respects the OS setting for free.

`--direction` is set from the `dir` attribute, so it follows the document and any
subtree that declares its own direction. Components multiply inline offsets by it,
because CSS has logical properties for the box (`inset-inline`, `padding-inline`) but
none for `translate`, `rotate` or `scale`. Writing a component that moves along the
inline axis, reach for it the same way: `calc(100% * var(--direction, 1))` to offset,
`var(--direction, 1) 1` as a `scale` to mirror a sideways arrow. Block-axis movement
needs nothing. Set `dir="rtl"` on `<html>` and the library mirrors itself; without it
the token is `1`.

Component properties follow the settings map one to one: every key in
`src/settings/components/_vv-button.scss` becomes `--vv-button-…`. Examples from the
compiled output: `--vv-button-background`, `--vv-button-border-color`,
`--vv-button-state-hover-background`, `--vv-button-element-icon-block-size`,
`--vv-button-modifier-primary-background`. There is no unprefixed `--button-background`.

## CSS-only customization

Brand colors derive their ten shades from the base with relative color syntax
(`hsl(from var(--color-brand) h s calc(l * 1.1))`), so one override recolors everything.
The same goes for `--color-{name}-contrast`, which flips to black when the color turns
light, and for the neutrals, which follow `--color-tint`: rebranding at runtime means
setting both, with the light brand as the tint in both themes. There are no
`--color-brand-hue/saturation/lightness` channels in the default build (they exist only
when the library is compiled with `$use-color-mix: false`, where the contrast tokens are
chosen at compile time and `--color-tint` does not exist).

```css
:root, :host, .theme {
  --color-brand: #45cb85;
  --color-tint: #45cb85; /* gray, word, surface, shadow, backdrop follow its hue */
  --color-accent: #e040fb;
  --font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
  --rounded: 0.5rem; /* the whole radius scale but none and full */
}

/* one component, everywhere */
:root, :host, .theme {
  --vv-button-border-radius: var(--rounded-full);
  --vv-button-font-weight: var(--font-medium);
}

/* a new variant without touching SCSS. A class beats the zero specificity of
   the state rules, so the hover is written out, and each shade takes its own
   contrast text and cover, or a light color gets white text */
.vv-button--success {
  --vv-button-background: var(--color-success);
  --vv-button-border-color: var(--color-success);
  --vv-button-color: var(--color-success-contrast);
  --vv-button-text-shadow: 0 1px 0 var(--color-success-cover), 0 1px 0 var(--color-gray-darken-5);
}
.vv-button--success:not([disabled]):hover {
  --vv-button-background: var(--color-success-darken-1);
  --vv-button-border-color: var(--color-success-darken-1);
  --vv-button-color: var(--color-success-darken-1-contrast);
  --vv-button-text-shadow: 0 1px 0 var(--color-success-darken-1-cover), 0 1px 0 var(--color-gray-darken-5);
}

/* all form fields at once */
:root, :host, .theme {
  --input-min-height: var(--spacing-44);
  --input-background-color: var(--color-surface);
}

/* scoped to a region: <section class="theme marketing-hero"> */
.marketing-hero {
  --color-brand: #ff5722;
}
```

A derived token is computed where it is declared, on `:root` and on every `.theme`
element, so a scoped override only reaches the shades, the contrast tokens and the
`--vv-*` component properties when the element carrying it also has the `theme` class.
Without it the region keeps the root's shades and contrast text: a light brand set on a
plain `<div>` gets the white text computed for the root's brand.

## Dark theme

The dark theme is a separate stylesheet, never part of the main bundle. Load it after
the base:

```css
@import '@volverjs/style';
@import '@volverjs/style/themes/dark';
```

```scss
@use '@volverjs/style/scss';
@use '@volverjs/style/scss/themes/dark';
```

Activation is class based. There is no `data-theme` attribute.

| Markup | Result |
|---|---|
| nothing (or `class="theme"`) | follows `prefers-color-scheme` |
| `<html class="theme theme--dark">` | forced dark |
| `<html class="theme theme--light">` | forced light |
| `<section class="theme theme--dark">` | dark for that subtree only |

Both classes are required for forcing: the emitted selectors are
`:where(.theme.theme--dark)` and, for the automatic branch,
`:where(:host, :root, .theme):not(.theme--light)` inside
`@media (prefers-color-scheme: dark)`.

In a Vue app the reference implementation is `docs/App.vue` in the library repo:
`useDark({ attribute: 'class', valueDark: 'theme theme--dark', valueLight: 'theme theme--light' })`.

Dark values override the same custom properties (`--color-word`, `--color-surface-*`,
`--input-background-color`, `--vv-button-modifier-primary-background` …), so custom CSS
written against tokens adapts automatically. Custom CSS written with hard-coded colors
does not; keep colors as `var(--color-…)`.

---

# SCSS API: imports, configuration, extending components

Verified against `package.json` exports, `src/_config.scss`, `src/_context.scss`,
`src/tools/**`, and by compiling the snippets with the repo's Sass.

## Import paths

CSS (pre-built, `dist/`):

| Path | Content |
|---|---|
| `@volverjs/style` | everything (reset, preflight, props, components, utilities) |
| `@volverjs/style/reset` `…/base` `…/props` `…/components` `…/utilities` | one layer each |
| `@volverjs/style/components/vv-button` (one per component) | a single component |
| `@volverjs/style/props/colors` (one per group) | a single token group |
| `@volverjs/style/utilities/spacing` (one per group) | a single utility group |
| `@volverjs/style/themes/dark` `…/themes/dark/props` `…/themes/dark/components` | dark theme |

Use them with CSS `@import` or a JS `import '@volverjs/style'`.

SCSS (`src/`, prefix every path with `scss/`):

| Path | Content |
|---|---|
| `@volverjs/style/scss` | the full library, configurable through `scss/context` |
| `@volverjs/style/scss/context` | config + settings maps + tools; the module to `@use … with (…)` |
| `@volverjs/style/scss/reset` `…/scss/preflight` `…/scss/base` `…/scss/props` `…/scss/components` `…/scss/utilities` | one layer each |
| `@volverjs/style/scss/components/vv-button`, `…/scss/props/colors`, `…/scss/utilities/spacing` | single modules |
| `@volverjs/style/scss/props/media` | `@custom-media` definitions, opt-in: not part of `scss`, `scss/base` or `scss/props` (see "Custom media") |
| `@volverjs/style/scss/tools` `…/scss/mixins` `…/scss/functions` `…/scss/settings` | tools only, no output |
| `@volverjs/style/scss/themes/dark` (+ `/context` `/props` `/components` `/settings`) | dark theme |

The settings partials (`src/settings/components/_vv-*.scss`) are published but not
exported: read them from `node_modules/@volverjs/style/src/…` as documentation, and
reach the maps through `scss/context`.

## Configuring through the context

Configure once, before the first `@use` that emits CSS. Every settings variable is
`!default`, so they are all reachable from one `with (…)` block on `scss/context`.

```scss
@use '@volverjs/style/scss/context' with (
  $color-brand: #45cb85,
  $color-accent: #e040fb,
  $font-family-sans: "'Inter', sans-serif",
  $use-css-layers: true,
  $preflight: false
);
@use '@volverjs/style/scss';
```

A font stack is **one** quoted string. `$font-family-sans: 'Inter', sans-serif` is a
compile error, because the comma separates configuration entries.

| Variable | Default | Effect |
|---|---|---|
| `$color-brand` `$color-accent` `$color-success` `$color-danger` `$color-info` `$color-warning` `$color-gray` `$color-word` `$color-surface` | brand `#166abd`, accent `#9c27b0` … | palette bases; shades derive |
| `$color-tint` | `$color-brand` | hue of gray, word, surface, shadow and backdrop while they keep their defaults; emitted as `--color-tint` |
| `$color-readable-ratio` | `4.6` | contrast the `-readable` roles keep with what they sit on, in each theme |
| `$color-graphic-ratio` | `3.1` | contrast the `-graphic` roles keep on the same surfaces |
| `$color-readable-depth` | `2` | the deepest neutral surface the roles read on, `--color-surface-2` |
| `$color-readable-strong-factor` `$dark-color-readable-strong-factor` | `0.5`, `1.5` | luminance step from `-readable` to `-readable-strong`, per theme |
| `$font-family-sans` `$font-family-serif` `$font-family-mono` | system stacks | one quoted string each |
| `$font-size` `$font-size-dynamic` `$font-weight` `$spacing` `$spacing-dynamic` `$breakpoints` `$colors` | maps | override the scales themselves |
| `$container-breakpoints` | `xs` 20rem … `xxxl` 48rem | steps of the `@` container variants, all above 0; `()` emits none |
| `$border-radius-fixed` | `(none, full)` | radius steps that keep their value instead of following `--rounded` |
| `$vv-button` `$vv-card` … one per component | maps | see "Extending a component" |
| `$components-prefix` | `vv` | class prefix for every component |
| `$components-names` | map | rename a component, classes and `--vv-*` properties alike, except in `.preflight`, which extends and leaves out the default `vv-` names: a renamed component loses what preflight gives its bare tags, and one renamed outside the prefix is dressed by it. It cannot drop a component, `scss` emits them all, so cherry-pick the modules to leave some out |
| `$preflight` | `true` | emit the opinionated base styles |
| `$use-custom-props-for-components` | `true` | expose `--vv-{block}-*` properties (turn off for a smaller CSS) |
| `$use-color-mix` | `true` | relative color syntax for shades; `false` falls back to HSL channel variables |
| `$use-css-layers` | `false` | wrap output in `@layer` |
| `$layer-order` | `(reset, preflight, props, components, themes, utilities)` | |
| `$layer-prefix` | `'volver'` | layers are emitted as `volver.reset`, `volver.utilities` … |
| `$zero-specificity-for-components` `$zero-specificity-for-utilities` | `true` | wrap selectors in `:where()` |

## Cherry-picking modules

Files that share a basename (`props/spacing` and `utilities/spacing`) collide on the
default namespace, so alias them. Components consume tokens from several prop groups
(borders, typography, effects, transitions, not just colors and spacing): when picking
components, take `scss/props` whole.

```scss
@use '@volverjs/style/scss/context' with ($color-brand: #45cb85);
@use '@volverjs/style/scss/reset';
@use '@volverjs/style/scss/props';
@use '@volverjs/style/scss/utilities/spacing' as utilities-spacing;
@use '@volverjs/style/scss/utilities/layout' as utilities-layout;
@use '@volverjs/style/scss/utilities/flexbox' as utilities-flexbox;
@use '@volverjs/style/scss/components/vv-button';
@use '@volverjs/style/scss/components/vv-card';
```

## Extending a component

Components are SCSS maps. Root keys style the block; `element`, `modifier`, `state`
sub-maps generate BEM selectors; `modifier` can nest `element` and `state`; `pseudo`
targets pseudo-elements; `_alias` lets a plain child tag stand in for an element class.
Deep-merge into the map before the library is emitted:

```scss
@use 'sass:map';
@use '@volverjs/style/scss/context' as ctx;

ctx.$vv-button: map.deep-merge(
  ctx.$vv-button,
  (
    modifier: (
      success: (
        background: var(--color-success),
        border-color: var(--color-success),
        // the text and the cover of each shade, as the brand button has them
        color: var(--color-success-contrast),
        text-shadow: (0 1px 0 var(--color-success-cover), 0 1px 0 var(--color-gray-darken-5)),
        state: (
          hover: (
            background: var(--color-success-darken-1),
            border-color: var(--color-success-darken-1),
            color: var(--color-success-darken-1-contrast),
            text-shadow: (0 1px 0 var(--color-success-darken-1-cover), 0 1px 0 var(--color-gray-darken-5)),
          ),
        ),
      ),
    ),
  )
);

@use '@volverjs/style/scss';
```

Emits `.vv-button--success` with `--vv-button-modifier-success-*` properties and the
hover selector (`.vv-button--success.vv-button:not([disabled]):hover`). Use it as
`class="vv-button vv-button--success"`. Utility maps (`$spacing`, `$colors`, …) can be
extended the same way.

Valid `state` keys: `active` `focus` `hover` `focus-within` `focus-visible` `target`
`visited` `disabled` `readonly` `checked` `checked-within` `focus-visible-within`
`indeterminate` `determinate` `open` `close` `popover` `popover-open` `pressed`
`pressed-within` `selected` `multiple` `dirty` `valid` `invalid` `empty` `placeholder-shown`
`first-child` `last-child` `current` `current-page` (`[aria-current="page"]`) `current-date`
(`[aria-current="date"]`)
`sort-ascending` `sort-descending` `sort-none` (`aria-sort` on a `th`). Other keys are
silently dropped.

The `-within` states match a child of the block: `checked-within` is
`:has(input:checked)`, `focus-visible-within` is `:has(input:focus-visible)` (a keyboard
ring on a tile whose native input is hidden) and `pressed-within` is
`:has(> [aria-pressed="true"])` (a row chosen through the button inside it). The light
rules and the dark theme read the same table, `src/tools/mixin-modules/_states.scss`.

## Presets

`@volverjs/style/scss/presets/outlined-fields` turns every field (`vv-input-text`,
`vv-textarea`, `vv-select`, `vv-input-file`, `vv-field`) from the filled box into an outlined
one: plain surface, 1px border, radius, a ring on focus, the floating label as a notch.
Load it after the context and before the library, or it changes nothing:

```scss
@use '@volverjs/style/scss/context' with (...);
@use '@volverjs/style/scss/presets/outlined-fields';
@use '@volverjs/style/scss';
```

It adds `--input-border-color(-hover)`, `--input-border-radius`, `--input-focus-color`,
`--input-focus-ring`, `--input-invalid-ring` and `--input-disabled-*`, and changes the look
only, not the density.

## Creating a component

```scss
@use '@volverjs/style/scss/context' as ctx;

$my-panel: (
  display: flex,
  gap: var(--spacing-md),
  padding: var(--spacing-lg),
  background: var(--color-surface-1),
  border-radius: var(--rounded-lg),
  element: (
    title: (font-weight: var(--font-semibold), color: var(--color-word-1)),
    body: (flex: 1),
  ),
  modifier: (
    compact: (padding: var(--spacing-sm)),
  ),
  state: (
    hover: (background: var(--color-surface-2)),
  ),
);

@include ctx.spread-map-into-bem(
  $map: $my-panel,
  $block: my-panel,
  $use-custom-props: true,
  $zero-specificity: true,
  $bps: ctx.$breakpoints
);
```

Generates `--my-panel-*` properties, `.my-panel`, `.my-panel__title`, `.my-panel__body`,
`.my-panel--compact` and the hover selectors. A dark variant of a custom component is
built with `spread-theme-component($base-map, $theme-map, $component-name, …)` from
`scss/themes/dark/context`; `src/themes/dark/components/_vv-button.scss` is the model.

A component that wraps a native control needs one extra call, because its own `state`
rules would compile to selectors like `.my-field:disabled` that can never match a
`<div>`. `spread-map-into-control-states` re-emits them on the control's attribute:
pass `$states: ('disabled')` where HTML has no readonly, and list in
`$except-modifiers` any modifier that undoes the disabled look. Every `vv-input-*` and
`vv-select` is built this way (`src/components/vv-input-range.scss` is the shortest
example).

## Mixins and functions

| Name | Signature | Purpose |
|---|---|---|
| `spread-map-into-bem` | `($map, $block, $use-custom-props: true, $zero-specificity: true, $bps: (xxs: 0), …)` | map → BEM block, elements, modifiers, states, custom props |
| `spread-map-into-utilities` | `($map, $class, $attribute, $deep: true, $bps: (xxs: 0), $prefix: '', $zero-specificity: false, $cqs: ())` | map → utility classes, optional responsive (`$bps`) and container (`$cqs`) variants |
| `spread-map-into-props` | `($map, $prefix, $deep: true)` | map → `--{prefix}-{key}` custom properties |
| `media-breakpoint-up` / `bp-up` | `($name, $bps: $breakpoints)` | `@media (min-width: …)` |
| `media-breakpoint-down` / `bp-down` | `($name, $bps)` | `@media (max-width: …)` |
| `media-breakpoint-between` / `bp-between` | `($lower, $upper, $bps)` | |
| `media-breakpoint-only` / `bp-only` | `($name, $bps)` | |
| `container-breakpoint-up` / `cq-up` | `($name, $cqs: $container-breakpoints)` | `@container (min-width: …)`; an unknown step or a step of 0 is a compile error |
| `wrap-with-where` | `($selector, $enabled: true)` | `:where()` wrapper |
| `layer` | `($name, $enabled, $prefix)` | emit inside a cascade layer when enabled |
| `spread-map-into-control-states` | `($map, $block, $control: 'input', $states: ('disabled', 'readonly'), $except-modifiers: (), $zero-specificity: true)` | for a wrapper field component: re-applies its `state` rules on the control's attribute through `:has()`, so `<input disabled>` styles the whole block |
| `spread-theme-component` | `($base-map, $theme-map, $component-name, $bps, $use-custom-props, $zero-specificity)` | dark (or any) theme variant of a component |
| `relative-color-value`, `color-mix-lighten-map`, `color-mix-darken-map`, `color-mix-alpha-map` | functions | shade generation used by the palette |

```scss
@use '@volverjs/style/scss/context' as ctx;

.sidebar {
  display: none;
  @include ctx.bp-up(md) { display: block; }
}
```

## Custom media

`scss/props/media` defines `@custom-media` queries for preferences and pointers
(`--motion-ok`, `--motion-not-ok`, `--os-dark`, `--os-light`, `--high-contrast`,
`--touch`, `--stylus`, `--pointer`, `--mouse`, `--portrait`, `--landscape` …) and three
ranges per breakpoint (`--md-only`, `--md-n-above`, `--md-n-below`). `@custom-media` is
a draft that has to be resolved at build time, so the module is opt-in and `scss` does
not emit it. Use it only where the project resolves the queries (postcss-custom-media,
or Vite with `css.transformer: 'lightningcss'` and
`css.lightningcss.drafts.customMedia: true`), and `@use` it, after the context, in every
stylesheet that writes a query: both resolvers read the definitions of the file they
transform. Without the import, postcss-custom-media leaves the query as it is and it
matches nothing, while Lightning CSS stops the build with `Custom media query
--motion-ok is not defined`. A Vue `<style>` block is a compilation of its own, so its
ranges follow the default `$breakpoints` unless it configures the context too. The CSS
export `@volverjs/style/props/media` is empty.

The breakpoint ranges cover the same widths as `bp-only`, `bp-up` and `bp-down`:
`--md-only` is `992px <= width < 1024px`, `--md-n-above` is `width >= 992px`,
`--md-n-below` is `width < 1024px`, and the last breakpoint has no upper bound. Without
a resolver in the project, use the `bp-*` mixins, which emit plain media queries.

## Cascade layers

With `$use-css-layers: true` the output opens with

```css
@layer volver.reset, volver.preflight, volver.props, volver.components, volver.themes, volver.utilities;
```

so utilities beat components and themes beat base styles regardless of source order.
Your own unlayered CSS beats all of them. `$layer-order` and `$layer-prefix` change the
list and the prefix.