@uncinq/css-components 1.16.2 → 1.16.3

package/docs/embeds/map.md

@@ -0,0 +1,57 @@
+---
+isIndex: false
+title: Map
+description: A Leaflet map container, and where Leaflet's own stylesheet belongs in the layer order.
+weight: 3
+icon: map
+---
+
+A map container, driven by Leaflet through a `js-map` hook.
+
+```html
+<div class="map js-map"
+     data-markers="[...]"
+     data-zoom="12"
+     data-tile="3"
+     data-marker-hidden="false"></div>
+```
+
+| Attribute | Role |
+| --- | --- |
+| `data-markers` | The markers to plot |
+| `data-zoom` | Initial zoom level |
+| `data-tile` | Tile layer selection |
+| `data-marker-hidden` | Whether markers start hidden |
+
+This package provides the container only: ratio, background, radius and margins. **Leaflet itself, its stylesheet and the script reading those attributes are yours to supply.**
+
+## It breaks out on mobile
+
+```css
+@media not (--sm) {
+  --map-ratio: var(--map-ratio-mobile);
+
+  .container & { margin-inline: calc(-1 * var(--gutter)); }
+  .row { display: block; }
+}
+```
+
+Three changes below 768px. The ratio switches to `--map-ratio-mobile`, usually taller, because a wide map on a narrow screen shows almost nothing useful. Inside a `.container` the map pulls out to the screen edges by one gutter. And a `.row` inside it stops laying out in columns.
+
+The bleed is deliberately scoped to `.container &`, so a map in a card or a sidebar stays inside its parent instead of overflowing something with no room to give.
+
+## Where Leaflet's CSS goes
+
+This is the clearest case in the package for why the layer order matters. Leaflet ships its own stylesheet, and a map is often loaded lazily.
+
+```css
+@layer reset, tokens, libs, base, vendors, layouts, components, pages, utilities;
+```
+
+Import Leaflet's stylesheet into `@layer libs`, and any adjustments you write into `@layer vendors`. A layer's position is fixed the first time its name appears, so a stylesheet injected at runtime lands in the slot its layer already occupies rather than at the end of the cascade. Without that, a lazily loaded Leaflet outranks your own rules purely on source order, and the map's marker styling starts winning arguments it should lose.
+
+See [Cascade layers](../../cascade-layers/).
+
+## Accessibility
+
+A map with no text alternative is unusable without sight. Whatever the map shows, addresses, opening hours, a route, should also exist as text near it. The container has no role and announces nothing on its own.

package/docs/embeds/video.md

@@ -0,0 +1,53 @@
+---
+isIndex: false
+title: Video
+description: A wrapper for a native video, positioning the optional pause control an autoplaying video needs.
+weight: 2
+icon: camera-video
+---
+
+A wrapper for a **native** `<video>`, as opposed to an embedded player.
+
+```html
+<div class="video">
+  <video autoplay muted loop playsinline></video>
+  <button class="btn btn-toggle-video is-playing" aria-label="Pause">
+    <span class="icon-pause"></span>
+    <span class="icon-play"></span>
+  </button>
+</div>
+```
+
+## What it does
+
+Three things:
+
+```css
+.video {
+  position: relative;
+
+  video { aspect-ratio: var(--video-ratio, var(--ratio-video)); width: 100%; }
+
+  .btn-toggle-video { position: absolute; inset-block-end: 0; inset-inline-end: 0; z-index: 10; }
+}
+```
+
+It establishes the positioning context, sizes the video to its container at a known ratio, and pins the control to the bottom inline-end corner. The ratio falls back to `--ratio-video` from the design tokens, so `--video-ratio` only needs setting for a portrait or square clip.
+
+## The control is not decoration
+
+A video that autoplays without native controls must be pausable to meet WCAG, which is exactly what [`.btn-toggle-video`](../../buttons/btn-toggle-video/) provides. If your video carries `controls`, you do not need it.
+
+The button is the only child the wrapper positions. Anything else you put inside sits in the normal flow.
+
+## Inside a media block
+
+```css
+.media .video { height: 100%; }
+```
+
+A [`.media`](../../content/media/) stretches the wrapper to fill it, so a video and an image are interchangeable within a [card](../../content/card/) without changing the card's structure. The media block's own `--media-ratio` then governs the box, and the video is cropped to it by `object-fit: cover`.
+
+## Autoplay checklist
+
+`muted` is required for autoplay to be allowed at all, and `playsinline` keeps iOS from taking the video fullscreen. `loop` is what makes a background video a background video. All three are attributes on the element, not something this component can supply.

