@expressivecss/expressive 0.11.0 → 0.13.1

package/CHANGELOG.md

@@ -5,6 +5,388 @@ the format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.13.1] - 2026-10-08
+
+### Fixed
+
+- The capability roadmap's source links point at a commit on `master`. The
+  0.13.0 links pointed at a pull request commit that no longer exists, which
+  stopped the 0.13.0 release before it reached npm. 0.13.1 contains the
+  0.13.0 changes below.
+
+## [0.13.0] - 2026-10-08
+
+### Added
+
+- `.rich-text-editor` turns a `<textarea>` into a Tiptap editor with a
+  docked toolbar. The page installs Tiptap and passes its `Editor` class and
+  extensions to `RichTextEditor.init()`; ExpressiveCSS does not bundle it.
+  A toolbar button's `data-command` names a Tiptap command and
+  `data-attributes` holds its JSON argument. Buttons are disabled when their
+  command cannot run, and `toggle` commands set `aria-pressed` and `.active`.
+  The textarea keeps the editor's HTML, so it submits with its form, and
+  names the editable textbox.
+- `.marquee` scrolls a row of logos, images or text without end. Write
+  the items in two `.marquee-content` groups, the second marked
+  `aria-hidden="true"`. `vertical`, `reverse` and `fade` change the
+  direction and edges, `paused` stops it, and hover or focus inside pauses
+  it. Reduced motion stops the scroll and hides the copy. CSS only.
+- `<mark>` highlights part of a text in the tertiary container colors,
+  with no padding so a match inside a word keeps its spacing.
+  `::highlight(mark)` paints ranges registered with the CSS Custom
+  Highlight API the same way.
+- `.message-scroller` scrolls a conversation. While the reader is at the
+  end it follows streamed replies, and scrolling up releases it. A message
+  appended with `data-scroll-anchor` starts a turn and is scrolled to the
+  top, leaving 64px of the previous message in view. Messages added above
+  keep the reader's place. A transcript can open at its end, its start or
+  its last turn, `scrollToMessage(id)` jumps to any message, and an optional
+  `.message-scroller-button` scrolls to the latest message.
+- `form.questionnaire` asks one question at a time. Each `<fieldset>` is a
+  question with radio, checkbox or text answers, and footer buttons marked
+  `value="previous"`, `"skip"` and `"next"` move between them. The component
+  adds a progress row, checks each question with the browser's validation
+  (`data-required` asks for at least one checkbox), shows the question's
+  `.questionnaire-error`, offers Skip on optional questions and leaves out
+  disabled ones so pages can branch. The form submits normally, and without
+  JavaScript every question shows at once.
+- KPI component: `article.kpi` is a card for one key figure, with its
+  label and value in a `<dl>`, a `.kpi-trend` chip that takes `up`, `down`
+  and `negative`, an optional `.kpi-icon`, a `.kpi-actions` corner button,
+  a sparkline chart, a progress bar and a `.kpi-footer`. A `negative` trend
+  also turns the sparkline to the error color. CSS only.
+- `.countdown` shows a whole number from 0 to 999 and rolls its digits up
+  or down when `--md-comp-countdown-value` changes. The element's text is
+  the value screen readers read. `--md-comp-countdown-digits` pads with
+  leading zeros, and reduced motion turns the roll off. CSS only.
+- `.aura` wraps one button, card or panel and runs a light around a ring
+  just outside it, to mark the one thing a screen most needs the user to
+  see. `dual`, `rainbow` and `glow` change the light, and tokens set its
+  color, width, corners and speed. The ring is fully rounded around a
+  button, stops turning under reduced motion and stays out of the
+  accessibility tree.
+- The agent skill gains an `expressivecss-charts` guide for building charts
+  and chart dashboards. It covers choosing a chart for the question asked,
+  table cells the charts can read, chart cards with stats, tokens,
+  sparklines and redrawing. Its recipes cover a period switch, a KPI row,
+  a donut with its total, a budget meter, a gauge, a heatmap and a
+  dashboard section. The root skill routes chart work to it.
+- `.mixed-chart` draws a `<figure>`'s data table as columns, lines and
+  areas on one plot, chosen by each series header's class: `column`,
+  `area`, or a line by default, with `dashed` lines. A series with `end`
+  is drawn against a second scale, set by `data-end-min` and
+  `data-end-max`, for values in other units. The tooltip, cursor points,
+  legend and `sparkline` work as in the line chart.
+- `.radial-chart` draws a `<figure>`'s data table as rings, one per row,
+  filled clockwise from the top as a share of `data-max` (100 by default),
+  with a legend, tracks, and a tooltip that follows the pointer across the
+  rings or the arrow keys. `gauge` draws half circles, a `<tfoot>` row shows
+  in the middle, and `sparkline` is a small chart. Ring width, gap and track
+  color are tokens.
+- `.heatmap-chart` draws a `<figure>`'s data table as a grid of cells shaded
+  from the lowest value to the highest, with the row headers beside it, the
+  column headers below and a scale naming the lowest and highest cells. A
+  tooltip follows the pointer or the arrow keys from cell to cell. `values`
+  writes each cell's text on it in black or white, whichever reads on the
+  shade; `data-label` shortens or hides a header on the grid; `data-min` and
+  `data-max` fix the scale.
+- `.radar-chart` draws a `<figure>`'s data table as shapes on spokes from a
+  shared middle, one spoke per row clockwise from the top and one shape per
+  series, with each row's label past its spoke, a legend, and a tooltip that
+  follows the pointer round the chart or the arrow keys. `area` fills the
+  shapes, `points` marks each value, and `sparkline` is a small chart.
+- `.pie-chart` draws a `<figure>`'s data table as slices of a whole,
+  clockwise from the top, with a legend of each row's cell and share and a
+  tooltip that follows the pointer round the pie or the arrow keys. `donut`
+  cuts a hole and shows a `<tfoot>` total in it, `values` writes each share
+  on its slice, and `sparkline` is a small pie. Further value columns show in
+  the tooltip.
+- `.bar-chart` draws a `<figure>`'s data table as horizontal bars from zero,
+  with each row's label beside it, a legend, and a highlight band and tooltip
+  that follow the pointer or the up and down arrows. The plot grows with its
+  rows. `stacked`, `split`, `track`, `values` and `sparkline` vary it: `values`
+  writes each cell from its bar's base, running past a short bar, and a
+  stacked, split row on a track with `data-max` is a meter. It shares the column chart's runtime and markup, and
+  the bars grow leftwards in a right-to-left page.
+- Line, column and bar charts: a tap on a touch screen shows the tapped row
+  instead of the first, keeps it when the finger lifts, and hides it when the
+  page scrolls.
+- `.column-chart` draws a `<figure>`'s data table as columns from zero, one
+  group per row, with x labels, a legend, and a highlight band and tooltip that
+  follow the pointer or the arrow keys. `stacked`, `fade`, `track` and
+  `sparkline` vary it, and negative values hang below zero. It shares the line
+  chart's runtime, markup and accessibility; the table stays as the text
+  alternative and the no-JavaScript fallback.
+- Line chart: `stacked` draws each series on the total of the ones before it
+  and fills the band between them, from a zero baseline. The tooltip still
+  shows each cell, and an empty cell breaks the series above it. The docs add chart card layouts with a period switch, a
+  compact chart and a side sparkline.
+
+- Message component: `.message` lays out one message in a conversation with an
+  optional `.message-avatar`, `.message-header` and `.message-footer` around a
+  `.message-bubble`. `end` moves a message to the sender's side,
+  `.message-group` stacks consecutive messages and joins their corners, and
+  `.message-bubble.outlined` holds attachments. CSS only.
+- Accordion component: `.accordion` stacks native `<details>` items as joined
+  tiles with a turning chevron. A shared `name` keeps one item open, and
+  opening animates where the engine can transition to `auto` height. CSS only.
+- Data table component: `.data-table` wraps a native `<table>` in a scrolling,
+  outlined container with a sticky header row. `numeric` aligns number columns,
+  `dense` shortens rows, `aria-sort` on a header draws its sort arrow, and a
+  checked checkbox in the first cell selects the row. The page owns sorting.
+  CSS only.
+- Avatar component: `.avatar` shows a person as a circular image, initials or
+  icon in `small`, default and `large` sizes. `.avatar-group` overlaps avatars
+  with a surface ring. CSS only.
+- Skeleton component: `.skeleton` draws placeholder boxes, `text` lines and
+  `circle` shapes with a shimmer that stops under reduced motion. CSS only.
+- Empty state component: `.empty-state` centers an icon or illustration, a
+  heading, supporting text and an `.empty-state-actions` row. CSS only.
+- Popover component: `.popover` styles a native `[popover]` panel opened by a
+  `popovertarget` button and places it with CSS anchor positioning, below the
+  button by default or with `top`, `start` and `end`, flipping to stay on
+  screen. Use it for toggletips and small action panels. CSS only.
+- Stepper component: `ol.stepper` numbers a fixed sequence of steps.
+  `aria-current="step"`, `complete` and `invalid` mark each step's state, and
+  the complete and invalid states are spoken through translatable tokens.
+  `vertical` stacks the steps and takes a `.stepper-content` panel. CSS only.
+- Drop zone component: `.drop-zone` stretches a native file input over a large
+  labelled target. The Forms behavior marks a drag with `dragover` and lists
+  each chosen file's name and size in `.drop-zone-files`.
+- Text fields take a trailing `.icon-button.suffix` as a clickable control.
+  `password-toggle` on that button shows and hides the password and reports
+  its state with `aria-pressed`. `input.otp` draws one native input as a row of
+  one-time code cells.
+- Menu `contextMenu` option, also set by `data-context-menu` on the trigger:
+  the trigger is a region, and its menu opens at the pointer on right-click,
+  long-press, the menu key or Shift+F10, flipping to stay on screen.
+- Timeline component: `ol.timeline` marks each event with a dot joined to the
+  next by a line, or with a leading icon in a tonal circle. CSS only.
+- Stat component: `dl.stats` lays out key figures as wrapping tiles, with a
+  `.stat-change` line that takes `up`, `down` and `negative`. CSS only.
+- Tree component: `ul.tree` nests lists of native disclosures and links with
+  guide lines, turning chevrons and an `aria-current` row. It takes no tree
+  role. CSS only.
+- Rating component: `fieldset.rating` draws native radios as stars that fill
+  up to the choice and preview on hover; `.rating[role="img"]` with
+  `--md-comp-rating-value` shows a score, halves included. CSS only.
+- Command palette component: `dialog.command-palette` with a search input and
+  a list of link or button commands. `CommandPalette` filters by text and
+  `data-keywords`, moves the active command with the arrow keys, runs it with
+  Enter and opens on Ctrl+K or Command+K. `AutoInit()` starts it.
+- `<kbd>` is drawn as a keycap; an outer `<kbd>` around a combination stays
+  plain.
+- `.line-chart` draws a `<figure>`'s data table as smooth SVG lines with x
+  labels, a legend, and a cursor and tooltip that follow the pointer or the
+  arrow keys. `area`, `fade`, `sparkline` and `<th class="dashed">` vary it.
+  The table stays as the text alternative and the no-JavaScript fallback.
+- `.scroll-area` styles native scrollbars with theme-aware colors and thin
+  sizing, with a WebKit fallback and system scrollbars in forced-colors mode.
+- `.shape-*` cuts images, videos, buttons, and other elements to twenty
+  rounded shapes after the M3 Expressive shape library, such as
+  `.shape-scallop-6`, `.shape-spark`, and `.shape-bloom-4`. Focused shapes draw
+  their focus ring inside the edge. CSS only.
+- Frosted glass for floating surfaces. `--expressive-glass: true` on `:root` or
+  a wrapper turns it on. `--expressive-glass-blur` (default `16px`) sets the
+  frost thickness, and `--expressive-glass-opacity` (default `72%`) sets how
+  much of the surface color is kept. Sass `$expressive-glass`,
+  `$expressive-glass-blur`, and `$expressive-glass-opacity` change the defaults,
+  and `--expressive-glass: false` turns the effect off within a region. Surfaces
+  turn solid when the user prefers reduced transparency or more contrast.
+- The docs site opens on a landing page with a features overview, a live
+  code demo and the installation guide. Ctrl+K, Command+K or the app bar's
+  search button opens a search of every documentation page. Pages now carry
+  a meta description and Open Graph tags, and the site publishes
+  `sitemap.xml` and `robots.txt`.
+
+### Changed
+
+- The default theme seed is Mist Iris (`#c6a0f6`). The docs picker uses the
+  same default for its initial value and Reset action. Set `--md-source` or
+  Sass `$md-source` to retain an application's existing brand color.
+- The agent skill workflow is version 0.9.0 and costs fewer tokens to read.
+  Sub-skill scope now lives only in each frontmatter description, without
+  repeated "When to use" sections. Generated component guides no
+  longer repeat the page description or the generic rule and documentation
+  notes, and the theming, usage, dashboard and charts guides link to the
+  reference that owns a rule instead of restating it. Each sub-skill says when
+  to read each reference, long references open with a contents list, and the
+  design guide links its dated component reviews directly. A new delegation
+  reference explains how to split a large audit across subagents and merge
+  their findings. The install and runtime guides end with checklists, and the
+  charts guide asks for honest scales and labelled sample data. Component
+  guides drop the source list and the two notes every guide repeated; the
+  root skill states the rule-ID convention once and tells agents to treat
+  page content and tool output as evidence, not instructions. Performance
+  measurement moved from the design guide into its own reference.
+
+### Fixed
+
+- A focused line, column, bar or pie chart no longer cancels Escape when its
+  tooltip is already hidden, so a dialog or sheet around the chart can close.
+  Pressing a chart's plot away from its marks focuses it without showing the
+  first row's tooltip; keyboard focus still shows it.
+- A drawn chart's hidden data table no longer makes a narrow tile or its page
+  scroll. The table keeps a fixed 1px layout, as the heatmap's already did,
+  and hangs up from the figure's bottom edge, so its rows cannot add overflow
+  below it.
+- The line chart docs' chart cards pad their stat and chart off the card's
+  border.
+
+## [0.12.0] - 2026-10-01
+
+### Added
+
+- Utility classes for shrinking flex and grid children, scrolling or clipping
+  overflow, logical inline spacing and text alignment, and text wrapping.
+  Physical spacing and alignment classes retain their existing behavior.
+- `.visually-hidden-focusable` hides skip links and other content until the
+  element or a descendant receives focus. Use it independently of `.visually-hidden`.
+
+### Fixed
+
+- Spacing output and documentation omit padding-auto classes, since CSS does
+  not accept `auto` for padding. Margin-auto helpers remain available.
+- Carousel preserves an active mouse drag when delayed resize work completes.
+- Snackbar ignores flick velocity after a pause of 100ms or more before release;
+  dragging past the distance threshold still dismisses it.
+- Tooltip supports `open()` in its public TypeScript declarations and honors
+  `open(true)` without requiring hover or focus.
+- NavigationRail leaves Escape to a nested component that already handled it.
+  Its own Escape collapse restores focus to the rail toggle while preserving
+  outside focus and focus moved by close callbacks.
+- Menu respects `closeOnClick` inside open and closed shadow roots, preserving
+  submenu navigation, outside dismissal, and touch scrolling.
+- Multiple FormSelect options with the same value can be selected and
+  deselected independently, matching their native option state.
+- Chips supports programmatic addition without an editable input and accepts
+  numeric ID `0` during initialization and addition. An empty autocomplete menu
+  does not prevent adding a custom chip.
+- Autocomplete keeps its open state synchronized with its Menu, accepts
+  preselected IDs before data loads, and bubbles selection changes to form
+  listeners. Chips lets an open suggestion menu handle Enter.
+- Timepicker reloads edited host values when opened and cancels obsolete clock
+  updates, so delayed transitions cannot overwrite newer edits or update a
+  destroyed instance.
+- Datepicker honors custom parsers during initialization and reopening, rejects
+  reversed range edits through every input path, and preserves an empty
+  single-date selection after clearing.
+- Each Datepicker range input emits its own change event. Generated date inputs
+  opt out of AutoInit so repeated initialization cannot create duplicate pickers.
+- Component `init()` methods return an empty array for empty element collections,
+  matching their TypeScript return types.
+- Datepicker can reopen a range when only its end date is set. Clearing
+  either endpoint preserves the other and removes incomplete range shading.
+- A cancelled Snackbar swipe cannot carry its velocity into the next gesture.
+- Bottom and side sheets recognize a recent flick when the release coordinates
+  match the last pointer move, while paused or reversed short drags stay open.
+- Carousel preserves ordinary button and link clicks inside slides while keeping
+  mouse dragging available, including in swipeable tab panels.
+- Chips autocomplete preserves the query while filtering and clears it after
+  an item is selected.
+- Destroying a Timepicker cancels pending automatic submission, so an old
+  instance cannot overwrite a replacement input value.
+- Datepicker and Timepicker confirmation buttons invoke their callbacks once
+  per Enter press. Both TypeScript option interfaces accept `autoSubmit: false`.
+- Closing a Menu preserves focus on an outside input or another control.
+- Docked Datepicker and Timepicker popovers account for their positioning
+  parent, including `.field` wrappers and scrolled containers.
+- Destroying Chips also destroys its owned Autocomplete and Menu.
+- Tooltip teardown restores authored rich content and preserves existing
+  description associations, allowing the same content to be initialized again.
+- Snackbars can reuse an element supplied through `snackbarId` without deleting
+  it or retaining callbacks and controls from an earlier instance.
+- A vertical touch swipe that starts on a carousel scrolls the page again, and
+  pinch-zoom works over it. The carousel tracks no longer restrict
+  `touch-action`.
+- In Firefox the top app bar is `surface` at rest instead of
+  `surface-container`. The scroll fill now runs only where `animation-timeline`
+  is supported.
+- `.slider.stops` draws its dots. Each dot sits at a step position on the
+  active track, including centered and right-to-left sliders. Vertical and
+  two-handle sliders show no dots.
+- In Firefox an indeterminate `<progress class="progress">` shows its track and
+  a moving 40% bar, which stays still under reduced motion.
+- In Firefox a date input with a Datepicker shows its value. The formatted
+  overlay only applies in engines that render it.
+- Mouse drag moves the carousel track again in the horizontal full-screen
+  layout and in `.uncontained.snap`. Snapping used to pull the track back on
+  every move.
+- Editing or clearing a Datepicker `<input type="date">` with the keyboard
+  updates the formatted date painted over the field in Chrome and Safari.
+  After the field lost focus it used to show the previous date.
+- Clicking a Datepicker date input no longer opens the browser's date picker on
+  top of a visible Datepicker calendar (`openByDefault` or `container`). When
+  the calendar is hidden, the default, the browser picker still opens.
+- Leading `.prefix` and trailing `.suffix` icons stay visible on a Datepicker
+  date input in Chrome and Safari. The input's filled background used to cover
+  them.
+- `.slider.stops` puts each dot at `min` plus a whole number of steps, so a
+  `step` that does not divide the range no longer spreads the dots over the
+  whole track. With no `step`, `step="any"`, or a zero or negative step, the
+  slider shows no dots. Dots follow the range input's direction and leave the
+  inset icon uncovered.
+- `Slider.destroy()` removes the custom properties it set on the input and its
+  host, so stop dots and the track fill no longer stay painted. Inline values
+  set before init come back.
+- A `<header>` that holds only a `nav.tabs` is no longer styled as a top app
+  bar, so it no longer sticks to the top of the page or takes the app bar fill.
+- Medium and large app bars no longer send the page back to the top when they
+  collapse. A short or slow scroll near the top used to snap back and leave the
+  bar switching between sizes. The bar now collapses once the page has
+  scrolled by the height it gives up, and expands when the page returns to the
+  top of the bar.
+
+### Changed
+
+- The ExpressiveCSS skill bundles the starter page and the five layout
+  templates under `assets/templates/`, and the Install and Design guides point
+  to them. The Install guide gives a plain `npm install` command, and its
+  minimum page no longer puts the page heading in an app bar without
+  destinations.
+- Skill guides put their steps under their own headings instead of under
+  "Do not use when". The framework contribution path moved to
+  `references/contributing.md`.
+- Component guides list the API reference subsections they leave out. Their
+  examples use real link targets, and menu actions are buttons. The Buttons
+  reference calls `circle` a round common button and points icon buttons to
+  `.icon-button`.
+- Documentation examples no longer use `href="#!"` in copyable code. Menu,
+  split-button, app-bar and tooltip actions are `<button type="button">`,
+  and code samples link to realistic paths. Live navigation demos on the docs
+  site keep `#!`. The app-bar Search icon is a button. The API reference drops
+  rendered demo text that had been copied into it, and the Lightbox guide
+  includes its options and methods.
+- The footer partial no longer carries sticky-footer rules. Their nested
+  `:has()` selector was invalid, so browsers had always dropped them. The
+  Footer page now gives the two rules to add yourself, as the API reference
+  already did.
+- The Auto Init page and the API reference list every component `AutoInit()`
+  starts. They add AppBar and ExpandingCard, give Cards its real selector, and
+  list both picker spellings, `.datepicker, .date-picker` and
+  `.timepicker, .time-picker`. Both name all eight
+  behaviors the bundle starts on import, including Dialogs, BottomSheets and
+  SideSheets, and call the range control Slider instead of Range.
+- Documentation code samples match their demos and the current framework. The
+  Date picker and Time picker samples select `.date-picker` and `.time-picker`,
+  the Slider samples and the M3 guidelines use `Expressive.Slider`, and card
+  samples drop the unstyled `supporting-text` class. The Grid, circular image,
+  character counter, snackbar dismiss and full-screen dialog samples now match
+  the demos next to them. The Scrollspy sample uses the canonical
+  `hide-on-compact-only` instead of the legacy `hide-on-small-only` alias.
+- Documentation no longer describes removed classes or markup. Typography
+  names `body-large`, `body-medium` and `body-small`, and Select describes the
+  `.field` wrapper the plugin reuses or creates instead of `.select-wrapper`.
+  Tabs no longer mentions `tabs-horizontal`, and Tooltips no longer says the
+  plugin adds `.material-tooltip`. Grid offsets use the Compact through
+  Extra-large breakpoint names.
+- Getting started lists `fonts/` and `modular.mjs` in the `dist/` tree and
+  the minified files in the project tree. Its README link opens the "Reduce
+  page downloads" section.
+- On the docs site, the Start navigation item opens the landing page again.
+  Slider demos keep their stop dots, and carousel demo links no longer point
+  at anchors that do not exist.
+
 ## [0.11.0] - 2026-09-30
 
 ### Added
