opui-css 5.4.3 → 6.0.0-rc.2

package/skills/opui/references/control-group.md

@@ -0,0 +1,270 @@
+# Control group
+
+Related buttons and fields joined into one control, like a split button, a search field with its button, or a currency and an amount.
+
+- CSS: `opui-css/css/components/control-group.css`, `opui-css/css/components/button.css` and `opui-css/css/components/text-field.css`.
+- Full docs with every example: [HTML](https://open-props-ui.netlify.app/html/components/control-group.md), [Astro](https://open-props-ui.netlify.app/astro/components/control-group.md), [React](https://open-props-ui.netlify.app/react/components/control-group.md), [Svelte](https://open-props-ui.netlify.app/svelte/components/control-group.md), [Vue](https://open-props-ui.netlify.app/vue/components/control-group.md).
+- The docs page also documents `Button`, see `button.md`.
+
+## ControlGroup
+
+### Parts
+
+- `.ui-control-group` (root): Container element.
+- `& > :is(.ui-number-field, .ui-select, .ui-text-field, .ui-textarea)` (`TextField`): A number field, select, text field or textarea. Its `.ui-field` joins the controls next to it.
+- `& > .ui-button` (`Button`): A button or button link.
+
+### Props and modifiers
+
+- `color`: `"critical"` (`.ui-critical`), `"primary"` (`.ui-primary`). Optional colors for the buttons.
+- `orientation`: `"horizontal"` (default), `"vertical"` (`.ui-vertical`). The orientation of the element.
+- `overflow`: `"scroll"` (`.ui-overflow-scroll`), `"shrink"` (`.ui-overflow-shrink`), `"wrap"` (default). What the controls do when they don't fit. `wrap` wraps them onto more rows, `scroll` keeps them on one row and scrolls it sideways, and `shrink` keeps them on one row, shrinks the fields and truncates button labels with an ellipsis. Icon-only buttons keep their size.
+- `size`: `"large"` (`.ui-large`), `"medium"` (default), `"small"` (`.ui-small`), `"x-small"` (`.ui-x-small`). The size of the buttons and fields.
+- `variant`: `"filled"` (`.ui-filled`), `"outlined"` (`.ui-outlined`), `"tonal"` (`.ui-tonal`), `"transparent"` (default). The variant of the buttons.
+
+### Slots
+
+- `default`: The buttons and fields.
+
+### Notes
+
+- HTML: The root needs `role="group"`.
+
+## Component properties
+
+Set inputs on the component, inline or in your CSS. Outputs follow the variant and state, so never override them.
+
+### control-group.css
+
+- `--_divider-accent`: The color `--_divider-border-color` lightens or darkens by 0.1, like the button's `--_accent-tonal`: `--ui-surface-tonal`, the palette tint in `.ui-critical`, and `--ui-primary-tonal` or the tint in `.ui-primary`. In a filled `.ui-critical` or `.ui-primary` group, `--ui-critical` within `--ui-accent-fill-max-lightness` or `--ui-primary`, like the button's `--_accent-fill`.
+- `--_divider-border-color-enabled`: Color of the line while a button in the group is enabled, from `--_divider-accent`. In a `.ui-filled` group without a color, `currentColor`, so where the buttons overlap each one draws the line in its own text color, and the rule between them is `transparent`, so the surface behind the group shows through. `--ui-control-border-color-filled`, the hook for filled controls, replaces it when a theme sets it.
+
+Outputs: `--_border-color`, `--_divider-border-color`, `--_divider-border-color-disabled`, `--_divider-gap`, `--_end-end-radius`, `--_end-start-radius`, `--_overlap`, `--_ring-reach`, `--_shadow`, `--_start-border-color`, `--_start-end-radius` and `--_start-start-radius`.
+
+### button.css
+
+- `--_accent`: The accent color. Fills, borders, text, hover and active states are derived from it. Defaults to `--ui-button-accent` when a theme sets it. `.ui-primary` and `.ui-critical` set it.
+- `--_accent-fill`: Fill of filled buttons, of hovered outlined buttons unless `--ui-button-hover` is `layer`, of hovered tonal ones when it is unset, and the base of the filled hover and pressed shades. `--ui-button-accent-filled` when a theme sets it, else `--_accent`, and in `.ui-critical` `--ui-critical` kept within `--ui-accent-fill-max-lightness`, so the light text stays readable while the border keeps `--ui-critical`. `.ui-primary` resets it to `--_accent`, so the token applies to default buttons only.
+- `--_accent-tonal`: Background of `.ui-tonal`. `--ui-surface-tonal`, a palette tint in `.ui-critical`, and `--ui-primary-tonal` or the tint in `.ui-primary`.
+- `--_border-width`: The border width.
+- `--_ease`: Easing of the transitions. Defaults to `--ui-ease`.
+- `--_end-end-radius`: The radius of the end-end corner. Defaults to `--_radius`. A `ControlGroup` sets it to `0` where the button joins the next control.
+- `--_end-start-radius`: The radius of the end-start corner. Defaults to `--_radius`. A `ControlGroup` sets it to `0` where the button joins another control.
+- `--_font-size`: The font size. Set by `.ui-x-small` and `.ui-small`.
+- `--_icon-size`: The size of a direct child `svg`. Icon-only buttons scale it with `--_size`.
+- `--_motion`: Motion multiplier for the transitions. `0` turns them off.
+- `--_on-accent`: Text color on a fill of `--_accent`. Defaults to `--ui-button-on-accent` when a theme sets it. `.ui-primary` sets `--ui-on-primary`, `.ui-critical` `--ui-on-fill`.
+- `--_on-accent-fill`: Text color on `--_accent-fill`: filled buttons, hovered outlined ones unless `--ui-button-hover` is `layer`, and hovered tonal ones when it is unset. `--ui-button-on-accent-filled` when a theme sets it, else `--_on-accent`.
+- `--_on-accent-tonal`: Text color of `.ui-tonal`.
+- `--_padding-inline`: The inline padding. Set by the size classes from `--ui-button-padding-inline` and its size variants.
+- `--_radius`: The corner radius. Defaults to `--ui-button-radius`, or `--ui-radius` when the theme doesn't set it. `.ui-round` makes it round.
+- `--_size`: The height, and the width of an icon-only button. Defaults to `--ui-button-size`, set by the size classes.
+- `--_start-end-radius`: The radius of the start-end corner. Defaults to `--_radius`. A `ControlGroup` sets it to `0` where the button joins another control.
+- `--_start-start-radius`: The radius of the start-start corner. Defaults to `--_radius`. A `ControlGroup` sets it to `0` where the button joins the control before it.
+
+Outputs: `--_accent-text`, `--_actions-shift`, `--_bg-color`, `--_border-color`, `--_current-bg-color`, `--_current-text-color`, `--_default-active-bg-color`, `--_default-hover-bg-color`, `--_duration`, `--_filled-active-bg-color`, `--_filled-hover-bg-color`, `--_outlined-active-bg-color`, `--_outlined-active-border-color`, `--_outlined-active-text-color`, `--_outlined-hover-bg-color`, `--_outlined-hover-border-color`, `--_outlined-hover-text-color`, `--_shadow`, `--_text-color`, `--_tonal-active-bg-color`, `--_tonal-active-text-color`, `--_tonal-current-bg-color`, `--_tonal-hover-bg-color` and `--_tonal-hover-text-color`.
+
+### text-field.css
+
+- `--_accent`: Border color of `.ui-field` when its control has focus without `:focus-visible`, such as a clicked file or color input or a Select picked with the pointer. Text-entry fields show the focus ring on click too. Defaults to `--ui-primary`, `--ui-invalid` when invalid.
+- `--_arrow-inset`: Distance of the select arrow from the inline end.
+- `--_chevron-image`: The select arrow, as an image used for a mask.
+- `--_chevron-size`: Width and height of the select arrow.
+- `--_ease`: Easing of the transitions. Defaults to `--ui-ease`.
+- `--_end-end-radius`: The radius of the end-end corner of `.ui-field`. Defaults to `--_radius`. A `ControlGroup` sets it to `0` where the field joins the next control.
+- `--_end-start-radius`: The radius of the end-start corner of `.ui-field`. Defaults to `--_radius`. A `ControlGroup` sets it to `0` where the field joins another control.
+- `--_field-padding-block`: The preferred block padding of the control. Set by the size classes.
+- `--_field-padding-inline`: The inline padding of the control and affixes. `--ui-field-padding-inline`, or `--ui-space-2` when a theme leaves it unset, and `--ui-field-padding-inline-large` or `--ui-space-3` in `.ui-large`.
+- `--_font-size`: The font size of the control and affixes.
+- `--_motion`: Motion multiplier for the transitions. `0` turns them off.
+- `--_radius`: The corner radius of `.ui-field` and a file input's button. Defaults to `--ui-field-radius`, or `--ui-radius` when the theme doesn't set it.
+- `--_shadow`: The shadow of `.ui-field`. Defaults to `--ui-shadow-field`, or `--ui-shadow-control` when the theme leaves it unset. `none` in a `ControlGroup`.
+- `--_size`: The height of `.ui-field`, a minimum so a textarea can grow, and the width and height of a color field. Defaults to `--ui-field-size`, set by the size classes.
+- `--_start-end-radius`: The radius of the start-end corner of `.ui-field`. Defaults to `--_radius`. A `ControlGroup` sets it to `0` where the field joins another control.
+- `--_start-start-radius`: The radius of the start-start corner of `.ui-field`. Defaults to `--_radius`. A `ControlGroup` sets it to `0` where the field joins the control before it.
+
+Outputs: `--_affix-button-size`, `--_affix-text-color`, `--_arrow-padding`, `--_bg-color`, `--_border-color`, `--_duration`, `--_field-padding-block-fit`, `--_file-button-inset` and `--_helper-text-color`.
+
+## Theme tokens
+
+The stylesheets read `--ui-accent-fill-max-lightness`, `--ui-border-width`, `--ui-button-accent`, `--ui-button-accent-filled`, `--ui-button-focus`, `--ui-button-font-weight`, `--ui-button-hover`, `--ui-button-hover-shadow`, `--ui-button-hover-translate`, `--ui-button-on-accent`, `--ui-button-on-accent-filled`, `--ui-button-padding-inline`, `--ui-button-padding-inline-large`, `--ui-button-padding-inline-small`, `--ui-button-padding-inline-x-small`, `--ui-button-radius`, `--ui-button-shadow`, `--ui-button-size`, `--ui-button-size-large`, `--ui-button-size-small`, `--ui-button-size-x-small`, `--ui-card-padding`, `--ui-contrast`, `--ui-control-accent`, `--ui-control-border-color`, `--ui-control-border-color-filled`, `--ui-critical`, `--ui-critical-text`, `--ui-disabled-opacity`, `--ui-duration`, `--ui-duration-fast`, `--ui-ease`, `--ui-ease-move`, `--ui-field-bg-color`, `--ui-field-border-color`, `--ui-field-border-width`, `--ui-field-helper-font-size`, `--ui-field-helper-line-height`, `--ui-field-helper-text-color`, `--ui-field-label-font-size`, `--ui-field-label-font-weight`, `--ui-field-label-text-color`, `--ui-field-padding-inline`, `--ui-field-padding-inline-large`, `--ui-field-placeholder-text-color`, `--ui-field-radius`, `--ui-field-required-text-color`, `--ui-field-size`, `--ui-field-size-large`, `--ui-field-size-small`, `--ui-field-size-x-small`, `--ui-focus-border-color`, `--ui-focus-border-width`, `--ui-focus-highlight`, `--ui-focus-ring-color`, `--ui-focus-ring-offset`, `--ui-focus-ring-style`, `--ui-focus-ring-width`, `--ui-font-body`, `--ui-font-code`, `--ui-font-size-caption`, `--ui-font-size-control`, `--ui-font-size-small`, `--ui-font-weight-bold`, `--ui-font-weight-normal`, `--ui-icon-size`, `--ui-icon-size-small`, `--ui-invalid`, `--ui-invalid-text`, `--ui-line-height-control`, `--ui-line-height-tight`, `--ui-motion`, `--ui-on-control-accent`, `--ui-on-fill`, `--ui-on-focus-highlight`, `--ui-on-primary`, `--ui-on-primary-tonal`, `--ui-palette-on-strong`, `--ui-palette-on-tint`, `--ui-palette-strong`, `--ui-palette-tint`, `--ui-press-scale`, `--ui-primary`, `--ui-primary-text`, `--ui-primary-tonal`, `--ui-radius`, `--ui-radius-round`, `--ui-radius-small`, `--ui-shadow-control`, `--ui-shadow-field`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`, `--ui-state-active-alpha-accent`, `--ui-state-active-alpha-dark`, `--ui-state-active-alpha-light`, `--ui-state-hover-alpha-accent`, `--ui-state-hover-alpha-dark`, `--ui-state-hover-alpha-light`, `--ui-state-selected-alpha-accent`, `--ui-surface`, `--ui-surface-tonal`, `--ui-surface-tonal-hover`, `--ui-text`, `--ui-text-disabled`, `--ui-text-max-chroma`, `--ui-text-min-lightness`, `--ui-text-strong` and `--ui-text-subtle`. `theming.md` and `tokens.json` describe them.
+
+## HTML
+
+### Example: Variants
+
+```html
+<div class="ui-control-group" role="group">
+  <button class="ui-button" type="button">Transparent</button>
+  <button class="ui-button" type="button">Transparent</button>
+  <a class="ui-button" href="#">Transparent</a>
+</div>
+
+<div class="ui-control-group ui-outlined" role="group">
+  <button class="ui-button" type="button">Outlined</button>
+  <button class="ui-button" type="button">Outlined</button>
+  <a class="ui-button" href="#">Outlined</a>
+</div>
+
+<div class="ui-control-group ui-tonal" role="group">
+  <button class="ui-button" type="button">Tonal</button>
+  <button class="ui-button" type="button">Tonal</button>
+  <a class="ui-button" href="#">Tonal</a>
+</div>
+
+<div class="ui-control-group ui-filled" role="group">
+  <button class="ui-button" type="button">Filled</button>
+  <button class="ui-button" type="button">Filled</button>
+  <a class="ui-button" href="#">Filled</a>
+</div>
+```
+
+## Astro
+
+`import { Button, ControlGroup, TextField } from "opui-css/astro"`
+
+### Example: Variants
+
+```astro
+---
+import { Button, ControlGroup } from "opui-css/astro"
+---
+
+<ControlGroup>
+  <Button>Transparent</Button>
+  <Button>Transparent</Button>
+  <Button href="#">Transparent</Button>
+</ControlGroup>
+
+<ControlGroup variant="outlined">
+  <Button>Outlined</Button>
+  <Button>Outlined</Button>
+  <Button href="#">Outlined</Button>
+</ControlGroup>
+
+<ControlGroup variant="tonal">
+  <Button>Tonal</Button>
+  <Button>Tonal</Button>
+  <Button href="#">Tonal</Button>
+</ControlGroup>
+
+<ControlGroup variant="filled">
+  <Button>Filled</Button>
+  <Button>Filled</Button>
+  <Button href="#">Filled</Button>
+</ControlGroup>
+```
+
+## React
+
+`import { Button, ControlGroup, TextField } from "opui-css/react"`
+
+### Example: Variants
+
+```tsx
+import { Button, ControlGroup } from "opui-css/react"
+
+export default function Variants() {
+  return (
+    <>
+      <ControlGroup>
+        <Button>Transparent</Button>
+        <Button>Transparent</Button>
+        <Button href="#">Transparent</Button>
+      </ControlGroup>
+
+      <ControlGroup variant="outlined">
+        <Button>Outlined</Button>
+        <Button>Outlined</Button>
+        <Button href="#">Outlined</Button>
+      </ControlGroup>
+
+      <ControlGroup variant="tonal">
+        <Button>Tonal</Button>
+        <Button>Tonal</Button>
+        <Button href="#">Tonal</Button>
+      </ControlGroup>
+
+      <ControlGroup variant="filled">
+        <Button>Filled</Button>
+        <Button>Filled</Button>
+        <Button href="#">Filled</Button>
+      </ControlGroup>
+    </>
+  )
+}
+```
+
+## Svelte
+
+`import { Button, ControlGroup, TextField } from "opui-css/svelte"`
+
+### Example: Variants
+
+```svelte
+<script lang="ts">
+  import { Button, ControlGroup } from "opui-css/svelte"
+</script>
+
+<ControlGroup>
+  <Button>Transparent</Button>
+  <Button>Transparent</Button>
+  <Button href="#">Transparent</Button>
+</ControlGroup>
+
+<ControlGroup variant="outlined">
+  <Button>Outlined</Button>
+  <Button>Outlined</Button>
+  <Button href="#">Outlined</Button>
+</ControlGroup>
+
+<ControlGroup variant="tonal">
+  <Button>Tonal</Button>
+  <Button>Tonal</Button>
+  <Button href="#">Tonal</Button>
+</ControlGroup>
+
+<ControlGroup variant="filled">
+  <Button>Filled</Button>
+  <Button>Filled</Button>
+  <Button href="#">Filled</Button>
+</ControlGroup>
+```
+
+## Vue
+
+`import { Button, ControlGroup, TextField } from "opui-css/vue"`
+
+### Example: Variants
+
+```vue
+<script setup lang="ts">
+import { Button, ControlGroup } from "opui-css/vue"
+</script>
+
+<template>
+  <ControlGroup>
+    <Button>Transparent</Button>
+    <Button>Transparent</Button>
+    <Button href="#">Transparent</Button>
+  </ControlGroup>
+
+  <ControlGroup variant="outlined">
+    <Button>Outlined</Button>
+    <Button>Outlined</Button>
+    <Button href="#">Outlined</Button>
+  </ControlGroup>
+
+  <ControlGroup variant="tonal">
+    <Button>Tonal</Button>
+    <Button>Tonal</Button>
+    <Button href="#">Tonal</Button>
+  </ControlGroup>
+
+  <ControlGroup variant="filled">
+    <Button>Filled</Button>
+    <Button>Filled</Button>
+    <Button href="#">Filled</Button>
+  </ControlGroup>
+</template>
+```

package/skills/opui/references/copy.md

@@ -0,0 +1,181 @@
+# Copy
+
+A button that copies text or a field's value to the clipboard.
+
+- CSS: `opui-css/css/components/copy.css`.
+- Full docs with every example: [HTML](https://open-props-ui.netlify.app/html/components/copy.md), [Astro](https://open-props-ui.netlify.app/astro/components/copy.md), [React](https://open-props-ui.netlify.app/react/components/copy.md), [Svelte](https://open-props-ui.netlify.app/svelte/components/copy.md), [Vue](https://open-props-ui.netlify.app/vue/components/copy.md).
+
+## Copy
+
+### Parts
+
+- `opui-copy.ui-copy` (root): The `<opui-copy>` custom element around the text or field to copy, with `display: contents`.
+- `<span popover>` (prop `copiedLabel`, prop `failedLabel`): The label next to the button that shows `copiedLabel` or `failedLabel`.
+- `<span role="status">`: The live region that announces the copy, visually hidden with `.ui-sr-only`.
+
+### Props and modifiers
+
+- `copiedLabel`: `string`, `[copied-label]`, default `"Copied"`. The text shown and announced after a copy.
+- `failedLabel`: `string`, `[failed-label]`, default `"Copy failed"`. The text shown and announced when the clipboard is blocked.
+- `id`: `string`. The id the copy button points at with `commandfor`. Required.
+
+### Slots
+
+- `default`: The text or the field to copy, and the button if it sits inside.
+
+### Notes
+
+- HTML: Wrap the text or the field in `<opui-copy class="ui-copy">` with an id, and end it with `<span class="ui-sr-only" role="status">` for the announcement and `<span class="ui-floating" popover aria-hidden="true">` for the label. Point a button at it with `commandfor` and `command="--copy"`, inside the element or right after it, and import `opui-css/elements/copy.js`. Until it loads, the button is hidden.
+- Astro: The component loads `opui-css/elements/copy.js`. Attributes that aren't props go to the root `<opui-copy>`, and the button works once the element runs.
+- React: The component loads `opui-css/elements/copy.js` once it mounts, unless the page imports it first. Attributes that aren't props go to the root `<opui-copy>`, and the button works once the element runs.
+- Svelte and Vue: The component imports `opui-css/elements/copy.js`, so the element runs as soon as the component's code loads. Attributes that aren't props go to the root `<opui-copy>`, and the button works once the element runs.
+
+## Component properties
+
+Set inputs on the component, inline or in your CSS. Outputs follow the variant and state, so never override them.
+
+### copy.css
+
+- `--_bg-color`: Background of the label. Defaults to `--ui-surface-elevated`.
+- `--_ease`: Easing of the reveal and the fade. Defaults to `--ui-ease-enter`.
+- `--_motion`: Motion multiplier for the reveal and the fade. `0` turns them off.
+- `--_offset`: The gap between the label and the button.
+
+Outputs: `--_accent`, `--_border-color`, `--_duration`, `--_font-size`, `--_hidden-clip-path`, `--_radius`, `--_shown-clip-path` and `--_text-color`.
+
+## Theme tokens
+
+The stylesheets read `--ui-border-width`, `--ui-button-accent`, `--ui-button-font-weight`, `--ui-button-padding-inline`, `--ui-button-radius`, `--ui-button-shadow`, `--ui-contrast`, `--ui-control-accent`, `--ui-control-border-color`, `--ui-duration`, `--ui-ease-enter`, `--ui-ease-exit`, `--ui-font-size-control`, `--ui-font-weight-bold`, `--ui-line-height-tight`, `--ui-motion`, `--ui-palette-strong`, `--ui-radius`, `--ui-shadow-control`, `--ui-space-1`, `--ui-space-4`, `--ui-surface-elevated`, `--ui-text-max-chroma` and `--ui-text-min-lightness`. `theming.md` and `tokens.json` describe them.
+
+## HTML
+
+### Example: Basics
+
+```html
+<opui-copy id="copy-basics-1" class="ui-copy">
+  <label class="ui-text-field">
+    <span class="ui-sr-only">Invite link</span>
+    <span class="ui-field">
+      <input readonly value="https://example.com/invite/8f3k2" type="text" />
+    </span>
+  </label>
+  <span class="ui-sr-only" role="status"></span>
+  <span aria-hidden="true" class="ui-floating" popover></span>
+</opui-copy>
+<button
+  class="ui-button ui-outlined"
+  type="button"
+  command="--copy"
+  commandfor="copy-basics-1"
+>
+  Copy
+</button>
+
+<script type="module">
+  import "opui-css/elements/copy.js"
+</script>
+```
+
+## Astro
+
+`import { Copy } from "opui-css/astro"`
+
+### Example: Basics
+
+```astro
+---
+import { Button, Copy, TextField } from "opui-css/astro"
+---
+
+<Copy id="copy-basics-1">
+  <TextField
+    hideLabel
+    label="Invite link"
+    readonly
+    value="https://example.com/invite/8f3k2"
+  />
+</Copy>
+<Button command="--copy" commandfor="copy-basics-1" variant="outlined"
+  >Copy</Button
+>
+```
+
+## React
+
+`import { Copy } from "opui-css/react"`
+
+- Client components (`"use client"`): `Copy`.
+
+### Example: Basics
+
+```tsx
+import { Button, Copy, TextField } from "opui-css/react"
+
+export default function Basics() {
+  return (
+    <>
+      <Copy id="copy-basics-1">
+        <TextField
+          hideLabel
+          label="Invite link"
+          readOnly
+          value="https://example.com/invite/8f3k2"
+        />
+      </Copy>
+      <Button command="--copy" commandfor="copy-basics-1" variant="outlined">
+        Copy
+      </Button>
+    </>
+  )
+}
+```
+
+## Svelte
+
+`import { Copy } from "opui-css/svelte"`
+
+### Example: Basics
+
+```svelte
+<script lang="ts">
+  import { Button, Copy, TextField } from "opui-css/svelte"
+</script>
+
+<Copy id="copy-basics-1">
+  <TextField
+    hideLabel
+    label="Invite link"
+    readonly
+    value="https://example.com/invite/8f3k2"
+  />
+</Copy>
+<Button command="--copy" commandfor="copy-basics-1" variant="outlined"
+  >Copy</Button
+>
+```
+
+## Vue
+
+`import { Copy } from "opui-css/vue"`
+
+### Example: Basics
+
+```vue
+<script setup lang="ts">
+import { Button, Copy, TextField } from "opui-css/vue"
+</script>
+
+<template>
+  <Copy id="copy-basics-1">
+    <TextField
+      hideLabel
+      label="Invite link"
+      readonly
+      value="https://example.com/invite/8f3k2"
+    />
+  </Copy>
+  <Button command="--copy" commandfor="copy-basics-1" variant="outlined"
+    >Copy</Button
+  >
+</template>
+```

package/skills/opui/references/customizing.md

@@ -0,0 +1,84 @@
+# Customizing
+
+A theme in `theme.custom`, `--_*` properties for one component, and your own layer for the rest.
+
+## Your theme
+
+Set 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.
+
+```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;
+  }
+}
+```
+
+The [Theme builder](https://open-props-ui.netlify.app/theme-builder.md) writes one for you. Put pinned roles, like `--ui-primary`, on `:where(html, .ui-palette, .ui-contrast-more)`.
+
+### Example themes
+
+Tokens only, no component CSS. They name their fonts but don't load them. Each borrows the look of a design system it isn't affiliated with.
+
+- `bootstrap`: Bootstrap 5. Its `oklch(0.578 0.228 260)` blue, gray secondary buttons, buttons that shade their own color on hover, the danger, warning, info and success colors with the subtle alert palettes, `oklch(0.91 0.007 248)` borders, 38px controls, regular weight buttons, labels and links, 16px paragraph spacing with 8px under headings, 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, with a state layer instead of a fill swap, filled in the main blue, white fields on the gray-blue page, the main blue also behind tooltips and selected items, black links, 500 weight body text and the 1.75 line height of Tailwind prose in rich text.
+- `govuk`: GOV.UK Design System. Black text on white, the brand blue, regular weight links in the darker link blue and purple once visited, the error red and the success green as they are, 2px black field borders, square corners, green default buttons with a 2px bottom edge and gray secondary buttons that darken on hover, 40px checkboxes and radios that draw a black check and dot on white, with the gray hover ring, 19px body, label, hint and control text on 25px lines, the bold heading scale up to 48px, 15px to 20px paragraph spacing, headings spaced from their own size, 5px spacing steps, the 3px yellow focus ring on a black edge, 4px on checkboxes, radios and fields, links and buttons that turn yellow with black text when focused, no shadows, and Arial, its font off GOV.UK. GOV.UK has no dark mode, so the theme swaps its black and white.
+- `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 that thicken to 2px when focused, 8px chips, 18px checkboxes with 2px borders, 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 over a gray border, 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, 500 weight links and the 1.75 line height of Tailwind prose in rich text.
+
+```css
+@import "opui-css/css/imports.css";
+@import "opui-css/themes/brutalist.css";
+```
+
+## Component properties
+
+Each component page lists its `--_*` properties. Button reads these:
+
+- `--_accent`: the accent color, which every state derives from.
+- `--_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.
+- `--_motion`: the motion multiplier.
+- `--_padding-inline`: the inline padding.
+
+Set them on the component, not 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`, which freezes every state.
+
+## Unlayered or your own layer
+
+Unlayered CSS beats every [layer](https://open-props-ui.netlify.app/html/guide/concepts.md#cascade-layers). With your own layers, add one after `utils`.
+
+```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);
+  }
+}
+```