@naeil/ui 0.4.0 → 0.5.0

package/docs/design/v2-migration.md

@@ -2,22 +2,25 @@
 
 이 안내는 `@naeil/ui`의 기본 모양과 재사용 규칙을 설명한다. 패키지 소비와 소비 사이트 배포는 별도 작업이다.
 
-이 안내는 **@naeil/ui 0.4.0**의 CSS·API·패키지 경계를 대상으로 한다. UI v2는 디자인 세대 이름이며 npm 2.0을 뜻하지 않는다. 기존 npm 0.2.0에 이 기능이 모두 구현됐다고 가정하지 않는다. Registry의 게시 여부와 latest 태그는 별도로 확인한다.
+이 안내는 **@naeil/ui 0.5.0 릴리스 후보**의 CSS·API·패키지 경계를 대상으로 한다. 최종 소스·archive 검증과 registry 게시, 새 Docs·운영 사이트 배포는 아직 완료로 기록하지 않는다. 2026-10-11에 확인한 npm 0.4.0 게시·latest와 당시 소비 앱·Docs·운영 사이트 결과는 [0.4.0 게시 기록](https://github.com/naeil-dev/naeil-ui/blob/main/docs/design/naeil-brand-0.4.0-publication.md)으로 유지한다. UI v2는 디자인 세대 이름이며 npm 2.0을 뜻하지 않는다.
 
 ## 시작하기
 
-React 19/ReactDOM 19와 Tailwind 4 앱에서 `/ui`를 사용한다. API 키와 Next.js는 필요 없다. 소비 앱에서 정확한 버전을 지정한다.
+React 19/ReactDOM 19와 Tailwind 4 앱에서 `/ui` 또는 선택적 `/naeil-header`를 사용한다. API 키와 Next.js는 필요 없다. 후보 검증 중에는 저장소에서 빌드·pack한 archive를 소비 앱에 설치한다.
 
 ```sh
-pnpm add --save-exact @naeil/ui@0.4.0
-# npm install --save-exact @naeil/ui@0.4.0
+# 이 저장소에서:
+pnpm build:pkg
+npm pack --ignore-scripts --pack-destination /tmp
+# 소비 앱에서:
+pnpm add --save-exact /tmp/naeil-ui-0.5.0.tgz
 ```
 
-이 명령은 해당 버전이 registry에 있을 때 사용할 수 있다. 게시 전 소스 검증은 저장소에서 `pnpm build:pkg` 후 `npm pack --ignore-scripts --pack-destination /tmp`를 실행하고, 소비 앱에 `/tmp/naeil-ui-0.4.0.tgz`를 설치한다. [독립 React 예제](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/examples/react/README.md)와 [검증/릴리스 정책](../package-release.md)을 참고한다.
+0.5.0 registry 게시가 실제 확인된 뒤에는 `pnpm add --save-exact @naeil/ui@0.5.0`을 사용한다. 설치 명령을 문서에 쓰는 것만으로 게시가 완료되지는 않는다. [독립 React 예제](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/examples/react/README.md)와 [검증/릴리스 정책](../package-release.md)을 참고한다.
 
 공통 UI 소비에는 Supabase, 21st 또는 다른 API 키가 필요하지 않다. React/ReactDOM 19는 소비 앱의 peer이며, Next 15/16과 next-intl 4는 호환 경로에 필요한 선택적 peer다. next-themes 0.4와 tailwind-merge 3은 공통 런타임 의존성으로 설치된다. 사이트의 Supabase·MDX·Three 의존성과 코드는 공통 소비 경계에서 제외했다.
 
-버전을 생략한 설치는 registry의 latest 태그를 따른다. 이 안내와 동일한 경계를 사용하려면 0.4.0을 지정하고 [변경 기록](../../CHANGELOG.md)을 확인한다.
+버전을 생략한 설치는 registry의 latest 태그를 따른다. 이 안내와 동일한 경계를 사용하려면 검증된 0.5.0 후보 archive를 사용하고, 게시 확인 후에는 0.5.0을 지정한다. 업그레이드 전에 [변경 기록](../../CHANGELOG.md)을 확인한다.
 
 Tailwind 4를 사용하는 앱의 전역 CSS에서 공통 스타일을 한 번 불러온다.
 
@@ -55,8 +58,37 @@ Select는 값 선택, DropdownMenu는 행동 선택에 사용한다. Switch와 C
 - 레이블·도움말·오류 문구는 소비 화면이 연결한다. Input의 `aria-invalid`와 `aria-describedby`를 사용하고, 로딩 중에는 Button의 `disabled`와 `aria-busy`를 함께 지정한다.
 - 성공·경고·오류·안내에는 Badge의 `success`, `warning`, `error`, `info` variant를 사용할 수 있다. 색만으로 의미를 전달하지 않는다.
 
+## 브라우저 탭 제목과 파비콘
+
+2026-10-13 승인한 공통 브랜드·콘텐츠 규칙이며, 2026-10-14 사용자 요청으로 naeil.dev의 서비스명을 `.naeil`로 통일했다. 기준은 [DESIGN.md의 Browser identity](../../DESIGN.md#browser-identity--tab-title-and-favicon)이며, 브라우저 탭의 글꼴·크기는 브라우저가 결정한다.
+
+| 화면 | 탭 제목 예시 |
+| --- | --- |
+| naeil.dev 홈 | `.naeil` |
+| Home 홈/소개 화면 | `Naeil Home` |
+| Home 대시보드 | `대시보드 — Naeil Home` |
+| Home API 키 관리 | `API 키 — Naeil Home` |
+| naeil.dev 프로젝트 목록 | `프로젝트 — .naeil` |
+| Home 영문 대시보드 | `Dashboard — Naeil Home` |
+
+- 이름이 있는 페이지는 `페이지 이름 — 서비스 이름`으로 작성한다. 구분자는 양옆 공백이 있는 em dash(` — `)이며, 서비스 이름은 한 번만 붙인다.
+- 서비스 홈/소개 화면은 서비스 이름만 사용할 수 있다. 대시보드처럼 이름이 있는 업무 화면은 첫 진입 경로이더라도 페이지 이름을 포함한다.
+- 서비스 이름은 naeil.dev의 경우 `.naeil`, Home의 경우 `Naeil Home`으로 고정한다. 앞의 마침표까지 공식 이름에 포함하며 로고와 탭 제목·공유 메타데이터에 같은 표기를 쓴다. 다른 서비스는 앱 설정에 공식 표기를 한 번 정의해 재사용한다.
+- 페이지 이름은 현재 UI 언어에 맞춰 번역하고, 서비스 이름의 대소문자·띄어쓰기는 언어가 바뀌어도 유지한다. 본문 제목이나 글 제목을 사용해 현재 화면을 식별할 수 있게 한다.
+- 같은 서비스의 페이지를 이동할 때 파비콘은 유지한다. 승인된 브랜드 자산을 사용하며 파일·메타데이터·앱 manifest와 배포는 소비 서비스가 관리한다.
+
+Next.js 소비자는 layout의 metadata title 기본값/템플릿과 페이지별 title을 연결하고, 일반 React 앱은 라우터의 페이지 메타데이터에서 같은 규칙으로 document.title을 설정한다. 제목 조립은 한 곳에서 담당해 `API 키 — Naeil Home — Naeil Home`처럼 중복되지 않게 한다. Navigation이나 Logo 렌더링에 문서 제목 변경을 숨겨 넣지 않는다.
+
+적용 확인은 실제 브라우저에서 홈·하위 페이지의 직접 진입, 클라이언트 경로 이동, 뒤로 가기, 언어 전환 후 제목과 파비콘을 확인한다. 제목은 현재 페이지와 일치하고 서비스 접미사가 중복되지 않아야 하며, 파비콘 파일 요청도 성공해야 한다. 이 문서 변경은 규칙 등록이며 기존 naeil.dev/Home의 메타데이터 수정·배포 완료를 의미하지 않는다.
+
 ## 앱 전체 틀과 콘텐츠 폭
 
+실제 naeil.dev 브랜드 헤더를 이어받는 앱은 선택적 React 전용 `@naeil/ui/naeil-header`의 `NaeilHeader`를 사용한다. 전체 프로젝트 메뉴·헤더 번역·테마/선택적 언어 컨트롤·toolbar·반응형 스타일을 한 모듈에서 제공하므로 소비 앱에 다시 복사하지 않는다. 소비 앱은 기존 theme provider, 라우팅·저장 guard, 현재 언어와 실제 인증 슬롯을 연결한다. 언어 변경을 지원하지 않으면 `onLocaleChange`를 생략한다. [전체 헤더 계약](../components/naeil-header.md)을 참조한다.
+
+이 브랜드 헤더는 고정 높이 65px, 최대 폭 1280px, 좌우 여백 24px를 사용한다. 본문·푸터의 제품별 폭과 독립적이다. 소비 앱은 main·sticky 영역과 초점/anchor 이동에 `calc(var(--ui-navigation-height) + 1px)`만큼 여유를 둔다. 다섯 장식 이미지는 공식 `https://naeil.dev/images/*.png` URL을 참조하므로 네트워크가 필요하다. 이미지 바이트는 npm에 포함하지 않으며 재배포 출처·권리 미해결 사항은 [제3자 고지](../../THIRD_PARTY_NOTICES.md)에 유지한다.
+
+다른 제품 메뉴에는 `@naeil/ui/ui`의 범용 `Navigation`과 `SiteFooter`를 조합하고 제품 메뉴 데이터·번역·폭을 소유한다. 기존 `Nav`·`Footer`는 Next/next-intl 호환 API를 유지한다. [범용 API와 마이그레이션 안내](../components/navigation.md)를 참조한다. Naeil Home 운영 적용은 아직 완료되지 않았으며 저장소의 `docs/design/navigation-footer-integration.md`에서 추적한다.
+
 앱의 공통 헤더·메뉴·좌우 여백과 본문의 읽기/설정/목록 폭은 별도로 관리한다. 같은 앱 틀을 사용하는 페이지는 같은 화면 크기·언어·테마에서 메뉴 위치가 유지되어야 한다. 설정 폼을 640px로 제한할 때 헤더까지 그 폭에 종속시키지 않는다. 변동하는 계정 수·상태 요약도 메뉴를 밀어내지 않도록 배치한다.
 
 아래는 소비 앱의 구성 예이며 새 패키지 API가 아니다. `product-frame`과 최대 폭·여백은 제품에서 소유하고 정한다. 공통 숫자 토큰은 `src/tokens/*.json`을 기준으로 한다.
@@ -125,7 +157,7 @@ Storybook의 로컬 폰트 import는 예시다. 그대로 앱 전역에 모든
 
 ## 개별 컴포넌트 안내
 
-[13개 사용 안내](../components/README.md)는 실제 wrapper API·기본값, 키보드, 상태, 레이블·오류 연결, 재정의 책임을 설명한다. Storybook의 각 `UI / 컴포넌트 / Docs`와 `Usage`에서 같은 안내와 실행 예시를 확인한다. [지원 범위와 수동 점검](public-ui-support.md)은 자동 검사와 실제 보조 기술·운영체제 검증의 차이를 기록한다.
+[컴포넌트 사용 안내](../components/README.md)는 13개 primitive와 Navigation·SiteFooter·전체 NaeilHeader의 실제 wrapper API·기본값, 키보드, 상태, 레이블·오류 연결, 재정의 책임을 설명한다. 현재 로컬 Storybook은 UI 15개와 Brand 2개, 총 17개 Docs를 제공한다. 각 `Docs`·`Usage`와 `Brand / NaeilHeader / JapaneseApplication`에서 안내와 실행 예시를 확인한다. 이는 새 hosted Docs 배포 완료를 뜻하지 않는다. [지원 범위와 수동 점검](public-ui-support.md)은 자동 검사와 실제 보조 기술·운영체제 검증의 차이를 기록한다.
 
 ## 확인 방법
 
@@ -138,7 +170,7 @@ Storybook의 로컬 폰트 import는 예시다. 그대로 앱 전역에 모든
 
 ## 0.3 package boundary
 
-`/ui` is the React core. Root imports preserve Nav, Footer, Logo, LocaleSwitcher, ThemeProvider, ThemeToggle, ThemeToggleIcon, PageTitle, SectionTitle and their class helpers, but root has static Next/next-intl dependencies. React-only apps must use `/ui`, `/utils` and appropriate shared deep modules. `next-themes` is a React runtime library; it does not require Next.js. Fonts remain consumer-owned.
+The heading retains the original 0.3 migration anchor; the allowlist below reflects the 0.5.0 candidate additions. `/ui` is the React core. The opt-in `/naeil-header` is the canonical complete branded header, also React-only. Root imports preserve Nav, Footer, Logo, LocaleSwitcher, ThemeProvider, ThemeToggle, ThemeToggleIcon, PageTitle, SectionTitle and their class helpers, but root has static Next/next-intl dependencies. React-only apps must use `/ui`, `/utils` and appropriate shared deep modules. `next-themes` is a React runtime library; it does not require Next.js. Fonts remain consumer-owned.
 
 Next.js `^15 || ^16` and next-intl `^4` are optional peers. Install both when using root, Nav, Footer or `i18n/routing`. This is an existing compatibility contract, not a claim that every peer combination has browser validation; the clean Next fixture checks Next 16.1.7. React/ReactDOM `^19` come from the host. Tailwind 4 is the documented styling pipeline. Explicit `className`, Radix props, Toaster options and theme-provider props remain consumer overrides.
 
@@ -155,6 +187,8 @@ components/ui/checkbox
 components/ui/dialog
 components/ui/dropdown-menu
 components/ui/input
+components/ui/navigation
+components/ui/site-footer
 components/ui/select
 components/ui/sonner
 components/ui/switch
@@ -173,13 +207,13 @@ i18n/config
 i18n/routing
 ```
 
-`components/index` has the same framework requirements as root. `/utils` and `lib/utils` remain aliases for `cn`. `i18n/config` preserves the compatibility locale names; products may instead own their locale list and routing. There are no open-ended component/lib/i18n export patterns. Root, `/ui`, `/utils`, `/theme.css`, `/globals.css` and `/components.css` remain public.
+`components/index` has the same framework requirements as root. `/utils` and `lib/utils` remain aliases for `cn`. `i18n/config` preserves the compatibility locale names; products may instead own their locale list and routing. There are no open-ended component/lib/i18n export patterns. Root, `/ui`, `/utils`, `/theme.css`, `/globals.css` and `/components.css` remain public; `/naeil-header` is the explicit new opt-in entry. It is not an open-ended component export pattern.
 
 Every excluded source path stays in this repository for the brand/example website. Move any local-source consumer use into the consumer application before upgrading:
 
 | Previously declared source path | Ownership/migration |
 | --- | --- |
-| `components/nav-wrapper`, `components/nav-server-wrapper` | Compose preserved Nav and its slots in your app; your app loads users/sessions. |
+| `components/nav-wrapper`, `components/nav-server-wrapper` | Use `/naeil-header` for the canonical whole header, or preserve Nav compatibility through your own adapter; your app loads users/sessions. |
 | `components/footer-wrapper` | Compose preserved Footer with your app's Link. |
 | `components/auth-slot` | App-owned account UI, logout action and avatar policy; pass it through Nav slots. |
 | `components/hero-scene`, `components/hero-section`, `components/paraglider-cursor` | Website scene/cursor source, assets and Three dependencies stay website-owned. |
@@ -196,7 +230,7 @@ The reachable Next consumer's observed deep imports (Nav, Footer, ThemeProvider,
 
 ## Demand-led extension
 
-Version 0.3.0 also adds `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` and `Textarea` to `/ui`, plus exact `components/ui/tabs` and `components/ui/textarea` deep entries. Existing root stays the brand/framework barrel. No new dependency or existing default is changed. See the [13-family index](../components/README.md), [Tabs defaults/mount responsibilities](../components/tabs.md), [native Textarea contract](../components/textarea.md), [field/native-radio composition](../components/composition.md), and [demand decision](component-demand.md). Publishing does not update consumers that use locally copied primitives.
+Version 0.3.0 also adds `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` and `Textarea` to `/ui`, plus exact `components/ui/tabs` and `components/ui/textarea` deep entries. Existing root stays the brand/framework barrel. No new dependency or existing default is changed. See the [component index](../components/README.md), [Tabs defaults/mount responsibilities](../components/tabs.md), [native Textarea contract](../components/textarea.md), [field/native-radio composition](../components/composition.md), and [demand decision](component-demand.md). Publishing does not update consumers that use locally copied primitives.
 
 
 ## Brand Logo integration (0.4.0)
@@ -224,6 +258,6 @@ Root and `components/index` continue to export Logo; root still has the existing
 - Default accessible name is naeil with role=img. Use `label={null}` for decorative use and name the enclosing link/button. `aria-label` and other standard SVG attributes remain consumer overrides.
 - Nav now uses the horizontal wordmark at 28px; Footer uses the footer lockup at 20px. Their official visible spelling remains `.naeil`: the period marks an ending, followed by tomorrow. Nav's `brandSlot`, brandHref, external/internal links, layout frame and other slots are preserved. Check custom layouts on upgrade because the new artwork has a different width.
 
-The independent kit lives in the repository's `brand/naeil/1.1.1/` directory with its own usage guide, SVG/PNG/icons, OFL and checksums. Copy it for non-React uses without installing @naeil/ui. It is intentionally not copied into the npm tarball. The package carries only generated React artwork and the [Lato notice](../../licenses/Lato-OFL.txt). A favicon is application-owned: Next file conventions can use the kit's favicon.ico, favicon.svg and apple-touch-icon.png; each consumer chooses its own app manifest and deployment.
+The independent kit lives in the repository's `brand/naeil/1.1.1/` directory with its own usage guide, SVG/PNG/icons, OFL and checksums, and is available as a [verified release ZIP](https://github.com/naeil-dev/naeil-ui/releases/download/v0.4.0/naeil-brand-1.1.1.zip). Copy it for non-React uses without installing @naeil/ui. It is intentionally not copied into the npm tarball. The package carries only generated React artwork and the [Lato notice](../../licenses/Lato-OFL.txt). A favicon is application-owned: Next file conventions can use the kit's favicon.ico, favicon.svg and apple-touch-icon.png; each consumer chooses its own app manifest and deployment.
 
 Maintainers run `pnpm build:brand` after explicitly selecting a reviewed version in `brand/current.json`, then `pnpm check:brand`. Package/Storybook builds check that generated artwork, notices and this site's icon files match that version. Shared color tokens and Pretendard do not change. In Storybook, **Brand / Logo / Docs, Usage, Application** demonstrates the actual adapter, canonical SVG comparisons and Nav/Footer composition.

package/docs/package-release.md

@@ -1,12 +1,12 @@
 # Package verification and release policy
 
-This policy covers `@naeil/ui@0.4.0`; the 0.3.0 publication evidence below is retained as history. UI v2 names a design generation, not an npm major. A 0.x minor increment communicates this dependency/export boundary change; future breaking changes must receive an explicit migration and version decision. The historical registry baseline on 2026-10-02 was npm latest at `0.2.0`; the 2026-10-03 publication evidence below records npm 0.3.0, its GitHub Release and live hosted Docs separately. Version-scoped installation is in the [README](../README.md#use-the-ui).
+This policy covers the intended **@naeil/ui 0.5.0 release candidate**. Final source/archive verification, registry publication and new hosted deployments are pending. Verified 0.4.0 (2026-10-11) and 0.3.0 publication evidence below remains dated history. UI v2 names a design generation, not an npm major. Future breaking changes require an explicit migration and version decision. Version-scoped installation is in the [README](../README.md#use-the-ui).
 
 ## Architecture
 
-One repository contains the shared package and the separate Next.js brand/example website. `@naeil/ui/ui` is the React entrypoint. The legacy root is a framework compatibility entry with static Next/next-intl imports, even when selecting only Logo or a heading; React-only consumers use the documented shared deep modules. Next and next-intl are optional peers, not optional behavior inside the root. Supply them when importing that entry, Nav, Footer, or i18n/routing. Theme controls and Toaster use the framework-independent React library next-themes, retained as a runtime dependency.
+One repository contains the shared package and the separate Next.js brand/example website. `@naeil/ui/ui` provides React primitives and generic Navigation/SiteFooter. The opt-in React-only `@naeil/ui/naeil-header` provides the complete actual naeil.dev branded header; see [its consumer contract](components/naeil-header.md). The legacy root is a framework compatibility entry with static Next/next-intl imports, even when selecting only Logo or a heading; React-only consumers use the documented shared deep modules. Next and next-intl are optional peers, not optional behavior inside the root. Supply them when importing that entry, Nav, Footer, or i18n/routing. Theme controls and Toaster use the framework-independent React library next-themes, retained as a runtime dependency.
 
-Website tools remain development dependencies so maintainers can develop both products. npm tarball consumers install only component runtime dependencies and their host React/ReactDOM. Build entries, package exports and packed checks constrain the public boundary. There is no bundled website action, Supabase helper, Three/hero/cursor module, blog engine or application message catalog.
+Website tools remain development dependencies so maintainers can develop both products. npm tarball consumers install only component runtime dependencies and their host React/ReactDOM. Build entries, package exports and packed checks constrain the public boundary. There is no bundled website action, Supabase helper, Three/hero/cursor module, blog engine or full application message catalog. The opt-in header includes only its three header dictionaries and canonical project catalog. Its five decorative images reference official `https://naeil.dev/images/*.png` URLs and require network access; no image bytes are bundled, and unresolved artwork redistribution provenance remains in [third-party notices](../THIRD_PARTY_NOTICES.md).
 
 ## Checks
 
@@ -31,6 +31,15 @@ pnpm test:browser
 
 `check:package:boundary` inspects an actual `npm pack --ignore-scripts` archive for every declared export, runtime dependencies, source aliases, relative imports, required CSS/tokens/documents/notices and forbidden website payload. `check:consumers` separately installs that tarball with npm into two temporary directories. It builds the reusable React example with Vite/Tailwind, type-checks with library checks enabled, imports shared deep modules, checks SSR and CSS, and asserts Next/Supabase/Three are absent. A separate Next production build exercises root exports and the deep paths observed in the reachable Next consumer, with consumer-owned messages and no auth backend. Neither fixture uses repository dependency symlinks. Network access is needed for uncached npm dependencies; temporary installs are removed on completion or failure.
 
+For a frozen release candidate, both archive-producing checks can enforce the reviewed SHA-256 before extraction or consumer installation:
+
+```sh
+# Replace the placeholder with the frozen archive's full lowercase SHA-256.
+NAEIL_UI_EXPECTED_ARCHIVE_SHA256=FULL_LOWERCASE_SHA256 pnpm check:package
+```
+
+Each check hashes its actual `npm pack` output and prints the digest. An unset expectation preserves normal development checks; a defined malformed or mismatched digest fails. Record matching boundary and clean React/Next results against the final archive, then reconcile package metadata, source revision and the consumer lock/archive identities. A provisional pack pass does not verify later documentation or archive bytes.
+
 CI runs these checks and a separate actual Storybook/browser job. Configured browser projects run Chromium, Firefox and WebKit in CI. Local Chromium/WebKit results and the Firefox environment launch block are distinguished in the [current support matrix](design/public-ui-support.md) and [dated Stage 3 verification](design/public-ui-stage3-verification.md) and [Stage 4 extension verification](design/public-ui-stage4-verification.md); configured CI is not a recorded remote pass. Automated axe/keyboard checks are not manual screen-reader or native Safari certification. The website build checks compatibility independently from package consumption; fonts fetched through next/font may require network access. Supabase OAuth and deployed behavior remain separate checks.
 
 At baseline `bcf99fca3467ae2b1cd29d54fa24f2569fb6001c`, both [push CI](https://github.com/naeil-dev/naeil-ui/actions/runs/36945564443) and [PR CI](https://github.com/naeil-dev/naeil-ui/actions/runs/36945943651) passed package-and-site and failed the browser job. Linux Firefox application coverage passed in those runs. The [final correction follow-up](design/public-ui-final-verification.md) preserves that baseline and the initial local freeze evidence, then records independent scoped review approval and successful [push CI](https://github.com/naeil-dev/naeil-ui/actions/runs/36948276767) and [PR CI](https://github.com/naeil-dev/naeil-ui/actions/runs/36948280881) at exact correction commit `9f90493abb4fb1186c948084026c3f4c04074013`. The PR browser job passed 209 tests with 4 expected Firefox/WebKit forced-colors skips; package-and-site and optional helper checks passed. The downloaded CI preview also passed actual Chromium/WebKit subpath navigation/font checks. This acceptance applies to that source; [merged PR checks](https://github.com/naeil-dev/naeil-ui/pull/1/checks) retain the release-preparation checks. Subsequent documentation changes require their own verification. Publication and manual platform acceptance remain separate.
@@ -39,11 +48,24 @@ The explicit font-notice regression gate copies the real React fixture config in
 
 ## Publication and deployment
 
-### 0.4.0 release scope — 2026-10-11
+### Intended 0.5.0 release — pending
+
+The owner authorized npm publication, reviewed main integration and naeil.dev deployment for the whole-header change. Authentication and actual execution are separate from authorization. At this documentation checkpoint no 0.5.0 registry version, tag/release, new hosted Docs, production site deployment or final archive identity is claimed. Freeze and verify the complete candidate before following the procedure below; record each external outcome independently.
+
+### Verified 0.4.0 publication — 2026-10-11
+
+Brand 1.1.1 is independent of npm 0.4.0. Existing imports/props/slots remain supported; Logo variants, grayscale and theme controls accompany the approved `.naeil` identity. Publication, Docs and production results are recorded in the [publication report](https://github.com/naeil-dev/naeil-ui/blob/main/docs/design/naeil-brand-0.4.0-publication.md).
+
+- npm published `@naeil/ui@0.4.0` at `2026-10-11T05:36:58.047Z`; `latest` was verified as `0.4.0`. [Registry/consumer evidence](https://github.com/naeil-dev/naeil-ui/releases/download/v0.4.0/npm-publication-verification.json) records independent empty-cache React/Next installs, types, production builds and browser contracts.
+- [PR #3](https://github.com/naeil-dev/naeil-ui/pull/3) merged as `e8fe5afc13788a0cac0244b72e78975812f4a2ee`; `v0.4.0` points to that source. The [GitHub Release](https://github.com/naeil-dev/naeil-ui/releases/tag/v0.4.0) was published at `2026-10-11T05:45:55Z` with 9 publicly downloadable, byte-verified assets.
+- Frozen candidate, merged-source rebuild and registry download are byte-identical: **108 files**, **131,414 compressed bytes**, **772,862 unpacked bytes**, SHA-256 `77fe024ceb631ea76100fdc687f04ee1ae90bfcbb306629cb9dac854226c724f`.
+- The independent [brand 1.1.1 ZIP](https://github.com/naeil-dev/naeil-ui/releases/download/v0.4.0/naeil-brand-1.1.1.zip) contains 159 files and passes CRC; SHA-256 `a922a7375b5c3be412c759c0f54b532155f260801ea2bdd9cff43eca66848144`. [Brand evidence](https://github.com/naeil-dev/naeil-ui/releases/download/v0.4.0/brand-publication-verification.json) retains the approved extraction checks.
+- [Pages run 38114879574](https://github.com/naeil-dev/naeil-ui/actions/runs/38114879574) deployed that exact source. Actual [hosted checks](https://github.com/naeil-dev/naeil-ui/releases/download/v0.4.0/hosted-docs-verification.json) passed 28 Docs visits, 28 Docs-to-Usage transitions, 4 brand theme checks, 6 exact notices, 4 canonical SVGs, local fonts and pinned links in Chromium/WebKit.
+- Vercel production deployment `6991225824` succeeded for the same source. [Production checks](https://github.com/naeil-dev/naeil-ui/releases/download/v0.4.0/production-verification.json) passed 24 homepage/login conditions on [naeil.dev](https://naeil.dev/) across Korean/English/Japanese, desktop/mobile and light/dark, plus 3 exact deployed icons.
 
-The user authorized repository integration, npm publication, hosted Docs and naeil.dev deployment for the approved `.naeil` logo. Brand 1.1.1 is independent of npm 0.4.0. Existing imports/props/slots remain supported; new Logo variants, grayscale and theme controls justify a minor package increment. New consumers should use the 0.4.0 instructions above the historical records.
+Local unit tests passed 46 tests. [Merged-source CI](https://github.com/naeil-dev/naeil-ui/actions/runs/38113742370) passed package/site checks; both that run and the Docs workflow passed 233 browser tests with 4 expected forced-colors skips. Production page checks do not certify full OAuth authentication. Native/manual platform coverage, print/trademark certification and real-consumer adoption retain their documented limits.
 
-Follow the release procedure below with version 0.4.0, freeze and publish the inspected archive, and record actual registry/tag/site/Docs outcomes in the v0.4.0 GitHub Release. Authorization is not itself evidence of publication. The previous Supabase-local-runtime and manual-device limitations remain documented; verify production behavior at its actual URL after Vercel deployment.
+The npm archive and release tag retain the reviewed source. These maintained documentation updates record the later publication outcome and do not replace the immutable archive or redeploy the unchanged Storybook runtime. The earlier local Supabase environment failure remains dated evidence; actual production homepage/login rendering was verified separately above.
 
 ### Verified 0.3.0 publication — 2026-10-03
 
@@ -58,15 +80,15 @@ The immutable npm archive's bundled guides are the release-preparation snapshot.
 
 ### Release procedure
 
-The Storybook guide URL base and README documentation index use publication-status documentation snapshot `04c5b8cce145a4c387763db6f28d29e62f7664c7`. Runtime/API source-authority links retain tested component snapshot `81fd395031dc5b20074c4d915a8585360ce2d28a`; that original evidence remains valid and is not replaced by this documentation-only snapshot. Verify targets at their respective pinned revisions and preserve original upstream sources, dated approval scope and runtime evidence. Freeze subsequent documentation changes separately from the immutable 0.3.0 archive.
+The deployed Storybook's component guide URL base uses the 0.3.0 publication-status documentation snapshot `04c5b8cce145a4c387763db6f28d29e62f7664c7`. Runtime/API source-authority links retain tested component snapshot `81fd395031dc5b20074c4d915a8585360ce2d28a`; those foundation links remain valid and were rechecked during 0.4.0 hosted verification. The README documentation index points to the maintained main-branch index. Verify targets at their respective revisions and preserve original sources, dated approval scope and runtime evidence. Freeze subsequent documentation changes separately from immutable release archives.
 
 The authorized 0.3.0 release completed main merge, npm 0.3.0, a GitHub Release and hosted Docs as recorded above. The release maintainer performs external authentication and publication; documentation preparation does not itself execute those operations. The automatic verification workflow does not publish or deploy. Record native/manual observations with their actual scope and carry unrun checks as limitations; do not substitute automated WebKit/axe checks or publication authorization for human certification.
 
-The 0.3.0 publication procedure below preserves the distinction between preparation and external verification; future releases require their own version, authorization and frozen source/archive:
+The procedure preserves the distinction between preparation and external verification. Use the intended version in place of `VERSION`; future releases require their own authorization and frozen source/archive:
 
 1. Review the changelog, migration, dated verification and the [2026-10-02 native environment report](design/public-ui-release-validation.md). Its capability blockers leave all native/manual acceptance rows open and add no native component pass. Confirm maintained links, actual Storybook Docs/Usage and legal notices for the intended source. Record unresolved manual coverage without inventing passes.
-2. Build and inspect a fresh archive with `npm pack --ignore-scripts --json --pack-destination /path/to/candidate`; preserve its SHA-256, file list and source revision outside the archive. Run boundary/relative-link checks and clean packed consumers on that candidate.
-3. Check registry availability for `@naeil/ui@0.3.0` immediately before publication. Publish the verified candidate archive, then verify the registry version, integrity and dist-tag; a changelog or install command alone proves none of these.
+2. Build and inspect a fresh archive with `npm pack --ignore-scripts --json --pack-destination /path/to/candidate`; preserve its SHA-256, file list and source revision outside the archive. Run boundary/relative-link checks and clean packed consumers with `NAEIL_UI_EXPECTED_ARCHIVE_SHA256` set to that digest; confirm both generated archives match the candidate.
+3. Check registry availability for `@naeil/ui@VERSION` immediately before publication. Publish the verified candidate archive, then verify the registry version, integrity and dist-tag; a changelog or install command alone proves none of these.
 4. Create the release tag/GitHub Release for the recorded source and retain version, artifact identity, validation scope and support limitations.
 5. Publish the reviewed Storybook artifact through the manual Pages workflow below. Verify the actual hosted URL, subpath Docs-to-Usage navigation, fonts and notices over HTTP before reporting it live.
 
@@ -76,7 +98,7 @@ npm publication, GitHub Releases, main merge and hosted Docs are distinct operat
 
 ## Storybook preview artifact
 
-`pnpm build:storybook` builds actual Docs pages and interactive Usage examples for all 13 families. It copies only generated documentation notices, bundles locally installed Pretendard/Noto Sans JP and disables Vite publicDir. The artifact check verifies real Docs/story entries, exact MIT/shadcn/font notices and absence of website public images/SVGs/HTML. It does not claim those excluded site assets have cleared rights.
+`pnpm build:storybook` builds 17 actual Docs pages: 15 UI families (the 13 primitives plus Navigation and SiteFooter) and Brand / Logo and NaeilHeader. Interactive Usage examples include the complete branded header and its JapaneseApplication adapter. It copies generated documentation notices and approved canonical brand SVGs, bundles locally installed Pretendard/Noto Sans JP and disables Vite publicDir. The artifact check verifies real Docs/story entries, exact MIT/shadcn/font notices, brand references and absence of website public images/SVGs/HTML. It does not claim those excluded site assets have cleared rights.
 
 CI uploads `storybook-preview` after a successful build; it is a downloadable static artifact, not a hosted deployment. Download/unzip it and serve the extracted directory (containing index.html):
 
@@ -86,11 +108,11 @@ pnpm preview:storybook
 # Open http://127.0.0.1:6007 and choose UI / a family / Docs or Usage.
 ```
 
-Run the command from this checkout after installing its dependencies. It serves the built or downloaded static artifact with persistent HTTP connections; a conventional static host works as well. Do not open iframe.html directly as a file; use HTTP. Preserve LICENSE, THIRD_PARTY_NOTICES.md and licenses/ with the artifact. The static preview needs no backend, credentials or external font server. Third-party dependency code also retains its own bundled/license notices.
+Run the command from this checkout after installing its dependencies. It serves the built or downloaded static artifact with persistent HTTP connections; a conventional static host works as well. Do not open iframe.html directly as a file; use HTTP. Preserve LICENSE, THIRD_PARTY_NOTICES.md and licenses/ with the artifact. The static preview needs no backend, credentials or external font server. The whole-header decorative project images reference the official site and require network access; failed images retain usable text and destinations. Third-party dependency code also retains its own bundled/license notices.
 
 ### Authorized GitHub Pages publication
 
-The public Docs destination [https://naeil-dev.github.io/naeil-ui/](https://naeil-dev.github.io/naeil-ui/) is live following the 2026-10-02 [Pages run 36963256014](https://github.com/naeil-dev/naeil-ui/actions/runs/36963256014). The [release](https://github.com/naeil-dev/naeil-ui/releases/tag/v0.3.0) records deployed source and hosted HTTP/navigation checks. Pages uses `build_type=workflow` and a **github-pages** main-only deployment branch policy. See [Docs workflow status](https://github.com/naeil-dev/naeil-ui/actions/workflows/publish-docs-manual.yml) for subsequent deployments; preview artifact checks above establish local artifact behavior only.
+The public Docs destination [https://naeil-dev.github.io/naeil-ui/](https://naeil-dev.github.io/naeil-ui/) serves source `e8fe5afc13788a0cac0244b72e78975812f4a2ee` following the 2026-10-11 [Pages run 38114879574](https://github.com/naeil-dev/naeil-ui/actions/runs/38114879574). The [0.4.0 release](https://github.com/naeil-dev/naeil-ui/releases/tag/v0.4.0) records deployed source and hosted HTTP/navigation checks; the 0.3.0 deployment above remains history. Pages uses `build_type=workflow` and a **github-pages** main-only deployment branch policy. See [Docs workflow status](https://github.com/naeil-dev/naeil-ui/actions/workflows/publish-docs-manual.yml) for subsequent deployments; preview artifact checks above establish local artifact behavior only.
 
 `.github/workflows/publish-docs-manual.yml` is an explicit `workflow_dispatch` recipe with no PR/push trigger. Pages is configured to use **GitHub Actions**; the **github-pages** environment permits deployment from main only. Run the authorized workflow from main with the exact reviewed source SHA; configuration alone does not establish a successful deployment. The workflow file does not enable Pages itself. A default-branch merge can separately invoke the brand site's existing Vercel integration; that production deployment and its asset/font provenance require separate handling.
 
@@ -101,7 +123,7 @@ Select **Publish reviewed UI docs (manual only)** in Actions (or use the command
 gh workflow run publish-docs-manual.yml -f reviewed_sha=FULL_REVIEWED_COMMIT_SHA -f confirmation=PUBLISH_REVIEWED_DOCS
 ```
 
-After deployment, verify the manager and iframe under `/naeil-ui/`, all 13 Docs/Usage entries, Docs links, local fonts and exact LICENSE/THIRD_PARTY_NOTICES/font notices. Retain the deployment URL, source SHA and observed HTTP/navigation results. Hosted Storybook uses simulated data and requires no Supabase project, design API key or external font server. Only the reviewed Storybook directory is uploaded; website public assets stay excluded.
+After a 0.5.0 deployment, verify the manager and iframe under `/naeil-ui/`, all 15 UI and 2 Brand Docs pages, their Usage examples and NaeilHeader JapaneseApplication, canonical artwork and official image references, Docs links, local fonts and exact LICENSE/THIRD_PARTY_NOTICES/font notices. Retain the deployment URL, source SHA and observed HTTP/navigation results. Hosted Storybook uses simulated data and requires no Supabase project, design API key or external font server. Only the reviewed Storybook directory is uploaded; website public assets stay excluded.
 
 Normal builds are network-independent after dependency installation. Vite collects notices for actual preview modules; checked-in manager notices conservatively cover named embedded packages and versions from Storybook 10.4.6's original source lock. `check-storybook` fails if a named embedded module lacks a full notice. Four vendored tiny modules have no embedded version in that lock/comments; their original npm notice source is explicitly marked, without an exact-version claim. The exact use-composed-ref@1.4.0 tarball/repository provides MIT metadata but no standalone notice; its metadata plus full declared terms are retained without inventing a year/holder. The client-only@0.0.1 React marker retains its exact metadata and the original React MIT notice. Other missing notices fail the build; no generic MIT fallback passes arbitrary packages.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naeil/ui",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "license": "MIT",
   "sideEffects": [
@@ -125,6 +125,18 @@
     "./components/ui/textarea": {
       "types": "./dist/source/components/ui/textarea.d.ts",
       "import": "./dist/source/components/ui/textarea.js"
+    },
+    "./components/ui/navigation": {
+      "types": "./dist/source/components/ui/navigation.d.ts",
+      "import": "./dist/source/components/ui/navigation.js"
+    },
+    "./components/ui/site-footer": {
+      "types": "./dist/source/components/ui/site-footer.d.ts",
+      "import": "./dist/source/components/ui/site-footer.js"
+    },
+    "./naeil-header": {
+      "types": "./dist/components/naeil-header.d.ts",
+      "import": "./dist/components/naeil-header.js"
     }
   },
   "scripts": {

package/src/styles/components.css

@@ -1,4 +1,296 @@
 @layer components {
+  .ui-navigation {
+    position: relative;
+    z-index: 40;
+    color: var(--foreground);
+    background: var(--background);
+    border-bottom: 1px solid var(--border);
+  }
+  /* Branded website chrome is an opt-in composition, independent of app content widths. */
+  .naeil-header {
+    position: fixed;
+    inset-block-start: 0;
+    inset-inline: 0;
+    width: 100%;
+  }
+  .naeil-header-frame {
+    max-width: 80rem;
+  }
+  .naeil-header-controls {
+    display: flex;
+    align-items: center;
+    gap: var(--spacing-2-value);
+  }
+  .ui-navigation-mobile-toolbar > .naeil-header-controls {
+    flex-wrap: wrap;
+    gap: var(--spacing-4-value);
+  }
+  .naeil-header-separator {
+    flex: none;
+    width: 1px;
+    height: var(--spacing-4-value);
+    background: var(--border);
+  }
+  .naeil-header-project-icon {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: var(--ui-control-height);
+    height: var(--ui-control-height);
+    border: 1px solid;
+    border-radius: var(--radius-lg-value);
+  }
+  .ui-navigation-frame,
+  .ui-site-footer-frame {
+    width: 100%;
+    margin-inline: auto;
+    padding-inline: var(--spacing-6-value);
+  }
+  .ui-navigation-frame {
+    container-type: inline-size;
+  }
+  .ui-navigation-row {
+    display: flex;
+    align-items: center;
+    gap: var(--spacing-4-value);
+    min-height: var(--ui-navigation-height);
+    padding-block: var(--spacing-2-value);
+  }
+  .ui-navigation-brand {
+    flex-shrink: 0;
+  }
+  .ui-navigation-brand a {
+    display: inline-flex;
+    align-items: center;
+    min-height: var(--ui-touch-target);
+  }
+  .ui-navigation-brand a:focus-visible {
+    outline: 2px solid var(--ring);
+    outline-offset: 3px;
+  }
+  .ui-navigation-desktop,
+  .ui-navigation-toolbar {
+    display: none;
+    align-items: center;
+    gap: var(--spacing-2-value);
+  }
+  .ui-navigation-toolbar {
+    margin-inline-start: auto;
+  }
+  .ui-navigation-link {
+    display: flex;
+    align-items: center;
+    gap: var(--spacing-2-value);
+    min-height: var(--ui-touch-target);
+    min-width: var(--ui-touch-target);
+    padding: var(--spacing-2-value) var(--spacing-3-value);
+    border-radius: var(--radius-md-value);
+    color: var(--foreground);
+    font-size: var(--text-base);
+    line-height: var(--leading-normal);
+    text-align: start;
+    text-decoration: none;
+    overflow-wrap: anywhere;
+    transition: background-color var(--ui-motion-fast);
+  }
+  .ui-navigation-link:hover {
+    background: var(--surface-subtle);
+  }
+  .ui-navigation-link[aria-current="page"],
+  .ui-navigation-link[data-active],
+  .ui-navigation-link[data-state="open"] {
+    background: var(--surface-selected);
+  }
+  .ui-navigation-link[aria-current="page"] {
+    text-decoration: underline;
+    text-underline-offset: 4px;
+  }
+  .ui-navigation-entry {
+    align-items: flex-start;
+    gap: var(--spacing-4-value);
+    min-height: var(--ui-row-height);
+    padding: var(--spacing-3-value);
+  }
+  .ui-navigation-entry[aria-current="page"] {
+    text-decoration: none;
+  }
+  .ui-navigation-entry[aria-current="page"] .ui-navigation-title {
+    font-weight: 600;
+  }
+  .ui-navigation-title {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: var(--spacing-2-value);
+    font-weight: 500;
+  }
+  .ui-navigation-copy {
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    gap: var(--spacing-1-value);
+  }
+  .ui-navigation-icon {
+    flex-shrink: 0;
+  }
+  .ui-navigation-entry .ui-navigation-icon {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: var(--ui-control-height);
+    min-height: var(--ui-control-height);
+  }
+  .ui-navigation-description {
+    color: var(--muted-foreground);
+    font-size: var(--text-sm);
+  }
+  .ui-navigation-toggle {
+    margin-inline-start: auto;
+    justify-content: center;
+  }
+  .ui-navigation-popover {
+    z-index: 50;
+    width: var(--ui-navigation-menu-width);
+    max-width: min(
+      var(--radix-popover-content-available-width),
+      calc(100vw - 2 * var(--spacing-4-value))
+    );
+    max-height: var(--radix-popover-content-available-height);
+    overflow-y: auto;
+    padding: var(--spacing-4-value);
+    color: var(--popover-foreground);
+    background: var(--popover);
+    border: 1px solid var(--border-strong);
+    border-radius: var(--radius-lg-value);
+    box-shadow: var(--shadow-md);
+  }
+  .ui-navigation-popover[data-columns="2"] {
+    width: var(--ui-navigation-menu-wide-width);
+  }
+  .ui-navigation-menu-grid {
+    display: grid;
+    gap: var(--spacing-2-value);
+  }
+  .ui-navigation-popover[data-columns="2"] .ui-navigation-menu-grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+  .ui-navigation-overlay {
+    position: fixed;
+    inset: 0;
+    z-index: 50;
+    background: rgb(0 0 0 / 0.6);
+  }
+  .ui-navigation-sheet {
+    position: fixed;
+    inset: 0 0 0 auto;
+    z-index: 50;
+    display: flex;
+    flex-direction: column;
+    gap: var(--spacing-6-value);
+    width: min(100%, var(--ui-width-short-form));
+    padding: var(--spacing-6-value);
+    overflow-y: auto;
+    overscroll-behavior: contain;
+    background: var(--background);
+    color: var(--foreground);
+  }
+  .ui-navigation-sheet-heading {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--spacing-4-value);
+  }
+  .ui-navigation-mobile-links {
+    display: grid;
+    gap: var(--spacing-4-value);
+  }
+  .ui-navigation-group-label {
+    padding: var(--spacing-2-value) var(--spacing-3-value);
+    font-size: var(--text-sm);
+    font-weight: 600;
+  }
+  .ui-navigation-mobile-toolbar {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--spacing-4-value);
+    border-top: 1px solid var(--border);
+    padding-top: var(--spacing-4-value);
+  }
+  .ui-navigation-mobile-footer {
+    margin-top: auto;
+    padding-top: var(--spacing-4-value);
+  }
+  @container (min-width: 48rem) {
+    .ui-navigation-brand {
+      width: var(--ui-navigation-brand-width);
+    }
+    .ui-navigation-desktop,
+    .ui-navigation-toolbar {
+      display: flex;
+      flex-wrap: wrap;
+    }
+    .ui-navigation-toggle {
+      display: none;
+    }
+  }
+  .ui-site-footer {
+    border-top: 1px solid var(--border);
+    color: var(--foreground);
+    background: var(--background);
+  }
+  .ui-site-footer-frame {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: flex-start;
+    gap: var(--spacing-8-value);
+    padding-block: var(--spacing-8-value);
+  }
+  .ui-site-footer-brand {
+    display: grid;
+    gap: var(--spacing-4-value);
+    margin-inline-end: auto;
+  }
+  .ui-site-footer-description {
+    max-width: var(--ui-width-short-form);
+    color: var(--muted-foreground);
+    font-size: var(--text-sm);
+  }
+  .ui-site-footer-label {
+    font-size: var(--text-sm);
+    font-weight: 600;
+    margin-bottom: var(--spacing-2-value);
+  }
+  .ui-site-footer-link {
+    display: flex;
+    align-items: center;
+    min-height: var(--ui-touch-target);
+    color: var(--muted-foreground);
+    font-size: var(--text-sm);
+    text-decoration: none;
+  }
+  .ui-site-footer-link:hover {
+    color: var(--foreground);
+    text-decoration: underline;
+  }
+  .ui-site-footer-meta {
+    width: 100%;
+    font-size: var(--text-sm);
+    color: var(--muted-foreground);
+  }
+  .ui-site-footer[data-variant="compact"] .ui-site-footer-frame {
+    align-items: center;
+    padding-block: var(--spacing-4-value);
+    gap: var(--spacing-4-value);
+  }
+  .ui-site-footer[data-variant="compact"] .ui-site-footer-meta {
+    width: auto;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .ui-navigation-link {
+      transition: none;
+    }
+  }
   .ui-textarea {
     min-height: var(--ui-control-height);
     font-size: var(--text-base);

package/src/styles/theme.css

@@ -156,6 +156,10 @@
   --ui-width-short-form: 480px;
   --ui-motion-fast: 120ms;
   --ui-motion-standard: 180ms;
+  --ui-navigation-height: 64px;
+  --ui-navigation-brand-width: 160px;
+  --ui-navigation-menu-width: 320px;
+  --ui-navigation-menu-wide-width: 640px;
   --project-cc: oklch(0.704 0.140 181);
   --project-sa: oklch(0.723 0.219 149);
   --project-pkm: oklch(0.627 0.265 303);