# @kimen/elements — Kimen web components > Kimen web components (ki-*). Standards-first Stencil components, tokens-only styling, agent-legible by contract. Install with `pnpm add @kimen/elements @kimen/tokens`. Register each component before using it. Every component is exported from `@kimen/elements/`, the way `ki-button` is here: ```ts import { defineCustomElement as defineKiButton } from '@kimen/elements/ki-button'; import '@kimen/tokens/css'; import '@kimen/tokens/css/base'; defineKiButton(); ``` Load `@kimen/tokens/css` once per page: it is the onmars default theme and the only stylesheet the components require. It declares every `--ki-*` token for both schemes together with the `color-scheme` they resolve from, so a page follows its visitor's light or dark preference with no further setup. `@kimen/tokens/css/base` — the page contract — is optional: it paints the page background, text color and body font from those tokens and declares no color scheme of its own. Without it the page keeps the browser's own canvas and text color for the active scheme, and every component stays legible on it. Human-readable documentation: https://kimen.dev/docs/ ## Theming All themes reassign the same `--ki-*` custom properties, so switching themes restyles every component with no code changes. Two attributes on the document root drive selection: - `data-ki-color-scheme`: `light` or `dark` forces a color scheme for any theme, overriding the OS preference. Without it, stylesheets follow `prefers-color-scheme`. - `data-ki-theme`: opts into a non-default theme. Unknown theme names match no selector and fall back to onmars through the cascade. To use the bundled Material 3 reference theme, side-effect import its stylesheet (exported as `@kimen/tokens/css/material3`) in addition to `@kimen/tokens/css`, then select it on the document root: ```html ``` ## Agent setup Coding agents can install the Kimen agent skills (`kimen-components` for pages built with these components, `kimen-genui` for agent-generated UI) and connect the `kimen-mcp` server, which lists and describes the catalog, validates UI specs and renders them. Setup for Claude Code, Claude Desktop, Codex, Antigravity, OpenCode and other clients: https://kimen.dev/docs/guides/connect-agents/ ## Components ### ki-accordion A set of native disclosure panels with a shared frame. When to use: group related FAQ answers, settings or expandable sections. Enable exclusive when readers benefit from one open section at a time. When NOT to use: switch between views or make the panels advance a workflow. Examples: ### Workspace FAQ Group direct disclosure children. Set `exclusive` when readers should see one answer at a time. ```html Only people you invite can see it. Open Settings, then select Data and Export. ``` Attributes: - `exclusive` (boolean, default false): Whether the accordion allows at most one direct member to be open. Slots: - (default): Direct ki-details members in reading order. Parts: - `group`: The frame around the disclosure rows. Events: none Methods: none CSS custom properties: - `--ki-accordion-divider-width`: Width of the separator between accordion rows. - `--ki-details-border`: Color of the disclosure frame and accordion separators. - `--ki-details-border-width`: Width of the disclosure or accordion frame. - `--ki-details-radius`: Corners of a standalone disclosure or the accordion frame. - `--ki-typography-family-body`: semantic font family for typography family body. ### ki-ai-label A compact provenance mark for AI-generated content, with optional details and a user-initiated request to restore their original text. When to use: Mark text or a value generated by AI. Include the source in `explanation` when people can inspect how it was generated. In a `ki-input`, place the label in the `end` slot to describe the field's provenance. When NOT to use: Use a status component for active generation or processing, and an application action for changes that do not restore the person's text. Examples: # AI label examples Mark generated content beside the text it describes. ```html
Weekly summary
``` Give people a short provenance explanation when they need to assess a result. The model and generation time are optional. ```html ``` Use the input's `end` slot to announce the provenance with the field description. Keep the original in application state and restore it on `ki-revert`. ```html ``` Attributes: - `explanation` (string | undefined): Plain-text explanation of how the content was generated. Supply a nonblank explanation to offer disclosure. Omit it for a static mark. - `generated-at` (string | undefined): Optional generation date or time, displayed as supplied. - `generated-at-label` (string, default 'Generated'): Visible prefix for the generation date or time. - `label` (string, default 'AI'): Short visible provenance text. Localize it with the trigger name. - `model` (string | undefined): Optional plain-text model name shown in the explanation. - `model-label` (string, default 'Model:'): Visible prefix for the model name. - `popover-label` (string, default 'About this content'): Accessible name of the non-modal explanation panel. - `revert-label` (string, default 'Revert to my text'): Visible text and accessible name of the revert action. - `revertible` (boolean, default false): Offer the revert action inside the explanation. Enable it when the application has the original text and handles `ki-revert`. - `size` ("md" | "sm", default 'sm'): Size of the painted mark. Unknown values use the small metrics. - `trigger-label` (string, default 'AI-generated: about this content'): Accessible name of the disclosure button. Include the visible label. Slots: none Parts: - `explanation`: Source explanation paragraph. - `icon`: Decorative sparkles glyph. - `label`: Tinted mark containing the icon and visible text. - `metadata`: Optional model and generation time. - `popover`: Non-modal explanation panel. - `revert`: Button that requests reversion. - `trigger`: Disclosure button, available with an explanation. Events: - `ki-revert` (CustomEvent): Bubbles when a person requests their original text. Use this request to restore the original from application state. Methods: none CSS custom properties: - `--ki-ai-label-backdrop-filter`: Complete filter behind the AI provenance mark. Defaults to none. - `--ki-ai-label-bg`: Fill of the AI provenance mark. - `--ki-ai-label-bg-image`: Optional image over the AI provenance fill. Defaults to none. - `--ki-ai-label-border-width`: Border width of the panel and the forced-colors mark. - `--ki-ai-label-fg`: Text and icon ink of the AI provenance mark. - `--ki-ai-label-gap`: Gap between the mark and its icon or between provenance metadata items. - `--ki-ai-label-md-height`: Minimum painted block size of the medium AI mark. - `--ki-ai-label-md-icon-size`: Sparkles icon size in the medium AI mark. - `--ki-ai-label-md-padding-inline`: Inline inset of the medium AI mark. - `--ki-ai-label-popover-backdrop-filter`: Complete filter behind the provenance explanation. Defaults to none. - `--ki-ai-label-popover-bg`: Raised fill of the provenance explanation. - `--ki-ai-label-popover-bg-image`: Optional image over the provenance explanation fill. Defaults to none. - `--ki-ai-label-popover-border`: Hairline color of the explanation panel. - `--ki-ai-label-popover-fg`: Ink of the provenance explanation and metadata. - `--ki-ai-label-popover-gap`: Gap between the panel sections and between the panel and trigger. - `--ki-ai-label-popover-padding`: Inset of the explanation panel. - `--ki-ai-label-popover-radius`: Corner radius of the explanation panel. - `--ki-ai-label-popover-shadow`: Elevation of the explanation panel. - `--ki-ai-label-popover-width`: Preferred inline size of the explanation panel. - `--ki-ai-label-radius`: Corner radius of the AI provenance mark. - `--ki-ai-label-sm-height`: Minimum painted block size of the small AI mark. - `--ki-ai-label-sm-icon-size`: Sparkles icon size in the small AI mark. - `--ki-ai-label-sm-padding-inline`: Inline inset of the small AI mark. - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-offset`: Gap between a focusable component and its keyboard focus ring. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. - `--ki-typography-family-body`: semantic font family for typography family body. - `--ki-typography-line-height-caption-2`: semantic dimension for typography line height caption 2. - `--ki-typography-line-height-para`: semantic dimension for typography line height para. - `--ki-typography-size-body-1`: semantic dimension for typography size body 1. - `--ki-typography-size-body-2`: semantic dimension for typography size body 2. - `--ki-typography-size-caption-2`: semantic dimension for typography size caption 2. - `--ki-typography-weight-body-semibold`: semantic font weight for typography weight body semibold. ### ki-alert A persistent inline status message with token-backed tone semantics. When to use: show a persistent inline message about the state of a page or section, such as a failed save, completed operation, or service notice, that remains until the condition is resolved or the person dismisses it. Express severity with `tone`, never custom styling. When NOT to use: transient confirmations that expire on their own belong to `ki-toast`, raised into a `ki-toaster`; tiny status descriptors attached to another element belong to `ki-badge`; blocking decisions belong to `ki-dialog`; inline field-level validation belongs to the form control. Assistive technology note: alerts that must be announced should be inserted dynamically, or re-shown by clearing `dismissed`; alerts present at initial page load are exposed with their role but platform announcement is not guaranteed. Every non-neutral alert should carry an icon: in the onmars theme the tone is drawn on the icon alone. Examples: `tone` sets the token-backed colors and the live-region urgency — `danger` and `warning` expose `role="alert"`, every other value `role="status"`: ```html Your changes were saved. Payment failed. Update your billing details. ``` An optional `heading` adds emphasized text inside the live region; it is a `strong` element, never a document heading: ```html You are using 92% of your plan. ``` `dismissible` renders the alert's only tab stop; user dismissal reflects `dismissed` and fires a composed `ki-dismiss` (programmatic `dismissed` writes stay silent, and clearing the attribute re-shows the alert): ```html Your changes could not be saved. Retry or copy your work elsewhere. ``` `dismiss-label` overrides the dismiss button's accessible name — the default `Dismiss` is the component's only built-in user-visible string, so localize it whenever the document language is not English: ```html Mantenimiento programado el sábado desde las 02:00 UTC. ``` The `icon` slot takes a decorative glyph, drawn in the tone's colors in a round frame at the top of the card; give every non-neutral alert one, since that is where the tone shows. The `actions` slot takes the responses to the message as `size="sm"` buttons, in a row after the message and outside the live region. An action never dismisses the alert by itself: set `dismissed` when it should go, and focus moves on to the next control: ```html Your session expires in one minute. Choose Stay signed in to keep working. Sign out Stay signed in ``` Attributes: - `dismiss-label` (string, default 'Dismiss'): Accessible name for the dismiss button. Override for localization; the default English string is the component's only built-in user-visible text. When to use: provide a localized action name whenever the document language is not English. When NOT to use: do not put the alert message here; use the default slot. - `dismissed` (boolean, default false): Reflected dismissed state. User dismissal sets it; applications may also set or clear it. While true, the host remains in the document but renders no alert subtree and leaves the accessibility tree. Clearing it re-shows the alert and creates a dynamic live-region appearance. When to use: persist or restore acknowledgement state from application data. When NOT to use: do not listen for programmatic changes as dismissal events; `ki-dismiss` is only for user activation. - `dismissible` (boolean, default false): Renders one native dismiss button when true. The button sits outside the live-region boundary, so its accessible name is not announced as part of the alert message. When false, the alert adds no tab stop. When to use: allow a person to acknowledge and clear a persistent message. When NOT to use: do not use dismissible for auto-expiring messages; those belong to `ki-toast`. - `heading` (string | undefined): Optional emphasized text rendered before the message inside the live region. Empty strings render no heading. The heading is a `strong` element, not a document heading, so it never changes page outline. When to use: add a short label when it helps identify the status message. When NOT to use: do not use heading for page structure; use a real heading outside the alert when the document needs one. - `tone` ("danger" | "info" | "neutral" | "success" | "warning" | string & {}, default 'neutral'): Semantic intent for visual styling and live-region urgency. `danger` and `warning` expose `role="alert"`; `neutral`, `success`, `info`, absent, and unrecognized values expose `role="status"`. Unknown values keep rendering and fall back to the neutral token matrix by CSS construction. When to use: choose the tone that describes the page or section state. When NOT to use: do not use tone for layout, density, or filled-vs-outlined styling; those are token/theme decisions. Slots: - (default): Message body. It lives inside the live-region boundary. - `actions`: Optional responses to this message, in a row at the bottom of the card, outside the live region. Slot `size="sm"` buttons. The alert never activates them and an action does not dismiss the alert; the application does, by setting `dismissed`. When NOT to use: a response the person cannot skip belongs in `ki-dialog`. - `icon`: Optional decorative glyph shown in a round frame at the top of the card, in the tone's colors. Hidden from assistive technology: it never carries meaning the heading and message lack. When to use: give every non-neutral alert an icon. When NOT to use: never as the only cue for the message. Parts: - `actions`: Row around the `actions` slot, rendered only when it holds content. - `alert`: Outer shell around the card: padding, radius, wash and blur. - `card`: Card holding the icon, text, actions and dismiss control: tone background, border, radius, padding and elevation. - `dismiss`: Native dismiss button, rendered only when dismissible. - `heading`: Optional emphasized heading, rendered only when non-empty. - `icon`: Round frame around the `icon` slot, rendered only when it holds content. - `message`: Message body wrapper around the default slot. Events: - `ki-dismiss` (CustomEvent): Fired once after the user dismisses the alert — emitted after the alert is hidden and focus has been handed to the next control. `detail` is `null` and the event is not cancelable (the alert is already gone when it runs). When to use: record acknowledgement, or advance an application flow after a user closes the alert. When NOT to use: do not treat it as a veto point, and do not expect it for programmatic `dismissed` changes — it fires only for user activation. Methods: none CSS custom properties: - `--ki-alert-actions-gap`: dimension used by the alert component for the gap between slotted actions (MarsUI Alert master CTAs gap Space/xl 12px). - `--ki-alert-border-width`: dimension used by the alert component for the card border width (MarsUI never strokes alert surfaces: the Alert master card stroke is fully transparent. material3 keeps its 2px border via its override). - `--ki-alert-card-shadow`: shadow used by the alert component for the card elevation (MarsUI Alert master List_wrap: elevation ramp level e5). - `--ki-alert-danger-bg`: color used by the alert component for the danger card background (MarsUI Alert master: the List_wrap card is Surface/special/light-s0-dark-s2 in every tone; the tone is drawn on the icon. Other themes may tint the card per tone here). - `--ki-alert-danger-border`: color used by the alert component for danger border (MarsUI draws no tone border on any alert/note/toast surface). - `--ki-alert-danger-fg`: color used by the alert component for the danger card foreground: heading and message ink (MarsUI Alert master Text/high-em in every tone; the message keeps this 4.5:1 ink instead of the master Text/low-em, spec 011 A1-D8). - `--ki-alert-danger-icon-bg`: color used by the alert component for the danger icon frame (MarsUI Alert master Feature-icon Surface/danger-base-em-alpha at 12%). - `--ki-alert-danger-icon-fg`: color used by the alert component for the danger icon glyph (MarsUI Alert master Feature-icon glyph Text/danger-high-em). - `--ki-alert-dismiss-active-fg`: color used by the alert component for dismiss active foreground. - `--ki-alert-dismiss-backdrop-filter`: Complete backdrop filter behind the alert dismiss button. - `--ki-alert-dismiss-border-width`: dimension used by the alert component for the dismiss chip bevel stroke (MarsUI 24px raised circle: 1px Outline/secondary_button_top hairline). - `--ki-alert-dismiss-hover-bg`: color used by the alert component for dismiss hover background (MarsUI hover mechanism: hover_overlay_inverse Black/3 wash — the dismiss chip previously had zero visible hover change). - `--ki-alert-dismiss-hover-fg`: color used by the alert component for dismiss hover foreground. - `--ki-alert-dismiss-icon-size`: dimension used by the alert component for dismiss icon size (Figma close glyph box 16px inside the 24px raised circle; repointed from 18px per the fidelity audit). - `--ki-alert-dismiss-radius`: dimension used by the alert component for the dismiss chip shape (MarsUI Radius/radius_round full circle). - `--ki-alert-dismiss-rest-fg`: color used by the alert component for dismiss rest foreground. - `--ki-alert-dismiss-size`: dimension used by the alert component for dismiss size. - `--ki-alert-focus-ring-color`: color used by the alert component for focus ring color. - `--ki-alert-focus-ring-offset`: dimension used by the alert component for focus ring offset. - `--ki-alert-focus-ring-shadow`: shadow used by the alert dismiss control for the focus ring glow (MarsUI Focus/primary: 3px spread ring at 20% — see ki.focus.primary. specs/002-ki-button/design-extraction.md §2.5 recorded 40%, having read the alpha off the Dark canvas mode, same double mechanism as ki-button: glow plus the opaque indicator). - `--ki-alert-focus-ring-width`: dimension used by the alert component for focus ring width. - `--ki-alert-font-size`: dimension used by the alert component for font size. - `--ki-alert-gap`: dimension used by the alert component for the card stack gap between icon, text and actions (MarsUI Alert master List_wrap gap Space/xl 12px). - `--ki-alert-heading-font-family`: Font family for the alert heading. Override it to give alerts their own heading typeface. - `--ki-alert-heading-font-size`: dimension used by the alert component for heading font size. - `--ki-alert-heading-font-weight`: font weight used by the alert component for heading font weight (MarsUI UI/Body 2/medium: weight 600 on the master heading). - `--ki-alert-icon-glyph-size`: dimension used by the alert component for the icon glyph inside the frame (MarsUI Alert master Feature-icon glyph 20px). - `--ki-alert-icon-radius`: dimension used by the alert component for the icon frame radius (MarsUI Alert master Feature-icon: a circle). - `--ki-alert-icon-size`: dimension used by the alert component for the icon frame (MarsUI Alert master Feature-icon size xs: 32px). - `--ki-alert-info-bg`: color used by the alert component for the info card background (MarsUI Alert master: the List_wrap card is Surface/special/light-s0-dark-s2 in every tone; the tone is drawn on the icon. Other themes may tint the card per tone here). - `--ki-alert-info-border`: color used by the alert component for info border (MarsUI draws no tone border on any alert/note/toast surface). - `--ki-alert-info-fg`: color used by the alert component for the info card foreground: heading and message ink (MarsUI Alert master Text/high-em in every tone; the message keeps this 4.5:1 ink instead of the master Text/low-em, spec 011 A1-D8). - `--ki-alert-info-icon-bg`: color used by the alert component for the info icon frame (MarsUI Alert master Feature-icon Surface/info-base-em-alpha at 12%). - `--ki-alert-info-icon-fg`: color used by the alert component for the info icon glyph (MarsUI Alert master Feature-icon glyph Text/info-high-em). - `--ki-alert-line-height`: dimension used by the alert component for line height. - `--ki-alert-message-line-height`: dimension used by the alert component for message line height (MarsUI description is 13/20 line_height/para; the heading keeps 15/24). - `--ki-alert-neutral-bg`: color used by the alert component for the neutral card background (MarsUI Alert master: the List_wrap card is Surface/special/light-s0-dark-s2 in every tone; the tone is drawn on the icon. Other themes may tint the card per tone here). - `--ki-alert-neutral-border`: color used by the alert component for neutral border. - `--ki-alert-neutral-fg`: color used by the alert component for the neutral card foreground: heading and message ink (MarsUI Alert master Text/high-em in every tone; the message keeps this 4.5:1 ink instead of the master Text/low-em, spec 011 A1-D8). - `--ki-alert-neutral-icon-bg`: color used by the alert component for the neutral icon frame (MarsUI Alert master Feature-icon Surface/primary-base-em-alpha at 12%: the master variable itself, not the heavier primary-tint content fill, so the primary glyph clears 4.5:1 in dark). - `--ki-alert-neutral-icon-fg`: color used by the alert component for the neutral icon glyph (MarsUI Alert master Feature-icon glyph Text/primary-high-em). - `--ki-alert-padding-block`: dimension used by the alert component for the card padding block (MarsUI Alert master List_wrap card: 12px on all four sides). - `--ki-alert-padding-inline`: dimension used by the alert component for the card padding inline (MarsUI Alert master List_wrap card: 12px on all four sides). - `--ki-alert-radius`: dimension used by the alert component for the card radius (MarsUI Alert master List_wrap big_component/radius_xs 16px; the shell around it has its own radius). - `--ki-alert-shell-backdrop-filter`: Complete backdrop filter behind the alert shell. - `--ki-alert-shell-bg`: color used by the alert component for the shell wash (MarsUI Alert master Inverse-white/alpha-2: the nearest step of the Kimen inverse-white ramp, Black/3 light and White/3 dark). - `--ki-alert-shell-padding`: dimension used by the alert component for the shell padding around the card (MarsUI Alert master: 12px on all four sides). - `--ki-alert-shell-radius`: dimension used by the alert component for the shell radius (MarsUI Alert master big_component/radius_lg 28px). - `--ki-alert-success-bg`: color used by the alert component for the success card background (MarsUI Alert master: the List_wrap card is Surface/special/light-s0-dark-s2 in every tone; the tone is drawn on the icon. Other themes may tint the card per tone here). - `--ki-alert-success-border`: color used by the alert component for success border (MarsUI draws no tone border on any alert/note/toast surface). - `--ki-alert-success-fg`: color used by the alert component for the success card foreground: heading and message ink (MarsUI Alert master Text/high-em in every tone; the message keeps this 4.5:1 ink instead of the master Text/low-em, spec 011 A1-D8). - `--ki-alert-success-icon-bg`: color used by the alert component for the success icon frame (MarsUI Alert master Feature-icon Surface/success-base-em-alpha at 12%). - `--ki-alert-success-icon-fg`: color used by the alert component for the success icon glyph (MarsUI Alert master Feature-icon glyph Text/success-high-em). - `--ki-alert-text-gap`: dimension used by the alert component for the heading-to-message stack gap (MarsUI Text_wrap 4px, decoupled from the outer 12px card gap). - `--ki-alert-warning-bg`: color used by the alert component for the warning card background (MarsUI Alert master: the List_wrap card is Surface/special/light-s0-dark-s2 in every tone; the tone is drawn on the icon. Other themes may tint the card per tone here). - `--ki-alert-warning-border`: color used by the alert component for warning border (MarsUI draws no tone border on any alert/note/toast surface). - `--ki-alert-warning-fg`: color used by the alert component for the warning card foreground: heading and message ink (MarsUI Alert master Text/high-em in every tone; the message keeps this 4.5:1 ink instead of the master Text/low-em, spec 011 A1-D8). - `--ki-alert-warning-icon-bg`: color used by the alert component for the warning icon frame (MarsUI Alert master Feature-icon Surface/warning-base-em-alpha at 12%). - `--ki-alert-warning-icon-fg`: color used by the alert component for the warning icon glyph (MarsUI Alert master Feature-icon glyph Text/warning-high-em). - `--ki-density-space-scale`: Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-effect-component-secondary-default-shadow`: MarsUI Component_effect/secondary_default: drop 0/2/1.5/-0.5 plus inner White/3 0/2/3. Pair with --ki-effect-component-backdrop-filter. - `--ki-motion-distance-sm`: Motion travel distance sm (4px): small slide/settle offsets. - `--ki-motion-duration-fast`: Fast interaction transition duration. - `--ki-motion-duration-medium-1`: M3 md.sys.motion.duration.medium1 (250ms). onmars: MarsUI moderate step (240ms, 2x the 120ms base). - `--ki-motion-easing-out`: Decelerating interaction transition easing curve. - `--ki-motion-easing-standard`: Standard interaction transition easing curve. - `--ki-outline-secondary-button-top`: semantic color for outline secondary button top. - `--ki-surface-special-light-s0-dark-s2`: semantic color for surface special light s0 dark s2. - `--ki-typography-family-body`: semantic font family for typography family body. ### ki-audio A recording player with play, pause, a seek timeline, elapsed and total time, playback speed, mute, and an optional transcript link. When to use: play a voice note, interview, or other prerecorded audio that a person deliberately starts. Provide a title and the equivalent text transcript URL when available. When NOT to use: show video (use ki-video), play an ambient loop or start playback automatically, or record audio. Examples: # Using ki-audio Offer a voice note or recording with a clear title and an adjacent transcript. ```html ``` Set the speeds and translate the control labels in the language of the page. The seek announcement substitutes the formatted elapsed and total times into the `time-label` template. ```html ``` Listen on the player for `play`, `pause`, `timeupdate` and `ended`. For example, an experiment can observe completion after the listener reaches the end of a recording. ```js const player = document.querySelector('ki-audio'); player?.addEventListener('ended', () => { document.querySelector('#next-recording')?.removeAttribute('hidden'); }); ``` Attributes: - `title` (string | undefined, default 'Audio player'): Visible title and accessible name of the player. - `error-label` (string, default 'Audio could not be played'): Message shown if playback cannot start or the recording fails to load. - `mute-label` (string, default 'Mute'): Accessible name of the mute button. - `pause-label` (string, default 'Pause'): Accessible name of the pause button. - `play-label` (string, default 'Play'): Accessible name of the play button. - `rates` (string, default '0.75,1,1.25,1.5,2'): Comma-separated playback speeds between 0.25 and 4. Normal speed (1) is always available. - `seek-label` (string, default 'Seek'): Accessible name of the timeline slider. - `speed-label` (string, default 'Playback speed'): Accessible label for the playback-rate picker. - `src` (string, required, URL): Source URL for the recording. Use an HTTP(S) URL or a relative URL. - `time-label` (string | undefined, default '{elapsed} of {duration}'): Accessible time template. Keep the {elapsed} and {duration} placeholders. - `transcript-href` (string | undefined, URL): URL for the recording's text transcript. Use an HTTP(S) URL or a relative URL. - `transcript-label` (string, default 'Read the transcript'): Text of the transcript link. - `unmute-label` (string, default 'Unmute'): Accessible name of the unmute button. Slots: none Parts: - `mute`: Mute and unmute control. - `play`: Play and pause control. - `player`: The named group and themed surface. - `progress`: Played portion of the timeline rail. - `seek`: Native seek slider. - `speed`: Native playback-rate picker. - `status`: Playback failure message. - `time`: Elapsed and total time readouts. - `title`: Visible recording title. - `track`: Timeline rail. - `transcript`: Transcript link. Events: - `ended` (CustomEvent): Forwarded when the recording ends. The catalog can bind a declared action here. - `pause` (CustomEvent): Forwarded when native playback pauses. - `play` (CustomEvent): Forwarded when the native playback state switches to playing. - `timeupdate` (CustomEvent): Forwarded when the native playback position is updated. Methods: none CSS custom properties: - `--ki-audio-backdrop-filter`: Complete backdrop filter applied to the player, off by default. - `--ki-audio-bg`: Background behind the player and transcript link. - `--ki-audio-bg-image`: Optional image painted over the player background. - `--ki-audio-border`: Boundary of the player panel. - `--ki-audio-fg`: Text on the player background. - `--ki-audio-progress-bg`: Colour of the elapsed timeline and seek thumb. - `--ki-audio-radius`: Corner radius of the player panel. - `--ki-audio-speed-radius`: Corner radius of the playback speed button. - `--ki-audio-title-family`: Font family of the recording title. - `--ki-audio-track-bg`: Colour of the inactive timeline. - `--ki-button-ghost-neutral-disabled-bg`: color used by the button component for ghost neutral disabled background. - `--ki-button-ghost-neutral-disabled-border`: color used by the button component for ghost neutral disabled border. - `--ki-button-ghost-neutral-disabled-fg`: color used by the button component for ghost neutral disabled foreground. - `--ki-button-ghost-neutral-hover-bg`: color used by the button component for ghost neutral hover background. - `--ki-button-ghost-neutral-hover-border`: color used by the button component for ghost neutral hover border. - `--ki-button-ghost-neutral-hover-fg`: color used by the button component for ghost neutral hover foreground. - `--ki-button-ghost-neutral-rest-bg`: color used by the button component for ghost neutral rest background. - `--ki-button-ghost-neutral-rest-border`: color used by the button component for ghost neutral rest border. - `--ki-button-ghost-neutral-rest-fg`: color used by the button component for ghost neutral rest foreground. - `--ki-button-primary-neutral-disabled-bg`: color used by the button component for primary neutral disabled background. Deliberate deviation: Figma disabled is Surface/disabled_base_em gray.100 with gray.400 text (≈1.4:1); Kimen keeps gray.200 for contrast (precedent 010 D2, pending founder ratification). - `--ki-button-primary-neutral-disabled-border`: color used by the button component for primary neutral disabled border. - `--ki-button-primary-neutral-disabled-fg`: color used by the button component for primary neutral disabled foreground. Deliberate deviation: Figma disabled text is text/base_em gray.400 (≈1.4:1 on gray.100); Kimen keeps text.muted gray.700 for readable disabled text (precedent 010 D2, pending founder ratification). - `--ki-button-primary-neutral-hover-bg`: color used by the button component for primary neutral hover background (MarsUI: rest fill; hover lightening comes from the hover overlay). - `--ki-button-primary-neutral-hover-border`: color used by the button component for primary neutral hover border (MarsUI bevel top/inline edge). - `--ki-button-primary-neutral-hover-fg`: color used by the button component for primary neutral hover foreground. - `--ki-button-primary-neutral-rest-bg`: color used by the button component for primary neutral rest background (MarsUI Surface/primary_med_em, brand 500). - `--ki-button-primary-neutral-rest-border`: color used by the button component for primary neutral rest border (MarsUI bevel top/inline edge). - `--ki-button-primary-neutral-rest-fg`: color used by the button component for primary neutral rest foreground. - `--ki-control-border-width`: Stroke width of the boundary of a compact control. - `--ki-control-radius-track`: Corner radius of a track containing adjacent controls. - `--ki-control-size-md`: Medium control track height, 40 CSS px at the default root size. - `--ki-control-size-sm`: Small control track height, 32 CSS px at the default root size. - `--ki-corner-activity-mark`: Round corners for rings and typing dots. - `--ki-corner-inline`: Small radius for an outline around inline content. - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-offset`: Gap between a focusable component and its keyboard focus ring. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. - `--ki-glyph-size-md`: Medium glyph for body content (20px at the default root size). - `--ki-glyph-size-sm`: Small glyph for dense layouts (16px at the default root size). - `--ki-media-layout-inline-max`: Maximum inline size of a self-contained media control panel. - `--ki-scale-control-coarse-target`: Minimum grip target when a value scale has a coarse primary pointer. - `--ki-scale-control-track-height`: Thickness of the inactive rail of a value scale. - `--ki-spacing-action-inset`: Interior space at the edge of an action surface or divider. - `--ki-spacing-block`: Deprecated alias kept for pre-Fase-1 consumers; use ki.space.xl. - `--ki-spacing-media-caption`: Block spacing between a media frame and its caption. - `--ki-typography-family-body`: semantic font family for typography family body. - `--ki-typography-line-height-body-1`: semantic dimension for typography line height body 1. - `--ki-typography-line-height-caption-2`: semantic dimension for typography line height caption 2. - `--ki-typography-size-body-1`: semantic dimension for typography size body 1. - `--ki-typography-size-caption-2`: semantic dimension for typography size caption 2. - `--ki-typography-underline-offset`: Gap between text and its underline. - `--ki-typography-underline-thickness`: Stroke width of a resting text underline. - `--ki-typography-weight-body-medium`: semantic font weight for typography weight body medium. ### ki-avatar A static identity visual that shows a person or entity at a glance through a fallback chain: portrait, then initials, then a built-in generic figure. When to use: a compact identity visual for a person or entity — a comment author, a contact list item, a project member. Set `label` whenever the avatar is the only carrier of the identity (no adjacent visible name); compose several into `ki-avatar-group` for a compact "who is involved" stack with overflow. When NOT to use: as a clickable control (compose the avatar inside an interactive host such as ki-button), for logos or arbitrary illustrations (plain `img`), or unlabeled when no adjacent text names the identity. Use the counter slot for a decorative count or presence dot. Examples: The fallback chain is content, never a mode switch: a portrait that loads wins, `initials` render verbatim otherwise, and a built-in generic figure covers the rest; `label` exposes the avatar as a named non-interactive image: ```html ``` Beside a visible name the avatar is decorative — omit `label` so assistive technology hears the name exactly once: ```html

Ana García

