ki-reasoning
@kimen/elements/ki-reasoning- Source
- Agent reference
Use ki-reasoning for supporting steps that a reader can open on demand. Keep
the assistant’s answer outside the disclosure. The disclosure starts collapsed
and its summary reads “Thinking…” while the assistant works.
Thinking
Append steps to the default slot as they arrive. An open disclosure shows the new
steps in order. Set open to display the steps immediately.
- Check the inputs.
- Compare the available outcomes.
<ki-reasoning open><ol> <li>Check the inputs.</li> <li>Compare the available outcomes.</li></ol></ki-reasoning>Completed
Set status="done" when the assistant finishes. Supply elapsed milliseconds in
duration for a summary such as “Thought for 12 seconds.” The component rounds
the elapsed time to the nearest second. Without a valid elapsed time, the
summary reads “Thought.” The disclosure keeps its current open state.
- Check the inputs.
- Compare the available outcomes.
<ki-reasoning status="done" duration="12000"><ol> <li>Check the inputs.</li> <li>Compare the available outcomes.</li></ol></ki-reasoning>Accessibility and customization
The native summary opens and closes with Enter or Space. Status changes have a
polite announcement, and reduced motion keeps the thinking text still. Localize
the summary with thinking-label, done-label, singular-duration-label, and
duration-label. Include {seconds} in the two duration labels where the
number belongs.
Use --ki-reasoning-fg to customize the text and --ki-reasoning-border to
customize the rule beside the steps. The backing is transparent by default.
Use --ki-reasoning-bg, --ki-reasoning-bg-image, and
--ki-reasoning-backdrop-filter to style it. The summary and body parts
allow additional styling.
Listen for ki-toggle to read event.detail.open after a reader opens or closes
the disclosure.
API reference
When to use: present assistant-supplied steps, progress or a completed plan alongside the answer.
When not to use: hide the answer or controls the user needs to complete a task. Use a general disclosure for unrelated content.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
done-label | doneLabel | string | 'Thought' | Summary text when done and elapsed time is unavailable. |
duration | duration | number | undefined | – | Optional elapsed milliseconds. Done displays finite, nonnegative values rounded to seconds. |
duration-label | durationLabel | string | 'Thought for {seconds} seconds' | Summary template for zero or multiple elapsed seconds. The {seconds} placeholder receives the rounded time. |
open | open | boolean | false | Whether the disclosure shows its steps. Native toggles update this reflected property. |
singular-duration-label | singularDurationLabel | string | 'Thought for {seconds} second' | Summary template for one elapsed second. The {seconds} placeholder receives the rounded time. |
status | status | "done" | "thinking" | 'thinking' | Use thinking while steps arrive and done once the assistant finishes. |
thinking-label | thinkingLabel | string | 'Thinking…' | Summary text while the assistant is thinking. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-toggle | CustomEvent<KiReasoningToggleDetail> | Emitted after a native disclosure toggle. Setting open from the application is silent. |
Slots
| Slot | Description |
|---|---|
| (default) | Supporting content shown when expanded, such as an ordered list of steps supplied by the application. |
CSS parts
| Part | Description |
|---|---|
body | The slotted content area with the inline-start rule. |
summary | The native disclosure control that shows the current status. |
CSS custom properties
The public styling contract of ki-reasoning: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--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-standard | Standard interaction transition easing curve. |
--ki-reasoning-backdrop-filter | Complete filter behind the disclosure. None keeps the backdrop clear. |
--ki-reasoning-bg | Fill behind the disclosure summary and its steps. |
--ki-reasoning-bg-image | Optional image painted over the disclosure fill. |
--ki-reasoning-body-gap | Block spacing between the summary and the step content. |
--ki-reasoning-body-indent | Inline spacing between the rule and the content. |
--ki-reasoning-border | Ink of the decorative rule at the inline start of the steps. |
--ki-reasoning-border-width | Width of the steps rule. |
--ki-reasoning-fg | Medium-emphasis ink for the disclosure summary and its steps. |
--ki-reasoning-list-indent | Inline space for markers on a slotted list. |
--ki-reasoning-shimmer-duration | Period of the thinking shimmer. |
--ki-reasoning-shimmer-easing | Easing into and out of the thinking highlight. |
--ki-reasoning-shimmer-fg | Readable highlight at the midpoint of the thinking shimmer. |
--ki-reasoning-summary-gap | Space between the summary text and glyphs and between separate step blocks. |
--ki-typography-family-body | semantic font family for typography family body. |
--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-visually-hidden-size | Nonzero edge for clipped text available to assistive technology. |