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

package/agent/llms.txt

@@ -0,0 +1,118 @@
+# @oddkin/components 1.0.0-beta.1
+
+> Themed custom elements, Oddkin layout presets, and component metadata.
+
+The agent kit for this installed version, generated from its published metadata. Read GUIDE.md first.
+
+## Guide
+
+- [GUIDE.md](GUIDE.md): install, register, the components by category, and the rules
+- [choosing](references/choosing-components.md)
+- [tokens:component](references/tokens/component.md)
+- [tokens:foundation](references/tokens/foundation.md)
+- [tokens:layout](references/tokens/layout.md)
+- [tokens:reference](references/tokens/reference.md)
+- [tokens:semantic](references/tokens/semantic.md)
+- [recipe:alert](references/recipes/alert.md)
+- [recipe:breadcrumbs](references/recipes/breadcrumbs.md)
+- [recipe:calendar](references/recipes/calendar.md)
+- [recipe:checkbox-group](references/recipes/checkbox-group.md)
+- [recipe:color-picker](references/recipes/color-picker.md)
+- [recipe:combobox](references/recipes/combobox.md)
+- [recipe:command-palette](references/recipes/command-palette.md)
+- [recipe:dialog](references/recipes/dialog.md)
+- [recipe:disclosure](references/recipes/disclosure.md)
+- [recipe:empty-state](references/recipes/empty-state.md)
+- [recipe:file-input](references/recipes/file-input.md)
+- [recipe:listbox](references/recipes/listbox.md)
+- [recipe:pagination](references/recipes/pagination.md)
+- [recipe:progress](references/recipes/progress.md)
+- [recipe:radio-group](references/recipes/radio-group.md)
+- [recipe:rating](references/recipes/rating.md)
+- [recipe:scroll-region](references/recipes/scroll-region.md)
+- [recipe:side-nav](references/recipes/side-nav.md)
+- [recipe:slider](references/recipes/slider.md)
+- [recipe:stat](references/recipes/stat.md)
+- [recipe:toolbar](references/recipes/toolbar.md)
+- [recipe:tree](references/recipes/tree.md)
+- [recipe:validation-summary](references/recipes/validation-summary.md)
+- [stylesheet:avatar-group](references/stylesheets/avatar-group.md)
+- [stylesheet:base](references/stylesheets/base.md)
+- [stylesheet:button](references/stylesheets/button.md)
+- [stylesheet:description-list](references/stylesheets/description-list.md)
+- [stylesheet:divider](references/stylesheets/divider.md)
+- [stylesheet:field](references/stylesheets/field.md)
+- [stylesheet:kbd](references/stylesheets/kbd.md)
+- [stylesheet:layout](references/stylesheets/layout.md)
+- [stylesheet:link](references/stylesheets/link.md)
+- [stylesheet:list](references/stylesheets/list.md)
+- [stylesheet:reset](references/stylesheets/reset.md)
+- [stylesheet:stepper](references/stylesheets/stepper.md)
+- [stylesheet:table](references/stylesheets/table.md)
+- [stylesheet:timeline](references/stylesheets/timeline.md)
+- [stylesheet:typography](references/stylesheets/typography.md)
+- [stylesheet:utilities](references/stylesheets/utilities.md)
+- [model:oddkin.navigation](references/models/oddkin.navigation.md)
+- [composition](references/composition.md)
+
+## Components
+
+- [odd-alert](references/components/odd-alert.md): A persistent inline message about the page or a region: a tone glyph, a title, a message, and optional actions.
+- [odd-avatar](references/components/odd-avatar.md): A person or group marker: a picture (`src`) or, without one or when it fails to load, the initials of `label`.
+- [odd-badge](references/components/odd-badge.md): A passive status or count: words with a tone colour and a glyph, so the meaning never rests on colour alone.
+- [odd-breadcrumbs](references/components/odd-breadcrumbs.md): A location trail: links to the pages above this one, then the current page as text.
+- [odd-button](references/components/odd-button.md): A button for actions.
+- [odd-calendar](references/components/odd-calendar.md): A month of dates to choose one from: the WAI-ARIA date grid, with the month and buttons to the months before and after above it, and Today and Clear below.
+- [odd-card](references/components/odd-card.md): A surface that groups related content, with optional header and footer.
+- [odd-carousel](references/components/odd-carousel.md): A carousel (APG carousel, manual only): one slide at a time, with previous and next, the position, and a button per slide.
+- [odd-checkbox](references/components/odd-checkbox.md): A checkbox that participates in forms like a native one: a native checkbox in the shadow root, drawn by the shared control-indicator module, labelled by the slotted text.
+- [odd-checkbox-group](references/components/odd-checkbox-group.md): A named group of `odd-checkbox` choices with one legend, description, and error.
+- [odd-chip](references/components/odd-chip.md): A compact token for a value, filter, or tag, with an explicit remove button when `removable`.
+- [odd-color-picker](references/components/odd-color-picker.md): One colour, typed as hex or chosen in a popup: a saturation-and-brightness area, a hue slider, hex and opacity entry, the RGB values, and suggested swatches, applied or cancelled.
+- [odd-combobox](references/components/odd-combobox.md): An editable input with a popup listbox (APG combobox, list autocomplete): typing filters the options and the first match becomes active; Enter or a click chooses.
+- [odd-command-palette](references/components/odd-command-palette.md): A command palette: a modal dialog with a search input and the matching commands below it (APG combobox with a listbox popup that is always shown).
+- [odd-container](references/components/odd-container.md): A content measure and an inline-size container: container queries and layout recipe conditions inside it resolve against its width, not the viewport's.
+- [odd-copy-button](references/components/odd-copy-button.md): A button that copies text to the clipboard: `value`, or the form value or text of the element named by `from`.
+- [odd-date-picker](references/components/odd-date-picker.md): One date, typed in the page language's numeric order or chosen from a calendar in a popup: the WAI-ARIA date picker dialog.
+- [odd-dialog](references/components/odd-dialog.md): A modal dialog: a native `<dialog>` shown modally, so the rest of the page is inert until it closes.
+- [odd-disclosure](references/components/odd-disclosure.md): One trigger that shows or hides one related region: a native `<details>` and `<summary>`.
+- [odd-drawer](references/components/odd-drawer.md): A panel at an inline edge of the viewport: odd-dialog with a side-sheet layout.
+- [odd-empty-state](references/components/odd-empty-state.md): Explains why a region is empty and offers the next useful step: first use, no results, nothing left to do.
+- [odd-file-input](references/components/odd-file-input.md): A file chooser over a native `<input type="file">`: a drop zone with a title, the help text, the browser's own picker button, and the chosen files as rows with their size and a remove button.
+- [odd-icon](references/components/odd-icon.md): An icon drawn in the current text colour: an SVG file by URL (`src`), or an inline `<svg>` placed inside.
+- [odd-input](references/components/odd-input.md): A labelled single-line text field that participates in forms like a native input.
+- [odd-listbox](references/components/odd-listbox.md): Persistent choices in a form (APG listbox): the listbox keeps focus and the active option is its `aria-activedescendant`.
+- [odd-menu](references/components/odd-menu.md): A menu button (APG): a button that opens a menu of actions, with groups, separators, and submenus.
+- [odd-one-time-code](references/components/odd-one-time-code.md): A one-time code (a verification code sent by text message or email) entered into `maxlength` cells (default six).
+- [odd-pagination](references/components/odd-pagination.md): Page navigation: the position as text, previous and next, and the first, last, and nearby pages with ellipses between.
+- [odd-picker](references/components/odd-picker.md): A field that opens a list or a hierarchy to choose from (APG select-only combobox): a popup listbox of options, or, with `items`, a popup tree whose rows expand and collapse without selecting.
+- [odd-popover](references/components/odd-popover.md): A non-modal surface anchored to the control that opens it.
+- [odd-progress](references/components/odd-progress.md): Progress of a task.
+- [odd-radio-group](references/components/odd-radio-group.md): One value from a short set of visible options, each a native radio with its label and description.
+- [odd-rating](references/components/odd-rating.md): A score from one to `max` stars (default five), with the chosen value beside the stars ("3 of 5"): the radio-group behavior drawn as stars, each filled up to the chosen one.
+- [odd-relative-time](references/components/odd-relative-time.md): A date and time said relative to now ("3 hours ago", "in 2 days", "now") in the page's language, as a `<time>` that keeps the exact value; the absolute date and time is its tooltip, and with `detail` it is shown as well.
+- [odd-scroll-region](references/components/odd-scroll-region.md): Content that scrolls on its own inside a page, reachable and scrollable from the keyboard (WCAG 2.1.1).
+- [odd-segmented-control](references/components/odd-segmented-control.md): One value from a few short options, drawn as joined segments: the radio-group behavior with a segmented look.
+- [odd-select](references/components/odd-select.md): A compact choice of one option in a form: a styled native `<select>`, so the engine's own picker, keyboard, and assistive-technology support come with it.
+- [odd-side-nav](references/components/odd-side-nav.md): Side navigation: links, actions, and expandable groups from `.items` (or native links in the default slot), arranged by the `side-nav` layout recipe, which responds to the element's own width with container queries only.
+- [odd-skeleton](references/components/odd-skeleton.md): A content-shaped placeholder while a region loads.
+- [odd-slider](references/components/odd-slider.md): A number from a bounded range, chosen by dragging a thumb along a track or with the keys, with the current value and both endpoints shown.
+- [odd-spinner](references/components/odd-spinner.md): An indeterminate busy indicator with a status label.
+- [odd-split-button](references/components/odd-split-button.md): A primary action with a menu of related actions beside it: two independent targets in one element, a primary button and a menu button (odd-menu, whose parts it forwards).
+- [odd-split-panel](references/components/odd-split-panel.md): Two panes side by side or stacked, with a separator the user drags or moves with the keyboard (APG window splitter).
+- [odd-stat](references/components/odd-stat.md): One metric: its `label`, its `value`, and the context in the default slot ("+8.2% this month").
+- [odd-status-marker](references/components/odd-status-marker.md): The status marker of a timeline event or a step (Figma's Event marker and Step status): a circle with the built-in glyph for `status`, or its own content (a step number) while idle.
+- [odd-switch](references/components/odd-switch.md): An on/off setting that participates in forms like a checkbox: a native checkbox with `role="switch"` in the shadow root, drawn as a track and thumb, labelled by the slotted text.
+- [odd-tab-panel](references/components/odd-tab-panel.md): One panel of `odd-tabs`: its tab's text, its value, and the content shown while its tab is selected.
+- [odd-tabs](references/components/odd-tabs.md): Tabs that switch between related panels (APG tabs).
+- [odd-textarea](references/components/odd-textarea.md): A labelled multi-line text field that participates in forms like a native textarea, with a character count while `maxlength` is set.
+- [odd-toast](references/components/odd-toast.md): A short message about something that just happened, at the block-end and inline-end corner of the viewport: a tone glyph, a title, the message, an optional action, and a close button.
+- [odd-toolbar](references/components/odd-toolbar.md): A named group of controls with one Tab stop (APG toolbar): arrow keys move focus among the slotted controls, which stay the author's own elements.
+- [odd-tooltip](references/components/odd-tooltip.md): A short description of the control it is anchored to, shown while the pointer rests on the control or the control has focus.
+- [odd-tree](references/components/odd-tree.md): A hierarchy the user browses and selects in (APG tree view): rows of items that expand and collapse, from `items`.
+- [odd-validation-summary](references/components/odd-validation-summary.md): 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.
+
+## Optional
+
+- [oddkin.metadata.json](../oddkin.metadata.json): every component, recipe, stylesheet, and model by stable id
+- [custom-elements.json](../custom-elements.json): the custom elements manifest

package/agent/references/choosing-components.md

@@ -0,0 +1,192 @@
+# Choosing components in @oddkin/components
+
+From authored `@useFor`, `@notFor`, and `@category`.
+
+## Actions
+
+- `<odd-button>`
+  - Use for: Triggering an action, or submitting or resetting the form it belongs to (its ancestor form or the one named by `form`).
+  - Not for: Navigation to another page; use a link.
+- `<odd-command-palette>`
+  - Use for: Finding and running any command or destination by name, from anywhere in an app (typically opened with Ctrl+K or Cmd+K).
+  - Not for: A few actions behind a button (use odd-menu); choosing a value in a form (use odd-combobox); site search results (use a page).
+- `<odd-copy-button>`
+  - Use for: Copying an identifier, a code snippet, a link, or a key that people paste elsewhere.
+  - Not for: Copying rich content or files; a share action (use the page's share flow).
+- `<odd-menu>`
+  - Use for: A short list of actions behind one button: row actions, "more" actions, create menus.
+  - Not for: Choosing a value in a form (use odd-select or odd-listbox); navigation between pages (use links or odd-side-nav); a searchable list of commands (use odd-command-palette).
+- `<odd-split-button>`
+  - Use for: A frequent action with a few alternatives: "Save" with "Save as" and "Save a copy", "Merge" with merge strategies.
+  - Not for: Unrelated actions (use separate buttons or odd-toolbar); only a list of actions (use odd-menu).
+- `<odd-toolbar>`
+  - Use for: Several related actions or formatting controls used together, such as above a table or an editor.
+  - Not for: A single action or two (place buttons directly); navigation (use links or odd-side-nav); a menu of commands (use odd-menu).
+
+## Collections
+
+- `<odd-tree>`
+  - Use for: Browsing and choosing in nested data: files, folders, categories, an outline.
+  - Not for: Site navigation (use odd-side-nav); a flat list of choices (use odd-listbox); content sections (use odd-disclosure).
+
+## Containers
+
+- `<odd-card>`
+  - Use for: Grouping related content and actions into one visual unit.
+  - Not for: Page layout; use layout recipes. A whole clickable card; put a link or button inside.
+
+## Display
+
+- `<odd-avatar>`
+  - Use for: Identifying people in lists, comments, assignments, and member groups.
+  - Not for: Product or file images; decorative illustrations.
+- `<odd-chip>`
+  - Use for: Selected values, applied filters, and tags that can be removed.
+  - Not for: Actions (use a button); status (use a badge).
+- `<odd-icon>`
+  - Use for: Pictograms beside text, or alone with `label`.
+  - Not for: The only name of a control (give the control its own label); decoration that belongs in CSS.
+- `<odd-relative-time>`
+  - Use for: When something happened or will happen, where closeness matters more than the exact time: activity, comments, updates.
+  - Not for: Exact times that people compare or copy (show the absolute date); a running countdown.
+- `<odd-stat>`
+  - Use for: A key figure on a dashboard or summary: a count, a total, a rate, with its change.
+  - Not for: Progress toward a goal (use a progress bar); several figures compared side by side (use a table or chart).
+- `<odd-status-marker>`
+  - Use for: Timeline events and steps, inside the `.odd-timeline` and `.odd-stepper` recipes.
+  - Not for: Status on its own (use a badge, which carries words); a progress value (use a progress bar).
+
+## Feedback
+
+- `<odd-alert>`
+  - Use for: Errors and warnings that affect a page or region, confirmations that must stay visible.
+  - Not for: Field errors (use the field's `error`); passing results (a toast); counts and labels (use odd-badge).
+- `<odd-badge>`
+  - Use for: Short status labels and counts next to the thing they describe.
+  - Not for: Actions or filters (use a button); messages that need attention (use an alert).
+- `<odd-empty-state>`
+  - Use for: Empty lists, tables, and searches with no results.
+  - Not for: Errors (use odd-alert); loading (use odd-skeleton or odd-spinner).
+- `<odd-progress>`
+  - Use for: Uploads, imports, and other work with a measurable amount.
+  - Not for: Work of unknown length in a small space (use odd-spinner); a measurement within a known range such as disk usage.
+- `<odd-skeleton>`
+  - Use for: Regions whose layout is known before their content: lists, cards, avatars with text.
+  - Not for: Waiting with no known layout (use odd-spinner); progress of a task (use odd-progress).
+- `<odd-spinner>`
+  - Use for: Waiting of unknown length: loading a region, saving.
+  - Not for: Known progress (use odd-progress); content-shaped placeholders (use odd-skeleton).
+
+## Forms
+
+- `<odd-calendar>`
+  - Use for: Choosing one date where the month view helps: a booking, a due date, a day in a schedule.
+  - Not for: A memorable date such as a birth date (use odd-input type="date" or separate fields); a date and time (use odd-input type="datetime-local"); a range of dates.
+- `<odd-checkbox>`
+  - Use for: A single yes-or-no choice, or one option among several that can each be on or off.
+  - Not for: An immediate on/off setting (use odd-switch); one choice among several (use odd-radio-group).
+- `<odd-checkbox-group>`
+  - Use for: Several independent choices under one question, such as notification channels.
+  - Not for: One choice among several (use odd-radio-group); a single yes-or-no choice (use odd-checkbox).
+- `<odd-color-picker>`
+  - Use for: A colour the user chooses for their own content: a layer, a label, a highlight.
+  - Not for: Theme colours (use design tokens); one colour from a short fixed set (use odd-radio-group or odd-segmented-control).
+- `<odd-combobox>`
+  - Use for: Choosing from a long list by typing: people, projects, countries; several values with `multiple`.
+  - Not for: A short list (use odd-select or odd-radio-group); free text with suggestions only (use odd-input); commands (use odd-command-palette).
+- `<odd-date-picker>`
+  - Use for: One date the user may know and type, or prefer to find in a month: a booking, a due date, a publish date.
+  - Not for: A memorable date such as a birth date (separate fields, or odd-input type="date"); a date and time (odd-input type="datetime-local"); a range of dates; an inline month to choose from (odd-calendar).
+- `<odd-file-input>`
+  - Use for: Attaching files to a form submission.
+  - Not for: Uploading in the background with progress (render your own rows); choosing an image to preview and crop.
+- `<odd-input>`
+  - Use for: Short values in forms: names, email addresses, search terms, numbers, dates, and times.
+  - Not for: Multi-line text (use odd-textarea); choices from a fixed list (use odd-select or odd-radio-group).
+- `<odd-listbox>`
+  - Use for: A visible list of a few to a few dozen choices, one or several, in a form.
+  - Not for: A compact choice (use odd-select); a long list to search (use odd-combobox); actions (use odd-menu).
+- `<odd-one-time-code>`
+  - Use for: A short code the user copies from a message to confirm a sign-in, an address, or a payment.
+  - Not for: Passwords and PINs the user chooses (use odd-input type="password"); long reference numbers (use odd-input).
+- `<odd-picker>`
+  - Use for: Choosing from a fixed list or a hierarchy in a form: map layers, folders, categories, one or several.
+  - Not for: A short list of plain options (use odd-select); a long list to search (use odd-combobox); browsing a hierarchy without a form value (use odd-tree).
+- `<odd-radio-group>`
+  - Use for: One choice from a few options that should all stay visible, especially with descriptions: a visibility setting, a plan.
+  - Not for: Several independent choices (use odd-checkbox-group); a long list (use odd-select or odd-combobox); a compact switch between a few short values (use odd-segmented-control).
+- `<odd-rating>`
+  - Use for: A score the user gives on a short ordered scale: an opinion of an item, a satisfaction level.
+  - Not for: A number on a long or continuous scale (use odd-slider); choices that are not ordered (use odd-radio-group).
+- `<odd-segmented-control>`
+  - Use for: A compact choice among two to five short values that takes effect at once: a view mode, a preview size.
+  - Not for: Switching between content panels (use odd-tabs); options that need descriptions (use odd-radio-group); actions (use odd-button or odd-toolbar).
+- `<odd-select>`
+  - Use for: One choice from a short, known list in a form: a role, a region, a sort order.
+  - Not for: Several choices, or a list that should stay visible (use odd-listbox); a long list to search (use odd-combobox); actions (use odd-menu).
+- `<odd-slider>`
+  - Use for: A setting within a known range where the approximate position matters more than the exact number: a zoom level, a volume, a preview scale.
+  - Not for: An exact number (use odd-input type="number"); one of a few named values (use odd-segmented-control); progress of a task (use odd-progress).
+- `<odd-switch>`
+  - Use for: A setting that takes effect at once, such as turning notifications on or off.
+  - Not for: A choice confirmed with a submit button (use odd-checkbox); one choice among several (use odd-radio-group).
+- `<odd-textarea>`
+  - Use for: Multi-line text in forms: descriptions, comments, messages.
+  - Not for: A single line (use odd-input); rich text.
+- `<odd-validation-summary>`
+  - Use for: Forms with several fields, where a failed submission should say what to fix in one place.
+  - Not for: One field's error (use the field's `error`); a failed save after a valid submission (use odd-alert).
+
+## Layout
+
+- `<odd-container>`
+  - Use for: A readable column of page content; a region whose children respond to its width with container queries.
+  - Not for: Spacing alone (use `.odd-box`); a scrolling area (use `odd-scroll-region`).
+- `<odd-scroll-region>`
+  - Use for: A bounded area that scrolls inside a page: a long list in a panel, a log, a preview pane.
+  - Not for: The page itself (let the document scroll); a set of choices (use a listbox, which manages focus itself).
+- `<odd-split-panel>`
+  - Use for: Two regions the user resizes, such as a file list beside an editor or a preview under code.
+  - Not for: A fixed page layout (use the layout recipes); hiding content without resizing (use odd-disclosure).
+
+## Navigation
+
+- `<odd-breadcrumbs>`
+  - Use for: Showing where a page sits in a hierarchy, with links to the levels above it.
+  - Not for: The steps of a process; primary navigation (use odd-side-nav); a back button.
+- `<odd-carousel>`
+  - Use for: A few related highlights in one place, one at a time: onboarding steps, featured items.
+  - Not for: Content everyone must see (show it all); switching views (use odd-tabs); paging a long list (use odd-pagination).
+- `<odd-disclosure>`
+  - Use for: Optional detail, advanced settings, and frequently asked questions (an accordion with `name`).
+  - Not for: Switching between views (use odd-tabs); navigation menus; content everyone needs to read.
+- `<odd-pagination>`
+  - Use for: Moving through a long list or result set one page at a time.
+  - Not for: Steps of a process; switching views (use odd-tabs); short lists (show everything).
+- `<odd-side-nav>`
+  - Use for: Primary or section navigation with links, a few actions, and one or two levels of groups.
+  - Not for: Menus of commands (use a menu), tabs, or trees with selection; page layout.
+- `<odd-tab-panel>`
+  - Use for: The content of one tab of odd-tabs.
+  - Not for: Content outside odd-tabs (use a section with a heading).
+- `<odd-tabs>`
+  - Use for: Switching between related views of the same subject in place.
+  - Not for: Page navigation (use links or odd-side-nav); a choice of value in a form (use a radio group or segmented control); steps of a process.
+
+## Overlays
+
+- `<odd-dialog>`
+  - Use for: A task or decision that must be finished or dismissed before going on: a short form, a confirmation, a destructive action.
+  - Not for: Extra detail next to its trigger (use odd-popover); a panel beside the page (use odd-drawer); a passing confirmation (use odd-toast).
+- `<odd-drawer>`
+  - Use for: Details or a task beside the page that keeps its context: an item's properties, filters, settings.
+  - Not for: A decision that must be made first (use odd-dialog); extra detail next to its trigger (use odd-popover); a passing confirmation (use odd-toast).
+- `<odd-popover>`
+  - Use for: Extra controls or details next to the control that shows them: a share form, settings, a definition.
+  - Not for: Content that must be answered before going on (use odd-dialog); a list of actions (use odd-menu); a hint on hover or focus (use odd-tooltip).
+- `<odd-toast>`
+  - Use for: A passing result of the user's action: saved, sent, copied, with Undo or Retry.
+  - Not for: A message that must stay with its region (use odd-alert); a decision (use odd-dialog); a field error (use the field's `error`).
+- `<odd-tooltip>`
+  - Use for: A short hint about a control: what an icon button does, a keyboard shortcut.
+  - Not for: Content to read at length or interact with (use odd-popover); a control's only name (use its label).

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

@@ -0,0 +1,81 @@
+# `<odd-alert>` (OddkinAlert)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Feedback. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A persistent inline message about the page or a region: a tone glyph, a title, a message, and
+optional actions. It stays until the situation changes; a passing result belongs in a toast.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/alert';`
+- Class: `import { OddkinAlert } from '@oddkin/components/alert';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `tone` | `tone` (reflects) | "neutral" \| "info" \| "success" \| "warning" \| "danger" | 'neutral' | Meaning colour and glyph. |
+| `label` | `label` | string | '' | The title, shown above the message. |
+| `announce` | `announce` | "none" \| "important" | 'none' | Announces the alert when it appears or changes (`role="alert"`). |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The message. |
+| `end` | Actions, such as "Try again". |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The surface. |
+| `label` | The title. |
+| `marker` | The tone glyph. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-alert-radius` | Corner radius. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Errors and warnings that affect a page or region, confirmations that must stay visible. (src/alert/alert.ts:17)
+- Not for: Field errors (use the field's `error`); passing results (a toast); counts and labels (use odd-badge). (src/alert/alert.ts:18)
+- Accessibility: Read in place. With `announce`, it is an ARIA alert, so inserting it or changing its text is announced at once; use that only for urgent, new information. (src/alert/alert.ts:15)
+
+## Examples
+
+- `example:odd-alert/announced` in src/alert/alert.examples.ts (package source)
+- `example:odd-alert/danger` in src/alert/alert.examples.ts (package source)
+- `example:odd-alert/default` in src/alert/alert.examples.ts (package source), preview roles role:alert
+- `example:odd-alert/success` in src/alert/alert.examples.ts (package source)
+- `example:odd-alert/warning` in src/alert/alert.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-alert/colorOnly` produces `usage.attribute.value`; correct: `example:odd-alert/danger`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-alert-radius`
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

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

@@ -0,0 +1,80 @@
+# `<odd-avatar>` (OddkinAvatar)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Display. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A person or group marker: a picture (`src`) or, without one or when it fails to load, the
+initials of `label`. Content placed inside replaces the initials (a "+3" overflow count).
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/avatar';`
+- Class: `import { OddkinAvatar } from '@oddkin/components/avatar';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | The person's or group's name; names the image. |
+| `src` | `src` | string | '' | Picture URL; the initials show without it. |
+| `size` | `size` (reflects) | "sm" \| "md" \| "lg" | 'md' | Diameter: 32, 40, or 48 px. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | Replaces the initials, such as "+3" at the end of a group. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The circle. |
+| `image` | The picture. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-avatar-size` | Diameter; overrides `size`. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Identifying people in lists, comments, assignments, and member groups. (src/avatar/avatar.ts:16)
+- Not for: Product or file images; decorative illustrations. (src/avatar/avatar.ts:17)
+- Accessibility: An image named by `label` (the person's name); without `label` it is hidden from assistive technology, for a name already shown beside it. (src/avatar/avatar.ts:14)
+
+## Examples
+
+- `example:odd-avatar/decorative` in src/avatar/avatar.examples.ts (package source)
+- `example:odd-avatar/default` in src/avatar/avatar.examples.ts (package source), preview roles role:avatar
+- `example:odd-avatar/large` in src/avatar/avatar.examples.ts (package source)
+- `example:odd-avatar/overflow` in src/avatar/avatar.examples.ts (package source)
+- `example:odd-avatar/picture` in src/avatar/avatar.examples.ts (package source)
+- `example:odd-avatar/small` in src/avatar/avatar.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-avatar/nameAttribute` produces `usage.attribute.unknown`; correct: `example:odd-avatar/default`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-avatar-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`

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

@@ -0,0 +1,79 @@
+# `<odd-badge>` (OddkinBadge)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Feedback. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A passive status or count: words with a tone colour and a glyph, so the meaning never rests on
+colour alone. Not an action; do not make it clickable.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/badge';`
+- Class: `import { OddkinBadge } from '@oddkin/components/badge';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `tone` | `tone` (reflects) | "neutral" \| "info" \| "success" \| "warning" \| "danger" | 'neutral' | Meaning colour and glyph. |
+| `noMarker` | `no-marker` (reflects) | boolean | false | Hides the tone glyph, as for a count. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The text. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The surface. |
+| `marker` | The tone glyph (hidden with `no-marker`). |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-badge-radius` | Corner radius. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Short status labels and counts next to the thing they describe. (src/badge/badge.ts:14)
+- Not for: Actions or filters (use a button); messages that need attention (use an alert). (src/badge/badge.ts:15)
+- Accessibility: Read in place as text; it has no role. Put the meaning in the words ("Failed", "3 new"), not only in the tone. (src/badge/badge.ts:12)
+
+## Examples
+
+- `example:odd-badge/count` in src/badge/badge.examples.ts (package source)
+- `example:odd-badge/danger` in src/badge/badge.examples.ts (package source)
+- `example:odd-badge/default` in src/badge/badge.examples.ts (package source), preview roles role:badge
+- `example:odd-badge/info` in src/badge/badge.examples.ts (package source)
+- `example:odd-badge/success` in src/badge/badge.examples.ts (package source)
+- `example:odd-badge/warning` in src/badge/badge.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-badge/colorOnly` produces `usage.attribute.value`; correct: `example:odd-badge/danger`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-badge-radius`
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

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

@@ -0,0 +1,86 @@
+# `<odd-breadcrumbs>` (OddkinBreadcrumbs)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Navigation. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A location trail: links to the pages above this one, then the current page as text. Items come
+from `<a href>` descendants (a server-rendered `<ol><li><a href>` list works as written) or the
+`items` property; with `max-items`, the middle items wait behind a "more" button.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/breadcrumbs';`
+- Class: `import { OddkinBreadcrumbs } from '@oddkin/components/breadcrumbs';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | Names the navigation; default `strings.label`. |
+| `items` | none: assign as a property | readonly LinkRecord[] \| undefined | undefined | Items `{ label, href }`, the last being the current page. When set (even to an empty array) it is the only source; `<a href>` children are ignored. |
+| `maxItems` | `max-items` | number | 0 | Collapse when there are more items than this: the first item, a "more" button, and the last `max-items − 1` items show. 0 never collapses. |
+| `strings` | none: assign as a property | Partial<{ label: string; more: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| `home` | Replaces the first item's text: other text, or an icon (`<svg>`), which is decorative; with no text in it, the first item's label stays as hidden text, so the item keeps its name. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The `<nav>` surface. |
+| `current` | The current page (text with `aria-current="page"`). |
+| `item` | Each list item. |
+| `link` | Each link to a page above this one. |
+| `list` | The ordered list. |
+| `more` | The button that shows the collapsed items. |
+| `separator` | The mark before each item after the first. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-breadcrumbs-radius` | Corner radius of the surface. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Showing where a page sits in a hierarchy, with links to the levels above it. (src/breadcrumbs/breadcrumbs.ts:39)
+- Not for: The steps of a process; primary navigation (use odd-side-nav); a back button. (src/breadcrumbs/breadcrumbs.ts:40)
+- Accessibility: A `<nav>` landmark named by `label` (default `strings.label`, "Breadcrumb") around an ordered list. The last item is the current page, as text with `aria-current="page"`. Separators are hidden from assistive technology. The "more" button is named "Show 2 more" (`strings.more`); activating it shows the collapsed items and moves focus to the first of them. (src/breadcrumbs/breadcrumbs.ts:36)
+- Keyboard: Tab moves through the links and the "more" button; Enter follows a link; Enter or Space on "more" shows the collapsed items. (src/breadcrumbs/breadcrumbs.ts:37)
+
+## Examples
+
+- `example:odd-breadcrumbs/collapsed` in src/breadcrumbs/breadcrumbs.examples.ts (package source)
+- `example:odd-breadcrumbs/default` in src/breadcrumbs/breadcrumbs.examples.ts (package source), preview roles role:breadcrumbs
+- `example:odd-breadcrumbs/homeIcon` in src/breadcrumbs/breadcrumbs.examples.ts (package source)
+- `example:odd-breadcrumbs/items` in src/breadcrumbs/breadcrumbs.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-breadcrumbs/itemsAttribute` produces `usage.attribute.propertyOnly`; correct: `example:odd-breadcrumbs/items`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-breadcrumbs-radius`
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`