@naeil/ui 0.1.0 → 0.3.0

package/docs/components/input.md

@@ -0,0 +1,32 @@
+# Input
+
+Use Input for native single-line text/value entry. Use [Textarea](./textarea.md) for multiline text, Select for a small known option set, and Checkbox/Switch for booleans.
+
+## API and wrapper defaults
+
+Export: `Input`. Accepts `React.ComponentProps<"input">`; no wrapper default for `type`, value, disabled or validation. Native omitted type resolves to text. Important props: `value` + `onChange` or `defaultValue`, `name`, `type`, `required`, `readOnly`, `disabled`, `autoComplete`, `inputMode`, `min`/`max`, `minLength`/`maxLength`, `pattern`, form and ARIA props. No built-in label, error text or async validation API.
+
+The [shared usage contract](common.md) covers setup, inherited/native prop typing, themes, density, font delivery and overrides. [Wrapper source](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/src/components/ui/input.tsx) is the API authority.
+
+## Composition
+
+```tsx
+<label htmlFor="email">Notification email</label>
+<Input id="email" name="email" type="email" required
+  autoComplete="email" aria-invalid={invalid}
+  aria-describedby="email-help email-error" />
+<p id="email-help">Used for important updates.</p>
+<p id="email-error" role="alert">{invalid ? 'Enter a valid email address.' : ''}</p>
+```
+
+Import the named components from `@naeil/ui/ui`. Variables/handlers in snippets are consumer-owned. Run **UI / Input / Usage** in Storybook for a complete interactive example; its Docs page renders this same guide.
+
+## Keyboard, focus and accessible content
+
+Tab focuses the input; text/navigation/editing follow the native input type. Consumer validation should focus the first invalid field and retain its value. Use labels and described help/errors; announce asynchronous validation outcomes without announcing each keystroke. Read-only and disabled have different focus/form submission behavior.
+
+## States, resilience and mistakes
+
+Show normal, empty, disabled, read-only, invalid and recovery. Loading may disable submission while preserving editable values; a disabled input is omitted from FormData. Never use placeholder as the only label, mix controlled/uncontrolled values, or lower mobile font size. Long input values scroll inside the native control; wrap helper/error text outside it.
+
+Check this example in light/dark, comfortable/compact and mobile, including long Korean, English and Japanese text. Consumer overrides remain supported; follow the [shared override and acceptance guidance](common.md#styling-themes-and-overrides). Actual engine results and manual limits are in the [support matrix](../design/public-ui-support.md).

package/docs/components/select.md

@@ -0,0 +1,39 @@
+# Select
+
+Use Select for one value from a finite option set. Prefer native select when native platform behavior is essential; use DropdownMenu for actions and text input/search for very large or editable choices.
+
+## API and wrapper defaults
+
+Exports: `Select`, `SelectValue`, `SelectGroup`, `SelectTrigger`, `SelectContent`, `SelectItem`, `SelectLabel`, `SelectSeparator`, `SelectScrollUpButton`, `SelectScrollDownButton`.
+
+Select/Value/Group alias Radix parts. Root: `value`/`defaultValue`/`onValueChange`, `open`/`defaultOpen`/`onOpenChange`, `name`, `required`, `disabled`, `form`, `dir`, `autoComplete`; wrapper sets no root defaults. Trigger forwards button/ARIA props and renders a chevron. Value accepts placeholder. Content creates Portal, Viewport and scroll buttons and defaults **position="popper", sideOffset=6**; forwards position/alignment/collision/Escape/close-focus/outside handlers. Item requires a nonempty string `value`, accepts `disabled` and `textValue`, and creates ItemText/Indicator. No searchable, multiselect or async data API; SelectPortal/Viewport/Icon/ItemText are not public exports.
+
+Inherited [Select 2.2.6 declaration](https://unpkg.com/@radix-ui/react-select@2.2.6/dist/index.d.ts).
+
+The [shared usage contract](common.md) covers setup, inherited/native prop typing, themes, density, font delivery and overrides. [Wrapper source](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/src/components/ui/select.tsx) is the API authority.
+
+## Composition
+
+```tsx
+<label htmlFor="language">Language</label>
+<Select name="language" defaultValue="en">
+  <SelectTrigger id="language"><SelectValue placeholder="Choose language" /></SelectTrigger>
+  <SelectContent>
+    <SelectItem value="ko">한국어</SelectItem>
+    <SelectItem value="en">English</SelectItem>
+    <SelectItem value="ja">日本語</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+Import the named components from `@naeil/ui/ui`. Variables/handlers in snippets are consumer-owned. Run **UI / Select / Usage** in Storybook for a complete interactive example; its Docs page renders this same guide.
+
+## Keyboard, focus and accessible content
+
+Trigger is the labeled combobox. Enter/Space/arrows open; arrows/Home/End/typeahead navigate enabled options; Enter chooses, Escape cancels and focus returns. Name and value allow form submission. Put aria-invalid/aria-describedby on Trigger and visible help/error nearby; SelectLabel labels a group, not the form control.
+
+## States, resilience and mistakes
+
+Show placeholder, selected, disabled root/item, invalid, loading and empty option sets. Loading/empty data is consumer state: disable the trigger and provide external status/retry, not an empty-string SelectItem. Empty string is the clear/placeholder root value. Trigger truncates long text; ensure the full accessible name/value remains available and option text wraps. Theme/density must be on the document root because content is portaled.
+
+Check this example in light/dark, comfortable/compact and mobile, including long Korean, English and Japanese text. Consumer overrides remain supported; follow the [shared override and acceptance guidance](common.md#styling-themes-and-overrides). Actual engine results and manual limits are in the [support matrix](../design/public-ui-support.md).

package/docs/components/sonner.md

@@ -0,0 +1,37 @@
+# Toaster
+
+Use Toaster for brief nonblocking outcome feedback. Keep form errors inline and persistent; use Dialog only when a task needs focused interaction. Critical recovery must remain available after a toast expires.
+
+## API and wrapper defaults
+
+Export: `Toaster`. `toast` is **not** re-exported: import it from `sonner` (declare Sonner as a direct consumer dependency when using its API).
+
+Accepts Sonner `ToasterProps`. Wrapper defaults: theme from next-themes (falls back to `system`), position **bottom-right**, duration **4000ms**, semantic icons and CSS-variable style. Props are spread last: consumer `theme`, `position`, `duration`, `icons`, `style`, `className`, `toastOptions`, `offset`, `mobileOffset`, `closeButton`, `hotkey`, `containerAriaLabel` override wrapper values; `style`/`icons` replace that object, not a deep merge. Mount one instance per intended notification scope.
+
+Inherited [Sonner 2.0.7 declarations](https://unpkg.com/sonner@2.0.7/dist/index.d.ts). Installed Sonner implements polite notifications and Alt+T as its default focus hotkey; these are primitive behaviors, not new wrapper defaults.
+
+The [shared usage contract](common.md) covers setup, inherited/native prop typing, themes, density, font delivery and overrides. [Wrapper source](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/src/components/ui/sonner.tsx) is the API authority.
+
+## Composition
+
+```tsx
+import { Toaster, Button } from '@naeil/ui/ui';
+import { toast } from 'sonner';
+<>
+  <Button type="button" onClick={() => toast.success('Settings saved.')}>Save</Button>
+  <Toaster closeButton containerAriaLabel="Notifications"
+    toastOptions={{ closeButtonAriaLabel: 'Dismiss notification' }} />
+</>
+```
+
+Import the named components from `@naeil/ui/ui`. Variables/handlers in snippets are consumer-owned. Run **UI / Toaster / Usage** in Storybook for a complete interactive example; its Docs page renders this same guide.
+
+## Keyboard, focus and accessible content
+
+Sonner creates its notification region; meaningful text should convey status without color. Name notification/close controls in the product language. The tested keyboard flow uses Alt+T to focus notifications, Tab to an action. Escape collapses the notification stack; moving focus out restores the prior action. macOS WebKit may require Option+Tab/Option+Shift+Tab to include buttons under its default keyboard-navigation setting. Review conflicts before changing hotkeys. Verify actual announcements with a screen reader manually; axe does not prove them.
+
+## States, resilience and mistakes
+
+Demonstrate success/info/warning/error, loading updated by the same id, and an action. Toaster has no disabled/loading prop; those belong to toast calls and initiating controls. With no notifications it renders no message. Keep long multilingual text wrap-safe, use mobileOffset deliberately, avoid duplicate toasters and move persistent errors/retry to the page. Custom style/icons/animations need contrast and reduced-motion verification.
+
+Check this example in light/dark, comfortable/compact and mobile, including long Korean, English and Japanese text. Consumer overrides remain supported; follow the [shared override and acceptance guidance](common.md#styling-themes-and-overrides). Actual engine results and manual limits are in the [support matrix](../design/public-ui-support.md).

package/docs/components/switch.md

@@ -0,0 +1,33 @@
+# Switch
+
+Use Switch for an on/off preference; tell the user whether it applies immediately or on Save. Use Checkbox for consent, selection or a group of options; use Select for more than two values.
+
+## API and wrapper defaults
+
+Export: `Switch`. Forwards Radix Root props: `checked`/`defaultChecked`/`onCheckedChange`, `disabled`, `required`, `name`, `value`, `form`, `id`, button/ARIA props. Wrapper sets no state defaults and always renders its own Thumb; no public Thumb, size, loading or indeterminate API. Graphic is 36×22px with a 44px pseudo-element hit area independent of density. Underlying form mirroring comes from Radix when used in a form.
+
+Inherited [Switch 1.2.6 declaration](https://unpkg.com/@radix-ui/react-switch@1.2.6/dist/index.d.ts).
+
+The [shared usage contract](common.md) covers setup, inherited/native prop typing, themes, density, font delivery and overrides. [Wrapper source](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/src/components/ui/switch.tsx) is the API authority.
+
+## Composition
+
+```tsx
+<div className="ui-choice-label">
+  <Switch id="summary" name="summary" defaultChecked />
+  <label htmlFor="summary">Weekly summary</label>
+</div>
+<p>Changes apply when you save.</p>
+```
+
+Import the named components from `@naeil/ui/ui`. Variables/handlers in snippets are consumer-owned. Run **UI / Switch / Usage** in Storybook for a complete interactive example; its Docs page renders this same guide.
+
+## Keyboard, focus and accessible content
+
+Tab focuses enabled switches; Space toggles and aria-checked exposes the boolean. Keep a stable label across on/off states. The label should activate the control; checked values submit, unchecked/disabled controls are omitted. No mixed state; choose Checkbox if mixed selection is needed.
+
+## States, resilience and mistakes
+
+Demonstrate on/off/disabled and consumer saving/error recovery. Put pending/error/status beside the preference; never claim disabling saves the value. Keep labels and pseudo-element hit areas from overlapping neighbors, check visible thumb/track/focus in forced colors, and let long localized labels wrap. Custom classes must retain state distinction and focus.
+
+Check this example in light/dark, comfortable/compact and mobile, including long Korean, English and Japanese text. Consumer overrides remain supported; follow the [shared override and acceptance guidance](common.md#styling-themes-and-overrides). Actual engine results and manual limits are in the [support matrix](../design/public-ui-support.md).

package/docs/components/tabs.md

@@ -0,0 +1,40 @@
+# Tabs
+
+Use Tabs to switch related panels within one view. Use links for navigation to routes, Select/native radios for values, and DropdownMenu for actions. Tabs does not own routing, data fetching or draft storage.
+
+## API and wrapper defaults
+
+Exports: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`. Each accepts `React.ComponentProps<typeof RadixTabs.Part>`, including element `ref`, `className`, `style`, ARIA and event handlers. There are no custom variants. Root inherits `value`/`defaultValue`/`onValueChange`, `orientation`, `dir`, `activationMode`. List inherits `loop`; Trigger requires a unique string `value` and accepts `disabled`; Content requires the matching `value` and accepts `forceMount`.
+
+The wrappers set only slots/classes. Installed [Radix Tabs 1.1.13 declarations](https://unpkg.com/@radix-ui/react-tabs@1.1.13/dist/index.d.ts) and [runtime](https://unpkg.com/@radix-ui/react-tabs@1.1.13/dist/index.js) supply horizontal orientation, automatic activation, looping focus and enabled triggers by default. **Supply an initial `defaultValue` or controlled `value`**: omitting both leaves no panel selected until activation. `forceMount` is omitted by default: inactive panel containers are hidden and their children unmount. Draft state inside those children resets on remount; hoist state to preserve it.
+
+`forceMount` retains children and makes inactive panels present too. Consumers must explicitly hide inactive content, for example `hidden={value !== 'draft'}`, so it cannot receive focus or appear as a second visible panel. Root has no group-wide `disabled` prop; disable individual triggers. Keep matching values, generated IDs/roles and focus handlers intact.
+
+The [shared usage contract](common.md) covers setup, inherited/native prop typing, themes, density, font delivery and overrides. [Wrapper source](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/src/components/ui/tabs.tsx) is the API authority.
+
+## Composition
+
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@naeil/ui/ui';
+
+<Tabs defaultValue="overview">
+  <TabsList aria-label="Workspace details">
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="history">History</TabsTrigger>
+  </TabsList>
+  <TabsContent value="overview"><p>Workspace summary.</p></TabsContent>
+  <TabsContent value="history"><p>Activity history.</p></TabsContent>
+</Tabs>
+```
+
+Run **UI / Tabs / Usage** and its Docs page for automatic, controlled manual/vertical, disabled, localized overflow and explicitly hidden retained panels. `activationMode="manual"` is useful when switching requires delayed loading; the consumer owns loading/error/retry and status announcements. Automatic activation is suitable when panels are immediately available.
+
+## Keyboard, focus and accessible content
+
+Name the tablist with `aria-label` or `aria-labelledby`. Radix supplies tab/tabpanel relationships and roving focus: horizontal arrows or vertical Up/Down move through enabled tabs; Home/End reach endpoints. Automatic mode activates on focus; manual mode activates with Enter/Space. `dir="rtl"` adjusts horizontal navigation. List `loop={false}` stops endpoint wrap. Tab leaves the list for the selected panel or its controls. Panels have `tabIndex=0` and a visible shared focus outline. Disabled triggers are skipped.
+
+## States, resilience and mistakes
+
+Selection uses a neutral surface and a visible bottom border; focus has a separate outline. The list scrolls locally on one keyboard axis; each trigger is capped to available list width and long labels wrap without shrinking 16px text. Triggers grow above the density minimum to fit enlarged/multiline text. Do not wrap the list itself into ambiguous keyboard rows or truncate every label to fit. Vertical lists need a consumer-chosen width suitable for their labels; use horizontal orientation on narrow screens when needed. Panels wrap long words; check their contents separately from the list.
+
+Theme, root density, 40/36px trigger minimum heights and the mobile/coarse 44px minimum follow the existing system; wrapped or enlarged text increases height. Reduced motion removes color transitions. `className`/style and inherited props remain overrides; test state/focus/overflow after changes. Empty/error/loading panels are consumer content, not Tabs props. See [composition guidance](./composition.md) and the [current support matrix](../design/public-ui-support.md) for manual limits.

package/docs/components/textarea.md

@@ -0,0 +1,35 @@
+# Textarea
+
+Use Textarea for plain multiline text. Use Input for single-line values. Rich-text/code editors, autosizing, chat submission shortcuts and file/paste processing belong to the product.
+
+## API and wrapper defaults
+
+Export: `Textarea`. Accepts `React.ComponentProps<"textarea">`, including React 19 `ref`, `rows`, `cols`, `name`, `form`, `value`/`defaultValue`, `onChange`, `onKeyDown`, `onPaste`, `required`, `readOnly`, `disabled`, `minLength`/`maxLength`, `autoComplete`, `wrap`, ARIA, `className` and `style`.
+
+The wrapper sets only slot/classes; **omitted `rows` retains the native two-row default**. It defaults to vertical resizing, full available width, 16px text, 25px line height and 8px vertical padding. Root density supplies the existing 40/36px minimum, raised to at least 44px on mobile/coarse pointers; rows and text determine the actual multiline height. It has no fixed control height or content autosizing. Consumer `rows`, resizing classes, padding and styles remain available. No label, error, value, validation or disabled default is invented.
+
+The [shared usage contract](common.md) covers setup, inherited/native prop typing, themes, density, font delivery and overrides. [Wrapper source](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/src/components/ui/textarea.tsx) is the API authority. Native props are defined by the installed React 19 declarations and HTML textarea behavior.
+
+## Composition
+
+```tsx
+import { Textarea } from '@naeil/ui/ui';
+
+<label htmlFor="notes">Workspace notes</label>
+<Textarea id="notes" name="notes" rows={4} required
+  aria-invalid={invalid} aria-describedby="notes-help notes-error" />
+<p id="notes-help">Describe the workspace. Enter starts a new line.</p>
+<p id="notes-error" role="alert">{invalid ? 'Enter workspace notes.' : ''}</p>
+```
+
+The screen owns `invalid` and submission. Run **UI / Textarea / Usage** and its Docs page for native row/ref/form behavior, invalid recovery, disabled/read-only controls, localization and field/radio/Select/action composition. See the complete [field composition guide](./composition.md).
+
+## Keyboard, focus and accessible content
+
+Use a visible label and unique ID; placeholder is supplementary. Connect existing help/error IDs with `aria-describedby`; set `aria-invalid` when validation fails. On failed submit preserve the value and focus the invalid field; announce asynchronous outcomes with a status/alert region. Tab focuses the textarea; Enter inserts a newline. The wrapper adds no shortcuts and does not intercept composition events. A consumer chat handler must account for IME and modifier keys itself.
+
+## States, resilience and mistakes
+
+Support empty/placeholder, editable, invalid/recovery, read-only and disabled states. Read-only controls remain focusable and submit their name/value; disabled controls do neither. Native `required` and length constraints are available; server validation remains consumer-owned. Use either controlled `value` + handler or `defaultValue`, and do not switch modes.
+
+Long text scrolls inside the native control and can be resized vertically; labels/help/errors wrap outside it. Check long Korean/English/Japanese, both themes and densities, mobile input size, focus/error boundaries and override classes. Normal and invalid boundaries use existing semantic tokens, reduced motion removes transitions, and shared font delivery stays consumer-owned. Do not lower essential mobile text or remove focus to imitate a specialized editor. [Support and manual acceptance](../design/public-ui-support.md) distinguish engine checks from Safari/screen-reader/device certification.

package/docs/design/component-demand.md

@@ -0,0 +1,30 @@
+# Demand-led component decision — 2026-10-02
+
+This extends the approved shared system with **Tabs and Textarea only**. Form fields and native exclusive choices receive composition guidance. It adds no dependencies, product workflows, website redesign or RadioGroup/FormField API. Prepared package 0.3.0 remains unpublished.
+
+## Evidence and boundaries
+
+A read-only audit inspected reachable application manifests and UI source, traced imports to route render sites, and distinguished installed package imports from local primitives. Exact private source/call-site/hash provenance was retained privately and directly checked before scope acceptance. Public roles below describe that bounded local sample, not an ecosystem survey or promised migration. Worktrees/snapshots, unused wrapper files and menu-radio definitions were excluded from adoption counts. No consumer repository was edited or executed.
+
+| Candidate | Actual observed demand | Decision / smallest reusable contract |
+| --- | --- | --- |
+| Tabs | Four route-reachable panel compositions across three distinct products: a report detail view, a collaboration shell, dashboard detail, and usage windows. All four use locally copied Radix tabs, including the product separately installing @naeil/ui 0.1.0 for navigation/theme/locale compatibility imports. | Adopt Root/List/Trigger/Content wrappers forwarding Radix props/ref/classes. Shared panel relationships, keyboard focus and neutral states are absent from the existing 11 families. No package Tabs adoption is claimed. |
+| Textarea | Repeated routed description/brief fields, composer and correction flows in one copied-UI product. A second product's native file editor corroborates multiline input, but is not another styled-wrapper adopter. | Adopt native textarea props/ref and shared focus/invalid/type/density styling. Input cannot replace multiline entry. Native HTML supplies editing/form behavior; the wrapper avoids repeated visual drift. Autosizing, chat shortcuts and editor behavior remain product-owned. |
+| FormField | Labels repeat around different controls; help/error/validation lives in the consumer and existing repository examples. No common form-state/context API is used in the sample. | Use label/ID, described help/error and state composition; no new wrapper or form-state dependency. |
+| RadioGroup | No application RadioGroup/native-radio use was observed. One routed product uses exclusive answer buttons, establishing candidate single-choice composition demand. Unused legacy choice/workbench code and action-menu radio exports are not additional adopters. | Document native fieldset/legend/same-name radios and compact Select. Defer a styled RadioGroup API until a broader shared contract needs it; this is not a claim that exclusive-choice demand is absent. |
+
+## Contract and cost
+
+[Tabs](../components/tabs.md) keeps installed Radix defaults: horizontal, automatic activation, looping focus, no invented initial value or forced mounting. [Textarea](../components/textarea.md) keeps native two-row and vertical-resize defaults and all native handlers/constraints. Existing semantic palette, Pretendard/Japanese companion, 16px text, density/touch minima, purpose-specific widths, short/reduced motion and class overrides remain the authority in [DESIGN.md](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/DESIGN.md). No new numeric token is needed.
+
+The runtime cost is thin wrappers and existing shared CSS; Radix Tabs already comes through the installed radix-ui dependency. Maintenance includes two exact deep entries, docs/stories, state/keyboard/form/override regressions and packed type/runtime checks. There is no new dependency, unused visual variant, form context or cross-product business contract. Revisit deferred candidates when repeated real usage needs more than native composition.
+
+## Reproducible repository evidence
+
+The external audit is a private local sample; these repository artifacts reproduce the accepted common contracts without exposing private applications:
+
+- [Field/choice guide](../components/composition.md), source `src/stories/extension-examples.tsx`, standalone `src/components/ui/{tabs,textarea}.stories.tsx`, and the real packed example `examples/react/src/App.tsx`.
+- Units: `pnpm exec vitest run src/lib/design/__tests__/extension.test.ts`.
+- Rendered Docs/Usage and behavior: `pnpm build:storybook`, then `pnpm exec playwright test e2e/extension.spec.ts --project=chromium --project=webkit`.
+- Distribution: `pnpm build:pkg`, `pnpm check:package` (actual isolated React and Next tarball installs).
+- [Dated Stage 4 verification](public-ui-stage4-verification.md) records commands, source identities, actual results and limits. The [Stage 3 report](public-ui-stage3-verification.md) remains dated evidence of its original 11-family scope.

package/docs/design/public-ui-final-verification.md

@@ -0,0 +1,96 @@
+# Final CI correction follow-up — 2026-10-02
+
+This follow-up starts from `bcf99fca3467ae2b1cd29d54fa24f2569fb6001c` and covers the bounded test-harness and React-fixture corrections. Stage 4 independent review at that baseline does not approve these later changes. At the initial local freeze, the corrected source still required its own scoped review and Linux CI acceptance; the completed results at `9f90493abb4fb1186c948084026c3f4c04074013` are appended below. No publication or deployment was performed.
+
+## Baseline and causal evidence
+
+The actual [push run 36945564443](https://github.com/naeil-dev/naeil-ui/actions/runs/36945564443) passed package-and-site; its browser job recorded 207 passed, 4 skipped and 2 failed: Chromium workspace axe concurrency and WebKit Avatar Docs text ambiguity. The actual [PR run 36945943651](https://github.com/naeil-dev/naeil-ui/actions/runs/36945943651) passed package-and-site; its browser job recorded 208 passed, 4 skipped and 1 failed: the same Avatar Docs ambiguity. Firefox application tests passed in both Linux baseline runs. Neither overall run was green.
+
+Root's separate local baseline verification at that SHA recorded 140 Chromium/WebKit passes and 2 expected WebKit forced-colors skips; actual built 13-family Docs/Usage/notices, the independent packed React/Next consumers and both-engine packed extensions, website compatibility build with dummy public configuration, 21 pinned HTTP targets returning 200, and both-engine `/naeil-ui/` Docs-to-Usage/font/network checks passed. Those are historical baseline results, not results for this correction patch.
+
+The baseline focused rerun passed 18 cases; that alone did not reproduce the intermittent Linux race. A deterministic rendered probe waited for both the guide code and real Avatar group, then reproduced the original strict-mode assertion failure in both engines: the snippet's token and the group's screen-reader count both match `3 additional members`.
+
+A separate diagnostic probe instrumented only the served axe module in temporary browser contexts. It preserved the real addon `axe.run` and invoked real `runPartial` immediately after that run started, reproducing the exact concurrent-scan exception in Chromium and WebKit. This is a diagnostic overlap probe, not an unmodified acceptance run. Storybook 10.4.6's actual URL parser uses dot notation for objects: the earlier `a11y:(manual:!true)` URLs left the rendered `a11y.manual` **false**. Those spellings did not establish manual scan ownership. With `a11y.manual:!true`, the actual global is **true**, the diagnostic records zero automatic addon runs, and controlled workspace axe scans finish with zero violations in both engines after finite transitions settle.
+
+The React fixture's old `closeBundle` copied font notices relative to process cwd. The existing clean-consumer checker starts and closes the fixture's Vite development server in the repository process; that close hook wrote duplicate notices into package `dist/licenses`. A scratch caller/fixture probe reproduced both misplaced OFLs. The persistent regression gate loads a copied unchanged real fixture config/helper through the scratch-installed Vite, executes only the named font-notices plugin from another cwd, and asserts exact installed font notice bytes in fixture output with no caller output. It failed on the old configuration with `Closing the fixture must not create caller output`, then passed after correcting paths to Vite's resolved root/output directory. Scratch cleanup restores cwd and runs on failure. No real consumer or caller output is deleted to pass the test.
+
+## Changes and verification
+
+- Workspace, component Usage and extension test URLs use the verified `a11y.manual:!true` global. Storybook's default addon configuration remains unchanged, and every existing controlled axe scan remains in place.
+- Avatar Docs separately checks the displayed group/count code, the actual named group's accessibility snapshot, and visual `+3` shorthand. Mobile Avatar snapshots, accessible counts and axe checks remain in place.
+- The React fixture resolves both notice inputs and output from Vite's actual resolved configuration. Both original font OFLs remain delivered in standalone consumer output.
+- `node --test scripts/consumer-font-notices.test.mjs` is an explicit package-and-site CI gate. It installs only versions already declared by the fixture for Vite, the Tailwind Vite plugin and the two font packages; transitive peers are installed by npm. It does not add root dependencies, install the application package, or use root's transitive Storybook Vite as a substitute. As with clean-consumer checks, a cold npm cache requires network; installation uses `--ignore-scripts --no-audit --no-fund` without a lockfile.
+- This report is included in the tarball so maintained support/release links resolve in packed consumption. No other manifest contract changes.
+
+Correction verification commands and results are recorded separately from the baseline:
+
+| Command / probe | Result |
+| --- | --- |
+| Focused workspace light/dark axe + Avatar Docs, Chromium/WebKit, three repetitions | 18 passed |
+| Full `pnpm test:browser --project=chromium --project=webkit` | 140 passed / 2 expected WebKit forced-colors skips |
+| `node --test scripts/consumer-font-notices.test.mjs` | Old configuration red; corrected configuration 1 passed |
+| `pnpm test` | 8 files / 41 tests passed |
+| `pnpm check:types` | Passed |
+| Scoped ESLint for the three specs, fixture config and regression gate | Passed |
+| `pnpm lint` | No errors; existing unused `locale` website warning retained |
+| `pnpm check:contrast` | All token contrast combinations passed |
+| `pnpm build:pkg` + generated-token drift check | Passed; generated CSS unchanged |
+| `pnpm check:package` | Packed boundary and clean React/Next consumers passed; both-engine packed extensions and exact consumer font notices passed |
+
+Local verification uses macOS arm64, Node 22.23.2, Playwright 1.63.0, Chromium 153.0.8010.12 and WebKit 26.6, Storybook 10.4.6 and axe Playwright 4.13.0. A fresh installed Firefox launch still failed before the application with `Could not find profile folder`; local Firefox acceptance remains blocked. At this initial local freeze, corrected Linux CI results were pending root freeze and branch push. The subsequent exact-commit acceptance is recorded below without extending it to a future documentation commit.
+
+## Artifact identity and limits
+
+At baseline, an isolated package build/boundary check recorded **103 files / 412,826 unpacked bytes**. After the old clean-consumer development-server close hook, the package archive recorded **105 files / 421,559 unpacked bytes**, SHA-256 `ffcf3dbbcd3854f8214780ff307c842f3c2148eadfc70b724306e90920149736`, identical to the prior link-only archive. The extra files were exactly the duplicate `dist/licenses/Pretendard-OFL.txt` and `dist/licenses/Noto-Sans-JP-OFL.txt`; root-level notices existed in both. Storybook/site build order alone did not explain them. These baseline artifacts are retained, not relabeled as correction artifacts.
+
+The initial corrected package was built fresh through the normal package build, then checked before and after clean consumers. Its archive retained root-level notices, omitted the accidental duplicate dist notices and included this new report plus maintained CI-state documentation. That historical correction archive had **104 files / 424,537 unpacked bytes**, SHA-256 `65daffadb65aa2635fdb48b9340642a22d4cf7ba1d0faaca10d96da43e2351ee`: the package build removed the two accidental duplicate files through its normal clean operation, and the approved manifest included one new verification report. This identity remains the original freeze evidence. Later prose changes produce a different archive checksum; their exact manifests and SHA-256 are frozen separately, without a circular self-checksum in the packed report.
+
+Root inspected 94 baseline broad-suite axe attachments: zero violations, with incomplete rules **aria-hidden-focus, aria-valid-attr-value, bypass and color-contrast**. Dialog hidden backgrounds/focus guards and DropdownMenu submenu `aria-controls` occur in those incomplete records. They remain manual/diagnostic obligations; this report does not label every incomplete as verified or suppress rules. Stage 4's narrower extension result remains a separate scope. Independent extraction of the corrected HTML report inspected all **94** axe attachments: **zero violations**, with the same four incomplete rule IDs retained. Existing keyboard/focus tests passed, but those results do not resolve every incomplete. The separate workspace axe assertions also passed. The clean-consumer development StrictMode probe produced the same 34 Vite font allow-list warnings as the baseline; its pass covers overlay ownership/replay, while loaded-font claims come from the production consumer probes.
+
+Automated snapshots, keyboard/focus tests, media emulation and axe do not certify screen-reader announcements, physical devices, native Safari, native zoom or Windows high contrast. No runtime/API/style/token/export/guide-base change was made. Earlier dated evidence and prior findings remain intact.
+
+## Frozen implementation source identities
+
+These SHA-256 identities identify the correction files tested locally on top of the baseline, not a future commit. The bounded source and artifact manifests are frozen separately for scoped review.
+
+| File | SHA-256 |
+| --- | --- |
+| `e2e/ui-v2.spec.ts` | `2ab2032eea88a52c752f1ec153c217d3eb8f59e8d833e4f6564c6a382c233de8` |
+| `e2e/component-usage.spec.ts` | `787784da3ec6c896944096a20d50c486fbc96ab1b6dce256bfd2a2dc55bf4fd4` |
+| `e2e/extension.spec.ts` | `fbdb377fe6f64f2675370825beb228dda85e21f50cefe0703cac074a0543eb68` |
+| `examples/react/vite.config.mjs` | `48ffb3e5052c6f4e47f8668842a61574ed09b856c38596b2212e253ea56e4ef4` |
+| `scripts/consumer-font-notices.test.mjs` | `3f858428c734634b3524a14e42231f95717a4c41640d03478728de5f4eb8e0cf` |
+| `.github/workflows/verify.yml` | `e9d0c393c3b7cd461ae374c9526b46ba7187bd8d70070bca19c8bc7fe7233590` |
+
+## Post-freeze review and Linux acceptance — source `9f90493`
+
+The exact correction commit `9f90493abb4fb1186c948084026c3f4c04074013` received independent scoped review approval with no actionable findings. The reviewer freshly checked 8 focused browser cases, the font-notice gate, types, scoped lint, clean packed React/Next consumers and both-engine packed extensions; inspected the actual red/manual-true probes, ten frozen source hashes, archive identity and all 94 local axe attachments. This approval covers the correction source at that commit. It does not approve publication or complete the manual platform checks.
+
+Both actual Linux workflows completed successfully at that exact source: [push run 36948276767](https://github.com/naeil-dev/naeil-ui/actions/runs/36948276767) and [PR run 36948280881](https://github.com/naeil-dev/naeil-ui/actions/runs/36948280881). The PR browser job recorded **209 passed / 4 expected forced-colors skips** across Chromium, Firefox and WebKit: 71 Chromium passes, 69 Firefox passes and 69 WebKit passes, with two skipped forced-colors cases in each of Firefox/WebKit. Package-and-site passed, including 41 unit tests, 46 token contrast combinations, types, lint, generated-token drift, package/site builds, clean consumers and the font-notice gate. Optional helper regressions also passed: Node suites of 12 and 16 tests, and 8 Python tests. These results certify the tested source and configured environments, not every browser/peer version or any later commit. The unchanged local Firefox profile launch block remains a separate limitation.
+
+The actual PR [Storybook artifact 11202888717](https://github.com/naeil-dev/naeil-ui/actions/runs/36948280881/artifacts/11202888717) was downloaded and checked: 838 files, all 13 Docs/Usage families, and exact repository/font notice bodies. Root served that downloaded artifact under `/naeil-ui/` and exercised Docs-to-Usage navigation and locally loaded Pretendard/Japanese fonts in Chromium and WebKit, with zero failed requests/errors. This is verification of the downloaded CI artifact, not hosted Pages publication. No Vercel deployment record exists for this source; main remains `d963dc5c1bbd49a1159d445edbb4c30309d96db9`.
+
+This result append changes only this report, the maintained support matrix and release guidance. Packed boundary/relative-link checks, unchanged implementation/runtime hashes and exact notice-byte comparisons verify the documentation update; no browser, consumer or Storybook rebuild is needed solely for this prose. Its three replacement hashes and new archive identity are frozen in a separate external manifest. The original six implementation-source hash rows, failed baseline counts, red/green evidence and historical archive identities remain intact. Root will commit/push the documentation update for the latest-head automatic checks; no future-head CI pass is claimed here. [Live PR checks](https://github.com/naeil-dev/naeil-ui/pull/1/checks) show that later status. Main merge, npm publication, tags, Releases and hosted documentation remain separate authorization decisions.
+
+## Forced-colors keyboard timing follow-up — 2026-10-02
+
+At exact source `e171f4b03b4afe9d2b645ecd4c4aa52c242a1052`, [PR run 36950041237](https://github.com/naeil-dev/naeil-ui/actions/runs/36950041237) succeeded with **209 passed / 4 expected forced-colors skips**, while the identical-head [push run 36950036947](https://github.com/naeil-dev/naeil-ui/actions/runs/36950036947) failed with **208 passed / 4 expected skips / 1 Chromium forced-colors failure**. The failed trace and screenshot show History selected and outlined while the test expected Overview's outline. The original `9f90493` review, green results and six source hash rows above remain historical evidence for that source.
+
+The causal diagnostics used real compiled Storybook assets in an isolated scratch server, without rebuilding or changing component behavior. The downloaded `9f90493` CI artifact was retained byte-for-byte for replay; the e171 trace's captured HTML/CSS/fonts matched it. The local iframe assets also matched; differences in project metadata and two manager bundles were outside this iframe replay. Installed Radix Tabs 1.1.13 delegates directional movement to Roving Focus 1.1.11, whose key handler schedules `focusFirst(candidateNodes)` with `setTimeout`. Tabs selects automatically on focus.
+
+An ungated instrumented replay recorded both ArrowRight and ArrowLeft targeting Overview before either directional callback ran. With two enabled tabs, both callbacks computed History as their first candidate; the second callback found History already focused and returned. A deterministic diagnostic gate held only the real directional callbacks: the old sequence ended with History focused/selected and Overview's outline `none`, failing the original solid-outline requirement. Releasing ArrowRight's callback and verifying History focus/selection before ArrowLeft made the reverse key target History; releasing that callback returned Overview focus/selection with a solid outline, 2px selected border and nontransparent border color. These are causal diagnostics, not additional platform acceptance or a change to production scheduling.
+
+Only the existing forced-colors test block now asserts initial Overview focus/selection, then History focus/selection after ArrowRight, then Overview focus/selection after the real ArrowLeft key. All original outline, selected-border width/color and invalid-Textarea outline/alert assertions remain. No arbitrary delay, retry, skip, direct selection or runtime/Storybook configuration change was added.
+
+Fresh scoped verification on macOS arm64 with Node 22.23.2 and Playwright 1.63.0:
+
+| Command / probe | Result |
+| --- | --- |
+| Diagnostic directional callback gate, old sequence versus state barrier | Old sequence red; state barrier green; zero page errors |
+| `pnpm exec playwright test e2e/extension.spec.ts --project=chromium --grep 'Extensions forced-colors' --repeat-each=10` | 10 passed |
+| `pnpm exec playwright test e2e/extension.spec.ts --project=chromium --project=webkit --grep 'Tabs automatic\|Tabs controlled'` | 4 passed |
+| `pnpm check:types` and `pnpm exec eslint e2e/extension.spec.ts` | Passed |
+| `git diff --check` | Passed |
+| `pnpm check:package:boundary` and fresh `npm pack --ignore-scripts --json` comparison | Passed; packed relative links resolve; only this report's tar entry changed |
+
+The package comparison retains every other tar entry and exact legal notice bytes, with separate before/after archive identities in the external freeze manifest. The two-file patch, source hashes, failed trace and key/focus timelines are preserved for independent focused review. No broad suite, clean-consumer or Storybook rebuild was repeated for this test/report correction. At this local two-file freeze, independent review and corrected exact-head Linux CI were pending; [live PR checks](https://github.com/naeil-dev/naeil-ui/pull/1/checks) show subsequent status, without claiming a future commit identity or CI approval here. Existing local Firefox and manual platform limitations remain unchanged.

package/docs/design/public-ui-release-validation.md

@@ -0,0 +1,86 @@
+# Native environment and remaining manual validation — 2026-10-02
+
+**Native/manual acceptance remains open.** This follow-up records actual local capability probes and their blockers at accepted checkout `79d9382f62166e99eeb26c785e690bf90cbb5379`. It does not change the shared UI, close prior accessibility findings, certify every supported platform, or make a publication decision. Existing automated results remain in [the final verification report](public-ui-final-verification.md); maintained support policy is in [the support matrix](public-ui-support.md).
+
+## Actual environment and execution
+
+| Probe | Observed result | Scope |
+| --- | --- | --- |
+| `sw_vers` | macOS 27.0.1, build `26A434` | Actual local OS. |
+| `/usr/bin/safaridriver --version` | Safari 27.0.1, build `22625.1.29.11.28` | Installed native SafariDriver; version alone is not application verification. |
+| Owned SafariDriver `/status` | `ready: true` | Driver started on a newly allocated local port. Readiness did not establish a session. |
+| Actual `POST /session` with `browserName: safari` | HTTP 500, `session not created`; exact message below | No usable Safari automation session and no application page/control assertions. |
+| AppleEvents no-prompt preflight | Initially `-600` while Safari was absent; subsequently `-1744` | Initial result was application-not-running, not permission acceptance. Subsequent result is `errAEEventWouldRequireUserConsent`. No AppleScript event was sent to request consent. |
+| `AXIsProcessTrusted()` without a prompt | `false` | The diagnostic process lacked Accessibility trust. Native keyboard/menu control and accessible-tree inspection were not established. |
+| VoiceOver process check; VoiceOver Utility Info.plist | VoiceOver not running; Utility version 10, build 993 installed | VoiceOver was not enabled or executed. No speech/captions were observed, and no screen-reader usability pass is claimed. |
+| Playwright Firefox default launch | Firefox 155.0, build `15526.9.2`; process exit 1, `Could not find profile folder` | Failed before loading the application. |
+| One Firefox follow-up with an existing new canonical temporary profile | Same exit 1 and `Could not find profile folder` | Explicit isolated persistent profile did not resolve the failure. Profile removed; no reinstall, global preference change or further blind retry. |
+| Existing Storybook served on an owned random loopback port | `index.html`, `iframe.html`, `index.json` and one asset from each bundled font family returned HTTP 200 with bytes identical to disk | Artifact delivery only. Neither rendered font selection nor Safari layout was observed. |
+
+SafariDriver's exact session error:
+
+> Could not create a session: You must enable 'Allow remote automation' in the Developer section of Safari Settings to control Safari via WebDriver.
+
+No global preference, TCC setting, VoiceOver state or existing browser profile was changed. The failed SafariDriver session attempt nevertheless launched Safari, which had not been running initially. It returned no session/window identifier. Existing or restored windows were not inspected, navigated or closed, and no global Safari quit/kill was issued. The owned driver and local artifact server were stopped. An operator's settings confirmation alone must not be promoted to acceptance: a future retry must obtain an actual successful `/session` response before testing pages.
+
+## Artifact and source identity
+
+This run reused the existing local `storybook-static` build without rebuilding or editing it. Its full sorted relative-path SHA-256 manifest contains **838 files**, and the manifest text has SHA-256 `0f996659cf9892376a897e9fb389732274c27cb0fa0def75e6baf86169015614`. Each line is `<file SHA-256><two spaces><relative POSIX path><newline>`, sorted by path. This identifies the reused artifact; it does not independently prove that it is a downloaded CI artifact or establish its build provenance.
+
+| File | SHA-256 |
+| --- | --- |
+| `storybook-static/index.html` | `f351829970d55bcb8799daecbc2dcf96ce55faa8950f7c115273ae0faf2b1176` |
+| `storybook-static/iframe.html` | `db62cb99d67cc6e87ce6cc3d3e5de3c366ad9d16498cd165df7012fb77971ef6` |
+| `storybook-static/index.json` | `b4543eb1f0cbcb643ead1ee59b1c06de9271e38b8154cf3d62ac698796264993` |
+| `e2e/ui-v2.spec.ts` | `2ab2032eea88a52c752f1ec153c217d3eb8f59e8d833e4f6564c6a382c233de8` |
+| `e2e/extension.spec.ts` | `83f90028ca04d8fade46b6261e6363916f4aad09f44113106ed6a5ecdb7b54b4` |
+| `src/styles/theme.css` | `210ce5a83f61eb1f856f405d2a25b1a2e1be835329c2b251221e4d052ba4fece` |
+
+The served index contains `ui-v2--workspace`, `ui-tabs--usage` and `ui-textarea--usage`, pointing to their real repository stories. Raw capability responses, launch logs, served-byte comparisons and the full artifact manifest were retained outside the repository. No Safari screenshot, Safari DOM probe, native AX snapshot or observed screen-reader output was produced. Earlier Playwright WebKit results are separate engine evidence; they are not a substitute for native Safari. Earlier Linux Firefox application passes remain valid for their recorded source/run, while this local launch blocker remains unresolved.
+
+## Reproduction and native checks still required
+
+For a manual run, serve the unchanged build from the repository root on a newly allocated port:
+
+```sh
+python3 -m http.server 0 --bind 127.0.0.1 --directory storybook-static
+```
+
+Read the actual port from the server output. Use a new window owned by the tester and record its identity; preserve other windows and the user's theme, zoom, keyboard-navigation and assistive-technology settings. Close only the owned window and stop only the owned server/driver. Do not enable automation or change system settings as a side effect of a test script. The exact Safari settings blocker above must be resolved by the operator before automated native checks can run.
+
+The session request used in this run was:
+
+```json
+{"capabilities":{"alwaysMatch":{"browserName":"safari"}}}
+```
+
+It was sent to a locally launched `/usr/bin/safaridriver -p <unused-port>` at `POST http://127.0.0.1:<unused-port>/session`. Record the actual response and browser capabilities. A successful session may support WebDriver keyboard actions and programmatic DOM assertions; label those as automated native Safari checks. They do not establish human keyboard or screen-reader usability, and browser UI page zoom needs separate evidence.
+
+Open `/iframe.html?id=ui-v2--workspace&viewMode=story&globals=a11y.manual:!true`, and family stories using `/iframe.html?id=ui-<family>--usage&viewMode=story&globals=theme:light;density:comfortable;a11y.manual:!true`. Repeat with `theme:dark` and `density:compact` as appropriate. The verified dot notation `a11y.manual:!true` avoids concurrent automatic addon scans when a controlled axe scan is actually used. It does not disable or replace human checks.
+
+The expected behavior below comes from the actual `e2e/ui-v2.spec.ts`, `e2e/component-usage.spec.ts` and `e2e/extension.spec.ts`, rather than inferred component names. **All rows remain unrun in native Safari in this follow-up.**
+
+| Check | Reproduction and expected result |
+| --- | --- |
+| Dialog (`ui-dialog--usage`) | Focus “Edit workspace”, Enter: focus “Workspace name”. Tab and Shift+Tab remain inside the modal. Empty save keeps focus and shows invalid state; long Korean/English/Japanese input survives recovery. Save completion and Escape return focus to the trigger. Confirm visible focus and scrollable content. |
+| Select (`ui-select--usage`; workspace language input) | Enter opens value options; type `e` focuses English in the family story; Enter selects it and restores trigger focus. Submit reports `en`. Loading disables the trigger; empty state exposes retry. In the workspace, End focuses the final Japanese option, ArrowUp focuses English; Escape closes without changing the selected value. Check disabled-option skipping and popup scrolling. |
+| DropdownMenu (`ui-dropdownmenu--usage`) | ArrowDown opens “Workspace actions” on “Copy reference”. Next eligible item is mixed “Show completed”; Enter changes it to checked and restores trigger focus. Radio action updates sort text. ArrowRight on “More actions” enters “Export details”; activation reports completion. Escape restores trigger focus. |
+| Tabs (`ui-tabs--usage`) | Automatic horizontal arrows skip “Unavailable”, activate History and loop; Home/End work. Temporary panel draft resets after unmount. Vertical manual tabs move focus with arrows but change selection only on Enter/Space; disabled looping stops at the end. Retained hidden draft remains intact. Localized long tab labels scroll inside their tablist with the focused last tab visible. |
+| Textarea (`ui-textarea--usage`) | Empty save focuses “Workspace notes”, sets invalid and displays the persistent error. Enter Korean/English/Japanese and a newline; editing clears invalid state without losing content. Confirm native two/four rows and resize policy. Native radio arrows change delivery; labels activate their radio. Save shows busy state then “Saved digest / en. (Example)”. |
+| Light/dark, density and long content | Compare matching window dimensions and content. Use all three languages, long labels and multiline errors. Check focus and field boundaries, disabled state, overlays, persistent errors/retry, and text wrapping. Keep application frame and purpose-specific content widths separate. |
+| Narrow window / mobile layout | In a desktop Safari narrow window record actual `innerWidth`, minimum supported window size, overflow and overlay scrolling. A desktop narrow window or responsive emulator is not a physical mobile pass. Physical-device checks remain below. |
+| Native 200% and 400% page zoom | Use Safari's native page-zoom control in the owned window. Record the browser UI percentage and baseline/zoomed `innerWidth`, screenshots, long-dialog scrollability, labels and persistent recovery actions. Check the 320 CSS-pixel equivalent when attainable. CSS `zoom`, root font-size changes and device/media emulation do not meet this row. Restore owned-window zoom. |
+
+Native controls can depend on the user's keyboard-navigation setting. Record it and actual key sequences; do not silently change a global setting to make a test pass. Screenshot inspection, DOM measurements, WebDriver focus assertions and AX snapshots should each be labeled with their actual method.
+
+## Remaining human/platform acceptance
+
+| Environment / task | Current status and evidence to collect |
+| --- | --- |
+| Safari 27.0.1 with VoiceOver | Blocked here by absent AppleEvents consent/Accessibility trust and no safe observed-output path. With an operator, preserve/restore VoiceOver state; observe actual speech or real captions for labels/help/errors, switch checked, checkbox mixed, selected language, dialog title/focus return, selected tabs/panels, textarea/radio values and toast outcomes once. Axe, AX snapshots and `say` are not screen-reader acceptance. |
+| Windows with NVDA and actual high contrast | No Windows environment was exercised. Record Windows/browser/NVDA versions; hear the same state transitions and check real high-contrast text, field boundaries, focus, switch/checkbox indicators, selected tab and invalid textarea in enabled/disabled states. Chromium forced-colors emulation does not close this row. |
+| Physical iOS Safari / Android Chrome | No physical device was exercised. Record hardware/OS/browser, portrait/landscape, software keyboard opening, native input auto-zoom, 44px targets without adjacent overlap and scrollable overlays. Desktop/mobile emulation does not close this row. |
+| OS text enlargement, font/network failure and product-specific flows | Actual OS text enlargement and human fallback/readability checks remain open. Test long real data, slow/offline font loading and persistent error/empty/retry states in the consuming app. HTTP font delivery above does not prove loaded-face rendering or fallback usability. |
+| Consumer keyboard overrides and prior axe incompletes | Recheck consumer class/focus/outside-handler overrides, nested Dialog/Select, removed/triggerless focus return and logical Tab order. Preserve prior `aria-hidden-focus`, `aria-valid-attr-value`, `bypass` and `color-contrast` incomplete findings until the affected states are reviewed; a launch diagnostic closes none of them. |
+
+Record source/artifact identity, tester, date, actual OS/browser/AT version, method, expected/observed behavior, screenshot or observed-output evidence and remaining findings for each completed row. This report adds no native component pass and leaves all human/platform acceptance rows open.

package/docs/design/public-ui-stage3-verification.md

@@ -0,0 +1,98 @@
+# Public UI usage verification — 2026-10-02
+
+The original Stage 3 implementation was verified locally against the original source hashes below, based on frozen Stage 2 `8bbbdf62d9a3cc6794d2c5fcf7cfafeca034dbb8`, and frozen at `80732074349b35d41e31b674f248171101481742`. Independent review found one P3 Avatar example accessibility issue; the focused correction and its replacement hashes are recorded separately below, pending an independent scoped recheck. This evidence does not authorize publication. No commit, push, package publication, workflow dispatch or site deployment was performed by either executor.
+
+Authority: DESIGN.md, the shared v2 specification/migration and actual wrappers/installed primitive declarations. Scope: maintained guides and runnable Docs/Usage for all 11 existing families, accessibility/resilience examples, documented public support, independently packed consumption, preview asset/notices boundary and manual-only deployment preparation. The public export allowlist, approved palette/fonts, numeric foundations and product/site scope remain unchanged.
+
+## Original frozen broad verification
+
+Local execution used Node 22.23.2, pnpm 10.30.3 and Playwright 1.63.0 on macOS. Installed browser metadata identifies Chromium 153.0.8010.12, WebKit 26.6 and Firefox 155.0.
+
+| Command / check | Observed result |
+| --- | --- |
+| `pnpm test` | 7 suites, **37/37 passed**. |
+| `pnpm check:types` | Passed. |
+| `pnpm lint` | 0 errors; one pre-existing unused `locale` warning in the website blog route. Generated preview/test reports are excluded from lint. |
+| `pnpm build:tokens` then `git diff --exit-code -- src/styles/theme.css` | Passed; generated CSS has no drift. No generated CSS was hand-edited. |
+| `pnpm check:contrast` | **40/40 semantic pairs passed** across light/dark. |
+| `pnpm build:pkg` | Bundled/deep builds and declarations passed, including the internal-only helper entry. |
+| `pnpm check:package` | Packed boundary and clean independently installed React + Next consumers passed. Finalized guide/report links and payload also passed `pnpm check:package:boundary`. |
+| Independent React browser | 390px light/dark: actual local Pretendard Korean/Latin + Noto Sans JP faces loaded; no page overflow; native required-field rejection, preserved localized input and save recovery passed. Deliberately blocked fonts remained unavailable while fallback form stayed operable. **47 actual consumer-code package notices** and exact consumer-owned font OFLs passed. |
+| Mixed public imports | Bundled `/ui` and deep menu imports passed overlapping inert ownership in both close orders, forced removal, existing inert preservation, object refs and focus restoration. Independently installed Vite development mode confirmed **two StrictMode effect setups**, then reran the same checks; production mode also passed. |
+| `pnpm build:storybook` | 11 actual built Docs entries + 11 runnable Usage entries; exact repo/shadcn/OFL copies and bundled fonts; no website images/SVG/HTML copied. **74 actual Vite preview package notices + 254 conservative manager package-version notice entries** passed. |
+| `python3 scripts/refresh-storybook-notices.py` | Opt-in source/npm refresh actually completed: 254 complete entries. Python syntax check also passed. Ordinary builds use checked-in notice bodies offline. |
+| `pnpm exec playwright test --project=chromium --project=webkit` | **111 passed, 1 expected skip, 0 failures (1.7m)**. The skip is WebKit forced-colors emulation; Chromium's control/state/focus probe passed. Both projects rendered all 11 actual manager Docs pages. |
+| Single Firefox Docs test | Failed before application launch: `Could not find profile folder`. This is an installed-browser environment block, not a passing Firefox application result. Firefox stays configured in CI; no remote CI pass is claimed. |
+| `git diff --check` | Passed. |
+
+Browser coverage includes default/compact/light/dark, 320px localized open overlays, keyboard/modal traps and trigger restoration, disabled/mixed/radio/menu/submenu states, real submitted values, invalid/loading/error/retry forms and toast loading/action/keyboard behavior. Axe runs use WCAG 2/2.1/2.2 A/AA tags on whole documents including opened overlays, with full violations/incomplete attachments. No rule is suppressed or threshold reduced. The addon is set to manual in external-axe test URLs to avoid concurrent axe instances; the external scan still runs normally. Finite theme/open animations settle before scans. Incomplete findings are preserved for manual review.
+
+## Reproductions and repairs
+
+Chromium forced-colors emulation reproduced an invisible Switch: both track and thumb became Canvas white. Shared CSS now uses system-color boundaries/track/thumb states and retains visible focus; no numeric token or normal-theme palette change was made.
+
+Radix-managed hidden Select/menu background branches remained programmatically focusable and produced whole-document `aria-hidden-focus` findings. The internal helper follows Radix's `data-aria-hidden` ownership, adds inert, and restores each element's original inert state. A document-owned symbol registry coordinates bundled/deep/multiple module instances. Default modal, nonmodal, nested Dialog/Select, forced unmount, callback-ref cleanup, object refs and consumer handlers were checked. This remains the main global-interaction review surface; arbitrary consumer focus/outside overrides and third-party overlay combinations require their own acceptance checks.
+
+Consumer examples corrected 320px/200% root-text wrapping and used percentage-based dialog max-height for the separate 200% CSS-zoom probe. These probes are not native desktop browser zoom. macOS WebKit's default navigation requires Option+Shift+Tab to include buttons; the toast test uses that setting and verifies actual document/trigger focus return. No Sonner component repair was needed.
+
+Earlier local manager loads intermittently failed with `ERR_CONNECTION_RESET`/`ERR_SOCKET_NOT_CONNECTED` from Python's local static server, leaving a spinner/unstyled state. The verification/local-preview route now uses a persistent Node static server. The fresh complete suite passed through it; earlier failed runs are diagnostic history rather than final validation.
+
+## Artifact and image review
+
+The local reproducible preview is `storybook-static/`, served with `pnpm preview:storybook`; CI is configured to upload `storybook-preview` and browser results, but no hosted artifact or remote passing execution is claimed. Local Storybook results/HTML report, Firefox launch log, packed-consumer captures, command logs and a built manager Docs screenshot were retained privately; they are not npm payload or checked-in evidence. This checked-in dated command/source record and its reproducible commands identify the verified scope.
+
+Actually opened and visually inspected final captures: Chromium light 2560px/default workspace; WebKit dark 2560px/default workspace; WebKit light and Chromium dark 390px/compact workspace; WebKit light and Chromium dark mobile open dialogs; Chromium forced-colors Switch; packed React light/dark/font-fallback pages; and the actual built Button manager Docs page. The inspected captures show bounded content, wrapped multilingual text, stacked mobile panels, visible overlay recovery/focus and distinguishable forced-color Switch states. Screenshot inspection does not certify every glyph, viewport or screen-reader behavior. Matching engine/theme/mobile captures for the remaining combinations are retained, but are not claimed as separately visually inspected.
+
+Preview notices preserve complete installed/original LICENSE/NOTICE bodies, including Lucide's mixed ISC/Feather MIT text. Source-less use-composed-ref@1.4.0 has exact MIT metadata plus full declared terms, explicitly without an invented copyright holder/year. Four manager vendored modules lack exact embedded versions; their conservative original npm notice sources are identified without an exact-version claim. Next-vendored manifests omit versions and are similarly labeled. These concrete inventory/source limitations remain visible in the notice JSON and [source ledger](https://github.com/naeil-dev/naeil-ui/blob/main/docs/design/frontend-sources.md); this is artifact-level notice preservation, not blanket provenance or legal certification. Unknown website-art rights remain unresolved, with those assets excluded.
+
+## Unrun / blocked acceptance
+
+Screen readers, actual Safari, native desktop 200%/400% zoom, actual Windows high contrast, physical iOS/Android devices, all peer-version combinations, deployed behavior and arbitrary consumer overrides were not tested. Local Firefox application checks are blocked as above. Use the [support matrix and manual acceptance checklist](public-ui-support.md) before a release. The manual-only Pages workflow/recipe is prepared, unexecuted, and still requires future explicit publication authorization and protected-environment setup.
+
+## Original frozen source identity
+
+SHA-256 identifies the scope of the original broad run frozen at `80732074349b35d41e31b674f248171101481742`. These historical hashes remain attached to that run; only the affected files have replacement hashes in the focused follow-up below. Orchestration-plan edits are outside executor ownership.
+
+| File | SHA-256 |
+| --- | --- |
+| `src/lib/design/modal-inert.ts` | `4cb6e1bab2d651d1724c994a2eb03aa2211281c3e2a2f9525a96d31fb152815c` |
+| `src/components/ui/select.tsx` | `27aa623255a7992f044a3882ba71450e75942b2d3062daee7b99476a653ed32e` |
+| `src/components/ui/dropdown-menu.tsx` | `b9f398c3bff1aa4c7fca7eed16ea4e9a10f7e933d0c67015dda0ccaec13fac02` |
+| `src/styles/components.css` | `5bd58b7a6ada0945e9457c9b642dcb4f25283c43d1d341130681b4310c847d1d` |
+| `src/stories/component-examples.tsx` | `5a8c33b840047c91f3669a4d1c30c41d9ff3ac363d3b885b1026bc04041f7dd5` |
+| `e2e/component-usage.spec.ts` | `90204b7035c5cfb04be5931d026b43a56a0ca265329a22ce476f09958502e980` |
+| `playwright.config.ts` | `6621ef61f8b47b90716ae5848cb9fc75458f6176de18a7bce12dd9c5b0a7a28b` |
+| `scripts/serve-storybook.ts` | `190d65a8dae7eec2dedfdf574198ea2d603f92ca4a023bfb50b91da0df5a2370` |
+| `scripts/bundled-notices.ts` | `6f0514cb7c818c8246f9efdbb339c80b22f0501dfe8754337e90f4cc6d484ddf` |
+| `.storybook/manager-notices.json` | `8e13782901d7c31845d313861cb3251dd90e47b38a995be82d67f51daad34f8c` |
+| `scripts/check-consumer-browser.ts` | `09144d0bac7b91a1e0524cbb4f18a475d403008ff79cf8563aa2b46716bdb838` |
+| `examples/react/src/App.tsx` | `865fbabe907ddad39f22724f744de582075f88e1acdb71c6fd39db5901dfa2c1` |
+| `package.json` | `6d327bae94fae383eb37c3c0e9c6f0b8e06d4291b3c77075ed509820ed925665` |
+| `pnpm-lock.yaml` | `807b43593d1362afe9278091a5220dc146ecfb46b210f45fb2a68ddb0f56e65c` |
+| `.storybook/main.ts` | `162591a47e0b2095be02d24ffb4c13e9be33e5c36e455389c992d7f08ae1ea74` |
+
+## Focused P3 Avatar follow-up — 2026-10-02
+
+The named generic AvatarGroup lacked a supported role, and AvatarGroupCount's generic-div `aria-label` did not convey the additional-member count. The consumer-owned Usage example now supplies `role="group"` and keeps the visual `+3` in an `aria-hidden` span with actual `sr-only` text, `3 additional members`. The Avatar guide documents both compositions. No package component runtime, API, style, token or override changed.
+
+The existing Avatar mobile checks now require the exact group accessibility snapshot, including both named fallback images and the additional-member text; they also check the loaded image, failed-image fallback and visual count. Full axe violations/incomplete attachments remain unsuppressed, and Avatar checks additionally reject any `aria-prohibited-attr` incomplete result. The existing actual Docs checks verify that the rebuilt guide includes the correction.
+
+| Focused command / check | Observed result |
+| --- | --- |
+| `pnpm build:storybook` | Passed: 11 built Docs/Usage entries, exact notices/fonts and asset boundary; 74 preview + 254 manager notice entries. |
+| `pnpm exec playwright test e2e/component-usage.spec.ts --grep avatar --project=chromium --project=webkit` | **6/6 passed (5.6s)**: actual manager Avatar Docs in both engines; 320px light/dark compact Usage in both engines, including loaded/failed/missing image content and localized reflow. |
+| Actual snapshot / axe inspection | All four Usage snapshots expose group `Team members`, images `Alex Lee`/`田中 遥`, and text `3 additional members`, with no accessible `+3` duplicate. All four scans have **0 violations** and **no `aria-prohibited-attr` incomplete**. The sole remaining incomplete rule is `bypass` on the standalone story document's `html` (no heading/landmark/skip link); retained for manual review, outside this group/count correction. |
+| Actual visual inspection | Opened rebuilt Avatar manager Docs through Aside REPL; inspected its capture and a Chromium capture of the corrected guide section, plus all four Chromium/WebKit light/dark 320px Usage captures. Circular graphics, overlapping group, visual `+3` and localized wrapping remain intact; accessible count text is visually hidden. |
+| `pnpm check:types`, `pnpm lint`, `pnpm check:contrast` | Passed; lint retains only the pre-existing website unused-`locale` warning; **40/40** semantic contrast pairs pass. |
+| Final `pnpm check:package:boundary` and packed Avatar guide inspection | Passed: the freshly packed consumer-facing guide matches repository bytes and includes the named-group role and actual hidden count text; document links and package boundary pass. |
+| `git diff --check` | Passed. |
+
+Focused command logs, browser HTML report with full attachments, extracted axe/snapshot attachments, four Usage screenshots, actual manager Docs snapshots/captures, packed tarball/content inspection and replacement source hashes were retained privately, separately from the original broad artifacts. This checked-in dated command/source record and the reproducible commands in this record describe that correction. The original **111 passed / 1 expected skip** browser result, unit/package-runtime/clean-consumer results and manual/environment limitations are historical frozen evidence; the full browser suite, package runtime build and clean React/Next consumer browser checks were not rerun for this example/packed-guide-only correction. No new screen-reader, Safari or Firefox pass is claimed.
+
+The following SHA-256 values supersede only these affected files for the focused follow-up. Source is frozen for the independent scoped recheck; the orchestrator owns the orchestration record and any later freeze commit.
+
+| File | Focused follow-up SHA-256 |
+| --- | --- |
+| `src/stories/component-examples.tsx` | `4386e8ca9b7cf58da083258568bb97427bf331c237d52396399202081f1eb04a` |
+| `e2e/component-usage.spec.ts` | `ed9f67d33283e07d3c3698a6035ae21a1598cbccaabc7466c0dfb9eddfb75a99` |
+| `docs/components/avatar.md` | `5be6ff754f98336a6a5ace144ed7d757ec92929eaf38d0af42c686f102041231` |