@cahyo-dimas/freeday 3.3.1 → 3.5.0

package/CHANGELOG.md

@@ -9,6 +9,89 @@ 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
+`keamanan-cluster`) datang dari pemilik yang menguji di iPhone X, dan ketiganya punya bentuk yang
+sama: tak satu pun dapat ditemukan di Chromium, dan tak satu pun akan pernah ditangkap uji yang
+sudah ada — bukan karena ujinya kurang, melainkan karena mesin peramban di laptop tidak berperilaku
+seperti Safari di HP, dan laptop tidak punya ibu jari.
+
+Yang pertama mengunci navigasi sepenuhnya: tap di luar drawer tidak menutupnya, layar tetap gelap,
+dan satu-satunya jalan keluar adalah memuat ulang halaman.
+
+### Added
+- **`.fdy-bottomnav`** — bilah navigasi bawah untuk aplikasi di HP. Kit punya `--horizontal` untuk
+  top-nav dan drawer off-canvas untuk sidebar, dan tidak punya apa pun untuk susunan yang justru
+  dipakai hampir semua aplikasi telepon. Tampil hanya di `max-width:720px`; di desktop sidebar sudah
+  membawa tautan yang sama dan salinan kedua hanya duplikasi.
+  Sengaja **bukan** bagian markup `.fdy-app`: ia `position:fixed` sehingga bekerja dari mana pun di
+  dalam shell, dan aplikasi yang tidak memakainya tidak membayar apa pun.
+  Target minimal 44px — di bawah itu satu tap menjadi satu percobaan ulang, dan bilah ini ditekan
+  lebih sering daripada kontrol mana pun. Label tidak opsional: bilah ikon-saja menuntut setiap
+  pengguna sudah hafal arti tiap glyph. `env(safe-area-inset-bottom)` masuk ke padding, jadi label
+  tidak duduk di bawah home indicator pada HP bernotch.
+- **`.fdy-app--has-bottomnav`** menyediakan ruang bawah untuk bilah itu. Tanpanya baris terakhir
+  setiap daftar di setiap layar berakhir di bawah bilah — dan baris yang tak bisa digulir ke sana
+  adalah baris yang tak seorang pun tahu ada.
+- **`.fdy-app--navtoggle-end`** memindahkan tombol nav ke sisi jauh topbar. Ini ergonomi, bukan
+  selera: pada HP besar yang dipegang satu tangan, pojok kiri-ATAS adalah tempat tersulit dijangkau
+  ibu jari kanan, dan tombol itu yang paling sering ditekan di sana. Opt-in, sebab shell desktop yang
+  juga menaruh avatar di kanan punya persoalan sebaliknya.
+
+### Fixed
+- **`.fdy-app__backdrop` kini membawa `cursor:pointer`** (`#057`). Ini bukan untuk tetikus. Safari
+  iOS hanya mensintesis `click` dari tap pada elemen yang dianggapnya interaktif, dan bentuk kursor
+  salah satu penanda yang dipakainya. Backdrop-nya `<div>` polos dengan handler klik — tanpa button,
+  tanpa role, tanpa tabindex — sehingga tanpa aturan ini sebuah tap di atasnya sama sekali tidak
+  menghasilkan klik: drawer tetap terbuka, scrim tetap gelap, dan memuat ulang halaman adalah
+  satu-satunya jalan keluar. Tidak dapat direproduksi di Chromium, baik dengan klik tetikus maupun
+  `touchscreen.tap()` — itu sebabnya tidak satu pun uji di kit ini maupun di app yang memakainya
+  pernah menangkapnya. Dijaga `browser/bottom-nav.mjs`.
+
 ## [3.3.1] - 2026-09-07
 
 **Tautan lewati yang tak punya tujuan, di tiga stack sekaligus.** `#056` (dari `keamanan-cluster`)

package/COMPONENTS.md

@@ -146,7 +146,16 @@ off-canvas drawer and backdrop are built in.
   overriding `width` on `.fdy-app__sidebar`, whose value also feeds the collapse transition.
 - Modifiers: `--nav-open` (drawer open) · `--nav-collapsed` (collapse to zero width, ≥721px) ·
   `--nav-overlay` (≥721px: float the nav over the content instead of displacing it) · `--static`