``` `size` steps over the shared scale (`xxs` to `xl`, default `md`); an unrecognized value keeps the medium metrics: ```html ``` Attributes: - `initials` (string | undefined): Initials rendered verbatim as the second fallback step — never derived from the label, never truncated (FR-003). Catalog guidance: one to two characters. With a label present the initials are presentational; assistive technology receives the label alone. - `label` (string | undefined): Accessible name for the identity ("Ana García"). With a label the avatar is exposed as a named non-interactive image (role `img`) in every content mode — the portrait never carries a second alternative text of its own. Without a label the avatar is decorative and contributes nothing to the accessibility tree; the identity must then live in adjacent visible text (FR-002). - `size` ("lg" | "md" | "sm" | "xl" | "xs" | "xxs", default 'md'): Size step over the shared scale; per-size metrics (box, initials font, figure glyph) are per-theme component tokens, never hardcoded (FR-004). An unrecognized value matches no style selector, so the avatar keeps the default medium metrics (fallback by CSS construction, FR-007). - `src` (string | undefined, URL): Portrait URL, the first step of the fallback chain. When it fails to load — initially or at runtime — the avatar silently falls back to the initials (or the generic figure) with no error, no layout change and no event (FR-001). Loading policy follows the platform image defaults. Slots: - `counter`: Decorative ki-counter. Counts sit at block-start inline-end and dots at block-end inline-end. Include its meaning in the avatar label. Parts: - `avatar`: The avatar box: size, shape, surface, border and typography. - `icon`: The built-in generic person figure of the last fallback step. - `image`: The portrait image when `src` is set and loads. - `initials`: The verbatim initials text of the second fallback step. Events: none Methods: none CSS custom properties: - `--ki-avatar-bg`: color used by the avatar component for the initials/figure surface: Surface/primary_med_em, the exact variable behind the Type=text gradient start and the Type=icon solid fill. The Figma text gradient (primary_med_em -> primary_low_em_alpha 20%) is deliberately flattened to its solid start color — the token pipeline models no gradients and the spec defines one family-level bg (declared deviation, specs/019-ki-avatar/design-extraction.md decision 2, pending founder ratification). - `--ki-avatar-border-color`: color used by the avatar component for the surface border: Outline/base_em (Black/3 light, White/3 dark), the exact variable on Type=text variants. - `--ki-avatar-border-width`: dimension used by the avatar component for the surface border (MarsUI 1px hairline on Type=text; applied to the token surface behind initials and figure, dropped under a loaded portrait — design-extraction decision 4). - `--ki-avatar-fg`: color used by the avatar component for the initials text and the generic-figure glyph (via currentColor): Text/primary_on_primary, the exact variable on every Type=text variant. - `--ki-avatar-font-family`: font family used by the avatar component for initials (MarsUI Typeface/family/body: Inter). - `--ki-avatar-font-weight`: font weight used by the avatar component for initials (MarsUI Typeface/weight/body/medium: 600). - `--ki-avatar-lg-font-size`: dimension used by the avatar component for lg initials (MarsUI UI/Body 2: 15px). - `--ki-avatar-lg-icon-size`: dimension used by the avatar component for the lg generic-figure glyph (MarsUI Icon/User 24px, Space/7xl). - `--ki-avatar-lg-size`: dimension used by the avatar component for the lg box (48px circle, Figma Space/14xl). - `--ki-avatar-md-font-size`: dimension used by the avatar component for md initials (MarsUI UI/Para: body_1 13px). - `--ki-avatar-md-icon-size`: dimension used by the avatar component for the md generic-figure glyph (MarsUI Icon/User 20px, Space/5xl). - `--ki-avatar-md-size`: dimension used by the avatar component for the md box (40px circle, Figma Space/12xl, node 10011:947). - `--ki-avatar-radius`: dimension used by the avatar component for the shape: Radius/radius_round bound to every avatar variant — the circle is a radius token, never an attribute (002 shape precedent, FR-005). - `--ki-avatar-sm-font-size`: dimension used by the avatar component for sm initials (MarsUI UI/Caption 2: 12px). - `--ki-avatar-sm-icon-size`: dimension used by the avatar component for the sm generic-figure glyph (MarsUI Icon/User 18px, Space/4xl). - `--ki-avatar-sm-size`: dimension used by the avatar component for the sm box (32px circle, Figma Space/10xl). - `--ki-avatar-xl-font-size`: dimension used by the avatar component for xl initials (MarsUI UI/Title 2: 18px). - `--ki-avatar-xl-icon-size`: dimension used by the avatar component for the xl generic-figure glyph (MarsUI Icon/User 28px, Space/9xl). - `--ki-avatar-xl-size`: dimension used by the avatar component for the xl box (56px circle, Figma Space/16xl). - `--ki-avatar-xs-font-size`: dimension used by the avatar component for xs initials (MarsUI UI/Caption 1: 10px, same step as xxs — verified on Type=text Size=xs 10108:6226). - `--ki-avatar-xs-icon-size`: dimension used by the avatar component for the xs generic-figure glyph (MarsUI Icon/User 14px, same step as xxs — NOT the icon-button 16px ramp; verified on 10108:6230). - `--ki-avatar-xs-size`: dimension used by the avatar component for the xs box (24px circle, Figma Space/7xl). - `--ki-avatar-xxs-font-size`: dimension used by the avatar component for xxs initials (MarsUI UI/Caption 1: 10px). - `--ki-avatar-xxs-icon-size`: dimension used by the avatar component for the xxs generic-figure glyph (MarsUI Icon/User 14px, Space/2xl). - `--ki-avatar-xxs-size`: dimension used by the avatar component for the xxs box (20px circle, Figma Space/5xl; specs/019-ki-avatar/design-extraction.md). - `--ki-counter-ring-width`: Thickness of the separating ring. - `--ki-motion-duration-fast`: Fast interaction transition duration. - `--ki-motion-easing-out`: Decelerating interaction transition easing curve. ### ki-avatar-group A token-styled companion container that stacks `ki-avatar` children as one overlapping row with a configurable visible cap and a static "+N" overflow counter. When to use: a compact "who is involved" stack — the members of a shared document, project card or event row — where space deserves only the first few identities and an exact "+N" counter accounts for the rest. When NOT to use: as a member picker or expandable overflow (future interactive grouping — the counter is static text, never a button), for a single identity (use `ki-avatar` alone), or with children other than `ki-avatar` (foreign markup is unsupported and not repaired, 016 precedent). Examples: `max` caps the visible stack; members beyond the cap are neither rendered nor exposed to assistive technology, and a static "+N" counter accounts exactly for the hidden rest: ```html ``` Without `max` — or with a cap that is not a positive whole number — every member renders and no counter appears (never "+0"): ```html ``` The group's `size` governs every visible member and the counter, overriding member-declared sizes so the stack stays uniform: ```html ``` Attributes: - `max` (number | undefined): Visible cap for the member stack. When the member count exceeds it, the first `max` members render followed by a "+N" counter accounting exactly for the hidden rest. Without it — or when it is not a positive whole number — every member renders and no counter appears; malformed agent-generated markup never breaks the page (FR-009, S14, S15). - `size` ("lg" | "md" | "sm" | "xl" | "xs" | "xxs", default 'md'): Size step governing the metrics of every visible member and the counter (avatar vocabulary, FR-010). Member-declared sizes are overridden inside a group so the stack stays uniform (S6). An unrecognized value matches no style selector, so the group keeps the default medium metrics (FR-007). Slots: - (default): `ki-avatar` members, stacked in source order. Members beyond the visible cap are neither rendered nor exposed to assistive technology. Parts: - `counter`: The static "+N" overflow text trailing the stack. - `group`: The stack row containing the members and the counter. Events: none Methods: none CSS custom properties: - `--ki-avatar-font-family`: font family used by the avatar component for initials (MarsUI Typeface/family/body: Inter). - `--ki-avatar-font-weight`: font weight used by the avatar component for initials (MarsUI Typeface/weight/body/medium: 600). - `--ki-avatar-group-counter-bg`: color used by the avatar group component for the +N counter surface: Surface/special/secondary_alpha_base, the exact variable on the secondary-button-styled counter of every capped Avatar_group frame. - `--ki-avatar-group-counter-border-color`: color used by the avatar group component for the counter border: Outline/secondary_button_top, the exact variable on the counter pill (the secondary-button bevel top edge). - `--ki-avatar-group-counter-border-width`: dimension used by the avatar group component for the counter border (MarsUI 1px hairline on the counter pill). - `--ki-avatar-group-counter-fg`: color used by the avatar group component for the +N counter text: Text/high_em, the exact variable on the counter label. - `--ki-avatar-group-counter-radius`: dimension used by the avatar group component for the counter shape: Radius/component/radius_* resolves to 1000 in the MarsUI Round mode — the pill is a radius token, never an attribute. - `--ki-avatar-group-counter-shadow`: shadow used by the avatar group component for the counter effects: the exact Component_effect/secondary_default pair (drop 0/2/1.5/-0.5 Elevation/shadow + inner White/3 0/2/3) without its backdrop blur (glass restraint, 021 decision 3). - `--ki-avatar-group-lg-counter-font-size`: dimension used by the avatar group component for the lg counter text (body_2 15px on the 48px frame). - `--ki-avatar-group-lg-counter-padding-inline`: dimension used by the avatar group component for the lg counter inline padding (Space/xl 12px on the 48px frame). - `--ki-avatar-group-lg-overlap`: dimension used by the avatar group component for the lg member overlap (the exact -12px on the 48px Avatar_group frame 10090:2873). - `--ki-avatar-group-md-counter-font-size`: dimension used by the avatar group component for the md counter text (body_1 13px on the 40px frame). - `--ki-avatar-group-md-counter-padding-inline`: dimension used by the avatar group component for the md counter inline padding (Space/lg 10px on the 40px frame). - `--ki-avatar-group-md-overlap`: dimension used by the avatar group component for the md member overlap (the exact -12px on the 40px Avatar_group frame 10087:2701). - `--ki-avatar-group-ring-color`: color used by the avatar group component for the separating ring: transparent while the onmars ring width is zero (FR-008; a future theme may resolve both). - `--ki-avatar-group-ring-width`: dimension used by the avatar group component for the separating ring around stacked members: NO Avatar_group frame draws a ring (verified across all five sizes), so onmars resolves the capability to zero — the ring stays a theme decision, never an attribute (FR-008). - `--ki-avatar-group-sm-counter-font-size`: dimension used by the avatar group component for the sm counter text (body_1 13px on the 32px frame — one step above the sm initials, verified). - `--ki-avatar-group-sm-counter-padding-inline`: dimension used by the avatar group component for the sm counter inline padding (Space/md 8px on the 32px frame). - `--ki-avatar-group-sm-overlap`: dimension used by the avatar group component for the sm member overlap (the exact -8px on the 32px Avatar_group frame 10087:2601). - `--ki-avatar-group-xl-counter-font-size`: dimension used by the avatar group component for the xl counter text (title_2 18px on the 56px frame). - `--ki-avatar-group-xl-counter-padding-inline`: dimension used by the avatar group component for the xl counter inline padding (Space/2xl 14px on the 56px frame). - `--ki-avatar-group-xl-overlap`: dimension used by the avatar group component for the xl member overlap (the exact -12px on the 56px Avatar_group frame 10090:2973). - `--ki-avatar-group-xs-counter-font-size`: dimension used by the avatar group component for the xs counter text (synthesized 24px step following the avatar xs initials size, declared for founder review). - `--ki-avatar-group-xs-counter-padding-inline`: dimension used by the avatar group component for the xs counter inline padding (synthesized 24px step extending the verified 8/10/12/14 ramp, declared for founder review). - `--ki-avatar-group-xs-overlap`: dimension used by the avatar group component for the xs member overlap: the 24px group step exists in no Figma frame (five-step set), so it inherits the -8px overlap of the neighboring 20/32px frames (synthesized step, spec 019 Assumptions). - `--ki-avatar-group-xxs-counter-font-size`: dimension used by the avatar group component for the xxs counter text: no counter exists on the 20px frame, so the value follows the avatar xxs initials step (synthesized, declared for founder review). - `--ki-avatar-group-xxs-counter-padding-inline`: dimension used by the avatar group component for xxs counter padding inline (raised to clear the 8px member tuck so the + glyph is never occluded; the 20px Figma frame ships no counter — synthesized step, founder review pending). - `--ki-avatar-group-xxs-overlap`: dimension used by the avatar group component for the xxs member overlap (the -8px stack step on the 20px Avatar_group frame — named xs in Figma, the vocabulary skew recorded in spec 019 Assumptions). - `--ki-avatar-lg-font-size`: dimension used by the avatar component for lg initials (MarsUI UI/Body 2: 15px). - `--ki-avatar-lg-icon-size`: dimension used by the avatar component for the lg generic-figure glyph (MarsUI Icon/User 24px, Space/7xl). - `--ki-avatar-lg-size`: dimension used by the avatar component for the lg box (48px circle, Figma Space/14xl). - `--ki-avatar-md-font-size`: dimension used by the avatar component for md initials (MarsUI UI/Para: body_1 13px). - `--ki-avatar-md-icon-size`: dimension used by the avatar component for the md generic-figure glyph (MarsUI Icon/User 20px, Space/5xl). - `--ki-avatar-md-size`: dimension used by the avatar component for the md box (40px circle, Figma Space/12xl, node 10011:947). - `--ki-avatar-radius`: dimension used by the avatar component for the shape: Radius/radius_round bound to every avatar variant — the circle is a radius token, never an attribute (002 shape precedent, FR-005). - `--ki-avatar-sm-font-size`: dimension used by the avatar component for sm initials (MarsUI UI/Caption 2: 12px). - `--ki-avatar-sm-icon-size`: dimension used by the avatar component for the sm generic-figure glyph (MarsUI Icon/User 18px, Space/4xl). - `--ki-avatar-sm-size`: dimension used by the avatar component for the sm box (32px circle, Figma Space/10xl). - `--ki-avatar-xl-font-size`: dimension used by the avatar component for xl initials (MarsUI UI/Title 2: 18px). - `--ki-avatar-xl-icon-size`: dimension used by the avatar component for the xl generic-figure glyph (MarsUI Icon/User 28px, Space/9xl). - `--ki-avatar-xl-size`: dimension used by the avatar component for the xl box (56px circle, Figma Space/16xl). - `--ki-avatar-xs-font-size`: dimension used by the avatar component for xs initials (MarsUI UI/Caption 1: 10px, same step as xxs — verified on Type=text Size=xs 10108:6226). - `--ki-avatar-xs-icon-size`: dimension used by the avatar component for the xs generic-figure glyph (MarsUI Icon/User 14px, same step as xxs — NOT the icon-button 16px ramp; verified on 10108:6230). - `--ki-avatar-xs-size`: dimension used by the avatar component for the xs box (24px circle, Figma Space/7xl). - `--ki-avatar-xxs-font-size`: dimension used by the avatar component for xxs initials (MarsUI UI/Caption 1: 10px). - `--ki-avatar-xxs-icon-size`: dimension used by the avatar component for the xxs generic-figure glyph (MarsUI Icon/User 14px, Space/2xl). - `--ki-avatar-xxs-size`: dimension used by the avatar component for the xxs box (20px circle, Figma Space/5xl; specs/019-ki-avatar/design-extraction.md). - `--ki-effect-component-secondary-hover-shadow`: MarsUI Component_effect/secondary_hover: drops as primary_hover plus inner White/8 0/2/3. Pair with --ki-effect-component-backdrop-filter. - `--ki-motion-duration-fast`: Fast interaction transition duration. - `--ki-motion-duration-medium-1`: M3 md.sys.motion.duration.medium1 (250ms). onmars: MarsUI moderate step (240ms, 2x the 120ms base). - `--ki-motion-easing-out`: Decelerating interaction transition easing curve. - `--ki-motion-easing-standard`: Standard interaction transition easing curve. ### ki-badge A static, non-interactive status pill. When to use: annotate an entity with short status text (a state, a category) whose meaning is carried by the label itself; the tone color only reinforces the text, it never replaces it. When NOT to use: feedback that must be announced (that is ki-alert's job — the badge has no live region), an interactive chip, filter or button, empty content (the label IS the meaning), or a notification-counter overlay (use ki-counter). Examples: The slotted label is the sole carrier of meaning; `tone` only reinforces it with the `--ki-badge-{tone}-*` token colors, and an unrecognized value keeps the neutral appearance: ```html Draft Beta Active Trial ends soon Suspended ``` `size` selects the metric scale (`sm` or `md`, default `md`): ```html Synced ``` A typical placement — trailing status on a list entry: ```html Production deploy Healthy ``` Attributes: - `size` ("md" | "sm" | "xs", default 'md'): Metric scale (`--ki-badge-{size}-*` tokens): 20, 24 or 28px tall in onmars, with 12px text at every size. An unrecognized value falls back to the `md` metrics the same way. - `tone` ("danger" | "info" | "neutral" | "success" | "warning", default 'neutral'): Semantic intent, never appearance: each tone resolves its colors from the `--ki-badge-{tone}-*` tokens. An unrecognized value matches no style selector, so the badge keeps the neutral appearance (fallback by CSS construction — no validation code). Slots: - (default): The label: short status text, the sole carrier of meaning. Parts: - `badge`: The pill: background, foreground, border, radius, metrics and typography. Events: none Methods: none CSS custom properties: - `--ki-badge-backdrop-filter`: Complete backdrop filter for the neutral badge surface. - `--ki-badge-border-width`: dimension used by the badge component for border width (MarsUI tone tags carry width 0 in default state; only the neutral glass type draws its 1px bevel via ki.badge.neutral.border-width. material3 keeps its border via its override). - `--ki-badge-danger-bg`: color used by the badge component for danger background (MarsUI Surface/danger_base_em_alpha: tone-500 at 12% light — the tint composites over any surface and the dark alias adapts automatically). - `--ki-badge-danger-border`: color used by the badge component for danger border. - `--ki-badge-danger-fg`: color used by the badge component for danger foreground. - `--ki-badge-font-family`: font family used by the badge component for font family. - `--ki-badge-font-weight`: font weight used by the badge component for font weight. - `--ki-badge-info-bg`: color used by the badge component for info background (MarsUI Surface/info_base_em_alpha: tone-500 at 12% light — the tint composites over any surface and the dark alias adapts automatically). - `--ki-badge-info-border`: color used by the badge component for info border. - `--ki-badge-info-fg`: color used by the badge component for info foreground. - `--ki-badge-md-font-size`: dimension used by the badge component for md font size (MarsUI UI/Caption 2: 12px at both sm and md; only xs drops to Caption 1). - `--ki-badge-md-height`: dimension used by the badge component for md height (MarsUI Tag md outer height 28px). - `--ki-badge-md-line-height`: dimension used by the badge component for md line height (MarsUI caption_2 16px). - `--ki-badge-md-padding-inline`: dimension used by the badge component for md padding inline (MarsUI total text inset 10px; paired with the border-width 0 + border-box change so the badge does not shrink). - `--ki-badge-md-radius`: dimension used by the badge component for md radius (MarsUI Tag: Radius/component/radius_sm 8px at both sm and md). - `--ki-badge-neutral-bg`: color used by the badge component for neutral background (MarsUI secondary glass Tag: Surface/special/secondary_alpha_base Gray-100 alpha light / Dark-700 blur base dark — the same fill as ki-button secondary; completes the glass bevel/blur/shadow the component already draws. material3 keeps the opaque s2 chip via its override). - `--ki-badge-neutral-border`: color used by the badge component for neutral border (MarsUI secondary Tag bevel: Outline/secondary_button_top; drawn at ki.badge.neutral.border-width). - `--ki-badge-neutral-border-width`: dimension used by the badge component for the neutral (secondary glass) border width: MarsUI draws the 1px bevel only on this type. - `--ki-badge-neutral-fg`: color used by the badge component for neutral foreground. - `--ki-badge-sm-font-size`: dimension used by the badge component for sm font size. - `--ki-badge-sm-height`: dimension used by the badge component for sm height. - `--ki-badge-sm-line-height`: dimension used by the badge component for sm line height. - `--ki-badge-sm-padding-inline`: dimension used by the badge component for sm padding inline (MarsUI total text inset 8px; paired with the border-width 0 + border-box change). - `--ki-badge-sm-radius`: dimension used by the badge component for sm radius (MarsUI Tag silhouette is an 8px rounded rect — Radius/component/radius_sm — never a pill). - `--ki-badge-success-bg`: color used by the badge component for success background (MarsUI Surface/success_base_em_alpha: tone-500 at 12% light — the tint composites over any surface and the dark alias adapts automatically). - `--ki-badge-success-border`: color used by the badge component for success border. - `--ki-badge-success-fg`: color used by the badge component for success foreground. - `--ki-badge-warning-bg`: color used by the badge component for warning background (MarsUI Surface/warning_base_em_alpha: tone-500 at 12% light — the tint composites over any surface and the dark alias adapts automatically). - `--ki-badge-warning-border`: color used by the badge component for warning border. - `--ki-badge-warning-fg`: color used by the badge component for warning foreground. - `--ki-badge-xs-font-size`: dimension used by the badge component for xs font size (Tag 10106:4651 xs). Figma draws caption_1, 10px; caption_2, 12px, is the smallest text the library ships (spec 050 D7). - `--ki-badge-xs-height`: dimension used by the badge component for xs height (Tag 10106:4651 xs: 20px). - `--ki-badge-xs-line-height`: dimension used by the badge component for xs line height (caption_2 16px, the same height as caption_1). - `--ki-badge-xs-padding-inline`: dimension used by the badge component for xs padding inline (Tag 10106:4651 xs: Space/xs plus the Text_wrap Space/xxs, 6px). - `--ki-badge-xs-radius`: dimension used by the badge component for xs radius (Tag 10106:4651 xs binds Radius/small-component/xs). - `--ki-effect-component-secondary-default-shadow`: MarsUI Component_effect/secondary_default: drop 0/2/1.5/-0.5 plus inner White/3 0/2/3. Pair with --ki-effect-component-backdrop-filter. - `--ki-motion-duration-fast`: Fast interaction transition duration. - `--ki-motion-easing-out`: Decelerating interaction transition easing curve. - `--ki-outline-secondary-button-bottom`: semantic color for outline secondary button bottom. ### ki-breadcrumb A path of ancestor links ending at the current page, with optional overflow. When to use: show the current page in a deeper hierarchy using direct ki-breadcrumb-item children ordered from root to current. When NOT to use: switch between peer routes, toggle peer panels, or display progress through a form. Examples: ## Show the path to the current page ```html Workspace Projects Settings ``` ## Collapse middle levels ```html Workspace Projects Kimen Packages Releases v2.4.0 ``` In this example the overflow has three levels. The trail shows Workspace, the overflow button, Releases, and v2.4.0. ## Render a guarded breadcrumb Put breadcrumb items in the default slot and supply plain-text item labels. The surface's URL policy applies to each destination. Native links have no custom action binding. ```json { "version": 1, "root": { "component": "ki-breadcrumb", "props": { "label": "Project path" }, "slots": { "": [ { "component": "ki-breadcrumb-item", "props": { "href": "/workspace" }, "slots": { "": ["Workspace"] } }, { "component": "ki-breadcrumb-item", "props": { "current": true }, "slots": { "": ["Settings"] } } ] } } } ``` Attributes: - `label` (string, default 'Breadcrumb'): Accessible name of the navigation landmark. - `max-items` (number | undefined): Optional overflow threshold. Above it, keep the first and last two levels visible. Positive values are rounded down and clamped to four. Omit this prop, or pass a non-positive or non-finite value, to show the full trail. - `more-label` (string, default 'Show {n} more levels'): Localizable name of the overflow control. Use {n} for the hidden level count. Slots: - (default): Direct ki-breadcrumb-item children in hierarchy order. Parts: - `current`: The current page label. - `label`: The label of an ancestor with no destination. - `link`: A visible native ancestor link. - `list`: The ordered list of visible levels. - `list-item`: A list entry for a level or the overflow control. - `menu`: The anchored menu of collapsed levels. - `menu-item`: A destination or unavailable level in the overflow menu. - `more-button`: The overflow menu button. - `navigation`: The named navigation landmark. Events: none Methods: none CSS custom properties: - `--ki-breadcrumb-bg`: Transparent backing for ancestor text and the overflow trigger. - `--ki-breadcrumb-current-bg`: Transparent backing for the current level. - `--ki-breadcrumb-current-fg`: Emphasized foreground of the current level. - `--ki-breadcrumb-fg`: Medium-emphasis ink for ancestors and the overflow trigger, strengthened in more-contrast mode. - `--ki-breadcrumb-gap`: Gap between breadcrumb rows, levels and their chevrons. - `--ki-breadcrumb-glyph-size`: Size of the ellipsis glyph. - `--ki-breadcrumb-hover-bg`: Backing for the active overflow trigger and highlighted overflow links. - `--ki-breadcrumb-hover-fg`: Foreground for the active overflow trigger and highlighted overflow links. - `--ki-breadcrumb-menu-backdrop-filter`: Complete backdrop filter of the overflow menu, none by default. - `--ki-breadcrumb-menu-bg`: Surface behind the overflow menu entries. - `--ki-breadcrumb-menu-bg-image`: Optional image layered over the overflow menu surface. - `--ki-breadcrumb-menu-fg`: Text of overflow menu entries. - `--ki-breadcrumb-menu-max-block-size`: Maximum block size of the scrollable overflow menu. - `--ki-breadcrumb-menu-padding`: Inset around the overflow menu entries. - `--ki-breadcrumb-menu-radius`: Outer radius of the overflow menu. - `--ki-breadcrumb-menu-shadow`: Elevation of the overflow menu above the page. - `--ki-breadcrumb-padding-block`: Block inset of a level label. - `--ki-breadcrumb-padding-inline`: Inline inset of a level label. - `--ki-breadcrumb-radius`: Radius of the overflow trigger and level focus outlines. - `--ki-breadcrumb-separator`: Foreground of the decorative breadcrumb chevron. - `--ki-breadcrumb-separator-size`: Edge length of the decorative chevron before rotation. - `--ki-breadcrumb-separator-stroke`: Stroke width of the decorative chevron. - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-offset`: Gap between a focusable component and its keyboard focus ring. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. - `--ki-typography-family-body`: semantic font family for typography family body. - `--ki-typography-line-height-body-1`: semantic dimension for typography line height body 1. - `--ki-typography-size-body-1`: semantic dimension for typography size body 1. - `--ki-typography-underline-offset`: Gap between text and its underline. - `--ki-typography-weight-body-medium`: semantic font weight for typography weight body medium. ### ki-breadcrumb-item One declarative level in a breadcrumb path. When to use: declare a direct child of ki-breadcrumb in hierarchy order. Give ancestors an href and use short text labels. The last level is the current page. When NOT to use: render a standalone link or display an interactive control inside the label. Examples: Place each item directly inside a breadcrumb. Use the item's text for its label and add `href` to link to an ancestor page. A level without `href` provides context as text. Put the current page last. ```html Workspace Administration Settings ``` Attributes: - `current` (boolean, default false): Explicitly marks the final level as current. The owning breadcrumb treats its final level as current by position, including when this marker is omitted. - `href` (string | undefined, URL): Native destination for an ancestor level. Leaves the label as text when omitted. The final level never links away from the current page. Slots: - (default): Plain-text label mirrored by the owning breadcrumb. Parts: none Events: none Methods: none CSS custom properties: - `--ki-typography-family-body`: semantic font family for typography family body. ### ki-button A token-styled action button with native button semantics. When to use: trigger the single main action of a view, supporting actions in descending hierarchy, confirming/destructive actions through tone, or persistent actions such as Bold with `toggle`. While the action a button started is in progress, set `loading` on that button instead of disabling it. When NOT to use: navigation, icon-only actions, form values, or the progress of a page or region (use ki-progress). Examples: A standalone primary action: ```html Save ``` In momentary mode `type` defaults to `submit`. Use `type="button"` for an independent action inside a form. ```html
Cancel Save changes
``` Use `toggle` for a persistent action. `selected` sets the starting state and each activation changes `aria-pressed` while keeping the label. Toggle mode acts independently of form submission and reset, regardless of `type`. ```html Pin ``` Programmatic writes to `selected` are silent. A parent coordinating several toggles can listen for their bubbling `ki-change` events and update their `selected` values together. Open a dialog with `command="show-modal"` and its ID in `commandfor`. The dialog and invoker share a document or shadow root. The command takes precedence over form submission or reset. ```html Preview draft This draft is visible only to you. Done ``` Programmatic creation after registration; string attributes and properties are interchangeable: ```ts import { defineCustomElement } from '@kimen/elements/ki-button'; defineCustomElement(); const saveButton = document.createElement('ki-button'); saveButton.setAttribute('type', 'button'); saveButton.textContent = 'Save'; document.body.append(saveButton); ``` While the action a button started is in progress, set `loading` on it instead of `disabled`: it keeps its width and focus, ignores further activation (it neither submits nor resets its form), draws a spinner in place of its label and announces `loading-label` (default "Loading") as a polite status message. Clear it when the action ends: ```html
Save changes
``` Attributes: - `command` ("close" | "request-close" | "show-modal" | undefined): Dialog action to run for `commandfor`. Use `show-modal` to open, `close` for direct dismissal, or `request-close` for guarded dismissal. Choose a command for local dialog control and omit it for other actions. - `commandfor` (string | undefined): ID of a ki-dialog in the same document or shadow tree as this button. Set it together with `command` to connect a dialog declaratively. - `disabled` (boolean, default false): Prevents activation, removes the button from keyboard reach, and exposes the unavailable state through the internal native button. Wins over `loading` when both are set. When NOT to use: do not use disabled for pending/loading semantics; use `loading`. - `loading` (boolean, default false): Pending state of the action this button started (saving, sending). While set, every activation is blocked (pointer, Enter and Space) and the button neither submits nor resets its form, but it stays focusable, in the Tab order and at its width: the label stays laid out, transparent, and a spinner is drawn in its place. The internal native button is exposed with `aria-disabled="true"` and keeps its name, and `loadingLabel` is announced as a polite status message. `disabled`, and a disabled fieldset, win over it. The application sets it when the action starts and clears it when the action ends. When to use: while the work a click on this button started is running, so a second activation cannot repeat it. When NOT to use: for a button the person cannot use yet (use `disabled`), or for the progress of a page or region (use ki-progress). - `loading-label` (string, default 'Loading'): Text of the polite status message announced while `loading` is set. Override for localization; the default English string is the button's only built-in user-visible text. When to use: provide a localized message whenever the document language is not English, or a more specific one ("Saving"). When NOT to use: do not repeat the button's label here; the person already hears it on focus. - `name` (string | undefined): Form-data key contributed when this button submits its form. When NOT to use: omit when no submitter value should be sent. - `selected` (boolean, default false): Current press state in toggle mode. Set this to initialize or synchronize the state programmatically without emitting a change. - `size` ("lg" | "md" | "sm" | "xl" | "xs", default 'md'): Token-backed button size. Every size keeps at least the minimum pointer target; choose the size that matches the density of the surrounding UI. When NOT to use: do not use `ki-button` for icon-only compact controls. - `toggle` (boolean, default false): Enables persistent press state for an action such as Bold. The native button exposes `aria-pressed` and each activation switches `selected`. Use the same label in both states. A toggle does not submit or reset a form. - `tone` ("danger" | "neutral" | "success", default 'neutral'): Semantic intent for the action, independent of hierarchy. Use `success` for confirming actions and `danger` for destructive actions. Toggle palettes are specific to the variant. When NOT to use: do not use tone for visual hierarchy; use `variant`. - `type` ("button" | "reset" | "submit", default 'submit'): Native form action type: `submit` submits the owning form (running constraint validation and contributing `name`/`value` to the form data), `reset` restores field defaults, and `button` leaves the form alone. Toggle mode and configured dialog commands take precedence over form actions. Cancel a submission from the form's `submit` event (`preventDefault()`); unlike a native button, `preventDefault()` on the `click` event does not cancel it. During submission `event.submitter` is a transient native button carrying this element's `name`/`value`, not the `ki-button` host. When NOT to use: use `button` when the action must never submit a form. - `value` (string | undefined): Form-data value paired with `name` when this button submits its form. When NOT to use: omit when the default empty submitter value is intended. - `variant` ("ghost" | "outline" | "primary" | "quaternary" | "secondary" | "tertiary", default 'secondary'): Visual hierarchy for the action. Use filled `primary` for the single main action, outlined `secondary` for supporting actions, `quaternary` for neutral text actions, `ghost` for accent text actions and `outline` for an unfilled action with a visible boundary. When NOT to use: do not use variant to signal success or danger; use `tone` for intent. Slots: - (default): Label content. This is the accessible name source. - `end`: Trailing icon or media. Follows writing direction. - `start`: Leading icon or media. Follows writing direction. Parts: - `button`: Internal native button. - `label`: Label wrapper around the default slot. - `spinner`: Loading spinner drawn at the center of the button, in the button's foreground ink, rendered only while `loading` is in effect. Events: - `ki-change` (CustomEvent<{ selected: boolean }>): Emitted after toggle activation with the new selected state. Methods: none CSS custom properties: - `--ki-button-backdrop-filter`: Complete backdrop filter for glass button and icon-button variants. - `--ki-button-border-width`: dimension used by the button component for border width (MarsUI bevel/outline stroke: 1px). - `--ki-button-focus-ring-color`: color used by the button component for focus ring color. - `--ki-button-focus-ring-offset`: dimension used by the button component for focus ring offset. - `--ki-button-focus-ring-shadow`: shadow used by the button component for the focus ring glow (MarsUI Focus/primary: 3px spread ring). - `--ki-button-focus-ring-width`: dimension used by the button component for focus ring width. - `--ki-button-font-family`: font family used by the button component for font family. - `--ki-button-font-weight`: font weight used by the button component for font weight. - `--ki-button-ghost-danger-hover-bg`: color used by the button component for ghost danger hover background. - `--ki-button-ghost-danger-hover-border`: color used by the button component for ghost danger hover border. - `--ki-button-ghost-danger-hover-fg`: color used by the button component for ghost danger hover foreground. - `--ki-button-ghost-danger-rest-bg`: color used by the button component for ghost danger rest background. - `--ki-button-ghost-danger-rest-border`: color used by the button component for ghost danger rest border. - `--ki-button-ghost-danger-rest-fg`: color used by the button component for ghost danger rest foreground. - `--ki-button-ghost-disabled-shadow`: value used by the button component for ghost disabled shadow. - `--ki-button-ghost-hover-shadow`: value used by the button component for ghost hover shadow. - `--ki-button-ghost-neutral-disabled-bg`: color used by the button component for ghost neutral disabled background. - `--ki-button-ghost-neutral-disabled-border`: color used by the button component for ghost neutral disabled border. - `--ki-button-ghost-neutral-disabled-fg`: color used by the button component for ghost neutral disabled foreground. - `--ki-button-ghost-neutral-hover-bg`: color used by the button component for ghost neutral hover background. - `--ki-button-ghost-neutral-hover-border`: color used by the button component for ghost neutral hover border. - `--ki-button-ghost-neutral-hover-fg`: color used by the button component for ghost neutral hover foreground. - `--ki-button-ghost-neutral-rest-bg`: color used by the button component for ghost neutral rest background. - `--ki-button-ghost-neutral-rest-border`: color used by the button component for ghost neutral rest border. - `--ki-button-ghost-neutral-rest-fg`: color used by the button component for ghost neutral rest foreground. - `--ki-button-ghost-rest-shadow`: value used by the button component for ghost rest shadow. - `--ki-button-ghost-selected-bg`: Background of the selected ghost button toggle. - `--ki-button-ghost-selected-fg`: Foreground of the selected ghost button toggle. - `--ki-button-ghost-success-hover-bg`: color used by the button component for ghost success hover background. - `--ki-button-ghost-success-hover-border`: color used by the button component for ghost success hover border. - `--ki-button-ghost-success-hover-fg`: color used by the button component for ghost success hover foreground. - `--ki-button-ghost-success-rest-bg`: color used by the button component for ghost success rest background. - `--ki-button-ghost-success-rest-border`: color used by the button component for ghost success rest border. - `--ki-button-ghost-success-rest-fg`: color used by the button component for ghost success rest foreground. - `--ki-button-label-padding-inline`: dimension used by the button component for the label Text_wrap inline padding (MarsUI 8003:300: 4px each side of the label; the flex gap subtracts the same value so icon-to-text keeps the composite distance). - `--ki-button-lg-font-size`: dimension used by the button component for lg font size. - `--ki-button-lg-gap`: dimension used by the button component for lg gap. - `--ki-button-lg-height`: dimension used by the button component for lg height. - `--ki-button-lg-icon-size`: dimension used by the button component for lg icon size. - `--ki-button-lg-line-height`: dimension used by the button component for lg line height. - `--ki-button-lg-min-target`: dimension used by the button component for lg min target. - `--ki-button-lg-padding-inline`: dimension used by the button component for lg padding inline. - `--ki-button-lg-radius`: dimension used by the button component for lg radius (Button master 8003:300 binds Radius/small-component/lg, the scale a radius mode reassigns). - `--ki-button-lg-spinner-size`: dimension used by the button component for the lg loading spinner box (20px, the lg icon size; spec 046 D5: no Figma source, the spinner takes the place of the content). - `--ki-button-md-font-size`: dimension used by the button component for md font size. - `--ki-button-md-gap`: dimension used by the button component for md gap (MarsUI effective icon-to-text gap 6px). - `--ki-button-md-height`: dimension used by the button component for md height. - `--ki-button-md-icon-size`: dimension used by the button component for md icon size. - `--ki-button-md-line-height`: dimension used by the button component for md line height. - `--ki-button-md-min-target`: dimension used by the button component for md min target. - `--ki-button-md-padding-inline`: dimension used by the button component for md padding inline. - `--ki-button-md-radius`: dimension used by the button component for md radius (Button master 8003:300 binds Radius/small-component/md, the scale a radius mode reassigns). - `--ki-button-md-spinner-size`: dimension used by the button component for the md loading spinner box (18px, the md icon size; spec 046 D5: no Figma source, the spinner takes the place of the content). - `--ki-button-outline-rest-bg`: Background of the outline variant at rest. - `--ki-button-outline-rest-border`: Visible outline of the outline variant at rest. - `--ki-button-outline-rest-fg`: Foreground of the outline variant at rest. - `--ki-button-outline-selected-bg`: Background of the selected outline button toggle. - `--ki-button-outline-selected-fg`: Foreground of the selected outline button toggle. - `--ki-button-padding-block`: dimension used by the button component for padding block (MarsUI: 4px in every size). - `--ki-button-primary-active-overlay`: Pressed state layer for the primary button: primary paints on a dark brand fill, so its wash lightens: the next rung above ki.surface.hover-overlay (White/5 -> White/8 light). Replaces this variant's share of a 45-cell active bg/fg/border matrix whose values were documented mirrors of rest and which WITHDREW the hover overlay rather than deepening it, an appearance legible only to a pointer user who had hovered first. - `--ki-button-primary-danger-hover-bg`: color used by the button component for primary danger hover background (MarsUI: rest fill; hover lightening comes from the hover overlay). - `--ki-button-primary-danger-hover-border`: color used by the button component for primary danger hover border (MarsUI bevel top/inline edge). - `--ki-button-primary-danger-hover-fg`: color used by the button component for primary danger hover foreground. - `--ki-button-primary-danger-rest-bg`: color used by the button component for primary danger rest background. Deliberate deviation: Figma specifies the 500 ramp (Surface/danger_med_em #f05149) but white on 500 is ≈3.5:1 < AA 4.5:1; Kimen keeps the 700 ramp (precedent 010 D2, pending founder ratification). - `--ki-button-primary-danger-rest-border`: color used by the button component for primary danger rest border (MarsUI bevel top/inline edge). - `--ki-button-primary-danger-rest-fg`: color used by the button component for primary danger rest foreground. - `--ki-button-primary-disabled-shadow`: value used by the button component for primary disabled shadow. - `--ki-button-primary-hover-overlay`: color used by the button component for the primary hover overlay layer (MarsUI hover_overlay, White/5). - `--ki-button-primary-hover-shadow`: shadow used by the button component for button primary hover shadow (MarsUI Component_effect/primary_hover). - `--ki-button-primary-neutral-disabled-bg`: color used by the button component for primary neutral disabled background. Deliberate deviation: Figma disabled is Surface/disabled_base_em gray.100 with gray.400 text (≈1.4:1); Kimen keeps gray.200 for contrast (precedent 010 D2, pending founder ratification). - `--ki-button-primary-neutral-disabled-border`: color used by the button component for primary neutral disabled border. - `--ki-button-primary-neutral-disabled-fg`: color used by the button component for primary neutral disabled foreground. Deliberate deviation: Figma disabled text is text/base_em gray.400 (≈1.4:1 on gray.100); Kimen keeps text.muted gray.700 for readable disabled text (precedent 010 D2, pending founder ratification). - `--ki-button-primary-neutral-hover-bg`: color used by the button component for primary neutral hover background (MarsUI: rest fill; hover lightening comes from the hover overlay). - `--ki-button-primary-neutral-hover-border`: color used by the button component for primary neutral hover border (MarsUI bevel top/inline edge). - `--ki-button-primary-neutral-hover-fg`: color used by the button component for primary neutral hover foreground. - `--ki-button-primary-neutral-rest-bg`: color used by the button component for primary neutral rest background (MarsUI Surface/primary_med_em, brand 500). - `--ki-button-primary-neutral-rest-border`: color used by the button component for primary neutral rest border (MarsUI bevel top/inline edge). - `--ki-button-primary-neutral-rest-fg`: color used by the button component for primary neutral rest foreground. - `--ki-button-primary-rest-border-bottom`: color used by the button component for the primary bevel bottom edge (MarsUI Outline/primary_button_bottom). - `--ki-button-primary-rest-shadow`: shadow used by the button component for button primary rest shadow (MarsUI Component_effect/primary_default). - `--ki-button-primary-selected-bg`: Background of the selected primary button toggle. - `--ki-button-primary-selected-fg`: Foreground of the selected primary button toggle. - `--ki-button-primary-success-hover-bg`: color used by the button component for primary success hover background (MarsUI: rest fill; hover lightening comes from the hover overlay). - `--ki-button-primary-success-hover-border`: color used by the button component for primary success hover border (MarsUI bevel top/inline edge). - `--ki-button-primary-success-hover-fg`: color used by the button component for primary success hover foreground. - `--ki-button-primary-success-rest-bg`: color used by the button component for primary success rest background. Deliberate deviation: Figma specifies the 500 ramp (Surface/success_med_em #409b3f) but white on 500 is ≈3.5:1 < AA 4.5:1; Kimen keeps the 700 ramp (precedent 010 D2, pending founder ratification). - `--ki-button-primary-success-rest-border`: color used by the button component for primary success rest border (MarsUI bevel top/inline edge). - `--ki-button-primary-success-rest-fg`: color used by the button component for primary success rest foreground. - `--ki-button-quaternary-danger-hover-bg`: color used by the button component for quaternary danger hover background. - `--ki-button-quaternary-danger-hover-border`: color used by the button component for quaternary danger hover border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-danger-hover-fg`: color used by the button component for quaternary danger hover foreground. - `--ki-button-quaternary-danger-rest-bg`: color used by the button component for quaternary danger rest background. - `--ki-button-quaternary-danger-rest-border`: color used by the button component for quaternary danger rest border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-danger-rest-fg`: color used by the button component for quaternary danger rest foreground. - `--ki-button-quaternary-disabled-shadow`: value used by the button component for quaternary disabled shadow. - `--ki-button-quaternary-hover-shadow`: value used by the button component for quaternary hover shadow. - `--ki-button-quaternary-neutral-disabled-bg`: color used by the button component for quaternary neutral disabled background. - `--ki-button-quaternary-neutral-disabled-border`: color used by the button component for quaternary neutral disabled border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-neutral-disabled-fg`: color used by the button component for quaternary neutral disabled foreground: the disabled ink of every field and selection control (Text/base_em). quaternary has no fill or border, so its ink alone shows the state; ki.text.muted equals its resting ki.text.med-em in onmars. - `--ki-button-quaternary-neutral-hover-bg`: color used by the button component for quaternary neutral hover background (MarsUI hover mechanism: hover_overlay_inverse Black/3 wash over the transparent rest fill). - `--ki-button-quaternary-neutral-hover-border`: color used by the button component for quaternary neutral hover border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-neutral-hover-fg`: color used by the button component for quaternary neutral hover foreground (MarsUI quaternary label text/med_em gray; the outlined-purple rest identity was a pre-master synthesis). - `--ki-button-quaternary-neutral-rest-bg`: color used by the button component for quaternary neutral rest background. - `--ki-button-quaternary-neutral-rest-border`: color used by the button component for quaternary neutral rest border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-neutral-rest-fg`: color used by the button component for quaternary neutral rest foreground (MarsUI quaternary label text/med_em gray; the outlined-purple rest identity was a pre-master synthesis). - `--ki-button-quaternary-rest-shadow`: value used by the button component for quaternary rest shadow. - `--ki-button-quaternary-selected-bg`: Background of the selected quaternary button toggle. - `--ki-button-quaternary-selected-fg`: Foreground of the selected quaternary button toggle. - `--ki-button-quaternary-success-hover-bg`: color used by the button component for quaternary success hover background. - `--ki-button-quaternary-success-hover-border`: color used by the button component for quaternary success hover border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-success-hover-fg`: color used by the button component for quaternary success hover foreground. - `--ki-button-quaternary-success-rest-bg`: color used by the button component for quaternary success rest background. - `--ki-button-quaternary-success-rest-border`: color used by the button component for quaternary success rest border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-success-rest-fg`: color used by the button component for quaternary success rest foreground. - `--ki-button-secondary-active-overlay`: Pressed state layer for the secondary button: secondary paints on a light fill, so its wash darkens: the next rung above ki.surface.hover-overlay-inverse (Black/3 -> Black/5 light). Replaces this variant's share of a 45-cell active bg/fg/border matrix whose values were documented mirrors of rest and which WITHDREW the hover overlay rather than deepening it, an appearance legible only to a pointer user who had hovered first. - `--ki-button-secondary-danger-hover-bg`: color used by the button component for secondary danger hover background. - `--ki-button-secondary-danger-hover-border`: color used by the button component for secondary danger hover border (MarsUI bevel top/inline edge, variant trait). - `--ki-button-secondary-danger-hover-fg`: color used by the button component for secondary danger hover foreground. - `--ki-button-secondary-danger-rest-bg`: color used by the button component for secondary danger rest background. - `--ki-button-secondary-danger-rest-border`: color used by the button component for secondary danger rest border (MarsUI bevel top/inline edge, variant trait). - `--ki-button-secondary-danger-rest-fg`: color used by the button component for secondary danger rest foreground. - `--ki-button-secondary-disabled-shadow`: value used by the button component for secondary disabled shadow. - `--ki-button-secondary-hover-overlay`: color used by the button component for the secondary hover overlay layer (MarsUI hover_overlay_inverse, Black/3). - `--ki-button-secondary-hover-shadow`: shadow used by the button component for secondary hover shadow (MarsUI Component_effect/secondary_hover). - `--ki-button-secondary-neutral-disabled-bg`: color used by the button component for secondary neutral disabled background. - `--ki-button-secondary-neutral-disabled-border`: color used by the button component for secondary neutral disabled border. - `--ki-button-secondary-neutral-disabled-fg`: color used by the button component for secondary neutral disabled foreground. - `--ki-button-secondary-neutral-hover-bg`: color used by the button component for secondary neutral hover background (MarsUI: rest fill; hover darkening comes from the hover overlay). - `--ki-button-secondary-neutral-hover-border`: color used by the button component for secondary neutral hover border (MarsUI bevel top/inline edge). - `--ki-button-secondary-neutral-hover-fg`: color used by the button component for secondary neutral hover foreground (MarsUI text/high_em). - `--ki-button-secondary-neutral-rest-bg`: color used by the button component for secondary neutral rest background (MarsUI Surface/special/secondary_alpha_base: gray glass, not a brand tint). - `--ki-button-secondary-neutral-rest-border`: color used by the button component for secondary neutral rest border (MarsUI bevel top/inline edge). - `--ki-button-secondary-neutral-rest-fg`: color used by the button component for secondary neutral rest foreground (MarsUI text/high_em). - `--ki-button-secondary-rest-border-bottom`: color used by the button component for the secondary bevel bottom edge (MarsUI Outline/secondary_button_bottom). - `--ki-button-secondary-rest-shadow`: shadow used by the button component for secondary rest shadow (MarsUI Component_effect/secondary_default). - `--ki-button-secondary-selected-bg`: Background of the selected secondary button toggle. - `--ki-button-secondary-selected-fg`: Foreground of the selected secondary button toggle. - `--ki-button-secondary-success-hover-bg`: color used by the button component for secondary success hover background. - `--ki-button-secondary-success-hover-border`: color used by the button component for secondary success hover border (MarsUI bevel top/inline edge, variant trait). - `--ki-button-secondary-success-hover-fg`: color used by the button component for secondary success hover foreground. - `--ki-button-secondary-success-rest-bg`: color used by the button component for secondary success rest background. - `--ki-button-secondary-success-rest-border`: color used by the button component for secondary success rest border (MarsUI bevel top/inline edge, variant trait). - `--ki-button-secondary-success-rest-fg`: color used by the button component for secondary success rest foreground. - `--ki-button-sm-font-size`: dimension used by the button component for sm font size. - `--ki-button-sm-gap`: dimension used by the button component for sm gap (Button master 8003:301: root gap Space/xxs 2px + Text_wrap inline padding Space/xs 4px = 6px icon-to-text). - `--ki-button-sm-height`: dimension used by the button component for sm height. - `--ki-button-sm-icon-size`: dimension used by the button component for sm icon size. - `--ki-button-sm-line-height`: dimension used by the button component for sm line height. - `--ki-button-sm-min-target`: dimension used by the button component for sm min target. - `--ki-button-sm-padding-inline`: dimension used by the button component for sm padding inline. - `--ki-button-sm-radius`: dimension used by the button component for sm radius (Button master 8003:300 binds Radius/small-component/sm, the scale a radius mode reassigns). - `--ki-button-sm-spinner-size`: dimension used by the button component for the sm loading spinner box (16px, the sm icon size; spec 046 D5: no Figma source, the spinner takes the place of the content). - `--ki-button-spinner-duration`: duration used by the button and icon button components for one turn of the loading spinner (spec 046 D5: the ki-progress indeterminate period). Applied only under prefers-reduced-motion: no-preference. - `--ki-button-spinner-stroke-width`: dimension used by the button and icon button components for the loading spinner stroke (spec 046 D5: the circular ki-progress ring, drawn with a non-scaling stroke of this width). - `--ki-button-tertiary-danger-hover-bg`: Tertiary alias of the secondary danger hover background. - `--ki-button-tertiary-danger-hover-border`: color used by the button component for tertiary danger hover border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-danger-hover-fg`: color used by the button component for tertiary danger hover foreground. - `--ki-button-tertiary-danger-rest-bg`: Tertiary alias of the secondary danger rest background. - `--ki-button-tertiary-danger-rest-border`: color used by the button component for tertiary danger rest border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-danger-rest-fg`: color used by the button component for tertiary danger rest foreground. - `--ki-button-tertiary-disabled-shadow`: value used by the button component for tertiary disabled shadow. - `--ki-button-tertiary-hover-overlay`: Hover overlay for neutral tertiary buttons, shared with secondary by default. - `--ki-button-tertiary-hover-shadow`: shadow used by the button component for tertiary hover shadow (MarsUI Component_effect/secondary_hover). - `--ki-button-tertiary-neutral-disabled-bg`: color used by the button component for tertiary neutral disabled background. - `--ki-button-tertiary-neutral-disabled-border`: color used by the button component for tertiary neutral disabled border. - `--ki-button-tertiary-neutral-disabled-fg`: color used by the button component for tertiary neutral disabled foreground. - `--ki-button-tertiary-neutral-hover-bg`: Tertiary alias of the secondary neutral hover background. - `--ki-button-tertiary-neutral-hover-border`: color used by the button component for tertiary neutral hover border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-neutral-hover-fg`: Tertiary alias of the secondary neutral hover foreground. - `--ki-button-tertiary-neutral-rest-bg`: Tertiary alias of the secondary neutral rest background. - `--ki-button-tertiary-neutral-rest-border`: color used by the button component for tertiary neutral rest border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-neutral-rest-fg`: Tertiary alias of the secondary neutral rest foreground. - `--ki-button-tertiary-rest-border-bottom`: color used by the button component for the tertiary bevel bottom edge (MarsUI Outline/secondary_button_bottom — same bevel pair as secondary). - `--ki-button-tertiary-rest-shadow`: shadow used by the button component for tertiary rest shadow (MarsUI Component_effect/secondary_default — replaces the migrated M2-era stack, which the material3 theme keeps via its own override). - `--ki-button-tertiary-success-hover-bg`: Tertiary alias of the secondary success hover background. - `--ki-button-tertiary-success-hover-border`: color used by the button component for tertiary success hover border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-success-hover-fg`: color used by the button component for tertiary success hover foreground. - `--ki-button-tertiary-success-rest-bg`: Tertiary alias of the secondary success rest background. - `--ki-button-tertiary-success-rest-border`: color used by the button component for tertiary success rest border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-success-rest-fg`: color used by the button component for tertiary success rest foreground. - `--ki-button-toggle-quiet-bg`: Background of unselected ghost and quaternary toggle buttons. - `--ki-button-toggle-quiet-fg`: Foreground of unselected ghost toggle buttons. - `--ki-button-toggle-radius`: Rounded rectangle shape for an unselected text toggle button. - `--ki-button-toggle-selected-radius`: Pill shape for a selected text toggle button. - `--ki-button-toggle-unselected-bg`: Background of unselected filled toggle buttons. - `--ki-button-toggle-unselected-fg`: Foreground of unselected filled toggle buttons. - `--ki-button-xl-font-size`: dimension used by the button component for xl font size. - `--ki-button-xl-gap`: dimension used by the button component for xl gap (MarsUI effective icon-to-text gap 8px). - `--ki-button-xl-height`: dimension used by the button component for xl height. - `--ki-button-xl-icon-size`: dimension used by the button component for xl icon size. - `--ki-button-xl-line-height`: dimension used by the button component for xl line height. - `--ki-button-xl-min-target`: dimension used by the button component for xl min target. - `--ki-button-xl-padding-inline`: dimension used by the button component for xl padding inline (MarsUI 14px). - `--ki-button-xl-radius`: dimension used by the button component for xl radius (Button master 8003:300 binds Radius/small-component/xl, the scale a radius mode reassigns). - `--ki-button-xl-spinner-size`: dimension used by the button component for the xl loading spinner box (24px, the xl icon size; spec 046 D5: no Figma source, the spinner takes the place of the content). - `--ki-button-xs-font-size`: dimension used by the button component for xs font size: caption_2, 12px, the smallest size the library ships for informative text (spec 002 amendment A1, issue #321). The Figma Button master draws caption_1, 10px. - `--ki-button-xs-gap`: dimension used by the button component for xs gap (MarsUI effective icon-to-text gap 4px). - `--ki-button-xs-height`: dimension used by the button component for xs height. - `--ki-button-xs-icon-size`: dimension used by the button component for xs icon size (MarsUI 14px). - `--ki-button-xs-line-height`: dimension used by the button component for xs line height (caption_2 16px, the same height as caption_1). - `--ki-button-xs-min-target`: dimension used by the button component for xs min target. - `--ki-button-xs-padding-inline`: dimension used by the button component for xs padding inline. - `--ki-button-xs-radius`: dimension used by the button component for xs radius (Button master 8003:300 binds Radius/small-component/xs, the scale a radius mode reassigns). - `--ki-button-xs-spinner-size`: dimension used by the button component for the xs loading spinner box (14px, the xs icon size; spec 046 D5: no Figma source, the spinner takes the place of the content). - `--ki-density-control-offset`: Added to the block size of every scaled control and row (button, icon button, field, select, textarea, option, list item, tab). Components floor the result at ki.size.target-min. - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-effect-component-no-backdrop-filter`: An unadorned surface applies no backdrop filter. - `--ki-elevation-none`: Flat surfaces carry no resting shadow. - `--ki-motion-duration-fast`: Fast interaction transition duration. - `--ki-motion-easing-out`: Decelerating interaction transition easing curve. - `--ki-outline-none`: semantic color for outline none. - `--ki-surface-image-none`: An unadorned surface has no background image. ### ki-button-group Arranges related actions as a spaced group, attached group, or keyboard toolbar. When to use: place two to five related actions together, present a primary action with a menu of alternatives, or give formatting tools one Tab stop. When NOT to use: for a single-choice setting, unrelated actions, or navigation. Use a segmented control for a single-choice setting and links for navigation. Examples: # Using ki-button-group ## Spaced and attached groups Use a label that describes what the actions do together. In attached mode the first button provides the common variant and size. An explicit group size applies in both modes. ```html Undo Redo Copy Paste ``` ## Formatting toolbar Import the glyphs used by your page. Give each icon button a tooltip using the same label. The application sets `pressed` as the formatting state changes. The native button exposes it as `aria-pressed`. ```js import '@kimen/elements/icons/bold'; import '@kimen/elements/icons/list'; ``` ```html ``` ## Split button With a build that includes `ki-menu`, anchor the menu to the chevron action. Import `@kimen/elements/icons/chevron-down` before mounting the group. Handle the main button's click and menu selection as separate actions. ```html Save Save as draft Save a copy ``` Keep the icon button's `expanded` property in sync with the menu's `open` state. Its native button exposes that state as `aria-expanded`. Attributes: - `attached` (boolean, default false): Joins neighboring actions at their inner edges. Buttons share the first button's variant and use its size when the group has no explicit size. Use for a closely related set of actions or for a split button. - `label` (string, required): Required accessible name for the group or toolbar (for example, "Text formatting"). Provide a localized name that describes the actions' shared purpose. - `size` ("lg" | "md" | "sm" | "xl" | "xs" | undefined): Applies one token-backed size to each button while it belongs to the group. Omit it to keep individual sizes in spaced mode. - `toolbar` (boolean, default false): Gives the group toolbar semantics, a framed surface and one Tab stop. Horizontal arrows, Home and End move between the toolbar's actions. Slots: - (default): Related ki-button and ki-icon-button controls, in reading order. Wrap labeled icon actions in ki-tooltip with the same label to show the label on focus and hover. A toolbar can also include vertical separators. Parts: - `group`: The named group or toolbar surface. Events: none Methods: none CSS custom properties: - `--ki-button-group-attached-gap`: Gap between joined actions. - `--ki-button-group-attached-radius`: Radius of the logical corners along a shared button edge. - `--ki-button-group-backdrop-filter`: Complete optional backdrop filter for the toolbar surface. - `--ki-button-group-bg`: Toolbar surface colour. - `--ki-button-group-bg-image`: Optional decorative image over the toolbar surface. - `--ki-button-group-border-color`: Thin toolbar frame colour. - `--ki-button-group-border-width`: Thickness of the toolbar frame and divider. - `--ki-button-group-divider`: Decorative toolbar separator ink. - `--ki-button-group-divider-size`: Block size of a vertical toolbar separator. - `--ki-button-group-fg`: Default toolbar foreground on its raised surface. - `--ki-button-group-gap`: Gap between actions in a spaced group. - `--ki-button-group-padding`: Toolbar frame inset and divider margin. - `--ki-button-group-radius`: Logical outside radius of the toolbar frame. - `--ki-button-group-seam-overlap`: Shared-edge overlap between adjacent attached actions. - `--ki-button-group-toolbar-gap`: Gap between toolbar actions. - `--ki-typography-family-body`: semantic font family for typography family body. ### ki-card A card surface for grouping related content, with an optional primary link or action. When to use: group related media, a title, supporting text and actions into one scannable surface. Set `href` for navigation or `interactive` for a declared action. Give a clickable card one text heading in the header slot and place secondary controls in the body or footer. When NOT to use: as a form field, fieldset, page landmark, section replacement or nested card. Use a standalone button or link for a control without supporting content. Examples: The four regions — `media`, `header`, default body and `footer`; supply the heading element yourself, because plain text in the `header` slot carries no heading semantics: ```html Orbit trajectory plot