@@ -94,7 +476,7 @@ the format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - **Offline design context for the ExpressiveCSS skill.** The generator now
   copies the hard rules, window-size tables, component chooser, screen recipes,
-  anatomy cheat sheet, and Materialize name map from `m3-guidelines.md` into
+  anatomy cheat sheet, and retired name map from `m3-guidelines.md` into
   `skills/expressivecss/references/design-rules.md`, and the root, Design,
   Usage, and Install guides route to it. JavaScript component guides inline the
   options table and method names from `llm.md`. The Install guide carries a
@@ -703,7 +1085,7 @@ semantics sweep keeps rendering — nothing warns at runtime — so each
   the same promise with no keyboard model behind it. `semantics.json` records
   the rejection.
 
-  **Migration.** `.searchbar`, the pre-1.0 Materialize navbar search field,
+  **Migration.** `.searchbar`, the pre-1.0 navbar search field,
   is now an alias of `.search-bar` and moves out of `forms/_input-fields.scss`
   into `components/_search.scss`. Old markup keeps working and picks up the M3
   container; `tests/m3-naming.test.js` holds the alias to every rule.
@@ -1049,7 +1431,7 @@ semantics sweep keeps rendering — nothing warns at runtime — so each
   `height` above and leave `full-screen` off.
 
 - **The coverflow carousel layout is gone.** `.coverflow` was the 3D
