@cahyo-dimas/freeday 3.4.0 → 3.5.0

package/CHANGELOG.md

@@ -9,6 +9,49 @@ benar. Perubahan seperti itu ditulis di bawah `### Changed: BREAKING (types)`
 lama → tipe baru, dan cara menyempitkannya — bukan di bawah `### Added`, betapapun aditifnya dari
 sisi kit.
 
+## [3.5.0] - 2026-09-15
+
+**Sebuah angka yang hanya bisa ditemukan dengan membaca stylesheet kit.** `#058` (dari
+`IDU_AI_DOC_SAPB1_CLIENT` dan `IDU_AI_DOC_SAAS`, satu sapuan atas dua konsol) datang dari audit yang
+hasilnya nyaris bersih: tipografi, spasi dan warna tak menyisakan satu pun nilai mentah. Yang tersisa
+cuma media query — dan di situlah dua hal yang sama-sama berakar pada satu kenyataan CSS: `@media`
+tak bisa membaca custom property.
+
+Akibatnya angka breakpoint kit hanya hidup sebagai literal, app mengetik ulang literal itu, dan
+literal yang diketik ulang hanyut. Dua konsol itu menuliskan satu lebar yang sama dengan tiga cara
+(`640px`, `40rem`, `45rem`) untuk satu maksud yang sama.
+
+### Added
+- **`@cahyo-dimas/freeday/media`** — berkas `@custom-media` (`dist/freeday.media.css`), jawaban
+  sisi-CSS untuk apa yang selama ini hanya dijawab `tokens/breakpoints.mjs` di sisi JS. App menulis
+  `@media (--fdy-below-sm)` atau `@media (--fdy-filterbar-stacked)`, bukan literal yang diketik
+  ulang, dan karenanya tak bisa hanyut.
+  Isinya `--fdy-below-*` / `--fdy-from-*` untuk ramp (`sm`·`md`·`lg`·`xl`), plus `--fdy-nav-drawer`,
+  `--fdy-nav-static` dan `--fdy-filterbar-stacked` untuk dua lebar yang bukan anak tangga ramp.
+  **Opt-in, dan tak mengubah apa pun bagi yang tidak memakainya:** `@custom-media` adalah transform
+  PostCSS (`postcss-custom-media`, sudah termasuk di `postcss-preset-env`), jadi app ber-Vite
+  mendapatkannya cuma-cuma dan app tanpa PostCSS tetap menulis literal seperti kemarin. Berkas ini
+  **tidak** ikut `freeday.css` maupun `freeday.bundle.css` — at-rule waktu-build tak punya urusan di
+  stylesheet yang dimuat tiap app — dan tak membawa satu rule pun, jadi meng-import-nya tak berbiaya
+  saat runtime.
+  Di-**generate** dari objek yang sama yang diekspor sisi JS, jadi kedua paruh skala itu tak mungkin
+  berbeda pendapat; yang menjaganya agar tetap sama dengan CSS yang dideskripsikannya adalah dua tes
+  baru di `test/docs.test.mjs`, diverifikasi dengan mutasi.
+- **`breakpoints.filterbar` (640)** — lebar tempat `.fdy-filterbar` menumpuk fieldnya jadi selebar
+  penuh, kini bernama, bukan cuma tertulis di `filterbar.css:45`.
+
+### Changed
+- **640 tetap 640, tapi berhenti jadi angka siluman.** Ia bukan anak tangga ramp (`sm` = 600) dan
+  sengaja tidak dipindahkan: 640 adalah lebar telepon-lanskap yang nyata, dan menggesernya akan
+  me-reflow setiap filter bar di setiap app. Yang salah bukan angkanya, melainkan bahwa satu-satunya
+  cara menemukannya adalah membaca stylesheet kit lalu mempercayai sumber di atas dokumentasi.
+  Menyelaraskan rule app ke `sm` — hal yang wajar dilakukan dari dokumentasi saja — merusak
+  600–640px: fieldnya sudah ditumpuk kit sementara app masih membatasi lebar field `--w-grow`-nya,
+  sehingga field itu terlihat lebih sempit dari tetangganya di tumpukan.
+  Header `breakpoints.css`, komentar `filterbar.css`, `COMPONENTS.md` dan kedua README kini menyebut
+  `nav` **dan** `filterbar` sebagai dua lebar yang bukan ramp, lengkap dengan pita px yang rusak
+  kalau dibulatkan ke anak tangga terdekat.
+
 ## [3.4.0] - 2026-09-07
 
 **Tiga hal yang hanya terlihat setelah sebuah app bertemu telepon sungguhan.** `#057` (dari

package/COMPONENTS.md

@@ -313,10 +313,33 @@ Responsive display: `.fdy-hide-below-sm|md|lg` · `.fdy-hide-above-sm|md|lg`.
 Breakpoints (min-width): `sm` 600 · `md` 960 · `lg` 1280 · `xl` 1920, importable as
 `import { breakpoints } from '@cahyo-dimas/freeday/breakpoints'`.
 
-**`breakpoints.nav` (721) is separate and is the one the shell uses.** `.fdy-app` switches the
-sidebar from off-canvas drawer to static column at 721px, *not* at `md`. Any `matchMedia` guard or
-utility variant that has to agree with the shell must use `nav`; using `md` leaves 721–959px broken
-(sidebar already static while your script still treats it as an overlay).
+**Two widths in that object are not ramp steps**, and each is the one to use when your rule has to
+fire with a kit rule. Aligning either to the nearest ramp step leaves a band of broken widths, in
+which the kit has already switched and your app has not:
+
+| | px | Governs | Aligning to the ramp instead breaks |
+|---|---|---|---|
+| `breakpoints.nav` | 721 | `.fdy-app` switches the sidebar from off-canvas drawer to static column — and `.fdy-app__main`'s padding step and `.fdy-bottomnav` ride the same width | 721–959px, if you use `md`: sidebar already static while your script still treats it as an overlay |
+| `breakpoints.filterbar` | 640 | `.fdy-filterbar` stacks every field full-width | 600–640px, if you use `sm`: fields already stacked while your rule still caps the `--w-grow` one, so it sits visibly narrower than the fields under it |
+
+**In CSS, import the breakpoints instead of retyping them.** `@media` cannot read a custom property,
+so there is no `--breakpoint-*` token and never will be; `@cahyo-dimas/freeday/media` answers it the
+only way CSS can, as a `@custom-media` sheet:
+
+```css
+@import '@cahyo-dimas/freeday/media';           /* once, above the rules that use it */
+
+@media (--fdy-filterbar-stacked) { .page-filters > .fdy-field--w-grow { max-width: none } }
+@media (--fdy-nav-drawer)        { .page-banner { padding-inline: var(--space-5) } }
+```
+
+Declared: `--fdy-below-sm|md|lg|xl` and `--fdy-from-sm|md|lg|xl` (the ramp, matching the utilities
+above), plus `--fdy-nav-drawer` / `--fdy-nav-static` and `--fdy-filterbar-stacked` for the two
+widths in the table. It is **opt-in**: `@custom-media` is a PostCSS transform
+(`postcss-custom-media`, included in `postcss-preset-env`), so an app that runs PostCSS — anything on
+Vite already does — gets it, and an app that does not keeps writing literals exactly as before. The
+sheet carries no rules, so importing it costs nothing at runtime, and it is deliberately not part of
+`freeday.css` or `freeday.bundle.css`.
 
 **Visual style: `data-style="soft | glass"`.** `soft` is the default and the look the kit has always
 had; `glass` frosts the **raised** surfaces — card, modal, drawer, menu, appbar, the app shell's

package/README.id.md

@@ -5,7 +5,7 @@
 > **Lebih banyak _free day_ buat dev. UI kit-nya sudah siap pakai.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v3.4.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.4.0)