Mission telemetry

Latest downlink completed at 14:02 UTC. All systems nominal.

View details
``` Any subset of regions works — a text-only card is valid: ```html

Storage almost full

You are using 92% of your plan. Consider archiving old projects.

``` Place independent actions in the `footer` slot. ```html

Invite your team

Collaborators can review specs and approve merges.

Invite Later
``` Use `href` for a primary destination. Use `interactive` to emit the `ki-activate` action event. Supply a single text heading for either option and keep secondary controls in their own slot content. ```html

Search index rebuild

Scheduled for midnight.

Bookmark

Preview monthly report

Review the new report before publishing it.

``` Attributes: - `href` (string | undefined, URL): Destination for the card's title link. Supply a text heading in the header slot. A nonblank href takes precedence over interactive. - `interactive` (boolean | undefined, default false): Gives a titled card a primary button that emits ki-activate. Use href for navigation. Keep other actions in separate controls in the card. - `variant` ("default" | "elevated" | "filled" | "outlined" | undefined, default 'default'): Surface treatment. Choose elevated for a raised panel, filled for a tinted group or outlined for a bordered surface. Use default to follow the theme's existing card treatment. Slots: - (default): Body region for supporting text or arbitrary composed content. - `footer`: Closing region for actions such as `ki-button`; no dedicated actions slot exists in v1. - `header`: Title region. Supply one nonempty text heading at the surrounding document level for a clickable card. - `media`: Leading visual region for an image, video or illustration. Parts: - `body`: Body region wrapper around the default slot. - `card`: Card surface: background, border, radius, elevation and region gap. - `footer`: Footer region wrapper. - `header`: Header region wrapper. - `media`: Media region wrapper. - `trigger`: Native link or action button in a clickable card’s heading. Events: - `ki-activate` (CustomEvent): Fires once when the user activates an action card by pointer or keyboard. Methods: none CSS custom properties: - `--ki-card-backdrop-filter`: Complete card backdrop filter, off by default. - `--ki-card-bg`: color used by the card component for background (MarsUI Dashboard masters bind Surface/special/light-s0_dark-s1: white light / Dark/900 dark; #f9f9fa is the nested media panel, so the old s1 value inverted the surface hierarchy). - `--ki-card-bg-image`: Optional decorative image over the card background. - `--ki-card-body-padding`: dimension used by the card component for body padding. - `--ki-card-border-color`: color used by the card component for border color (MarsUI Outline/base_em hairline — painted on large Chart cards; Dashboard_info leaves width 0, which stays the default via ki.card.border-width). - `--ki-card-border-width`: dimension used by the card component for border width. - `--ki-card-elevated-bg`: Raised card background. - `--ki-card-elevated-fg`: Text on the elevated card background. - `--ki-card-elevated-shadow`: Resting shadow for an elevated card. - `--ki-card-elevation`: Card resting elevation: MarsUI elevation ramp level e1 (brief §5, drop 0/1/1/-0.5 in the scheme shadow color; replaces the migrated M2-era shadow). - `--ki-card-fg`: color used by the card component for foreground. - `--ki-card-filled-bg`: Tinted card background. - `--ki-card-filled-fg`: Text on the filled card background. - `--ki-card-footer-padding`: dimension used by the card component for footer padding. - `--ki-card-gap`: dimension used by the card component for gap (MarsUI Dashboard_info/Chart inter-region rhythm 12px; material3 keeps zero via its override). - `--ki-card-header-padding`: dimension used by the card component for header padding. - `--ki-card-hover-overlay`: Pointer hover state layer on a primary-action card. - `--ki-card-hover-shadow`: Hover shadow of a primary-action card. - `--ki-card-media-padding`: dimension used by the card component for media padding (MarsUI Dashboard masters inset media panels 8px inline; material3 keeps full-bleed zero via its override). - `--ki-card-media-radius`: dimension used by the card component for slotted media corner radius (MarsUI nested media panel Radius/big_component/radius_sm 20px; formalizes the fallback ki-card.css already consumes). - `--ki-card-outlined-bg`: Page-coloured background for an outlined card. - `--ki-card-outlined-border`: Boundary colour for an outlined card. - `--ki-card-outlined-border-width`: Hairline width for an outlined card. - `--ki-card-outlined-fg`: Text on the outlined card background. - `--ki-card-padding-block`: dimension used by the card component for the surface block padding (16px carried by the card surface itself so stacked region paddings no longer double to 32px; formalizes the fallback ki-card.css already consumes). - `--ki-card-radius`: dimension used by the card component for radius (MarsUI card surfaces ride the big_component scale: Dashboard_info 400x128 binds radius_xs 16px; large Chart cards anchor radius_lg 28px). - `--ki-card-title-family`: Family used for a clickable card title. - `--ki-density-space-scale`: Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-elevation-e2`: MarsUI Elevation/e2 (cumulative: e1 layers plus 0/3/3/-1.5). - `--ki-elevation-none`: Flat surfaces carry no resting shadow. - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-offset`: Gap between a focusable component and its keyboard focus ring. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. - `--ki-motion-distance-sm`: Motion travel distance sm (4px): small slide/settle offsets. - `--ki-motion-duration-fast`: Fast interaction transition duration. - `--ki-motion-duration-medium-1`: M3 md.sys.motion.duration.medium1 (250ms). onmars: MarsUI moderate step (240ms, 2x the 120ms base). - `--ki-motion-easing-out`: Decelerating interaction transition easing curve. - `--ki-motion-easing-standard`: Standard interaction transition easing curve. - `--ki-typography-family-body`: semantic font family for typography family body. - `--ki-typography-line-height-title-1`: semantic dimension for typography line height title 1. - `--ki-typography-size-title-1`: semantic dimension for typography size title 1. ### ki-carousel An ordered, swipeable sequence with previous and next controls and position feedback. When to use: show a short set of related highlights, onboarding steps or media panels. Give the carousel a meaningful label and supply one ki-carousel-item per slide. When NOT to use: hide essential content behind rotation, replace ordinary page navigation, or present slides that readers need to compare side by side at the same time. Examples: # Carousel examples ```html Discover the tools Pick a theme Set up your workspace Share your first surface ``` ```js const carousel = document.querySelector('ki-carousel'); carousel.addEventListener('ki-slide-change', ({ detail }) => { console.log(detail.index); }); await carousel.goTo(3); ``` With per-tag imports, define both `ki-carousel` and `ki-carousel-item`. Attributes: - `autoplay` (number | undefined, minimum 1, maximum 2147483647): Rotation interval in milliseconds. Omitting it leaves rotation off. - `carousel-role-description` (string, default 'carousel'): Accessible role description of the region. - `current` (number, default 1, minimum 1): One-based leading slide. Setting it moves the carousel and clamps the index to the available leading positions. - `label` (string, required): Required accessible name of the carousel region. - `layout` ("full-screen" | "hero" | "multi-browse" | "single" | "uncontained", default 'single'): Item arrangement. Full-screen uses a vertical, full-viewport slide. - `loop` (boolean, default false): Whether navigating past one endpoint wraps to the other. - `navigation` (boolean, default true): Whether to show the Previous and Next buttons. The viewport stays keyboard-operable. - `next-label` (string, default 'Next slide'): Accessible label of the Next button. - `pagination` (boolean, default true): Whether to show the noninteractive slide position indicator. - `pause-label` (string, default 'Pause'): Visible and accessible label of the Pause button. - `play-label` (string, default 'Play'): Visible and accessible label of the Play button. - `position-label` (string, default 'Slide position'): Accessible label of the position indicator. - `previous-label` (string, default 'Previous slide'): Accessible label of the Previous button. - `slide-label` (string, default '{index} of {count}'): Spoken slide name and announcement. Use {index} and {count} as placeholders. - `slide-role-description` (string, default 'slide'): Accessible role description of each slide group. - `slides-per-move` (number, default 1, minimum 1): Number of positions advanced by Previous, Next and automatic rotation. - `slides-per-view` (number, default 1, minimum 1): Number of slides visible together in the single layout. Material 3 layouts determine their own item widths. Slots: - (default): Direct ki-carousel-item children in reading order. Parts: - `announcement`: Visually hidden live region for manual changes. - `controls`: Row containing slide position and navigation. - `next`: Next slide button. - `position`: Position indicator and optional numeric position. - `previous`: Previous slide button. - `rotation`: Play or Pause button when automatic rotation is configured. - `viewport`: Scroll-snap viewport and its keyboard focus outline. Events: - `ki-slide-change` (CustomEvent): Reports the one-based index when the leading slide changes. Methods: - `goTo(index)` (Promise): Moves to the requested one-based leading position within the available range. - `next()` (Promise): Advances by slidesPerMove. - `previous()` (Promise): Moves back by slidesPerMove. CSS custom properties: - `--ki-carousel-control-backdrop-filter`: Complete optional backdrop filter for the carousel controls. - `--ki-carousel-control-bg`: Surface of the carousel navigation and rotation controls. - `--ki-carousel-control-bg-image`: Optional image layered over the carousel control background color. - `--ki-carousel-control-border`: Visible control boundary against the surrounding surface. - `--ki-carousel-control-fg`: Text and glyph ink against the carousel control surface. - `--ki-carousel-control-gap`: Spacing between carousel controls. - `--ki-carousel-control-icon-size`: Glyph size in the carousel navigation controls. - `--ki-carousel-control-radius`: Corner radius of the carousel controls. - `--ki-carousel-control-shadow`: Resting elevation of the carousel controls. - `--ki-carousel-control-size`: Resting carousel control size before applying the density target floor. - `--ki-carousel-full-screen-block-size`: Block size of the vertical carousel viewport. - `--ki-carousel-gap`: Gap between carousel slides and between the viewport and the controls. - `--ki-carousel-preview-min-inline-size`: Minimum inline size of a decorative carousel preview when space permits. - `--ki-carousel-radius`: Corner radius shared by the carousel viewport and slide surfaces. - `--ki-control-border-width`: Stroke width of the boundary of a compact control. - `--ki-density-space-scale`: Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-offset`: Gap between a focusable component and its keyboard focus ring. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. - `--ki-typography-family-body`: semantic font family for typography family body. ### ki-carousel-item A slide in an ordered ki-carousel sequence. When to use: supply a single slide to a ki-carousel. Put the full slide in the default slot and optional decorative preview media in the preview slot. When NOT to use: present a standalone card or a layout container outside a carousel. Examples: # Carousel item example ```html Read the guide Explore themes ``` Attributes: none Slots: - (default): The full slide content, including any links and controls. - `preview`: Decorative, noninteractive media shown when the item is a reduced preview. Parts: - `content`: Surface that holds the full slide. - `preview`: Decorative surface used in small or partly shown previews. Events: none Methods: none CSS custom properties: - `--ki-carousel-item-backdrop-filter`: Complete optional backdrop filter for the slide surface. - `--ki-carousel-item-bg`: Surface for carousel slide content and its decorative preview. - `--ki-carousel-item-bg-image`: Optional image layered over the slide background color. - `--ki-carousel-item-fg`: Text on the carousel slide surface. - `--ki-carousel-item-min-block-size`: Minimum block size of a full slide. - `--ki-carousel-item-padding`: Inset of full slide content. - `--ki-carousel-radius`: Corner radius shared by the carousel viewport and slide surfaces. - `--ki-control-border-width`: Stroke width of the boundary of a compact control. - `--ki-density-space-scale`: Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). - `--ki-typography-family-body`: semantic font family for typography family body. ### ki-checkbox A form-associated checkbox for selecting independent options. Like a native field, it answers `checkValidity()`, `reportValidity()`, `setCustomValidity(message)`, `validity`, `validationMessage` and `willValidate` synchronously, on the custom-elements build (not on hosts created by the lazy loader). When to use: selecting one or more independent options that a form submits later, including a "select all" parent that presents partial selection with `indeterminate`. Always provide a visible label in the default slot. When NOT to use: a single mutually exclusive choice, an immediate on/off effect, triggering an action, unlabeled/icon-only usage, or `checked="false"` to mean unchecked. Boolean attributes use presence semantics; omit `checked` to express unchecked. Examples: The default slot is the visible label — the accessible name and a native activation surface; when checked, `name` and `value` pair into the submitted form data: ```html
Email SMS Save preferences
``` Boolean attributes use presence semantics — omit `checked` to express unchecked, never write `checked="false"`; without `value` a checked box submits `on`, and unchecked boxes contribute no form entry: ```html Send me the weekly digest ``` `required` blocks submission while unchecked (the invalid appearance appears only after a blocked attempt or an invalidating toggle, never on initial render), and `disabled` removes the checkbox from keyboard reach and form data: ```html
I accept the terms of service Notify me by fax Create account
``` `indeterminate` presents the mixed state of a "select all" parent — presentation-only, exposed to assistive technology as mixed, cleared by any user toggle, and never submitted (model data stays binary through `checked`): ```html Select all rows ``` Attributes: - `checked` (boolean, default false): Live binary selection state. User activation by pointer, slotted label or Space toggles it with native checkbox parity and emits composed `input` before composed `change`. Boolean presence semantics apply: `checked="false"` still renders checked; omit the attribute to express unchecked. Programmatic assignment is silent. When NOT to use: do not treat this reflected attribute as a native `defaultChecked`; reset uses the baseline captured at form association. - `disabled` (boolean, default false): Prevents activation, removes the checkbox from keyboard reach, exposes the unavailable state, and excludes it from form data. When NOT to use: do not use disabled for validation errors or pending state. - `error-text` (string | undefined): Message shown in place of the help text once a `required` checkbox is left unchecked, and its `validationMessage`. Say what checking it means ("Accept the terms to continue"). Without it the browser's own message shows, in the browser's language. An error set with `setCustomValidity` outranks it. When NOT to use: do not use it for server-side or cross-field errors; call `setCustomValidity` for those. - `help-text` (string | undefined): One line of help under the checkbox, read with it as its description: what checking it means or commits to. When NOT to use: do not repeat the label, and do not use it for error messages; use `error-text`. - `indeterminate` (boolean, default false): Presentation-only mixed state. It renders the dash mark, is forwarded to the internal native input for mixed assistive-technology exposure, and never changes the submitted value. Any user toggle clears it and removes the reflected attribute. When NOT to use: do not submit or persist `indeterminate` as a third value; model data remains binary through `checked`. - `label-hint` (string | undefined): Short text shown after the slotted label and read with it as part of the checkbox name, so people know before submitting whether they must check it: "(required)" on a consent the form cannot do without, "(optional)" on one it can, in the page's own language. It changes no validation; set `required` for that, and keep the two consistent. When NOT to use: do not put what checking it commits to in it (use `help-text`), errors (use `error-text`), or a repeat of the label. - `name` (string | undefined): Form-data key contributed when the checkbox is checked. When NOT to use: omit when the checkbox should not submit a value. - `required` (boolean, default false): Requires the checkbox to be checked before form submission can proceed. The invalid appearance appears after a blocked submission attempt or an invalidating user toggle, never on initial render. When NOT to use: do not use required to express group-level rules; compose those at the form/application layer. - `size` ("lg" | "md" | "sm", default 'md'): Token-backed size: the box is 18, 20 or 24px in onmars. `sm` also takes the smaller label (13/20, 8px away); `md` and `lg` keep the 15px label. The pointer target never drops under 24px. An unrecognized value matches no style rule and keeps the medium metrics. When to use: match the size of the text and controls around it. When NOT to use: do not pick a smaller size to fit a dense region or a larger one for touch; declare `data-ki-density` on the region instead, which composes with every size. - `value` (string | undefined): Form-data value paired with `name` when checked. If omitted, the submitted value is `on`, matching native checkbox behavior. When NOT to use: do not encode the unchecked state here; unchecked checkboxes contribute no form entry. Slots: - (default): Visible label content. This is the accessible name source and a native activation surface. Parts: - `control`: Visual checkbox box, border, focus ring and currentColor marks. - `error`: Error line shown in place of the help text while the checkbox is invalid after the person toggled it or submitted; a polite live region, starting with a decorative error symbol. - `help`: Help line under the checkbox, read as its description. - `label`: Label wrapper around the default slot. - `label-hint`: The `label-hint` text after the slotted label, inside the label wrapper and part of the accessible name; rendered only while a hint is set. Events: - `change` (Event): Fired once after a user toggle (pointer, slotted label or Space) commits, composed across the shadow boundary; `checked` is already current when listeners run. When to use: react to the committed selection. When NOT to use: do not expect it for programmatic `checked` writes, which are silent. Methods: none CSS custom properties: - `--ki-checkbox-border-width`: dimension used by the checkbox component for border width. - `--ki-checkbox-checked-active-bg`: color used by the checkbox component for checked active background. - `--ki-checkbox-checked-active-border`: color used by the checkbox component for checked active border. - `--ki-checkbox-checked-active-fg`: color used by the checkbox component for checked active foreground. - `--ki-checkbox-checked-disabled-bg`: color used by the checkbox component for checked disabled background (MarsUI Surface/disabled_med_em Gray/300 light / White-18 dark). - `--ki-checkbox-checked-disabled-border`: color used by the checkbox component for checked disabled border. - `--ki-checkbox-checked-disabled-fg`: color used by the checkbox component for checked disabled mark (MarsUI Text/base_em Gray/400 light / White-32 dark; retires the deprecated ki.text.muted alias). - `--ki-checkbox-checked-hover-bg`: color used by the checkbox component for checked hover background. - `--ki-checkbox-checked-hover-border`: color used by the checkbox component for checked hover border. - `--ki-checkbox-checked-hover-fg`: color used by the checkbox component for checked hover foreground. - `--ki-checkbox-checked-rest-bg`: color used by the checkbox component for checked rest background. - `--ki-checkbox-checked-rest-border`: color used by the checkbox component for checked rest border. - `--ki-checkbox-checked-rest-fg`: color used by the checkbox component for checked rest foreground. - `--ki-checkbox-control-size`: dimension used by the checkbox component for control size. - `--ki-checkbox-focus-ring-color`: color used by the checkbox component for focus ring color. - `--ki-checkbox-focus-ring-offset`: dimension used by the checkbox component for focus ring offset. - `--ki-checkbox-focus-ring-shadow`: shadow used by the checkbox component for the focus ring glow (MarsUI Focus/primary: 3px spread ring at 20% — see ki.focus.primary. specs/002-ki-button/design-extraction.md §2.5 recorded 40%, having read the alpha off the Dark canvas mode, same double mechanism as ki-button: glow plus the opaque indicator). - `--ki-checkbox-focus-ring-width`: dimension used by the checkbox component for focus ring width. - `--ki-checkbox-gap`: dimension used by the checkbox component for gap (MarsUI md label pairing: Space/xl 12px for the 20px box). - `--ki-checkbox-indeterminate-active-bg`: color used by the checkbox component for indeterminate active background (MarsUI Surface/primary_low_em_alpha: brand-500 at 20% light / 56% dark; the master defines no indeterminate hover, so every state keeps the tint). - `--ki-checkbox-indeterminate-active-border`: color used by the checkbox component for indeterminate active border (Figma draws no border on the 20% tint, but the tint alone measures ~1.3:1 against light pages; the opaque brand ring keeps the WCAG 1.4.11 3:1 control boundary — gate-driven declared deviation, same law that pinned ki.outline.control). - `--ki-checkbox-indeterminate-active-fg`: color used by the checkbox component for indeterminate active dash (Figma binds Text/primary_med_em brand-500, which measures 2.7:1 against the 56% tint in dark; one em step up keeps the 3:1 non-text law in both schemes — gate-driven compliant alternative). - `--ki-checkbox-indeterminate-disabled-bg`: color used by the checkbox component for indeterminate disabled background (MarsUI Surface/disabled_med_em Gray/300 light / White-18 dark). - `--ki-checkbox-indeterminate-disabled-border`: color used by the checkbox component for indeterminate disabled border. - `--ki-checkbox-indeterminate-disabled-fg`: color used by the checkbox component for indeterminate disabled mark (MarsUI Text/base_em Gray/400 light / White-32 dark; retires the deprecated ki.text.muted alias). - `--ki-checkbox-indeterminate-hover-bg`: color used by the checkbox component for indeterminate hover background (MarsUI Surface/primary_low_em_alpha: brand-500 at 20% light / 56% dark; the master defines no indeterminate hover, so every state keeps the tint). - `--ki-checkbox-indeterminate-hover-border`: color used by the checkbox component for indeterminate hover border (Figma draws no border on the 20% tint, but the tint alone measures ~1.3:1 against light pages; the opaque brand ring keeps the WCAG 1.4.11 3:1 control boundary — gate-driven declared deviation, same law that pinned ki.outline.control). - `--ki-checkbox-indeterminate-hover-fg`: color used by the checkbox component for indeterminate hover dash (Figma binds Text/primary_med_em brand-500, which measures 2.7:1 against the 56% tint in dark; one em step up keeps the 3:1 non-text law in both schemes — gate-driven compliant alternative). - `--ki-checkbox-indeterminate-rest-bg`: color used by the checkbox component for indeterminate rest background (MarsUI Surface/primary_low_em_alpha: brand-500 at 20% light / 56% dark; the master defines no indeterminate hover, so every state keeps the tint). - `--ki-checkbox-indeterminate-rest-border`: color used by the checkbox component for indeterminate rest border (Figma draws no border on the 20% tint, but the tint alone measures ~1.3:1 against light pages; the opaque brand ring keeps the WCAG 1.4.11 3:1 control boundary — gate-driven declared deviation, same law that pinned ki.outline.control). - `--ki-checkbox-indeterminate-rest-fg`: color used by the checkbox component for indeterminate rest dash (Figma binds Text/primary_med_em brand-500, which measures 2.7:1 against the 56% tint in dark; one em step up keeps the 3:1 non-text law in both schemes — gate-driven compliant alternative). - `--ki-checkbox-invalid-bg`: color used by the checkbox component for invalid background. - `--ki-checkbox-invalid-border`: color used by the checkbox component for invalid border. - `--ki-checkbox-invalid-fg`: color used by the checkbox component for invalid foreground. - `--ki-checkbox-label-font-size`: dimension used by the checkbox component for label font size (MarsUI md pairing: body_2 15px for the 20px box). - `--ki-checkbox-label-font-weight`: font weight used by the checkbox component for label font weight. - `--ki-checkbox-label-hint-fg`: color used by the checkbox component for the label hint after the label text (spec 047: the supporting-text role, a declared a11y deviation from the MarsUI Input_label support text Text/low_em, which reads 2.8-3.13:1 on the onmars light surfaces; under more contrast it strengthens with every other supporting text). - `--ki-checkbox-label-hint-gap`: dimension used by the checkbox component for the gap between the label text and the label hint (MarsUI Input_label: Space/xs 4px). - `--ki-checkbox-label-line-height`: dimension used by the checkbox component for label line height (MarsUI body_2 24px). - `--ki-checkbox-lg-control-size`: dimension used by the checkbox component for the lg box (Checkbox 10030:982 lg: 24px in a 28px cell). - `--ki-checkbox-lg-min-target`: dimension used by the checkbox component for the lg min target (Checkbox 10030:982 lg cell: 28px). - `--ki-checkbox-min-target`: dimension used by the checkbox component for min target. - `--ki-checkbox-radius`: dimension used by the checkbox component for radius (MarsUI Radius/radius_sm 6px bound on the box; Figma corner smoothing is an accepted rasterization gap). - `--ki-checkbox-sm-control-size`: dimension used by the checkbox component for the sm box (Checkbox 10030:982 sm: 18px in a 20px cell). - `--ki-checkbox-sm-gap`: dimension used by the checkbox component for the sm gap between control and label (Checkbox-label 10095:3846 sm binds Space/md, 8px; spec 050 D4). - `--ki-checkbox-sm-label-font-size`: dimension used by the checkbox component for the sm label font size (Checkbox-label 10095:3846 sm: UI/para 13/20; spec 050 D4). - `--ki-checkbox-sm-label-line-height`: dimension used by the checkbox component for the sm label line height (Checkbox-label 10095:3846 sm: UI/para 13/20). - `--ki-checkbox-sm-min-target`: dimension used by the checkbox component for the sm min target: 24px, the WCAG 2.5.8 minimum, above the master's 20px cell. - `--ki-checkbox-unchecked-active-bg`: color used by the checkbox component for unchecked active background. - `--ki-checkbox-unchecked-active-border`: color used by the checkbox component for unchecked active border. - `--ki-checkbox-unchecked-active-fg`: color used by the checkbox component for unchecked active foreground. - `--ki-checkbox-unchecked-disabled-bg`: color used by the checkbox component for unchecked disabled background (MarsUI Surface/disabled_med_em Gray/300 light / White-18 dark). - `--ki-checkbox-unchecked-disabled-border`: color used by the checkbox component for unchecked disabled border. - `--ki-checkbox-unchecked-disabled-fg`: color used by the checkbox component for unchecked disabled mark (MarsUI Text/base_em Gray/400 light / White-32 dark; retires the deprecated ki.text.muted alias). - `--ki-checkbox-unchecked-hover-bg`: color used by the checkbox component for unchecked hover background. - `--ki-checkbox-unchecked-hover-border`: color used by the checkbox component for unchecked hover border. - `--ki-checkbox-unchecked-hover-fg`: color used by the checkbox component for unchecked hover foreground. - `--ki-checkbox-unchecked-rest-bg`: color used by the checkbox component for unchecked rest background. - `--ki-checkbox-unchecked-rest-border`: color used by the checkbox component for unchecked rest border. - `--ki-checkbox-unchecked-rest-fg`: color used by the checkbox component for unchecked rest foreground. - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-effect-component-primary-default-shadow`: MarsUI Component_effect/primary_default: drop 0/1/1/-0.5 plus inner White/12 0/3/3. Pair with --ki-effect-component-backdrop-filter — CSS cannot mix backdrop blur into box-shadow. - `--ki-motion-duration-fast`: Fast interaction transition duration. - `--ki-motion-easing-emphasized-out`: Expressive exit curve for selected controls. Onmars eases out without overshoot. - `--ki-motion-easing-out`: Decelerating interaction transition easing curve. - `--ki-motion-easing-standard`: Standard interaction transition easing curve. - `--ki-surface-special-dark-s0-light-s2`: semantic color for surface special dark s0 light s2. - `--ki-surface-special-light-s0-dark-s4`: semantic color for surface special light s0 dark s4. - `--ki-text-danger-high-em`: semantic color for text danger high em. - `--ki-text-high-em`: semantic color for text high em. - `--ki-text-supporting`: Supporting text of an enabled control: field labels, placeholders, list secondary lines, quiet button labels and unselected tabs. A role, distinct from the med-em emphasis step it resolves to, so a mode can strengthen enabled supporting text without touching the disabled ink that also draws from med-em (directly, or through text.muted). - `--ki-typography-family-body`: semantic font family for typography family body. - `--ki-typography-line-height-caption-2`: semantic dimension for typography line height caption 2. - `--ki-typography-size-caption-2`: semantic dimension for typography size caption 2. - `--ki-typography-weight-body-normal`: semantic font weight for typography weight body normal. ### ki-checkbox-group A form-associated group of independently selectable checkboxes. When to use: people may select several visible options that share a question, form field, and optional selection limits. When NOT to use: mutually exclusive choices (use `ki-radio-group`) or an immediate on/off setting (use `ki-switch`). Provide a group label. Examples: # Checkbox group examples ## Submit several selections ```html
Europe Americas Asia-Pacific
``` Reading `new FormData(form).getAll('regions')` returns each checked value in option order. Keep individual option labels visible and give each option a distinct value when you need to select it independently from JavaScript. ## Read and update selection ```js import { defineCustomElement as defineCheckbox } from '@kimen/elements/ki-checkbox'; import { defineCustomElement as defineCheckboxGroup } from '@kimen/elements/ki-checkbox-group'; defineCheckbox(); defineCheckboxGroup(); const group = document.querySelector('#regions'); group.value = ['eu', 'apac']; group.addEventListener('ki-change', (event) => { const selectedRegions = event.detail.value; console.log(selectedRegions); }); ``` ## Horizontal choices ```html Mentions Review requests ``` Attributes: - `disabled` (boolean, default false): Makes the group unavailable and excludes it from form submission. - `error-text` (string | undefined): Localized message displayed for a failing selection limit. - `help-text` (string | undefined): One line of guidance displayed under the choices. - `label` (string, required): Visible legend and accessible name for these choices. - `max` (number | undefined): Maximum number of checked options, as a nonnegative integer. - `min` (number | undefined): Minimum number of checked options, as a nonnegative integer. - `name` (string | undefined): Form-data key repeated for each selected option. - `orientation` ("horizontal" | "vertical", default 'vertical'): Lays choices out vertically or in a wrapping horizontal row. Slots: - (default): Direct `ki-checkbox` options, each with its own visible label and value. Put form naming and constraints on the group. Parts: - `error`: Polite error message shown in place of the help. - `help`: Guidance below the options and the group's accessible description. - `label`: Legend that names the group. Events: - `ki-change` (CustomEvent): Fires once for a committed user toggle with a copy of the current selection. Methods: none CSS custom properties: - `--ki-checkbox-group-gap`: Space between checkbox options and the group label and messages. - `--ki-radio-group-label-font-size`: dimension used by the radio group component for label font size. - `--ki-radio-group-label-font-weight`: font weight used by the radio group component for label font weight. - `--ki-radio-group-label-line-height`: dimension used by the radio group component for label line height (closest measured analogue: Radio_label sm 13/20; no group-title master exists — low-confidence refinement). - `--ki-text-danger-high-em`: semantic color for text danger high em. - `--ki-text-high-em`: semantic color for text high em. - `--ki-text-med-em`: semantic color for text med em. - `--ki-text-supporting`: Supporting text of an enabled control: field labels, placeholders, list secondary lines, quiet button labels and unselected tabs. A role, distinct from the med-em emphasis step it resolves to, so a mode can strengthen enabled supporting text without touching the disabled ink that also draws from med-em (directly, or through text.muted). - `--ki-typography-family-body`: semantic font family for typography family body. - `--ki-typography-line-height-caption-2`: semantic dimension for typography line height caption 2. - `--ki-typography-size-caption-2`: semantic dimension for typography size caption 2. - `--ki-typography-weight-body-normal`: semantic font weight for typography weight body normal. ### ki-chip A compact filter toggle, removable picked value, or contextual action. When to use: apply independent filters, represent values selected in an entry field, or offer a small contextual action alongside content. When NOT to use: static status (ki-badge), primary actions (ki-button), suggested prompts, or mutually exclusive choices (ki-radio-group). Examples: # Chip examples Use a filter group for independent toggles. Read `ki-change.detail.selected` to update the results. The chip's `value` identifies the filter. ```html Design Engineering ``` Use an input group for picked values. Link the entry field by ID so focus returns to it after the last chip. Listen to `ki-remove` to update your collection. If a framework owns these nodes, cancel the event and let it apply the DOM change, then focus the next chip or the linked field. ```html Ana García Luis ``` Use assist for a contextual action. Handle `ki-activate` in application code. ```html Add to calendar ``` Attributes: - `disabled` (boolean, default false): Prevents activation, removal and moving the chip. - `removable` (boolean, default false): Gives an input chip a trailing remove button and keyboard deletion. - `remove-label` (string, default 'Remove'): Localized action prefix in the remove button's accessible name, followed by the chip label. - `selected` (boolean, default false): The pressed state of a filter chip. The user can toggle it in place. - `size` ("md" | "sm", default 'md'): Visual size of the pill, 24 CSS px for sm and 32 CSS px for md at standard text spacing. - `type` ("assist" | "filter" | "input" | undefined): Chip kind. Inherits the immediate chip group's type when omitted. Standalone chips default to filter. - `value` (string, default ''): Value sent with removal, contextual activation and reorder events. Slots: - (default): The visible text label. Use text or non-interactive markup. - `start`: One decorative glyph or extra-extra-small avatar. A filter check replaces it when selected. Do not slot controls. Parts: - `chip`: The painted pill. - `drag-handle`: The grip enabled by a reorderable parent group. - `label`: The text wrapper around the default slot. - `remove`: The native remove button on a removable input chip. - `selection-icon`: The selected filter check. - `start`: The decorative leading content. Events: - `ki-activate` (CustomEvent<{ value: string; }>): Emitted by an assist chip when its native button is activated. - `ki-change` (CustomEvent<{ selected: boolean; }>): Emitted after a filter chip changes its pressed state. - `ki-remove` (CustomEvent<{ value: string }>): Remove request for an input chip. Cancel it to keep application ownership of the chip. Methods: none CSS custom properties: - `--ki-chip-assist-icon-fg`: Decorative glyph in an assist chip. - `--ki-chip-backdrop-filter`: Default compact pill surface leaves the backdrop unfiltered. - `--ki-chip-bg`: Resting filter and assist surface. - `--ki-chip-bg-image`: Default compact pill surface uses a solid color. - `--ki-chip-border`: Outline of an unselected filter or assist chip. - `--ki-chip-border-width`: Default thickness of a compact pill border. - `--ki-chip-disabled-border`: Outline of a disabled chip. - `--ki-chip-disabled-ink`: Label on a disabled chip. - `--ki-chip-fg`: Resting filter and assist label. - `--ki-chip-font-family`: Font family for the visible chip label. - `--ki-chip-font-size`: Default chip label size. - `--ki-chip-font-size-sm`: Small chip label size. - `--ki-chip-font-weight`: Weight for a chip label. - `--ki-chip-gap`: Gap between content in a compact pill. - `--ki-chip-height`: Default height of a compact pill. - `--ki-chip-height-sm`: Small height of a compact pill. - `--ki-chip-hover-bg`: Surface under the hovering pointer. - `--ki-chip-hover-fg`: Label over the hover surface. - `--ki-chip-icon-size`: Icon size inside a compact pill. - `--ki-chip-input-bg`: Surface of a picked value. - `--ki-chip-input-fg`: Label of a picked value. - `--ki-chip-inset`: Default inline padding of a compact pill. - `--ki-chip-inset-action`: Trailing inset beside a pill action. - `--ki-chip-inset-sm`: Small inline padding of a compact pill. - `--ki-chip-line-height`: Default line height of the chip label. - `--ki-chip-line-height-sm`: Small line height of the chip label. - `--ki-chip-pressed-bg`: Surface while the activation is held. - `--ki-chip-pressed-fg`: Label while the activation is held. - `--ki-chip-radius`: Fully rounded compact pill shape. - `--ki-chip-remove-bg`: Remove button surface inside an input chip. - `--ki-chip-remove-fg`: Resting remove glyph. - `--ki-chip-remove-hover-bg`: Remove button hover surface. - `--ki-chip-remove-hover-fg`: Remove glyph over the hover surface. - `--ki-chip-selected-bg`: Selected filter surface. - `--ki-chip-selected-border`: Accessible boundary of a selected filter. - `--ki-chip-selected-fg`: Selected filter label and check. - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-offset`: Gap between a focusable component and its keyboard focus ring. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. - `--ki-motion-duration-fast`: Fast interaction transition duration. - `--ki-motion-easing-out`: Decelerating interaction transition easing curve. ### ki-chip-group A named collection of filter, input or assist chips, with optional ordering. When to use: label related chips or let people change their reading order. When NOT to use: choose exactly one option or submit a form value. Examples: # Chip group examples A labelled group lets the user reorder direct chips with a drag handle, two pointer activations on the handles, or Alt+Left/Right. The order is announced on each move. Listen for `ki-reorder` to persist the new order. ```html Ana García Luis ``` Attributes: - `focus-target` (string | undefined, ID of another element of the same spec): ID of the entry field in the same document or shadow root for focus after the last chip. - `label` (string, default ''): Accessible name for the group or list. - `reorder-announcement` (string, default '{label} moved to position {position} of {total}.'): Localized polite message using {label}, {position} and {total}. Position is one-based. - `reorderable` (boolean, default false): Enables dragging, pointer pick-and-place and Alt+Left/Right to move chips. - `type` ("assist" | "filter" | "input", default 'filter'): Shared chip kind and collection semantics. Input chips are presented as a list. Slots: - (default): Direct ki-chip children in reading order. Parts: - `group`: The wrapping chip layout. Events: - `ki-reorder` (CustomEvent): Emitted after moving a chip. Indices are zero-based positions in the visible chip collection. Methods: none CSS custom properties: - `--ki-chip-group-font-family`: Font family inherited by chip group content. - `--ki-chip-group-gap`: Gap between adjacent chips and rows. - `--ki-chip-height-sm`: Small height of a compact pill. - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). ### ki-citation A numbered inline link from an answer to a source card. When to use: Next to a claim supported by a `ki-source` in the same document or shadow root. Repeat the same reference for subsequent mentions. When NOT to use: To cite a source outside this tree or replace a standalone link. Use `ki-link` for direct navigation. Examples: # Using ki-citation Place a citation after its claim and set `ref` to the matching source identifier. ```html

