opui-css 5.4.2 → 6.0.0-rc.1

package/skills/opui/references/customizing.md

@@ -0,0 +1,85 @@
+# Customizing
+
+Where your CSS goes: a theme in `theme.custom` changes the whole library, a component's `--_*` properties change one component or one instance, and your own layer holds the rest.
+
+## Your theme
+
+A theme is the [knobs, roles and component tokens](https://open-props-ui.netlify.app/html/guide/concepts.md#token-tiers) you change, in the `theme.custom` layer, right after the defaults. Tokens you leave out keep their defaults, also new ones in later releases.
+
+```css
+@layer theme.custom {
+  :where(html) {
+    --ui-density: 0.9;
+    --ui-font-body: "Inter", system-ui, sans-serif;
+    --ui-font-heading: "Fraunces", serif;
+    --ui-palette-chroma: 0.35;
+    --ui-palette-hue: 265;
+  }
+}
+```
+
+If it might load before `layers.css`, start it with the two `@layer` statements from there, like the example themes do. The [Theme builder](https://open-props-ui.netlify.app/theme-builder.md) writes one for you, and [Theming](https://open-props-ui.netlify.app/html/guide/theming.md) walks through the knobs.
+
+Knobs inherit, so `html` is enough for them. A role you pin, such as `--ui-surface` or `--ui-primary`, goes on `:where(html, .ui-palette, .ui-contrast-more)` so the scope classes keep it. The example themes and the Theme builder do that for every token.
+
+### Example themes
+
+The themes below ship with the package to show how far tokens go. Each is only tokens in `theme.custom`, on `html` and, for the colors of severity scopes such as `.ui-info`, on those classes. No component CSS. Every stress test page runs with each of them in light and dark mode. They copy their originals faithfully, also where those fall short of WCAG contrast (the translucent focus rings of Bootstrap and shadcn, the light field borders of Bootstrap and shadcn, the bright blue of brutalist). They name their fonts (Geist, Roboto, DM Sans) but don't load them. The [Theme builder](https://open-props-ui.netlify.app/theme-builder.md) starts from any of them.
+
+- `bootstrap`: Bootstrap 5. Its `oklch(0.578 0.228 260)` blue, gray secondary buttons, the danger, warning, info and success colors with the subtle alert palettes, `oklch(0.91 0.007 248)` borders, 38px controls, regular weight buttons and labels, 16px checks and 32px switches, solid blue selected items, the heading scale, 1.5 line height and the wide translucent focus ring. No shadow on dropdowns and modals.
+- `brutalist`: neobrutalism. Black 2px borders, hard 4px shadows on cards, dialogs and menus and on buttons that press into them on hover without changing color, filled in the main blue, white fields on the gray-blue page, the main blue also behind tooltips and selected items, black links and 500 weight body text.
+- `m3`: Material 3. The baseline purple scheme and its tinted surfaces, the error red, pill buttons with 24px padding that show 8% state layers and lift on hover, outlined ones in the outline gray, 12px cards, 28px dialogs, 4px menus and outlined fields, 8px chips, 18px checkboxes, on-surface text with on-surface-variant secondary text, primary tab labels, 52 by 32px switches, Roboto, the type scale, the emphasized easing and the 3px secondary focus ring over a 32% scrim.
+- `shadcn`: shadcn/ui. Neutral grays, a near-black primary also behind tooltips, 36px controls with 14px text and 16px padding, 32px small and 40px large buttons, light borders with a faint shadow, the accent tint on hover instead of a fill, a 3px gray focus ring, 16px checks with 4px corners, a 32px switch with a white thumb, 8px menus and chips, 10px dialogs and 14px cards with 24px padding, muted secondary text.
+
+```css
+@import "opui-css/css/imports.css";
+@import "opui-css/themes/brutalist.css";
+```
+
+## Component properties
+
+The `--_*` private properties are each component's wiring, the last [tier](https://open-props-ui.netlify.app/html/guide/concepts.md#token-tiers) before its CSS. Every component page lists its own under Component properties, marked as inputs or outputs, and components share names where they mean the same thing. Button reads these:
+
+- `--_accent`: the accent color. Fills, borders, text, hover and active states are all derived from it.
+- `--_bg-color` and `--_text-color`: the current background and text color.
+- `--_duration` and `--_ease`: the transition duration and easing.
+- `--_icon-size`: the size of a direct child `svg`.
+- `--_size`: the control size, set by the size classes: the height, and the width when the control is square.
+- `--_motion`: the motion multiplier, `0` turns transitions off.
+- `--_padding-inline`: the inline padding, set by the size classes.
+
+The component declares them on itself, so set them on the component, not on a parent. Theme tokens are the ones to set on a parent:
+
+```css
+/* Does nothing: every .ui-button declares its own --_icon-size */
+.toolbar {
+  --_icon-size: 1.25em;
+}
+
+/* Works */
+.toolbar .ui-button {
+  --_icon-size: 1.25em;
+}
+
+/* Theme tokens inherit, so a parent is fine */
+.toolbar {
+  --ui-button-radius: var(--ui-radius-round);
+}
+```
+
+Prefer inputs like `--_accent` over outputs like `--_bg-color`. The states set the outputs, so a new `--_bg-color` freezes the background in every state, while a new `--_accent` flows through all of them.
+
+## Unlayered or your own layer
+
+Unlayered CSS beats every [layer](https://open-props-ui.netlify.app/html/guide/concepts.md#cascade-layers), which is fine for most apps. If you use layers yourself, add one after `utils`: it beats the library and still loses to your unlayered one-off fixes.
+
+```css
+@layer openprops, theme, normalize, components.prose, components.root, components.extended, components.compat, utils, overrides;
+@layer theme.palette, theme.base, theme.custom, theme.severity;
+
+@layer overrides {
+  .ui-badge {
+    --_size: var(--ui-space-5);
+  }
+}
+```

package/skills/opui/references/description-list.md

@@ -0,0 +1,191 @@
+# Description list
+
+Description lists are used to display a list of terms and their descriptions.
+
+- CSS: `opui-css/css/components/description-list.css`.
+- Full docs with every example: [HTML](https://open-props-ui.netlify.app/html/components/description-list.md), [Astro](https://open-props-ui.netlify.app/astro/components/description-list.md), [React](https://open-props-ui.netlify.app/react/components/description-list.md), [Svelte](https://open-props-ui.netlify.app/svelte/components/description-list.md), [Vue](https://open-props-ui.netlify.app/vue/components/description-list.md).
+
+## DescriptionList
+
+### Parts
+
+- `dl.ui-description-list` (root): Container element.
+- `<div>` (`DescriptionListItem`): Groups a term with its description.
+- `<dt>` (`DescriptionListTerm`): The term.
+- `<dd>` (`DescriptionListDescription`): The description.
+
+### Props and modifiers
+
+- `bordered`: `boolean`, `.ui-bordered`. Adds a line between the term and the description.
+- `dotted`: `boolean`, `.ui-dotted`. Makes the `bordered` line dotted.
+- `orientation`: `"auto"` (default), `"horizontal"` (`.ui-horizontal`). The orientation of the items. `auto` stacks the term and the description when the list is `45ch` or narrower, `horizontal` keeps them side by side at any width.
+
+### Slots
+
+- `default`: The items.
+
+## Component properties
+
+Set inputs on the component, inline or in your CSS. Outputs follow the variant and state, so never override them.
+
+### description-list.css
+
+- `--_border-style`: Style of the line between term and description. `.ui-bordered.ui-dotted` makes it dotted.
+- `--_border-width`: Width of the line between term and description. `.ui-bordered.ui-dotted` sets it to `2px`.
+
+## Theme tokens
+
+The stylesheets read `--ui-border-color`, `--ui-border-width`, `--ui-border-width-thick`, `--ui-font-weight-bold`, `--ui-space-1`, `--ui-space-3` and `--ui-text`. `theming.md` and `tokens.json` describe them.
+
+## HTML
+
+### Example: Basics
+
+```html
+<dl class="ui-description-list">
+  <div>
+    <dt>Price</dt>
+    <dd>6 950 000</dd>
+  </div>
+  <div>
+    <dt>Size</dt>
+    <dd>64 m²</dd>
+  </div>
+  <div>
+    <dt>Rooms</dt>
+    <dd>3</dd>
+  </div>
+</dl>
+```
+
+## Astro
+
+`import { DescriptionList, DescriptionListDescription, DescriptionListItem, DescriptionListTerm } from "opui-css/astro"`
+
+### Example: Basics
+
+```astro
+---
+import {
+  DescriptionList,
+  DescriptionListDescription,
+  DescriptionListItem,
+  DescriptionListTerm,
+} from "opui-css/astro"
+---
+
+<DescriptionList>
+  <DescriptionListItem>
+    <DescriptionListTerm>Price</DescriptionListTerm>
+    <DescriptionListDescription>6 950 000</DescriptionListDescription>
+  </DescriptionListItem>
+  <DescriptionListItem>
+    <DescriptionListTerm>Size</DescriptionListTerm>
+    <DescriptionListDescription>64 m²</DescriptionListDescription>
+  </DescriptionListItem>
+  <DescriptionListItem>
+    <DescriptionListTerm>Rooms</DescriptionListTerm>
+    <DescriptionListDescription>3</DescriptionListDescription>
+  </DescriptionListItem>
+</DescriptionList>
+```
+
+## React
+
+`import { DescriptionList, DescriptionListDescription, DescriptionListItem, DescriptionListTerm } from "opui-css/react"`
+
+### Example: Basics
+
+```tsx
+import {
+  DescriptionList,
+  DescriptionListDescription,
+  DescriptionListItem,
+  DescriptionListTerm,
+} from "opui-css/react"
+
+export default function Basics() {
+  return (
+    <DescriptionList>
+      <DescriptionListItem>
+        <DescriptionListTerm>Price</DescriptionListTerm>
+        <DescriptionListDescription>6 950 000</DescriptionListDescription>
+      </DescriptionListItem>
+      <DescriptionListItem>
+        <DescriptionListTerm>Size</DescriptionListTerm>
+        <DescriptionListDescription>64 m²</DescriptionListDescription>
+      </DescriptionListItem>
+      <DescriptionListItem>
+        <DescriptionListTerm>Rooms</DescriptionListTerm>
+        <DescriptionListDescription>3</DescriptionListDescription>
+      </DescriptionListItem>
+    </DescriptionList>
+  )
+}
+```
+
+## Svelte
+
+`import { DescriptionList, DescriptionListDescription, DescriptionListItem, DescriptionListTerm } from "opui-css/svelte"`
+
+### Example: Basics
+
+```svelte
+<script lang="ts">
+  import {
+    DescriptionList,
+    DescriptionListDescription,
+    DescriptionListItem,
+    DescriptionListTerm,
+  } from "opui-css/svelte"
+</script>
+
+<DescriptionList>
+  <DescriptionListItem>
+    <DescriptionListTerm>Price</DescriptionListTerm>
+    <DescriptionListDescription>6 950 000</DescriptionListDescription>
+  </DescriptionListItem>
+  <DescriptionListItem>
+    <DescriptionListTerm>Size</DescriptionListTerm>
+    <DescriptionListDescription>64 m²</DescriptionListDescription>
+  </DescriptionListItem>
+  <DescriptionListItem>
+    <DescriptionListTerm>Rooms</DescriptionListTerm>
+    <DescriptionListDescription>3</DescriptionListDescription>
+  </DescriptionListItem>
+</DescriptionList>
+```
+
+## Vue
+
+`import { DescriptionList, DescriptionListDescription, DescriptionListItem, DescriptionListTerm } from "opui-css/vue"`
+
+### Example: Basics
+
+```vue
+<script setup lang="ts">
+import {
+  DescriptionList,
+  DescriptionListDescription,
+  DescriptionListItem,
+  DescriptionListTerm,
+} from "opui-css/vue"
+</script>
+
+<template>
+  <DescriptionList>
+    <DescriptionListItem>
+      <DescriptionListTerm>Price</DescriptionListTerm>
+      <DescriptionListDescription>6 950 000</DescriptionListDescription>
+    </DescriptionListItem>
+    <DescriptionListItem>
+      <DescriptionListTerm>Size</DescriptionListTerm>
+      <DescriptionListDescription>64 m²</DescriptionListDescription>
+    </DescriptionListItem>
+    <DescriptionListItem>
+      <DescriptionListTerm>Rooms</DescriptionListTerm>
+      <DescriptionListDescription>3</DescriptionListDescription>
+    </DescriptionListItem>
+  </DescriptionList>
+</template>
+```

package/skills/opui/references/dialog.md

@@ -0,0 +1,301 @@
+# Dialog
+
+A minimally styled window overlaid on the main content. By design the Dialog is minimal with zero content to allow for both modal and non-modal use.
+
+- CSS: `opui-css/css/components/dialog.css` and `opui-css/css/components/card.css`.
+- Full docs with every example: [HTML](https://open-props-ui.netlify.app/html/components/dialog.md), [Astro](https://open-props-ui.netlify.app/astro/components/dialog.md), [React](https://open-props-ui.netlify.app/react/components/dialog.md), [Svelte](https://open-props-ui.netlify.app/svelte/components/dialog.md), [Vue](https://open-props-ui.netlify.app/vue/components/dialog.md).
+
+## Dialog
+
+### Parts
+
+- `dialog.ui-dialog` (root): Container element.
+- `.ui-header` (`DialogHeader`): The header, a row for the title and anything next to it.
+- `<h2>` (`DialogTitle`): The title. Names the dialog through `aria-labelledby`.
+- `.ui-content` (`DialogContent`): The scrollable content.
+- `.ui-footer` (`DialogFooter`): The footer, a row at the end.
+
+### Props and modifiers
+
+- `closedby`: `"any" | "closerequest" | "none"`, `[closedby]`. How the dialog can be closed. `"any"` also closes it on a click outside.
+
+### Slots
+
+- `default`: The dialog parts, and any other content.
+
+### Notes
+
+- HTML: Add `.ui-elevated` to the root for the raised surface.
+- Astro, React, Svelte and Vue: Attributes that aren't props go to the `<dialog>`, like `id`. Without `aria-label` or `aria-labelledby`, the `DialogTitle` names the dialog. A dialog without a `DialogTitle` needs an `aria-label`. An `id` on `DialogTitle` only applies when the dialog has `aria-label` or `aria-labelledby`.
+
+## DialogFooter
+
+### Parts
+
+- `.ui-footer` (root): A row at the end, for buttons, text or anything else.
+- `.ui-footer > .ui-actions`: Groups buttons. Moves to the end when other content comes first.
+
+### Props and modifiers
+
+- `align`: `"end"` (default), `"start"` (`.ui-align-start`). Alignment for the footer content.
+
+### Slots
+
+- `default`: The footer content, such as buttons.
+
+## Component properties
+
+Set inputs on the component, inline or in your CSS. Outputs follow the variant and state, so never override them.
+
+### dialog.css
+
+- `--_backdrop-bg-color`: The backdrop color. Defaults to `--ui-backdrop-bg-color`.
+- `--_backdrop-blur`: The backdrop filter. Defaults to a `--ui-backdrop-blur` blur.
+- `--_ease`: Easing of the open transition. Defaults to `--ui-ease-enter`.
+- `--_elevated-shadow`: Shadow of the dialog. `card.css` declares it for `.ui-elevated` surfaces, and the dialog sets it to `--ui-shadow-overlay`, like `Drawer` and `Menu`.
+- `--_max-inline-size`: Maximum width, capped to fit the viewport.
+- `--_motion`: Motion multiplier for the transitions. `0` turns them off.
+- `--_scroll-shadow`: Shadow at the edges of `.ui-content` when it scrolls. Defaults to `--ui-shadow-scroll`.
+- `--_title-font-size`: Font size of the title, a heading in `.ui-header`. Defaults to `--ui-font-size-h4`.
+
+Outputs: `--_duration`.
+
+### card.css
+
+- `--_ease`: Easing of the focus ring animation. Defaults to `--ui-ease`.
+- `--_elevated-bg-color`: Background of `.ui-elevated`. Defaults to `--ui-surface-elevated`.
+- `--_elevated-shadow`: Shadow of `.ui-elevated`. Defaults to `--ui-shadow-elevated`.
+- `--_motion`: Motion multiplier for the focus ring animation. `0` turns it off.
+- `--_outlined-border-color`: Border color of `.ui-outlined`. Defaults to `--ui-border-color`.
+- `--_padding`: Padding of the header, content and actions. `--ui-card-padding`, or `--ui-space-3` when a theme leaves it unset.
+- `--_surface-bg-color`: Background of default and `.ui-outlined` cards, and border color of `.ui-tonal` and `.ui-elevated` unless a theme sets `--ui-border-color-raised`. Defaults to `--ui-surface`.
+- `--_tonal-bg-color`: Background of `.ui-tonal`. Defaults to `--ui-surface-tonal`.
+
+Outputs: `--_bg-color`, `--_border-color`, `--_border-width`, `--_duration` and `--_shadow`.
+
+## Theme tokens
+
+The stylesheets read `--ui-backdrop-bg-color`, `--ui-backdrop-blur`, `--ui-border-color`, `--ui-border-color-on-raised`, `--ui-border-color-raised`, `--ui-border-width`, `--ui-card-padding`, `--ui-dialog-radius`, `--ui-duration`, `--ui-duration-slow`, `--ui-ease`, `--ui-ease-enter`, `--ui-field-border-color-on-raised`, `--ui-focus-ring-color`, `--ui-focus-ring-inset`, `--ui-focus-ring-offset`, `--ui-focus-ring-style`, `--ui-focus-ring-width`, `--ui-font-size-body`, `--ui-font-size-caption`, `--ui-font-size-h4`, `--ui-letter-spacing-heading`, `--ui-line-height-tight`, `--ui-motion`, `--ui-radius`, `--ui-rhythm-step`, `--ui-shadow-elevated`, `--ui-shadow-overlay`, `--ui-shadow-scroll`, `--ui-shadow-surface`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-6`, `--ui-surface`, `--ui-surface-elevated`, `--ui-surface-tonal`, `--ui-text` and `--ui-text-strong`. `theming.md` and `tokens.json` describe them.
+
+## HTML
+
+### Example: Basics
+
+```html
+<button
+  type="button"
+  commandfor="dialog-basics-1"
+  command="show-modal"
+  class="ui-button ui-outlined"
+>
+  Open dialog
+</button>
+
+<dialog
+  id="dialog-basics-1"
+  class="ui-dialog ui-elevated"
+  aria-labelledby="dialog-basics-1-title"
+>
+  <div class="ui-header">
+    <h2 id="dialog-basics-1-title">Newsletter</h2>
+  </div>
+  <div class="ui-content">
+    <p>
+      Get a short email when we ship something new. No more than once a month.
+    </p>
+  </div>
+  <div class="ui-footer">
+    <button
+      commandfor="dialog-basics-1"
+      command="close"
+      class="ui-button"
+      type="button"
+    >
+      Not now
+    </button>
+    <button
+      commandfor="dialog-basics-1"
+      command="close"
+      class="ui-button ui-filled"
+      type="button"
+    >
+      Subscribe
+    </button>
+  </div>
+</dialog>
+```
+
+## Astro
+
+`import { Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle } from "opui-css/astro"`
+
+### Example: Basics
+
+```astro
+---
+import {
+  Button,
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "opui-css/astro"
+---
+
+<Button commandfor="dialog-basics-1" command="show-modal" variant="outlined">
+  Open dialog
+</Button>
+
+<Dialog id="dialog-basics-1">
+  <DialogHeader>
+    <DialogTitle>Newsletter</DialogTitle>
+  </DialogHeader>
+  <DialogContent>
+    <p>
+      Get a short email when we ship something new. No more than once a month.
+    </p>
+  </DialogContent>
+  <DialogFooter>
+    <Button commandfor="dialog-basics-1" command="close"> Not now </Button>
+    <Button commandfor="dialog-basics-1" command="close" variant="filled">
+      Subscribe
+    </Button>
+  </DialogFooter>
+</Dialog>
+```
+
+## React
+
+`import { Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle } from "opui-css/react"`
+
+- Client components (`"use client"`): `Dialog`.
+
+### Example: Basics
+
+```tsx
+import {
+  Button,
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "opui-css/react"
+
+export default function Basics() {
+  return (
+    <>
+      <Button
+        commandfor="dialog-basics-1"
+        command="show-modal"
+        variant="outlined"
+      >
+        Open dialog
+      </Button>
+
+      <Dialog id="dialog-basics-1">
+        <DialogHeader>
+          <DialogTitle>Newsletter</DialogTitle>
+        </DialogHeader>
+        <DialogContent>
+          <p>
+            Get a short email when we ship something new. No more than once a
+            month.
+          </p>
+        </DialogContent>
+        <DialogFooter>
+          <Button commandfor="dialog-basics-1" command="close">
+            Not now
+          </Button>
+          <Button commandfor="dialog-basics-1" command="close" variant="filled">
+            Subscribe
+          </Button>
+        </DialogFooter>
+      </Dialog>
+    </>
+  )
+}
+```
+
+## Svelte
+
+`import { Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle } from "opui-css/svelte"`
+
+### Example: Basics
+
+```svelte
+<script lang="ts">
+  import {
+    Button,
+    Dialog,
+    DialogContent,
+    DialogFooter,
+    DialogHeader,
+    DialogTitle,
+  } from "opui-css/svelte"
+</script>
+
+<Button commandfor="dialog-basics-1" command="show-modal" variant="outlined">
+  Open dialog
+</Button>
+
+<Dialog id="dialog-basics-1">
+  <DialogHeader>
+    <DialogTitle>Newsletter</DialogTitle>
+  </DialogHeader>
+  <DialogContent>
+    <p>
+      Get a short email when we ship something new. No more than once a month.
+    </p>
+  </DialogContent>
+  <DialogFooter>
+    <Button commandfor="dialog-basics-1" command="close">Not now</Button>
+    <Button commandfor="dialog-basics-1" command="close" variant="filled">
+      Subscribe
+    </Button>
+  </DialogFooter>
+</Dialog>
+```
+
+## Vue
+
+`import { Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle } from "opui-css/vue"`
+
+### Example: Basics
+
+```vue
+<script setup lang="ts">
+import {
+  Button,
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "opui-css/vue"
+</script>
+
+<template>
+  <Button commandfor="dialog-basics-1" command="show-modal" variant="outlined">
+    Open dialog
+  </Button>
+
+  <Dialog id="dialog-basics-1">
+    <DialogHeader>
+      <DialogTitle>Newsletter</DialogTitle>
+    </DialogHeader>
+    <DialogContent>
+      <p>
+        Get a short email when we ship something new. No more than once a month.
+      </p>
+    </DialogContent>
+    <DialogFooter>
+      <Button commandfor="dialog-basics-1" command="close"> Not now </Button>
+      <Button commandfor="dialog-basics-1" command="close" variant="filled">
+        Subscribe
+      </Button>
+    </DialogFooter>
+  </Dialog>
+</template>
+```

package/skills/opui/references/divider.md

@@ -0,0 +1,112 @@
+# Divider
+
+It's just a line.
+
+- CSS: `opui-css/css/components/divider.css`.
+- Full docs with every example: [HTML](https://open-props-ui.netlify.app/html/components/divider.md), [Astro](https://open-props-ui.netlify.app/astro/components/divider.md), [React](https://open-props-ui.netlify.app/react/components/divider.md), [Svelte](https://open-props-ui.netlify.app/svelte/components/divider.md), [Vue](https://open-props-ui.netlify.app/vue/components/divider.md).
+
+## Divider
+
+### Parts
+
+- `.ui-divider` (root): The divider line. An `<hr>`, or a `<div>` or `<p>` with content in the middle.
+
+### Props and modifiers
+
+- `align`: `"center"` (default), `"end"` (`.ui-align-end`), `"start"` (`.ui-align-start`). Where the content sits on the line.
+- `color`: `"primary"` (`.ui-primary`). Optional colors.
+- `variant`: `"filled"` (`.ui-filled`), `"outlined"` (default), `"tonal"` (`.ui-tonal`). The variant to use.
+
+### Slots
+
+- `default`: Optional content in the middle of the line. Renders a `<div>`.
+
+## Component properties
+
+Set inputs on the component, inline or in your CSS. Outputs follow the variant and state, so never override them.
+
+### divider.css
+
+- `--_divider-border-color`: The line color. Defaults to `--ui-border-color`, `.ui-filled`, `.ui-primary` and `.ui-tonal` set it.
+
+## Theme tokens
+
+The stylesheets read `--ui-border-color`, `--ui-border-width`, `--ui-divider-gap`, `--ui-font-size-caption`, `--ui-primary`, `--ui-space-3`, `--ui-space-4`, `--ui-surface-filled`, `--ui-surface-tonal` and `--ui-text`. `theming.md` and `tokens.json` describe them.
+
+## HTML
+
+### Example: Basics
+
+```html
+This text is placed over
+<hr class="ui-divider" />
+This text is placed under
+```
+
+## Astro
+
+`import { Divider } from "opui-css/astro"`
+
+### Example: Basics
+
+```astro
+---
+import { Divider } from "opui-css/astro"
+---
+
+This text is placed over
+<Divider />
+This text is placed under
+```
+
+## React
+
+`import { Divider } from "opui-css/react"`
+
+### Example: Basics
+
+```tsx
+import { Divider } from "opui-css/react"
+
+export default function Basics() {
+  return (
+    <>
+      This text is placed over <Divider /> This text is placed under
+    </>
+  )
+}
+```
+
+## Svelte
+
+`import { Divider } from "opui-css/svelte"`
+
+### Example: Basics
+
+```svelte
+<script lang="ts">
+  import { Divider } from "opui-css/svelte"
+</script>
+
+This text is placed over
+<Divider />
+This text is placed under
+```
+
+## Vue
+
+`import { Divider } from "opui-css/vue"`
+
+### Example: Basics
+
+```vue
+<script setup lang="ts">
+import { Divider } from "opui-css/vue"
+</script>
+
+<template>
+  This text is placed over
+  <Divider />
+  This text is placed under
+</template>
+```