+[![Release](https://img.shields.io/badge/release-v3.5.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.5.0)
 
 UI KIT yang token-driven & framework-agnostic. Satu sumber kebenaran untuk warna, tipografi,
 spasi, dan komponen. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.
@@ -60,7 +60,7 @@ npm i @cahyo-dimas/freeday
 ```js
 import '@cahyo-dimas/freeday/css';   // token + komponen (satu file)
 import '@cahyo-dimas/freeday';       // semua enhancer JS (auto-init [data-fdy-*])
-// granular bila perlu: '@cahyo-dimas/freeday/tokens' · '@cahyo-dimas/freeday/css/components' · '@cahyo-dimas/freeday/enhancers/<nama>'
+// granular bila perlu: '@cahyo-dimas/freeday/tokens' · '@cahyo-dimas/freeday/css/components' · '@cahyo-dimas/freeday/enhancers/<nama>' · '@cahyo-dimas/freeday/media' (breakpoint @custom-media)
 ```
 Set tema di root app: `<html data-theme="light" data-density="comfortable">`. `dist/` di-commit &
 ter-publish → install tanpa build step; minify diserahkan ke bundler konsumen. Karena terbit di
@@ -153,9 +153,13 @@ container-nya, bukan scroll sendiri.
   menyusut/melebar saat `data-density` berubah.
 - (roadmap) `data-style` untuk varian visual lain.
 - Skala breakpoint (`sm`/`md`/`lg`/`xl` = 600/960/1280/1920px, sama dengan utilitas
-  `src/components/breakpoints.css`) juga tersedia di JS: `import { breakpoints } from
-  '@cahyo-dimas/freeday/breakpoints'`. Pakai itu untuk menyamakan `matchMedia`/`@media` app-mu
-  dengan skala Freeday.
+  `src/components/breakpoints.css`) tersedia untuk app-mu dalam dua bahasa: `import { breakpoints }
+  from '@cahyo-dimas/freeday/breakpoints'` untuk JS (`matchMedia`, varian utility), dan `@import
+  '@cahyo-dimas/freeday/media'` untuk CSS, yang mendeklarasikan tiap lebar sebagai `@custom-media`
+  sehingga sebuah rule ditulis `@media (--fdy-below-sm)`, bukan literal yang diketik ulang (butuh
+  PostCSS; opt-in). Objeknya juga membawa dua lebar yang **bukan** anak tangga ramp dan tak boleh
+  dibulatkan ke salah satunya: `nav` (721, saklar drawer↔sidebar milik shell) dan `filterbar` (640,
+  tempat `.fdy-filterbar` menumpuk). Lihat [`COMPONENTS.md`](COMPONENTS.md) untuk apa yang diaturnya.
 
 ## Integrasi framework (SPA)
 > **Peta library lengkap:** [`docs/integrations.md`](docs/integrations.md). Tiap area

package/README.md

@@ -5,7 +5,7 @@
 > **More free days for devs. The UI kit is ready to use.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v3.4.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.4.0)