The methods account for the difference.

``` Use `citationRef` in JSX. Tab to the link for a preview. Escape dismisses the preview, and Enter opens the list and moves focus to the source link. Attributes: - `ref` (string, required): ID or source-id of the source. Use the `ref` attribute in HTML and `citationRef` in JSX so framework refs remain available. - `label-template` (string, default 'Source {number}: {title}'): Localized link name with `{number}` and `{title}` placeholders. Slots: none Parts: - `link`: Focusable citation link. - `marker`: Visible citation number. - `preview`: Anchored title and hostname preview. - `preview-domain`: Hostname in the preview. - `preview-title`: Title in the preview. Events: none Methods: none CSS custom properties: - `--ki-citation-backdrop-filter`: Complete backdrop filter for a citation marker. - `--ki-citation-bg`: Background of a citation marker. - `--ki-citation-bg-image`: Optional decorative image over a citation marker. - `--ki-citation-fg`: Text on a citation marker. - `--ki-citation-hover-bg`: Background of a hovered citation marker. - `--ki-citation-hover-fg`: Text on a hovered citation marker. - `--ki-citation-padding`: Inline padding of the citation number. - `--ki-citation-preview-backdrop-filter`: Complete backdrop filter for the citation preview. - `--ki-citation-preview-bg`: Background of the title and hostname preview. - `--ki-citation-preview-bg-image`: Optional decorative image over the citation preview. - `--ki-citation-preview-border`: Edge color of the citation preview. - `--ki-citation-preview-border-width`: Edge width of the citation preview. - `--ki-citation-preview-fg`: Text on the citation preview. - `--ki-citation-preview-max-inline-size`: Maximum width of the citation preview. - `--ki-citation-preview-padding`: Inset around the preview content. - `--ki-citation-preview-radius`: Corner radius of the citation preview. - `--ki-citation-preview-shadow`: Elevation of the citation preview. - `--ki-citation-radius`: Corner radius of a citation marker. - `--ki-citation-size`: Minimum painted edge of a citation marker. - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-offset`: Gap between a focusable component and its keyboard focus ring. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. - `--ki-typography-family-body`: semantic font family for typography family body. - `--ki-typography-line-height-caption-2`: semantic dimension for typography line height caption 2. - `--ki-typography-size-caption-2`: semantic dimension for typography size caption 2. - `--ki-typography-weight-body-semibold`: semantic font weight for typography weight body semibold. ### ki-code-block Presents source code with a named header, syntax colors, line controls and clipboard feedback. When to use: display a multiline example, generated code or a tool result that readers should be able to inspect and copy. When NOT to use: when the reader should edit the source or when the code belongs inline in a sentence. Use an editor or a native inline code element. Examples: # ki-code-block examples Display a TypeScript snippet with line numbers and a highlighted line. ```html // Load the current sample. const sample = load(3); ``` Use plain text for unsupported syntax. In HTML, escape literal angle brackets so they remain part of the source. ```html <p>Hello</p> ``` The guarded catalog accepts source strings in the default slot. ```json { "version": 1, "actions": ["sampleCopied"], "root": { "component": "ki-code-block", "props": { "language": "js", "filename": "index.js", "line-numbers": true }, "slots": { "": ["const sample = load(3);"] }, "action": "sampleCopied" } } ``` Attributes: - `copied-label` (string, default 'Copied'): Polite announcement after a successful clipboard write. - `copy-error-label` (string, default "Couldn't copy"): Polite announcement after a failed clipboard write. - `copy-label` (string, default 'Copy code'): Accessible name of the copy button. - `copyable` (boolean, default true): Show the copy control. Set `copyable="false"` in HTML to hide it. - `filename` (string | undefined): File name shown in the header beside the language. - `highlight` (string | undefined): Comma-separated lines or inclusive ranges, for example `"3,5-7"`. - `highlight-label` (string, default 'Highlighted lines'): Localizable prefix for the accessible description of highlighted lines. - `label` (string | undefined, default 'Code'): Figure and scroll area label when there is no language or filename. - `language` (string | undefined): Visible language label and syntax grammar. Supports JavaScript, TypeScript and JSON. - `line-numbers` (boolean, default false): Show decorative one-based line numbers. - `wrap` (boolean, default false): Soft-wrap long lines within the available width. Slots: - (default): Literal source text. Escape markup in HTML or supply a text node. Parts: - `code`: The monospaced source and its optional gutter. - `figure`: Framed surface around the snippet. - `header`: Caption containing the language, filename and copy control. - `scroll`: Focusable native code scroll area. Events: - `ki-copy` (CustomEvent<{ value: string }>): CopyButton reports a successful write with the original source text. - `ki-copy-error` (CustomEvent): CopyButton reports an unsuccessful clipboard write. Methods: none CSS custom properties: - `--ki-code-backdrop-filter`: Whole backdrop filter for the figure. - `--ki-code-bg`: Solid backing for the header and source. - `--ki-code-bg-image`: Optional image layer above the solid backing. - `--ki-code-border`: Frame and header divider. - `--ki-code-border-width`: Width of the frame and header divider. - `--ki-code-comment`: Supporting syntax ink for comments. - `--ki-code-fg`: Default source ink. - `--ki-code-focus-color`: Keyboard focus ring of the scroll area. - `--ki-code-focus-width`: Width of the scroll area's focus ring. - `--ki-code-font-family`: Typeface for source and line numbers. - `--ki-code-font-size`: Compact text size for caption and source. - `--ki-code-function`: Syntax ink for function names. - `--ki-code-header-fg`: Supporting language and filename ink. - `--ki-code-header-padding`: Compact header inset and gap. - `--ki-code-highlight-bg`: Fill of a highlighted line. - `--ki-code-highlight-marker`: Inline rule identifying a highlighted line. - `--ki-code-highlight-marker-width`: Width of the highlighted line rule. - `--ki-code-keyword`: Syntax ink for keywords. - `--ki-code-line-height`: Line box height for caption and source. - `--ki-code-line-number`: Ink for the decorative line numbers. - `--ki-code-number`: Syntax ink for numbers. - `--ki-code-padding`: Inset of the source and leading caption edge. - `--ki-code-radius`: Corner radius of the figure. - `--ki-code-string`: Syntax ink for strings. - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-typography-family-body`: semantic font family for typography family body. ### ki-code-input A form-associated verification field with one native text input and a visual box per character. When to use: Collect a one-time code of four to eight characters for sign-in or verification. When NOT to use: Use ki-input for passwords, long codes or free text. Examples: # ki-code-input examples Use `ki-code-input` for fixed one-time codes of four to eight characters. Use `ki-input` for passwords, longer codes and free text. ## Numeric verification with a resend action ```html
Verify Resend code
``` Read `new FormData(form).get('otp')` in the submit handler and send the string to the verification service. The application knows the expiration time and owns the resend request. On successful resend, clear the old value and any custom validity error, update the help text, and focus the field. Offer a visible and announced status if a request is still pending or fails. On the custom-elements build, use `field.setCustomValidity(message)` and `field.reportValidity()` to display a server rejection. Clear the message with `field.setCustomValidity('')` once the person edits or resends the code. ## Four-character recovery code ```html ``` Both `ki-input` and `ki-complete` carry `{ value }`. Listen for `ki-complete` if filling the last box enables the next step. Leave submission to the form unless completing the code can safely advance the flow. Attributes: - `disabled` (boolean, default false): Disable editing, sequential focus and form participation. - `error-text` (string | undefined): Message for a failing code constraint. Omit to use the browser's message. - `help-text` (string | undefined): Instructions saying where the code was sent and how long it is valid. - `label` (string, required): Visible accessible name. Supply a label in the language of the form. - `length` (number, default 6, minimum 4, maximum 8): Number of cells and maximum code length. Unsupported lengths fall back to six. - `name` (string | undefined): Key for the single value submitted to the enclosing form. - `required` (boolean, default false): Require a complete code before submitting. An optional field may be empty. - `size` ("md" | "sm", default 'md'): Medium or small cells. The form region's density adjusts both sizes. - `type` ("alphanumeric" | "numeric", default 'numeric'): Allowed characters and keyboard hint. Alphanumeric mode preserves ASCII letter case. - `value` (string, default ''): The current code, including leading zeros. Use the attribute to declare the reset value. Programmatic assignments are normalized and silent. Slots: none Parts: - `cell`: Decorative box for one code character. - `error`: Polite validation message that replaces the instructions. - `field`: Enclosure of the native input and its visual boxes. - `help`: Delivery and validity instructions read with the field. - `input`: Single native text input, responsible for editing and autofill. - `label`: Visible label supplying the native input's accessible name. Events: - `ki-complete` (CustomEvent): Emitted after the input event when the edited code fills all the cells. - `ki-input` (CustomEvent): Emitted when a user edit changes the code. Methods: none CSS custom properties: - `--ki-code-input-active-border`: Focus outline around the active or selected cells. - `--ki-code-input-backdrop-filter`: Optional compositing filter behind a code cell. - `--ki-code-input-bg`: Resting code cell fill. - `--ki-code-input-bg-image`: Optional image painted over the code cell fill. - `--ki-code-input-blink-duration`: Duration of one code caret blink. - `--ki-code-input-border`: Resting code cell boundary. - `--ki-code-input-cell-size`: Default code cell edge before applying control density. - `--ki-code-input-cell-size-sm`: Small code cell edge before applying control density. - `--ki-code-input-disabled-fg`: Code character ink while the field is disabled. - `--ki-code-input-error-border`: Code cell boundary after failed validation. - `--ki-code-input-fg`: Resting code character ink. - `--ki-code-input-font-size`: Code character size. - `--ki-code-input-gap`: Inline space between code cells. - `--ki-code-input-radius`: Code cell corner radius. - `--ki-code-input-selection-bg`: Background of a selected code character. - `--ki-code-input-selection-fg`: Ink of a selected code character. - `--ki-code-input-touch-font-size`: Minimum native input text size on a coarse pointer. - `--ki-control-border-width`: Stroke width of the boundary of a compact control. - `--ki-density-control-offset`: Added to the block size of every scaled control and row (button, icon button, field, select, textarea, option, list item, tab). Components floor the result at ki.size.target-min. - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. - `--ki-layout-spacing-xs`: The xs spacing step for a stack or grid gap. - `--ki-text-danger-high-em`: semantic color for text danger high em. - `--ki-text-high-em`: semantic color for text high em. - `--ki-text-supporting`: Supporting text of an enabled control: field labels, placeholders, list secondary lines, quiet button labels and unselected tabs. A role, distinct from the med-em emphasis step it resolves to, so a mode can strengthen enabled supporting text without touching the disabled ink that also draws from med-em (directly, or through text.muted). - `--ki-typography-family-body`: semantic font family for typography family body. - `--ki-typography-family-mono`: semantic font family for typography family mono. - `--ki-typography-line-height-body-1`: semantic dimension for typography line height body 1. - `--ki-typography-line-height-caption-2`: semantic dimension for typography line height caption 2. - `--ki-typography-size-body-1`: semantic dimension for typography size body 1. - `--ki-typography-size-caption-2`: semantic dimension for typography size caption 2. - `--ki-typography-weight-body-medium`: semantic font weight for typography weight body medium. - `--ki-typography-weight-body-normal`: semantic font weight for typography weight body normal. - `--ki-typography-weight-body-semibold`: semantic font weight for typography weight body semibold. ### ki-combobox An editable, form-associated combobox with local or remote filtering, single or multiple selection, and optional free entry. When to use: choose from a long list of options, let people search an option source, or allow multiple selections that remain visible as tags. When NOT to use: use a select-only control for a short closed set or a plain text field for unrestricted input with no choices. Examples: ## Search people When importing custom elements individually, register both `@kimen/elements/ki-combobox` and `@kimen/elements/ki-option`. ```html Ana Ruiz Juan Antón ``` ## Pick or create multiple labels ```html bug search documentation ``` Assign an array to the JavaScript `value` property to set multiple selections. Use a JSON array string in HTML or neutral catalog specs. Each selection submits under the same form name. Read them all with `FormData.getAll`. ## Request server results Set `filter="none"` to display the options supplied by your application. Listen for `ki-input` and use `event.detail.value` as the query. Set `loading` while fetching, replace the field's `ki-option` children with the latest results, and clear `loading`. Use `change` to respond to a committed selection. Attributes: - `add-label` (string, default 'Add “{text}”'): Localizable free-entry offer. {text} is replaced by the trimmed query. - `allow-custom` (boolean, default false): Offers to add trimmed query text when no known or selected choice already matches it. - `disabled` (boolean, default false): Disables editing, navigation and form submission. - `empty-label` (string, default 'No results'): Localizable status when there are no choices to display. - `error-text` (string | undefined): Message used when a required selection is missing, in place of the browser's message. - `filter` ("contains" | "none" | "starts-with", default 'contains'): Filters by label. Set to none when the application provides results from a remote search. - `help-text` (string | undefined): Guidance shown below the field and read as its description. - `label` (string, required): Visible label and accessible name. Supply it even when placeholder text is also set. - `loading` (boolean, default false): Replaces visible options with a loading indicator while a search is pending. - `loading-label` (string, default 'Loading results'): Localizable status while waiting for a result set. - `multiple` (boolean, default false): Enables ordered multiple selection and renders selected values as tags. - `name` (string | undefined): Form-data key. Multiple choices contribute one entry each under this name. - `placeholder` (string, default ''): Hint shown in the text input when it is empty. - `remove-label` (string, default 'Remove {label}'): Localizable removal button label. {label} is replaced by the selected label. - `required` (boolean, default false): Requires a committed choice to submit the form. - `result-count-label` (string, default '{count} results'): Localizable status for several choices. {count} is replaced by the result count. - `result-one-label` (string, default '1 result'): Localizable status for one available choice. - `value` (string | string[], default ''): Committed value. Use a string for single selection and an array of strings for multiple selection. In HTML and catalog specs, encode multiple values as a JSON array string in the value attribute, or supply one literal value. Assign a new array to change multiple selections programmatically. Slots: - (default): Declarative ki-option children. Supply unique values and a human-readable label. Parts: - `description`: An option's secondary text. - `error`: Polite error message shown after failed validation. - `field`: Container for the text input and selected tags. - `help`: Help below the field. - `input`: Native text input with the combobox role. - `label`: Visible label of the field and its listbox. - `listbox`: Floating listbox surface. - `option`: A mirrored choice row. - `remove`: A native button that removes a selected tag. - `tag`: A selected value in multiple mode. Events: - `ki-input` (CustomEvent<{ value: string }>): Reports a raw text edit in `detail.value`. Listen to it to request remote results. - `change` (Event): Composed event after a user changes the committed selection. Read the committed value from the host. Methods: none CSS custom properties: - `--ki-combobox-field-bg`: Fill for the editable field. - `--ki-combobox-field-border`: Outline around the editable field. - `--ki-combobox-field-fg`: Text on the editable field. - `--ki-combobox-field-height`: Resting minimum block size of the field. - `--ki-combobox-icon-size`: Size of search, selection and remove glyphs. - `--ki-combobox-input-basis`: Preferred text-entry width before a row of tags wraps. - `--ki-combobox-input-touch-font-size`: Minimum editable text size for coarse-pointer input. - `--ki-combobox-listbox-backdrop-filter`: Complete backdrop filter for the floating listbox. - `--ki-combobox-listbox-bg`: Fill for the floating listbox. - `--ki-combobox-listbox-bg-image`: Optional image layered over the floating listbox. - `--ki-combobox-listbox-border`: Outline around the floating listbox. - `--ki-combobox-listbox-fg`: Text on the floating listbox. - `--ki-combobox-listbox-max-block-size`: Maximum listbox block size before options scroll. - `--ki-combobox-listbox-shadow`: Elevation of the floating listbox. - `--ki-combobox-match-fg`: Foreground of the first bolded query match. - `--ki-combobox-option-active-bg`: Fill for the active option. - `--ki-combobox-option-active-fg`: Text on the active option. - `--ki-combobox-tag-bg`: Fill for the selected tag. - `--ki-combobox-tag-fg`: Text on the selected tag. - `--ki-corner-field-item`: Corner radius for choices and tokens inside an editable field. - `--ki-corner-field-surface`: Corner radius for an editable field and its floating choice surface. - `--ki-density-control-offset`: Added to the block size of every scaled control and row (button, icon button, field, select, textarea, option, list item, tab). Components floor the result at ki.size.target-min. - `--ki-density-space-scale`: Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-offset`: Gap between a focusable component and its keyboard focus ring. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. - `--ki-layout-spacing-md`: The md spacing step for a stack or grid gap. - `--ki-layout-spacing-xs`: The xs spacing step for a stack or grid gap. - `--ki-layout-spacing-xxs`: The xxs spacing step for a stack or grid gap. - `--ki-outline-danger-high-em`: semantic color for outline danger high em. - `--ki-outline-hairline-width`: Width of a hairline component surface edge. - `--ki-text-danger-high-em`: semantic color for text danger high em. - `--ki-text-high-em`: semantic color for text high em. - `--ki-text-supporting`: Supporting text of an enabled control: field labels, placeholders, list secondary lines, quiet button labels and unselected tabs. A role, distinct from the med-em emphasis step it resolves to, so a mode can strengthen enabled supporting text without touching the disabled ink that also draws from med-em (directly, or through text.muted). - `--ki-typography-family-body`: semantic font family for typography family body. - `--ki-typography-line-height-body-1`: semantic dimension for typography line height body 1. - `--ki-typography-line-height-caption-2`: semantic dimension for typography line height caption 2. - `--ki-typography-size-body-1`: semantic dimension for typography size body 1. - `--ki-typography-size-caption-2`: semantic dimension for typography size caption 2. - `--ki-typography-visually-hidden-size`: Nonzero edge for clipped text available to assistive technology. - `--ki-typography-weight-body-bold`: semantic font weight for typography weight body bold. - `--ki-typography-weight-body-medium`: semantic font weight for typography weight body medium. ### ki-confirmation An inline prompt for a decision about a proposed assistant action. When to use: Show the exact action and the details a person needs before granting permission. A trusted host maps the two decision events to its declared actions and records the outcome in state. When NOT to use: Report a completed action without a preceding request, or block the rest of the interface with a modal decision (use ki-dialog). The displayed action identifier is text and carries no execution authority. Examples: # Confirm an assistant action ```html
To
Ana Rivera
Subject
Weekly report
``` Map the two decisions in trusted host code. This MCP Apps example uses a ready `SurfaceBridge` whose rendered spec declares `approve-send-email` and `deny-send-email` in its top-level `actions`. Keep a guarded node's scalar `action` binding unset because the component declares two events. Its `props.action` carries the visible tool identifier. A trusted host that applies an origin allowlist can supply that identifier after rendering, since guarded spec data under that prop name passes through the URL policy. ```js const prompt = document.querySelector('#send-email-prompt'); prompt.addEventListener('ki-approve', (event) => { if (event.composedPath()[0] !== prompt) return; bridge.dispatch('approve-send-email', { tool: 'send_email', remember: event.detail?.remember === true, }); }); prompt.addEventListener('ki-deny', (event) => { if (event.composedPath()[0] !== prompt) return; bridge.dispatch('deny-send-email', { tool: 'send_email' }); }); ``` The host owns execution, deadlines and any conversation permission. Supply outcome metadata and set the resolved state after recording the decision. ```js prompt.resolvedBy = 'You'; prompt.resolvedAt = '10:32'; prompt.state = 'approved'; ``` Call `await prompt.focusPrompt()` when the person is waiting for the request. Keep the proposed inputs stable while the person is deciding. Mount a new element if another request for the same tool replaces a pending one. Attributes: - `action` (string, required): Tool identifier shown to the person and available for reporting by the host. - `approve-label` (string, required): Verb or short phrase that describes what approval does, such as "Send email". - `approved-label` (string, default 'Approved'): Localized outcome text when the host marks the request approved. - `consequence` (string | undefined): Cost or irreversible effect to read before deciding, displayed as a warning note. - `denied-label` (string, default 'Denied'): Localized outcome text when the host marks the request denied. - `deny-label` (string, required): Verb or short phrase for refusal, such as "Keep draft". - `expired-label` (string, default 'Expired'): Localized outcome text when the host marks the request expired. - `heading` (string, required): Question naming the proposed action. Provide it before asking for a decision. - `remember` (boolean, default false): Offers an unchecked preference limited to this action in the current conversation. - `remember-label` (string, default 'Allow this action for the rest of this conversation'): Localized conversation permission label. Name the specific permission when possible. - `resolved-at` (string | undefined): Display-ready, localized resolution time from the host, if known. - `resolved-by` (string | undefined): Display-ready name of the person or service that resolved the request, if known. - `state` ("approved" | "denied" | "expired" | "pending", default 'pending'): Host-controlled outcome. Resolve after recording a decision or expiring the request. - `tone` ("danger" | "neutral", default 'neutral'): Use danger when approval is destructive. Unknown values use neutral. Slots: - (default): Details the person needs to make the decision. Use readable text or semantic markup such as a description list. Parts: - `decisions`: The row of decision controls. - `group`: The painted, labelled prompt or outcome surface. - `heading`: The pending question. - `remember`: The label of the conversation preference checkbox. - `summary`: The resolved row. Events: - `ki-approve` (CustomEvent<{ remember: boolean }>): Explicit approval, with the conversation preference at the time of the decision. - `ki-deny` (CustomEvent): Explicit refusal of the pending request. Methods: - `focusPrompt()` (Promise): Moves focus to the pending group and reports success. Call only when the host knows the person was waiting for this request. A focused editor keeps its focus, including editors inside open shadow roots. CSS custom properties: - `--ki-confirmation-backdrop-filter`: Complete backdrop effect behind the confirmation. - `--ki-confirmation-bg`: Solid raised background of the confirmation prompt and summary. - `--ki-confirmation-bg-image`: Optional image painted over the solid confirmation background. - `--ki-confirmation-border`: Boundary of the confirmation surface. - `--ki-confirmation-border-width`: Stroke width of the confirmation boundary. - `--ki-confirmation-fg`: Text on the confirmation surface. - `--ki-confirmation-gap`: Block separation between confirmation rows. - `--ki-confirmation-heading-font-family`: Typeface of the pending question. - `--ki-confirmation-inline-gap`: Space between text and controls in a row. - `--ki-confirmation-padding`: Space between the prompt's edge and its content. - `--ki-confirmation-radius`: Corner radius of the confirmation surface. - `--ki-density-space-scale`: Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-offset`: Gap between a focusable component and its keyboard focus ring. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. - `--ki-surface-primary-med-em`: semantic color for surface primary med em. - `--ki-typography-family-body`: semantic font family for typography family body. - `--ki-typography-family-mono`: semantic font family for typography family mono. - `--ki-typography-line-height-para`: semantic dimension for typography line height para. - `--ki-typography-size-body-1`: semantic dimension for typography size body 1. - `--ki-typography-size-body-2`: semantic dimension for typography size body 2. - `--ki-typography-visually-hidden-size`: Nonzero edge for clipped text available to assistive technology. ### ki-conversation An accessible chat transcript with optional following as messages arrive. When to use: Display chronological user, assistant and event messages. Give the host a block-size constraint to keep scrolling within the transcript. When NOT to use: Collect input, send messages or present a static sequence of cards. Place the composer outside the transcript. Examples: # ki-conversation examples ## Bounded transcript Set a block size to make the transcript scroll. Enable `stick-to-bottom` to follow new messages and keep incoming replies in view. ```html Which inputs handle form errors? Searched the component docs Input, textarea and select show field errors. ``` ## Pass application chunks to a message Call this function with the async iterable supplied by your application. Keep the composer and any waiting indicator outside the live log. ```js async function appendReply(conversation, chunks) { const reply = document.createElement('ki-message'); reply.setAttribute('streaming', ''); conversation.append(reply); try { for await (const chunk of chunks) { reply.append(chunk); } } finally { reply.removeAttribute('streaming'); } } ``` ## Custom-elements entry points ```ts import { defineCustomElement as defineConversation } from '@kimen/elements/ki-conversation'; import { defineCustomElement as defineMessage } from '@kimen/elements/ki-message'; defineConversation(); defineMessage(); ``` Attributes: - `jump-label` (string, default 'Jump to latest'): Visible and accessible label for the control that resumes following. - `label` (string, default 'Conversation'): Accessible name of the transcript. Supply a distinct label when several logs share a page. - `stick-to-bottom` (boolean, default false): Follow new or growing messages until the reader scrolls away from the end. Slots: - (default): The chronological transcript, normally ki-message elements. Parts: - `jump`: The Jump to latest button shown while following is paused. - `log`: The named polite live region and keyboard-focusable scrollport. - `messages`: The stack of slotted messages inside the scrollport. Events: none Methods: none CSS custom properties: - `--ki-conversation-gap`: Space between messages in the transcript. - `--ki-conversation-max-width`: Maximum inline size of the transcript. - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. - `--ki-layout-spacing-md`: The md spacing step for a stack or grid gap. - `--ki-typography-family-body`: semantic font family for typography family body. ### ki-copy-button Copies text to the clipboard and confirms the result in the same button. When to use: let a person copy a link, identifier, token or code sample. Supply a direct value or point to a source in the same document or shadow root. When NOT to use: submit a form, navigate, or trigger an action with no clipboard write. Use a button or link for those actions. Examples: # ki-copy-button examples ## Copy an invite link ```html ``` ## Copy what a field currently contains ```html Copy token ``` ## Copy a code sample with localized feedback ```html
pnpm add @kimen/elements
Copiar comando ``` Attributes: - `copied-label` (string, default 'Copied'): Polite announcement after a successful write. Override for localized interfaces. - `copy-error-label` (string, default "Couldn't copy"): Polite announcement after a failed write or missing source. Override for localized interfaces. - `feedback-duration` (number, default 1500, minimum 0): Milliseconds to show feedback after a write settles. Zero keeps the outcome visible until the next result. Invalid values use 1500 ms. - `from` (string | undefined, ID of another element of the same spec): ID of a source in this button's document or shadow root. A nonempty ID takes precedence over `value`. The source's current string value or its text content is read on activation. - `label` (string, default 'Copy'): Accessible name for the icon-only control. Visible slot text supplies the name when present. - `size` ("lg" | "md" | "sm" | "xl" | "xs", default 'md'): Token-backed button size. Match the size of adjacent controls. - `value` (string | undefined): Exact clipboard text, including whitespace. Supply it when the text is known directly. - `variant` ("ghost" | "outline" | "primary" | "quaternary" | "secondary", default 'ghost'): Button emphasis. Use ghost for compact actions and secondary for a visible supporting action. Slots: - (default): Optional visible text, which supplies the accessible name and places the icon at the inline start. Use plain text or non-interactive markup. Parts: - `button`: Native copy control with keyboard and pointer activation. - `icon`: Fixed-size decorative feedback glyph box inside the button. - `label`: Wrapper around the visible slotted label. Events: - `ki-copy` (CustomEvent<{ value: string }>): Fired after a successful clipboard write. The detail carries the exact text copied. - `ki-copy-error` (CustomEvent): Fired when the source cannot be read or clipboard writing is unavailable or fails. Methods: none CSS custom properties: - `--ki-button-backdrop-filter`: Complete backdrop filter for glass button and icon-button variants. - `--ki-button-border-width`: dimension used by the button component for border width (MarsUI bevel/outline stroke: 1px). - `--ki-button-focus-ring-color`: color used by the button component for focus ring color. - `--ki-button-focus-ring-offset`: dimension used by the button component for focus ring offset. - `--ki-button-focus-ring-shadow`: shadow used by the button component for the focus ring glow (MarsUI Focus/primary: 3px spread ring). - `--ki-button-focus-ring-width`: dimension used by the button component for focus ring width. - `--ki-button-font-family`: font family used by the button component for font family. - `--ki-button-font-weight`: font weight used by the button component for font weight. - `--ki-button-ghost-danger-hover-bg`: color used by the button component for ghost danger hover background. - `--ki-button-ghost-danger-hover-border`: color used by the button component for ghost danger hover border. - `--ki-button-ghost-danger-hover-fg`: color used by the button component for ghost danger hover foreground. - `--ki-button-ghost-danger-rest-bg`: color used by the button component for ghost danger rest background. - `--ki-button-ghost-danger-rest-border`: color used by the button component for ghost danger rest border. - `--ki-button-ghost-danger-rest-fg`: color used by the button component for ghost danger rest foreground. - `--ki-button-ghost-disabled-shadow`: value used by the button component for ghost disabled shadow. - `--ki-button-ghost-hover-shadow`: value used by the button component for ghost hover shadow. - `--ki-button-ghost-neutral-disabled-bg`: color used by the button component for ghost neutral disabled background. - `--ki-button-ghost-neutral-disabled-border`: color used by the button component for ghost neutral disabled border. - `--ki-button-ghost-neutral-disabled-fg`: color used by the button component for ghost neutral disabled foreground. - `--ki-button-ghost-neutral-hover-bg`: color used by the button component for ghost neutral hover background. - `--ki-button-ghost-neutral-hover-border`: color used by the button component for ghost neutral hover border. - `--ki-button-ghost-neutral-hover-fg`: color used by the button component for ghost neutral hover foreground. - `--ki-button-ghost-neutral-rest-bg`: color used by the button component for ghost neutral rest background. - `--ki-button-ghost-neutral-rest-border`: color used by the button component for ghost neutral rest border. - `--ki-button-ghost-neutral-rest-fg`: color used by the button component for ghost neutral rest foreground. - `--ki-button-ghost-rest-shadow`: value used by the button component for ghost rest shadow. - `--ki-button-ghost-selected-bg`: Background of the selected ghost button toggle. - `--ki-button-ghost-selected-fg`: Foreground of the selected ghost button toggle. - `--ki-button-ghost-success-hover-bg`: color used by the button component for ghost success hover background. - `--ki-button-ghost-success-hover-border`: color used by the button component for ghost success hover border. - `--ki-button-ghost-success-hover-fg`: color used by the button component for ghost success hover foreground. - `--ki-button-ghost-success-rest-bg`: color used by the button component for ghost success rest background. - `--ki-button-ghost-success-rest-border`: color used by the button component for ghost success rest border. - `--ki-button-ghost-success-rest-fg`: color used by the button component for ghost success rest foreground. - `--ki-button-label-padding-inline`: dimension used by the button component for the label Text_wrap inline padding (MarsUI 8003:300: 4px each side of the label; the flex gap subtracts the same value so icon-to-text keeps the composite distance). - `--ki-button-lg-font-size`: dimension used by the button component for lg font size. - `--ki-button-lg-gap`: dimension used by the button component for lg gap. - `--ki-button-lg-height`: dimension used by the button component for lg height. - `--ki-button-lg-icon-size`: dimension used by the button component for lg icon size. - `--ki-button-lg-line-height`: dimension used by the button component for lg line height. - `--ki-button-lg-min-target`: dimension used by the button component for lg min target. - `--ki-button-lg-padding-inline`: dimension used by the button component for lg padding inline. - `--ki-button-lg-radius`: dimension used by the button component for lg radius (Button master 8003:300 binds Radius/small-component/lg, the scale a radius mode reassigns). - `--ki-button-lg-spinner-size`: dimension used by the button component for the lg loading spinner box (20px, the lg icon size; spec 046 D5: no Figma source, the spinner takes the place of the content). - `--ki-button-md-font-size`: dimension used by the button component for md font size. - `--ki-button-md-gap`: dimension used by the button component for md gap (MarsUI effective icon-to-text gap 6px). - `--ki-button-md-height`: dimension used by the button component for md height. - `--ki-button-md-icon-size`: dimension used by the button component for md icon size. - `--ki-button-md-line-height`: dimension used by the button component for md line height. - `--ki-button-md-min-target`: dimension used by the button component for md min target. - `--ki-button-md-padding-inline`: dimension used by the button component for md padding inline. - `--ki-button-md-radius`: dimension used by the button component for md radius (Button master 8003:300 binds Radius/small-component/md, the scale a radius mode reassigns). - `--ki-button-md-spinner-size`: dimension used by the button component for the md loading spinner box (18px, the md icon size; spec 046 D5: no Figma source, the spinner takes the place of the content). - `--ki-button-outline-rest-bg`: Background of the outline variant at rest. - `--ki-button-outline-rest-border`: Visible outline of the outline variant at rest. - `--ki-button-outline-rest-fg`: Foreground of the outline variant at rest. - `--ki-button-outline-selected-bg`: Background of the selected outline button toggle. - `--ki-button-outline-selected-fg`: Foreground of the selected outline button toggle. - `--ki-button-padding-block`: dimension used by the button component for padding block (MarsUI: 4px in every size). - `--ki-button-primary-active-overlay`: Pressed state layer for the primary button: primary paints on a dark brand fill, so its wash lightens: the next rung above ki.surface.hover-overlay (White/5 -> White/8 light). Replaces this variant's share of a 45-cell active bg/fg/border matrix whose values were documented mirrors of rest and which WITHDREW the hover overlay rather than deepening it, an appearance legible only to a pointer user who had hovered first. - `--ki-button-primary-danger-hover-bg`: color used by the button component for primary danger hover background (MarsUI: rest fill; hover lightening comes from the hover overlay). - `--ki-button-primary-danger-hover-border`: color used by the button component for primary danger hover border (MarsUI bevel top/inline edge). - `--ki-button-primary-danger-hover-fg`: color used by the button component for primary danger hover foreground. - `--ki-button-primary-danger-rest-bg`: color used by the button component for primary danger rest background. Deliberate deviation: Figma specifies the 500 ramp (Surface/danger_med_em #f05149) but white on 500 is ≈3.5:1 < AA 4.5:1; Kimen keeps the 700 ramp (precedent 010 D2, pending founder ratification). - `--ki-button-primary-danger-rest-border`: color used by the button component for primary danger rest border (MarsUI bevel top/inline edge). - `--ki-button-primary-danger-rest-fg`: color used by the button component for primary danger rest foreground. - `--ki-button-primary-disabled-shadow`: value used by the button component for primary disabled shadow. - `--ki-button-primary-hover-overlay`: color used by the button component for the primary hover overlay layer (MarsUI hover_overlay, White/5). - `--ki-button-primary-hover-shadow`: shadow used by the button component for button primary hover shadow (MarsUI Component_effect/primary_hover). - `--ki-button-primary-neutral-disabled-bg`: color used by the button component for primary neutral disabled background. Deliberate deviation: Figma disabled is Surface/disabled_base_em gray.100 with gray.400 text (≈1.4:1); Kimen keeps gray.200 for contrast (precedent 010 D2, pending founder ratification). - `--ki-button-primary-neutral-disabled-border`: color used by the button component for primary neutral disabled border. - `--ki-button-primary-neutral-disabled-fg`: color used by the button component for primary neutral disabled foreground. Deliberate deviation: Figma disabled text is text/base_em gray.400 (≈1.4:1 on gray.100); Kimen keeps text.muted gray.700 for readable disabled text (precedent 010 D2, pending founder ratification). - `--ki-button-primary-neutral-hover-bg`: color used by the button component for primary neutral hover background (MarsUI: rest fill; hover lightening comes from the hover overlay). - `--ki-button-primary-neutral-hover-border`: color used by the button component for primary neutral hover border (MarsUI bevel top/inline edge). - `--ki-button-primary-neutral-hover-fg`: color used by the button component for primary neutral hover foreground. - `--ki-button-primary-neutral-rest-bg`: color used by the button component for primary neutral rest background (MarsUI Surface/primary_med_em, brand 500). - `--ki-button-primary-neutral-rest-border`: color used by the button component for primary neutral rest border (MarsUI bevel top/inline edge). - `--ki-button-primary-neutral-rest-fg`: color used by the button component for primary neutral rest foreground. - `--ki-button-primary-rest-border-bottom`: color used by the button component for the primary bevel bottom edge (MarsUI Outline/primary_button_bottom). - `--ki-button-primary-rest-shadow`: shadow used by the button component for button primary rest shadow (MarsUI Component_effect/primary_default). - `--ki-button-primary-selected-bg`: Background of the selected primary button toggle. - `--ki-button-primary-selected-fg`: Foreground of the selected primary button toggle. - `--ki-button-primary-success-hover-bg`: color used by the button component for primary success hover background (MarsUI: rest fill; hover lightening comes from the hover overlay). - `--ki-button-primary-success-hover-border`: color used by the button component for primary success hover border (MarsUI bevel top/inline edge). - `--ki-button-primary-success-hover-fg`: color used by the button component for primary success hover foreground. - `--ki-button-primary-success-rest-bg`: color used by the button component for primary success rest background. Deliberate deviation: Figma specifies the 500 ramp (Surface/success_med_em #409b3f) but white on 500 is ≈3.5:1 < AA 4.5:1; Kimen keeps the 700 ramp (precedent 010 D2, pending founder ratification). - `--ki-button-primary-success-rest-border`: color used by the button component for primary success rest border (MarsUI bevel top/inline edge). - `--ki-button-primary-success-rest-fg`: color used by the button component for primary success rest foreground. - `--ki-button-quaternary-danger-hover-bg`: color used by the button component for quaternary danger hover background. - `--ki-button-quaternary-danger-hover-border`: color used by the button component for quaternary danger hover border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-danger-hover-fg`: color used by the button component for quaternary danger hover foreground. - `--ki-button-quaternary-danger-rest-bg`: color used by the button component for quaternary danger rest background. - `--ki-button-quaternary-danger-rest-border`: color used by the button component for quaternary danger rest border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-danger-rest-fg`: color used by the button component for quaternary danger rest foreground. - `--ki-button-quaternary-disabled-shadow`: value used by the button component for quaternary disabled shadow. - `--ki-button-quaternary-hover-shadow`: value used by the button component for quaternary hover shadow. - `--ki-button-quaternary-neutral-disabled-bg`: color used by the button component for quaternary neutral disabled background. - `--ki-button-quaternary-neutral-disabled-border`: color used by the button component for quaternary neutral disabled border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-neutral-disabled-fg`: color used by the button component for quaternary neutral disabled foreground: the disabled ink of every field and selection control (Text/base_em). quaternary has no fill or border, so its ink alone shows the state; ki.text.muted equals its resting ki.text.med-em in onmars. - `--ki-button-quaternary-neutral-hover-bg`: color used by the button component for quaternary neutral hover background (MarsUI hover mechanism: hover_overlay_inverse Black/3 wash over the transparent rest fill). - `--ki-button-quaternary-neutral-hover-border`: color used by the button component for quaternary neutral hover border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-neutral-hover-fg`: color used by the button component for quaternary neutral hover foreground (MarsUI quaternary label text/med_em gray; the outlined-purple rest identity was a pre-master synthesis). - `--ki-button-quaternary-neutral-rest-bg`: color used by the button component for quaternary neutral rest background. - `--ki-button-quaternary-neutral-rest-border`: color used by the button component for quaternary neutral rest border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-neutral-rest-fg`: color used by the button component for quaternary neutral rest foreground (MarsUI quaternary label text/med_em gray; the outlined-purple rest identity was a pre-master synthesis). - `--ki-button-quaternary-rest-shadow`: value used by the button component for quaternary rest shadow. - `--ki-button-quaternary-selected-bg`: Background of the selected quaternary button toggle. - `--ki-button-quaternary-selected-fg`: Foreground of the selected quaternary button toggle. - `--ki-button-quaternary-success-hover-bg`: color used by the button component for quaternary success hover background. - `--ki-button-quaternary-success-hover-border`: color used by the button component for quaternary success hover border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-success-hover-fg`: color used by the button component for quaternary success hover foreground. - `--ki-button-quaternary-success-rest-bg`: color used by the button component for quaternary success rest background. - `--ki-button-quaternary-success-rest-border`: color used by the button component for quaternary success rest border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-success-rest-fg`: color used by the button component for quaternary success rest foreground. - `--ki-button-secondary-active-overlay`: Pressed state layer for the secondary button: secondary paints on a light fill, so its wash darkens: the next rung above ki.surface.hover-overlay-inverse (Black/3 -> Black/5 light). Replaces this variant's share of a 45-cell active bg/fg/border matrix whose values were documented mirrors of rest and which WITHDREW the hover overlay rather than deepening it, an appearance legible only to a pointer user who had hovered first. - `--ki-button-secondary-danger-hover-bg`: color used by the button component for secondary danger hover background. - `--ki-button-secondary-danger-hover-border`: color used by the button component for secondary danger hover border (MarsUI bevel top/inline edge, variant trait). - `--ki-button-secondary-danger-hover-fg`: color used by the button component for secondary danger hover foreground. - `--ki-button-secondary-danger-rest-bg`: color used by the button component for secondary danger rest background. - `--ki-button-secondary-danger-rest-border`: color used by the button component for secondary danger rest border (MarsUI bevel top/inline edge, variant trait). - `--ki-button-secondary-danger-rest-fg`: color used by the button component for secondary danger rest foreground. - `--ki-button-secondary-disabled-shadow`: value used by the button component for secondary disabled shadow. - `--ki-button-secondary-hover-overlay`: color used by the button component for the secondary hover overlay layer (MarsUI hover_overlay_inverse, Black/3). - `--ki-button-secondary-hover-shadow`: shadow used by the button component for secondary hover shadow (MarsUI Component_effect/secondary_hover). - `--ki-button-secondary-neutral-disabled-bg`: color used by the button component for secondary neutral disabled background. - `--ki-button-secondary-neutral-disabled-border`: color used by the button component for secondary neutral disabled border. - `--ki-button-secondary-neutral-disabled-fg`: color used by the button component for secondary neutral disabled foreground. - `--ki-button-secondary-neutral-hover-bg`: color used by the button component for secondary neutral hover background (MarsUI: rest fill; hover darkening comes from the hover overlay). - `--ki-button-secondary-neutral-hover-border`: color used by the button component for secondary neutral hover border (MarsUI bevel top/inline edge). - `--ki-button-secondary-neutral-hover-fg`: color used by the button component for secondary neutral hover foreground (MarsUI text/high_em). - `--ki-button-secondary-neutral-rest-bg`: color used by the button component for secondary neutral rest background (MarsUI Surface/special/secondary_alpha_base: gray glass, not a brand tint). - `--ki-button-secondary-neutral-rest-border`: color used by the button component for secondary neutral rest border (MarsUI bevel top/inline edge). - `--ki-button-secondary-neutral-rest-fg`: color used by the button component for secondary neutral rest foreground (MarsUI text/high_em). - `--ki-button-secondary-rest-border-bottom`: color used by the button component for the secondary bevel bottom edge (MarsUI Outline/secondary_button_bottom). - `--ki-button-secondary-rest-shadow`: shadow used by the button component for secondary rest shadow (MarsUI Component_effect/secondary_default). - `--ki-button-secondary-selected-bg`: Background of the selected secondary button toggle. - `--ki-button-secondary-selected-fg`: Foreground of the selected secondary button toggle. - `--ki-button-secondary-success-hover-bg`: color used by the button component for secondary success hover background. - `--ki-button-secondary-success-hover-border`: color used by the button component for secondary success hover border (MarsUI bevel top/inline edge, variant trait). - `--ki-button-secondary-success-hover-fg`: color used by the button component for secondary success hover foreground. - `--ki-button-secondary-success-rest-bg`: color used by the button component for secondary success rest background. - `--ki-button-secondary-success-rest-border`: color used by the button component for secondary success rest border (MarsUI bevel top/inline edge, variant trait). - `--ki-button-secondary-success-rest-fg`: color used by the button component for secondary success rest foreground. - `--ki-button-sm-font-size`: dimension used by the button component for sm font size. - `--ki-button-sm-gap`: dimension used by the button component for sm gap (Button master 8003:301: root gap Space/xxs 2px + Text_wrap inline padding Space/xs 4px = 6px icon-to-text). - `--ki-button-sm-height`: dimension used by the button component for sm height. - `--ki-button-sm-icon-size`: dimension used by the button component for sm icon size. - `--ki-button-sm-line-height`: dimension used by the button component for sm line height. - `--ki-button-sm-min-target`: dimension used by the button component for sm min target. - `--ki-button-sm-padding-inline`: dimension used by the button component for sm padding inline. - `--ki-button-sm-radius`: dimension used by the button component for sm radius (Button master 8003:300 binds Radius/small-component/sm, the scale a radius mode reassigns). - `--ki-button-sm-spinner-size`: dimension used by the button component for the sm loading spinner box (16px, the sm icon size; spec 046 D5: no Figma source, the spinner takes the place of the content). - `--ki-button-spinner-duration`: duration used by the button and icon button components for one turn of the loading spinner (spec 046 D5: the ki-progress indeterminate period). Applied only under prefers-reduced-motion: no-preference. - `--ki-button-spinner-stroke-width`: dimension used by the button and icon button components for the loading spinner stroke (spec 046 D5: the circular ki-progress ring, drawn with a non-scaling stroke of this width). - `--ki-button-tertiary-danger-hover-bg`: Tertiary alias of the secondary danger hover background. - `--ki-button-tertiary-danger-hover-border`: color used by the button component for tertiary danger hover border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-danger-hover-fg`: color used by the button component for tertiary danger hover foreground. - `--ki-button-tertiary-danger-rest-bg`: Tertiary alias of the secondary danger rest background. - `--ki-button-tertiary-danger-rest-border`: color used by the button component for tertiary danger rest border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-danger-rest-fg`: color used by the button component for tertiary danger rest foreground. - `--ki-button-tertiary-disabled-shadow`: value used by the button component for tertiary disabled shadow. - `--ki-button-tertiary-hover-overlay`: Hover overlay for neutral tertiary buttons, shared with secondary by default. - `--ki-button-tertiary-hover-shadow`: shadow used by the button component for tertiary hover shadow (MarsUI Component_effect/secondary_hover). - `--ki-button-tertiary-neutral-disabled-bg`: color used by the button component for tertiary neutral disabled background. - `--ki-button-tertiary-neutral-disabled-border`: color used by the button component for tertiary neutral disabled border. - `--ki-button-tertiary-neutral-disabled-fg`: color used by the button component for tertiary neutral disabled foreground. - `--ki-button-tertiary-neutral-hover-bg`: Tertiary alias of the secondary neutral hover background. - `--ki-button-tertiary-neutral-hover-border`: color used by the button component for tertiary neutral hover border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-neutral-hover-fg`: Tertiary alias of the secondary neutral hover foreground. - `--ki-button-tertiary-neutral-rest-bg`: Tertiary alias of the secondary neutral rest background. - `--ki-button-tertiary-neutral-rest-border`: color used by the button component for tertiary neutral rest border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-neutral-rest-fg`: Tertiary alias of the secondary neutral rest foreground. - `--ki-button-tertiary-rest-border-bottom`: color used by the button component for the tertiary bevel bottom edge (MarsUI Outline/secondary_button_bottom — same bevel pair as secondary). - `--ki-button-tertiary-rest-shadow`: shadow used by the button component for tertiary rest shadow (MarsUI Component_effect/secondary_default — replaces the migrated M2-era stack, which the material3 theme keeps via its own override). - `--ki-button-tertiary-success-hover-bg`: Tertiary alias of the secondary success hover background. - `--ki-button-tertiary-success-hover-border`: color used by the button component for tertiary success hover border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-success-hover-fg`: color used by the button component for tertiary success hover foreground. - `--ki-button-tertiary-success-rest-bg`: Tertiary alias of the secondary success rest background. - `--ki-button-tertiary-success-rest-border`: color used by the button component for tertiary success rest border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-success-rest-fg`: color used by the button component for tertiary success rest foreground. - `--ki-button-toggle-radius`: Rounded rectangle shape for an unselected text toggle button. - `--ki-button-toggle-selected-radius`: Pill shape for a selected text toggle button. - `--ki-button-xl-font-size`: dimension used by the button component for xl font size. - `--ki-button-xl-gap`: dimension used by the button component for xl gap (MarsUI effective icon-to-text gap 8px). - `--ki-button-xl-height`: dimension used by the button component for xl height. - `--ki-button-xl-icon-size`: dimension used by the button component for xl icon size. - `--ki-button-xl-line-height`: dimension used by the button component for xl line height. - `--ki-button-xl-min-target`: dimension used by the button component for xl min target. - `--ki-button-xl-padding-inline`: dimension used by the button component for xl padding inline (MarsUI 14px). - `--ki-button-xl-radius`: dimension used by the button component for xl radius (Button master 8003:300 binds Radius/small-component/xl, the scale a radius mode reassigns). - `--ki-button-xl-spinner-size`: dimension used by the button component for the xl loading spinner box (24px, the xl icon size; spec 046 D5: no Figma source, the spinner takes the place of the content). - `--ki-button-xs-font-size`: dimension used by the button component for xs font size: caption_2, 12px, the smallest size the library ships for informative text (spec 002 amendment A1, issue #321). The Figma Button master draws caption_1, 10px. - `--ki-button-xs-gap`: dimension used by the button component for xs gap (MarsUI effective icon-to-text gap 4px). - `--ki-button-xs-height`: dimension used by the button component for xs height. - `--ki-button-xs-icon-size`: dimension used by the button component for xs icon size (MarsUI 14px). - `--ki-button-xs-line-height`: dimension used by the button component for xs line height (caption_2 16px, the same height as caption_1). - `--ki-button-xs-min-target`: dimension used by the button component for xs min target. - `--ki-button-xs-padding-inline`: dimension used by the button component for xs padding inline. - `--ki-button-xs-radius`: dimension used by the button component for xs radius (Button master 8003:300 binds Radius/small-component/xs, the scale a radius mode reassigns). - `--ki-button-xs-spinner-size`: dimension used by the button component for the xs loading spinner box (14px, the xs icon size; spec 046 D5: no Figma source, the spinner takes the place of the content). - `--ki-copy-button-error-bg`: Contrast ground for the error glyph on filled primary copy buttons. - `--ki-copy-button-error-fg`: Copy failure glyph ink. - `--ki-copy-button-success-bg`: Contrast ground for the success glyph on filled primary copy buttons. - `--ki-copy-button-success-fg`: Confirmation check ink. - `--ki-density-control-offset`: Added to the block size of every scaled control and row (button, icon button, field, select, textarea, option, list item, tab). Components floor the result at ki.size.target-min. - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-motion-duration-fast`: Fast interaction transition duration. - `--ki-motion-easing-out`: Decelerating interaction transition easing curve. - `--ki-typography-family-body`: semantic font family for typography family body. ### ki-counter A decorative count or dot over a trigger or avatar. When to use: mark unread or pending items on a trigger, or presence on an avatar. Supply the full meaning in the host's accessible name and use a page-owned polite live region for important updates. When NOT to use: for an object's status (use ki-badge), a count inside a list row (use text or ki-badge), or an announcement that needs its own semantics. Examples: # Notification count and presence Provide the actual count or presence in the host's label. The visible counter is decorative, so a label can expose the full count even if the pill says `99+`. ```html ``` The `for` attribute attaches the indicator to a trigger ID in the same document or shadow root. Set the trigger's accessible name directly. ```html Inbox

