diff --git a/packages/design-system/BREAKING-CHANGES.md b/packages/design-system/BREAKING-CHANGES.md
new file mode 100644
index 0000000..24ec1e1
--- /dev/null
+++ b/packages/design-system/BREAKING-CHANGES.md
@@ -0,0 +1,91 @@
+# Breaking Changes
+
+Cumulative log of breaking changes in `@fireflyframework/design-system`, with migration notes for consumers.
+
+For the full per-release history (including non-breaking changes), see [CHANGELOG.md](CHANGELOG.md).
+
+## How to read this file
+
+- Entries are grouped by version, newest first.
+- Every entry states: what changed, why, and the migration path (before / after).
+- Pre-1.0 packages may include breaking changes inside minor bumps; they are still listed here.
+
+## [Unreleased]
+
+_No breaking changes pending release._
+
+## [0.4.0] - 2026-07-21
+
+### `ff-button` host classes — style/color split
+
+**What changed.** The host BEM class changed from a single `ff-button--{variant}` (e.g. `.ff-button--primary`, `.ff-button--secondary`) to two orthogonal classes: `ff-button--{style}` (`solid`/`outline`/`ghost`) plus `ff-button--color-{color}` (semantic palette). The `variant` input's default also changed from `primary` to `solid`. The TS input stays backward-compatible — `variant="primary"`/`"secondary"` are still accepted (soft-deprecated) and remapped to `solid` + the matching color — but consumer **CSS** targeting the old classes no longer matches anything.
+
+**Why.** Flydocs' real usage needs the style axis (solid/outline/ghost) and the color axis (primary dominant, but all semantic colors in use) to combine freely; a single fused variant could not express the inventory's combinations.
+
+**Migration.**
+
+Before:
+
+```scss
+.ff-button--primary { /* … */ }
+.ff-button--secondary { /* … */ }
+```
+
+After:
+
+```scss
+.ff-button--solid.ff-button--color-primary { /* … */ }
+.ff-button--solid.ff-button--color-secondary { /* … */ }
+```
+
+Templates relying on the old default should pin it explicitly: `<ff-button variant="solid" color="primary">` (or keep `variant="primary"` during the deprecation window).
+
+**Refs:** FIR-288, [CHANGELOG.md](CHANGELOG.md) `[0.4.0] · Changed`
+
+### New required peer — `@angular/cdk ^21.2.0`
+
+**What changed.** The package now declares `@angular/cdk ^21.2.0` as a peer dependency. Installs without CDK fail to resolve.
+
+**Why.** `ff-select` (portaled overlay), `ff-dialog-container` (focus trap) and `ff-menu-button` (overlay) are built on the CDK primitives instead of hand-rolled positioning.
+
+**Migration.**
+
+Before:
+
+```jsonc
+// package.json — no @angular/cdk required
+```
+
+After:
+
+```jsonc
+"dependencies": {
+  "@angular/cdk": "^21.2.0"
+}
+```
+
+**Refs:** FIR-291, FIR-292, [CHANGELOG.md](CHANGELOG.md) `[0.4.0] · Changed`
+
+### New required peer — `@fireflyframework/design-system-contract >=0.2.0 <1.0.0`
+
+**What changed.** The contract package becomes a declared peer dependency (it was not one at 0.3.0). Consumers must have `@fireflyframework/design-system-contract@>=0.2.0` installed.
+
+**Why.** The `ff-data-table`/`ff-list` patterns type their public surface against `DataTableContract`/`ListContract`, so the contract is now part of the installed graph rather than a dev-only reference.
+
+**Migration.**
+
+Before:
+
+```jsonc
+// package.json — design-system only
+"@fireflyframework/design-system": "^0.3.0"
+```
+
+After:
+
+```jsonc
+"@fireflyframework/design-system": "^0.4.0",
+"@fireflyframework/design-system-contract": ">=0.2.0 <1.0.0"
+```
+
+**Refs:** FIR-293, [CHANGELOG.md](CHANGELOG.md) `[0.4.0] · Changed`
diff --git a/packages/design-system/CHANGELOG.md b/packages/design-system/CHANGELOG.md
index 5822090..d4617f6 100644
--- a/packages/design-system/CHANGELOG.md
+++ b/packages/design-system/CHANGELOG.md
@@ -7,15 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-21
+
 ### Added
 - `ff-data-table` — composition-tier pattern (composes `ff-checkbox`, `ff-skeleton`, `ff-empty-state`, `ff-icon`, `ff-button`, `ff-select`): typed headers with cell/row/expansion templates, server-side sorting, single/multi selection with a "select all" checkbox, expandable rows, server-side pagination with an optional page-size control, a `caption` input and a `rowLabel` input naming each row's checkbox/expand toggle
 - `ff-list` — composition-tier pattern sharing `ff-data-table`'s selection/pagination/expansion/empty-state model without columns; renders a real `role="listbox"` with a full keyboard contract (arrows, Home/End, Space, Enter) and `role="option"` entries when selection is enabled
 - `FF_NO_RESULTS_CONFIG` / `provideFfNoResultsConfig()`: shared empty-state text configuration for `ff-data-table` and `ff-list`
 - `compareWith` input on `ff-data-table` and `ff-list`: lets selection/expansion membership survive a re-fetch that returns equivalent but non-identical objects, instead of the default reference equality
 - `ariaLabel` input on `ff-checkbox`, applied as `aria-label` on the native input when `label` is empty
