@oddkin/components 0.0.0-stage → 1.0.0-beta.0

package/agent/references/components/odd-tooltip.md

@@ -0,0 +1,90 @@
+# `<odd-tooltip>` (OddkinTooltip)
+
+Package `@oddkin/components` 1.0.0-beta.0 · category Overlays. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A short description of the control it is anchored to, shown while the pointer rests on the
+control or the control has focus. It stays while the pointer is over the control or the tooltip,
+and until Escape (WCAG 1.4.13). It describes the control and is never its name.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/tooltip';`
+- Class: `import { OddkinTooltip } from '@oddkin/components/tooltip';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `anchor` | `anchor` | string | '' | The ID of the element it describes and is placed against, in the same document or shadow root. |
+| `side` | `side` | "inline-end" \| "inline-start" \| "block-end" \| "block-start" | 'block-start' | The side of the anchor it shows on, in the anchor's writing direction; it flips when there is more room on the other side. |
+| `align` | `align` | "center" \| "start" \| "end" | 'center' | How it lines up with the anchor along that side. |
+| `open` | `open` (reflects) | boolean | false | Whether it is shown. |
+| `anchorElement` | none: assign as a property | Element \| null |  | The element it describes, when it is not found by `anchor` (another tree, or no ID). |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `show()` | Shows it. |
+| `close()` | Hides it. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The text: a short phrase, nothing interactive. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The text, inside the surface. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-tooltip-max-inline-size` | The widest it grows before its text wraps. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: A short hint about a control: what an icon button does, a keyboard shortcut. (src/tooltip/tooltip.ts:28)
+- Not for: Content to read at length or interact with (use odd-popover); a control's only name (use its label). (src/tooltip/tooltip.ts:29)
+- Accessibility: A `tooltip` that describes its anchor: a native anchor gets its `id` in `aria-describedby` (an `id` is generated when it has none); an Oddkin control adds its text to its inner control's description. Give the anchor its own name. It takes no focus. (src/tooltip/tooltip.ts:25)
+- Keyboard: Focus on the anchor shows it; Escape hides it until the anchor is hovered or focused again. (src/tooltip/tooltip.ts:26)
+
+## Examples
+
+- `example:odd-tooltip/default` in src/tooltip/tooltip.examples.ts (package source), preview roles role:tooltip
+- `example:odd-tooltip/inlineEnd` in src/tooltip/tooltip.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-tooltip/physicalSide` produces `usage.attribute.value`; correct: `example:odd-tooltip/inlineEnd`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-tooltip-max-inline-size`
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`
+
+## Verified
+
+- 24 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/components/test/contract.browser.test.ts, 2026-10-28)

package/agent/references/components/odd-tree.md

@@ -0,0 +1,99 @@
+# `<odd-tree>` (OddkinTree)
+
+Package `@oddkin/components` 1.0.0-beta.0 · category Collections. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A hierarchy the user browses and selects in (APG tree view): rows of items that expand and
+collapse, from `items`. Items holding a selected item start expanded. Children of a `lazy` item
+load when it first expands: listen to `odd-toggle`, then assign new `items` in which that item
+has `children`.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/tree';`
+- Class: `import { OddkinTree } from '@oddkin/components/tree';`
+- Dependency (icon): `<odd-icon>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | Names the tree. |
+| `items` | none: assign as a property | readonly TreeItemRecord[] \| undefined | undefined | The top-level items; each may hold `children`, or be `lazy`. |
+| `expanded` | none: assign as a property | readonly string[] \| undefined | undefined | Ids of expanded items, owned by the caller. Omit it to let the element track expansion. |
+| `value` | `value` | string | '' | Id of the selected item. |
+| `values` | none: assign as a property | readonly string[] \| undefined | undefined | Ids of the selected items with `multiple`. |
+| `multiple` | `multiple` (reflects) | boolean | false | Several items can be selected. |
+| `loading` | `loading` (reflects) | boolean | false | Shows a busy row and marks the tree busy. |
+| `strings` | none: assign as a property | Partial<{ loading: string; empty: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-toggle` | CustomEvent<NavigationToggleDetail> | user (authored) | An item is about to expand or collapse; cancelable. Load the children of a lazy item here. |
+| `input` | CustomEvent | user (authored) | The user selected an item (`value`, or `values` with `multiple`). |
+| `change` | CustomEvent | user (authored) | Dispatched after `input` for each user selection (native `change` is not composed). |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| `empty` | Shown when there are no items and nothing is loading (default `strings.empty`). |
+| `status` | Status content such as an error and a retry button. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The surface. |
+| `empty` | The wrapper of the empty slot. |
+| `item` | Each row (`role="treeitem"`). |
+| `loading` | The busy row while `loading`. |
+| `tree` | The `role="tree"` list of rows. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Browsing and choosing in nested data: files, folders, categories, an outline. (src/tree/tree.ts:49)
+- Not for: Site navigation (use odd-side-nav); a flat list of choices (use odd-listbox); content sections (use odd-disclosure). (src/tree/tree.ts:50)
+- Accessibility: A `tree` named by `label`, `aria-multiselectable` with `multiple`, `aria-busy` while loading. Each row is a `treeitem` with `aria-level`, `aria-setsize`, `aria-posinset`, `aria-expanded` when it has children, `aria-selected`, and `aria-busy` while its lazy children load. Selection is marked by a bar and weight, not colour alone. Disabled rows are skipped by the keyboard. (src/tree/tree.ts:46)
+- Keyboard: Tab reaches the selected row (or the first). Up and Down move between shown rows; Home and End go to the first and last. Right expands a closed row, or moves into an open one; Left collapses an open row, or moves to its parent (mirrored right to left). `*` expands every sibling. Enter or Space selects (with `multiple`, toggles). Typing moves to the next row whose label starts with the typed characters. (src/tree/tree.ts:47)
+
+## Examples
+
+- `example:odd-tree/collapsed` in src/tree/tree.examples.ts (package source)
+- `example:odd-tree/default` in src/tree/tree.examples.ts (package source), preview roles role:tree
+- `example:odd-tree/empty` in src/tree/tree.examples.ts (package source)
+- `example:odd-tree/error` in src/tree/tree.examples.ts (package source)
+- `example:odd-tree/lazy` in src/tree/tree.examples.ts (package source)
+- `example:odd-tree/loading` in src/tree/tree.examples.ts (package source)
+- `example:odd-tree/multiple` in src/tree/tree.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-tree/itemsAttribute` produces `usage.attribute.propertyOnly`; correct: `example:odd-tree/default`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`
+
+## Verified
+
+- 38 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/components/test/contract.browser.test.ts, 2026-10-28)

