@cahyo-dimas/freeday 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -9,6 +9,74 @@ 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.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`)
+menunjuk satu kalimat di COMPONENTS.md — *"the markup below is for stacks without an adapter (and is
+what the wrapper renders)"* — lalu menunjukkan bahwa untuk `.fdy-app__main` kalimat itu tidak benar.
+Markup mentahnya membawa `id="main"`; ketiga wrapper typed tidak membawa apa pun. Jadi `.fdy-skip`
+yang didokumentasikan dengan `href="#main"` merender tautan yang menerima fokus lalu tidak
+memindahkan siapa pun. Ini bentuk kegagalan yang paling sulit terlihat: tak ada galat, tak ada yang
+tampak salah, dan pemeriksaan visual tak akan pernah menangkapnya — app yang melaporkannya memilih
+**tidak memasang tautan lewati sama sekali**, karena tak ada yang bisa dituju.
+
+### Fixed
+- **`FdyAppShell` merender `<main id="main" tabindex="-1">` di Vue, React dan Blazor** (`#056` §1).
+  `id` menyamakan wrapper dengan markup mentah yang sudah didokumentasikan; `tabindex="-1"` diambil
+  dari `docs/reference-screen.html`, yang selama ini lebih benar daripada skeleton di COMPONENTS.md —
+  tanpa itu tautan fragmen menggulung halaman tanpa memindahkan fokus, sehingga Tab berikutnya
+  melanjutkan dari tempat pembaca tadi, bukan dari tempat ia dikirim. Skeleton COMPONENTS.md ikut
+  disamakan. Dijaga uji paritas baru di `browser/adapter.mjs` (Vue, React) dan
+  `test/blazor/FdyAppShellTests.cs` (Blazor).
+
+### Docs
+- **`.fdy-title-page` menyebut level headingnya di dalam shell** (`#056` §2). Tabel tipografi
+  menuliskan `<h1>`, "One per screen", sementara `docs/reference-screen.html` memakai
+  `<h2 class="fdy-title-page">` karena `.fdy-app__title` di topbar sudah menjadi `<h1>` layar itu.
+  Menyusun keduanya persis seperti dokumentasi menghasilkan dua `<h1>` — yang justru dilarang
+  kalimat di sebelahnya. Tabelnya kini menyebut kedua kasus; keputusan yang dipakai adalah keputusan
+  yang sudah diambil reference screen, bukan keputusan baru.
+
 ## [3.3.0] - 2026-08-28
 
 **Tiga kemampuan yang sebenarnya sudah ada di kit ini, dan tak satu pun bisa diminta.** `#054` dan

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
@@ -156,7 +165,10 @@ positioning rules differ, and only above the breakpoint. It also changes which s
 On the raw path, if you add or remove the class yourself, call
 **`FreedayAppShell.refresh(root)`** afterwards — the shell has to re-read the DOM, or `inert` and
 `aria-expanded` keep describing the arrangement you just left.
-- Also: `.fdy-skip`, the skip-to-content link, first child of the shell.
+- Also: `.fdy-skip`, the skip-to-content link, first child of the shell. Its target is
+  `__main`, which carries `id="main"` **and `tabindex="-1"`** — without the latter a fragment
+  link scrolls the page without moving focus, so the next Tab resumes from where the reader
+  was, not from where they were sent. The typed wrappers render both.
 - **Behaviour: `freeday-app-shell.js`.** Opt in with `data-fdy-app` on the root. The markup below
   is unchanged. It owns the toggle in both modes plus everything an overlay needs that hand-rolling
   reliably forgets: Escape, backdrop click, closing when a `.fdy-nav__item` is followed, focus moved
@@ -209,7 +221,7 @@ tall containing block. The brand goes in the **sidebar** (sized to match the top
       <h1 class="fdy-app__title">Invoices</h1><!-- auto-spacer: pushes what follows right -->
       <!-- topbar actions -->
     </header>
-    <main class="fdy-app__main" id="main"><!-- .fdy-page goes here --></main>
+    <main class="fdy-app__main" id="main" tabindex="-1"><!-- .fdy-page goes here --></main>
   </div>
 
   <div class="fdy-app__backdrop"></div>
@@ -283,7 +295,7 @@ One role per level of hierarchy. Never re-use a card title for a page title.
 | Class | Element | Use |
 |---|---|---|
 | `.fdy-eyebrow` | `<p>` | Small uppercase label above a title. Optional. |
-| `.fdy-title-page` | `<h1>` | One per screen. |
+| `.fdy-title-page` | `<h1>` · `<h2>` in a shell | One `<h1>` per screen. Standalone page: `<h1>`. Inside `.fdy-app`, the topbar's `.fdy-app__title` is already that `<h1>`, so the page title steps down to `<h2>` — as `docs/reference-screen.html` does. |
 | `.fdy-title-section` | `<h2>` | A region inside the page. |
 | `.fdy-title-card` | `<h3>` | A title inside a card or row (`.fdy-card__title` is equivalent). |
 | `.fdy-text-muted` · `.fdy-text-subtle` | any | Secondary / tertiary text colour. |
@@ -1493,6 +1505,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.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.3.0)
+[![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)
 
 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`.

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

package/adapters/blazor/FdyAppShell.razor

@@ -41,7 +41,7 @@
             @TopbarContent
         </header>
 
-        <main class="fdy-app__main">
+        <main class="fdy-app__main" id="main" tabindex="-1">
             @ChildContent
         </main>
     </div>

package/adapters/react/components/FdyAppShell.tsx

@@ -186,7 +186,7 @@ export function FdyAppShell(props: FdyAppShellProps): JSX.Element {
           {props.topbar}
         </header>
 
-        <main className="fdy-app__main">{props.children}</main>
+        <main className="fdy-app__main" id="main" tabIndex={-1}>{props.children}</main>
       </div>
 
       <div

package/adapters/vue/components/FdyAppShell.vue

@@ -180,7 +180,7 @@ onBeforeUnmount((): void => {
         <slot name="topbar" />
       </header>
 
-      <main class="fdy-app__main">
+      <main class="fdy-app__main" id="main" tabindex="-1">
         <slot />
       </main>
     </div>

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

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

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.0"` (public npm package). `dist/` is
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^3.4.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.0",
+  "version": "3.4.0",
   "description": "Freeday: token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",
@@ -92,7 +92,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;}}