``` For an important count update, update the trigger name and the counter, then write one localized announcement to the pre-existing status region. Attributes: - `dot` (boolean, default false): Show a dot independently of the count, including when the value is zero. - `for` (string | undefined, ID of another element of the same spec): Literal ID of a trigger in the same document or shadow root. Places the indicator at its block-start inline-end corner and hides it while the trigger is unavailable. For a named host slot, omit this property. - `max` (number, default 99): Largest count displayed in full. Higher values display the cap with a plus sign. Fractional caps round down; invalid caps use 99. - `tone` ("danger" | "neutral" | "primary" | "success", default 'danger'): Semantic palette of the pill or dot. An unknown tone uses danger. - `value` (number | undefined): Count of unread or pending items. Finite values are rounded down. Values below one and non-finite values hide the count. Slots: none Parts: - `indicator`: Painted pill or dot, including the surrounding ring. Events: none Methods: none CSS custom properties: - `--ki-counter-backdrop-filter`: Complete backdrop filter for the indicator. - `--ki-counter-bg`: Danger notification indicator fill. - `--ki-counter-bg-image`: Optional image over the notification indicator fill. - `--ki-counter-dot-size`: Width and height of the presence dot. - `--ki-counter-fg`: Danger notification count text. - `--ki-counter-font-family`: Font family for the count. - `--ki-counter-font-size`: Font size for the count. - `--ki-counter-font-weight`: Font weight for the count. - `--ki-counter-neutral-bg`: Neutral notification indicator fill. - `--ki-counter-neutral-fg`: Neutral notification count text. - `--ki-counter-padding-inline`: Horizontal padding of a count pill. - `--ki-counter-primary-bg`: Primary notification indicator fill. - `--ki-counter-primary-fg`: Primary notification count text. - `--ki-counter-radius`: Radius of the painted pill or dot. - `--ki-counter-ring`: Surface-colored ring that separates the indicator from the trigger. - `--ki-counter-ring-width`: Thickness of the separating ring. - `--ki-counter-size`: Minimum width and height of a count pill. - `--ki-counter-success-bg`: Success notification indicator fill. - `--ki-counter-success-fg`: Success notification count text. ### ki-date-picker A locale-aware date field with an anchored keyboard-operable calendar. When to use: Choose a nearby date or date range when the weekday matters, such as a booking, a deadline or a schedule. When NOT to use: Enter a known distant date, such as a birth date, or choose a time. Examples: # DatePicker examples ## Choose a departure date ```html ``` Typing `20/11/2026` and pressing Enter emits `ki-change` with `{ "value": "2026-11-20" }`. ## Apply a stay range ```html ``` Pick two endpoints and activate Apply to save the range. The form receives one `stay` entry with the date pair. Attributes: - `apply-label` (string, default 'Apply'): Localized label of the confirmation button that saves a complete draft. - `cancel-label` (string, default 'Cancel'): Localized label of the confirmation button that discards a draft. - `change-label` (string, default 'Change date, {date}'): Localized name of the trigger when a date is saved. Use {date} for the current selection. - `choose-label` (string, default 'Choose date'): Localized name of the calendar dialog and of the trigger when no date is saved. - `confirm` (boolean, default false): Require Apply before saving picks made in the calendar. - `disabled` (boolean, default false): Disables the text entry and calendar button and excludes the field from form data. - `error-text` (string | undefined): Overrides the message shown when a date is missing, invalid or outside the bounds. - `first-day-of-week` (number | undefined, minimum 0, maximum 6): First weekday, where Sunday is 0 and Saturday is 6. Defaults to the locale's week start. - `help-text` (string | undefined): A format hint or explanation read with the field. It is replaced by a visible error. - `invalid-date-label` (string, default 'Enter a valid date within the allowed range.'): Localized fallback message for an impossible, incomplete or out-of-bounds date. - `label` (string, required): Visible text and accessible name of the date field. Provide a label for every field. - `locale` (string | undefined): BCP 47 language tag for localized dates and weekday order. Defaults to the page language. - `max` (string | undefined): Latest selectable date, inclusive. Use YYYY-MM-DD. - `min` (string | undefined): Earliest selectable date, inclusive. Use YYYY-MM-DD. - `mode` ("range" | "single", default 'single'): Select one date or a range with a start and an end date. - `name` (string | undefined): Form-data key. A range is submitted as a single value. - `next-month-label` (string, default 'Next month'): Localized accessible name of the next-month button. - `previous-month-label` (string, default 'Previous month'): Localized accessible name of the previous-month button. - `required` (boolean, default false): Requires a complete date or pair of dates for native form submission. - `value` (string, default ''): Current ISO date, ISO start/end pair or empty string. The value attribute is the reset default. Slots: none Parts: - `day`: Date button in the calendar grid. - `error`: Live constraint message replacing help when the field is invalid. - `field`: Enclosure of the text field and calendar button. - `grid`: Calendar grid with localized weekdays and date buttons. - `help`: Help text associated with the input. - `input`: Native text entry for a localized date or range. - `label`: Visible label and accessible name of the text field. - `month`: Live month and year heading. - `popup`: Anchored non-modal calendar dialog. - `trigger`: Button that opens and closes the calendar. Events: - `ki-change` (CustomEvent): Reports a changed, committed value in canonical ISO form. Use this for calendar and typed changes. Methods: none CSS custom properties: - `--ki-control-border-width`: Stroke width of the boundary of a compact control. - `--ki-control-radius-track`: Corner radius of a track containing adjacent controls. - `--ki-control-size-sm`: Small control track height, 32 CSS px at the default root size. - `--ki-control-size-touch`: Touch target size for controls on a coarse pointer. - `--ki-date-picker-backdrop-filter`: Complete filter behind the calendar. - `--ki-date-picker-bg`: Fill of the calendar dialog. - `--ki-date-picker-bg-image`: Optional image layered over the calendar fill. - `--ki-date-picker-border`: Calendar surface edge. - `--ki-date-picker-day-hover-bg`: Hover fill of an available unselected day. - `--ki-date-picker-day-hover-fg`: Ink on the hover fill. - `--ki-date-picker-day-radius`: Radius of a day and the ends of a range. - `--ki-date-picker-day-size`: Default size of a day target. - `--ki-date-picker-fg`: Default calendar text. - `--ki-date-picker-field-bg`: Fill of the text field. - `--ki-date-picker-field-fg`: Text, icon and caret of the field. - `--ki-date-picker-heading-family`: Family of the calendar month heading. - `--ki-date-picker-outside-bg`: Fill behind dates in neighboring months. - `--ki-date-picker-outside-fg`: Ink of dates in neighboring months. - `--ki-date-picker-radius`: Calendar popup corner radius. - `--ki-date-picker-range-bg`: Fill of the span between selected endpoints. - `--ki-date-picker-range-fg`: Text of dates within the span. - `--ki-date-picker-selected-bg`: Fill of a chosen day or range endpoint. - `--ki-date-picker-selected-fg`: Text of a chosen day or range endpoint. - `--ki-date-picker-shadow`: Calendar popup elevation. - `--ki-date-picker-today-border`: Outline of the current date. - `--ki-date-picker-weekday-bg`: Fill behind weekday names. - `--ki-date-picker-weekday-fg`: Ink of weekday names. - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-offset`: Gap between a focusable component and its keyboard focus ring. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. - `--ki-glyph-size-md`: Medium glyph for body content (20px at the default root size). - `--ki-layout-spacing-3xl`: The 3xl spacing step for a stack or grid gap. - `--ki-layout-spacing-lg`: The lg spacing step for a stack or grid gap. - `--ki-layout-spacing-md`: The md spacing step for a stack or grid gap. - `--ki-layout-spacing-xl`: The xl spacing step for a stack or grid gap. - `--ki-layout-spacing-xs`: The xs spacing step for a stack or grid gap. - `--ki-outline-control`: The boundary of a control that can be EMPTY — field, checkbox, radio, switch. Such a control carries no label inside its own box, so the box IS what identifies it and must clear WCAG 1.4.11's 3:1 against every surface it can sit on (s0-s2). Pinned to an accessibility floor, NOT to a position in the emphasis ramp: rebalancing outline.base/low/med/high must never silently erase a control's edge. MarsUI draws Outline/Black-8 here, but as a bevel over a filled cell on a fixed canvas — transcribed literally it measured 1.19:1 against a fill identical to the page (audit 2026-07-25). Declared deviation. - `--ki-outline-danger-high-em`: semantic color for outline danger high em. - `--ki-surface-transparent`: Transparent surface backing for a background image that carries its own opacity. - `--ki-text-danger-high-em`: semantic color for text danger high em. - `--ki-text-high-em`: semantic color for text high em. - `--ki-text-supporting`: Supporting text of an enabled control: field labels, placeholders, list secondary lines, quiet button labels and unselected tabs. A role, distinct from the med-em emphasis step it resolves to, so a mode can strengthen enabled supporting text without touching the disabled ink that also draws from med-em (directly, or through text.muted). - `--ki-typography-family-body`: semantic font family for typography family body. - `--ki-typography-line-height-body-1`: semantic dimension for typography line height body 1. - `--ki-typography-line-height-caption-2`: semantic dimension for typography line height caption 2. - `--ki-typography-size-body-1`: semantic dimension for typography size body 1. - `--ki-typography-size-caption-2`: semantic dimension for typography size caption 2. - `--ki-typography-weight-body-medium`: semantic font weight for typography weight body medium. - `--ki-typography-weight-body-semibold`: semantic font weight for typography weight body semibold. ### ki-details A native disclosure for supporting information that can stay collapsed. When to use: reveal a short explanation, FAQ answer, settings section or tool output on demand. Use ki-accordion for related disclosures. When NOT to use: hide the primary action or information needed to complete a task. For script-free HTML, author native details and summary directly. Examples: ### Workspace permissions Use one disclosure for an explanation the reader can reveal on demand. Use the plain `summary` prop for text or a heading in the `summary` slot. The default slot contains the answer. ```html