package/agent/references/components/odd-validation-summary.md

@@ -0,0 +1,84 @@
+# `<odd-validation-summary>` (OddkinValidationSummary)
+
+Package `@oddkin/components` 1.0.0-beta.0 · category Forms. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Lists a form's problems after a submission that validation blocked: a heading with the count,
+then each invalid control's label and message as a link that moves focus to the control. It
+takes focus when it appears, shrinks as fields are fixed, and hides once the form is valid.
+Entered values are never cleared.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/validation-summary';`
+- Class: `import { OddkinValidationSummary } from '@oddkin/components/validation-summary';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | The heading; default `strings.title`, "Please fix {count} fields". |
+| `form` | `form` | string | '' | ID of the form it reports on; default: the ancestor form. |
+| `strings` | none: assign as a property | Partial<{ title: string; titleOne: string; entry: string; }> \| undefined | undefined | Localized string overrides: `title`, `titleOne` (one problem), `entry`. |
+
+## Events
+
+None.
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The surface; takes focus when the summary appears. |
+| `label` | The heading. |
+| `link` | A problem: the control's label and message, linking to the control. |
+| `list` | The list of problems. |
+| `marker` | The danger glyph. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Forms with several fields, where a failed submission should say what to fix in one place. (src/validation-summary/validation-summary.ts:73)
+- Not for: One field's error (use the field's `error`); a failed save after a valid submission (use odd-alert). (src/validation-summary/validation-summary.ts:74)
+- Accessibility: A `role="group"` named by its heading. After a blocked submission it receives focus (`tabindex="-1"`), so the heading and the problems are read first; each link moves focus to its control. The browser's own validation bubbles are not shown while the summary reports the problems. (src/validation-summary/validation-summary.ts:70)
+- Keyboard: Tab moves through the links; Enter on a link moves focus to that control. (src/validation-summary/validation-summary.ts:71)
+- Limitations: It reports submissions the user starts inside the form (a click on a submit button there, or Enter in a field). `form.requestSubmit()` and `form.checkValidity()` called by a script, and a submit button outside the form (its `form` attribute), leave it hidden. A form with `novalidate` is never blocked, so the summary never shows. (src/validation-summary/validation-summary.ts:75)
+- Limitations: The form is found when the summary connects or its `form` attribute changes: the ancestor form, or the form with that ID in the same document or shadow root. (src/validation-summary/validation-summary.ts:76)
+
+## Examples
+
+- `example:odd-validation-summary/default` in src/validation-summary/validation-summary.examples.ts (package source), preview roles role:validationSummary
+- `example:odd-validation-summary/externalForm` in src/validation-summary/validation-summary.examples.ts (package source)
+- `example:odd-validation-summary/heading` in src/validation-summary/validation-summary.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-validation-summary/forAttribute` produces `usage.attribute.unknown`; correct: `example:odd-validation-summary/externalForm`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`
+
+## Verified
+
+- 17 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/components/test/contract.browser.test.ts, 2026-10-28)

package/agent/references/composition.md

@@ -0,0 +1,58 @@
+# Interfaces as data: `@oddkin/components/composition`
+
+An interface described as data: published Oddkin elements and native text elements, their attributes and properties, text, and events mapped to action names. Rendered by renderComposition() from @oddkin/components/composition.
+
+## Entry
+
+- `import { validateComposition, renderComposition } from '@oddkin/components/composition';` (never imported by element entries).
+- `validateComposition(document: unknown, options?: { readonly limits?: CompositionLimits; }): CompositionValidation`: Check a composition document; `ok` is false when any diagnostic is an error.
+- `renderComposition(document: unknown, target: ParentNode, options: RenderCompositionOptions): RenderedComposition`: Validate `document`, then append it to `target`; refuse it whole if any check fails.
+
+## Document
+
+- Schema: `@oddkin/components/schemas/composition/composition.v1.json` (`https://oddkin.dev/schemas/composition/composition.v1.json`). Required: `version`, `root`; `version` is `1`.
+- `root` and every `children`: an array of nodes. A node is a string (text) or an object with `element`: a published element (one schema each, below) or a native text element (`p`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `span`, `strong`, `em`, `a`, `ul`, `ol`, `li`).
+- An element object: `element`, optional `id` (The element's id, unique in the document.), `slot` (A named slot of the parent element.), `attributes` (published attributes and properties only), `children`, and `actions`: event name to action name (An action name the host handles, such as "settings.save"; never code.).
+- Values are data: no functions, no markup strings, no styles. The host maps action names to its own handlers.
+
+## Element schemas
+
+54 files in `@oddkin/components/schemas/composition/`: `odd-alert`, `odd-avatar`, `odd-badge`, `odd-breadcrumbs`, `odd-button`, `odd-calendar`, `odd-card`, `odd-carousel`, `odd-checkbox-group`, `odd-checkbox`, `odd-chip`, `odd-color-picker`, `odd-combobox`, `odd-command-palette`, `odd-container`, `odd-copy-button`, `odd-date-picker`, `odd-dialog`, `odd-disclosure`, `odd-drawer`, `odd-empty-state`, `odd-file-input`, `odd-icon`, `odd-input`, `odd-listbox`, `odd-menu`, `odd-one-time-code`, `odd-pagination`, `odd-picker`, `odd-popover`, `odd-progress`, `odd-radio-group`, `odd-rating`, `odd-relative-time`, `odd-scroll-region`, `odd-segmented-control`, `odd-select`, `odd-side-nav`, `odd-skeleton`, `odd-slider`, `odd-spinner`, `odd-split-button`, `odd-split-panel`, `odd-stat`, `odd-status-marker`, `odd-switch`, `odd-tab-panel`, `odd-tabs`, `odd-textarea`, `odd-toast`, `odd-toolbar`, `odd-tooltip`, `odd-tree`, `odd-validation-summary`. Each lists the element's attributes with their types, its slots, and its actions.
+
+## Example (validated when this kit was generated)
+
+```json
+{
+  "$schema": "https://oddkin.dev/schemas/composition/composition.v1.json",
+  "version": 1,
+  "root": [
+    {
+      "element": "odd-card",
+      "attributes": {
+        "label": "Settings"
+      },
+      "children": [
+        {
+          "element": "p",
+          "children": [
+            "Save your changes before leaving."
+          ]
+        },
+        {
+          "element": "odd-button",
+          "slot": "footer",
+          "attributes": {
+            "appearance": "primary"
+          },
+          "children": [
+            "Save"
+          ],
+          "actions": {
+            "click": "settings.save"
+          }
+        }
+      ]
+    }
+  ]
+}
+```

package/agent/references/models/oddkin.navigation.md

@@ -0,0 +1,5 @@
+# Model oddkin.navigation v1
+
+Id `model:oddkin.navigation`. JSON Schema: `@oddkin/components/schemas/oddkin.navigation.v1.json`.
+
+Kinds: `link`, `action`, `group`.

package/agent/references/recipes/alert.md

@@ -0,0 +1,10 @@
+# Recipe alert
+
+Id `recipe:alert`.
+
+| Region | Helper |
+| --- | --- |
+| `alert` | row |
+| `end` | row |
+
+Layers: recipe.base → recipe.variant → recipe.condition.

package/agent/references/recipes/checkbox-group.md

@@ -0,0 +1,13 @@
+# Recipe checkbox-group
+
+Id `recipe:checkbox-group`.
+
+| Region | Helper |
+| --- | --- |
+| `options` | stack |
+
+## Variants
+
+- `orientation`: horizontal
+
+Layers: recipe.base → recipe.variant → recipe.condition.

package/agent/references/recipes/color-picker.md

@@ -0,0 +1,14 @@
+# Recipe color-picker
+
+Id `recipe:color-picker`.
+
+| Region | Helper |
+| --- | --- |
+| `controls` | stack |
+| `entries` | row |
+| `entry` | stack |
+| `swatches` | stack |
+| `swatch-row` | row |
+| `actions` | row |
+
+Layers: recipe.base → recipe.variant → recipe.condition.

package/agent/references/recipes/combobox.md

@@ -0,0 +1,14 @@
+# Recipe combobox
+
+Id `recipe:combobox`.
+
+| Region | Helper |
+| --- | --- |
+| `chips` | row |
+| `count` | row |
+| `avatars` | row |
+| `review-bar` | row |
+| `panel` | stack |
+| `spread` | row |
+
+Layers: recipe.base → recipe.variant → recipe.condition.

package/agent/references/recipes/command-palette.md

@@ -0,0 +1,11 @@
+# Recipe command-palette
+
+Id `recipe:command-palette`.
+
+| Region | Helper |
+| --- | --- |
+| `search` | row |
+| `state` | row |
+| `footer` | row |
+
+Layers: recipe.base → recipe.variant → recipe.condition.

package/agent/references/recipes/empty-state.md

@@ -0,0 +1,10 @@
+# Recipe empty-state
+
+Id `recipe:empty-state`.
+
+| Region | Helper |
+| --- | --- |
+| `empty` | stack |
+| `footer` | row |
+
+Layers: recipe.base → recipe.variant → recipe.condition.

package/agent/references/recipes/listbox.md

@@ -0,0 +1,9 @@
+# Recipe listbox
+
+Id `recipe:listbox`.
+
+| Region | Helper |
+| --- | --- |
+| `state` | row |
+
+Layers: recipe.base → recipe.variant → recipe.condition.

package/agent/references/recipes/progress.md

@@ -0,0 +1,9 @@
+# Recipe progress
+
+Id `recipe:progress`.
+
+| Region | Helper |
+| --- | --- |
+| `head` | row |
+
+Layers: recipe.base → recipe.variant → recipe.condition.

package/agent/references/recipes/radio-group.md

@@ -0,0 +1,14 @@
+# Recipe radio-group
+
+Id `recipe:radio-group`.
+
+| Region | Helper |
+| --- | --- |
+| `options` | stack |
+| `group` | stack |
+
+## Variants
+
+- `orientation`: horizontal
+
+Layers: recipe.base → recipe.variant → recipe.condition.

package/agent/references/recipes/rating.md

@@ -0,0 +1,9 @@
+# Recipe rating
+
+Id `recipe:rating`.
+
+| Region | Helper |
+| --- | --- |
+| `row` | row |
+
+Layers: recipe.base → recipe.variant → recipe.condition.

package/agent/references/recipes/scroll-region.md

@@ -0,0 +1,9 @@
+# Recipe scroll-region
+
+Id `recipe:scroll-region`.
+
+| Region | Helper |
+| --- | --- |
+| `content` | stack |
+
+Layers: recipe.base → recipe.variant → recipe.condition.

package/agent/references/recipes/side-nav.md

@@ -0,0 +1,17 @@
+# Recipe side-nav
+
+Id `recipe:side-nav`. Container `side-nav`.
+
+| Region | Helper |
+| --- | --- |
+| `root` | stack |
+| `header` | row |
+| `content` | stack |
+| `group-items` | stack |
+| `footer` | row |
+
+## Conditions
+
+- `@container side-nav (min-inline-size: 40rem)`
+
+Layers: recipe.base → recipe.variant → recipe.condition.

package/agent/references/recipes/slider.md

@@ -0,0 +1,10 @@
+# Recipe slider
+
+Id `recipe:slider`.
+
+| Region | Helper |
+| --- | --- |
+| `heading` | row |
+| `endpoints` | row |
+
+Layers: recipe.base → recipe.variant → recipe.condition.

package/agent/references/recipes/stat.md

@@ -0,0 +1,10 @@
+# Recipe stat
+
+Id `recipe:stat`.
+
+| Region | Helper |
+| --- | --- |
+| `base` | stack |
+| `context` | row |
+
+Layers: recipe.base → recipe.variant → recipe.condition.

package/agent/references/recipes/tree.md

@@ -0,0 +1,11 @@
+# Recipe tree
+
+Id `recipe:tree`.
+
+| Region | Helper |
+| --- | --- |
+| `root` | stack |
+| `tree` | stack |
+| `state` | row |
+
+Layers: recipe.base → recipe.variant → recipe.condition.

package/agent/references/stylesheets/avatar-group.md

@@ -0,0 +1,13 @@
+# Stylesheet avatar-group
+
+Id `stylesheet:avatar-group`. Import `@oddkin/components/css/avatar-group.css` once per document; its rules are in the `odd.components` layer.
+
+`.odd-avatar-group`: overlapping `odd-avatar` children, each ringed in the page colour; `.odd-avatar-group-more` on the last one for an overflow count ("+3").
+
+## Classes
+
+`.odd-avatar-group`, `.odd-avatar-group-more`
+
+## Tokens read
+
+`border.width.strong`, `color.action.default`, `color.canvas`, `color.text.on-action`, `space.xs`

package/agent/references/stylesheets/base.md

@@ -0,0 +1,9 @@
+# Stylesheet base
+
+Id `stylesheet:base`. Import `@oddkin/components/css/base.css` once per document; its rules are in the `odd.base` layer.
+
+Page defaults from the theme: text, surface, links, code, and the keyboard focus ring.
+
+## Tokens read
+
+`color.canvas`, `color.focus.ring`, `color.link`, `color.text.primary`, `focus.offset`, `focus.width`, `font.family.mono`, `type.body.family`, `type.body.letter-spacing`, `type.body.line-height`, `type.body.size`, `type.body.weight`

package/agent/references/stylesheets/button.md

@@ -0,0 +1,17 @@
+# Stylesheet button
+
+Id `stylesheet:button`. Import `@oddkin/components/css/button.css` once per document; its rules are in the `odd.components` layer.
+
+`<button class="odd-button">`: native buttons that look like `odd-button`, for forms that need native submit-button semantics. Indented one level, as the stylesheet writer expects of templates nested in this module.
+
+## Classes
+
+`.odd-button`
+
+## Variables an author may set
+
+`--odd-button-background`, `--odd-button-border-color`, `--odd-button-color`, `--odd-button-height`, `--odd-button-padding-inline`, `--odd-button-radius`
+
+## Tokens read
+
+`border.width.default`, `color.action.default`, `color.action.hover`, `color.action.pressed`, `color.border.strong`, `color.focus.ring`, `color.selection.background`, `color.selection.foreground`, `color.surface.default`, `color.surface.hover`, `color.surface.sunken`, `color.text.disabled`, `color.text.on-action`, `color.text.primary`, `control.gap`, `control.height.lg`, `control.height.md`, `control.height.sm`, `control.padding.inline.lg`, `control.padding.inline.md`, `control.padding.inline.sm`, `control.radius`, `focus.offset`, `focus.width`, `motion.duration.fast`, `motion.easing.standard`, `space.none`, `target.min`, `type.body.size`, `type.ui.family`, `type.ui.letter-spacing`, `type.ui.line-height`, `type.ui.size`, `type.ui.weight`

package/agent/references/stylesheets/description-list.md

@@ -0,0 +1,17 @@
+# Stylesheet description-list
+
+Id `stylesheet:description-list`. Import `@oddkin/components/css/description-list.css` once per document; its rules are in the `odd.components` layer.
+
+`dl.odd-description-list`: term and value pairs, each pair a `div` row (`<div><dt>…</dt> <dd>…</dd></div>`) divided by rules, with one stable term column for every row (at most `--odd-description-list-term-width`). The list is an inline-size container: below 36rem of its own width each term stacks above its value. A missing value is author text ("Not provided").
+
+## Classes
+
+`.odd-description-list`
+
+## Variables an author may set
+
+`--odd-description-list-term-width`
+
+## Tokens read
+
+`border.width.default`, `color.border.default`, `color.text.primary`, `color.text.secondary`, `space.md`, `space.xs`, `type.body.family`, `type.body.letter-spacing`, `type.body.line-height`, `type.body.size`, `type.body.weight`, `type.ui.family`, `type.ui.letter-spacing`, `type.ui.line-height`, `type.ui.size`, `type.ui.weight`

package/agent/references/stylesheets/divider.md

@@ -0,0 +1,13 @@
+# Stylesheet divider
+
+Id `stylesheet:divider`. Import `@oddkin/components/css/divider.css` once per document; its rules are in the `odd.components` layer.
+
+`hr.odd-divider`, or a labelled `.odd-divider` ("or") the author gives `role="separator"`.
+
+## Classes
+
+`.odd-divider`
+
+## Tokens read
+
+`border.width.default`, `color.border.default`, `color.text.secondary`, `space.md`, `space.sm`, `type.small.family`, `type.small.line-height`, `type.small.size`, `type.small.weight`

package/agent/references/stylesheets/field.md

@@ -0,0 +1,17 @@
+# Stylesheet field
+
+Id `stylesheet:field`. Import `@oddkin/components/css/field.css` once per document; its rules are in the `odd.components` layer.
+
+`.odd-field`: the field anatomy for native and third-party controls (`.odd-field-label`, `.odd-field-description`, `.odd-field-control`, `.odd-field-error`), generated from the rules of Oddkin's form controls, with the same `--odd-field-*` variables. The author wires `<label for>`, `aria-describedby`, and `aria-invalid`.
+
+## Classes
+
+`.odd-field`, `.odd-field-control`, `.odd-field-control-box`, `.odd-field-control-end`, `.odd-field-control-start`, `.odd-field-description`, `.odd-field-error`, `.odd-field-label`
+
+## Variables an author may set
+
+`--odd-field-background`, `--odd-field-border-color`, `--odd-field-height`, `--odd-field-radius`
+
+## Tokens read
+
+`border.width.default`, `color.border.strong`, `color.danger.foreground`, `color.surface.default`, `color.surface.hover`, `color.surface.sunken`, `color.text.disabled`, `color.text.primary`, `color.text.secondary`, `control.gap`, `control.height.md`, `control.padding.inline.md`, `control.radius`, `motion.duration.fast`, `motion.easing.standard`, `space.none`, `space.xs`, `target.min`, `type.body.family`, `type.body.line-height`, `type.body.size`, `type.small.line-height`, `type.small.size`, `type.ui.letter-spacing`, `type.ui.line-height`, `type.ui.size`, `type.ui.weight`

package/agent/references/stylesheets/kbd.md

@@ -0,0 +1,13 @@
+# Stylesheet kbd
+
+Id `stylesheet:kbd`. Import `@oddkin/components/css/kbd.css` once per document; its rules are in the `odd.components` layer.
+
+`kbd.odd-kbd`: a key cap that does not look clickable; sequences are adjacent keys.
+
+## Classes
+
+`.odd-kbd`
+
+## Tokens read
+
+`border.width.default`, `color.border.default`, `color.surface.default`, `color.text.secondary`, `radius.sm`, `space.2xs`, `type.code.family`, `type.code.line-height`, `type.code.size`, `type.code.weight`