package/docs/forms/_index.md

@@ -0,0 +1,31 @@
+---
+isIndex: false
+title: Forms
+description: The .form grid, the .form-check row, and where the actual control styling lives.
+weight: 7
+icon: ui-checks
+---
+
+Form **controls** are styled by [@uncinq/css-base](../../css-base/base/#forms), on the native elements themselves. There is no `.input` or `.select` class to apply.
+
+This package adds only what css-base cannot: the layout around those controls.
+
+| Page | Class | Covers |
+| --- | --- | --- |
+| [Form](form/) | `.form` | The two-column grid and its layout helpers |
+| [Check row](form-check/) | `.form-check` | A checkbox or radio laid out beside its label |
+
+Both live in `components/form.css`.
+
+## Accessibility
+
+Nothing here supplies an accessible name. Every control needs a `<label for>` pointing at its `id`, or a `.visually-hidden` label when the design has no room for a visible one.
+
+Tie `.help` text to its field with `aria-describedby`, otherwise it is visible but never announced:
+
+```html
+<input id="message" aria-describedby="message-help">
+<p class="help" id="message-help">Markdown is supported.</p>
+```
+
+For error states, use `aria-invalid="true"` on the control and point `aria-describedby` at the error message.

package/docs/forms/form-check.md

@@ -0,0 +1,77 @@
+---
+isIndex: false
+title: Check row
+description: A checkbox or radio laid out beside its label, and why the class is only one declaration.
+weight: 2
+icon: check-square
+---
+
+A checkbox or radio laid out inline with its label.
+
+```html
+<div class="form-check">
+  <input id="terms" type="checkbox">
+  <label for="terms">I accept the terms</label>
+</div>
+```
+
+## The whole component
+
+```css
+.form-check { display: flex; }
+```
+
+That is the entire rule, and it is deliberate. The control's appearance, its size, and the gap between it and the adjacent label all come from [css-base](../../../css-base/base/#forms), which styles `[type='checkbox'] + label` directly on the native elements.
+
+So the only thing missing from a bare input and label is that they sit on separate lines by default. This class fixes that, and stays out of everything else.
+
+The practical consequence: if the spacing between a checkbox and its label is wrong, the fix is in css-base or in the tokens, not here. Adding a `gap` to `.form-check` would apply on top of the one css-base already sets, and the two would drift apart.
+
+## The label must come after the control
+
+`[type='checkbox'] + label` is an adjacent sibling selector. Wrapping the input inside the label, or putting the label first, means the control gets no spacing and no styling from css-base.
+
+```html
+<!-- works -->
+<div class="form-check">
+  <input id="terms" type="checkbox">
+  <label for="terms">I accept the terms</label>
+</div>
+
+<!-- does not -->
+<div class="form-check">
+  <label for="terms">I accept the terms</label>
+  <input id="terms" type="checkbox">
+</div>
+```
+
+## Inside a form grid
+
+A check row is a direct child of [`.form`](../form/) like any other field, so it takes a grid track. Give it `.full` when the label is long enough to wrap in half the width:
+
+```html
+<div class="form-check full">
+  <input id="newsletter" type="checkbox">
+  <label for="newsletter">Send me the monthly newsletter</label>
+</div>
+```
+
+## Groups of radios
+
+There is no class for the group. Use a `<fieldset>` with a `<legend>`, and one `.form-check` per option:
+
+```html
+<fieldset class="full">
+  <legend>Preferred contact</legend>
+  <div class="form-check">
+    <input id="by-email" type="radio" name="contact" value="email">
+    <label for="by-email">Email</label>
+  </div>
+  <div class="form-check">
+    <input id="by-phone" type="radio" name="contact" value="phone">
+    <label for="by-phone">Phone</label>
+  </div>
+</fieldset>
+```
+
+The legend is what names the group in the accessibility tree. A set of radios with individual labels and no legend is announced one option at a time, with nothing saying what is being chosen.

package/docs/forms/form.md

@@ -0,0 +1,67 @@
+---
+isIndex: false
+title: Form
+description: A responsive grid that is one column or two, never three, plus its layout helpers.
+weight: 1
+icon: columns-gap
+---
+
+A responsive two-column grid that collapses to one column when there is not enough room.
+
+```html
+<form class="form">
+  <div>
+    <label for="first">First name</label>
+    <input id="first" type="text">
+  </div>
+  <div>
+    <label for="last">Last name</label>
+    <input id="last" type="text">
+  </div>
+  <div class="full">
+    <label for="message">Message</label>
+    <textarea id="message"></textarea>
+    <p class="help" id="message-help">Markdown is supported.</p>
+  </div>
+  <div class="actions">
+    <button class="btn" type="submit">Send</button>
+  </div>
+</form>
+```
+
+Each field is a plain `div`. There is no `.form-group` or `.field` class: the grid places its direct children, whatever they are.
+
+## One column or two, never three
+
+```css
+grid-template-columns: repeat(
+  auto-fill,
+  minmax(max(var(--form-col-min-width, 25ch), calc(50% - var(--gap) / 2)), 1fr)
+);
+```
+
+The `max()` is doing two jobs at once. It sets a **floor** of `25ch`, below which a field is too narrow to use, and it sets each track to at least half the width minus half the gap, which **caps** the result at two columns however wide the container gets.
+
+A three-column form is almost never what you want, because it breaks the vertical reading order of a sequence of fields: the eye has to move right twice before dropping a line, and nothing in the layout says which order the fields belong in.
+
+Change the floor with `--form-col-min-width`. Raising it past 50% forces a single column, which is a reasonable way to write a narrow form without a variant class.
+
+## Layout helpers
+
+| Class | Effect |
+| --- | --- |
+| `.full` | Spans both columns, `grid-column: 1 / -1` |
+| `.actions` | Spans both columns and stacks its children vertically |
+| `.help` | Help text under a field |
+
+`.actions` is a column flex container aligned to the start, with `--gap` between its children and their block margins flattened. So a submit button, a consent line and a legal note stack in the order written without fighting each other's margins.
+
+`.help` reads `--help-*` for colour, size, weight, margin and alignment. Pair it with `aria-describedby`, or it is seen and never announced.
+
+## Field spacing
+
+Both axes use `--gap`, the same token the grid uses for its column calculation. That is why the two-column cap subtracts `var(--gap) / 2`: the track width and the gutter come from one value, so changing it cannot desynchronise them.
+
+## Controls are not styled here
+
+Inputs, selects, textareas and their focus and invalid states come from [css-base](../../../css-base/base/#forms), applied to the native elements. This file adds layout and nothing else, which is why a form built without `.form` still looks right, it is simply stacked.

package/docs/navigation/_index.md

@@ -0,0 +1,29 @@
+---
+isIndex: false
+title: Navigation
+description: Navigation lists, navigation titles, skip links, breadcrumbs and pagination.
+weight: 5
+icon: signpost
+---
+
+Five components for moving around a site.
+
+| Page | Class | Purpose |
+| --- | --- | --- |
+| [Nav](nav/) | `.nav` | The base navigation list |
+| [Nav title](nav-title/) | `.nav-title` | A label above a group of links |
+| [Skip links](nav-accessibility/) | `.nav-accessibility` | Skip navigation for keyboard and assistive technology |
+| [Breadcrumb](breadcrumb/) | `.breadcrumb-wrapper` | The breadcrumb trail |
+| [Pagination](pagination/) | `.pagination` | Page navigation |
+
+## Two of them take the class on the wrapper
+
+`.breadcrumb-wrapper` goes on the `<nav>`, not on the `<ol>` inside it. `.nav-accessibility` goes on the list itself, but only alongside `.nav`. Neither is guessable from the name, so check the page before writing the markup.
+
+## None of them supplies the landmark
+
+`<nav>`, `aria-label` and `aria-current` are yours to write. A page with three navigation regions and no labels on them is harder to use with a screen reader than a page with one, which is the usual reason to add them.
+
+## `.item` means two different things
+
+In [pagination](pagination/), `.item` is a page number. It is unrelated to the `.item` card unit mentioned throughout the [Content](../content/) section, which is not defined in this package at all.

package/docs/navigation/breadcrumb.md

@@ -0,0 +1,59 @@
+---
+isIndex: false
+title: Breadcrumb
+description: The breadcrumb trail, with the class on the wrapper and the separator drawn from a token.
+weight: 4
+icon: chevron-double-right
+---
+
+The breadcrumb trail. **The class goes on the wrapper, not on the list.**
+
+```html
+<nav class="breadcrumb-wrapper" aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Home</a></li>
+    <li><a href="/docs">Docs</a></li>
+    <li aria-current="page">Navigation</li>
+  </ol>
+</nav>
+```
+
+`.breadcrumb-wrapper` styles the `ol` and the `li` inside it by element, so there is no class to put on either. The name says wrapper for that reason.
+
+## The separator
+
+Drawn on `li::before` from a token, with the first item's suppressed:
+
+```css
+li::before { content: var(--breadcrumb-separator); color: var(--breadcrumb-color-separator); }
+li:first-child::before { display: none; }
+```
+
+`--breadcrumb-separator` defaults to `"/"` and takes any `content` value, so a chevron or an arrow is a token change. It needs the quotes, since it is dropped into `content` as is.
+
+Because the separator is generated content rather than text, it is not selected when a reader copies the trail, and screen readers skip it.
+
+## Marking the current page
+
+Use `aria-current="page"`, which is both the accessible marker and the styling hook:
+
+```css
+li[aria-current="page"] { color: var(--breadcrumb-color-text-active); }
+```
+
+There is no `.active` class here, deliberately. Relying on the attribute means the visual state and the announced state cannot disagree, and it rules out the other common approach, styling `:last-child`, which breaks the moment a trail ends on something other than the current page.
+
+## Overflow on narrow screens
+
+```css
+overflow-x: auto;
+li { flex-shrink: 0; white-space: nowrap; }
+```
+
+A long trail scrolls sideways rather than wrapping into several lines or truncating. Items keep their full width, so the deepest entries stay readable and the reader scrolls to reach the shallow ones.
+
+The wrapper also carries a block border and its own background, which is what lets a breadcrumb sit as a full-width band under the header.
+
+## Accessibility
+
+`aria-label` on the `<nav>` is what distinguishes this landmark from the other navigation regions on the page. Use an `<ol>`, not a `<ul>`: the order of a breadcrumb is its meaning.

package/docs/navigation/nav-accessibility.md

@@ -0,0 +1,67 @@
+---
+isIndex: false
+title: Skip links
+description: Skip navigation for keyboard and assistive technology users, hidden off-screen rather than hidden.
+weight: 3
+icon: universal-access
+---
+
+Skip links, for keyboard and assistive technology users.
+
+```html
+<ul class="nav nav-accessibility">
+  <li><a href="#main">Skip to content</a></li>
+  <li><a href="#navigation">Skip to navigation</a></li>
+  <li><a href="#footer">Skip to footer</a></li>
+</ul>
+```
+
+Three things matter here, and getting any of them wrong defeats the purpose.
+
+## It must be the first focusable element in `<body>`
+
+A skip link that comes after the navigation it skips is useless. It goes before the header, before any cookie banner, before anything else that can take focus.
+
+## It is hidden off-screen, not hidden
+
+```css
+.nav-accessibility {
+  position: absolute;
+  transform: translateY(-100%);
+
+  &:focus-within { transform: translateY(0); }
+}
+```
+
+`display: none` or `visibility: hidden` would remove it from the tab order entirely, which is the one thing a skip link cannot afford. It is pushed out of view with a transform and slides back on `:focus-within`, so the whole group appears as soon as any link inside it is reached.
+
+The slide is behind `prefers-reduced-motion`; with motion disabled the group simply appears.
+
+## It requires the `.nav` base class
+
+`.nav-accessibility` sets `flex-direction: row` and a small font size, but the flex layout, the list reset and the link padding all come from [`.nav`](../nav/). On its own it is an unstyled list positioned off-screen.
+
+## The focus treatment is deliberate
+
+```css
+a {
+  background: var(--color-background);
+  &:focus {
+    background: var(--color-text);
+    color: var(--color-background);
+    outline: none;
+  }
+}
+```
+
+The resting background is what keeps the links readable once the group slides over the page content. On focus the colours invert, which is why the usual focus ring is dropped: the inversion is the focus indicator, and it meets the contrast requirement on its own.
+
+Note this uses `:focus`, not `:focus-visible`, so the indicator appears however focus arrived.
+
+## The targets have to be focusable
+
+`z-index: 300` puts the group above sticky headers, but a working skip link also needs somewhere to land. An `id` on a non-interactive element needs `tabindex="-1"`, otherwise the jump scrolls the page without moving focus, and the next Tab press continues from the top of the document:
+
+```html
+<main id="main" tabindex="-1">
+```

package/docs/navigation/nav-title.md

@@ -0,0 +1,43 @@
+---
+isIndex: false
+title: Nav title
+description: A label above a group of navigation links.
+weight: 2
+icon: type
+---
+
+A title within a navigation block, for labelling a group of links.
+
+```html
+<nav aria-labelledby="docs-nav">
+  <p class="nav-title" id="docs-nav">Documentation</p>
+  <ul class="nav">
+    <li><a href="/docs/install">Installation</a></li>
+    <li><a href="/docs/usage">Usage</a></li>
+  </ul>
+</nav>
+```
+
+It is a leaf component with no children and no variants:
+
+```css
+.nav-title {
+  font-size: var(--nav-title-font-size);
+  font-weight: var(--nav-title-font-weight);
+  margin-block: var(--nav-title-margin-block, 0);
+  padding-block: var(--nav-title-padding-block);
+  padding-inline: var(--nav-title-padding-inline);
+}
+```
+
+## It is a sibling of the list, not an item in it
+
+Putting it inside the `<ul>` as an `<li>` would make it a list item that screen readers count and announce as one, and [`.nav`](../nav/) would style it as a navigation entry. Keep it outside.
+
+## Why it carries inline padding
+
+`--nav-title-padding-inline` exists so the label lines up with the link text below it, which is itself inset by `--nav-link-padding-inline`. Keep the two in step when you change either, or the title sits proud of the list it labels.
+
+## Use it as the accessible name
+
+A group of links deserves a label in the accessibility tree as well as on screen. Point the surrounding `<nav>` at it with `aria-labelledby` rather than repeating the text in an `aria-label`, so the two cannot drift apart.

package/docs/navigation/nav.md

@@ -0,0 +1,65 @@
+---
+isIndex: false
+title: Nav
+description: The base navigation list, vertical by default, whose direction is set by context rather than by a modifier class.
+weight: 1
+icon: compass
+---
+
+The base navigation list, vertical by default.
+
+```html
+<ul class="nav">
+  <li><a href="/">Home</a></li>
+  <li><a href="/about">About</a></li>
+</ul>
+```
+
+Works on `ul` or `ol`.
+
+## Direction is set by context, not by a modifier
+
+There is no `.nav-horizontal`. The direction comes from a token:
+
+```css
+flex-direction: var(--nav-direction, column);
+```
+
+so a header lays its own navigation out horizontally by setting `--nav-direction: row` on it, or `flex-direction` directly. That keeps the component free of layout variants that would only ever be used in one place, and it means the same list is a column in a drawer and a row in a header without a class change.
+
+## Nested lists inherit the layout
+
+```css
+&,
+:is(ul, ol) { display: flex; flex-direction: var(--nav-direction, column); ... }
+```
+
+The rule matches the nav **and** every list inside it, so a submenu needs no second `.nav` class. Note that a nested list inherits `--nav-direction` too, so a horizontal header menu gets horizontal submenus unless the submenu resets it.
+
+## Links
+
+`a:where(:not(.btn))` and `li > span` are styled together, so a non-link entry, the current page rendered as text, lines up with the links around it. `.btn` is excluded through `:where()`, which adds no specificity, so a call to action inside a navigation keeps its own styling.
+
+The current entry is marked with a class on the link:
+
+```html
+<li><a href="/about" class="active" aria-current="page">About</a></li>
+```
+
+```css
+&.active { --nav-color-text: var(--nav-color-text-active); }
+```
+
+The class drives the colour; `aria-current` is what a screen reader announces. Write both.
+
+## Highlighted items
+
+`.nav-item-highlighted` tightens the line height and pulls the item out to the nav's own inline padding, for an entry rendered as a block rather than as a line of text.
+
+## Dropdowns inside a nav
+
+`.dropdown-toggle` is restyled to take `--nav-color-text`, so a [dropdown](../../overlays/dropdown/) in a header menu matches the links beside it. Nothing else about the dropdown changes.
+
+## Inside a panel
+
+A `.modal` or `.drawer` publishes `--nav-color-text` from its own text colour, so a navigation inside a panel follows the panel's palette. Going inline with [`.panel-inline-*`](../../overlays/panel/#inline-variants) hands that token back to the page, which is why a drawer menu that becomes a sidebar column changes colour at the breakpoint.

package/docs/navigation/pagination.md

@@ -0,0 +1,77 @@
+---
+isIndex: false
+title: Pagination
+description: Page navigation, with masked control glyphs and a built-in responsive collapse.
+weight: 5
+icon: three-dots
+---
+
+A page navigation list.
+
+```html
+<nav aria-label="Pagination">
+  <ul class="pagination">
+    <li class="disabled"><a class="first">First</a></li>
+    <li><a class="previous" href="?page=1">Previous</a></li>
+    <li class="item active"><a href="?page=2">2</a></li>
+    <li class="item item-adjacent"><a href="?page=3">3</a></li>
+    <li><a class="next" href="?page=3">Next</a></li>
+    <li><a class="last" href="?page=9">Last</a></li>
+  </ul>
+</nav>
+```
+
+| Class | On | Role |
+| --- | --- | --- |
+| `.first`, `.previous`, `.next`, `.last` | the `a` | Navigation controls |
+| `.item` | the `li` | A page number |
+| `.item-adjacent` | the `li` | A page number next to the current one |
+| `.active` | the `li` | The current page |
+| `.disabled` | the `li` | An unavailable control |
+
+`.active` and `.disabled` are both read as ancestors of the link (`.active a`, `.disabled a`), so putting either on the `li` is what the rules expect.
+
+## The glyphs are shipped
+
+Each control draws a mask on `::after` from its own token:
+
+```css
+.next::after { mask: var(--pagination-icon-next) center / var(--pagination-icon-size) no-repeat; }
+```
+
+Four tokens, `--pagination-icon-first`, `-previous`, `-next` and `-last`, sized by `--pagination-icon-size`. The two backwards controls reuse their forwards glyph and rotate it:
+
+```css
+.first::after    { mask: var(--pagination-icon-first) ...;    rotate: 180deg; }
+.previous::after { mask: var(--pagination-icon-previous) ...; rotate: 180deg; }
+```
+
+So a themed arrow only has to exist in one direction. Because the glyph is a mask over `currentColor`, it follows the link colour through hover, active and disabled without a second declaration.
+
+The text inside the control (`First`, `Previous`) sits beside the glyph. Replace it with a `.visually-hidden` span if the design wants icons alone; do not remove it, or the control loses its accessible name.
+
+## The responsive collapse is built in
+
+```css
+@media not (--sm) {
+  .first, .last,
+  li:has(.first), li:has(.last),
+  .item:not(.item-adjacent):not(.active) { display: none; }
+}
+```
+
+Below 768px the paginator drops to *previous, the current page, its neighbours, next*. You do not need to write that rule, and you do not need a second markup path for mobile: render the full paginator and let CSS thin it out.
+
+This is what `.item-adjacent` is for. It is the only signal the CSS has about which page numbers are near the current one, so a paginator that omits it collapses to the current page alone on a narrow screen.
+
+The `li:has(...)` selectors are there so the list item goes with the control it contains, rather than leaving an empty `li` contributing a gap.
+
+## States
+
+`.active a` and `.disabled a` both get `pointer-events: none`, so neither is clickable regardless of whether you render an `href`. The active page takes the `-active` colour pair, and a disabled control takes `--pagination-disabled-opacity`.
+
+Note that the hover rule here is **not** behind `@media (hover: hover) and (pointer: fine)`, unlike the rest of the package. On a touch device a tapped page number can keep its hover background until the next paint.
+
+## Accessibility
+
+The `<nav>` and its `aria-label` are yours to write; the component styles the list only. Mark the current page with `aria-current="page"` on the link as well as `.active` on the item, so the state is announced and not merely coloured.

package/docs/overlays/_index.md

@@ -0,0 +1,34 @@
+---
+isIndex: false
+title: Overlays
+description: The shared panel skeleton behind .modal and .drawer, the two opening strategies, and the .dropdown contract.
+weight: 3
+icon: window-stack
+---
+
+Four files, and a design worth understanding before reading any of them.
+
+| Page | Covers |
+| --- | --- |
+| [Panel](panel/) | The shared skeleton, `.panel-inline-*`, `.panel-trigger-*`, the backdrop and the JavaScript contract |
+| [Modal](modal/) | `.modal`, the centred configuration |
+| [Drawer](drawer/) | `.drawer` and its four edge variants |
+| [Dropdown](dropdown/) | `.dropdown`, a contextual menu with its own contract |
+
+## `.modal` and `.drawer` are the same panel
+
+Same structure, header and content and footer. Same open and closed contract. Same backdrop. They differ only in where they sit: modal centres them, drawer pins them to an edge.
+
+`components/panel.css` owns **every rule**. The two variants are pure configuration, declaring nothing but `--panel-*` tokens.
+
+There is **no `.panel` class to apply.** The file targets `:where(.modal, .drawer)` directly, so the skeleton arrives with either variant class. `panel` names the shared concept and the token namespace, not a class.
+
+Each variant aliases `--panel-*` from its own namespace, so `--modal-*` and `--drawer-*` remain the public API. Override those.
+
+## The tag picks the strategy, not the class
+
+Either variant works both ways, and the choice is an accessibility one rather than a styling one. See [Two ways to open a panel](panel/#two-ways-to-open-a-panel).
+
+## No JavaScript ships here
+
+`.modal`, `.drawer` and `.dropdown` all expect a script. The CSS defines the classes and attributes that script must toggle; each page documents the contract it needs.