Only people you invite can see it.

``` Listen for `ki-toggle` on the disclosure to read `event.detail.open`. In a catalog surface, bind the action to the individual Details node. Attributes: - `disabled` (boolean, default false): Disables summary activation. The page can still set open. - `name` (string | undefined): Nonempty name for exclusive disclosures in the same document or shadow root. - `open` (boolean, default false): Whether the panel is open. Native changes reflect back to this property. - `summary` (string | undefined): Plain label for the control. Supply the summary slot for a rich label. Slots: - (default): Content shown when the disclosure is open. - `summary`: Rich summary text or an authored heading, replacing the summary prop. Parts: none Events: - `ki-toggle` (CustomEvent): Emitted when the native disclosure toggles or an exclusive peer closes it. Methods: none CSS custom properties: - `--ki-density-space-scale`: Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-details-backdrop-filter`: Complete filter for the backdrop behind the disclosure surface. - `--ki-details-bg`: Color of the disclosure surface. - `--ki-details-bg-image`: Optional image painted over the disclosure surface. - `--ki-details-body-bg`: Surface color of the disclosure body. - `--ki-details-body-fg`: Supporting text color of the disclosure body. - `--ki-details-border`: Color of the disclosure frame and accordion separators. - `--ki-details-border-width`: Width of the disclosure or accordion frame. - `--ki-details-disabled-fg`: Text and icon color of a disabled summary. - `--ki-details-fg`: Text color on the disclosure surface. - `--ki-details-motion-duration`: Duration of the chevron rotation. - `--ki-details-motion-easing`: Easing of the chevron rotation. - `--ki-details-padding`: Inline inset of the summary and inset of the panel body. - `--ki-details-radius`: Corners of a standalone disclosure or the accordion frame. - `--ki-details-summary-hover-bg`: Surface color of a hovered summary. - `--ki-details-summary-hover-fg`: Text and icon color of a hovered summary. - `--ki-details-summary-padding-block`: Block inset of the summary. - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. - `--ki-typography-family-body`: semantic font family for typography family body. - `--ki-typography-line-height-body-1`: semantic dimension for typography line height body 1. - `--ki-typography-line-height-para`: semantic dimension for typography line height para. - `--ki-typography-size-body-1`: semantic dimension for typography size body 1. - `--ki-typography-weight-body-medium`: semantic font weight for typography weight body medium. ### ki-dialog A modal dialog for an interrupting decision or a focused task. When to use: destructive confirmations, blocking choices, and brief critical input that must be resolved before returning to the page. Always provide a `heading`, place actions in the `footer` slot, wire each dismissal to `close()` or a close command, and in destructive confirmations put `autofocus` on the least destructive action. Use `fullscreen="compact"` for longer tasks that need the whole window on compact screens. When NOT to use: non-blocking feedback (`ki-alert`, `ki-toast`), supplementary hints (`ki-tooltip`), multi-step flows that need their own page, menus, or pickers. Examples: A modal confirmation. `heading` names the dialog and actions go in the `footer` slot. Each invoker uses the dialog's ID within the same document or shadow root. ```html Delete draft

This permanently removes the draft.

Cancel Delete
``` `close` dismisses the dialog. `request-close` first gives the dialog a chance to cancel the request. After an accepted close command, the opening button regains focus and `ki-close` reports `detail.reason: 'command'`. `show()` and `close()` remain available for programmatic control. ## Edit a longer form ```html Add event ``` Below 600 CSS pixels the modal fills the window and keeps its heading and actions visible above the scrollable body. At wider widths `Save` moves to the centered dialog's footer. Handle `ki-confirm` to save the form and call `close()` after success. In fullscreen, call `preventDefault()` on `ki-close` to veto Escape or the header close button while editing. When importing the dialog directly, register `ki-button` to use the themed confirmation button. A single-element import still provides a native confirmation button with the same label and event. Attributes: - `close-label` (string, default 'Close'): Accessible name for the fullscreen close button. Localize it or describe the effect of dismissing, for example "Discard and close". - `close-on-backdrop` (boolean, default false): Opts into backdrop light-dismiss. Omit this attribute for critical confirmations; `close-on-backdrop="false"` still enables it. When to use: low-risk dialogs where an outside click may safely dismiss. When NOT to use: destructive confirmations or decisions that should not be lost to a stray click; omit the attribute entirely rather than setting it to `"false"`. - `confirm-label` (string | undefined): Label for the optional confirmation button. Use an action verb such as "Save". The button is in the fullscreen header or the centered footer. - `fullscreen` ("always" | "compact" | "never", default 'never'): Layout for the native modal. Use `compact` to fill windows narrower than 600 CSS pixels, or `always` to fill any window. Use `never` for a centered dialog at every width. - `heading` (string, required): Visible dialog title and accessible-name source. Always provide a heading; an empty value intentionally leaves the native dialog unnamed. When to use: name the interrupting decision, for example "Delete account?". When NOT to use: do not omit it for production dialogs; APG modal dialogs require an accessible name. - `open` (boolean, default false): Reflected live modal state. Add it or call `show()` to open; remove it or call `close()` to close. When open, the native dialog enters the top layer and the page behind is inert. When to use: bind application state to the dialog's modal lifecycle. When NOT to use: do not set the internal native `` attribute; the host attribute is the only public source of truth. Slots: - (default): Dialog body content. - `footer`: Dialog actions. Dismiss using an invoker command or `close()`. Parts: - `body`: Scrollable body region. - `dialog`: Internal native dialog surface. - `footer`: Action row, collapsed when empty. - `header`: Fullscreen bar with the title and its controls. - `heading`: Visible h2 title, rendered only when `heading` is non-empty. Events: - `ki-close` (CustomEvent): Requests dismissal on fullscreen Escape or activation of the header close button. Prevent the default on that cancelable event to keep the modal open. The button reports `method` and Escape reports `escape`. Every other dismissal path emits a noncancelable notification after close and focus restoration. Use `open` to observe the modal's live state. - `ki-confirm` (CustomEvent): The user activated the confirmation button. Handle validation, submission and dismissal in the application. Methods: - `close()` (Promise): Closes the dialog and reports `method`. No-op when already closed. Equivalent to removing the host `open` attribute. Footer actions never close automatically; wire them to this method or an invoker command. When to use: resolve footer actions, programmatic dismissals, and application-controlled cancellation. When NOT to use: do not use for Escape or backdrop bookkeeping; those paths set their own close reasons. - `show()` (Promise): Opens the dialog modally. No-op when already open. Equivalent to adding the host `open` attribute. When to use: call from the invoker that should receive focus again after close. When NOT to use: do not call repeatedly to refresh content; update slotted content directly while open. CSS custom properties: - `--ki-button-primary-neutral-rest-bg`: color used by the button component for primary neutral rest background (MarsUI Surface/primary_med_em, brand 500). - `--ki-button-primary-neutral-rest-fg`: color used by the button component for primary neutral rest foreground. - `--ki-control-radius-item`: Corner radius of an individual control inside a track. - `--ki-control-size-md`: Medium control track height, 40 CSS px at the default root size. - `--ki-density-space-scale`: Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-dialog-backdrop-bg`: color used by the dialog component for backdrop background. - `--ki-dialog-backdrop-filter`: Complete backdrop filter behind the dialog surface. - `--ki-dialog-bg`: Base background color of the dialog. Onmars v1 uses a transparent backing beneath its glass image. - `--ki-dialog-bg-image`: Optional CSS background image layered over the dialog fill. Use none for a solid fill. - `--ki-dialog-body-padding-block-end`: dimension used by the dialog component for body section padding block end (Modal compact Body: Space/5xl 20px.) - `--ki-dialog-body-padding-block-start`: dimension used by the dialog component for body section padding block start (Modal compact Body 16414:19668: Space/5xl 20px.) - `--ki-dialog-body-padding-inline`: dimension used by the dialog component for body section padding inline (Modal compact Body: Space/5xl 20px.) - `--ki-dialog-border`: border used by the dialog component for border (MarsUI 1px solid Outline/base_em Black/3 light / White/3 dark; retires the migrated Black/5 foundation reference). - `--ki-dialog-divider-color`: color used by the dialog component for the dividers under the heading and above the footer (Outline/base-em). - `--ki-dialog-divider-width`: dimension used by the dialog component for the dividers under the heading and above the footer (Modal-header and Modal-actions 1px strokes). Zero removes them. - `--ki-dialog-fg`: color used by the dialog component for foreground. - `--ki-dialog-focus-ring-color`: color used by the dialog component for focus ring color. - `--ki-dialog-focus-ring-offset`: dimension used by the dialog component for focus ring offset. - `--ki-dialog-focus-ring-width`: dimension used by the dialog component for focus ring width. - `--ki-dialog-footer-padding-block-end`: dimension used by the dialog component for footer section padding block end (Modal-actions/CTAs: Space/7xl 24px.) - `--ki-dialog-footer-padding-block-start`: dimension used by the dialog component for footer section padding block start (Modal-actions/CTAs 14158:28302: Space/7xl 24px, below the divider.) - `--ki-dialog-footer-padding-inline`: dimension used by the dialog component for footer section padding inline (Modal-actions/CTAs: Space/5xl 20px.) - `--ki-dialog-fullscreen-backdrop-filter`: Complete backdrop filter for the fullscreen surface. - `--ki-dialog-fullscreen-bg`: Solid raised surface for the fullscreen dialog. - `--ki-dialog-fullscreen-bg-image`: Optional image over the fullscreen fill. - `--ki-dialog-fullscreen-fg`: Foreground for the fullscreen dialog. - `--ki-dialog-fullscreen-header-border`: Divider beneath the fullscreen header. - `--ki-dialog-fullscreen-header-height`: Minimum block size of the fullscreen header. - `--ki-dialog-gap`: dimension used by the dialog component for the gap between its footer actions (Modal-actions/CTAs 14158:28302: Space/xl 12px). - `--ki-dialog-heading-font-family`: Font family for the dialog heading. Override it to give dialogs their own heading typeface. - `--ki-dialog-heading-font-size`: dimension used by the dialog component for heading font size. - `--ki-dialog-heading-font-weight`: font weight used by the dialog component for heading font weight. - `--ki-dialog-heading-letter-spacing`: Letter spacing for the dialog heading. Override it to tune tracking for the chosen heading typeface. - `--ki-dialog-heading-line-height`: dimension used by the dialog component for heading line height. - `--ki-dialog-heading-padding-block-end`: dimension used by the dialog component for heading section padding block end (Modal-header compact: Space/3xl 16px, above the divider.) - `--ki-dialog-heading-padding-block-start`: dimension used by the dialog component for heading section padding block start (Modal-header compact 14156:25916: Space/3xl 16px.) - `--ki-dialog-heading-padding-inline`: dimension used by the dialog component for heading section padding inline (Modal-header compact: Space/5xl 20px.) - `--ki-dialog-max-width`: dimension used by the dialog component for max width (surface size scale; the former ki.space.26xl reference misused the spacing scale). - `--ki-dialog-min-width`: dimension used by the dialog component for min width (surface size scale; the former ki.space.25xl reference misused the spacing scale). - `--ki-dialog-motion-duration`: duration used by the dialog component for the enter transition (MarsUI moderate step 240ms; retires the migrated 0ms token that disabled the @starting-style fade). - `--ki-dialog-motion-easing`: easing used by the dialog component for the enter transition (MarsUI decelerate curve; retires the migrated linear pair). - `--ki-dialog-padding`: dimension used by the dialog component for the room it keeps from the viewport edges when its width or height is clamped. Each section pads itself (heading, body and footer padding tokens). - `--ki-dialog-radius`: dimension used by the dialog component for radius (MarsUI compact Modal master 16414:19665: Radius/big_component/radius_sm 20px; the large variant anchors 24px big_component/radius_md). - `--ki-dialog-shadow`: Dialog elevation: MarsUI elevation ramp level e4 (brief §5, high modal surface; replaces the migrated approximation). material3 keeps its own e3 override (M3 dialog = level3). - `--ki-elevation-none`: Flat surfaces carry no resting shadow. - `--ki-focus-primary`: MarsUI Focus/primary: 3px spread focus ring of Outline/primary_base_em_alpha, read from the Figma master as #845abe33 = brand 500 at 20% (Kimen name: outline.primary-base-em-alpha / brand.500-alpha-2). The previous 40% (outline.primary-low-em-alpha / brand.500-alpha-4) came from specs/002-ki-button/design-extraction.md §2.5, which read the alpha off the Dark canvas mode and recorded it as the Light value; the ring shipped 2x too strong in light and 2.8x in dark across twelve components. - `--ki-layout-spacing-md`: The md spacing step for a stack or grid gap. - `--ki-layout-spacing-xs`: The xs spacing step for a stack or grid gap. - `--ki-motion-distance-md`: Motion travel distance md (8px): entrance slide offsets (e.g. dialog rise). - `--ki-motion-duration-fast`: Fast interaction transition duration. - `--ki-motion-easing-out`: Decelerating interaction transition easing curve. - `--ki-motion-easing-standard-accelerate`: Utility exit curve. M3 md.sys.motion.easing.standard-accelerate. onmars: the MarsUI accelerate curve (ki.easing.in). - `--ki-spacing-action-hairline`: Width of the frame and divider in an action surface. - `--ki-state-layer-hover`: Hover interaction state layer. M3 md.sys.state.hover.state-layer-opacity: 8% of the on-color. onmars: the MarsUI hover_overlay (White/5 light, Black/5 dark). - `--ki-state-layer-pressed`: Pressed interaction state layer. M3 md.sys.state.pressed.state-layer-opacity: 12% of the on-color (same as focus). onmars: MarsUI overlay one step above hover_overlay (White/8 light, Black/8 dark). - `--ki-surface-transparent`: Transparent surface backing for a background image that carries its own opacity. - `--ki-typography-family-body`: semantic font family for typography family body. - `--ki-typography-family-heading`: Shared font family for component headings. Reassign it on a theme root to style headings independently of body copy. - `--ki-typography-line-height-para`: semantic dimension for typography line height para. - `--ki-typography-size-body-1`: semantic dimension for typography size body 1. - `--ki-typography-weight-body-normal`: semantic font weight for typography weight body normal. - `--ki-typography-weight-body-semibold`: semantic font weight for typography weight body semibold. ### ki-divider A static, decorative rule that visually separates adjacent content. When to use: visually separate adjacent content when spacing alone is not enough: grouped settings sections, toolbar action groups, distinct regions inside a card — horizontal between stacked content, vertical between side-by-side content. When NOT to use: between list items (separation is a ki-list theme-token decision), semantic thematic breaks in running prose (native `
` carries those semantics — the divider is deliberately decorative and contributes no role, name or announcement), as a border or outline substitute (surface/border tokens), or purely decorative flourishes (prefer white space). Examples: A horizontal rule between stacked content; the divider is decorative — no role, no name, no tab stop (semantic thematic breaks belong to native `
`): ```html
Profile
Notifications
``` `orientation="vertical"` separates side-by-side content and stretches to the cross size its layout context provides — give the row a height or let flex stretch it: ```html
Edit Share
``` An inset is a per-instance layout decision — use logical margins on the instance; thickness, color, end caps and gutter stay per-theme `--ki-divider-*` tokens, never attributes: ```html ``` Attributes: - `orientation` ("horizontal" | "vertical", default 'horizontal'): Layout axis of the rule: `horizontal` spans the available inline size between stacked content; `vertical` stretches to the cross size its layout context provides, between side-by-side content. A structural axis, never appearance — thickness, color, end caps and gutter are per-theme `--ki-divider-*` tokens. An unrecognized value matches no style selector, so the divider keeps the default horizontal rendering (fallback by CSS construction — no validation code). Slots: none Parts: - `divider`: The rule itself: thickness, color and end-cap radius. Events: none Methods: none CSS custom properties: - `--ki-divider-color`: color used by the divider component for the rule: Outline/base_em (Black/3 light, White/3 dark), the exact variable bound to every Figma divider variant and the same semantic role ki-list uses for item dividers. - `--ki-divider-radius`: dimension used by the divider component for the end caps: the MarsUI ends axis is a pure-appearance, per-theme choice (FR-006); onmars keeps the rounded hairline (ends=rounded, pill caps). - `--ki-divider-spacing`: dimension used by the divider component for the reserved gutter: the 8px MarsUI variant frame with the rule centered inside it (FR-007). - `--ki-divider-thickness`: dimension used by the divider component for the rule thickness: the MarsUI 1px hairline verified on the Divider_horizontal/Divider_vertical sets (specs/020-ki-divider/design-extraction.md). - `--ki-motion-duration-fast`: Fast interaction transition duration. - `--ki-motion-easing-standard-decelerate`: Utility entrance curve. M3 md.sys.motion.easing.standard-decelerate. onmars: the MarsUI decelerate curve (ki.easing.out). - `--ki-typography-family-body`: semantic font family for typography family body. ### ki-drawer An edge-aligned sheet for a focused task that keeps the current page in context. When to use: Edit an item beside its list or offer a short set of actions in a bottom sheet. Supply a heading and wire slotted actions in the application. Use non-modal mode if people need to interact with the page while editing. When NOT to use: Menus, hover hints, permanent navigation, or work that needs a full page. For a short interrupting decision in the center, use ki-dialog. Examples: ## Edit details beside a list Use `heading` to name the sheet. Open it from a focused trigger so focus can return there. The app wires its own footer actions. ```html Edit incident Save ``` ## Offer a short list of actions A bottom sheet has a swipe handle and a keyboard-accessible Close button. Use `close-label` to translate the button for your audience. ```html

Choose how to share the incident.