-  perspective tween inherited from the vendored MaterializeCSS source, and
+  perspective tween inherited from the older source, and
   Material 3 defines it at no layout and no size. It hand-wrote a momentum
   simulation the browser already performs — velocity smoothing over a
   `Date.now()` delta, exponential-decay easing toward a target, modular index
@@ -1216,7 +1598,7 @@ semantics sweep keeps rendering — nothing warns at runtime — so each
   instead of the spec's 56. Keyed on the shared `$icon` list now, the way
   `_buttons` and `_toolbar` already were.
 - **Five more tokens were declared or referenced but not both**, found by the
-  new check below. The time picker's AM/PM buttons referenced Materialize's
+  new check below. The time picker's AM/PM buttons referenced retired
   `--btn-padding` and `--btn-border-radius`, which no longer exist — the
   declarations were invalid at computed-value time, which does *not* fall back
   to the rule underneath, so the padding rendered as 0 while a base button rule
@@ -1597,7 +1979,7 @@ LLM-facing documentation, and the docs site's own templates.
 ### Fixed
 
 - **`llm.md` taught classes that do not exist.** It is the markup contract other
-  tools and models read, and several sections still carried Materialize-era
+  tools and models read, and several sections still carried retired
   names the Material Design 3 rewrite removed. Each replacement was verified
   against `dist/css/expressive.css` and `src/ts`:
   - `.btn-floating`, `.btn-large` and `.btn-small` (16 references) — a FAB is
