@expressivecss/expressive 0.7.0 → 0.9.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.7.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)
 
@@ -23,17 +23,45 @@ Documentation: [www.expressivecss.com](https://www.expressivecss.com)
 
 - [Node.js](https://nodejs.org/) 20 or newer
 - npm
-- Python 3.14 or newer and [uv](https://docs.astral.sh/uv/) to run the local
-  documentation site
 
-Python is not required to build or use the framework itself.
+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
 ```
 
@@ -44,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
@@ -52,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
 
@@ -138,37 +176,44 @@ 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 |
+| `npm run docs:preview` | Serve what `docs:build` wrote |
 
-Run the local documentation and smoke-test site in a second terminal:
+Run the documentation and smoke-test site:
 
 ```sh
-uv sync
-uv run python docs/app.py
+npm run docs:dev
 ```
 
-Then open `http://127.0.0.1:5000`. The Flask app serves assets directly from
-`dist/`, so changes made by `npm run watch` appear after a browser refresh.
+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), built from `docs/`.
+[www.expressivecss.com](https://www.expressivecss.com), authored in
+`docs/src/`.
 
 ## Project structure
 
-```text
-src/
-├── sass/        Design tokens, utilities, base styles, and component styles
-└── ts/          Core APIs, behaviors, plugins, and interactive components
-docs/            Local Flask documentation and build smoke test
-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
 
@@ -185,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).