@fluid-theme/core 0.4.3 → 2.1.0

package/AGENTS.md

@@ -1,32 +1,9 @@
-# AI Agent Instructions
+# AI agent instructions: The Fluid Theme
 
-This project uses **The Fluid Theme** — a semantic CSS design system. If you are an AI coding assistant, read the following files to understand project conventions:
+This file is a pointer. The instructions for every agent live in one place:
 
-## Essential Reading
+- **[`CLAUDE.md`](https://github.com/Agile-Media-Agency/the-fluid-theme/blob/main/CLAUDE.md)**: rules, gates, key files and the docs table. Agent-neutral despite the name.
+- **[`_docs/STATUS.md`](https://github.com/Agile-Media-Agency/the-fluid-theme/blob/main/_docs/STATUS.md)**: what the theme is now (one lean base, a child theme per site, about 20 knobs on `:root`). It wins over every older doc.
+- How every project is built: `Agile-Media-Agency/the-fluid-stack` `playbook/README.md`.
 
-1. **`fluid-agent-kit/skills/css-conventions.md`** — CSS layer order, design tokens, logical properties, data attributes
-2. **`fluid-agent-kit/skills/accessibility.md`** — Non-negotiable accessibility standards
-3. **`fluid-agent-kit/skills/ux-rules.md`** — 12 behavioral rules for interactive components
-4. **`fluid-agent-kit/skills/image-optimization.md`** — Responsive images, lazy loading, focal points
-
-## Key Rules
-
-- Use **semantic HTML** with data attributes — not utility classes
-- Use **CSS custom properties** (tokens) for all values — never hardcode `16px` or `#333`
-- Use **logical properties** — `margin-block-start` not `margin-top`
-- Use **`<dialog>`** for modals — not `<div role="dialog">`
-- **Never remove focus outlines** — restyle if needed
-- **Respect `prefers-reduced-motion`** in all animations
-- Every `<img>` needs `alt`, `width`, `height`, and `loading="lazy"` (except above-fold)
-
-## Full Documentation
-
-- `_docs/DEVELOPMENT.md` — Master development guide
-- `_docs/UX-BEHAVIOR-SPEC.md` — Complete UX specification (18 sections)
-- `_docs/images-guide.md` — Image optimization guide
-- `_docs/reference/components.md` — Component API reference
-- `_docs/reference/tokens.md` — Design token reference
-
-## Framework Version
-
-0.4.0
+Presets, palettes, `data-preset`, `data-palette` and `_docs/reference/tokens.md` are superseded (Pass 0, 2026-10-23); do not write code for them. The version is the latest git tag; never write or bump it by hand. Pass 1 (draft PR #75, step 8) plans to replace this file and `CLAUDE.md` with one `AGENT.md`.

package/CHANGELOG.md

@@ -5,10 +5,522 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.4.3] - 2026-03-24
+## [2.1.0] - 2026-11-01
+
+### Added
+- feat(v2): package Swiss and Gallery child themes, 1.x migration guide, showcase re-vendor, and site auto-updater
+
+
+## [2.0.0] - 2026-10-30
+
+### Breaking
+- **Base v2 typographic default:** body text moves to fluid `17–20px` (was `16–18px`) on a `pow(var(--type-ratio), n)` scale; default stacks become Newsreader (display/headings) over Schibsted Grotesk (body/UI) with system fallbacks when no font stylesheet is linked; default `--accent` becomes deep oxblood `oklch(42% 0.15 22)` on warm paper `--neutral-tint`; `--radius-card`, `--radius-control` and `--shadow-style` default to `0`; `--motion-base` defaults to `320ms`; cards are open without hover lift; `--color-border-strong` is ink; `--hero-headline-size` no longer sets a `:root` default (still honoured when set). See `_docs/migrations/from-1x.md`.
+- **Inverted `.nav` by default:** `.nav` renders in the opposite scheme of the page (dark bar on a light page, light bar on a dark page) with a border hairline only when `[data-sticky]` is present. Add `data-bg="plain"` on `.nav` to keep a page-coloured bar.
+
+### Added
+- **New `:root` knobs:** `--font-display`, `--type-ratio`, `--text-min`, `--text-max`, `--weight-display`, `--weight-heading`, `--h1-size`, `--h2-size`, `--h3-size`, `--display-max`, `--measure`, and `--rail`.
+- **Layouts & typography:** `.content-grid` (`content`, `wide`, `full` bleed tracks), `.section__head` with ink rules, hang-line `.gallery` (with Firefox intrinsic-ratio fallback), `.display` headlines and `assets/js/fit-text.js` (`data-fit` column/measure fitting), and section bands (`tinted`, `accent`, `inverse`, `accent-strong`).
+- **Opt-in self-hosted fonts (`dist/fluid-fonts.min.css`, export `./fonts`):** Newsreader + Schibsted Grotesk variable WOFF2 subset with capsize metric-matched local fallback faces (`Newsreader Fallback`, `Schibsted Fallback`) across regular, bold, italic, and bold-italic cuts.
+- **Fluid Zero (`dist/fluid-zero.min.css`, export `./zero`):** ~2.4 KB gzip alternate base (reset, `:root` colour/type roles, and native HTML elements) sharing core's `@layer` order and knob names.
+- **Article TOC module (`dist/fluid-toc.min.css`, export `./toc`, plus `assets/js/toc.js` and `assets/js/toc-build.mjs`, export `./toc-build`):** server- or client-built H2/H3 table of contents with scroll spy, inline fold, sticky rail, and two-row mobile bottom dock (`data-toc="rail dock"`).
+- **Navigation modes (`dist/fluid-nav.min.css`, export `./nav`):** opt-in compact `"+"` popover (`data-nav="compact"`), drop panel (`data-nav="compact drop"`), icon mode (`data-nav="icon"`), and sticky-links bar (`data-sticky="links"`), while core keeps one-line tracking squeeze and balanced-row wrapping within the 24,500 B gzip core budget.
+- **1.x compatibility bundles:** `dist/fluid-legacy-1x.css` (export `./legacy-1x`) and single-file `dist/fluid-1x.min.css` (export `./1x`) restoring 1.x knob defaults on 2.0 core.
+- **Verification gates:** `scripts/toc-check.mjs` (`npm run test:toc`), `scripts/nav-check.mjs` (`npm run test:nav`), `npm run test:zero`, `visual-scan.mjs` `ALIGN`, `SHIFT` and `RATIO` checks, child-theme `--theme` flags on `visual-scan`, `axe-check`, and `focus-check`, and unfocused-vs-focused indicator delta measurement in `focus-check.mjs`.
+
+### Changed
+- **npm Trusted Publishing:** `.github/workflows/release.yml` publishes `@fluid-theme/core` publicly via GitHub OIDC (`id-token: write`, Node 24, `npm@^11.5.1`) with a `workflow_dispatch` publish-only recovery path.
+
+
+## [1.1.10] - 2026-10-29
+
+### Fixed
+- ci(site): /status/ smoke test without curl | grep -q (pipefail)
+
+
+## [1.1.9] - 2026-10-29
+
+### Fixed
+- feat(site): /status/ and /version.json on thefluidtheme.com; footer names the build
+
+
+## [1.1.8] - 2026-10-29
+
+### Fixed
+- CLAUDE.md: a pruned ref leaves the purged objects; gc the Mac Studio clone
+
+
+## [1.1.7] - 2026-10-29
+
+### Fixed
+- Dependabot: drop engines.browsers (an array) so updates run; CLAUDE.md Exceptions
+
+
+## [1.1.6] - 2026-10-29
+
+### Fixed
+- CLAUDE.md: an old clone's gitsync pushed the purged history back
+
+
+## [1.1.5] - 2026-10-29
+
+### Fixed
+- Showcase: skip link and <main> on printsofthemasters and shirtsandsquirrels
+
+
+## [1.1.4] - 2026-10-28
+
+### Fixed
+- Pass 1 step 0: housekeeping
+
+
+## [1.1.3] - 2026-10-28
+
+### Fixed
+- Plan Pass 1: ready to build new sites
+
+
+## [1.1.2] - 2026-10-28
+
+### Fixed
+- chore(starter): take Vite 8 with plugin-react 6 and fix the React starter build
+
+
+## [1.1.1] - 2026-10-28
+
+### Fixed
+- ci(release): PR number is the last #N in the merge subject
+
+
+## [1.1.0] - 2026-10-27
+
+### Added
+- Forms: honeypot and conditional-field rules in core (@layer utilities)
+
+
+## [1.0.5] - 2026-10-27
+
+### Fixed
+- Docs: Fluid truth (audit 2026-10-25, batch F4)
+
+
+## [1.0.4] - 2026-10-27
+
+### Fixed
+- Docs: lessons from domain-landing (child themes, focus gate gap, skip link, fit text, form stopgaps)
+
+
+## [1.0.3] - 2026-10-27
+
+### Fixed
+- Site deploys: job-level concurrency; CLAUDE.md: history was rewritten
+
+
+## [1.0.2] - 2026-10-27
 
 ### Fixed
-- feat: npm package setup — @fluid-theme/core v0.4.2
+- Site: thefluidtheme.com from Cloudflare Pages, built in Actions
+
+
+## [1.0.1] - 2026-10-25
+
+### Fixed
+- Remove Palm Vita student reports from the theme repo
+
+
+## [1.0.0] - 2026-10-24
+
+### Breaking
+The CSS is the same as 0.9.27, which shipped Pass 0 (#73) as a patch by
+mistake; 1.0.0 is that change under the right number. Upgrading from 0.9.26 or
+earlier breaks every site that used the variation system. Full list:
+`_docs/STATUS.md`, "What Pass 0 removed".
+- `data-preset`, `data-palette`, `data-accent` and `data-contrast` do nothing:
+  the 11 presets, 13 palettes, 13 accents and the subdued mode are gone. A site
+  sets about 20 knobs on `:root` instead (a child theme), or it falls back to
+  the base look.
+- Dark mode is one `light-dark()` per colour role: the OS decides and
+  `<html data-theme>` overrides.
+- Accent text uses `--accent-ink` and text on accent fills `--on-accent`
+  (theme issue #49).
+- Removed tokens include `--palette-1..6`, `--theme-dark/light`, the 20-step
+  grey scale and `--shadow-offset-hover`; `--radius-button` and
+  `--radius-input` are now `--radius-control`.
+- Removed files: `settings-panel.css`, `version-badge.css`,
+  `scroll-progress.css`, `themed-images.css`, `fonts/preset-fonts.css`; the
+  preset view-transition keyframes; the bare-button gradient skin.
+- Mapping example: the-fluid-stack PR #105 (its D22) turned 7 looks and 6
+  colours into knob values.
+
+### Changed
+- Release 1.0.0: let the release job read PR labels
+
+
+## [0.9.27] - 2026-10-24
+
+### Fixed
+- Pass 0: strip the variation system, wire the knobs (#73). This is a breaking
+  change released as a patch by mistake: the release job could not read the
+  PR's `major` label. 1.0.0 is the same CSS under the right number.
+
+
+## [0.9.26] - 2026-10-18
+
+### Fixed
+- CLAUDE.md: version is the latest git tag, not a number written here
+
+
+## [0.9.25] - 2026-10-18
+
+### Fixed
+- docs: PRINCIPLES_AUDIT.md, playbook pointer, release-time version rule
+
+
+## [0.9.24] - 2026-10-17
+
+### Fixed
+- Merge pull request #68 from Agile-Media-Agency/claude/dazzling-gates-pjhwg2
+
+
+## [0.9.23] - 2026-10-17
+
+### Fixed
+- Merge pull request #67 from Agile-Media-Agency/claude/dazzling-gates-pjhwg2
+
+
+## [0.9.22] - 2026-10-13
+
+### Fixed
+- v1 planning prompt: research is on main now (#63 merged); start a new draft PR
+
+
+## [0.9.21] - 2026-10-13
+
+### Fixed
+- Merge pull request #63 from Agile-Media-Agency/claude/dazzling-gates-pjhwg2
+
+
+## [0.9.20] - 2026-10-09
+
+### Fixed
+- fix: empty required fields aren't shown as errors before anyone types
+
+
+## [0.9.19] - 2026-10-09
+
+### Fixed
+- fix: content never stays hidden when the reveal script isn't loaded
+
+
+## [0.9.18] - 2026-10-08
+
+### Fixed
+- feat(site): llms.txt, robots.txt and sitemap.xml for AI assistants and search; nav preset name and template contrast fixes
+
+
+## [0.9.17] - 2026-10-08
+
+### Fixed
+- feat(templates): project page for design pros; layouts, reveals and search fit a phone; dropdown trigger contrast
+
+
+## [0.9.16] - 2026-10-08
+
+### Fixed
+- feat(compare): before / after photo slider for trades and renovation portfolios
+
+
+## [0.9.15] - 2026-10-08
+
+### Fixed
+- ci: move actions to Node 24 (checkout@v5, setup-node@v5; release Node 24)
+
+
+## [0.9.14] - 2026-10-08
+
+### Fixed
+- feat(gallery): photo grid + lightbox for portfolio sites
+
+
+## [0.9.13] - 2026-10-08
+
+### Fixed
+- fix(table): tables and fieldsets fit a phone; release skips npm with a warning while NPM_TOKEN is missing
+
+
+## [0.9.12] - 2026-10-08
+
+### Fixed
+- fix(nav): current-page link reads at 4.5:1 under every preset and palette
+
+
+## [0.9.11] - 2026-10-08
+
+### Fixed
+- fix(nav): the narrow layout wraps, the toggle keeps its size, links never run off the page
+
+
+## [0.9.10] - 2026-10-08
+
+### Fixed
+- fix(base): bare checkboxes and radios render as boxes, not full-width bars
+
+
+## [0.9.9] - 2026-10-08
+
+### Fixed
+- fix(a11y): button focus ring survives preset signature shadows
+
+
+## [0.9.8] - 2026-10-08
+
+### Fixed
+- fix(a11y): dark-mode link text reaches 4.5:1
+
+
+## [0.9.7] - 2026-10-08
+
+### Fixed
+- fix(a11y): unreadable follow-the-OS dark mode under most presets; status badges below 4.5:1
+
+
+## [0.9.6] - 2026-09-01
+
+### Fixed
+- Merge pull request #46 from Agile-Media-Agency/claude/fluid-theme-review-1ywkqb
+
+
+> **Note on 0.9.1–0.9.5:** the release workflow generates entries from the merge
+> commit subject, which produced five uninformative "Merge pull request #NN"
+> lines. They have been backfilled by hand from the actual diffs.
+
+## [0.9.5] - 2026-08-31
+
+### Added
+
+- **`data-text-overflow` utility** (`hyphenate` | `break` | `clip` | `normal`) — per-element control over how overlong words are handled. Named to avoid colliding with the layout layer's `data-overflow` (`hidden`/`auto`/`scroll`), which is a different concern.
+- **`data-fit-text` + `assets/js/fit-text.js`** — opt-in shrink-to-fit for display text. Steps font-size down (never up) to a 55% floor until content fits; refits on resize and on `document.fonts.ready`; `window.fluidFitText()` re-runs it after injecting dynamic content. Progressive enhancement — the CSS overflow handling remains the no-JS layer.
+- **`scripts/visual-scan.mjs`** — mechanical layout-defect scanner (page horizontal overflow, per-element text overflow, painted-band seam collapse) across four viewport widths, exit 1 on any flag. `scripts/fixtures/visual-scan-selftest.html` is its deliberately-broken self-test.
+
+### Fixed
+
+- **Heroes had no default vertical padding.** Once a hero's content outgrew `--hero-min-height` (long headlines on narrow screens), content rendered flush against the band's block edges — a CTA could touch the section below it. `.hero:not([data-padding])` now applies `--space-10`; the `data-padding` scale still wins when set.
+- **Serene scaled unrevealed sections up.** `scroll-reveal.css` used `transform: scale(1.02)` for serene's pre-reveal state, making every below-fold section wider than the viewport — horizontal overflow on mobile for any serene page. Now scales down (0.98) with the same settle.
+- `--space-32` was defined but never consumed; `editorial` hardcoded `8rem` instead. Editorial now uses the token.
+
+### Changed
+
+- `assets/js/` is now included in the npm package `files`, so `fit-text.js` and `scroll-reveal.js` reach package consumers instead of existing only in the repo.
+
+## [0.9.4] - 2026-08-31
+
+### Fixed
+
+- **Release workflow never installed dependencies.** `npm publish` triggers `prepublishOnly` → `npm run build` → `import 'lightningcss'`, a devDependency that was never installed on the runner (`ERR_MODULE_NOT_FOUND`). Added `npm ci` (with setup-node's npm cache) before the publish step. This had failed every release since v0.4.3 — see `_docs/HANDOFF.md`; a missing `NPM_TOKEN` secret still blocks publishing.
+
+## [0.9.3] - 2026-08-31
+
+### Fixed
+
+- **`[hidden]` was defeated by components that set `display`.** `.alert { display: flex }` overrode the UA stylesheet's `[hidden] { display: none }`, so success alerts rendered on page load and toggling `hidden` produced no visible change. `reset.css` now enforces `[hidden] { display: none !important }`.
+- **`scroll-margin` sat on links instead of targets.** The rule was on `a[href^="#"]`, where scroll-margin has no effect; anchor navigation buried destination headings under sticky navs. Moved to `:where([id])`.
+- **Rapids' default accent failed WCAG AA.** White-on-coral measured 4.37:1. Tuned `oklch(60% 0.25 25)` → `oklch(57% 0.245 25)`: 4.8:1 on fills and 4.7:1 for coral text on light, still reading as electric coral. All derived tokens recompute automatically.
+
+## [0.9.2] - 2026-08-30
+
+### Added
+
+- **`showcase/`** — three complete, self-contained example sites, each a living demonstration of a different preset and a test bed for the framework: `urbictionary` (rapids), `printsofthemasters` (serene), `shirtsandsquirrels` (cascade). See `_docs/SHOWCASE-SITES.md`.
+
+### Fixed
+
+- **Sections were invisible under every preset.** `scroll-reveal.css` hides `.section:not([data-reveal])` (opacity 0) expecting a `.revealed` class, but `scroll-reveal.js` only observed `[data-reveal]` elements — so any page using `.section` with a preset rendered its sections permanently invisible. The script now observes bare sections too.
+- Added a `@media (scripting: none)` guard so revealed-on-scroll content is never hidden when JavaScript is unavailable, restoring the progressive-enhancement guarantee.
+
+## [0.9.1] - 2026-08-30
+
+Release-automation version bump; no source changes beyond v0.9.0.
+
+
+## [0.9.0] - 2026-08-30
+
+### Added
+
+- **Preset-driven composition (pilot)** — new opt-in `data-arrange="auto"` attribute on `.hero` and `.features`: the active preset now changes the ARRANGEMENT of content, not just its skin. Same HTML recomposes per preset:
+  - Hero: `still` → Swiss left rail with asymmetric void; `serene` → editorial offset (full-width serif headline, copy hangs in the right column); `rapids` → poster split (giant headline left, caption column right); `tsunami` → cinema poster (bottom-anchored massive headline, subheadline as kicker); `flowing`/`stream`/`cascade` → the classic centered stack
+  - Features: `still` → ruled drafting-table grid with hairline gaps; `serene` → single unboxed literary column; `rapids` → dense 4-up pack; `tsunami` → monumental 2-up
+  - Requires flat hero markup (`hero__headline`/`hero__subheadline`/`hero__actions`/optional `hero__media` as direct children); markup using a `hero__content` wrapper is left untouched. Collapses to a single column below 48rem, preserving each preset's alignment.
+- **Default palette + accent per preset** — each water preset now ships a color identity: `still` → mono grayscale (deep slate), `serene` → morandi (dusty lavender), `stream` → fluid (deep teal), `flowing` → fluid (brand blue), `cascade`/`rapids` → bold (vivid purple / electric coral), `tsunami` → tsunami (storm teal). An explicit `data-palette` or `data-accent` always wins. Dark mode swaps to lighter swatches where a light-mode default would be unreadable (still, serene, tsunami).
+- **`data-accent="1-6"` without `data-palette`** — numeric accent swatches now work against the active preset's default family (previously required an explicit palette).
+- **Preset display-scale contrast** — presets now size display type differently: `still` restrained (5xl caps at 2.875rem), `rapids` oversized, `tsunami` massive (hero headlines up to 6.5rem via new `--hero-headline-size` token consumed by `.hero__headline`).
+- **Wider macro-dial ranges** — section rhythm now spans a 4.5× band (32px `still`/`rapids` → 144px `serene` via new `--space-32`/`--space-36` tokens) and content width spans 42rem (`serene` literary column) → 96rem (`stream`) → 100% (`tsunami`).
+- **`fluid-agent-kit/skills/preset-composition.md`** — new agent skill: per-preset layout DNA (canvas, rhythm, hero arrangement, grid density, alignment bias, do/don't) so AI assistants compose pages differently per preset at build time.
+- **`examples/composition.html`** — live demo of preset-driven arrangement with the preset switcher.
+
+### Changed
+
+- **Default accent is now the Fluid brand blue** (`oklch(60% 0.18 240)`), previously a neutral gray. Pages with no `data-preset`/`data-palette`/`data-accent` pick up the brand voice; `data-accent="default"` still gives the neutral gray.
+- `:root` `--accent-subtle` now mixes with `--color-background` instead of `--theme-light`, so bare pages get a correct subtle tint in dark mode.
+- `stream` widens to a 96rem canvas; `still` focuses to a 48rem column.
+
+### Fixed
+
+- `data-palette="fluid"` combined with `data-preset="stream"` or `"cascade"` produced an invalid accent (both presets were missing from the fluid palette's motion-to-color mapping).
+- Removed the redundant `[data-palette][data-accent="1-6"]` mapping block (byte-identical to the new unguarded rules).
+
+## [0.8.3] - 2026-08-28
+
+### Fixed
+- chore(deps-dev): bump brace-expansion from 2.0.2 to 2.1.2 in the npm_and_yarn group across 1 directory
+
+
+## [0.8.2] - 2026-03-26
+
+### Fixed
+- Update .gitignore: ignore terminal sessions
+
+
+## [0.8.1] - 2026-03-25
+
+### Fixed
+- feat: complete preset coverage for all components and sections — v0.8.0
+
+
+## [0.8.0] - 2026-03-24
+
+### Added
+
+- **Preset avatar styles** — Flowing: ocean glow ring; still: fully square (all shapes); cascade: enhanced group lift; rapids: hard shadow on group already present
+- **Preset form styles** — Still: flat no-glow focus (border only); rapids: offset shadow on focus, square fieldset; tsunami: asymmetric fieldset
+- **Preset empty-state styles** — Flowing: soft icon glow; still: square icon container; rapids: hard bordered offset icon; tsunami: asymmetric icon
+- **Preset search-input styles** — Still: square clear button; rapids: offset shadow + square on hover
+- **Preset settings-panel styles** — Flowing: frosted glass drawer panel; still: square FAB and theme cards; rapids: offset FAB hover translate; tsunami: asymmetric drawer
+- **Preset loading/skeleton styles** — Flowing: shadow on skeleton cards; still: square skeleton cards (no rounded corners)
+- **All 6 sections get preset coverage** — Features, CTA, footer, stats, testimonials, and team sections now each have still/flowing/rapids/tsunami/cascade preset-specific styles covering radius, shadow, and hover behavior
+
+## [0.7.0] - 2026-03-24
+
+### Added
+
+- **Preset signature hero gradients** — Every preset now has a unique hero background: flowing (ocean radial), serene (warm cream radial), stream (cool-white sky), cascade (accent waterfall mist), rapids (diagonal energy), tsunami (deep ocean vertical)
+- **Preset sticky nav styles** — All 5 non-flowing presets now have distinct sticky nav treatments: serene (warm cream glass), stream (crisp glass), cascade (friendly glass), rapids (hard neo-brutalist offset shadow), tsunami (dramatic deep shadow)
+- **Preset button interactions** — Serene, stream, cascade, and rapids each have signature button hover/active physics: serene (shadow expansion, no lift), stream (clean 1px lift), cascade (bouncy spring), rapids (hard offset translate)
+- **Stream card hover** — Clean minimal lift (-1px) with crisp shadow
+- **Flowing accordion** — Rounded xl corners + ocean shadow-sm for separated/bordered variants
+- **Flowing modal** — Enhanced backdrop blur (8px, 1.5× saturation) for frosted ocean depth
+- **Flowing toast/alert** — Elevated shadow-md
+- **Flowing dropdown** — Frosted glass menu with backdrop-filter + semi-transparent surface
+- **Flowing popover** — Frosted glass with backdrop-filter + semi-transparent surface
+- **Flowing table** — Rounded xl corners + ocean shadow-sm
+
+---
+
+## [0.6.0] - 2026-03-24
+
+### BREAKING CHANGES
+
+- **`data-motion` renamed to `data-preset`** — The attribute that controls visual personality (fonts, radius, shadows, spacing, color tint) has been renamed from `data-motion` to `data-preset`. Update all `<html data-motion="...">` to `<html data-preset="...">` in your code.
+- **`data-motion` repurposed** — `data-motion` now controls animation speed only: `reduced` | `slow` | `default` | `fast`. It no longer controls visual design.
+
+### Added
+- **New `data-motion` animation speed system** — override animation timing independently of visual preset. Four values: `reduced` (0ms, accessibility), `slow` (1.5× base), `default` (no override), `fast` (0.5× base). `prefers-reduced-motion` always wins.
+- **Separation of concerns** — visual personality (`data-preset`) and animation timing (`data-motion`) are now orthogonal axes. Any combination is valid: `data-preset="rapids" data-motion="slow"` gives the bold Rapids design with deliberate, cinematic motion.
+
+### Migrating from 0.5.x
+
+```html
+<!-- Before -->
+<html data-motion="flowing">
+
+<!-- After -->
+<html data-preset="flowing">
+
+<!-- Optional: add animation speed override -->
+<html data-preset="flowing" data-motion="fast">
+```
+
+---
+
+## [0.5.0] - 2026-03-24
+
+### Added
+- **Complete preset typography** — every `data-motion` preset now has a deliberate font personality:
+  - `serene`: Cormorant Garamond + EB Garamond (contemplative, literary, spa-like)
+  - `stream`: Plus Jakarta Sans (modern SaaS, clean, professional)
+  - `flowing`: Outfit + DM Sans (Fluid brand identity — smooth, geometric, the default)
+  - `cascade`: Nunito (friendly, rounded, approachable — Notion/Slack vibes)
+  - `rapids`: Syne + Space Grotesk (athletic, punchy, high-energy — Stripe/Vercel energy)
+  - `tsunami`: Bebas Neue + Barlow (cinematic, dramatic, commanding — Hokusai wave)
+  - `still` + `trickling`: system-ui (intentionally minimal — Swiss design needs no ornament)
+- **`src/fonts/preset-fonts.css`** — optional Google Fonts file for npm/bundler users. Import to activate all preset typefaces at once.
+- **Light-mode color character** — each preset now applies a subtle hue tint to background surfaces. The same page feels different in every preset, not just in dark mode:
+  - `still` → cool slate (hue 250) — crisp, disciplined
+  - `serene` → warm cream (hue 60) — like aged paper, spa calm
+  - `stream` → clean cool (hue 200) — modern SaaS white
+  - `flowing` → ocean breath (hue 230) — the Fluid brand signature
+  - `cascade` → soft lavender (hue 280) — warm, inviting, playful
+  - `rapids` → warm ember (hue 25) — heat, energy, forward motion
+  - `tsunami` → deep navy (hue 250) — imposing, cinematic
+- **Live preset switcher** on `examples/foundation.html` and `examples/components.html` — click any preset to see the full personality change in real time (typography + color + motion + radius + shadows)
+- **MutationObserver in `fonts.html`** — fonts load instantly when switching presets via JS, not just on page load
+
+### Changed
+- `flowing` (default) now uses Outfit + DM Sans, giving the Fluid brand a distinctive voice rather than falling back to system-ui
+- `rapids` switched from Archivo Black to Syne (more distinctive, athletic) + Space Grotesk body
+- `tsunami` switched from Space Grotesk to Bebas Neue (far more cinematic/dramatic) + Barlow body
+- `cascade` now uses Nunito for both heading and body (pure Nunito is more cohesive than mixed stacks)
+- Light-mode backgrounds are no longer pure white for any preset — each has a hue identity
+
+## [0.4.9] - 2026-03-24
+
+### Fixed
+- chore: final audit — TASK-QUEUE updated, README starter kits section, version consistency 0.4.8
+
+## [0.4.8] - 2026-03-24
+
+### Added
+- **1920w WebP variants** generated for all 18 hero images (77.5% savings: 33.63MB → 7.58MB)
+- `scripts/add-1920w-srcset.mjs` — adds 1920w to existing `<picture>` srcsets
+
+### Changed
+- `index.html` and 11 templates: 47 `<source>` srcsets now include 1920w WebP for large displays
+- `scripts/optimize-images.js` — now skips already-existing output files (idempotent)
+
+## [0.4.7] - 2026-03-24
+
+### Added
+- **Performance benchmarks** (`_docs/PERFORMANCE-BENCHMARKS.md`) — Lighthouse v13 scores: Homepage Perf 100, Foundation Perf 100, Components Perf 88; CLS=0 and TBT=0ms across all pages
+- **`scripts/perf-benchmark.mjs`** — automated benchmark runner
+
+## [0.4.6] - 2026-03-24
+
+### Added
+- **Accessibility audit** (`_docs/ACCESSIBILITY-AUDIT.md`) — axe-core WCAG 2.1 AA audit across Foundation, Components, and Homepage; 0 critical violations
+
+### Fixed
+- Loading spinners: added `role="status"` to all `.spinner` and `.spinner-dots` elements (required for `aria-label` on non-semantic elements)
+- Card ratings: added `role="img"` to `.card__rating` elements (required for `aria-label`)
+- Interactive card demo: removed invalid `role="button"` from `<article>` element
+- Updated `loading.css` usage comment to show correct `role="status"` pattern
+
+## [0.4.5] - 2026-03-24
+
+### Added
+- **React starter kit** (`starters/react/`) — Vite + React 18 starter with live theming demo, drives `data-*` attributes via React state, includes Next.js instructions in README
+
+## [0.4.4] - 2026-03-24
+
+### Added
+- **HTML starter kit** (`starters/html/`) — self-contained CDN-based starter, zero build step, includes nav, hero, features grid, contact form, footer, and full README
+
+## [0.4.3] - 2026-03-24
+
+### Added
+- **First public npm publish** — `@fluid-theme/core@0.4.3` is now live on the npm registry
+- **CDN links active** — jsDelivr and unpkg now serve the package automatically
+- npm account `agilemediaagency` created with `@fluid-theme` organization
+
+### Changed
+- Author email added to `package.json`
 
 
 ## [0.4.2] - 2026-03-21
@@ -157,3 +669,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [0.3.0]: https://github.com/Agile-Media-Agency/the-fluid-theme/releases/tag/v0.3.0
 [0.4.2]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.4.1...v0.4.2
 [0.4.3]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.4.2...v0.4.3
+[0.4.9]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.4.8...v0.4.9
+[0.8.1]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.8.0...v0.8.1
+[0.8.2]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.8.1...v0.8.2
+[0.8.3]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.8.2...v0.8.3
+[0.9.1]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.0...v0.9.1
+[0.9.2]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.1...v0.9.2
+[0.9.3]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.2...v0.9.3
+[0.9.4]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.3...v0.9.4
+[0.9.5]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.4...v0.9.5
+[0.9.6]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.5...v0.9.6
+[0.9.7]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.6...v0.9.7
+[0.9.8]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.7...v0.9.8
+[0.9.9]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.8...v0.9.9
+[0.9.10]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.9...v0.9.10
+[0.9.11]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.10...v0.9.11
+[0.9.12]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.11...v0.9.12
+[0.9.13]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.12...v0.9.13
+[0.9.14]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.13...v0.9.14
+[0.9.15]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.14...v0.9.15
+[0.9.16]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.15...v0.9.16
+[0.9.17]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.16...v0.9.17
+[0.9.18]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.17...v0.9.18
+[0.9.19]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.18...v0.9.19
+[0.9.20]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.19...v0.9.20
+[0.9.21]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.20...v0.9.21
+[0.9.22]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.21...v0.9.22
+[0.9.23]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.22...v0.9.23
+[0.9.24]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.23...v0.9.24
+[0.9.25]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.24...v0.9.25
+[0.9.26]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.25...v0.9.26
+[0.9.27]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.26...v0.9.27
+[1.0.0]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.9.27...v1.0.0
+[1.0.1]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.0.0...v1.0.1
+[1.0.2]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.0.1...v1.0.2
+[1.0.3]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.0.2...v1.0.3
+[1.0.4]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.0.3...v1.0.4
+[1.0.5]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.0.4...v1.0.5
+[1.1.0]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.0.5...v1.1.0
+[1.1.1]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.1.0...v1.1.1
+[1.1.2]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.1.1...v1.1.2
+[1.1.3]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.1.2...v1.1.3
+[1.1.4]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.1.3...v1.1.4
+[1.1.5]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.1.4...v1.1.5
+[1.1.6]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.1.5...v1.1.6
+[1.1.7]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.1.6...v1.1.7
+[1.1.8]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.1.7...v1.1.8
+[1.1.9]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.1.8...v1.1.9
+[1.1.10]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.1.9...v1.1.10
+[2.0.0]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v1.1.10...v2.0.0
+[2.1.0]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v2.0.0...v2.1.0