@@ -1680,7 +2062,7 @@ guidelines document. No breaking changes.
 
 ## [0.5.0] - 2026-08-19
 
-The release that finishes moving the vendored Materialize surface onto Material
+The release that finishes moving the older component set onto Material
 Design 3 Expressive. Components with no M3 counterpart are gone, several were
 renamed to their M3 names, and the color layer now carries the full role set.
 Pre-1.0, so the breaking changes below are not gated behind a deprecation cycle
@@ -1765,7 +2147,10 @@ are no compatibility aliases.
 - `.tabs` nested in a header or app bar as a secondary row. `.tabs` is a
   standalone component; the `.tabs.transparent` app bar variant is gone with it.
 
-[Unreleased]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.11.0...HEAD
+[Unreleased]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.13.1...HEAD
+[0.13.1]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.13.0...v0.13.1
+[0.13.0]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.12.0...v0.13.0
+[0.12.0]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.10.1...v0.11.0
 [0.10.1]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.10.0...v0.10.1
 [0.10.0]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.9.1...v0.10.0

package/README.md

@@ -4,7 +4,7 @@ ExpressiveCSS is a Material Design 3 front-end framework built with Sass and
 TypeScript. It provides theme tokens, layout and utility classes, styled form
 controls, and JavaScript components in browser, ES module, and CommonJS builds.
 