Email Copy link
``` Use `modal="false"` when the page behind the drawer should stay interactive. `placement="start"` and `placement="end"` follow the inherited direction. Attributes: - `close-label` (string | undefined, default 'Close'): Accessible name for the built-in Close button. Translate this for localized interfaces. - `heading` (string, required): Title and accessible name. Provide a heading whenever the drawer opens. - `modal` (boolean, default true): Makes the page behind the sheet inert. Set modal="false" for continued page interaction. - `open` (boolean, default false): Reflected live state. Setting it to false requests dismissal and may be vetoed. - `placement` ("bottom" | "end" | "start", default 'end'): Logical edge. Use bottom for an action sheet with a swipe handle. Unknown values use end. - `size` (string | undefined): Optional CSS length. Overrides the 18rem themed width or bottom height cap. Slots: - (default): The drawer's content, such as fields or a short list of actions. - `footer`: Optional actions such as Save. Wire these in the application. - `header-actions`: Optional actions between the heading and Close button. Parts: - `body`: The scrollable content region. - `close`: The built-in Close button. - `dialog`: The native sheet surface. - `footer`: The action row, collapsed when empty. - `handle`: The decorative bottom-sheet swipe handle. - `header`: The heading and action layout. - `heading`: The visible title that names the sheet. Events: - `ki-close` (CustomEvent): Requests dismissal before the drawer closes. Call preventDefault() to keep it open, for example when edits are unsaved. The event carries the reason in detail.reason. Methods: - `close()` (Promise): Requests dismissal. An application can veto it by canceling ki-close. - `show()` (Promise): Opens the sheet. A focused invoker receives focus again after modal dismissal. CSS custom properties: - `--ki-corner-control`: Deprecated alias kept for pre-Fase-1 consumers; use ki.radius.md. - `--ki-density-space-scale`: Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-dialog-backdrop-bg`: color used by the dialog component for backdrop background. - `--ki-dialog-divider-width`: dimension used by the dialog component for the dividers under the heading and above the footer (Modal-header and Modal-actions 1px strokes). Zero removes them. - `--ki-drawer-backdrop-filter`: Complete backdrop filter applied behind the drawer surface. - `--ki-drawer-bg`: Raised surface color of the drawer. - `--ki-drawer-bg-image`: Optional image layered over the drawer surface. - `--ki-drawer-close-size`: Preferred size of the Close button before the density minimum. - `--ki-drawer-fg`: Foreground color on the drawer surface. - `--ki-drawer-handle-color`: Color of the bottom-sheet handle. - `--ki-drawer-handle-size`: Inline extent of the bottom-sheet handle. - `--ki-drawer-handle-thickness`: Thickness of the bottom-sheet handle. - `--ki-drawer-heading-font-family`: Typeface of the drawer title. - `--ki-drawer-radius`: Radius of the corners on the inner edge of the drawer. - `--ki-drawer-shadow`: Resting elevation of the drawer. - `--ki-drawer-size`: Default inline size of a side sheet and block-size cap of a bottom sheet. - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. - `--ki-layout-spacing-2xl`: The 2xl spacing step for a stack or grid gap. - `--ki-layout-spacing-md`: The md spacing step for a stack or grid gap. - `--ki-layout-spacing-xl`: The xl spacing step for a stack or grid gap. - `--ki-motion-duration-fast`: Fast interaction transition duration. - `--ki-motion-duration-medium-1`: M3 md.sys.motion.duration.medium1 (250ms). onmars: MarsUI moderate step (240ms, 2x the 120ms base). - `--ki-motion-easing-out`: Decelerating interaction transition easing curve. - `--ki-outline-low-em`: semantic color for outline low em. - `--ki-surface-hover-overlay-inverse`: semantic color for surface hover overlay inverse. - `--ki-surface-transparent`: Transparent surface backing for a background image that carries its own opacity. - `--ki-typography-family-body`: semantic font family for typography family body. - `--ki-typography-line-height-title-2`: semantic dimension for typography line height title 2. - `--ki-typography-size-title-2`: semantic dimension for typography size title 2. - `--ki-typography-weight-body-semibold`: semantic font weight for typography weight body semibold. ### ki-empty-state A short explanation and next step for an empty view. When to use: explain an empty list, table, search result, or first-run view. Supply a localized heading that names what is empty and a short next step. Use announce for results that change after an interaction. When NOT to use: signal that results are loading or draw attention to an error that needs acknowledgement. Use ki-spinner or ki-alert for those states. Examples: Use EmptyState when a list, table or first-run screen is empty. Name what is empty, explain why or what to do next, and offer at most one primary action. ```ts import '@kimen/elements/icons/folder-plus'; ``` ```html Projects hold your surfaces, catalogs and themes. New project ``` Use `announce` for search or filter results. Insert the message when results become empty. If it remains visible for a subsequent search, update its heading and description. ```html Check the spelling or remove a filter. Clear filters ``` Put a decorative illustration in `media` to replace the icon. ```html New messages will appear here. ``` Attributes: - `announce` (boolean, default false): Put the heading and description in a polite status, with actions outside the region. Set before mounting a message that reports changed results. - `heading` (string, required): Localized heading that identifies the empty view. Blank text omits the heading. - `heading-level` (number, default 3, minimum 2, maximum 6): Native heading level for the surrounding document outline. Only integers from 2 through 6 are valid; unsupported values use level 3. - `icon-name` (string | undefined): Optional decorative Lucide glyph. Register it with a per-icon import before mounting. A supplied illustration takes precedence. - `size` ("md" | "sm", default 'md'): Use small inside a table or narrow panel. Unrecognized sizes use the medium layout. - `tone` ("danger" | "info" | "neutral" | "primary" | "primary-light" | "success" | "warning", default 'neutral'): FeatureIcon tone. Unrecognized tones use the neutral tile. Slots: - (default): Localized supporting text with a reason or recovery advice. - `actions`: Optional controls for the next step, with at most one primary action. In a guarded surface, bind actions to these controls. - `media`: Optional decorative illustration in place of the icon. Use an image with empty alt text or a decorative SVG. Keep this slot free of controls. Parts: - `actions`: Wrapping row of consumer-supplied controls. - `container`: Centered layout for the illustration, message and actions. - `description`: Wrapper for the default slot. - `heading`: Native heading at the selected document level. - `media`: Decorative illustration or FeatureIcon tile. Events: none Methods: none CSS custom properties: - `--ki-empty-state-backdrop-filter`: Complete filter applied behind the empty view. - `--ki-empty-state-bg`: Background behind the empty view. - `--ki-empty-state-bg-image`: Optional image above the background color. - `--ki-empty-state-description-bg`: Background layer behind the supporting copy. - `--ki-empty-state-description-fg`: Supporting text ink, strengthened in contrast-more mode. - `--ki-empty-state-description-line-height`: Line height of the supporting copy. - `--ki-empty-state-description-size`: Font size of the supporting copy. - `--ki-empty-state-fg`: Foreground ink for the heading. - `--ki-empty-state-gap`: Gap between the decorative media, message and action row. - `--ki-empty-state-gap-sm`: Gap between regions in a compact empty view. - `--ki-empty-state-heading-font-family`: Typeface for the native heading. - `--ki-empty-state-heading-line-height`: Heading line height in a regular empty view. - `--ki-empty-state-heading-line-height-sm`: Heading line height in a compact empty view. - `--ki-empty-state-heading-size`: Heading font size in a regular empty view. - `--ki-empty-state-heading-size-sm`: Heading font size in a compact empty view. - `--ki-empty-state-heading-weight`: Weight of the heading. - `--ki-empty-state-max-width`: Maximum inline size of the centered content. - `--ki-empty-state-tile-danger-bg`: Background of the danger decorative tile. - `--ki-empty-state-tile-danger-fg`: Glyph ink on the danger decorative tile. - `--ki-empty-state-tile-info-bg`: Background of the info decorative tile. - `--ki-empty-state-tile-info-fg`: Glyph ink on the info decorative tile. - `--ki-empty-state-tile-neutral-bg`: Background of the neutral decorative tile. - `--ki-empty-state-tile-neutral-fg`: Glyph ink on the neutral decorative tile. - `--ki-empty-state-tile-primary-bg`: Background of the primary decorative tile. - `--ki-empty-state-tile-primary-fg`: Glyph ink on the primary decorative tile. - `--ki-empty-state-tile-primary-light-bg`: Background of the primary-light decorative tile. - `--ki-empty-state-tile-primary-light-fg`: Glyph ink on the primary-light decorative tile. - `--ki-empty-state-tile-radius`: Corner radius of the regular fallback tile. - `--ki-empty-state-tile-radius-sm`: Corner radius of the compact fallback tile. - `--ki-empty-state-tile-size`: Regular FeatureIcon fallback tile size. - `--ki-empty-state-tile-size-sm`: Compact FeatureIcon fallback tile size. - `--ki-empty-state-tile-success-bg`: Background of the success decorative tile. - `--ki-empty-state-tile-success-fg`: Glyph ink on the success decorative tile. - `--ki-empty-state-tile-warning-bg`: Background of the warning decorative tile. - `--ki-empty-state-tile-warning-fg`: Glyph ink on the warning decorative tile. - `--ki-typography-family-body`: semantic font family for typography family body. ### ki-fab The primary action of a screen, as an icon or an extended control with a visible label. When to use: give a mobile screen one primary action, such as composing a draft or creating a project. Supply a descriptive label and a registered icon or decorative icon slot. Reserve page clearance for fixed placement, and leave the action binding unset for native link navigation. When NOT to use: for secondary or destructive actions, for multiple actions on the same screen, or on a desktop screen that already has a visible primary ki-button. Examples: # Using ki-fab Use one FAB for the primary action of a screen. Give it a localized `label` in every layout. Import each Lucide glyph before mounting a FAB that names it. Use the native `click` event to call your application's action handler. ```js import '@kimen/elements/icons/pencil'; import { defineCustomElement } from '@kimen/elements/ki-fab'; defineCustomElement(); document.querySelector('#compose')?.addEventListener('click', openComposer); ``` ```html ``` Use `href` when activation takes the user to a destination. To supply a custom glyph, use the `icon` slot with decorative, noninteractive content. ```html ``` Place a fixed FAB after the main content so its tab stop follows the page's controls. Reserve bottom space so the last item can scroll above it. Set `--ki-fab-mobile-nav-block-size` to the height of the fixed navigation when present, excluding the safe area. ```html
``` ```css :root { --ki-fab-mobile-nav-block-size: var(--app-mobile-nav-height, 0px); --compose-clearance: calc( var(--ki-fab-size) + 2 * var(--ki-fab-offset) + var(--ki-fab-mobile-nav-block-size) + env(safe-area-inset-bottom, 0px) ); scroll-padding-block-end: var(--compose-clearance); } .compose-page { padding-block-end: var(--compose-clearance); } ``` The clearance above uses the default `md` size. Adjust it for a larger FAB and use the actual expanded height if the label wraps. The label hides as the user scrolls down the document and reappears on upward scroll. The native control retains its accessible name and focus. Attributes: - `collapse-on-scroll` (boolean, default false): Compact an extended FAB on viewport scroll down and restore on scroll up. - `extended` (boolean, default false): Show the action label next to its icon. - `href` (string | undefined, URL): A nonempty destination renders an anchor. Relative URLs and fragments retain native resolution. - `icon-name` (string | undefined): Registered Lucide name. Import the icon module before rendering. The icon slot takes precedence. - `label` (string, required): Accessible name of the action. Also the visible text in the extended state. - `position` ("fixed" | "static", default 'static'): Fixed sits at the viewport's block-end inline-end corner. Reserve page clearance there. - `size` ("lg" | "md" | "xl", default 'md'): Square footprint when icon-only, and minimum size when extended. - `variant` ("primary" | "secondary" | "surface", default 'secondary'): Surface and ink: strong primary, tinted secondary or raised surface. Slots: - `icon`: Decorative, noninteractive icon replacing the named glyph. Parts: - `control`: The native button or link, including its surface and focus ring. - `icon`: Wrapper for the decorative named or slotted glyph. - `label`: Visible label of an extended FAB. Events: - `click` (Event): Native activation click. The page or guarded renderer handles the declared action. Methods: none CSS custom properties: - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-fab-backdrop-filter`: Complete optional filter behind the FAB. - `--ki-fab-bg`: Tinted secondary FAB fill. - `--ki-fab-bg-image`: Optional layer painted over the FAB fill. - `--ki-fab-collapse-duration`: Duration of the extended FAB footprint change. - `--ki-fab-collapse-easing`: Easing of the extended FAB footprint change. - `--ki-fab-fg`: Ink on the tinted secondary FAB. - `--ki-fab-font-family`: Typeface for FAB labels. - `--ki-fab-font-size`: Text size for extended FAB labels. - `--ki-fab-font-weight`: Text weight for extended FAB labels. - `--ki-fab-forced-colors-border-width`: Boundary width for the FAB in forced colors. - `--ki-fab-gap`: Space between icon and label in an extended FAB. - `--ki-fab-hover-shadow`: FAB elevation for a pointer that can hover. - `--ki-fab-icon-size`: Glyph size of the default FAB. - `--ki-fab-lg-icon-size`: Glyph size of the medium FAB. - `--ki-fab-lg-radius`: Corner radius of the medium FAB. - `--ki-fab-lg-size`: Minimum footprint of the medium FAB. - `--ki-fab-line-height`: Line height for extended FAB labels. - `--ki-fab-mobile-nav-block-size`: Height to reserve for mobile navigation, excluding the safe-area inset. - `--ki-fab-offset`: Fixed FAB gap to the viewport edge or mobile navigation. - `--ki-fab-padding-inline-end`: Inline end padding of an extended FAB. - `--ki-fab-padding-inline-start`: Inline start padding of an extended FAB. - `--ki-fab-primary-bg`: Strong primary FAB fill. - `--ki-fab-primary-fg`: Ink on the strong primary FAB. - `--ki-fab-radius`: Corner radius of the default FAB size. - `--ki-fab-shadow`: Resting FAB elevation. - `--ki-fab-size`: Minimum FAB footprint in the default size. - `--ki-fab-surface-bg`: Raised surface FAB fill. - `--ki-fab-surface-fg`: Ink on the raised surface FAB. - `--ki-fab-xl-icon-size`: Glyph size of the large FAB. - `--ki-fab-xl-radius`: Corner radius of the large FAB. - `--ki-fab-xl-size`: Minimum footprint of the large FAB. - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-offset`: Gap between a focusable component and its keyboard focus ring. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. ### ki-fab-menu An icon FAB that opens two to six related actions above its trigger. When to use: group related creation or screen actions behind one floating button. When NOT to use: for a single primary action, long lists, or site navigation. Examples: # Floating action menu examples Register optional Lucide glyphs, then register the menu and its item together. ```ts import '@kimen/elements/icons/calendar'; import '@kimen/elements/icons/pencil'; import { defineCustomElement as defineItem } from '@kimen/elements/ki-fab-menu-item'; import { defineCustomElement as defineMenu } from '@kimen/elements/ki-fab-menu'; defineItem(); defineMenu(); ``` ```html New message New event ``` Listen to `ki-select` on the menu to handle commands. Use the stable `value` in the event detail. Leave link navigation to the native anchor. In a catalog spec, bind separate action IDs to command items and supply a stable `value` for each item. Keep link items unbound. Use two to six direct items. Fixed placement shares the FAB's safe-area and navigation clearance tokens. In static placement, leave space above the trigger for the stack. Attributes: - `close-label` (string, default 'Close menu'): Localized accessible name of the trigger when it becomes the close control. - `icon-name` (string, default 'plus'): Registered Lucide glyph for the closed trigger. The plus glyph ships with the component. - `label` (string, required): Accessible name of the closed trigger and of the menu. - `open` (boolean, default false): Whether the action stack is open. Reflected when the user opens or dismisses it. - `position` ("fixed" | "static", default 'static'): Static anchors to the host. Fixed anchors to the viewport's block-end inline-end corner. - `scrim` (boolean, default true): Dim the viewport and dismiss on a scrim click. Use the boolean property or scrim="false" to opt out. - `variant` ("primary" | "secondary" | "surface", default 'secondary'): Closed FAB surface. The open trigger always uses primary. Slots: - (default): Two to six direct ki-fab-menu-item children, in top-to-bottom order. Parts: - `menu`: The named action list above the trigger. - `scrim`: The optional pointer-dismissible overlay behind the menu. - `trigger`: The native floating button that opens and closes the menu. Events: - `ki-close` (CustomEvent): Emitted when the action stack closes. - `ki-open` (CustomEvent): Emitted when the action stack opens. - `ki-select` (CustomEvent): Emits the selected item's value or its trimmed label. Native links retain their destination. Methods: none CSS custom properties: - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-fab-backdrop-filter`: Complete optional filter behind the FAB. - `--ki-fab-bg`: Tinted secondary FAB fill. - `--ki-fab-bg-image`: Optional layer painted over the FAB fill. - `--ki-fab-fg`: Ink on the tinted secondary FAB. - `--ki-fab-font-family`: Typeface for FAB labels. - `--ki-fab-forced-colors-border-width`: Boundary width for the FAB in forced colors. - `--ki-fab-hover-shadow`: FAB elevation for a pointer that can hover. - `--ki-fab-icon-size`: Glyph size of the default FAB. - `--ki-fab-menu-gap`: Gap between two stacked actions. - `--ki-fab-menu-scrim-backdrop-filter`: Complete optional filter behind the scrim. - `--ki-fab-menu-scrim-bg`: Dimming fill behind the open menu and its trigger. - `--ki-fab-menu-scrim-bg-image`: Optional image painted above the scrim fill. - `--ki-fab-menu-trigger-gap`: Gap between the last action and the FAB. - `--ki-fab-mobile-nav-block-size`: Height to reserve for mobile navigation, excluding the safe-area inset. - `--ki-fab-offset`: Fixed FAB gap to the viewport edge or mobile navigation. - `--ki-fab-primary-bg`: Strong primary FAB fill. - `--ki-fab-primary-fg`: Ink on the strong primary FAB. - `--ki-fab-radius`: Corner radius of the default FAB size. - `--ki-fab-shadow`: Resting FAB elevation. - `--ki-fab-size`: Minimum FAB footprint in the default size. - `--ki-fab-surface-bg`: Raised surface FAB fill. - `--ki-fab-surface-fg`: Ink on the raised surface FAB. - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-offset`: Gap between a focusable component and its keyboard focus ring. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. ### ki-fab-menu-item A labeled command or native link within a floating action menu. When to use: as a direct child of ki-fab-menu, with a short, visible action label. When NOT to use: for a standalone action, a form control, or a container of interactive content. Examples: # Floating action menu item examples Place commands and links directly inside a menu and supply visible labels. ```html New message New event ``` The command reports `message` through the parent menu's `ki-select` event. The link reports `New event` and follows its native destination. Attributes: - `href` (string | undefined, URL): A nonempty destination renders a native link and preserves relative URL resolution. - `icon-name` (string | undefined): Registered Lucide glyph. Import the desired icon before rendering. - `value` (string | undefined): Stable selection identifier. When omitted, the menu reports the trimmed visible label. Slots: - (default): The visible action label. Parts: - `control`: The native action button or link. - `icon`: The decorative glyph next to the label. Events: - `ki-select` (CustomEvent): Local command selection for a direct action binding. Links use native navigation. Methods: none CSS custom properties: - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-fab-forced-colors-border-width`: Boundary width for the FAB in forced colors. - `--ki-fab-menu-item-backdrop-filter`: Complete optional filter behind the action. - `--ki-fab-menu-item-bg`: Tinted surface of a floating action. - `--ki-fab-menu-item-bg-image`: Optional image painted above the action fill. - `--ki-fab-menu-item-content-gap`: Space between the action glyph and label. - `--ki-fab-menu-item-fg`: Label and icon ink on the tinted action surface. - `--ki-fab-menu-item-font-family`: Typeface for action labels. - `--ki-fab-menu-item-font-size`: Text size for action labels. - `--ki-fab-menu-item-font-weight`: Text weight of an action label. - `--ki-fab-menu-item-height`: Minimum block size and inline target of an action. - `--ki-fab-menu-item-hover-shadow`: Elevation of a hovered action. - `--ki-fab-menu-item-icon-size`: Size of the glyph preceding an action label. - `--ki-fab-menu-item-line-height`: Line height of an action label. - `--ki-fab-menu-item-padding-block`: Block padding for a wrapping action label. - `--ki-fab-menu-item-padding-end`: Inline-end padding of an action. - `--ki-fab-menu-item-padding-start`: Inline-start padding of an action. - `--ki-fab-menu-item-radius`: Pill radius of an action. - `--ki-fab-menu-item-shadow`: Elevation of a resting action. - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-offset`: Gap between a focusable component and its keyboard focus ring. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. ### ki-feature-icon A decorative glyph centered on a tinted tile. When to use: Place a decorative icon beside the visible heading of a feature, empty state or settings section. The heading carries the meaning. When NOT to use: For an action (use ki-icon-button), a status (use ki-badge), or the sole label of a section. Examples: # Using ki-feature-icon Load the token stylesheet, register each custom element, and import the Lucide glyph you use. Place one glyph with its default inherited size in the slot, next to the heading that names the section. ```js import '@kimen/tokens/css'; import '@kimen/elements/icons/shield-check'; import { defineCustomElement as defineFeatureIcon } from '@kimen/elements/ki-feature-icon'; import { defineCustomElement as defineIcon } from '@kimen/elements/ki-icon'; defineFeatureIcon(); defineIcon(); ``` ```html

Security settings