+[![Release](https://img.shields.io/badge/release-v3.5.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.5.0)
 
 A token-driven, framework-agnostic UI kit. One source of truth for color, typography,
 spacing, and components. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.
@@ -61,7 +61,7 @@ npm i @cahyo-dimas/freeday
 ```js
 import '@cahyo-dimas/freeday/css';   // tokens + components (single file)
 import '@cahyo-dimas/freeday';       // all JS enhancers (auto-init [data-fdy-*])
-// granular if needed: '@cahyo-dimas/freeday/tokens' · '@cahyo-dimas/freeday/css/components' · '@cahyo-dimas/freeday/enhancers/<name>'
+// granular if needed: '@cahyo-dimas/freeday/tokens' · '@cahyo-dimas/freeday/css/components' · '@cahyo-dimas/freeday/enhancers/<name>' · '@cahyo-dimas/freeday/media' (@custom-media breakpoints)
 ```
 Set the theme on your app root: `<html data-theme="light" data-density="comfortable">`. `dist/` is
 committed and published, so install needs **no build step**; minification is left to the consumer's
@@ -154,9 +154,13 @@ of scrolling.
   to shrink or grow when `data-density` changes.
 - (roadmap) `data-style` for alternative visual variants.
 - The breakpoint scale (`sm`/`md`/`lg`/`xl` = 600/960/1280/1920px, matching the
-  `src/components/breakpoints.css` utilities) is also available in JS: `import { breakpoints } from
-  '@cahyo-dimas/freeday/breakpoints'`. Use it to keep your app's `matchMedia`/`@media` on the same
-  scale as Freeday's.
+  `src/components/breakpoints.css` utilities) is available to your app in both languages: `import
+  { breakpoints } from '@cahyo-dimas/freeday/breakpoints'` for JS (`matchMedia`, utility variants),
+  and `@import '@cahyo-dimas/freeday/media'` for CSS, which declares each one as a `@custom-media`
+  so a rule reads `@media (--fdy-below-sm)` instead of a retyped literal (needs PostCSS; opt-in).
+  The object also carries the two widths that are **not** ramp steps and must not be rounded to one:
+  `nav` (721, the shell's drawer↔sidebar switch) and `filterbar` (640, where `.fdy-filterbar`
+  stacks). See [`COMPONENTS.md`](COMPONENTS.md) for what each governs.
 
 ## Framework integration (SPA)
 > **Full library map:** [`docs/integrations.md`](docs/integrations.md). Each area (forms/validation,

package/dist/freeday.bundle.css

@@ -1290,8 +1290,14 @@ a { color: var(--color-primary); }
 
 /* Freeday. Responsive display utilities (pairs with freeday-breakpoint.js).
  * Breakpoint scale (min-width, px): sm 600 · md 960 · lg 1280 · xl 1920.
+ * Two further widths exist and are NOT ramp steps: `nav` (app-shell.css, off-canvas drawer vs
+ * static sidebar) and `filterbar` (filterbar.css, the width its fields stack at). Both are named
+ * in tokens/breakpoints.mjs; a rule that has to fire with one of them aligns to it, not to the
+ * nearest ramp step, which is a band of broken widths in both directions.
  * NOTE: media-query breakpoints must be literal. CSS can't read custom properties
- * inside @media, so these px are structural, not stray magic numbers. */
+ * inside @media, so these px are structural, not stray magic numbers. An app that runs PostCSS
+ * need not retype them: `@cahyo-dimas/freeday/media` declares every width above as a
+ * @custom-media, so it can write `@media (--fdy-below-sm)` and never drift (#058 §2). */
 .fdy-hidden{display:none !important;}
 
 /* hide-below-X, hidden when the viewport is narrower than X (content shows at X and up) */
@@ -2077,7 +2083,14 @@ a { color: var(--color-primary); }
 /* Opt-in: sit the actions inline right after the last field instead of at the far edge, so when the
  * bar wraps they read as attached to the filters rather than shoved to the right of a lonely row. */
 .fdy-filterbar--actions-inline .fdy-filterbar__actions{margin-left:0;}
-/* Stack on narrow screens so nothing overflows the row. */
+/* Stack on narrow screens so nothing overflows the row.
+ * 640 is deliberately not a ramp step (sm is 600): it is a real phone-landscape width, and moving
+ * it now would reflow every filter bar in every consuming app. So it is NAMED instead — `filterbar`
+ * in tokens/breakpoints.mjs, `--fdy-filterbar-stacked` in the media sheet — because an app rule
+ * that must fire with the stack (releasing a --w-grow field's max-width, say) has to match this
+ * exact condition, and aligning it to sm from the docs alone leaves 600–640px half-stacked: the
+ * fields are already full width while the app still caps the growing one. Raised from
+ * IDU_AI_DOC_SAPB1_CLIENT and IDU_AI_DOC_SAAS (#058 §1). */
 @media (max-width:640px){
   .fdy-filterbar>.fdy-field,.fdy-filterbar>.fdy-field--w-sm,.fdy-filterbar>.fdy-field--w-lg,.fdy-filterbar>.fdy-field--w-xl,.fdy-filterbar>.fdy-field--w-2xl,.fdy-filterbar>.fdy-field--w-grow{width:100%;flex:1 1 100%;}
   .fdy-filterbar__actions{width:100%;margin-left:0;}

package/dist/freeday.css

@@ -412,8 +412,14 @@ a { color: var(--color-primary); }
 
 /* Freeday. Responsive display utilities (pairs with freeday-breakpoint.js).
  * Breakpoint scale (min-width, px): sm 600 · md 960 · lg 1280 · xl 1920.
+ * Two further widths exist and are NOT ramp steps: `nav` (app-shell.css, off-canvas drawer vs
+ * static sidebar) and `filterbar` (filterbar.css, the width its fields stack at). Both are named
+ * in tokens/breakpoints.mjs; a rule that has to fire with one of them aligns to it, not to the
+ * nearest ramp step, which is a band of broken widths in both directions.
  * NOTE: media-query breakpoints must be literal. CSS can't read custom properties
- * inside @media, so these px are structural, not stray magic numbers. */
+ * inside @media, so these px are structural, not stray magic numbers. An app that runs PostCSS
+ * need not retype them: `@cahyo-dimas/freeday/media` declares every width above as a
+ * @custom-media, so it can write `@media (--fdy-below-sm)` and never drift (#058 §2). */
 .fdy-hidden{display:none !important;}
 
 /* hide-below-X, hidden when the viewport is narrower than X (content shows at X and up) */
@@ -1199,7 +1205,14 @@ a { color: var(--color-primary); }
 /* Opt-in: sit the actions inline right after the last field instead of at the far edge, so when the
  * bar wraps they read as attached to the filters rather than shoved to the right of a lonely row. */
 .fdy-filterbar--actions-inline .fdy-filterbar__actions{margin-left:0;}
-/* Stack on narrow screens so nothing overflows the row. */
+/* Stack on narrow screens so nothing overflows the row.
+ * 640 is deliberately not a ramp step (sm is 600): it is a real phone-landscape width, and moving
+ * it now would reflow every filter bar in every consuming app. So it is NAMED instead — `filterbar`
+ * in tokens/breakpoints.mjs, `--fdy-filterbar-stacked` in the media sheet — because an app rule
+ * that must fire with the stack (releasing a --w-grow field's max-width, say) has to match this
+ * exact condition, and aligning it to sm from the docs alone leaves 600–640px half-stacked: the
+ * fields are already full width while the app still caps the growing one. Raised from
+ * IDU_AI_DOC_SAPB1_CLIENT and IDU_AI_DOC_SAAS (#058 §1). */
 @media (max-width:640px){
   .fdy-filterbar>.fdy-field,.fdy-filterbar>.fdy-field--w-sm,.fdy-filterbar>.fdy-field--w-lg,.fdy-filterbar>.fdy-field--w-xl,.fdy-filterbar>.fdy-field--w-2xl,.fdy-filterbar>.fdy-field--w-grow{width:100%;flex:1 1 100%;}
   .fdy-filterbar__actions{width:100%;margin-left:0;}

package/dist/freeday.media.css

@@ -0,0 +1,27 @@
+/* Freeday breakpoints as @custom-media. GENERATED by tokens/build.mjs. Do not edit by hand.
+ *
+ * Requires postcss-custom-media (or any PostCSS setup that includes postcss-preset-env); without it
+ * a browser ignores the at-rules and every @media (--fdy-*) in your CSS never matches. Import it
+ * ONCE, above the rules that use it:
+ *
+ *   @import '@cahyo-dimas/freeday/media';
+ *   @media (--fdy-below-sm) { .page-header { display: block } }
+ *
+ * This file carries no rules of its own, so importing it costs nothing at runtime; it is not part
+ * of freeday.css or freeday.bundle.css. */
+@custom-media --fdy-below-sm (max-width: 599.98px);
+@custom-media --fdy-from-sm (min-width: 600px);
+@custom-media --fdy-below-md (max-width: 959.98px);
+@custom-media --fdy-from-md (min-width: 960px);
+@custom-media --fdy-below-lg (max-width: 1279.98px);
+@custom-media --fdy-from-lg (min-width: 1280px);
+@custom-media --fdy-below-xl (max-width: 1919.98px);
+@custom-media --fdy-from-xl (min-width: 1920px);
+
+/* NOT ramp steps. Each mirrors one hard-wired rule in the kit, and a rule that must fire with it
+ * uses THIS condition, never the nearest ramp step: aligning shell-dependent code to --fdy-below-md
+ * leaves 721–959px broken, and aligning a filter-bar rule to --fdy-below-sm leaves 600–640px
+ * half-stacked. See tokens/breakpoints.mjs for what each one governs. */
+@custom-media --fdy-nav-drawer (max-width: 720px);
+@custom-media --fdy-nav-static (min-width: 721px);
+@custom-media --fdy-filterbar-stacked (max-width: 640px);

package/docs/agent-onboarding.md

@@ -96,6 +96,7 @@ Blazor). Then verify the agent can actually read those files. An agent that can'
 | `docs/agent-onboarding.md` | This file. |
 | `CHANGELOG.md` | **What changed between the version this project had and the one it has now.** Read it after every upgrade; each entry says what broke, what is new, and why. |
 | `dist/` | Built CSS + enhancers. **`freeday.bundle.css` = tokens + components** (what `@cahyo-dimas/freeday/css` resolves to); `freeday.css` is components **only**, `freeday.tokens.css` tokens only, so linking `freeday.css` alone leaves every `var(--…)` unresolved. Plus `freeday-*.js` and the `.d.ts` files. |
+| `dist/freeday.media.css` | The breakpoints as `@custom-media` (`@cahyo-dimas/freeday/media`), so a responsive rule in your CSS states the kit's condition instead of a retyped literal. Needs PostCSS; carries no rules, and is **not** in the bundle. |
 | `src/components/*.css` | The authoritative source for every class, when a doc is ambiguous. |
 | `tokens/tokens.json` | Every token in W3C DTCG format, machine-readable. |
 | `adapters/vue` · `adapters/react` · `adapters/blazor` | Typed wrappers, 11 components each (plus `FdyTableFooter`). |
@@ -138,6 +139,7 @@ Recent additions most likely to replace something an app hand-rolled (all detail
 | `.fdy-field--full` | `max-width: none` on the form container, once per form, because the fields are a flex column and not a `.fdy-form-grid` |
 | `.fdy-nav--flat` | undoing the caret, the pointer cursor and the group divider yourself, on a sidebar whose group labels never collapse |
 | `--fdy-app-sidebar-w` | overriding `width` on `.fdy-app__sidebar`, which is also the rule that animates the collapse |
+| `@media (--fdy-filterbar-stacked)` / `(--fdy-nav-drawer)`, from `@cahyo-dimas/freeday/media` | a literal `640px` or `720px` retyped into your stylesheet, which no longer matches the kit's rule the day the kit retunes it — and which you could only have found by reading `filterbar.css` |
 
 ## 3. Starting a new screen
 

package/docs/getting-started.md

@@ -191,7 +191,7 @@ live docs also have a copy button per component.
 ```bash
 npm i @cahyo-dimas/freeday
 ```
-Lands in `package.json` as `"@cahyo-dimas/freeday": "^3.4.0"` (public npm package). `dist/` is
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^3.5.0"` (public npm package). `dist/` is
 committed and published → no build step; `npm ci` runs without auth.
 
 ### 2. Import the CSS + enhancers **once** in your entry (`src/main.ts`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cahyo-dimas/freeday",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Freeday: token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",
@@ -54,6 +54,10 @@
       "types": "./dist/asset.d.ts",
       "default": "./dist/freeday.tokens.css"
     },
+    "./media": {
+      "types": "./dist/asset.d.ts",
+      "default": "./dist/freeday.media.css"
+    },
     "./breakpoints": {
       "types": "./tokens/breakpoints.d.ts",
       "default": "./tokens/breakpoints.mjs"

package/src/components/breakpoints.css

@@ -1,7 +1,13 @@
 /* Freeday. Responsive display utilities (pairs with freeday-breakpoint.js).
  * Breakpoint scale (min-width, px): sm 600 · md 960 · lg 1280 · xl 1920.
+ * Two further widths exist and are NOT ramp steps: `nav` (app-shell.css, off-canvas drawer vs
+ * static sidebar) and `filterbar` (filterbar.css, the width its fields stack at). Both are named
+ * in tokens/breakpoints.mjs; a rule that has to fire with one of them aligns to it, not to the
+ * nearest ramp step, which is a band of broken widths in both directions.
  * NOTE: media-query breakpoints must be literal. CSS can't read custom properties
- * inside @media, so these px are structural, not stray magic numbers. */
+ * inside @media, so these px are structural, not stray magic numbers. An app that runs PostCSS
+ * need not retype them: `@cahyo-dimas/freeday/media` declares every width above as a
+ * @custom-media, so it can write `@media (--fdy-below-sm)` and never drift (#058 §2). */
 .fdy-hidden{display:none !important;}
 
 /* hide-below-X, hidden when the viewport is narrower than X (content shows at X and up) */

package/src/components/filterbar.css

@@ -41,7 +41,14 @@
 /* Opt-in: sit the actions inline right after the last field instead of at the far edge, so when the
  * bar wraps they read as attached to the filters rather than shoved to the right of a lonely row. */
 .fdy-filterbar--actions-inline .fdy-filterbar__actions{margin-left:0;}
-/* Stack on narrow screens so nothing overflows the row. */
+/* Stack on narrow screens so nothing overflows the row.
+ * 640 is deliberately not a ramp step (sm is 600): it is a real phone-landscape width, and moving
+ * it now would reflow every filter bar in every consuming app. So it is NAMED instead — `filterbar`
+ * in tokens/breakpoints.mjs, `--fdy-filterbar-stacked` in the media sheet — because an app rule
+ * that must fire with the stack (releasing a --w-grow field's max-width, say) has to match this
+ * exact condition, and aligning it to sm from the docs alone leaves 600–640px half-stacked: the
+ * fields are already full width while the app still caps the growing one. Raised from
+ * IDU_AI_DOC_SAPB1_CLIENT and IDU_AI_DOC_SAAS (#058 §1). */
 @media (max-width:640px){
   .fdy-filterbar>.fdy-field,.fdy-filterbar>.fdy-field--w-sm,.fdy-filterbar>.fdy-field--w-lg,.fdy-filterbar>.fdy-field--w-xl,.fdy-filterbar>.fdy-field--w-2xl,.fdy-filterbar>.fdy-field--w-grow{width:100%;flex:1 1 100%;}
   .fdy-filterbar__actions{width:100%;margin-left:0;}

package/tokens/breakpoints.d.ts

@@ -4,6 +4,10 @@ export declare const breakpoints: {
   /** Width at which .fdy-app's sidebar turns from off-canvas drawer into a static column.
    *  Not part of the sm/md/lg/xl ramp; it mirrors app-shell.css and nothing else. */
   nav: number;
+  /** Width at or below which .fdy-filterbar stacks every field full-width.
+   *  Not part of the sm/md/lg/xl ramp; it mirrors filterbar.css and nothing else. A rule that
+   *  must fire with the stack uses this, not `sm` — `sm` leaves 600–640px half-stacked. */
+  filterbar: number;
   sm: number;
   md: number;
   lg: number;

package/tokens/breakpoints.mjs

@@ -1,11 +1,25 @@
 // Freeday breakpoint scale in px, mirrors src/components/breakpoints.css utilities
 // (sm/md/lg/xl). CSS @media can't read custom properties, so this is the JS-side
-// source of the scale for matchMedia / app @media alignment.
+// source of the scale for matchMedia / app @media alignment. The CSS-side answer to the
+// same problem is dist/freeday.media.css (`@cahyo-dimas/freeday/media`), a @custom-media
+// sheet GENERATED from this object, so the two halves cannot disagree.
 //
-// `nav` is not part of the sm/md/lg/xl ramp: it is the width at which .fdy-app switches the
-// sidebar from an off-canvas drawer (below) to a static column (at and above), hard-wired in
-// src/components/app-shell.css. Anything that has to agree with the shell, a matchMedia guard
-// deciding whether the nav toggle sets --nav-open or --nav-collapsed, a utility-framework
-// variant, must use THIS number, not md. Aligning such code to md (960) leaves 721–959px
-// broken: the sidebar is already static while the script still thinks it is an overlay.
-export const breakpoints = { nav: 721, sm: 600, md: 960, lg: 1280, xl: 1920 };
+// `nav` and `filterbar` are not part of the sm/md/lg/xl ramp. Each mirrors one hard-wired rule in
+// the kit, and each must be used INSTEAD of the nearest ramp step — that is the whole reason they
+// are named here rather than left to be discovered by reading the stylesheet.
+//
+// `nav` is the width at which .fdy-app switches the sidebar from an off-canvas drawer (below) to a
+// static column (at and above), hard-wired in src/components/app-shell.css. Anything that has to
+// agree with the shell, a matchMedia guard deciding whether the nav toggle sets --nav-open or
+// --nav-collapsed, a utility-framework variant, must use THIS number, not md. Aligning such code to
+// md (960) leaves 721–959px broken: the sidebar is already static while the script still thinks it
+// is an overlay.
+//
+// `filterbar` is the width at which .fdy-filterbar stacks every field full-width, hard-wired in
+// src/components/filterbar.css. It is deliberately not sm: 640 is a real phone-landscape width and
+// moving it would reflow every filter bar in every consuming app. An app rule that has to fire in
+// lockstep with the stack — releasing a growing field's max-width, say — must use THIS number.
+// Aligning it to sm (600) leaves 600–640px broken: the kit has already stacked the fields while the
+// app still caps one of them, so it sits visibly narrower than the fields under it. Raised from
+// IDU_AI_DOC_SAPB1_CLIENT and IDU_AI_DOC_SAAS (#058 §1).
+export const breakpoints = { nav: 721, filterbar: 640, sm: 600, md: 960, lg: 1280, xl: 1920 };