@expressivecss/expressive 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,52 @@ the format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-08
+
+### Migration from 0.8.0
+
+- Replace card-reveal `.activator` headings and separate close controls with a
+  native `<button type="button" class="card-reveal-trigger" aria-controls="details">`.
+  Its closest card must contain exactly one direct reveal panel with the matching
+  `id="details"`. Use unique IDs for each card and give every trigger an accessible
+  name. The runtime owns `aria-expanded`; legacy triggers no longer toggle panels.
+- Use `<div class="actions">` for card command groups instead of `<nav>`.
+- Review layouts that depend on medium or large app-bar heights and typography;
+  their flexible-bar sizes now follow the mappings listed below.
+- Include `dist/fonts/` beside `dist/css/` when copying the compiled distribution.
+  Sass consumers that load their own fonts can set `$expressive-include-fonts: false`.
+
+### Added
+
+- Community contribution and security policies, required CI, independently versioned MCP releases, and stable-release documentation deployment. Tracks [#134](https://github.com/BaezFJ/ExpressiveCSS/issues/134).
+- **Self-hosted fonts.** The compiled stylesheet ships `@font-face` rules and `dist/fonts/` holds the woff2 files the tokens name: variable Material Symbols (outlined, rounded, sharp), Latin Roboto 400/500, and Latin Noto Sans 400/500. Keep `dist/fonts/` next to `dist/css/`. Sass consumers can set `$expressive-font-path` or `$expressive-include-fonts: false`.
+- **M3 Expressive Button Groups.** Standard groups now redistribute a pressed item's 15% width growth from adjacent items; connected groups support native-button single and multiple selection through `data-selection` and `aria-pressed`. All five sizes support common and icon buttons, explicit child-size overrides, fast-spatial shape motion, 48dp minimum targets, selected color/shape/icon cues, and optional required selection.
+- **M3 Expressive app bar.** `.medium` and `.large` are the flexible bars: 112dp / `headline-medium` and 120dp / `display-small`. A subtitle is `<hgroup>` plus a `<p>` (136dp / 152dp). Titles wrap to two lines. `center` works on all three sizes. The search app bar is a `<search class="search-bar">` in the header. `AppBar` collapses the flexible bars on scroll and opens the related search view when the search field is selected.
+- **ExpressiveCSS design and review skill.** The workflow now uses explicit Implement, Refine, Redesign, Critique, and Audit modes; turns product and brand decisions into Material 3 Expressive components and tokens; covers every reachable state and relevant localization or offline behavior; and closes with responsive browser evidence, an independent finish review when delegation is available, and a non-numeric review matrix with pass, intentional-adaptation, fail, and not-applicable outcomes.
+- **Deterministic skill review evidence.** Critique, Audit, and component-contract checks now use stable criterion IDs, falsifiable claims, criterion-owned evidence rules, a fixture-owned state and responsive-boundary ledger, explicit `Blocked` handling, and exact matched captures collected before Refine or Redesign edits.
+- **Versioned skill contracts and component decisions.** Generated guides now carry framework version, stable component-rule IDs, and source-hash provenance across every contract input. A portable resolver requires a direct dependency, selects one active lockfile, records structured conflicts, and fails closed on ambiguous, malformed, symbolic-linked, or unreadable npm, pnpm, or Yarn metadata. Contract equality follows SemVer precedence, so build metadata does not create a false mismatch. One structured catalogue owns guide extraction and selection guidance for all 46 components.
+- **Behavioral skill evaluations.** Root-only replay cases count exact-path guide reads from tool traces and fail closed on missing, duplicate, unknown, or unevaluated critical invariant IDs. Mutation cases verify no-edit modes, required reads, evidence and event order, fixture-owned states, matched captures, older-version handling, token-based branding, dynamic ARIA, runtime ownership, and scoped MCP claims. Root-skill, case, and replay reads are descriptor-bounded; nested keys and values are capped; matched-capture chronology is bound to the first trusted edit. The runner rejects executable regular-expression assertions. Reports and adapter failures redact credential-shaped keys and values, authorization headers, credential-bearing URLs, and local paths before storage or display.
+- **Bounded MCP evidence.** MCP setup, rule, syntax, and quality steps work independently and report checks performed, evidence sources, inspected and uninspected files, unchecked areas, coverage, blocked checks, and contract compatibility. Static checks detect retired markup, duplicate initialization, missing teardown evidence tied to the initialized variable, raw authored colors, and semantics violations. MCP guide content comes only from its synchronized package data and is checked against the bundled contract; local framework-source contracts affect source provenance but cannot replace package guidance or diverge from its version and source hash. Installed and locked versions outside their direct manifest range are blocked. Missing inputs, failed commands, timeouts, stale or divergent provenance, unresolved contracts, aggregate file limits, and partial static scans block instead of producing a broad pass. Command execution requires an operator allowlist, uses a credential-free environment, and has bounded input and runtime limits. A command timeout still force-kills the process group after SIGTERM.
+
+### Fixed
+
+- Menu cancels superseded transition and deferred event callbacks on reversal and destruction, preserving visibility, focus and end-callback ownership.
+- Menu installs keyboard handlers before moving initial focus, so Escape works immediately after a zero-duration opening.
+- Filled enhanced selects reserve label space so enlarged and multiline RTL/LTR labels do not overlap the selected value.
+
+- Scale transitions now honor reduced-motion preferences, including changes during motion.
+- Expanding-card close cleanup follows the CSS container transition instead of a fixed timer. Reopening, cancellation, native close, and teardown cannot leave stale cleanup closing a new dialog or moving focus.
+
+- Tooltip teardown now cancels pending entry, exit, and animation callbacks.
+- FormSelect retains ownership of its generated Menu during repeated AutoInit, preventing a retained Menu registry entry.
+
+- **Card reveal accessibility.** Reveal panels now use a native `.card-reveal-trigger` button with a verified `aria-controls` relationship, runtime-owned `aria-expanded`, `inert` closed content, Escape handling, and focus return. AutoInit skips incomplete or disabled-only disclosures, and explicit initialization no longer hides a panel when it lacks a usable enabled `type="button"` trigger or exactly one identified direct panel. Closed-panel CSS is activated only after successful runtime setup, so rejected disclosures remain visible without JavaScript-managed state. This is a markup change: legacy `.activator` headings and separate heading-based close controls no longer toggle the panel.
+- **App bar search dialog.** Closing a full-screen search view no longer reopens it when focus returns to the field.
+- **Badge hosts.** Sibling badges on the stacked navigation bar and collapsed rail use logical inset and flip in RTL. Tabs nest a badge in the destination icon.
+- **Card action semantics.** Material 3 card anatomy now uses `<div class="actions">` for command buttons instead of creating a false `<nav>` landmark.
+- **Card layout and state parity.** Elevated, filled, and outlined cards now keep their Material variant elevations through hover, press, drag, and disabled states; dragged and picked-up elevation plus the 16% state layer take precedence over retained hover or active pointer state. Horizontal cards, including directly actionable cards and fixed-size helpers, keep intrinsic or specified heights when expanded and stack below 600px with fixed heights reset to content. Reveal content is no longer capped in browsers without intrinsic-size interpolation.
+- **Nested card disclosure isolation.** Reveal triggers and Escape handling now belong to their closest card, so nested cards—including a complete card inside an outer reveal panel—retain their own disclosure ownership and cannot initialize, open, or close the outer card.
+
 ## [0.8.0] - 2026-08-27
 
 Completes the HTML semantics sweep. Component markup is corrected so that
@@ -1447,7 +1493,8 @@ 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.8.0...HEAD
+[Unreleased]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.6.0...v0.7.0
 [0.7.0-rc.0]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.6.0...v0.7.0-rc.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 is currently at version `0.8.0` and under active development.
+> ExpressiveCSS is currently at version `0.9.0` and under active development.
 
 Documentation: [www.expressivecss.com](https://www.expressivecss.com)
 
@@ -24,15 +24,44 @@ Documentation: [www.expressivecss.com](https://www.expressivecss.com)
 - [Node.js](https://nodejs.org/) 20 or newer
 - npm
 
-Node 22.12 or newer to run the documentation site: that is Astro's own
-requirement, not the framework's, which still builds and tests on 20.
+Use Node 24 for repository development, selected by `.nvmrc`. The framework's
+runtime compatibility range remains unchanged. See [CONTRIBUTING.md](CONTRIBUTING.md)
+for setup, checks, and the community workflow.
+
+## MCP server for AI workflows
+
+This repository includes a local MCP server at `mcp/expressivecss/` that exposes an
+ExpressiveCSS design-to-QA workflow:
+
+- Setup Expert
+- Rules Enforcer
+- Creative Director
+- Page Arcjitect (`page_arcjitect`, with conventional `page_architect` compatibility)
+- Component Syntax Expert
+- Quality Inspector
+
+The MCP entry point is `mcp/expressivecss/server.js`, with sample config in
+`mcp/expressivecss/mcp.json`.
+
+Quick start:
+
+```sh
+cd mcp/expressivecss
+npm ci
+node server.js
+```
+
+To use it with your MCP client, point the command to:
+
+- `node mcp/expressivecss/server.js`
+- or `node ./server.js` from `mcp/expressivecss` as the working directory.
 
 ## Getting started
 
 Clone the repository and install the JavaScript dependencies:
 
 ```sh
-npm install
+npm ci
 npm run build
 ```
 
@@ -43,6 +72,14 @@ dist/
 ├── css/
 │   ├── expressive.css
 │   └── expressive.min.css
+├── fonts/
+│   ├── material-symbols-outlined.woff2
+│   ├── material-symbols-rounded.woff2
+│   ├── material-symbols-sharp.woff2
+│   ├── roboto-latin-400.woff2
+│   ├── roboto-latin-500.woff2
+│   ├── noto-sans-latin-400.woff2
+│   └── noto-sans-latin-500.woff2
 ├── js/
 │   ├── expressive.cjs
 │   ├── expressive.js
@@ -51,7 +88,9 @@ dist/
 └── types/
 ```
 
-Source maps are produced alongside the CSS and JavaScript bundles.
+Source maps are produced alongside the CSS and JavaScript bundles. The
+stylesheet loads fonts from `../fonts/`, so keep `dist/fonts/` next to
+`dist/css/`.
 
 ## Usage
 
@@ -137,8 +176,9 @@ Available npm commands include:
 | `npm run build:js` | Build ESM, CommonJS, and browser bundles |
 | `npm run build:types` | Generate TypeScript declarations |
 | `npm run watch` | Watch Sass and TypeScript sources |
+| `npm run verify` | Build, typecheck, test, check generated data, and verify docs |
 | `npm run typecheck` | Check the TypeScript source without emitting files |
-| `npm test` | Build the ESM bundle and run the test suite |
+| `npm test` | Build all JavaScript bundles and CSS, then run the test suite |
 | `npm run clean` | Remove generated build output |
 | `npm run docs:dev` | Build the framework, then watch it beside the docs server |
 | `npm run docs:build` | Build the documentation site into `_site/` and verify it |
@@ -150,9 +190,9 @@ Run the documentation and smoke-test site:
 npm run docs:dev
 ```
 
-One command from a clean checkout: it builds the framework first, then runs the
-Sass and esbuild watchers alongside the documentation server, so a change to
-either source appears after a browser refresh. Astro prints the URL it binds.
+This builds the framework, then starts the Sass and esbuild watchers alongside
+the documentation server. Refresh the browser to see source changes. Astro
+prints the server URL.
 
 It is the same site published at
 [www.expressivecss.com](https://www.expressivecss.com), authored in
@@ -160,18 +200,20 @@ It is the same site published at
 
 ## Project structure
 
-```text
-src/
-├── sass/        Design tokens, utilities, base styles, and component styles
-└── ts/          Core APIs, behaviors, plugins, and interactive components
-docs/            Documentation site and build smoke test (Astro)
-tests/           Node test runner and jsdom tests
-dist/            Generated distributable files
-```
-
-See [`src/sass/README.md`](src/sass/README.md) for Sass architecture and
-[`src/ts/README.md`](src/ts/README.md) for component conventions and testing
-guidance.
+| Location | Purpose | Tracked? |
+| --- | --- | --- |
+| `src/sass`, `src/ts` | Framework source | Yes |
+| `docs/src` | Astro documentation and examples | Yes |
+| `mcp/expressivecss` | Independently versioned MCP package | Yes |
+| `skills/expressivecss` | Agent guidance and generated component references | Yes |
+| `scripts`, `tests`, `visual` | Generators, verification, and test tooling | Source only |
+| `semantics.json`, `llm.md`, `m3-guidelines.md` | Markup rules, API reference, design guidance | Yes |
+| `SEMANTICS.md`, generated skill/MCP data | Derived files checked for drift | Yes |
+| `dist`, `_site`, visual reports and caches | Build output | No |
+| `.design-sync` | Optional external design previews | Configuration and source only |
+
+See [Sass architecture](src/sass/README.md), [TypeScript conventions](src/ts/README.md),
+and [development notes](docs/development-notes.md).
 
 ## Testing
 
@@ -188,8 +230,9 @@ behavior rather than geometry or visual transitions.
 
 ## Contributing
 
-Keep generated files out of commits, add tests for behavior changes, and run
-both the test suite and type checker before submitting a change. New JavaScript
-components must be exported from `src/ts/components/index.ts`; components that
-support automatic initialization must also be registered in
-`src/ts/components/registry.ts`.
+Start with [CONTRIBUTING.md](CONTRIBUTING.md). Use
+[Discussions](https://github.com/BaezFJ/ExpressiveCSS/discussions) for questions and
+proposals, and [Issues](https://github.com/BaezFJ/ExpressiveCSS/issues) for accepted
+work and reproducible bugs. Read our [governance](GOVERNANCE.md),
+[code of conduct](CODE_OF_CONDUCT.md), [security policy](SECURITY.md), and
+[release workflow](RELEASING.md).