-  (embed the shell in a page instead of filling the viewport)
+  (embed the shell in a page instead of filling the viewport) · `--navtoggle-end` (move the nav
+  toggle to the far side of the topbar) · `--has-bottomnav` (reserve room for `.fdy-bottomnav`)
+- **`--navtoggle-end`** is ergonomics, not taste: on a large phone held in one hand the top-LEFT
+  corner is the hardest place on the screen for a right thumb to reach, and the toggle is the
+  control pressed there most. Opt-in, because a desktop shell that also puts an avatar on the right
+  has the opposite problem.
+- The backdrop carries `cursor:pointer`. That is **not** for the mouse: Safari on iOS only
+  synthesises a `click` from a tap on elements it treats as interactive, and the cursor is one of
+  the signals it uses. Without it, tapping outside the drawer on an iPhone does nothing at all —
+  the drawer stays open, the scrim stays dark, and reloading is the only way out.
 
 **`--nav-overlay` is a layout choice, not a second behaviour.** With it the nav floats at *every*
 width, so the drawer's whole code path — backdrop, Escape, close-on-follow, focus into the panel and
@@ -304,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
@@ -1496,6 +1528,39 @@ Size-matched placeholders so nothing shifts when data lands: `--title` `--text`
 
 # Navigation
 
+## Bottom navigation — `.fdy-bottomnav`
+The bar a **phone** application puts its three-to-five most-used destinations on, where a thumb
+reaches them. Shown only at `max-width:720px`; on a desktop the sidebar already carries the same
+links, and a second copy would be duplication.
+
+Not part of `.fdy-app`'s markup: it is `position:fixed`, so it works from anywhere inside the
+shell, and an application that does not want one pays nothing. Put **`.fdy-app--has-bottomnav`** on
+the shell to reserve room for it — without that, the last row of every list ends underneath the bar,
+and a row nobody can scroll to is a row nobody knows is there.
+
+- Items are `<a class="fdy-bottomnav__item">` with `__icon` / `__label`; the current one gets
+  `aria-current="page"` — the same contract `.fdy-nav__item` uses, so "you are here" has one
+  meaning in this kit, not two.
+- Targets are at least 44px tall. Under that a tap becomes a retry, and this bar is pressed more
+  than any other control in a phone application.
+- Labels are **not** optional. An icon-only bar asks every user to have already learned what each
+  glyph means. Long labels ellipsis rather than wrap, so the bar keeps one height.
+- Bottom padding includes `env(safe-area-inset-bottom)`, so labels do not sit under the home
+  indicator on a notched phone.
+
+```html
+<nav class="fdy-bottomnav" aria-label="Main">
+  <a class="fdy-bottomnav__item" href="/dashboard" aria-current="page">
+    <span class="fdy-bottomnav__icon"><!--svg--></span>
+    <span class="fdy-bottomnav__label">Dashboard</span>
+  </a>
+  <a class="fdy-bottomnav__item" href="/schedule">
+    <span class="fdy-bottomnav__icon"><!--svg--></span>
+    <span class="fdy-bottomnav__label">Schedule</span>
+  </a>
+</nav>
+```
+
 ## Nav (menu) — `.fdy-nav`
 Navigation links, **vertical by default** (the app shell sidebar), horizontal with `--horizontal`. Items are `<a class="fdy-nav__item">` with
 `__icon` / `__label` / `__badge`; the current one gets `aria-current="page"`.

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.3.1-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.3.1)
+[![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.3.1-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.3.1)
+[![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

@@ -1040,6 +1040,13 @@ a { color: var(--color-primary); }
 .fdy-app__navtoggle:hover{background:var(--color-surface-2);color:var(--color-text);}
 .fdy-app__navtoggle:focus-visible{outline:none;box-shadow:0 0 0 2px var(--color-primary);}
 .fdy-app__navtoggle svg{display:block;width:1.25rem;height:1.25rem;}
+/* --navtoggle-end moves the toggle to the far side of the topbar. The title already
+ * carries `margin-right:auto`, so ordering the toggle last is enough; nothing else needs
+ * to know. On a large phone held in one hand the top-LEFT corner is the hardest place on
+ * the screen for a right thumb to reach, and the toggle is the control most often pressed
+ * there — so this is ergonomics, not taste. Left as an opt-in because a desktop shell that
+ * also puts an avatar on the right has the opposite problem. */
+.fdy-app--navtoggle-end .fdy-app__navtoggle{order:1;}
 /* Desktop collapse: animate width -> 0 (content clips via overflow:hidden; the content area
  * flexes in to fill). Not display:none, so the collapse/expand slides instead of snapping. */
 @media (min-width:721px){.fdy-app--nav-collapsed .fdy-app__sidebar{width:0;border-right-width:0;}}
@@ -1075,7 +1082,15 @@ a { color: var(--color-primary); }
  * the initial `visible`, so a mode switch alone hands the page ~200ms of dead clicks. Measured: with
  * only `visibility:hidden`, elementFromPoint over the nav toggle returned the backdrop.
  * Mobile: the sidebar becomes an off-canvas drawer opened by the topbar toggle. */
-.fdy-app__backdrop{display:none;}
+/* `cursor:pointer` here is not decoration, and not for the mouse. Safari on iOS only
+ * synthesises a `click` from a tap on elements it treats as interactive, and the cursor
+ * being a pointer is one of the signals it uses. The backdrop is a plain <div> with a
+ * click handler — no button, no role, no tabindex — so without this rule a tap on it
+ * produces no click at all: the drawer stays open, the scrim stays dark, and the only way
+ * out is reloading the page. Reported from a real iPhone X; not reproducible in Chromium
+ * with either mouse click or `touchscreen.tap()`, which is why no test in this kit or in
+ * the consuming app had ever caught it. */
+.fdy-app__backdrop{display:none;cursor:pointer;}
 @media (max-width:720px){
   .fdy-app__sidebar{position:fixed;top:0;left:0;bottom:0;height:100dvh;width:16rem;z-index:60;transform:translateX(-100%);transition:transform var(--dur-base) var(--ease-standard);box-shadow:var(--shadow-4);}
   .fdy-app--nav-open .fdy-app__sidebar{transform:translateX(0);}
@@ -1200,6 +1215,69 @@ a { color: var(--color-primary); }
 .fdy-badge-ov--bottom-right{top:auto;bottom:0;transform:translate(50%,50%);}
 .fdy-badge-ov--bottom-left{top:auto;bottom:0;right:auto;left:0;transform:translate(-50%,50%);}
 
+/* Freeday. Bottom navigation
+ *
+ * The bar a phone application puts its three-to-five most-used destinations on. The kit
+ * had `.fdy-nav--horizontal` for a top-nav application and the off-canvas drawer for a
+ * sidebar one, and nothing for the arrangement almost every phone application actually
+ * uses — which was only noticed when an app shipped to real phones and its owner reached
+ * for a thumb-reachable bar that did not exist.
+ *
+ * Deliberately NOT part of `.fdy-app`'s markup: it is `position:fixed`, so it works from
+ * anywhere inside the shell's content slot, and an application that does not want one
+ * pays nothing. `.fdy-app--has-bottomnav` on the shell is what reserves room for it. */
+.fdy-bottomnav{display:none;}
+@media (max-width:720px){
+  .fdy-bottomnav{
+    display:flex;position:fixed;left:0;right:0;bottom:0;z-index:50;
+    align-items:stretch;justify-content:space-around;gap:var(--space-1);
+    padding:var(--space-2) var(--space-2);
+    /* The home indicator on a notched phone sits over the bottom of the viewport, and a
+     * bar that ignores it puts its labels underneath a physical UI element. Added to the
+     * padding rather than substituted for it, so a phone without one is unaffected. */
+    padding-bottom:calc(var(--space-2) + env(safe-area-inset-bottom,0px));
+    background:var(--color-surface-raised);
+    backdrop-filter:var(--surface-filter);
+    -webkit-backdrop-filter:var(--surface-filter);
+    border-top:var(--bw) solid var(--color-border);
+  }
+  /* Room for the bar, or the last row of every list on every screen sits under it -- and
+     a row you cannot scroll to is a row nobody knows is there. */
+  .fdy-app--has-bottomnav .fdy-app__main{
+    padding-bottom:calc(var(--space-20) + env(safe-area-inset-bottom,0px));
+  }
+}
+.fdy-bottomnav__item{
+  display:flex;flex:1 1 0;min-width:0;flex-direction:column;align-items:center;
+  justify-content:center;gap:2px;
+  /* 44px is the smallest target a thumb hits reliably; anything under it turns a tap into
+   * a retry, and this bar is pressed more than any other control in the application. */
+  min-height:2.75rem;padding:var(--space-1);
+  border-radius:var(--radius-md);
+  font-family:var(--font-body);font-size:var(--text-xs);font-weight:var(--weight-medium);
+  color:var(--color-text-muted);text-decoration:none;text-align:center;
+  transition:background var(--dur-fast) var(--ease-standard),
+             color var(--dur-fast) var(--ease-standard);
+}
+.fdy-bottomnav__item:hover{color:var(--color-text);}
+.fdy-bottomnav__item:focus-visible{outline:none;box-shadow:0 0 0 2px var(--color-primary);}
+/* The current destination is marked by `aria-current="page"`, the same attribute
+ * `.fdy-nav__item` uses -- one contract for "you are here", not two. */
+.fdy-bottomnav__item[aria-current="page"]{
+  color:var(--color-primary-strong);background:var(--color-primary-soft);
+}
+.fdy-bottomnav__icon{display:block;width:1.25rem;height:1.25rem;flex:none;}
+.fdy-bottomnav__icon svg{display:block;width:100%;height:100%;}
+/* Labels are never dropped in favour of icons alone: an icon-only bar asks every user to
+ * have already learned what each glyph means, and the people using this kit's applications
+ * on a phone are often using them for the first time. Long labels ellipsis rather than
+ * wrap, so the bar keeps one height. */
+.fdy-bottomnav__label{
+  display:block;max-width:100%;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;
+  line-height:1.2;
+}
+@media (prefers-reduced-motion:reduce){.fdy-bottomnav__item{transition:none;}}
+
 /* Freeday. Breadcrumb */
 .fdy-breadcrumb{font-size:var(--text-sm);}
 .fdy-breadcrumb__list{display:flex;flex-wrap:wrap;align-items:center;gap:var(--space-2);list-style:none;margin:0;padding:0;}
@@ -1212,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) */
@@ -1999,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

@@ -162,6 +162,13 @@ a { color: var(--color-primary); }
 .fdy-app__navtoggle:hover{background:var(--color-surface-2);color:var(--color-text);}
 .fdy-app__navtoggle:focus-visible{outline:none;box-shadow:0 0 0 2px var(--color-primary);}
 .fdy-app__navtoggle svg{display:block;width:1.25rem;height:1.25rem;}
+/* --navtoggle-end moves the toggle to the far side of the topbar. The title already
+ * carries `margin-right:auto`, so ordering the toggle last is enough; nothing else needs
+ * to know. On a large phone held in one hand the top-LEFT corner is the hardest place on
+ * the screen for a right thumb to reach, and the toggle is the control most often pressed
+ * there — so this is ergonomics, not taste. Left as an opt-in because a desktop shell that
+ * also puts an avatar on the right has the opposite problem. */
+.fdy-app--navtoggle-end .fdy-app__navtoggle{order:1;}
 /* Desktop collapse: animate width -> 0 (content clips via overflow:hidden; the content area
  * flexes in to fill). Not display:none, so the collapse/expand slides instead of snapping. */
 @media (min-width:721px){.fdy-app--nav-collapsed .fdy-app__sidebar{width:0;border-right-width:0;}}
@@ -197,7 +204,15 @@ a { color: var(--color-primary); }
  * the initial `visible`, so a mode switch alone hands the page ~200ms of dead clicks. Measured: with
  * only `visibility:hidden`, elementFromPoint over the nav toggle returned the backdrop.
  * Mobile: the sidebar becomes an off-canvas drawer opened by the topbar toggle. */
-.fdy-app__backdrop{display:none;}
+/* `cursor:pointer` here is not decoration, and not for the mouse. Safari on iOS only
+ * synthesises a `click` from a tap on elements it treats as interactive, and the cursor
+ * being a pointer is one of the signals it uses. The backdrop is a plain <div> with a
+ * click handler — no button, no role, no tabindex — so without this rule a tap on it
+ * produces no click at all: the drawer stays open, the scrim stays dark, and the only way
+ * out is reloading the page. Reported from a real iPhone X; not reproducible in Chromium
+ * with either mouse click or `touchscreen.tap()`, which is why no test in this kit or in
+ * the consuming app had ever caught it. */
+.fdy-app__backdrop{display:none;cursor:pointer;}
 @media (max-width:720px){
   .fdy-app__sidebar{position:fixed;top:0;left:0;bottom:0;height:100dvh;width:16rem;z-index:60;transform:translateX(-100%);transition:transform var(--dur-base) var(--ease-standard);box-shadow:var(--shadow-4);}
   .fdy-app--nav-open .fdy-app__sidebar{transform:translateX(0);}
@@ -322,6 +337,69 @@ a { color: var(--color-primary); }
 .fdy-badge-ov--bottom-right{top:auto;bottom:0;transform:translate(50%,50%);}
 .fdy-badge-ov--bottom-left{top:auto;bottom:0;right:auto;left:0;transform:translate(-50%,50%);}
 
+/* Freeday. Bottom navigation
+ *
+ * The bar a phone application puts its three-to-five most-used destinations on. The kit
+ * had `.fdy-nav--horizontal` for a top-nav application and the off-canvas drawer for a
+ * sidebar one, and nothing for the arrangement almost every phone application actually
+ * uses — which was only noticed when an app shipped to real phones and its owner reached
+ * for a thumb-reachable bar that did not exist.
+ *
+ * Deliberately NOT part of `.fdy-app`'s markup: it is `position:fixed`, so it works from
+ * anywhere inside the shell's content slot, and an application that does not want one
+ * pays nothing. `.fdy-app--has-bottomnav` on the shell is what reserves room for it. */
+.fdy-bottomnav{display:none;}
+@media (max-width:720px){
+  .fdy-bottomnav{
+    display:flex;position:fixed;left:0;right:0;bottom:0;z-index:50;
+    align-items:stretch;justify-content:space-around;gap:var(--space-1);
+    padding:var(--space-2) var(--space-2);
+    /* The home indicator on a notched phone sits over the bottom of the viewport, and a
+     * bar that ignores it puts its labels underneath a physical UI element. Added to the
+     * padding rather than substituted for it, so a phone without one is unaffected. */
+    padding-bottom:calc(var(--space-2) + env(safe-area-inset-bottom,0px));
+    background:var(--color-surface-raised);
+    backdrop-filter:var(--surface-filter);
+    -webkit-backdrop-filter:var(--surface-filter);
+    border-top:var(--bw) solid var(--color-border);
+  }
+  /* Room for the bar, or the last row of every list on every screen sits under it -- and
+     a row you cannot scroll to is a row nobody knows is there. */
+  .fdy-app--has-bottomnav .fdy-app__main{
+    padding-bottom:calc(var(--space-20) + env(safe-area-inset-bottom,0px));
+  }
+}
+.fdy-bottomnav__item{
+  display:flex;flex:1 1 0;min-width:0;flex-direction:column;align-items:center;
+  justify-content:center;gap:2px;
+  /* 44px is the smallest target a thumb hits reliably; anything under it turns a tap into
+   * a retry, and this bar is pressed more than any other control in the application. */
+  min-height:2.75rem;padding:var(--space-1);
+  border-radius:var(--radius-md);
+  font-family:var(--font-body);font-size:var(--text-xs);font-weight:var(--weight-medium);
+  color:var(--color-text-muted);text-decoration:none;text-align:center;
+  transition:background var(--dur-fast) var(--ease-standard),
+             color var(--dur-fast) var(--ease-standard);
+}
+.fdy-bottomnav__item:hover{color:var(--color-text);}
+.fdy-bottomnav__item:focus-visible{outline:none;box-shadow:0 0 0 2px var(--color-primary);}
+/* The current destination is marked by `aria-current="page"`, the same attribute
+ * `.fdy-nav__item` uses -- one contract for "you are here", not two. */
+.fdy-bottomnav__item[aria-current="page"]{
+  color:var(--color-primary-strong);background:var(--color-primary-soft);
+}
+.fdy-bottomnav__icon{display:block;width:1.25rem;height:1.25rem;flex:none;}
+.fdy-bottomnav__icon svg{display:block;width:100%;height:100%;}
+/* Labels are never dropped in favour of icons alone: an icon-only bar asks every user to
+ * have already learned what each glyph means, and the people using this kit's applications
+ * on a phone are often using them for the first time. Long labels ellipsis rather than
+ * wrap, so the bar keeps one height. */
+.fdy-bottomnav__label{
+  display:block;max-width:100%;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;
+  line-height:1.2;
+}
+@media (prefers-reduced-motion:reduce){.fdy-bottomnav__item{transition:none;}}
+
 /* Freeday. Breadcrumb */
 .fdy-breadcrumb{font-size:var(--text-sm);}
 .fdy-breadcrumb__list{display:flex;flex-wrap:wrap;align-items:center;gap:var(--space-2);list-style:none;margin:0;padding:0;}
@@ -334,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) */
@@ -1121,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.3.1"` (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.3.1",
+  "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"
@@ -92,7 +96,7 @@
   "scripts": {
     "build": "node tokens/build.mjs",
     "test": "node --test",
-    "test:browser": "node --test --test-concurrency=3 browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs browser/root-init.mjs browser/upload-states.mjs browser/number.mjs browser/card-stretch.mjs browser/text-override.mjs browser/control-heights.mjs browser/field-width.mjs browser/cfl-multi.mjs browser/cfl-dialog-only.mjs browser/crowding.mjs browser/over-dialog.mjs browser/chart-scale.mjs browser/overlay-stack.mjs browser/chart-a11y.mjs browser/app-shell.mjs browser/picker-states.mjs browser/tabs-strip.mjs browser/cfl-narrow.mjs browser/harness-contract.mjs",
+    "test:browser": "node --test --test-concurrency=3 browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs browser/root-init.mjs browser/upload-states.mjs browser/number.mjs browser/card-stretch.mjs browser/text-override.mjs browser/control-heights.mjs browser/field-width.mjs browser/cfl-multi.mjs browser/cfl-dialog-only.mjs browser/crowding.mjs browser/over-dialog.mjs browser/chart-scale.mjs browser/overlay-stack.mjs browser/chart-a11y.mjs browser/app-shell.mjs browser/bottom-nav.mjs browser/picker-states.mjs browser/tabs-strip.mjs browser/cfl-narrow.mjs browser/harness-contract.mjs",
     "prepack": "node tokens/build.mjs",
     "version": "node tokens/build.mjs && git add dist",
     "typecheck:react": "tsc -p adapters/react/tsconfig.json --noEmit",

package/src/components/app-shell.css

@@ -83,6 +83,13 @@
 .fdy-app__navtoggle:hover{background:var(--color-surface-2);color:var(--color-text);}
 .fdy-app__navtoggle:focus-visible{outline:none;box-shadow:0 0 0 2px var(--color-primary);}
 .fdy-app__navtoggle svg{display:block;width:1.25rem;height:1.25rem;}
+/* --navtoggle-end moves the toggle to the far side of the topbar. The title already
+ * carries `margin-right:auto`, so ordering the toggle last is enough; nothing else needs
+ * to know. On a large phone held in one hand the top-LEFT corner is the hardest place on
+ * the screen for a right thumb to reach, and the toggle is the control most often pressed
+ * there — so this is ergonomics, not taste. Left as an opt-in because a desktop shell that
+ * also puts an avatar on the right has the opposite problem. */
+.fdy-app--navtoggle-end .fdy-app__navtoggle{order:1;}
 /* Desktop collapse: animate width -> 0 (content clips via overflow:hidden; the content area
  * flexes in to fill). Not display:none, so the collapse/expand slides instead of snapping. */
 @media (min-width:721px){.fdy-app--nav-collapsed .fdy-app__sidebar{width:0;border-right-width:0;}}
@@ -118,7 +125,15 @@
  * the initial `visible`, so a mode switch alone hands the page ~200ms of dead clicks. Measured: with
  * only `visibility:hidden`, elementFromPoint over the nav toggle returned the backdrop.
  * Mobile: the sidebar becomes an off-canvas drawer opened by the topbar toggle. */
-.fdy-app__backdrop{display:none;}
+/* `cursor:pointer` here is not decoration, and not for the mouse. Safari on iOS only
+ * synthesises a `click` from a tap on elements it treats as interactive, and the cursor
+ * being a pointer is one of the signals it uses. The backdrop is a plain <div> with a
+ * click handler — no button, no role, no tabindex — so without this rule a tap on it
+ * produces no click at all: the drawer stays open, the scrim stays dark, and the only way
+ * out is reloading the page. Reported from a real iPhone X; not reproducible in Chromium
+ * with either mouse click or `touchscreen.tap()`, which is why no test in this kit or in
+ * the consuming app had ever caught it. */
+.fdy-app__backdrop{display:none;cursor:pointer;}
 @media (max-width:720px){
   .fdy-app__sidebar{position:fixed;top:0;left:0;bottom:0;height:100dvh;width:16rem;z-index:60;transform:translateX(-100%);transition:transform var(--dur-base) var(--ease-standard);box-shadow:var(--shadow-4);}
   .fdy-app--nav-open .fdy-app__sidebar{transform:translateX(0);}

package/src/components/bottomnav.css

@@ -0,0 +1,62 @@
+/* Freeday. Bottom navigation
+ *
+ * The bar a phone application puts its three-to-five most-used destinations on. The kit
+ * had `.fdy-nav--horizontal` for a top-nav application and the off-canvas drawer for a
+ * sidebar one, and nothing for the arrangement almost every phone application actually
+ * uses — which was only noticed when an app shipped to real phones and its owner reached
+ * for a thumb-reachable bar that did not exist.
+ *
+ * Deliberately NOT part of `.fdy-app`'s markup: it is `position:fixed`, so it works from
+ * anywhere inside the shell's content slot, and an application that does not want one
+ * pays nothing. `.fdy-app--has-bottomnav` on the shell is what reserves room for it. */
+.fdy-bottomnav{display:none;}
+@media (max-width:720px){
+  .fdy-bottomnav{
+    display:flex;position:fixed;left:0;right:0;bottom:0;z-index:50;
+    align-items:stretch;justify-content:space-around;gap:var(--space-1);
+    padding:var(--space-2) var(--space-2);
+    /* The home indicator on a notched phone sits over the bottom of the viewport, and a
+     * bar that ignores it puts its labels underneath a physical UI element. Added to the
+     * padding rather than substituted for it, so a phone without one is unaffected. */
+    padding-bottom:calc(var(--space-2) + env(safe-area-inset-bottom,0px));
+    background:var(--color-surface-raised);
+    backdrop-filter:var(--surface-filter);
+    -webkit-backdrop-filter:var(--surface-filter);
+    border-top:var(--bw) solid var(--color-border);
+  }
+  /* Room for the bar, or the last row of every list on every screen sits under it -- and
+     a row you cannot scroll to is a row nobody knows is there. */
+  .fdy-app--has-bottomnav .fdy-app__main{
+    padding-bottom:calc(var(--space-20) + env(safe-area-inset-bottom,0px));
+  }
+}
+.fdy-bottomnav__item{
+  display:flex;flex:1 1 0;min-width:0;flex-direction:column;align-items:center;
+  justify-content:center;gap:2px;
+  /* 44px is the smallest target a thumb hits reliably; anything under it turns a tap into
+   * a retry, and this bar is pressed more than any other control in the application. */
+  min-height:2.75rem;padding:var(--space-1);
+  border-radius:var(--radius-md);
+  font-family:var(--font-body);font-size:var(--text-xs);font-weight:var(--weight-medium);
+  color:var(--color-text-muted);text-decoration:none;text-align:center;
+  transition:background var(--dur-fast) var(--ease-standard),
+             color var(--dur-fast) var(--ease-standard);
+}
+.fdy-bottomnav__item:hover{color:var(--color-text);}
+.fdy-bottomnav__item:focus-visible{outline:none;box-shadow:0 0 0 2px var(--color-primary);}
+/* The current destination is marked by `aria-current="page"`, the same attribute
+ * `.fdy-nav__item` uses -- one contract for "you are here", not two. */
+.fdy-bottomnav__item[aria-current="page"]{
+  color:var(--color-primary-strong);background:var(--color-primary-soft);
+}
+.fdy-bottomnav__icon{display:block;width:1.25rem;height:1.25rem;flex:none;}
+.fdy-bottomnav__icon svg{display:block;width:100%;height:100%;}
+/* Labels are never dropped in favour of icons alone: an icon-only bar asks every user to
+ * have already learned what each glyph means, and the people using this kit's applications
+ * on a phone are often using them for the first time. Long labels ellipsis rather than
+ * wrap, so the bar keeps one height. */
+.fdy-bottomnav__label{
+  display:block;max-width:100%;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;
+  line-height:1.2;
+}
+@media (prefers-reduced-motion:reduce){.fdy-bottomnav__item{transition:none;}}

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 };