KDS docs mobile responsiveness

develop specs/develop/docs-mobile-responsiveness.kmd

Audit + ongoing contract that every page on `kds.koder.dev` is usable on mobile screens (Compact width < 600 dp). Material parity (`/develop` cross-cutting concern). Distinct from `specs/web-apps/responsiveness.kmd` (which covers Koder web apps); this spec covers the docs site itself.

When this spec applies

Primary triggers

Audit KDS mobile responsiveness

All triggers

Verify a KDS page works on mobile
Add responsive rules to a new docs page kind
Audit mobile-broken pages after a site refactor

Spec — KDS docs mobile responsiveness

Facet Develop of Koder Design. Material parity: https://m3.material.io/develop (cross-cutting concern).

Scope

Every public page under https://kds.koder.dev/{locale}/** (and hub.koder.dev design-related pages) MUST function on Compact width (< 600 dp viewport).

In-scope page kinds:

Component reference (/reference/components-*.html)
Theme / facet pages (/themes/*, /foundations/*)
Tools (/themer/, /tools/contrast/, /migrate/*, /blog/)
Style preset pages (/style/*.html)
Spec catalogs (/specs/*, /develop/*)
Landing pages (homepage, locale roots)

Out of scope:

The Themer's full-fidelity 3-pane mode (mobile uses bottom-sheet fallback — already specified in tools/theme-builder.kmd § R1)
Authoring / admin tooling (not user-facing)

R1 — Breakpoint contract

Per app-layout/window-size-classes.kmd:

Class	Viewport width	KDS adapts to
Compact	< 600 dp	Mobile layout (single column, bottom-anchored nav, drawer behind icon)
Medium	600-839 dp	Tablet layout (split columns possible, side rail)
Expanded	840-1199 dp	Desktop default (side drawer, multi-column code samples)
Large	≥ 1200 dp	Wide desktop (more whitespace, code samples side-by-side)

KDS does NOT define new breakpoints — adheres to canonical ones.

R2 — Mandatory mobile behaviors

Behavior	Why
Side nav drawer collapses to hamburger icon	Saves screen width
Code samples scroll horizontally if too wide	Don't force line-wrap (breaks readability)
Tables scroll horizontally inside a scrollable wrapper	Preserves column alignment
Search field full-width below header	One-thumb reach
Top app bar with title only (actions overflow to menu)	Avoid cramped 5-icon row
Anchor links in TOC collapse to expand-on-tap section	Long TOCs unusable on mobile
Embedded interactive demos respect 100% width	Sliders / pickers must fit
Tap targets ≥ 48 × 48 dp	All interactive elements
Font size ≥ 16 px for body text	iOS auto-zoom trigger; readability

R3 — Forbidden mobile patterns

❌ Hover-only tooltips (mobile has no hover; rely on long-press fallback per components/tooltips.kmd § R1)
❌ Horizontal scrollbars in content (force ergonomic single-column layout)
❌ Modal dialogs wider than viewport
❌ Fixed-position elements covering > 30% of viewport
❌ Code blocks without horizontal scroll fallback (breaks layout if too wide)
❌ Tables with > 4 columns at Compact width (collapse to card layout)
❌ font-size smaller than 16 px on body text (iOS auto-zoom)
❌ Hardcoded width: 800px (or similar absolute values) — always use percentage / flex / breakpoint-conditional CSS

R4 — Automated audit

design-gen mobile-audit (new make target) runs Lighthouse Mobile preset + custom checks on every generated page:

Check	Pass criterion
Lighthouse Mobile score	≥ 90 overall
Viewport meta tag present	`<meta name="viewport" content="width=device-width, initial-scale=1">`
No horizontal scroll on root container	`document.body.scrollWidth ≤ viewport.width`
All tap targets ≥ 48 × 48 dp	Custom JSON-LD audit on rendered HTML
Code blocks have `overflow-x: auto`	CSS audit
Tables wrapped in `.responsive-table`	DOM audit

Run on every deploy + nightly cron. Failed pages open auto-tickets in projects/koder-stack.

R5 — Mobile-specific test viewports

CI runs the audit at:

360 × 800 dp (Android stock, common)
390 × 844 dp (iPhone 15)
320 × 568 dp (small mobile — Apple iPhone SE 1st gen, edge case)

If any of these breaks, the page fails the audit.

R6 — Designer-author responsibilities

When adding a new page kind:

Test on mobile manually (DevTools responsive mode at 360 dp)
Add the page kind to design-gen mobile-audit known kinds
Document any mobile-specific behavior in the page's kind file
Verify the page's first-screenshot renders correctly at 360 dp

R7 — Existing live bugs (snapshot at spec ratification)

At time of writing (2026-05-11), known mobile bugs in production (none — fixed in 2026-05-11 commit ba0f74449c typography wave 1 + responsive sweep):

✓ Top nav scroll-x works
✓ Padding correct at Compact
✓ Breadcrumb wraps
✓ Code blocks edge-to-edge
✓ Settings rail full-viewport

Future regressions: tracked via projects/koder-stack#129 (Google Fonts sweep + #161 mobile-responsiveness baseline tickets).

R8 — Accessibility cross-link

Mobile responsiveness ≠ accessibility, but they overlap:

Tap target size (≥ 48 dp) is BOTH (mobile usability + a11y)
Font size (≥ 16 px) is BOTH (mobile zoom + low-vision)
Color contrast applies regardless of viewport (see tools/contrast-checker.kmd)

This spec adds mobile-only checks; accessibility checks remain governed by separate specs.

R9 — Tracking when refactoring

Major site refactors (e.g., the 2026-04 landing redesign, the cluster 4 site updates) MUST run mobile-audit before deploy. Mobile audit is a release blocker:

make mobile-audit
# Pass → deploy proceeds
# Fail → block deploy + open tickets

Cross-link

app-layout/window-size-classes.kmd — breakpoint contract source
web-apps/responsiveness.kmd — sibling spec for product web apps
components/navigation.kmd — drawer-as-modal pattern on Compact
components/tabs.kmd — fixed-vs-scrollable rule based on width
components/tooltips.kmd — long-press fallback on touch
tools/contrast-checker.kmd — sibling cross-cutting tool

Implementation tracking

tools/design-gen/internal/audit/mobile.go — auditor (new file)
Makefile target mobile-audit (new)
CI workflow gate on deploy

References

specs/web-apps/responsiveness.kmd
specs/app-layout/window-size-classes.kmd
specs/components/navigation.kmd
specs/components/tabs.kmd