Skip to content
Kimenpre-v1documentation home
Color scheme

ki-reasoning

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.

Theme for this example
Color scheme for this example
  1. Check the inputs.
  2. 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.

Theme for this example
Color scheme for this example
  1. Check the inputs.
  2. 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

AttributePropertyTypeDefaultDescription
done-labeldoneLabelstring'Thought'Summary text when done and elapsed time is unavailable.
durationdurationnumber | undefined–Optional elapsed milliseconds. Done displays finite, nonnegative values rounded to seconds.
duration-labeldurationLabelstring'Thought for {seconds} seconds'Summary template for zero or multiple elapsed seconds. The {seconds} placeholder receives the rounded time.
openopenbooleanfalseWhether the disclosure shows its steps. Native toggles update this reflected property.
singular-duration-labelsingularDurationLabelstring'Thought for {seconds} second'Summary template for one elapsed second. The {seconds} placeholder receives the rounded time.
statusstatus"done" | "thinking"'thinking'Use thinking while steps arrive and done once the assistant finishes.
thinking-labelthinkingLabelstring'Thinking…'Summary text while the assistant is thinking.

Events

EventDetail typeDescription
ki-toggleCustomEvent<KiReasoningToggleDetail>Emitted after a native disclosure toggle. Setting open from the application is silent.

Slots

SlotDescription
(default)Supporting content shown when expanded, such as an ordered list of steps supplied by the application.

CSS parts

PartDescription
bodyThe slotted content area with the inline-start rule.
summaryThe 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.

TokenDescription
--ki-density-target-minThe 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-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-offsetGap between a focusable component and its keyboard focus ring.
--ki-focus-ring-widthThickness 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-fastFast interaction transition duration.
--ki-motion-easing-standardStandard interaction transition easing curve.
--ki-reasoning-backdrop-filterComplete filter behind the disclosure. None keeps the backdrop clear.
--ki-reasoning-bgFill behind the disclosure summary and its steps.
--ki-reasoning-bg-imageOptional image painted over the disclosure fill.
--ki-reasoning-body-gapBlock spacing between the summary and the step content.
--ki-reasoning-body-indentInline spacing between the rule and the content.
--ki-reasoning-borderInk of the decorative rule at the inline start of the steps.
--ki-reasoning-border-widthWidth of the steps rule.
--ki-reasoning-fgMedium-emphasis ink for the disclosure summary and its steps.
--ki-reasoning-list-indentInline space for markers on a slotted list.
--ki-reasoning-shimmer-durationPeriod of the thinking shimmer.
--ki-reasoning-shimmer-easingEasing into and out of the thinking highlight.
--ki-reasoning-shimmer-fgReadable highlight at the midpoint of the thinking shimmer.
--ki-reasoning-summary-gapSpace between the summary text and glyphs and between separate step blocks.
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-parasemantic dimension for typography line height para.
--ki-typography-size-body-1semantic dimension for typography size body 1.
--ki-typography-visually-hidden-sizeNonzero edge for clipped text available to assistive technology.

Workshop

Open ki-reasoning in Storybook