+- `ff-badge`: `color` axis (7 semantic colors, takes precedence over `variant`), `dot` status mode, `shape` (`pill`/`square`), size `xs`, and `maxWidth` with an automatic overflow `title` tooltip; new `FfBadgeColor`/`FfBadgeShape` types
+- `ff-button`: the style/color split — `variant` keeps the style axis (`solid`/`outline`/`ghost`) and the new `color` input takes the semantic palette; new `FfButtonColor` type
+- `ff-menu-button` pattern (`FfMenuButtonComponent`, `FfMenuButtonItem`): button-triggered dropdown menu over the CDK overlay
+- `ff-input`: `[ff-input-prefix]`/`[ff-input-suffix]` affix slots, `debounceTime`, `type="search"` with a `search` output, and `labelType` (`default`/`floating`/`hidden`); new `FfInputLabelType` type
+- `ff-toast-container` pattern (`FfToastContainerComponent`, `FfToastItem`): presentational toast stack driven by the consumer's alert service
+- `ff-dialog-container` pattern (`FfDialogContainerComponent` with a CDK focus trap, `FfDialogItem`/`FfDialogResolution`)
+- `ff-select`: rewritten over a portaled CDK overlay — `multiple` with `values`/`valuesChange`, `bindLabel`/`bindValue`, and option/label template directives; new `FfSelectOptionLike`/`FfSelectTemplateContext` types
 
 ### Changed
-- New peer dependency range: `@fireflyframework/design-system-contract ">=0.2.0 <1.0.0"` (required by the `DataTableContract`/`ListContract` additions)
+- **BREAKING:** `ff-button` host classes renamed from `ff-button--{variant}` to `ff-button--{style}` plus `ff-button--color-{color}`, and the `variant` default changed from `primary` to `solid` — see [BREAKING-CHANGES.md](BREAKING-CHANGES.md)
+- **BREAKING:** new required peer dependency `@angular/cdk ^21.2.0` (overlay/focus-trap for `ff-select`, `ff-dialog-container` and `ff-menu-button`) — see [BREAKING-CHANGES.md](BREAKING-CHANGES.md)
+- **BREAKING:** new required peer dependency `@fireflyframework/design-system-contract ">=0.2.0 <1.0.0"` (the `DataTableContract`/`ListContract` additions) — see [BREAKING-CHANGES.md](BREAKING-CHANGES.md)
+- Component tokens are now consumed with a literal fallback instead of declared with defaults (`var(--ff-btn-radius, var(--ff-radius-md))`), so any ancestor scope can override a component token by context; token names are unchanged
 
 ## [0.3.0] - 2026-07-18
 
diff --git a/packages/design-system/package.json b/packages/design-system/package.json
index 191d7d8..be7e706 100644
--- a/packages/design-system/package.json
+++ b/packages/design-system/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@fireflyframework/design-system",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "publishConfig": {
     "registry": "https://npm.pkg.github.com"
   },