From a5bd5f1bbba5c34ca18c4ce4d176485b585b3065 Mon Sep 17 00:00:00 2001 From: Mark Otto Date: Fri, 21 Aug 2026 20:54:58 -0700 Subject: [PATCH 1/4] Add a Chat component for message threads Agent and messaging UIs need bubbles, grouped bubbles, and a place to report tool calls and thinking states. The component gives each of these a token-driven class, so consumers can restyle them without overrides. --- scss/_chat.scss | 191 ++++++++++++++++++++++ scss/bootstrap.scss | 1 + site/data/sidebar.yml | 3 + site/src/content/docs/components/chat.mdx | 187 +++++++++++++++++++++ 4 files changed, 382 insertions(+) create mode 100644 scss/_chat.scss create mode 100644 site/src/content/docs/components/chat.mdx diff --git a/scss/_chat.scss b/scss/_chat.scss new file mode 100644 index 0000000000..e5cf2ea52f --- /dev/null +++ b/scss/_chat.scss @@ -0,0 +1,191 @@ +@use "config" as *; +@use "functions" as *; +@use "mixins/border-radius" as *; +@use "mixins/tokens" as *; + +$chat-tokens: () !default; + +// stylelint-disable custom-property-no-missing-var-function +// scss-docs-start chat-tokens +// stylelint-disable-next-line scss/dollar-variable-default +$chat-tokens: defaults( + ( + --chat-bg: var(--bg-body), + --chat-border-color: var(--border-muted), + --chat-padding: 1rem, + --chat-gap: .75rem, + --chat-message-gap: .25rem, + --chat-message-max-width: 75%, + --chat-message-padding-x: .875rem, + --chat-message-padding-y: .5rem, + --chat-message-border-radius: var(--radius-8), + --chat-message-group-radius: var(--radius-2), + --chat-message-group-start-radius: var(--chat-message-group-radius), + --chat-message-group-end-radius: var(--chat-message-border-radius), + --chat-message-tail-size: 1rem, + --chat-message-color: var(--theme-fg, var(--fg-body)), + --chat-message-bg: var(--theme-bg-subtle, var(--bg-2)), + --chat-message-you-color: var(--theme-contrast, var(--primary-contrast)), + --chat-message-you-bg: var(--theme-bg, var(--primary-bg)), + --chat-status-gap: .5rem, + --chat-thinking-font-size: var(--font-size-sm), + --chat-thinking-color: var(--fg-4), + --chat-thinking-highlight-color: var(--fg-body), + --chat-thinking-animation-duration: 2s, + ), + $chat-tokens +); +// scss-docs-end chat-tokens +// stylelint-enable custom-property-no-missing-var-function + +@layer components { + .chat { + @include tokens($chat-tokens); + + display: flex; + flex-direction: column; + gap: var(--chat-gap); + padding: var(--chat-padding); + background-color: var(--chat-bg); + border: var(--border-width) solid var(--chat-border-color); + @include border-radius(var(--radius-5)); + } + + .chat-row { + display: flex; + flex-direction: column; + gap: var(--chat-message-gap); + align-items: flex-start; + } + + .chat-row-you { + align-items: flex-end; + } + + .chat-message { + position: relative; + display: inline-block; + max-width: var(--chat-message-max-width); + padding: var(--chat-message-padding-y) var(--chat-message-padding-x); + color: var(--chat-message-color); + background-color: var(--chat-message-bg); + @include border-radius(var(--chat-message-border-radius)); + + &:last-child { + margin-bottom: calc(var(--chat-message-tail-size) * .5); + } + + // Inside a group, tighten the corners that face the neighbor bubble. The + // sender side keeps the tight corners, as iOS does. + &:not(:first-child) { + border-start-start-radius: var(--chat-message-group-start-radius); + border-start-end-radius: var(--chat-message-group-end-radius); + } + + &:not(:last-child) { + border-end-start-radius: var(--chat-message-group-start-radius); + border-end-end-radius: var(--chat-message-group-end-radius); + } + } + + // Message tail + // + // The ::before element paints the tail in the bubble color. The ::after + // element cuts the notch back into the panel background so the tail + // connects to the last bubble of the group. + // + // Logical properties keep the tail on the sender's edge, so it stays attached + // to the bubble in both writing directions. + .chat-message:last-child::before, + .chat-message:last-child::after { + position: absolute; + inset-block-end: 0; + content: ""; + } + + .chat-message:last-child::before { + inset-inline-start: calc(var(--chat-message-tail-size) * -.35); + z-index: 0; + width: var(--chat-message-tail-size); + height: var(--chat-message-tail-size); + background-color: var(--chat-message-bg); + @include border-bottom-end-radius(calc(var(--chat-message-tail-size) * .75)); + } + + .chat-message:last-child::after { + inset-inline-start: calc(var(--chat-message-tail-size) * -.5); + z-index: 1; + width: calc(var(--chat-message-tail-size) * .5); + height: var(--chat-message-tail-size); + background-color: var(--chat-bg); + @include border-bottom-end-radius(calc(var(--chat-message-tail-size) * .5)); + } + + .chat-message-you { + --chat-message-bg: var(--chat-message-you-bg); + --chat-message-color: var(--chat-message-you-color); + --chat-message-group-start-radius: var(--chat-message-border-radius); + --chat-message-group-end-radius: var(--chat-message-group-radius); + + &:last-child::before { + inset-inline-start: auto; + inset-inline-end: calc(var(--chat-message-tail-size) * -.35); + border-end-end-radius: 0; + @include border-bottom-start-radius(calc(var(--chat-message-tail-size) * .75)); + } + + &:last-child::after { + inset-inline-start: auto; + inset-inline-end: calc(var(--chat-message-tail-size) * -.5); + border-end-end-radius: 0; + @include border-bottom-start-radius(calc(var(--chat-message-tail-size) * .5)); + } + } + + // Status rows + // + // Thinking states and tool calls report on the work, so they stay outside a + // bubble. The inline padding lines their text up with the text in a bubble. + .chat-status { + display: flex; + flex-wrap: wrap; + gap: var(--chat-status-gap); + align-items: center; + padding-inline: var(--chat-message-padding-x); + } + + // A gradient sweeps across the label while the agent works. The text is + // transparent, so the background paints the glyphs. + .chat-thinking { + font-size: var(--chat-thinking-font-size); + color: transparent; + background-image: + linear-gradient( + 90deg, + var(--chat-thinking-color) 35%, + var(--chat-thinking-highlight-color) 50%, + var(--chat-thinking-color) 65% + ); + background-clip: text; + background-size: 200% 100%; + animation: chat-thinking var(--chat-thinking-animation-duration) linear infinite; + + @if $enable-reduced-motion { + // The glyphs come from the background, so the label needs a color back + // when the sweep stops. + @media (prefers-reduced-motion: reduce) { + color: var(--chat-thinking-highlight-color); + background-image: none; + animation: none; + } + } + } + + // The gradient tiles, and one iteration moves it by its own width, so the + // sweep repeats without a jump. + @keyframes chat-thinking { + to { + background-position: -200% 0; + } + } +} diff --git a/scss/bootstrap.scss b/scss/bootstrap.scss index 58960c6e9a..5f9efaf09d 100644 --- a/scss/bootstrap.scss +++ b/scss/bootstrap.scss @@ -29,6 +29,7 @@ @forward "chip"; @forward "card"; @forward "carousel"; +@forward "chat"; @forward "datepicker"; @forward "dialog"; @forward "menu"; diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml index ff804192b4..d1c852d3d3 100644 --- a/site/data/sidebar.yml +++ b/site/data/sidebar.yml @@ -129,6 +129,9 @@ - title: Button group - title: Card - title: Carousel + - title: Chat + meta: + - added: 6.0.0 - title: Close button - title: Collapse - title: Dialog diff --git a/site/src/content/docs/components/chat.mdx b/site/src/content/docs/components/chat.mdx new file mode 100644 index 0000000000..e0998573b9 --- /dev/null +++ b/site/src/content/docs/components/chat.mdx @@ -0,0 +1,187 @@ +--- +title: Chat +description: Documentation and examples for chat interfaces, including message bubbles, tool call indicators, thinking states, and a histogram for navigating a conversation. +toc: true +css_layer: components +--- + +## Examples + +Chats render conversations as a vertical stack of message groups. Each group of messages from the same sender lives in a `.chat-row`. Messages inside a row appear as iOS-style bubbles with a tail on the last bubble of the group. + + +
+
Dude
+
+
+
Hey!
+
You there?
+
Hello, how's it going?
+
+
+
Great, thanks!
+
How about you?
+
+ `} /> + +## Your messages + +Use `.chat-message-you` to mark your messages. Your messages align to the right and use the primary color by default. Put them inside a `.chat-row-you` so the whole group aligns to the right. + + +
+
Just shipped the fix
+
Can you review it?
+
+
+
On it!
+
+ `} /> + +## Theme colors + +Messages use the theme color tokens. Add a `.theme-*` class to the `.chat` container to recolor every message bubble at once. Without a theme class, your messages use the primary color. + + +
+
Shipped the dashboard revamp
+
Deploying now
+
+
+
Looks great in the preview!
+
+ `} /> + + +
+
All tests pass
+
+
+
Merging the pull request
+
+ `} /> + +## Status rows + +A tool call or a thinking state reports on the work, so it does not belong in a bubble. Put it in a `.chat-status` row instead. The row lines its text up with the text in the bubbles around it. + +## Tool calls + +Show tool calls with [Chips]([[docsref:/forms/chips]]) or [Badges]([[docsref:/components/badge]]) in a `.chat-status` row. Pair a chip with a `.spinner` while the tool runs, and use `.theme-*` classes to color each result. + + +
+
Find the search styles
+
+
+
+ + + Searching the codebase + + + + 3 files + +
+
+
+
Found 3 files, starting with search.scss
+
+ `} /> + +## Thinking + +Show a "thinking" or "working" state with `.chat-thinking`. A gradient sweeps across the label while the agent works. Name the task in the label, such as "Planning…" or "Reading files…". + +Add `role="status"` to the row so assistive technologies announce it. Under `prefers-reduced-motion: reduce`, the sweep stops and the label keeps a plain color. + + +
+
Anything new?
+
+
+
+ Thinking… +
+
+ `} /> + +Set `--chat-thinking-animation-duration` for a faster or slower sweep, and set the two colors to change how much the label stands out. + + +
+
+ Planning the migration… +
+
+
+
+ Reading 24 files… +
+
+
+
+ Running the test suite… +
+
+ `} /> + +## Conversation histogram + +Put a [Histogram]([[docsref:/components/histogram]]) next to a long conversation to navigate it. Each `.histogram-item` points at the `id` of a message group, and the bar length hints at how much that group holds. Point at the histogram to read the labels. + +Add [Scrollspy]([[docsref:/components/scrollspy]]) to the element that scrolls to move the current row as the reader scrolls. + + +
+
+
Morning! Is the summary ready?
+
+
+
Yes, here it is:
+
Deploys are green and the new sidebar shipped.
+
+
+
Nice work
+
+
+
I also cut the bundle by 12% and moved the icons to CSS masks.
+
+
+
Ship it
+
+
+ + `} /> + +## CSS + +### Variables + +Chat uses local CSS variables on `.chat` for real-time customization. Values for the CSS variables are generated from Sass maps unique to the component and applied to the aforementioned class. + + + + From ffed3383afe8ade0b4e87643fa4bc89f52ea474f Mon Sep 17 00:00:00 2001 From: Mark Otto Date: Fri, 21 Aug 2026 20:55:31 -0700 Subject: [PATCH 2/4] Add a Histogram component for conversation rails A long chat needs a compact map. The rail shows one bar per message, and it expands to labels on hover or focus. It pairs with Scrollspy to mark the message in view. --- scss/_histogram.scss | 167 ++++++++++++++++++ scss/bootstrap.scss | 1 + site/data/sidebar.yml | 3 + .../src/content/docs/components/histogram.mdx | 140 +++++++++++++++ site/src/scss/_component-examples.scss | 13 ++ 5 files changed, 324 insertions(+) create mode 100644 scss/_histogram.scss create mode 100644 site/src/content/docs/components/histogram.mdx diff --git a/scss/_histogram.scss b/scss/_histogram.scss new file mode 100644 index 0000000000..3263335888 --- /dev/null +++ b/scss/_histogram.scss @@ -0,0 +1,167 @@ +@use "config" as *; +@use "functions" as *; +@use "mixins/border-radius" as *; +@use "mixins/focus-ring" as *; +@use "mixins/transition" as *; +@use "mixins/tokens" as *; + +// Number of items that get a staggered reveal. Later items reveal with the +// same delay as the last one in the sequence. +$histogram-stagger-items: 12 !default; + +$histogram-tokens: () !default; + +// scss-docs-start histogram-tokens +// stylelint-disable-next-line scss/dollar-variable-default +$histogram-tokens: defaults( + ( + --histogram-track-width: 2.5rem, + --histogram-item-height: .75rem, + --histogram-item-hover-height: 1.5rem, + --histogram-item-hover-color: var(--fg-body), + --histogram-item-active-color: var(--theme-fg, var(--primary-fg)), + --histogram-bar-length: 100%, + --histogram-bar-size: .125rem, + --histogram-bar-border-radius: var(--radius-pill), + --histogram-bar-bg: var(--fg-4), + --histogram-bar-active-bg: var(--theme-bg, var(--primary-bg)), + --histogram-label-color: var(--fg-2), + --histogram-label-font-size: var(--font-size-sm), + --histogram-stagger: 30ms, + --histogram-transition-property: "block-size, color, opacity, background-color", + --histogram-transition-duration: .2s, + --histogram-transition-timing: var(--transition-timing-overlay), + ), + $histogram-tokens +); +// scss-docs-end histogram-tokens + +@layer components { + .histogram { + @include tokens($histogram-tokens); + + display: flex; + flex-direction: column; + } + + // Each item stacks a bar and a label in the same grid cell, so the label + // takes over the row without moving anything. The bar keeps its own column + // so its length stays a share of the track, not of the label. + .histogram-item { + // Items past the stagger cap match no `nth-child` rule below, so they fall + // back to this max delay and reveal with the last staggered row instead of + // jumping to the front. + --histogram-item-delay: calc(#{$histogram-stagger-items - 1} * var(--histogram-stagger)); + + display: grid; + grid-template-columns: var(--histogram-track-width) minmax(0, 1fr); + align-items: center; + block-size: var(--histogram-item-height); + padding: 0; + color: var(--histogram-label-color); + text-align: start; + text-decoration: none; + background-color: transparent; + border: 0; + @include transition-props( + var(--histogram-transition-property), + var(--histogram-transition-duration), + var(--histogram-transition-timing) + ); + + &:hover { + color: var(--histogram-item-hover-color); + } + + &:focus-visible { + @include focus-ring(true); + } + + &.active { + color: var(--histogram-item-active-color); + + .histogram-bar { + background-color: var(--histogram-bar-active-bg); + } + } + } + + .histogram-bar { + grid-area: 1 / 1; + inline-size: var(--histogram-bar-length); + block-size: var(--histogram-bar-size); + background-color: var(--histogram-bar-bg); + @include border-radius(var(--histogram-bar-border-radius)); + @include transition-props( + var(--histogram-transition-property), + var(--histogram-transition-duration), + var(--histogram-transition-timing) + ); + } + + .histogram-label { + grid-area: 1 / 1 / 2 / -1; + overflow: hidden; + font-size: var(--histogram-label-font-size); + text-overflow: ellipsis; + white-space: nowrap; + opacity: 0; + @include transition-props( + var(--histogram-transition-property), + var(--histogram-transition-duration), + var(--histogram-transition-timing) + ); + } + + // Bars trade places with labels as soon as a pointer or the keyboard enters + // the histogram. Rows grow at the same time to make room for the text. + .histogram:hover, + .histogram:focus-within { + .histogram-item { + block-size: var(--histogram-item-hover-height); + } + + .histogram-bar { + opacity: 0; + } + + .histogram-label { + opacity: 1; + + // The delay drives the staggered reveal, so it must follow the same + // reduced-motion gate as the transition itself. Otherwise the labels + // still pop in one by one for a user who asked for less motion. + @if $enable-reduced-motion { + @media (prefers-reduced-motion: no-preference) { + transition-delay: var(--histogram-item-delay, 0s); + } + } @else { + transition-delay: var(--histogram-item-delay, 0s); + } + } + } + + // Reveal the labels top to bottom instead of all at once. Only the reveal + // is staggered — leaving the histogram collapses every row together. + @for $i from 1 through $histogram-stagger-items { + .histogram-item:nth-child(#{$i}) { + --histogram-item-delay: calc(#{$i - 1} * var(--histogram-stagger)); + } + } + + // Mirror the histogram for a sidebar on the end edge of the conversation. + .histogram-end { + .histogram-item { + grid-template-columns: minmax(0, 1fr) var(--histogram-track-width); + } + + .histogram-bar { + grid-area: 1 / 2; + margin-inline-start: auto; + } + + .histogram-label { + text-align: end; + } + } +} diff --git a/scss/bootstrap.scss b/scss/bootstrap.scss index 5f9efaf09d..6d5a27ce2c 100644 --- a/scss/bootstrap.scss +++ b/scss/bootstrap.scss @@ -38,6 +38,7 @@ @forward "nav-overflow"; @forward "navbar"; @forward "drawer"; +@forward "histogram"; @forward "pagination"; @forward "placeholder"; @forward "popover"; diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml index d1c852d3d3..6fbc1d90d9 100644 --- a/site/data/sidebar.yml +++ b/site/data/sidebar.yml @@ -140,6 +140,9 @@ - title: Drawer meta: - added: 6.0.0 + - title: Histogram + meta: + - added: 6.0.0 - title: List group - title: Menu meta: diff --git a/site/src/content/docs/components/histogram.mdx b/site/src/content/docs/components/histogram.mdx new file mode 100644 index 0000000000..52264456aa --- /dev/null +++ b/site/src/content/docs/components/histogram.mdx @@ -0,0 +1,140 @@ +--- +title: Histogram +description: Documentation and examples for the histogram, a collapsed sidebar of bars that expands into labels on hover for navigating long chats and other lists. +toc: true +css_layer: components +--- + +## How it works + +A histogram is a compact sidebar for a long list, like the messages in a [chat]([[docsref:/components/chat]]). Each row collapses to a single bar, so the whole list reads as a shape. Point at the histogram and the bars trade places with their labels, one row after another. + +Every row is a `.histogram-item` with two children: + +- `.histogram-bar` draws the bar. Set its length with `--histogram-bar-length` to hint at the size of the row, such as the length of a message. +- `.histogram-label` holds the text. It stays in the accessibility tree while it is hidden, so it names the link for assistive technologies. + +Bars sit in a fixed column, `--histogram-track-width`, and labels fill the width of the histogram. Give the histogram enough width for the labels, and leave the rest of the space empty. The bars never move as a result. + + + + + Ship the pricing page revamp + + + + Found the pricing components + + + + Summarize the changes + + + + Tier cards, FAQ, and annual pricing + + + + Deploy it to the preview + + `} /> + +Rows reveal in sequence from the top. Set the step with `--histogram-stagger`, and set it to `0s` to reveal every row at once. Leaving the histogram always collapses the rows together. + +## Current item + +Add `.active` to mark the row you are on. The bar and the label both pick up the theme color. Add `aria-current="true"` so assistive technologies announce it too. + + + + + Run the visual checks + + + + All 12 checks passed + + + + Merge the pull request + + `} /> + +Pair the histogram with [Scrollspy]([[docsref:/components/scrollspy]]) to move `.active` as the reader scrolls. Point each `.histogram-item` at the `id` of a message and spy on the element that scrolls. + +## End alignment + +Add `.histogram-end` for a histogram on the end edge of the content. Bars grow from the end edge and labels align to it. + + + + + Ship the pricing page revamp + + + + Found the pricing components + + + + Deploy it to the preview + + `} /> + +## Sizing + +Three custom properties control the size of a histogram. `--histogram-track-width` sets the bar column, `--histogram-item-height` sets the collapsed row, and `--histogram-item-hover-height` sets the row while the labels show. + + + + + Read the deploy log + + + + Two builds failed on the same test + + + + Retry them with the fix + + `} /> + +## Theme colors + +The current row uses the theme color tokens. Add a `.theme-*` class to the histogram to recolor it. Without a theme class the current row uses the primary color. + + + + + Run the test suite + + + + All tests pass + + + + Tag the release + + `} /> + +## Accessibility + +Wrap the histogram in a `