``` Choose a circle with `shape="circle"`. For an inline SVG, use `currentColor` for the glyph's stroke or fill. Keep controls and meaningful labels outside the tile so they can receive focus and be announced. A guarded catalog surface supplies the glyph as a `ki-icon` node in the default slot. The host imports the glyph before rendering the surface. ```json { "version": 1, "root": { "component": "div", "props": { "direction": "row", "align": "center", "gap": "md" }, "slots": { "": [ { "component": "ki-feature-icon", "props": { "tone": "primary-light" }, "slots": { "": [{ "component": "ki-icon", "props": { "name": "shield-check" } }] } }, { "component": "h2", "slots": { "": ["Security settings"] } } ] } } } ``` Attributes: - `shape` ("circle" | "square", default 'square'): Rounded square or circle. Unknown values use square. - `size` ("lg" | "md" | "sm" | "xl" | "xs", default 'md'): Tile size. At a 16px root, the steps are 24, 32, 40, 48 and 64px. Unknown values use md. - `tone` ("danger" | "info" | "neutral" | "primary" | "primary-light" | "success" | "warning", default 'neutral'): Colour pair for the tile and its glyph. Unknown values use neutral. Slots: - (default): One Lucide glyph. Supply an inline SVG using currentColor or a ki-icon with inherited size. Guarded surfaces use a registered ki-icon. Parts: - `tile`: The painted tile that centers the glyph. Events: none Methods: none CSS custom properties: - `--ki-feature-icon-backdrop-filter`: Complete filter applied behind the feature icon tile. - `--ki-feature-icon-bg`: Background color of a neutral feature icon tile. - `--ki-feature-icon-bg-image`: Optional background image painted over the feature icon tile color. - `--ki-feature-icon-circle-radius`: Corner radius of a circular feature icon tile. - `--ki-feature-icon-danger-bg`: Background color of a danger feature icon tile. - `--ki-feature-icon-danger-fg`: Glyph color of a danger feature icon tile. - `--ki-feature-icon-fg`: Glyph color of a neutral feature icon tile. - `--ki-feature-icon-info-bg`: Background color of an info feature icon tile. - `--ki-feature-icon-info-fg`: Glyph color of an info feature icon tile. - `--ki-feature-icon-lg-radius`: Corner radius of a large square feature icon tile. - `--ki-feature-icon-lg-size`: Edge length of a large feature icon tile. - `--ki-feature-icon-primary-bg`: Background color of a primary feature icon tile. - `--ki-feature-icon-primary-fg`: Glyph color of a primary feature icon tile. - `--ki-feature-icon-primary-light-bg`: Background color of a primary-light feature icon tile. - `--ki-feature-icon-primary-light-fg`: Glyph color of a primary-light feature icon tile. - `--ki-feature-icon-radius`: Default corner radius of a square feature icon tile. - `--ki-feature-icon-size`: Default edge length of a feature icon tile. - `--ki-feature-icon-sm-radius`: Corner radius of a small square feature icon tile. - `--ki-feature-icon-sm-size`: Edge length of a small feature icon tile. - `--ki-feature-icon-success-bg`: Background color of a success feature icon tile. - `--ki-feature-icon-success-fg`: Glyph color of a success feature icon tile. - `--ki-feature-icon-warning-bg`: Background color of a warning feature icon tile. - `--ki-feature-icon-warning-fg`: Glyph color of a warning feature icon tile. - `--ki-feature-icon-xl-radius`: Corner radius of an extra-large square feature icon tile. - `--ki-feature-icon-xl-size`: Edge length of an extra-large feature icon tile. - `--ki-feature-icon-xs-radius`: Corner radius of an extra-small square feature icon tile. - `--ki-feature-icon-xs-size`: Edge length of an extra-small feature icon tile. - `--ki-typography-family-body`: semantic font family for typography family body. ### ki-file-upload A form-associated picker and drop zone with local selection validation and a list of file upload outcomes. When to use: collect local attachments, media or imports, and optionally show application-managed upload progress and results. When NOT to use: transfer files without an application handler, collect a URL, or use client-side type and size checks as upload authorization. Examples: # File upload examples ## Submit attachments with a form ```html
Choose up to three CSV or PDF files, up to 10 MB each.
``` Register the element once with the direct package entry point. ```js import { defineCustomElement } from '@kimen/elements/ki-file-upload'; defineCustomElement(); ``` The form submits each accepted original `File` under `attachments`. A reset clears the list. Use `error-text` for a form error, such as one returned by your application, and clear it when the error is resolved. ## Report progress from an application-managed transfer Use a standalone picker when your application sends files as soon as people choose them. ```html ``` Here `sendFile` is your application's transfer function. It accepts a `File`, an abort signal and a progress callback receiving a percentage. ```js const upload = document.querySelector('#transfer-picker'); const transfers = new Map(); function update(file, changes) { upload.files = upload.files.map((entry) => entry.file === file ? { ...entry, ...changes } : entry, ); } async function startUpload(file) { const controller = new AbortController(); transfers.set(file, controller); update(file, { status: 'uploading', progress: 0 }); try { await sendFile(file, { signal: controller.signal, onProgress: (progress) => update(file, { progress }), }); update(file, { status: 'done' }); } catch { const error = controller.signal.aborted ? 'Upload canceled.' : 'Upload failed.'; update(file, { status: 'error', error }); } finally { transfers.delete(file); } } upload.addEventListener('ki-files-add', ({ detail }) => { for (const { file } of detail.files) { void startUpload(file); } }); upload.addEventListener('ki-file-cancel', ({ detail }) => { transfers.get(detail.file.file)?.abort(); }); ``` Use `ki-file-remove` to update application state when a row is removed. For previously uploaded attachments, set `files` to rows with metadata and `status: 'done'`. Only rows carrying an original `File` contribute form entries. Attributes: - `accept` (string | undefined): Comma-separated extensions, MIME types and MIME wildcards allowed in new selections. - `browse-label` (string, default 'Browse files'): Visible text of the native file picker button. - `cancel-label` (string, default 'Cancel upload of {file}'): Accessible name template for cancellation. Use {file} for the displayed filename. - `count-error` (string, default 'Too many files.'): Rejection text for a file beyond selection capacity. - `disabled` (boolean, default false): Disables the picker and file actions and excludes the field from submission. - `done-label` (string, default 'Uploaded'): Status text for a completed upload. - `drop-label` (string, default 'Drop files here or'): Drop instruction shown just before the Browse button. - `error-text` (string | undefined): Application validation error. Clear it to allow form submission again. - `failed-label` (string, default 'Upload failed.'): Fallback status text for a failed upload without a supplied error. - `help-text` (string | undefined): Guidance for file formats, limits or the purpose of this field. - `label` (string, default 'Upload files'): Visible label and accessible name of the upload group. - `list-label` (string, default 'Files'): Accessible name of the list of files. - `max-files` (number | undefined): Maximum accepted local files as a nonnegative integer. Single-file mode also caps this at one. - `max-size` (string | undefined): Maximum size per selected file in bytes or decimal B, KB, MB or GB, such as "10MB". - `multiple` (boolean, default false): Allows a selection of more than one file. - `name` (string | undefined): Form-data key repeated for each accepted original file. - `queued-label` (string, default 'Queued'): Status text for an accepted file waiting to upload. - `remove-label` (string, default 'Remove {file}'): Accessible name template for removal. Use {file} for the displayed filename. - `required` (boolean, default false): Requires at least one original accepted file to submit the form. - `required-label` (string, default 'Required'): Visible annotation for a required file field. - `required-message` (string, default 'Select a file.'): Validation message when the form requires a file and none is selected. - `size-error` (string, default 'This file is too large.'): Rejection text for a file larger than max-size. - `type-error` (string, default 'This file type is not allowed.'): Rejection text for a file that does not match accept. - `uploading-label` (string, default 'Uploading {file}'): Progress indicator name template. Use {file} for the displayed filename. Slots: - `help`: Plain-language guidance for the picker, in place of help-text. Parts: - `action`: Native button for removal or cancellation. - `browse`: Native button that opens the file picker. - `drop-zone`: Surface that receives files dragged from the operating system. - `error`: Field-level form validation error. - `file-meta`: Size, outcome or error text for the file. - `file-name`: Name displayed for the file. - `help`: Guidance associated with the field. - `input`: Hidden native file picker. - `label`: Field label and optional required annotation. - `list`: List of selected files and rejections. - `progress`: Progress indicator for an uploading file. - `row`: A file row, with data-status matching its lifecycle state. Events: - `ki-file-cancel` (CustomEvent): Requests that the application cancel the identified upload. - `ki-file-remove` (CustomEvent): Reports a row removed by the user, after updating the file list. - `ki-files-add` (CustomEvent): Reports the accepted rows in one picker or drop batch, each with its original File. Methods: none CSS custom properties: - `--ki-corner-inline`: Small radius for an outline around inline content. - `--ki-density-space-scale`: Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-file-upload-active-bg`: Drop zone background while files are dragged over it. - `--ki-file-upload-active-border`: Drop zone boundary while files are dragged over it. - `--ki-file-upload-active-fg`: Main drop zone text while files are dragged over it. - `--ki-file-upload-backdrop-filter`: Complete backdrop filter applied behind the drop zone. - `--ki-file-upload-bg`: Drop zone background at rest. - `--ki-file-upload-bg-image`: Optional image over the drop zone background. - `--ki-file-upload-border`: Dashed boundary of the drop zone. - `--ki-file-upload-border-width`: Outline stroke width for the drop zone and file rows. - `--ki-file-upload-error-bg`: Background of a file row with an error. - `--ki-file-upload-error-border`: Boundary of a file row with an error. - `--ki-file-upload-error-fg`: Text of a file error or field error. - `--ki-file-upload-fg`: Main drop zone text at rest. - `--ki-file-upload-radius`: Drop zone corner radius. - `--ki-file-upload-row-backdrop-filter`: Complete backdrop filter applied behind a file row. - `--ki-file-upload-row-bg`: Background of a file row and the field label. - `--ki-file-upload-row-bg-image`: Optional image over the file row background. - `--ki-file-upload-row-border`: Boundary of a file row without an error. - `--ki-file-upload-row-fg`: File names, row action icons and the field label. - `--ki-file-upload-row-radius`: File row corner radius. - `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. - `--ki-focus-ring-offset`: Gap between a focusable component and its keyboard focus ring. - `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. - `--ki-layout-spacing-3xl`: The 3xl spacing step for a stack or grid gap. - `--ki-layout-spacing-md`: The md spacing step for a stack or grid gap. - `--ki-layout-spacing-xs`: The xs spacing step for a stack or grid gap. - `--ki-text-primary-high-em`: semantic color for text primary high em. - `--ki-text-supporting`: Supporting text of an enabled control: field labels, placeholders, list secondary lines, quiet button labels and unselected tabs. A role, distinct from the med-em emphasis step it resolves to, so a mode can strengthen enabled supporting text without touching the disabled ink that also draws from med-em (directly, or through text.muted). - `--ki-typography-family-body`: semantic font family for typography family body. - `--ki-typography-line-height-body-1`: semantic dimension for typography line height body 1. - `--ki-typography-line-height-caption-2`: semantic dimension for typography line height caption 2. - `--ki-typography-size-caption-2`: semantic dimension for typography size caption 2. - `--ki-typography-underline-offset`: Gap between text and its underline. - `--ki-typography-underline-thickness`: Stroke width of a resting text underline. - `--ki-typography-underline-thickness-hover`: Stroke width of an emphasized underline on hover. - `--ki-typography-visually-hidden-size`: Nonzero edge for clipped text available to assistive technology. - `--ki-typography-weight-body-medium`: semantic font weight for typography weight body medium. - `--ki-typography-weight-body-normal`: semantic font weight for typography weight body normal. ### ki-format-date Displays an ISO date or timestamp in the reader's language. When to use: For raw date and timestamp values in tables, records and prose. When NOT to use: For an editable date or an elapsed time that should change as the clock advances. Examples: # Format a date Use a calendar date when the day is the value, and send an offset or `Z` when the value is a timestamp. Set `lang` on the surrounding document or section. ```html
``` Attributes: - `date` (string | undefined): ISO calendar date (YYYY-MM-DD) or ISO date-time. A timestamp without an offset uses local time. - `date-style` ("full" | "long" | "medium" | "short" | undefined): Date detail. Defaults to medium when neither date style nor time style is supplied. - `lang` (string | undefined): Language tag for the formatted date. Inherits the nearest HTML lang declaration when omitted. - `time-style` ("full" | "long" | "medium" | "short" | undefined): Time detail. Omit to show the date alone. - `time-zone` (string | undefined): IANA time zone for a timestamp. A calendar date keeps its day in every zone. Slots: none Parts: none Events: none Methods: none CSS custom properties: - `--ki-format-date-font-family`: Default body font family for ki-format-date on a bare page. ### ki-format-number Displays a raw number using local number conventions and tabular figures. When to use: For numeric data, currency amounts, ratios and measurements in content. When NOT to use: For numeric input or values that already include localized formatting. Examples: # Format a number Pass raw numbers and let the nearest `lang` declaration select the separators, spacing and symbols. A percent takes a ratio. ```html
``` Attributes: - `currency` (string | undefined): ISO 4217 currency code, such as EUR. Selects currency output when format-style is omitted. - `format-style` ("decimal" | "percent" | "unit" | undefined): Decimal, percent or unit output. Without this option, currency selects currency output and other values use decimal. - `maximum-fraction-digits` (number | undefined, minimum 0): Maximum number of fraction digits. - `minimum-fraction-digits` (number | undefined, minimum 0): Minimum number of fraction digits. - `notation` ("compact" | undefined): Use compact notation for abbreviated large numbers. Omit for standard notation. - `unit` (string | undefined): Intl unit identifier, such as celsius or kilometer. Use with format-style="unit". - `value` (number | undefined): Raw finite number. A percent uses a ratio, so 0.49 displays as 49%. Slots: none Parts: none Events: none Methods: none CSS custom properties: - `--ki-format-number-font-family`: Default body font family for ki-format-number on a bare page. ### ki-grid A passive responsive grid for content items. When to use: lay out items on responsive tracks with consistent token spacing. When NOT to use: for page shells, painted grouping (use ki-card), or a data grid. Examples: # Grid examples An automatic grid fills its available space with tracks at least as wide as `min-column` where room allows. Here the summary takes two tracks when possible. ```html Overview Orders Inventory Customers ``` For a fixed count, set `columns`. The grid switches to one column when its own available inline size drops below 30rem. ```html Orders Inventory Customers ``` Attributes: - `columns` (number | undefined, minimum 1): Positive whole track count. Below 30rem of available inline size the fixed grid uses one column. Omit columns for automatic tracks. - `gap` ("10xl" | "11xl" | "12xl" | "13xl" | "14xl" | "15xl" | "16xl" | "17xl" | "18xl" | "19xl" | "20xl" | "21xl" | "22xl" | "23xl" | "24xl" | "25xl" | "26xl" | "2xl" | "3xl" | "4xl" | "5xl" | "6xl" | "7xl" | "8xl" | "9xl" | "lg" | "md" | "sm" | "xl" | "xs" | "xxs" | "zero", default 'xl'): Kimen spacing step, xl by default. Unsupported values keep the default gap. - `min-column` (string, default '15rem'): Minimum automatic track size as a CSS length. Defaults to 15rem and is ignored with fixed columns. Slots: - (default): The content in reading order. A direct child with data-span="2" spans two tracks when they fit. Parts: - `grid`: The grid layout containing the slotted content. Events: none Methods: none CSS custom properties: - `--ki-grid-gap`: Default gap between grid tracks. - `--ki-grid-min`: Default minimum size of an automatic grid track. - `--ki-layout-grid-fixed-breakpoint`: Minimum available inline size for a fixed grid to use multiple tracks. - `--ki-layout-grid-min`: Default minimum inline size of an automatic grid track. - `--ki-layout-spacing-xl`: The xl spacing step for a stack or grid gap. - `--ki-typography-family-body`: semantic font family for typography family body. ### ki-icon A static Lucide glyph selected by name from the application's per-icon imports. When to use: show a named glyph next to text, or give a standalone meaningful glyph an accessible label. Import `@kimen/elements/icons/` before mounting the component or rendering a guarded surface. When NOT to use: make an icon interactive, accept arbitrary SVG or URLs, or replace the accessible name of a control. Use the control's own label. Examples: # ki-icon examples Import the exact Lucide names used by your markup before you mount it. ```js import '@kimen/elements/icons/circle-check'; import '@kimen/elements/icons/triangle-alert'; import { defineCustomElement } from '@kimen/elements/ki-icon'; defineCustomElement(); ``` A confirmation has adjacent text, so the glyph is decorative. ```html Confirmed ``` A standalone meaningful glyph takes its accessible name from the label. ```html ``` For a guarded catalog surface, import the glyph in the host and reference it by name. The icon has no slots or actions. ```json { "version": 1, "root": { "component": "ki-icon", "props": { "name": "triangle-alert", "size": "lg", "label": "Warning" } } } ``` Attributes: - `label` (string | undefined): Accessible name for a meaningful glyph. Omit it when nearby text already conveys the meaning. - `name` (string, required): Lucide name made available by a per-icon import. An unavailable name draws no glyph. - `size` ("inherit" | "lg" | "md" | "sm", default 'inherit'): Glyph size. Inherit follows the surrounding text at 1em. Slots: none Parts: none Events: none Methods: none CSS custom properties: - `--ki-icon-size-lg`: Large ki-icon with the surrounding text ink. - `--ki-icon-size-md`: Medium ki-icon with the surrounding text ink. - `--ki-icon-size-sm`: Small ki-icon with the surrounding text ink. - `--ki-icon-stroke-width`: Lucide stroke width in viewBox units, scaled with the glyph. - `--ki-typography-family-body`: semantic font family for typography family body. ### ki-icon-button A token-styled, icon-only action button with native button semantics and a mandatory accessible name. When to use: a compact, widely understood action where space precludes a visible label: toolbars, card and dialog corners (close), media transport, data-row actions. Always supply `label`; usually pair with ki-tooltip for sighted discoverability. Enable `toggle` for persistent actions such as Bookmark. While the action it started is in progress, set `loading`. When NOT to use: whenever a visible label fits (use ki-button), navigation (use a link), or form submit/reset (ki-icon-button is not form-associated; use ki-button, whose visible label communicates the consequence). Examples: The default slot holds exactly one decorative icon; the mandatory `label` is the accessible name — the slot never contributes to it: ```html ``` Visual hierarchy comes from `variant` (default `secondary`). In the original momentary variants, `tone` (default `neutral`) carries semantic intent such as success or danger. ```html ``` Add `toggle` for an action such as Bookmark that stays pressed until the next activation. `variant="outline"` uses an outline at rest and a fill when selected. Give the pressed version a decorative icon in the `selected` slot. ```html ``` With an empty `selected` slot, the default inline SVG takes a `currentColor` fill while pressed. Let its paths inherit `fill`. Keep `label` the same in both states. Activating the control emits `ki-change` with `{ selected }`. Set the `selected` attribute for the initial state or write the property to update it silently. Sizes run `xs` (24px, exactly the WCAG 2.2 pointer-target floor) through `xl`, default `md`; each pairs a square box with its own icon size: ```html ``` Pair with `ki-tooltip` for sighted discoverability: the tooltip's `label` becomes the accessible description while the icon button's `label` stays the accessible name: ```html ``` An icon button in the dialog footer can dismiss it by ID. The dialog must be in the same document or shadow root as the icon button. ```html ``` While the action it started is in progress, set `loading` instead of `disabled`: the icon button keeps its size, its focus and its `label`, ignores further activation, draws a spinner in place of the icon and announces `loading-label` (default "Loading") as a polite status message: ```html ``` Attributes: - `command` ("close" | "request-close" | "show-modal" | undefined): Dialog action to run for `commandfor`. Use `show-modal` to open, `close` for direct dismissal, or `request-close` for guarded dismissal. Choose a command for local dialog control and omit it for other actions. - `commandfor` (string | undefined): ID of a ki-dialog in the same document or shadow tree as this button. Set it together with `command` to connect a dialog declaratively. - `disabled` (boolean, default false): Prevents activation, removes the icon button from keyboard reach, and exposes the unavailable state through the internal native button. Wins over `loading` when both are set. When NOT to use: do not use disabled for pending/loading semantics; use `loading`. - `expanded` (boolean | undefined): Application-owned disclosure state for a trigger that opens a popup. The native icon button exposes this as `aria-expanded`. Use with `aria-haspopup="menu"` for a menu trigger. Omit for other actions. - `label` (string, required): Accessible name of the internal focusable button ("Close", "Play"). Required in the catalog. When slotted as a trailing list control, the row text supplies a fallback through the host aria-label. Use ki-button when the action has a visible label. - `loading` (boolean, default false): Pending state of the action this icon button started (refreshing, sending). While set, every activation is blocked (pointer, Enter and Space), but the icon button stays focusable, in the Tab order and at its size: the icon stays laid out, transparent, and a spinner is drawn in its place. The internal native button is exposed with `aria-disabled="true"` and keeps its `label`, and `loadingLabel` is announced as a polite status message. `disabled` wins over it. The application sets it when the action starts and clears it when the action ends. When to use: while the work a click on this icon button started is running, so a second activation cannot repeat it. When NOT to use: for an icon button the person cannot use yet (use `disabled`), or for the progress of a page or region (use ki-progress). - `loading-label` (string, default 'Loading'): Text of the polite status message announced while `loading` is set. Override for localization; the default English string is the icon button's only built-in user-visible text. When to use: provide a localized message whenever the document language is not English, or a more specific one ("Refreshing"). When NOT to use: do not repeat `label` here; the person already hears it on focus. - `pressed` (boolean | undefined): Application-owned toggle state. The native icon button exposes this as `aria-pressed` when `toggle` is off. Omit for a momentary action. - `selected` (boolean, default false): Current press state in toggle mode. Set this to initialize or synchronize the state programmatically without emitting a change. - `size` ("lg" | "md" | "sm" | "xl" | "xs", default 'md'): Token-backed square size. Every size keeps at least the 24×24 minimum pointer target (`xs` sits exactly on it); choose the size that matches the density of the surrounding UI. When NOT to use: do not shrink below `xs` through tokens; no theme may go under the WCAG 2.2 pointer-target floor. - `toggle` (boolean, default false): Enables persistent press state for an action such as Bookmark. The native button exposes `aria-pressed` and each activation switches `selected`. Keep the same accessible label in both states. - `tone` ("danger" | "neutral" | "success", default 'neutral'): Semantic intent for the action, independent of hierarchy. Use `success` for confirming actions and `danger` for destructive actions. Toggle palettes are specific to the variant. When NOT to use: do not use tone for visual hierarchy; use `variant`. - `variant` ("ghost" | "outline" | "primary" | "quaternary" | "secondary" | "tertiary", default 'secondary'): Visual hierarchy for the action. Use filled `primary` for the single main action, outlined `secondary` for supporting actions, `quaternary` for neutral icon actions, `ghost` for accent icon actions and `outline` for an unfilled action with a visible boundary. When NOT to use: do not use variant to signal success or danger; use `tone` for intent. Slots: - (default): Exactly one decorative icon. The slot is presentational: its content is hidden from assistive technology and never contributes to the accessible name. Supply `label` or use a named trailing list control. - `counter`: Decorative ki-counter in the block-start inline-end corner. Include its meaning in the button label. - `selected`: Optional decorative icon shown when the toggle is selected. If omitted, the default icon stays visible and an inline SVG takes a current-colour fill. Parts: - `button`: Internal native button. - `icon`: Icon wrapper around the default slot. - `spinner`: Loading spinner drawn in place of the icon, in the button's foreground ink, rendered only while `loading` is in effect. Events: - `ki-change` (CustomEvent<{ selected: boolean }>): Emitted after toggle activation with the new selected state. Methods: none CSS custom properties: - `--ki-button-backdrop-filter`: Complete backdrop filter for glass button and icon-button variants. - `--ki-button-border-width`: dimension used by the button component for border width (MarsUI bevel/outline stroke: 1px). - `--ki-button-focus-ring-color`: color used by the button component for focus ring color. - `--ki-button-focus-ring-offset`: dimension used by the button component for focus ring offset. - `--ki-button-focus-ring-shadow`: shadow used by the button component for the focus ring glow (MarsUI Focus/primary: 3px spread ring). - `--ki-button-focus-ring-width`: dimension used by the button component for focus ring width. - `--ki-button-ghost-danger-hover-bg`: color used by the button component for ghost danger hover background. - `--ki-button-ghost-danger-hover-border`: color used by the button component for ghost danger hover border. - `--ki-button-ghost-danger-hover-fg`: color used by the button component for ghost danger hover foreground. - `--ki-button-ghost-danger-rest-bg`: color used by the button component for ghost danger rest background. - `--ki-button-ghost-danger-rest-border`: color used by the button component for ghost danger rest border. - `--ki-button-ghost-danger-rest-fg`: color used by the button component for ghost danger rest foreground. - `--ki-button-ghost-disabled-shadow`: value used by the button component for ghost disabled shadow. - `--ki-button-ghost-hover-shadow`: value used by the button component for ghost hover shadow. - `--ki-button-ghost-neutral-disabled-bg`: color used by the button component for ghost neutral disabled background. - `--ki-button-ghost-neutral-disabled-border`: color used by the button component for ghost neutral disabled border. - `--ki-button-ghost-neutral-disabled-fg`: color used by the button component for ghost neutral disabled foreground. - `--ki-button-ghost-neutral-hover-bg`: color used by the button component for ghost neutral hover background. - `--ki-button-ghost-neutral-hover-border`: color used by the button component for ghost neutral hover border. - `--ki-button-ghost-neutral-hover-fg`: color used by the button component for ghost neutral hover foreground. - `--ki-button-ghost-neutral-rest-bg`: color used by the button component for ghost neutral rest background. - `--ki-button-ghost-neutral-rest-border`: color used by the button component for ghost neutral rest border. - `--ki-button-ghost-neutral-rest-fg`: color used by the button component for ghost neutral rest foreground. - `--ki-button-ghost-rest-shadow`: value used by the button component for ghost rest shadow. - `--ki-button-ghost-success-hover-bg`: color used by the button component for ghost success hover background. - `--ki-button-ghost-success-hover-border`: color used by the button component for ghost success hover border. - `--ki-button-ghost-success-hover-fg`: color used by the button component for ghost success hover foreground. - `--ki-button-ghost-success-rest-bg`: color used by the button component for ghost success rest background. - `--ki-button-ghost-success-rest-border`: color used by the button component for ghost success rest border. - `--ki-button-ghost-success-rest-fg`: color used by the button component for ghost success rest foreground. - `--ki-button-lg-radius`: dimension used by the button component for lg radius (Button master 8003:300 binds Radius/small-component/lg, the scale a radius mode reassigns). - `--ki-button-md-radius`: dimension used by the button component for md radius (Button master 8003:300 binds Radius/small-component/md, the scale a radius mode reassigns). - `--ki-button-primary-active-overlay`: Pressed state layer for the primary button: primary paints on a dark brand fill, so its wash lightens: the next rung above ki.surface.hover-overlay (White/5 -> White/8 light). Replaces this variant's share of a 45-cell active bg/fg/border matrix whose values were documented mirrors of rest and which WITHDREW the hover overlay rather than deepening it, an appearance legible only to a pointer user who had hovered first. - `--ki-button-primary-danger-hover-bg`: color used by the button component for primary danger hover background (MarsUI: rest fill; hover lightening comes from the hover overlay). - `--ki-button-primary-danger-hover-border`: color used by the button component for primary danger hover border (MarsUI bevel top/inline edge). - `--ki-button-primary-danger-hover-fg`: color used by the button component for primary danger hover foreground. - `--ki-button-primary-danger-rest-bg`: color used by the button component for primary danger rest background. Deliberate deviation: Figma specifies the 500 ramp (Surface/danger_med_em #f05149) but white on 500 is ≈3.5:1 < AA 4.5:1; Kimen keeps the 700 ramp (precedent 010 D2, pending founder ratification). - `--ki-button-primary-danger-rest-border`: color used by the button component for primary danger rest border (MarsUI bevel top/inline edge). - `--ki-button-primary-danger-rest-fg`: color used by the button component for primary danger rest foreground. - `--ki-button-primary-disabled-shadow`: value used by the button component for primary disabled shadow. - `--ki-button-primary-hover-overlay`: color used by the button component for the primary hover overlay layer (MarsUI hover_overlay, White/5). - `--ki-button-primary-hover-shadow`: shadow used by the button component for button primary hover shadow (MarsUI Component_effect/primary_hover). - `--ki-button-primary-neutral-disabled-bg`: color used by the button component for primary neutral disabled background. Deliberate deviation: Figma disabled is Surface/disabled_base_em gray.100 with gray.400 text (≈1.4:1); Kimen keeps gray.200 for contrast (precedent 010 D2, pending founder ratification). - `--ki-button-primary-neutral-disabled-border`: color used by the button component for primary neutral disabled border. - `--ki-button-primary-neutral-disabled-fg`: color used by the button component for primary neutral disabled foreground. Deliberate deviation: Figma disabled text is text/base_em gray.400 (≈1.4:1 on gray.100); Kimen keeps text.muted gray.700 for readable disabled text (precedent 010 D2, pending founder ratification). - `--ki-button-primary-neutral-hover-bg`: color used by the button component for primary neutral hover background (MarsUI: rest fill; hover lightening comes from the hover overlay). - `--ki-button-primary-neutral-hover-border`: color used by the button component for primary neutral hover border (MarsUI bevel top/inline edge). - `--ki-button-primary-neutral-hover-fg`: color used by the button component for primary neutral hover foreground. - `--ki-button-primary-neutral-rest-bg`: color used by the button component for primary neutral rest background (MarsUI Surface/primary_med_em, brand 500). - `--ki-button-primary-neutral-rest-border`: color used by the button component for primary neutral rest border (MarsUI bevel top/inline edge). - `--ki-button-primary-neutral-rest-fg`: color used by the button component for primary neutral rest foreground. - `--ki-button-primary-rest-border-bottom`: color used by the button component for the primary bevel bottom edge (MarsUI Outline/primary_button_bottom). - `--ki-button-primary-rest-shadow`: shadow used by the button component for button primary rest shadow (MarsUI Component_effect/primary_default). - `--ki-button-primary-success-hover-bg`: color used by the button component for primary success hover background (MarsUI: rest fill; hover lightening comes from the hover overlay). - `--ki-button-primary-success-hover-border`: color used by the button component for primary success hover border (MarsUI bevel top/inline edge). - `--ki-button-primary-success-hover-fg`: color used by the button component for primary success hover foreground. - `--ki-button-primary-success-rest-bg`: color used by the button component for primary success rest background. Deliberate deviation: Figma specifies the 500 ramp (Surface/success_med_em #409b3f) but white on 500 is ≈3.5:1 < AA 4.5:1; Kimen keeps the 700 ramp (precedent 010 D2, pending founder ratification). - `--ki-button-primary-success-rest-border`: color used by the button component for primary success rest border (MarsUI bevel top/inline edge). - `--ki-button-primary-success-rest-fg`: color used by the button component for primary success rest foreground. - `--ki-button-quaternary-danger-hover-bg`: color used by the button component for quaternary danger hover background. - `--ki-button-quaternary-danger-hover-border`: color used by the button component for quaternary danger hover border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-danger-hover-fg`: color used by the button component for quaternary danger hover foreground. - `--ki-button-quaternary-danger-rest-bg`: color used by the button component for quaternary danger rest background. - `--ki-button-quaternary-danger-rest-border`: color used by the button component for quaternary danger rest border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-danger-rest-fg`: color used by the button component for quaternary danger rest foreground. - `--ki-button-quaternary-disabled-shadow`: value used by the button component for quaternary disabled shadow. - `--ki-button-quaternary-hover-shadow`: value used by the button component for quaternary hover shadow. - `--ki-button-quaternary-neutral-disabled-bg`: color used by the button component for quaternary neutral disabled background. - `--ki-button-quaternary-neutral-disabled-border`: color used by the button component for quaternary neutral disabled border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-neutral-disabled-fg`: color used by the button component for quaternary neutral disabled foreground: the disabled ink of every field and selection control (Text/base_em). quaternary has no fill or border, so its ink alone shows the state; ki.text.muted equals its resting ki.text.med-em in onmars. - `--ki-button-quaternary-neutral-hover-bg`: color used by the button component for quaternary neutral hover background (MarsUI hover mechanism: hover_overlay_inverse Black/3 wash over the transparent rest fill). - `--ki-button-quaternary-neutral-hover-border`: color used by the button component for quaternary neutral hover border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-neutral-hover-fg`: color used by the button component for quaternary neutral hover foreground (MarsUI quaternary label text/med_em gray; the outlined-purple rest identity was a pre-master synthesis). - `--ki-button-quaternary-neutral-rest-bg`: color used by the button component for quaternary neutral rest background. - `--ki-button-quaternary-neutral-rest-border`: color used by the button component for quaternary neutral rest border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-neutral-rest-fg`: color used by the button component for quaternary neutral rest foreground (MarsUI quaternary label text/med_em gray; the outlined-purple rest identity was a pre-master synthesis). - `--ki-button-quaternary-rest-shadow`: value used by the button component for quaternary rest shadow. - `--ki-button-quaternary-success-hover-bg`: color used by the button component for quaternary success hover background. - `--ki-button-quaternary-success-hover-border`: color used by the button component for quaternary success hover border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-success-hover-fg`: color used by the button component for quaternary success hover foreground. - `--ki-button-quaternary-success-rest-bg`: color used by the button component for quaternary success rest background. - `--ki-button-quaternary-success-rest-border`: color used by the button component for quaternary success rest border (MarsUI quaternary is borderless in every state). - `--ki-button-quaternary-success-rest-fg`: color used by the button component for quaternary success rest foreground. - `--ki-button-secondary-active-overlay`: Pressed state layer for the secondary button: secondary paints on a light fill, so its wash darkens: the next rung above ki.surface.hover-overlay-inverse (Black/3 -> Black/5 light). Replaces this variant's share of a 45-cell active bg/fg/border matrix whose values were documented mirrors of rest and which WITHDREW the hover overlay rather than deepening it, an appearance legible only to a pointer user who had hovered first. - `--ki-button-secondary-danger-hover-bg`: color used by the button component for secondary danger hover background. - `--ki-button-secondary-danger-hover-border`: color used by the button component for secondary danger hover border (MarsUI bevel top/inline edge, variant trait). - `--ki-button-secondary-danger-hover-fg`: color used by the button component for secondary danger hover foreground. - `--ki-button-secondary-danger-rest-bg`: color used by the button component for secondary danger rest background. - `--ki-button-secondary-danger-rest-border`: color used by the button component for secondary danger rest border (MarsUI bevel top/inline edge, variant trait). - `--ki-button-secondary-danger-rest-fg`: color used by the button component for secondary danger rest foreground. - `--ki-button-secondary-disabled-shadow`: value used by the button component for secondary disabled shadow. - `--ki-button-secondary-hover-overlay`: color used by the button component for the secondary hover overlay layer (MarsUI hover_overlay_inverse, Black/3). - `--ki-button-secondary-hover-shadow`: shadow used by the button component for secondary hover shadow (MarsUI Component_effect/secondary_hover). - `--ki-button-secondary-neutral-disabled-bg`: color used by the button component for secondary neutral disabled background. - `--ki-button-secondary-neutral-disabled-border`: color used by the button component for secondary neutral disabled border. - `--ki-button-secondary-neutral-disabled-fg`: color used by the button component for secondary neutral disabled foreground. - `--ki-button-secondary-neutral-hover-bg`: color used by the button component for secondary neutral hover background (MarsUI: rest fill; hover darkening comes from the hover overlay). - `--ki-button-secondary-neutral-hover-border`: color used by the button component for secondary neutral hover border (MarsUI bevel top/inline edge). - `--ki-button-secondary-neutral-hover-fg`: color used by the button component for secondary neutral hover foreground (MarsUI text/high_em). - `--ki-button-secondary-neutral-rest-bg`: color used by the button component for secondary neutral rest background (MarsUI Surface/special/secondary_alpha_base: gray glass, not a brand tint). - `--ki-button-secondary-neutral-rest-border`: color used by the button component for secondary neutral rest border (MarsUI bevel top/inline edge). - `--ki-button-secondary-neutral-rest-fg`: color used by the button component for secondary neutral rest foreground (MarsUI text/high_em). - `--ki-button-secondary-rest-border-bottom`: color used by the button component for the secondary bevel bottom edge (MarsUI Outline/secondary_button_bottom). - `--ki-button-secondary-rest-shadow`: shadow used by the button component for secondary rest shadow (MarsUI Component_effect/secondary_default). - `--ki-button-secondary-success-hover-bg`: color used by the button component for secondary success hover background. - `--ki-button-secondary-success-hover-border`: color used by the button component for secondary success hover border (MarsUI bevel top/inline edge, variant trait). - `--ki-button-secondary-success-hover-fg`: color used by the button component for secondary success hover foreground. - `--ki-button-secondary-success-rest-bg`: color used by the button component for secondary success rest background. - `--ki-button-secondary-success-rest-border`: color used by the button component for secondary success rest border (MarsUI bevel top/inline edge, variant trait). - `--ki-button-secondary-success-rest-fg`: color used by the button component for secondary success rest foreground. - `--ki-button-sm-radius`: dimension used by the button component for sm radius (Button master 8003:300 binds Radius/small-component/sm, the scale a radius mode reassigns). - `--ki-button-spinner-duration`: duration used by the button and icon button components for one turn of the loading spinner (spec 046 D5: the ki-progress indeterminate period). Applied only under prefers-reduced-motion: no-preference. - `--ki-button-spinner-stroke-width`: dimension used by the button and icon button components for the loading spinner stroke (spec 046 D5: the circular ki-progress ring, drawn with a non-scaling stroke of this width). - `--ki-button-tertiary-danger-hover-bg`: Tertiary alias of the secondary danger hover background. - `--ki-button-tertiary-danger-hover-border`: color used by the button component for tertiary danger hover border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-danger-hover-fg`: color used by the button component for tertiary danger hover foreground. - `--ki-button-tertiary-danger-rest-bg`: Tertiary alias of the secondary danger rest background. - `--ki-button-tertiary-danger-rest-border`: color used by the button component for tertiary danger rest border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-danger-rest-fg`: color used by the button component for tertiary danger rest foreground. - `--ki-button-tertiary-disabled-shadow`: value used by the button component for tertiary disabled shadow. - `--ki-button-tertiary-hover-overlay`: Hover overlay for neutral tertiary buttons, shared with secondary by default. - `--ki-button-tertiary-hover-shadow`: shadow used by the button component for tertiary hover shadow (MarsUI Component_effect/secondary_hover). - `--ki-button-tertiary-neutral-disabled-bg`: color used by the button component for tertiary neutral disabled background. - `--ki-button-tertiary-neutral-disabled-border`: color used by the button component for tertiary neutral disabled border. - `--ki-button-tertiary-neutral-disabled-fg`: color used by the button component for tertiary neutral disabled foreground. - `--ki-button-tertiary-neutral-hover-bg`: Tertiary alias of the secondary neutral hover background. - `--ki-button-tertiary-neutral-hover-border`: color used by the button component for tertiary neutral hover border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-neutral-hover-fg`: Tertiary alias of the secondary neutral hover foreground. - `--ki-button-tertiary-neutral-rest-bg`: Tertiary alias of the secondary neutral rest background. - `--ki-button-tertiary-neutral-rest-border`: color used by the button component for tertiary neutral rest border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-neutral-rest-fg`: Tertiary alias of the secondary neutral rest foreground. - `--ki-button-tertiary-rest-border-bottom`: color used by the button component for the tertiary bevel bottom edge (MarsUI Outline/secondary_button_bottom — same bevel pair as secondary). - `--ki-button-tertiary-rest-shadow`: shadow used by the button component for tertiary rest shadow (MarsUI Component_effect/secondary_default — replaces the migrated M2-era stack, which the material3 theme keeps via its own override). - `--ki-button-tertiary-success-hover-bg`: Tertiary alias of the secondary success hover background. - `--ki-button-tertiary-success-hover-border`: color used by the button component for tertiary success hover border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-success-hover-fg`: color used by the button component for tertiary success hover foreground. - `--ki-button-tertiary-success-rest-bg`: Tertiary alias of the secondary success rest background. - `--ki-button-tertiary-success-rest-border`: color used by the button component for tertiary success rest border (MarsUI secondary bevel top/inline edge — tertiary carries the secondary_button outline pair). - `--ki-button-tertiary-success-rest-fg`: color used by the button component for tertiary success rest foreground. - `--ki-button-toggle-quiet-bg`: Background of unselected ghost and quaternary toggle buttons. - `--ki-button-toggle-quiet-fg`: Foreground of unselected ghost toggle buttons. - `--ki-button-toggle-unselected-bg`: Background of unselected filled toggle buttons. - `--ki-button-toggle-unselected-fg`: Foreground of unselected filled toggle buttons. - `--ki-button-xl-radius`: dimension used by the button component for xl radius (Button master 8003:300 binds Radius/small-component/xl, the scale a radius mode reassigns). - `--ki-button-xs-radius`: dimension used by the button component for xs radius (Button master 8003:300 binds Radius/small-component/xs, the scale a radius mode reassigns). - `--ki-counter-ring-width`: Thickness of the separating ring. - `--ki-density-control-offset`: Added to the block size of every scaled control and row (button, icon button, field, select, textarea, option, list item, tab). Components floor the result at ki.size.target-min. - `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). - `--ki-effect-component-no-backdrop-filter`: An unadorned surface applies no backdrop filter. - `--ki-elevation-none`: Flat surfaces carry no resting shadow. - `--ki-icon-button-ghost-selected-bg`: Background of the selected ghost icon button toggle. - `--ki-icon-button-ghost-selected-fg`: Foreground of the selected ghost icon button toggle. - `--ki-icon-button-lg-icon-size`: dimension used by the icon button component for lg icon size (MarsUI Placeholder_lg 24px). - `--ki-icon-button-lg-size`: dimension used by the icon button component for lg box (48px square). - `--ki-icon-button-lg-spinner-size`: dimension used by the icon button component for the lg loading spinner box (24px, the lg icon size; spec 046 D5: the spinner takes the place of the icon). - `--ki-icon-button-md-icon-size`: dimension used by the icon button component for md icon size (MarsUI Placeholder_md 20px — the button md icon is 18px, 002 §3). - `--ki-icon-button-md-size`: dimension used by the icon button component for md box (40px square, Figma node 10078:3129). - `--ki-icon-button-md-spinner-size`: dimension used by the icon button component for the md loading spinner box (20px, the md icon size; spec 046 D5: the spinner takes the place of the icon). - `--ki-icon-button-outline-rest-bg`: Background of the outline variant at rest. - `--ki-icon-button-outline-rest-border`: Visible outline of the outline variant at rest. - `--ki-icon-button-outline-rest-fg`: Foreground of the outline variant at rest. - `--ki-icon-button-outline-selected-bg`: Background of the selected outline icon button toggle. - `--ki-icon-button-outline-selected-fg`: Foreground of the selected outline icon button toggle. - `--ki-icon-button-primary-selected-bg`: Background of the selected primary icon button toggle. - `--ki-icon-button-primary-selected-fg`: Foreground of the selected primary icon button toggle. - `--ki-icon-button-quaternary-selected-bg`: Background of the selected quaternary icon button toggle. - `--ki-icon-button-quaternary-selected-fg`: Foreground of the selected quaternary icon button toggle. - `--ki-icon-button-secondary-selected-bg`: Background of the selected secondary icon button toggle. - `--ki-icon-button-secondary-selected-fg`: Foreground of the selected secondary icon button toggle. - `--ki-icon-button-sm-icon-size`: dimension used by the icon button component for sm icon size (MarsUI Placeholder_sm 18px). - `--ki-icon-button-sm-size`: dimension used by the icon button component for sm box (32px square). - `--ki-icon-button-sm-spinner-size`: dimension used by the icon button component for the sm loading spinner box (18px, the sm icon size; spec 046 D5: the spinner takes the place of the icon). - `--ki-icon-button-toggle-radius`: Round shape for an unselected icon toggle button. - `--ki-icon-button-toggle-selected-radius`: Rounded square shape for a selected icon toggle button. - `--ki-icon-button-xl-icon-size`: dimension used by the icon button component for xl icon size (MarsUI Placeholder_xl 28px). - `--ki-icon-button-xl-size`: dimension used by the icon button component for xl box (56px square). - `--ki-icon-button-xl-spinner-size`: dimension used by the icon button component for the xl loading spinner box (28px, the xl icon size; spec 046 D5: the spinner takes the place of the icon). - `--ki-icon-button-xs-icon-size`: dimension used by the icon button component for xs icon size (MarsUI Icon/Placeholder_xs 16px — one step above the button xs icon). - `--ki-icon-button-xs-size`: dimension used by the icon button component for xs box (24px square, Figma Space/7xl). - `--ki-icon-button-xs-spinner-size`: dimension used by the icon button component for the xs loading spinner box (16px, the xs icon size; spec 046 D5: the spinner takes the place of the icon). - `--ki-motion-duration-fast`: Fast interaction transition duration. - `--ki-motion-easing-out`: Decelerating interaction transition easing curve. - `--ki-outline-none`: semantic color for outline none. - `--ki-surface-image-none`: An unadorned surface has no background image. - `--ki-typography-family-body`: semantic font family for typography family body. ### ki-image Displays one accessible image in a reserved frame, with an optional caption and a fallback if the source is refused or fails to load. When to use: to show a photo, illustration, or diagram with a predictable layout. Supply task-relevant alt text, or mark purely decorative media as decorative. Set an explicit ratio when the layout must stay fixed. When NOT to use: for a background decoration, a video, or an interactive control. Use a separate control to open or otherwise act on an image. Examples: # Using ki-image Give an informative image alt text that describes the detail the reader needs. An explicit ratio reserves the same frame while the image loads and when the fallback appears. Add supporting context in the caption slot. ```html View from the ridge ``` Use `contain` when the whole image must stay visible. The fallback for this example is named `Image unavailable: Office floor plan` if the source fails. ```html ``` Use `decorative` for ornamentation. The image and fallback stay out of the accessibility tree. ```html ``` Attributes: - `alt` (string | undefined): Describe what the image shows for the task at hand. Required and nonblank for an informative image. Omit it for a decorative image. - `decorative` (boolean, default false): Hide the media from assistive technology when it conveys no information. - `fallback-label` (string, default 'Image unavailable'): Localizable fallback label. An informative fallback appends the image's description, when available, to this label. - `fit` ("contain" | "cover", default 'cover'): Cover fills the frame. Contain preserves the whole image in it. - `loading` ("eager" | "lazy", default 'lazy'): Native loading hint. Use eager for a critical image above the fold. - `radius` ("lg" | "md" | "none", default 'lg'): Corner radius of the media frame. - `ratio` ("16:9" | "1:1" | "3:2" | "4:3" | "auto", default 'auto'): An explicit ratio reserves the same frame before load and on failure. Auto reserves 16:9 first and uses the intrinsic ratio after load. - `src` (string, required, URL): Relative or HTTP(S) image URL. Refused sources are left unloaded. Slots: - `caption`: Optional visible context displayed below the media in a figcaption. Parts: - `caption`: The figcaption carrying the slotted caption. - `fallback`: The unavailable-image indicator inside the frame. - `figure`: The figure containing the frame and optional caption. - `frame`: The reserved media box and its shape and backing surface. - `image`: The native image and its fit within the frame. Events: - `ki-error` (CustomEvent): Reports a load failure or rejected URL once per source attempt. Bubbles and crosses shadow boundaries so consumers can observe it on a surface. Methods: none CSS custom properties: - `--ki-image-caption-fg`: Text colour of the visible caption. - `--ki-image-caption-font-family`: Typeface of the visible caption. - `--ki-image-caption-font-size`: Type size of the visible caption. - `--ki-image-caption-gap`: Space between the image frame and its caption. - `--ki-image-caption-line-height`: Line height of the visible caption. - `--ki-image-fallback-backdrop-filter`: Complete filter applied behind the media surface. - `--ki-image-fallback-bg`: Solid fill behind the image and fallback symbol. - `--ki-image-fallback-bg-image`: Optional background image over the media fill. - `--ki-image-fallback-fg`: Foreground of the fallback symbol. - `--ki-image-fallback-icon-size`: Inline and block size of the unavailable-image symbol. - `--ki-image-fallback-icon-stroke-width`: Stroke width of the unavailable-image symbol. - `--ki-image-radius`: Corner radius of the default media frame. - `--ki-image-radius-md`: Corner radius of the medium media frame. - `--ki-typography-family-body`: semantic font family for typography family body. ### ki-indicator A non-interactive page-position indicator: one dot per position of a bounded sequence, exactly one highlighted as current. When to use: show the current position within a bounded, sequential set of peer views whose navigation lives elsewhere: carousel slides, unlabeled onboarding steps, gallery pages. Wire `count` and `current` (1-based) to the sequence the consumer renders and give it a `label` (required authoring: assistive technology reads one graphic named "