# Kutby Header — Production Finalization Report

**Date:** 2026-07-24  
**Sprint:** Header Finalization (production ready)  
**Status:** Header enters maintenance mode  

---

## Completed improvements

1. **Visibility SSOT** — `HeaderVisibility` shared by `HeaderPage` + `Dashboard` (incl. experimental denylist).
2. **Height SSOT** — `--kutby-header-height` via Design Tokens only; inline height styles removed.
3. **Stub features gated** — ThemeToggle, AccountLink, SocialIcons experimental filters; unwired from layouts; hidden from Admin.
4. **Sticky ownership** — moved from `FrontendHooks` to `HeaderModule`; documented.
5. **CSS isolation** — shared `header.css` + per-layout `layout-*.css`; intentional Classic / Modern / Centered differences; token-only visuals.
6. **Modern sticky stack** — announcement + header stick together via `kutby-header-stack`.
7. **Component hygiene** — Navigation position via `$args` only; Search unique ids + icon form a11y; Logo/MobileToggle unused ctx cleaned.
8. **A11y quick wins** — focus rings, Escape + `hidden` + resize sync in `navigation.js`.
9. **Docs** — `HEADER-ENGINE.md` reference for Footer and future engines.

---

## Files changed (this finalization)

| Area | Paths |
|------|--------|
| Services | `inc/Header/Services/HeaderVisibility.php` |
| Layouts | `ClassicHeader.php`, `ModernHeader.php`, `CenteredHeader.php` |
| Components | `Logo`, `Navigation`, `Search`, `MobileToggle`, `ThemeToggle`, `AccountLink`, `SocialIcons` |
| Module / Hooks | `HeaderModule.php`, `FrontendHooks.php` |
| Admin | `HeaderPage.php`, `Dashboard.php` |
| Options / Tokens | `Schema.php` (header), `Tokens.php` |
| CSS | `layout/header.css`, `components/header/layout-*.css`, `src/css/main.css`, `assets/css/main.css` |
| JS | `assets/js/navigation.js` |
| Docs | `HEADER-ENGINE.md`, `ARCHITECTURE.md` (link) |

---

## Architecture impact

**None on pipeline.** Registry → Manager → Renderer → Layout → Components unchanged.

Module boundary clarified (sticky + layout body class owned by HeaderModule).

---

## Performance impact

- Negligible: removed conditional per-layout enqueue (tiny CSS now always imported with main — avoids prod/dev skew and double-load risk).
- Context still memoized; one layout instance per request.
- Experimental components short-circuit before DOM.

---

## Developer experience

- One visibility API for all Admin/save consumers.
- Clear experimental gate pattern for unfinished components.
- `HEADER-ENGINE.md` is the Footer copy-paste contract.

---

## Remaining technical debt (non-blocking)

- Admin layout field list requires save/reload to refresh (no live conditional JS).
- Mobile nav: no focus trap / outside-click (dedicated a11y sprint).
- Experimental Social/Account/ThemeToggle incomplete (intentionally gated).
- Static component API (acceptable until heavier testing needs).
- Registry silent id overwrite on `add()`.

---

## Intentionally postponed

- Header Builder, Mega Menu, Mobile Header Engine, dark-mode ThemeToggle behavior, WooCommerce account destinations, SVG social set, live Admin field dependencies, Hero/Footer implementation.

---

## Production readiness score

**86 / 100**

Architecture approved and frozen. Quality gaps are documented debt, not blockers for Footer.
