opui-css 5.4.3 → 6.0.0-rc.1

package/skills/opui/references/carousel.md

@@ -0,0 +1,269 @@
+# Carousel
+
+A scrolling list with snap points, buttons and markers.
+
+- CSS: `opui-css/css/components/carousel.css`.
+- Full docs with every example: [HTML](https://open-props-ui.netlify.app/html/components/carousel.md), [Astro](https://open-props-ui.netlify.app/astro/components/carousel.md), [React](https://open-props-ui.netlify.app/react/components/carousel.md), [Svelte](https://open-props-ui.netlify.app/svelte/components/carousel.md), [Vue](https://open-props-ui.netlify.app/vue/components/carousel.md).
+
+## Carousel
+
+### Parts
+
+- `ul.ui-carousel` (root): The scroller.
+- `<li>` (slot `default`): An item.
+- `::scroll-button(inline-start)` (prop `buttons`): The previous button. `::scroll-button(block-start)` when vertical.
+- `::scroll-button(inline-end)` (prop `buttons`): The next button. `::scroll-button(block-end)` when vertical.
+- `li::scroll-marker` (prop `markers`): A marker, one per item.
+
+### Props and modifiers
+
+- `align`: `"center"` (`.ui-align-center`), `"start"` (default). Where items snap.
+- `aria-label`: `string`, `[aria-label]`. Accessible name of the carousel.
+- `aspectRatio`: `number | string`, `--_media-aspect-ratio`, default `"16 / 9"`. Aspect ratio that images, videos and iframes are cropped to.
+- `buttons`: `"inside"` (default), `"none"` (`.ui-buttons-none`), `"outside"` (`.ui-buttons-outside`). Previous and next buttons. `"outside"` places them beside the items, and `"none"` leaves them out.
+- `itemsPerView`: `number`, `--_items-per-view`, default `1`. Number of visible items.
+- `markers`: `boolean`, `.ui-markers`. One marker per item, after the list.
+- `orientation`: `"horizontal"` (default), `"vertical"` (`.ui-vertical`). The orientation of the element. A vertical carousel is `--_block-size` tall, `24rem` by default.
+- `peek`: `boolean`, `.ui-peek`. Shows part of the neighboring items.
+- `persistentButtons`: `boolean`, `.ui-persistent-buttons`. Keeps the buttons visible at the ends. A disabled button has a muted border.
+- `stretch`: `boolean`, `.ui-stretch`. Makes each item a grid, so its content (a card, a link) fills the item's height. Media with an aspect ratio keeps it.
+
+### Notes
+
+- HTML: The root is a `<ul>` with an `aria-label`. CSS adds the buttons, and `.ui-markers` the markers. Smooth scrolling follows `--ui-motion`: `.ui-motion-off` on the carousel or a parent turns it off.
+- Astro, React, Svelte and Vue: Smooth scrolling follows `--ui-motion`: `.ui-motion-off` on the carousel or a parent turns it off.
+
+## Component properties
+
+Set inputs on the component, inline or in your CSS. Outputs follow the variant and state, so never override them.
+
+### carousel.css
+
+- `--_block-size`: The height of `.ui-vertical`.
+- `--_button-bg-color`: Background of the scroll buttons. Defaults to `--ui-surface-inverse`.
+- `--_button-disabled-opacity`: Opacity of disabled scroll buttons. `0` hides them, `.ui-persistent-buttons` sets `1`.
+- `--_button-image`: Icon of the scroll buttons, pointing forward. The previous button mirrors it.
+- `--_button-image-size`: The icon size in the scroll buttons.
+- `--_button-inset`: Space between the scroll buttons and the carousel edge.
+- `--_button-next-label`: Accessible label of the next button.
+- `--_button-prev-label`: Accessible label of the previous button.
+- `--_button-shadow`: Shadow of the scroll buttons. Defaults to `--ui-shadow-overlay`.
+- `--_button-size`: Size of the scroll buttons. Defaults to `--ui-button-size-small`.
+- `--_ease`: Easing of the transitions. Defaults to `--ui-ease`.
+- `--_gap`: Space between items.
+- `--_items-per-view`: Number of items per view.
+- `--_marker-bg-color`: Fill of the other markers. Defaults to `transparent`.
+- `--_marker-border-color`: Ring of the other markers. Defaults to `--ui-text`, which keeps its contrast against the page in every theme.
+- `--_marker-gap`: Space between markers.
+- `--_marker-label`: Accessible label of each marker, followed by the item number.
+- `--_marker-selected-bg-color`: Fill and ring of the current marker. Defaults to `--ui-selected-strong`.
+- `--_marker-selected-padding`: Inset of the current marker's dot, smaller than the `--ui-space-2` of the other markers, so the current dot is larger. Defaults to `--ui-space-1`.
+- `--_marker-size`: Size of the markers. The dot sits inside, inset by `--ui-space-2`.
+- `--_markers-gap`: Space between the items and the markers.
+- `--_media-aspect-ratio`: Aspect ratio of `img`, `video` and `iframe` in items.
+- `--_media-radius`: Corner radius of `img`, `video` and `iframe` in items. Defaults to `--ui-radius`.
+- `--_motion`: Motion multiplier for the button and marker transitions. `0` turns them off.
+- `--_padding-block`: Block padding of `.ui-vertical`, showing the neighboring items. Set by `.ui-peek`.
+- `--_padding-inline`: The inline padding, showing the neighboring items. Set by `.ui-peek`.
+- `--_shadow-room`: Room around the items for their box shadows, so the scroll container doesn't clip them: padding that a negative margin cancels, so the layout stays the same. On the scroll axis it is capped by `--_block-room` and `--_inline-room`. Defaults to `--ui-space-3`.
+- `--_snap-align`: Snap alignment of items. `.ui-align-center` sets `center`.
+
+Outputs: `--_block-room`, `--_button-border-color`, `--_button-disabled-border-color`, `--_button-end-flip`, `--_button-flip`, `--_button-scale`, `--_button-start-flip`, `--_duration`, `--_inline-room`, `--_item-size` and `--_scale-duration`.
+
+## Theme tokens
+
+The stylesheets read `--ui-border-width`, `--ui-button-size-small`, `--ui-control-border-color-filled`, `--ui-duration`, `--ui-duration-fast`, `--ui-ease`, `--ui-focus-ring-color`, `--ui-focus-ring-offset`, `--ui-focus-ring-style`, `--ui-focus-ring-width`, `--ui-motion`, `--ui-radius`, `--ui-radius-round`, `--ui-selected-strong`, `--ui-shadow-overlay`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-5`, `--ui-space-8`, `--ui-surface-inverse` and `--ui-text`. `theming.md` and `tokens.json` describe them.
+
+## HTML
+
+### Example: Basics
+
+```html
+<ul class="ui-carousel ui-markers" aria-label="Destinations">
+  <li>
+    <div class="ui-card ui-tonal">
+      <hgroup class="ui-header">
+        <p>Destination</p>
+        <h3>Kyoto</h3>
+        <p>Temples, gardens and quiet lanes.</p>
+      </hgroup>
+    </div>
+  </li>
+  <li>
+    <div class="ui-card ui-tonal">
+      <hgroup class="ui-header">
+        <p>Destination</p>
+        <h3>Lima</h3>
+        <p>Ceviche by the Pacific.</p>
+      </hgroup>
+    </div>
+  </li>
+  <li>
+    <div class="ui-card ui-tonal">
+      <hgroup class="ui-header">
+        <p>Destination</p>
+        <h3>Lisbon</h3>
+        <p>Tiles, trams and custard tarts.</p>
+      </hgroup>
+    </div>
+  </li>
+  <li>
+    <div class="ui-card ui-tonal">
+      <hgroup class="ui-header">
+        <p>Destination</p>
+        <h3>Oslo</h3>
+        <p>Fjords, saunas and modern architecture.</p>
+      </hgroup>
+    </div>
+  </li>
+  <li>
+    <div class="ui-card ui-tonal">
+      <hgroup class="ui-header">
+        <p>Destination</p>
+        <h3>Tunis</h3>
+        <p>Medina markets and Mediterranean light.</p>
+      </hgroup>
+    </div>
+  </li>
+</ul>
+```
+
+## Astro
+
+`import { Carousel } from "opui-css/astro"`
+
+### Example: Basics
+
+```astro
+---
+import { Card, CardHeader, Carousel } from "opui-css/astro"
+
+const places = [
+  { description: "Temples, gardens and quiet lanes.", title: "Kyoto" },
+  { description: "Ceviche by the Pacific.", title: "Lima" },
+  { description: "Tiles, trams and custard tarts.", title: "Lisbon" },
+  { description: "Fjords, saunas and modern architecture.", title: "Oslo" },
+  { description: "Medina markets and Mediterranean light.", title: "Tunis" },
+]
+---
+
+<Carousel aria-label="Destinations" markers>
+  {
+    places.map(({ description, title }) => (
+      <li>
+        <Card variant="tonal">
+          <CardHeader>
+            <p>Destination</p>
+            <h3>{title}</h3>
+            <p>{description}</p>
+          </CardHeader>
+        </Card>
+      </li>
+    ))
+  }
+</Carousel>
+```
+
+## React
+
+`import { Carousel } from "opui-css/react"`
+
+### Example: Basics
+
+```tsx
+import { Card, CardHeader, Carousel } from "opui-css/react"
+
+const places = [
+  { description: "Temples, gardens and quiet lanes.", title: "Kyoto" },
+  { description: "Ceviche by the Pacific.", title: "Lima" },
+  { description: "Tiles, trams and custard tarts.", title: "Lisbon" },
+  { description: "Fjords, saunas and modern architecture.", title: "Oslo" },
+  { description: "Medina markets and Mediterranean light.", title: "Tunis" },
+]
+
+export default function Basics() {
+  return (
+    <Carousel aria-label="Destinations" markers>
+      {places.map(({ description, title }) => (
+        <li key={title}>
+          <Card variant="tonal">
+            <CardHeader>
+              <p>Destination</p>
+              <h3>{title}</h3>
+              <p>{description}</p>
+            </CardHeader>
+          </Card>
+        </li>
+      ))}
+    </Carousel>
+  )
+}
+```
+
+## Svelte
+
+`import { Carousel } from "opui-css/svelte"`
+
+### Example: Basics
+
+```svelte
+<script lang="ts">
+  import { Card, CardHeader, Carousel } from "opui-css/svelte"
+
+  const places = [
+    { description: "Temples, gardens and quiet lanes.", title: "Kyoto" },
+    { description: "Ceviche by the Pacific.", title: "Lima" },
+    { description: "Tiles, trams and custard tarts.", title: "Lisbon" },
+    { description: "Fjords, saunas and modern architecture.", title: "Oslo" },
+    { description: "Medina markets and Mediterranean light.", title: "Tunis" },
+  ]
+</script>
+
+<Carousel aria-label="Destinations" markers>
+  {#each places as { description, title } (title)}
+    <li>
+      <Card variant="tonal">
+        <CardHeader>
+          <p>Destination</p>
+          <h3>{title}</h3>
+          <p>{description}</p>
+        </CardHeader>
+      </Card>
+    </li>
+  {/each}
+</Carousel>
+```
+
+## Vue
+
+`import { Carousel } from "opui-css/vue"`
+
+### Example: Basics
+
+```vue
+<script setup lang="ts">
+import { Card, CardHeader, Carousel } from "opui-css/vue"
+
+const places = [
+  { description: "Temples, gardens and quiet lanes.", title: "Kyoto" },
+  { description: "Ceviche by the Pacific.", title: "Lima" },
+  { description: "Tiles, trams and custard tarts.", title: "Lisbon" },
+  { description: "Fjords, saunas and modern architecture.", title: "Oslo" },
+  { description: "Medina markets and Mediterranean light.", title: "Tunis" },
+]
+</script>
+
+<template>
+  <Carousel aria-label="Destinations" markers>
+    <li v-for="{ description, title } in places" :key="title">
+      <Card variant="tonal">
+        <CardHeader>
+          <p>Destination</p>
+          <h3>{{ title }}</h3>
+          <p>{{ description }}</p>
+        </CardHeader>
+      </Card>
+    </li>
+  </Carousel>
+</template>
+```

package/skills/opui/references/checkbox.md

@@ -0,0 +1,241 @@
+# Checkbox
+
+Use a Checkbox for choices that are submitted with a form. For a setting that applies right away, use a Switch, and for options in a toolbar a Toggle. See also: Checkbox field group.
+
+- CSS: `opui-css/css/components/checkbox.css`, `opui-css/css/components/choice.css`, `opui-css/css/components/form.css` and `opui-css/css/components/card.css`.
+- Full docs with every example: [HTML](https://open-props-ui.netlify.app/html/components/checkbox.md), [Astro](https://open-props-ui.netlify.app/astro/components/checkbox.md), [React](https://open-props-ui.netlify.app/react/components/checkbox.md), [Svelte](https://open-props-ui.netlify.app/svelte/components/checkbox.md), [Vue](https://open-props-ui.netlify.app/vue/components/checkbox.md).
+- The docs page also documents `FieldGroup`, see `form.md`.
+
+## Checkbox
+
+### Parts
+
+- `label.ui-checkbox` (root): Container element.
+- `<input>` (model): The checkbox input.
+- `.ui-label` (prop `label`, slot `default`): The label.
+- `.ui-end-text` (prop `endText`, slot `end-text`): Supporting text displayed below the label.
+
+### Props and modifiers
+
+- `card`: `boolean`, `.ui-card`. Renders the checkbox as a card: a padded, outlined surface that tints when hovered and when checked, with the label and `endText` inside. Add `spread` to put the input at the end, and `variant` to change the surface.
+- `disabled`: `boolean`, `input[aria-disabled="true"]`, `input[disabled]`. Dims the checkbox and shows a not-allowed cursor. `aria-disabled="true"` looks the same, but keeps the checkbox focusable and its value in the form, and doesn't stop the change, so block it with a script.
+- `error`: `boolean`, `input[aria-invalid="true"]`. Marks the control invalid and shows error styles.
+- `hideLabel`: `boolean`, `.ui-checkbox > span.ui-sr-only`. Visually hides the label, `.ui-sr-only` instead of `.ui-label`.
+- `id`: `string`. The id of the `<input>`.
+- `indeterminate`: `boolean`, `input[data-indeterminate]`. Shows a partially checked state. Sets the `indeterminate` property on the `<input>`.
+- `name`: `string`. The name of the `<input>`. Inside a `FieldGroup`, the group's `name` applies.
+- `orientation`: `"horizontal"` (default), `"vertical"` (`.ui-vertical`). The orientation of the element. `vertical` stacks the label under the input.
+- `required`: `boolean`, `input[required]`. Adds a required mark after the label. The form won't submit until it's checked.
+- `size`: `"large"` (`.ui-large`), `"medium"` (default), `"small"` (`.ui-small`), `"x-small"` (`.ui-x-small`). The size of the element.
+- `spread`: `boolean`, `.ui-spread`. Pushes the label and the input to opposite ends.
+- `value`: `string`. The value of the `<input>`, submitted with the form when it's checked.
+- `variant`: `"elevated"` (`.ui-elevated`), `"outlined"` (default), `"tonal"` (`.ui-tonal`). The surface of the card, with `card`. `outlined` has a border, `tonal` a tinted surface and `elevated` a shadow, like Card.
+
+Model: `checked` (`boolean | (string | number)[]`), the checked state, or the checked values of a group. Astro and React `checked`, Svelte `bind:checked`, `bind:group`, Vue `v-model`.
+
+### Notes
+
+- HTML: `data-indeterminate` needs `checkbox.js`. It sets the `indeterminate` property.
+- Astro and Vue: Attributes that aren't props go to the `<input>`, like `autofocus` and `form`, and `class` and `style` go to the root `<label>`. To hide the label, set `hideLabel` and keep the text in `label` or the slot.
+- React: Attributes that aren't props go to the `<input>`, like `autofocus` and `form`, and `className` and `style` go to the root `<label>`. To hide the label, set `hideLabel` and keep the text in `label` or `children`. Use `checked` with `onChange`, or `defaultChecked`. For a group, keep the checked values in your own state.
+- Svelte: Attributes that aren't props go to the `<input>`, like `autofocus` and `form`, and `class` and `style` go to the root `<label>`. To hide the label, set `hideLabel` and keep the text in `label` or `children`.
+
+## CheckboxInput
+
+### Parts
+
+- `<input type="checkbox">` (root): The checkbox input, without a label.
+
+### Props and modifiers
+
+- `indeterminate`: `boolean`, `[data-indeterminate]`. Shows a partially checked state. Sets the `indeterminate` property on the `<input>`.
+
+Model: `checked` (`boolean | (string | number)[]`), the checked state, or the checked values of a group. Astro and React `checked`, Svelte `bind:checked`, `bind:group`, Vue `v-model`.
+
+### Notes
+
+- Astro, React, Svelte and Vue: The checkbox `<input>` without the label, for a custom layout inside a `label.ui-checkbox`, such as the end of a `ListItem` with `type="checkbox"`. Attributes that aren't props go to the `<input>`. Inside a `FieldGroup`, it takes the group's `name`.
+
+## Component properties
+
+Set inputs on the component, inline or in your CSS. Outputs follow the variant and state, so never override them.
+
+### choice.css
+
+- `--_accent`: Fill and border of the checked input. `--ui-choice-accent` when the theme sets it, otherwise `--ui-primary` with its lightness capped in dark mode, and `--ui-invalid` when invalid.
+- `--_card-padding`: Padding of `.ui-card`. `--ui-space-3`, and `--ui-space-2` in `.ui-small` and `.ui-x-small`.
+- `--_checked-bg-color`: Background of a checked `.ui-card`. `--ui-primary-tonal` when the theme sets it, otherwise `--ui-primary` at `--ui-state-active-alpha-accent`.
+- `--_ease`: Easing of the transitions. Defaults to `--ui-ease`.
+- `--_hover-bg-color`: Background of a hovered `.ui-card`. Defaults to `--ui-surface-tonal-hover`.
+- `--_motion`: Motion multiplier for the transitions. `0` turns them off.
+- `--_on-accent`: Color of the checkmark, dash and dots on `--_accent`. `--ui-choice-on-accent` when the theme sets it, otherwise `--ui-on-primary`, or `--ui-on-fill` in dark mode. `--ui-on-fill` when invalid.
+- `--_ripple-size`: Size of the hover ripple of checkboxes and radios, relative to the input. Set on `input`.
+- `--_size`: Width and height of the checkbox and radio input, which the label centers on. Defaults to `--ui-choice-size`, set by the size classes. `switch.css` sets it to the track height.
+
+Outputs: `--_bg-color`, `--_border-color`, `--_border-width`, `--_duration`, `--_shadow` and `--_thumb-scale`.
+
+### 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-border-color`, `--ui-border-color-on-raised`, `--ui-border-color-raised`, `--ui-border-width`, `--ui-card-padding`, `--ui-choice-accent`, `--ui-choice-border-color`, `--ui-choice-fill-max-lightness`, `--ui-choice-label-offset`, `--ui-choice-on-accent`, `--ui-choice-ripple-bg-color`, `--ui-choice-size`, `--ui-choice-size-large`, `--ui-choice-size-small`, `--ui-choice-size-x-small`, `--ui-control-accent`, `--ui-disabled-opacity`, `--ui-duration`, `--ui-ease`, `--ui-field-border-color`, `--ui-field-border-color-on-raised`, `--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-required-text-color`, `--ui-focus-ring-color`, `--ui-focus-ring-offset`, `--ui-focus-ring-style`, `--ui-focus-ring-width`, `--ui-font-size-body`, `--ui-font-size-caption`, `--ui-invalid`, `--ui-invalid-text`, `--ui-line-height-control`, `--ui-line-height-tight`, `--ui-motion`, `--ui-on-control-accent`, `--ui-on-fill`, `--ui-on-primary`, `--ui-primary`, `--ui-primary-tonal`, `--ui-radius`, `--ui-radius-x-small`, `--ui-shadow-elevated`, `--ui-shadow-surface`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`, `--ui-state-active-alpha-accent`, `--ui-state-hover-alpha-accent`, `--ui-surface`, `--ui-surface-elevated`, `--ui-surface-tonal`, `--ui-surface-tonal-hover`, `--ui-switch-thumb-size-large`, `--ui-switch-thumb-size-small`, `--ui-switch-thumb-size-x-small`, `--ui-switch-track-block-size-large`, `--ui-switch-track-block-size-small`, `--ui-switch-track-block-size-x-small`, `--ui-switch-track-inline-size-large`, `--ui-switch-track-inline-size-small`, `--ui-switch-track-inline-size-x-small`, `--ui-text` and `--ui-text-strong`. `theming.md` and `tokens.json` describe them.
+
+## HTML
+
+### Example: Basics
+
+```html
+<label class="ui-checkbox">
+  <input name="checkbox-basics" type="checkbox" checked />
+  <span class="ui-sr-only">Checked</span>
+</label>
+
+<label class="ui-checkbox">
+  <input name="checkbox-basics" type="checkbox" />
+  <span class="ui-sr-only">Unchecked</span>
+</label>
+
+<label class="ui-checkbox">
+  <input name="checkbox-basics" type="checkbox" data-indeterminate />
+  <span class="ui-sr-only">Indeterminate</span>
+</label>
+
+<label class="ui-checkbox">
+  <input name="checkbox-basics" type="checkbox" disabled />
+  <span class="ui-sr-only">Disabled</span>
+</label>
+
+<label class="ui-checkbox">
+  <input name="checkbox-basics" type="checkbox" checked disabled />
+  <span class="ui-sr-only">Checked and disabled</span>
+</label>
+
+<script type="module">
+  import { activateIndeterminate } from "opui-css/css/js/checkbox.js"
+
+  activateIndeterminate()
+</script>
+```
+
+## Astro
+
+`import { Checkbox, CheckboxInput } from "opui-css/astro"`
+
+- `Checkbox` named slots: `end-text`. Fill one with `slot="end-text"` on a child.
+
+### Example: Basics
+
+```astro
+---
+import { Checkbox } from "opui-css/astro"
+---
+
+<Checkbox checked name="checkbox-basics" hideLabel>Checked</Checkbox>
+<Checkbox name="checkbox-basics" hideLabel>Unchecked</Checkbox>
+<Checkbox indeterminate name="checkbox-basics" hideLabel>Indeterminate</Checkbox
+>
+<Checkbox disabled name="checkbox-basics" hideLabel>Disabled</Checkbox>
+<Checkbox checked disabled name="checkbox-basics" hideLabel
+  >Checked and disabled</Checkbox
+>
+```
+
+## React
+
+`import { Checkbox, CheckboxInput } from "opui-css/react"`
+
+- `Checkbox` slot props (`ReactNode`): `children` and `endText`.
+- Client components (`"use client"`): `CheckboxInput`.
+- Hydration: `indeterminate` on `Checkbox` and `CheckboxInput`. A DOM property, set in a layout effect. The server renders `data-indeterminate`, but the box looks unchecked until hydration. Without hydration: Call `activateIndeterminate()` from `opui-css/css/js/checkbox.js`.
+
+### Example: Basics
+
+```tsx
+import { Checkbox } from "opui-css/react"
+
+export default function Basics() {
+  return (
+    <>
+      <Checkbox defaultChecked name="checkbox-basics" hideLabel>
+        Checked
+      </Checkbox>
+      <Checkbox name="checkbox-basics" hideLabel>
+        Unchecked
+      </Checkbox>
+      <Checkbox indeterminate name="checkbox-basics" hideLabel>
+        Indeterminate
+      </Checkbox>
+      <Checkbox disabled name="checkbox-basics" hideLabel>
+        Disabled
+      </Checkbox>
+      <Checkbox defaultChecked disabled name="checkbox-basics" hideLabel>
+        Checked and disabled
+      </Checkbox>
+    </>
+  )
+}
+```
+
+## Svelte
+
+`import { Checkbox, CheckboxInput } from "opui-css/svelte"`
+
+- `Checkbox` slot snippets: `children` and `endText`.
+- Hydration: `bind:checked` and `bind:group` on `Checkbox` and `CheckboxInput`. The bound value only updates on the client. The native control still changes and submits with its form. Without hydration: Read the value from the form instead.
+- Hydration: `indeterminate` on `Checkbox` and `CheckboxInput`. A DOM property, set in an `{@attach}`. The server renders `data-indeterminate`, but the box looks unchecked until hydration. Without hydration: Call `activateIndeterminate()` from `opui-css/css/js/checkbox.js`.
+
+### Example: Basics
+
+```svelte
+<script lang="ts">
+  import { Checkbox } from "opui-css/svelte"
+</script>
+
+<Checkbox checked name="checkbox-basics" hideLabel>Checked</Checkbox>
+<Checkbox name="checkbox-basics" hideLabel>Unchecked</Checkbox>
+<Checkbox indeterminate name="checkbox-basics" hideLabel>Indeterminate</Checkbox
+>
+<Checkbox disabled name="checkbox-basics" hideLabel>Disabled</Checkbox>
+<Checkbox checked disabled name="checkbox-basics" hideLabel
+  >Checked and disabled</Checkbox
+>
+```
+
+## Vue
+
+`import { Checkbox, CheckboxInput } from "opui-css/vue"`
+
+- `Checkbox` named slots: `end-text`. Fill one with `<template #end-text>`.
+- Hydration: `indeterminate` on `Checkbox` and `CheckboxInput`. A DOM property, set in `watchPostEffect`. The server renders `data-indeterminate`, but the box looks unchecked until hydration. Without hydration: Call `activateIndeterminate()` from `opui-css/css/js/checkbox.js`.
+- Hydration: `v-model` on `Checkbox` and `CheckboxInput`. The bound value only updates on the client. The native control still changes and submits with its form. Without hydration: Read the value from the form instead.
+
+### Example: Basics
+
+```vue
+<script setup lang="ts">
+import { Checkbox } from "opui-css/vue"
+</script>
+
+<template>
+  <Checkbox checked name="checkbox-basics" hideLabel>Checked</Checkbox>
+  <Checkbox name="checkbox-basics" hideLabel>Unchecked</Checkbox>
+  <Checkbox indeterminate name="checkbox-basics" hideLabel
+    >Indeterminate</Checkbox
+  >
+  <Checkbox disabled name="checkbox-basics" hideLabel>Disabled</Checkbox>
+  <Checkbox checked disabled name="checkbox-basics" hideLabel
+    >Checked and disabled</Checkbox
+  >
+</template>
+```

package/skills/opui/references/chip.md

@@ -0,0 +1,135 @@
+# Chip
+
+Chips are compact elements that represent an input, attribute, or action. Use them for filters, tags and choices. For the main action, like Save or Send, use a Button.
+
+- CSS: `opui-css/css/components/chip.css`.
+- Full docs with every example: [HTML](https://open-props-ui.netlify.app/html/components/chip.md), [Astro](https://open-props-ui.netlify.app/astro/components/chip.md), [React](https://open-props-ui.netlify.app/react/components/chip.md), [Svelte](https://open-props-ui.netlify.app/svelte/components/chip.md), [Vue](https://open-props-ui.netlify.app/vue/components/chip.md).
+
+## Chip
+
+### Parts
+
+- `.ui-chip` (root): Container element. Can be a `<div>`, `<a>` or `<button>`.
+- `<svg>` (slot `start`): Optional content at the start, such as an icon.
+- `.ui-chip > .ui-text` (prop `label`, slot `label`): The label, text or rich content.
+- `<svg>` (slot `end`): Optional content at the end, such as an icon.
+
+### Props and modifiers
+
+- `as`: `"a" | "button" | "div"`, default `"div"`. The element to render. Defaults to `"a"` with `href`.
+- `disabled`: `boolean`. Disables a button chip. A link chip drops its `href` and gets `aria-disabled="true"` instead.
+- `dot`: `boolean`, `.ui-dot`. Adds a leading dot in the chip's color. `critical`, `warning` and `neutral` shape it.
+- `href`: `string`. The link to use. Renders an `<a>`.
+- `multiline`: `boolean`, `.ui-multiline`. Lets the label wrap to multiple lines.
+- Pressed (HTML): `[aria-pressed="true"]`. Fills a pressed button chip with `--ui-selected`, or `--ui-primary`, for a filter or a choice.
+- `severity`: `"critical"` (`.ui-critical`), `"info"` (`.ui-info`), `"neutral"` (`.ui-neutral`), `"success"` (`.ui-success`), `"warning"` (`.ui-warning`). The severity of a status chip. It tints the chip, and colors and shapes its dot.
+- `size`: `"large"` (`.ui-large`), `"medium"` (default), `"small"` (`.ui-small`), `"x-small"` (`.ui-x-small`). The size of the element.
+- State (HTML): `button` (`button[disabled]`), `link` (`a[aria-disabled="true"]`), `static` (`.ui-disabled`). Disables a button chip. A link chip, which can't take `disabled`, drops its `href` and takes `aria-disabled="true"` instead. A static chip can't be disabled; `.ui-disabled` gives it an inactive look without announcing a state.
+- `variant`: `"outlined"` (`.ui-outlined`), `"tonal"` (default). The variant to use.
+
+## Component properties
+
+Set inputs on the component, inline or in your CSS. Outputs follow the variant and state, so never override them.
+
+### chip.css
+
+- `--_font-size`: The font size. `.ui-large` sets it.
+- `--_icon-padding-inline`: Inline padding on the side of a leading or trailing `svg`. `.ui-large` sets it.
+- `--_icon-size`: Width of an `svg`. `.ui-large` sets it.
+- `--_padding-inline`: The inline padding. `.ui-large` sets it.
+- `--_pressed-bg-color`: Background of a button chip with `aria-pressed="true"`. `--ui-selected` when the theme sets it, otherwise `--ui-primary`.
+- `--_size`: The height. Defaults to `--ui-chip-size`, set by the size classes.
+
+Outputs: `--_accent`, `--_bg-color`, `--_border-color`, `--_dot-bg-color` and `--_text-color`.
+
+## Theme tokens
+
+The stylesheets read `--ui-border-color`, `--ui-border-width`, `--ui-border-width-thick`, `--ui-chip-radius`, `--ui-chip-size`, `--ui-chip-size-large`, `--ui-chip-size-small`, `--ui-chip-size-x-small`, `--ui-control-border-color`, `--ui-control-border-color-filled`, `--ui-critical`, `--ui-disabled-opacity`, `--ui-font-size-caption`, `--ui-font-size-small`, `--ui-icon-size`, `--ui-icon-size-small`, `--ui-info`, `--ui-neutral`, `--ui-on-primary`, `--ui-on-selected`, `--ui-palette-accent`, `--ui-palette-border`, `--ui-palette-strong`, `--ui-palette-tint-subtle`, `--ui-primary`, `--ui-radius`, `--ui-radius-round`, `--ui-selected`, `--ui-shadow-control`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-success`, `--ui-surface`, `--ui-surface-tonal`, `--ui-surface-tonal-hover`, `--ui-text`, `--ui-text-disabled`, `--ui-text-strong` and `--ui-warning`. `theming.md` and `tokens.json` describe them.
+
+## HTML
+
+### Example: Variants
+
+```html
+<div class="ui-chip">
+  <span class="ui-text">Tonal</span>
+</div>
+
+<div class="ui-chip ui-outlined">
+  <span class="ui-text">Outlined</span>
+</div>
+```
+
+## Astro
+
+`import { Chip } from "opui-css/astro"`
+
+- `Chip` named slots: `end`, `label` and `start`. Fill one with `slot="end"` on a child.
+
+### Example: Variants
+
+```astro
+---
+import { Chip } from "opui-css/astro"
+---
+
+<Chip variant="tonal" label="Tonal" />
+<Chip variant="outlined" label="Outlined" />
+```
+
+## React
+
+`import { Chip } from "opui-css/react"`
+
+- `Chip` slot props (`ReactNode`): `end`, `label` and `start`.
+
+### Example: Variants
+
+```tsx
+import { Chip } from "opui-css/react"
+
+export default function Variants() {
+  return (
+    <>
+      <Chip variant="tonal" label="Tonal" />
+      <Chip variant="outlined" label="Outlined" />
+    </>
+  )
+}
+```
+
+## Svelte
+
+`import { Chip } from "opui-css/svelte"`
+
+- `Chip` slot snippets: `end`, `label` and `start`.
+
+### Example: Variants
+
+```svelte
+<script lang="ts">
+  import { Chip } from "opui-css/svelte"
+</script>
+
+<Chip variant="tonal" label="Tonal" />
+<Chip variant="outlined" label="Outlined" />
+```
+
+## Vue
+
+`import { Chip } from "opui-css/vue"`
+
+- `Chip` named slots: `end`, `label` and `start`. Fill one with `<template #end>`.
+
+### Example: Variants
+
+```vue
+<script setup lang="ts">
+import { Chip } from "opui-css/vue"
+</script>
+
+<template>
+  <Chip variant="tonal" label="Tonal" />
+  <Chip variant="outlined" label="Outlined" />
+</template>
+```