-> ExpressiveCSS version `0.11.0` is under active development.
+> ExpressiveCSS version `0.13.1` is under active development.
 
 Documentation: [www.expressivecss.com](https://www.expressivecss.com)
 
@@ -326,6 +326,42 @@ After building, run `node --test tests/selective-builds.test.js`. It records raw
 gzip, and Brotli sizes in `.cache/selective-builds/sizes.json`. The browser suite
 records font requests and full/selective screenshots separately in that directory.
 
+### Frosted glass
+
+Floating surfaces can blur the page behind them. The effect is off by default.
+Turn it on in CSS for the whole page or for one region:
+
+```css
+:root {
+  --expressive-glass: true;
+  --expressive-glass-blur: 16px;    /* frost thickness */
+  --expressive-glass-opacity: 72%;  /* share of the surface color kept; 100% is solid */
+}
+```
+
+The blur and opacity lines are optional and show the defaults. Set
+`--expressive-glass` on `:root` or on an element that contains the surfaces. The
+browser reads the value from a surface's parent, so setting it on the surface
+itself has no effect. `--expressive-glass: false` turns the effect off again inside
+a region.
+
+Sass builds can turn glass on by default and change the default values. The CSS
+properties still override these settings:
+
+```scss
+@use "@expressivecss/expressive/src/sass/expressive" with (
+  $expressive-glass: true,
+  $expressive-glass-blur: 16px,
+  $expressive-glass-opacity: 72%
+);
+```
+
+The effect applies to menus, tooltips, dialogs, bottom and side sheets, the
+snackbar, the navigation bar and rail, toolbars, and the search view. Grouped menus
+and a modal navigation rail keep a solid surface. The rail would otherwise clip its
+own scrim. Users who request reduced transparency or more contrast in their system
+settings see solid surfaces. The switch uses CSS style queries.
+
 ### Themes
 
 ExpressiveCSS uses the `theme` attribute on the root element: