@naeil/ui 0.4.0 → 0.6.0

package/dist/source/components/ui/navigation.js

@@ -0,0 +1,347 @@
+"use client";
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __objRest = (source, exclude) => {
+  var target = {};
+  for (var prop in source)
+    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
+      target[prop] = source[prop];
+  if (source != null && __getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(source)) {
+      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
+        target[prop] = source[prop];
+    }
+  return target;
+};
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Dialog, Popover } from "radix-ui";
+import { Check, ChevronDown, Menu, X } from "lucide-react";
+import { cn } from "../../lib/utils.js";
+const NativeLink = React.forwardRef(
+  function NativeLink2(props, ref) {
+    return /* @__PURE__ */ jsx("a", __spreadValues({ ref }, props));
+  }
+);
+function DesktopGroup({
+  item,
+  active,
+  open,
+  anotherGroupOpen,
+  onOpenChange,
+  children
+}) {
+  var _a;
+  const hoverOpened = React.useRef(false);
+  const closeTimer = React.useRef(
+    void 0
+  );
+  const panel = React.useRef(null);
+  const trigger = React.useRef(null);
+  const pointerType = React.useRef("");
+  const cancelClose = React.useCallback(() => {
+    clearTimeout(closeTimer.current);
+  }, []);
+  React.useEffect(() => {
+    return cancelClose;
+  }, [open, cancelClose]);
+  const leave = (event) => {
+    if (event.pointerType !== "mouse") return;
+    cancelClose();
+    const duration = getComputedStyle(event.currentTarget).getPropertyValue("--ui-motion-standard").trim();
+    closeTimer.current = setTimeout(
+      () => {
+        if (hoverOpened.current) onOpenChange(false);
+      },
+      parseFloat(duration) * (duration.endsWith("ms") ? 1 : 1e3)
+    );
+  };
+  return /* @__PURE__ */ jsxs(
+    Popover.Root,
+    {
+      open,
+      onOpenChange: (next) => {
+        cancelClose();
+        if (next) hoverOpened.current = false;
+        onOpenChange(next);
+      },
+      children: [
+        /* @__PURE__ */ jsxs(
+          Popover.Trigger,
+          {
+            ref: trigger,
+            className: "ui-navigation-link ui-focus",
+            "data-active": active || void 0,
+            onPointerEnter: (event) => {
+              if (event.pointerType !== "mouse") return;
+              cancelClose();
+              if (!open) {
+                hoverOpened.current = true;
+                onOpenChange(true);
+              }
+            },
+            onPointerLeave: leave,
+            onPointerDown: (event) => {
+              pointerType.current = event.pointerType;
+            },
+            onClick: (event) => {
+              var _a2, _b;
+              if (event.detail > 0 && pointerType.current === "mouse") {
+                event.preventDefault();
+                cancelClose();
+                hoverOpened.current = true;
+                onOpenChange(true);
+                return;
+              }
+              if (open && hoverOpened.current) {
+                event.preventDefault();
+                hoverOpened.current = false;
+                cancelClose();
+                (_b = (_a2 = panel.current) == null ? void 0 : _a2.querySelector("a[href]")) == null ? void 0 : _b.focus();
+              }
+            },
+            children: [
+              item.label,
+              /* @__PURE__ */ jsx(ChevronDown, { size: 16, "aria-hidden": "true" })
+            ]
+          }
+        ),
+        /* @__PURE__ */ jsx(Popover.Portal, { children: /* @__PURE__ */ jsx(
+          Popover.Content,
+          {
+            ref: panel,
+            "data-slot": "navigation-popover",
+            className: "ui-navigation-popover ui-popup",
+            "data-columns": (_a = item.columns) != null ? _a : 1,
+            align: "start",
+            sideOffset: 8,
+            "aria-label": item.label,
+            onPointerEnter: cancelClose,
+            onPointerLeave: leave,
+            onFocusCapture: () => {
+              hoverOpened.current = false;
+              cancelClose();
+            },
+            onOpenAutoFocus: (event) => {
+              if (hoverOpened.current) event.preventDefault();
+            },
+            onCloseAutoFocus: (event) => {
+              if (hoverOpened.current || anotherGroupOpen) event.preventDefault();
+            },
+            onInteractOutside: (event) => {
+              var _a2;
+              if ((_a2 = trigger.current) == null ? void 0 : _a2.contains(event.target))
+                event.preventDefault();
+            },
+            children: /* @__PURE__ */ jsx("nav", { "aria-label": item.label, className: "ui-navigation-menu-grid", children })
+          }
+        ) })
+      ]
+    }
+  );
+}
+function Navigation(_a) {
+  var _b = _a, {
+    brand,
+    items,
+    labels,
+    Link = NativeLink,
+    currentHref,
+    toolbar,
+    mobileToolbar,
+    mobileFooter,
+    containerClassName,
+    onNavigate,
+    className
+  } = _b, props = __objRest(_b, [
+    "brand",
+    "items",
+    "labels",
+    "Link",
+    "currentHref",
+    "toolbar",
+    "mobileToolbar",
+    "mobileFooter",
+    "containerClassName",
+    "onNavigate",
+    "className"
+  ]);
+  const [mobileOpen, setMobileOpen] = React.useState(false);
+  const [openGroup, setOpenGroup] = React.useState(null);
+  const trigger = React.useRef(null);
+  const desktop = React.useRef(null);
+  React.useEffect(() => {
+    setMobileOpen(false);
+    setOpenGroup(null);
+  }, [currentHref]);
+  React.useEffect(() => {
+    const element = desktop.current;
+    if (!element || typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(() => {
+      if (element.getBoundingClientRect().width > 0) setMobileOpen(false);
+      else setOpenGroup(null);
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+  const active = (item) => {
+    var _a2;
+    return (_a2 = item.active) != null ? _a2 : !item.external && item.href === currentHref;
+  };
+  function link(item, close, entry = false) {
+    const Component = item.external ? NativeLink : Link;
+    return /* @__PURE__ */ jsxs(
+      Component,
+      {
+        href: item.href,
+        target: item.target,
+        rel: item.target === "_blank" ? "noopener noreferrer" : void 0,
+        "aria-current": active(item) ? "page" : void 0,
+        className: cn(
+          "ui-navigation-link ui-focus",
+          entry && "ui-navigation-entry"
+        ),
+        onClick: (event) => {
+          onNavigate == null ? void 0 : onNavigate(event, item);
+          if (event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey)
+            close == null ? void 0 : close();
+        },
+        children: [
+          item.icon && /* @__PURE__ */ jsx("span", { className: "ui-navigation-icon", "aria-hidden": "true", children: item.icon }),
+          /* @__PURE__ */ jsxs("span", { className: "ui-navigation-copy", children: [
+            /* @__PURE__ */ jsxs("span", { className: "ui-navigation-title", children: [
+              /* @__PURE__ */ jsx("span", { children: item.label }),
+              item.badge,
+              entry && active(item) && /* @__PURE__ */ jsx(Check, { size: 16, className: "shrink-0", "aria-hidden": "true" })
+            ] }),
+            item.description && /* @__PURE__ */ jsx("span", { className: "ui-navigation-description", children: item.description })
+          ] })
+        ]
+      },
+      item.id
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    "header",
+    __spreadProps(__spreadValues({
+      "data-slot": "navigation",
+      className: cn("ui-navigation", className)
+    }, props), {
+      children: /* @__PURE__ */ jsx("div", { className: cn("ui-navigation-frame", containerClassName), children: /* @__PURE__ */ jsxs("div", { className: "ui-navigation-row", children: [
+        /* @__PURE__ */ jsx("div", { className: "ui-navigation-brand", children: brand }),
+        /* @__PURE__ */ jsx(
+          "nav",
+          {
+            ref: desktop,
+            "aria-label": labels.navigation,
+            className: "ui-navigation-desktop",
+            children: items.map(
+              (item) => "items" in item ? /* @__PURE__ */ jsx(
+                DesktopGroup,
+                {
+                  item,
+                  active: item.items.some(active),
+                  open: openGroup === item.id,
+                  anotherGroupOpen: openGroup !== null && openGroup !== item.id,
+                  onOpenChange: (open) => setOpenGroup(
+                    (current) => open ? item.id : current === item.id ? null : current
+                  ),
+                  children: item.items.map(
+                    (child) => link(child, () => setOpenGroup(null), true)
+                  )
+                },
+                item.id
+              ) : link(item)
+            )
+          }
+        ),
+        /* @__PURE__ */ jsx("div", { className: "ui-navigation-toolbar", children: toolbar }),
+        /* @__PURE__ */ jsxs(Dialog.Root, { open: mobileOpen, onOpenChange: setMobileOpen, children: [
+          /* @__PURE__ */ jsx(
+            Dialog.Trigger,
+            {
+              ref: trigger,
+              className: "ui-navigation-toggle ui-navigation-link ui-focus",
+              "aria-label": labels.menu,
+              children: /* @__PURE__ */ jsx(Menu, { "aria-hidden": "true", size: 20 })
+            }
+          ),
+          /* @__PURE__ */ jsxs(Dialog.Portal, { children: [
+            /* @__PURE__ */ jsx(
+              Dialog.Overlay,
+              {
+                "data-slot": "navigation-overlay",
+                className: "ui-navigation-overlay ui-popup"
+              }
+            ),
+            /* @__PURE__ */ jsxs(
+              Dialog.Content,
+              {
+                "data-slot": "navigation-sheet",
+                className: "ui-navigation-sheet ui-popup",
+                "aria-describedby": void 0,
+                onCloseAutoFocus: (event) => {
+                  var _a2, _b2;
+                  if (trigger.current && trigger.current.getBoundingClientRect().width === 0) {
+                    event.preventDefault();
+                    (_b2 = (_a2 = desktop.current) == null ? void 0 : _a2.querySelector("button, a")) == null ? void 0 : _b2.focus();
+                  }
+                },
+                children: [
+                  /* @__PURE__ */ jsxs("div", { className: "ui-navigation-sheet-heading", children: [
+                    /* @__PURE__ */ jsx(Dialog.Title, { className: "text-xl font-semibold", children: labels.menu }),
+                    /* @__PURE__ */ jsx(
+                      Dialog.Close,
+                      {
+                        className: "ui-navigation-link ui-focus",
+                        "aria-label": labels.close,
+                        children: /* @__PURE__ */ jsx(X, { size: 20, "aria-hidden": "true" })
+                      }
+                    )
+                  ] }),
+                  /* @__PURE__ */ jsx(
+                    "nav",
+                    {
+                      "aria-label": labels.navigation,
+                      className: "ui-navigation-mobile-links",
+                      children: items.map(
+                        (item) => "items" in item ? /* @__PURE__ */ jsxs("section", { "aria-label": item.label, children: [
+                          /* @__PURE__ */ jsx("h3", { className: "ui-navigation-group-label", children: item.label }),
+                          item.items.map(
+                            (child) => link(child, () => setMobileOpen(false), true)
+                          )
+                        ] }, item.id) : link(item, () => setMobileOpen(false))
+                      )
+                    }
+                  ),
+                  (mobileToolbar != null ? mobileToolbar : toolbar) && /* @__PURE__ */ jsx("div", { className: "ui-navigation-mobile-toolbar", children: mobileToolbar != null ? mobileToolbar : toolbar }),
+                  mobileFooter && /* @__PURE__ */ jsx("div", { className: "ui-navigation-mobile-footer", children: mobileFooter })
+                ]
+              }
+            )
+          ] })
+        ] })
+      ] }) })
+    })
+  );
+}
+export {
+  Navigation
+};

package/dist/source/components/ui/site-footer.d.ts

@@ -0,0 +1,21 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { NavigationLink, NavigationLinkComponent } from './navigation.js';
+
+interface SiteFooterProps extends react.ComponentPropsWithoutRef<"footer"> {
+    brand?: react.ReactNode;
+    description?: react.ReactNode;
+    groups?: Array<{
+        id: string;
+        label: string;
+        links: NavigationLink[];
+    }>;
+    Link?: NavigationLinkComponent;
+    meta?: react.ReactNode;
+    containerClassName?: string;
+    variant?: "full" | "compact";
+}
+/** Product content and translations belong to the consumer, including legal copy. */
+declare function SiteFooter({ brand, description, groups, Link, meta, children, containerClassName, className, variant, ...props }: SiteFooterProps): react_jsx_runtime.JSX.Element;
+
+export { SiteFooter, type SiteFooterProps };

package/dist/source/components/ui/site-footer.js

@@ -0,0 +1,93 @@
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __objRest = (source, exclude) => {
+  var target = {};
+  for (var prop in source)
+    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
+      target[prop] = source[prop];
+  if (source != null && __getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(source)) {
+      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
+        target[prop] = source[prop];
+    }
+  return target;
+};
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "../../lib/utils.js";
+function SiteFooter(_a) {
+  var _b = _a, {
+    brand,
+    description,
+    groups = [],
+    Link,
+    meta,
+    children,
+    containerClassName,
+    className,
+    variant = "full"
+  } = _b, props = __objRest(_b, [
+    "brand",
+    "description",
+    "groups",
+    "Link",
+    "meta",
+    "children",
+    "containerClassName",
+    "className",
+    "variant"
+  ]);
+  return /* @__PURE__ */ jsx(
+    "footer",
+    __spreadProps(__spreadValues({
+      "data-slot": "site-footer",
+      "data-variant": variant,
+      className: cn("ui-site-footer", className)
+    }, props), {
+      children: /* @__PURE__ */ jsxs("div", { className: cn("ui-site-footer-frame", containerClassName), children: [
+        /* @__PURE__ */ jsxs("div", { className: "ui-site-footer-brand", children: [
+          brand,
+          description && /* @__PURE__ */ jsx("div", { className: "ui-site-footer-description", children: description }),
+          children
+        ] }),
+        groups.map((group) => /* @__PURE__ */ jsxs("nav", { "aria-label": group.label, children: [
+          /* @__PURE__ */ jsx("h2", { className: "ui-site-footer-label", children: group.label }),
+          group.links.map((item) => {
+            const Component = !item.external && Link ? Link : "a";
+            return /* @__PURE__ */ jsx(
+              Component,
+              {
+                href: item.href,
+                target: item.target,
+                rel: item.target === "_blank" ? "noopener noreferrer" : void 0,
+                className: "ui-site-footer-link ui-focus",
+                children: item.label
+              },
+              item.id
+            );
+          })
+        ] }, group.id)),
+        meta && /* @__PURE__ */ jsx("div", { className: "ui-site-footer-meta", children: meta })
+      ] })
+    })
+  );
+}
+export {
+  SiteFooter
+};

package/docs/components/README.md

@@ -1,6 +1,8 @@
 # Component usage guides
 
-Published `@naeil/ui@0.3.0` (2026-10-03; [release](https://github.com/naeil-dev/naeil-ui/releases/tag/v0.3.0)). [Setup, themes, fonts and shared responsibilities](common.md). Open the [live Storybook](https://naeil-dev.github.io/naeil-ui/) or run `pnpm storybook` and choose each family’s Docs or Usage entry. Select chooses a value; DropdownMenu chooses an action.
+These guides target the **@naeil/ui 0.6.0**; release identities and publication evidence are recorded in the [release record](https://github.com/naeil-dev/naeil-ui/releases/tag/v0.6.0). [Setup, themes, fonts and shared responsibilities](common.md). Run `pnpm storybook` for the current 17 Docs pages (15 UI and 2 Brand) and choose Docs or Usage. The [hosted Storybook](https://naeil-dev.github.io/naeil-ui/) was last verified for [0.5.0 on 2026-10-15](https://github.com/naeil-dev/naeil-ui/releases/tag/v0.5.0); each subsequent deployment is recorded separately. Select chooses a value; DropdownMenu chooses an action.
+
+Start application layouts with the [shared navigation/footer selection and frame guide](application-layout.md). It includes a starter, the 1600px frame contract and instructions to place in consumer repositories so agents reuse the shared implementation.
 
 | Family | Guide | Runnable story |
 | --- | --- | --- |
@@ -17,5 +19,10 @@ Published `@naeil/ui@0.3.0` (2026-10-03; [release](https://github.com/naeil-dev/
 | Checkbox | [Checkbox](./checkbox.md) | UI / Checkbox / Usage |
 | Tabs | [Tabs](./tabs.md) | UI / Tabs / Usage |
 | Textarea | [Textarea](./textarea.md) | UI / Textarea / Usage |
+| Navigation | [Navigation](./navigation.md) | UI / Navigation / Usage |
+| SiteFooter | [SiteFooter](./navigation.md) | UI / SiteFooter / Usage |
+| NaeilHeader | [NaeilHeader](./naeil-header.md) | Brand / NaeilHeader / Usage, JapaneseApplication |
 
 [Field, native radio, Select and action composition](./composition.md) explains consumer state and semantic choices. [Demand decision](../design/component-demand.md) records why these two families were added.
+
+Use opt-in `@naeil/ui/naeil-header` for the actual naeil.dev branded header, with official artwork URL references and consumer-owned routing, theme provider and authentication. Use generic `Navigation` from `/ui` for different product menus. [Navigation / SiteFooter](navigation.md) also documents the compatibility adapters.

package/docs/components/application-layout.md

@@ -0,0 +1,102 @@
+# Application frame and shared navigation/footer
+
+This guide targets the **@naeil/ui 0.6.0**, including the width update approved on 2026-10-16. Use the matching registry release or tested local archive. See [consumer setup](../design/v2-migration.md) for CSS, Tailwind sources and fonts.
+
+## Choose the shared composition first
+
+| Application need | Use |
+| --- | --- |
+| The actual naeil.dev brand, project catalog and controls | `NaeilHeader` from `@naeil/ui/naeil-header` |
+| A product's own menu | `Navigation` from `@naeil/ui/ui` |
+| A full or compact application footer | `SiteFooter` from `@naeil/ui/ui` |
+| An existing Next/next-intl consumer | Keep its `Nav` / `Footer` adapters |
+
+Choose one header per application frame. Supply menu data, links, route guards, authentication and supported locale state through props/slots. Local adapters are appropriate; copies of the menu, responsive sheet, controls or footer implementation are not. Extend the shared component when a reusable behavior is missing.
+
+## Width contract
+
+| Region | Default | CSS contract |
+| --- | --- | --- |
+| Header, main, footer outer frame | Maximum 1600px, including gutters | `--ui-width-frame` |
+| Inline gutters | `clamp(16px, 2.4vw, 40px)` | `--ui-frame-gutter` |
+| Reading / settings | Maximum 640px | `data-ui-layout="reading"` / `"settings"` |
+| Short form | Maximum 480px | `data-ui-layout="short-form"` |
+| List / dashboard / table region | Available space inside the frame, capped at 1600px | `data-ui-layout="list"` |
+| Intentionally unrestricted region | Available parent width | `data-ui-layout="fluid"` |
+
+Use `.ui-app-frame` on main. Shared header/footer already apply the frame internally; **do not wrap them in another padded frame**. Put purpose-specific sections inside main. At 1920px the default frame has 1520px available after its 40px gutters. Small screens shrink the frame and reduce gutters to at least 16px. A narrow form must not constrain or move navigation.
+
+Reserve a consistent scrollbar gutter in the consumer's global CSS when routes can alternate between short and tall content:
+
+```css
+html { scrollbar-gutter: stable; }
+```
+
+This keeps a centered frame from shifting when a classic scrollbar appears. The document scroll policy belongs to the application; the shared components do not set it implicitly. In a 1920px Chromium viewport with a 15px scrollbar, the frame starts at 152.5px with this policy in both short and tall states. Without it, the start changes from 160px to 152.5px. Overlay-scrollbar platforms may reserve no extra space.
+
+## Canonical naeil application starter
+
+```tsx
+import type { ReactNode } from "react";
+import { NaeilHeader } from "@naeil/ui/naeil-header";
+import { SiteFooter } from "@naeil/ui/ui";
+import { Logo } from "@naeil/ui/components/logo";
+
+// Render inside the existing next-themes ThemeProvider.
+// Connect Link/onNavigate, locale and authSlot to real application state.
+export function ApplicationLayout({ children }: { children: ReactNode }) {
+  return <>
+    <NaeilHeader locale="en" />
+    <main className="ui-app-frame"
+      style={{ marginTop: "calc(var(--ui-navigation-height) + 1px)" }}>
+      {children}
+    </main>
+    <SiteFooter variant="compact"
+      brand={<Logo variant="footer" size={20} />} />
+  </>;
+}
+
+<ApplicationLayout>
+  <section data-ui-layout="settings">{/* Settings form */}</section>
+</ApplicationLayout>
+```
+
+`NaeilHeader` is fixed; reserve its 65px height and account for it in sticky areas and focus/anchor scroll margins. Default destinations are official naeil.dev URLs. Preserve routing/unsaved-change guards using the [header contract](naeil-header.md). Only pass `onLocaleChange` when the application supports its complete language set.
+
+For a different product menu, use the [generic Navigation composition](navigation.md) with the same main/footer structure. Generic Navigation is in document flow by default and needs no fixed-header clearance. The [standalone React example](https://github.com/naeil-dev/naeil-ui/tree/main/examples/react) exercises the installed header, narrow form and SiteFooter together.
+
+## Deliberate overrides
+
+Apply overrides on a common ancestor or document root so header, main and footer inherit them together. Explicit `containerClassName` overrides still work. Do not give each route its own header cap or gutter.
+
+```css
+/* Product exception: record why this cap is needed. */
+.product-shell {
+  --ui-width-frame: 1280px;
+  --ui-frame-gutter: 24px;
+}
+/* An existing focused list can retain its previous content cap. */
+.focused-list { --ui-width-list: 1200px; }
+```
+
+The new frame/list caps replace the previous 1280px branded header and 1200px list defaults. Remove old `max-w-7xl` or `px-6` frame overrides when adopting the new default. Shared numeric values belong in `src/tokens/ui.json`; regenerate CSS with `pnpm build:tokens`.
+
+## Consumer agent instructions
+
+Put this in the **consumer application's** `AGENTS.md` (or equivalent repository instructions). Installing a package does not automatically load this repository's agent rules.
+
+```markdown
+## Shared application layout
+- Read the installed @naeil/ui/DESIGN.md and docs/components/application-layout.md before UI layout work.
+- Use @naeil/ui/naeil-header for the canonical naeil header; use Navigation from @naeil/ui/ui for a different product menu. Use SiteFooter for application footers. Keep existing Next Nav/Footer compatibility adapters when applicable.
+- Local wrappers supply menu data, routing/guards, locale, auth and slots. Do not copy the menu, mobile sheet, controls or footer implementation. Extend the shared component for reusable missing behavior.
+- Use ui-app-frame on main; navigation/footer own their internal frames. Keep reading/settings/short-form sections inside that frame. Apply frame overrides consistently across routes.
+- Check the installed package version and CSS before creating a replacement for an apparently missing component.
+- Verify actual shared navigation/footer rendering and stable anchors across routes, themes and supported sizes. An import alone is not adoption evidence. Record intentional route exceptions.
+```
+
+## Adoption checks
+
+For each consumer, record its installed version, layout adapter, shared imports, CSS entrypoints and intentional exceptions. In that consumer's browser CI, check that expected application routes render `[data-slot="navigation"]` and `[data-slot="site-footer"]`, and that anchors remain stable between wide lists and narrow forms. Include narrow/zoomed screens, localized labels and tall content that introduces a scrollbar. Keep table overflow local.
+
+A blanket ban on `<header>`, `<nav>` or `<footer>` would also reject valid section landmarks and adapters. Review the root composition and its rendered output instead. This repository checks packed React/Next examples; external applications still need their own upgrades, adapter migrations and CI. Publication and deployment are separate work.

package/docs/components/common.md

@@ -1,12 +1,12 @@
 # Shared usage contract
 
-These guides describe **@naeil/ui 0.3.0, published 2026-10-03** ([release](https://github.com/naeil-dev/naeil-ui/releases/tag/v0.3.0)); [live Docs and Usage examples](https://naeil-dev.github.io/naeil-ui/) are available. Start with the [consumer setup and migration](../design/v2-migration.md). All listed exports are available from `@naeil/ui/ui`; the legacy root needs the optional Next/next-intl peers. Examples import real wrappers; product state, validation and network requests belong to consumers.
+These guides target the **@naeil/ui 0.6.0**; release identities and publication evidence are recorded in the [release record](https://github.com/naeil-dev/naeil-ui/releases/tag/v0.6.0). The [hosted Docs](https://naeil-dev.github.io/naeil-ui/) were last verified for [0.5.0 on 2026-10-15](https://github.com/naeil-dev/naeil-ui/releases/tag/v0.5.0), while `pnpm storybook` shows this checkout. Start with the [consumer setup and migration](../design/v2-migration.md). Primitives and generic Navigation/SiteFooter are exported from `@naeil/ui/ui`; the actual branded whole header uses the opt-in [NaeilHeader](naeil-header.md) entry `@naeil/ui/naeil-header`. Both are React-only. The legacy root needs the optional Next/next-intl peers. Examples import real wrappers; product state, validation and network requests belong to consumers.
 
 ## Styling, themes and overrides
 
 Import `@naeil/ui/globals.css` once and register `@source` for the installed package's `dist` in your Tailwind 4 build. Alternatively load both theme.css and components.css alongside your existing Tailwind setup. Deliver Pretendard and, for Japanese, Noto Sans JP locally through your app's font pipeline; the package does not fetch fonts. Keep font OFL notices with redistributed binaries. The independent React example demonstrates consumer-owned delivery.
 
-Use `.light`/`.dark` on the document root to override OS theme. Root `data-ui-density="compact"` changes spacing, not text size: default controls are 40px, compact 36px, small screens/coarse pointers at least 44px. Portals use document-level styles/density, so a locally themed subtree alone does not theme portaled content. Purpose-specific reading/settings/list widths are 640/640/1200px caps that shrink to available space; the product owns its application frame.
+Use `.light`/`.dark` on the document root to override OS theme. Root `data-ui-density="compact"` changes spacing, not text size: default controls are 40px, compact 36px, small screens/coarse pointers at least 44px. Portals use document-level styles/density, so a locally themed subtree alone does not theme portaled content. Header, main and footer share a 1600px maximum outer frame and `clamp(16px, 2.4vw, 40px)` gutters. Use `ui-app-frame` on main; shared header/footer components apply that frame internally. Reading/settings sections remain capped at 640px, short forms at 480px, and lists at 1600px within the available frame space. Product root token overrides and explicit component classes remain supported. The [application layout guide](application-layout.md) explains composition, adoption and consistent overrides.
 
 `className` is merged by `cn` (clsx + tailwind-merge). Consumer classes and primitive props remain available. Recheck specificity, text/control/focus contrast, mobile targets and portaled content after overriding. Override semantic color companions together; do not replace only an action hue or remove focus outlines. Reduced-motion rules remove shared transitions/animations. Custom consumer animation still needs its own reduced-motion treatment.
 

package/docs/components/naeil-header.md

@@ -0,0 +1,50 @@
+# NaeilHeader — branded whole-header composition
+
+This guide targets the **@naeil/ui 0.6.0**. See the [release record](https://github.com/naeil-dev/naeil-ui/releases/tag/v0.6.0) for archive and publication evidence. Import this opt-in React-only entry when an application inherits the actual naeil.dev header. Generic `Navigation` from `/ui` remains available for different product menus.
+
+```tsx
+import { NaeilHeader } from '@naeil/ui/naeil-header';
+import '@naeil/ui/globals.css';
+
+// Inside the consumer's existing next-themes ThemeProvider:
+<NaeilHeader locale="ja" Link={GuardedLink} currentHref={pathname}
+  authSlot={<LogoutButton />} />
+```
+
+Load shared styles once. Apps that already own their Tailwind/base styles may import both `@naeil/ui/theme.css` and `@naeil/ui/components.css` instead of globals. Tailwind 4 consumers must register the installed `dist` with `@source`; see [setup](../design/v2-migration.md#시작하기).
+
+The module owns the brand, five-project catalog and header-only translations, project artwork references/status, theme/optional locale controls, toolbar order, fixed positioning, branded frame and Radix desktop/mobile behavior. Do not copy menu JSX or styles into a consumer. The website's `NavWrapper` imports this same module and supplies locale/router/auth state; estimate consumes the built package entry. Legacy `Nav` retains its Next/next-intl compatibility API.
+
+## Consumer contract
+
+Consumers provide an existing next-themes provider, routing/dirty-save guard, current locale and real authentication behavior. Default destinations point to `https://naeil.dev/{locale}`; the site's localized Link instead uses `resolveHref={path => path}`. A supplied `Link` handles default official destinations, including cross-origin URLs. `onNavigate` can intercept brand and menu links; honor modified clicks and target behavior. Explicit `external: true` project overrides and `projectsExternal` use native anchors, so intercept them with `onNavigate` when a dirty guard is required.
+
+Only provide `onLocaleChange` when the application's interface supports all three canonical locales (`en`, `ko`, `ja`). Omitting it removes the locale control; the component does not create application translations or shared preferences. `authSlot` contains the consumer's real session action and must retain at least 44px touch targets. It does not integrate site SSO, share credentials or create accounts. Theme preferences remain consumer-origin state. Without a working provider, rendering alone does not establish theme switching.
+
+| Prop | Contract |
+| --- | --- |
+| `locale` | Required `en`, `ko` or `ja`; selects header-only copy. |
+| `resolveHref` | Resolves canonical unlocalized paths; defaults to the official localized site. |
+| `Link`, `currentHref`, `onNavigate` | Routing adapter, active destination and navigation interception inherited from Navigation. |
+| `onLocaleChange` | Optional supported-language callback; omit for a single-language application. |
+| `authSlot` | Consumer-owned authentication action in the default toolbar. |
+| `brandHref`, `brandSlot`, `brandLinkProps`, `brandLinkComponent` | Explicit brand destination/content/anchor overrides; default accessible brand name is `.naeil`. |
+| `projects`, `projectsExternal`, `showProjects`, `showBlog` | Legacy catalog/visibility/native-link overrides; defaults use the complete canonical catalog. |
+| `subNav`, `currentProjectKey`, `currentProjectHref` | Legacy extra links and current-project destination. |
+| `translations`, `labels` | Legacy header/project lookup overrides and navigation/menu/close accessible labels. |
+| `toolbarSlot` | Replaces the complete default theme/locale/auth toolbar. |
+| `mobileFooter`, `className`, `containerClassName` | Inherited mobile slot and style overrides; recheck frame/behavior after changes. |
+
+Standard header attributes and the remaining inherited [Navigation props](navigation.md) remain available. Compatibility overrides preserve existing consumers; new applications normally use the canonical composition.
+
+## Frame and content clearance
+
+The fixed header is 65px: the current 64px navigation token plus a 1px border. Clear it in the application's main, sticky regions and focus/anchor scroll margins with `calc(var(--ui-navigation-height) + 1px)`. The header, main and footer now share a 1600px maximum outer frame, including responsive `clamp(16px, 2.4vw, 40px)` gutters. Put `ui-app-frame` on main and reading/settings or short-form sections inside it; the header and shared footer apply their own internal frame. Do not wrap them in another padded frame. Apply deliberate `--ui-width-frame` / `--ui-frame-gutter` overrides on a common ancestor. Remove old `max-w-7xl` or `px-6` overrides to adopt the new defaults. This width update supersedes the previous 1280px/24px branded frame. See the [application layout starter](application-layout.md).
+
+## Artwork and package boundary
+
+The five decorative images reference `https://naeil.dev/images/{coral,jellyfish,whale,fish,turtle}.png`. Rendering those images requires network access to the official origin. Their bytes are not redistributed in npm; [third-party notices](../../THIRD_PARTY_NOTICES.md) retain unresolved artwork provenance and redistribution limits. Brand marks are not relicensed by the repository MIT license. Captions and links remain usable when images fail.
+
+This entry requires no Next.js, next-intl, site session/auth backend, full application message catalog, hero or site public folder. Generic `/ui` imports do not import its catalog. The local Storybook provides **Brand / NaeilHeader / Docs, Usage, JapaneseApplication**; the Japanese example omits unsupported locale switching and uses a consumer-owned auth slot. Candidate examples do not establish hosted deployment.
+
+Verify actual packed consumption, Storybook behavior and rendered comparisons at matching viewport/language/theme. Source imports alone do not prove visual parity. Native Safari, devices, assistive technology, full OAuth and unresolved accessibility observations retain the [documented support limits](../design/public-ui-support.md).