@naeil/ui 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.3.0 — 2026-10-02
+
+- Demand-led Radix Tabs and native Textarea with exact shared deep entries, standalone guides/Docs/Usage and packed behavior checks. Native field/radio composition remains consumer-owned; no FormField/RadioGroup API or dependency added.
+
+- Shared UI v2: approved neutral light/dark tokens, typography, density, content widths, restrained motion, and Radix Select/Switch/Checkbox. The design generation name “v2” is independent of npm versioning.
+- `/ui` is the React core entry. React and ReactDOM come from the host; Next.js and next-intl are optional compatibility peers. Next themes remains a React runtime dependency.
+- Preserve root brand/theme/heading names and documented shared deep imports. Replace open-ended deep exports with an explicit allowlist and compiled JavaScript/types.
+- Exclude website authentication/Supabase, MDX/blog code, hero/Three/cursor scenes, application wrappers and website messages from the tarball and installed runtime dependencies. See the [migration guide](docs/design/v2-migration.md#03-package-boundary).
+- Include CSS side-effect metadata, migration/design guidance and third-party notices/licenses. Verify isolated tarball consumers and add package/site/Storybook/browser CI.
+- Version-scoped installation and consumer font/theme/density guidance, plus a dispatch-only hosted Docs workflow. Hosted Docs and the brand website have separate deployment scopes; native/manual coverage is recorded separately from automated browser checks.
+
+This entry describes the 0.3.0 release scope; registry availability and tags are verified separately during publication. The historical registry baseline on 2026-10-02 was npm `latest` at `0.2.0`. Changes to the 0.x API boundary use a minor increment; there is no npm 2.0 release implied by UI v2.
+
+## 0.2.0 — published 2026-03-22
+
+Registry baseline: root, `/ui`, `/utils`, theme/global CSS, and declared wildcard component/lib/i18n paths. The actual 15-file tarball did not contain the source targets for its wildcard exports. It installed website dependencies and marked all files side-effect-free. These registry facts are distinct from later repository-only implementation work.

package/DESIGN.md

@@ -0,0 +1,186 @@
+# naeil UI v2 — Design brief
+
+Status: Visual direction accepted on 2026-09-29: neutral palette, Pretendard, larger text, purpose-specific widths, comfortable spacing by default, compact spacing for dense views, and short restrained transitions respecting reduced motion. Implemented in the shared package and actual-component Storybook examples. Independent review findings have been addressed; validation evidence and remaining limits are in [the verification report](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/docs/design/v2-verification.md). See [the v2 specification](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/docs/superpowers/specs/2026-09-29-shared-ui-v2-design.md) for scope. Publishing and deployment are separate.
+
+## Purpose and scope
+
+Build a shared design system that gives naeil products a precise, calm, coherent interface. The deliverables are design rules, tokens, reusable React components, composition examples, and instructions for consumers and coding agents.
+
+The design must work for settings, forms, lists, and information panels across products. naeil.dev page composition, project illustrations, hero scenes, and other site content are outside this brief. Existing brand components in the public package require an explicit migration decision before their API changes.
+
+## Reference and provenance
+
+- Selected by the user: Linear, on 2026-09-29.
+- Source: https://github.com/VoltAgent/awesome-design-md/blob/main/design-md/linear.app/DESIGN.md
+- Workflow reference: https://www.threads.com/@automation_claire/post/Dd1GZoREhnt
+- Follow-up constraints: https://www.threads.com/@automation_claire/post/Dd1GcQGkpbL
+
+The source is a third-party analysis of Linear's marketing pages, not an official specification of Linear's application. Its light theme, form validation, and complete application state palette are not documented. Source values are reference material, not verified accessibility results.
+
+Adopt from the reference:
+
+- Neutral surfaces with a slight cool tint and a consistent hierarchy of surface levels.
+- A restrained accent for important actions, selection, links, and focus.
+- Fine borders and surface differences to establish grouping and depth.
+- Medium and semibold typography with explicit roles.
+- A 4px spacing foundation and role-specific corner radii.
+
+Adapt for naeil:
+
+- Support both light and dark modes; the source's dark-only marketing rule does not apply.
+- Use available fonts with Korean, Japanese, and Latin coverage, rather than Linear's proprietary fonts.
+- Define success, warning, error, information, loading, empty, disabled, and selected states for product workflows.
+- Establish product UI sizes rather than adopting marketing display sizes and section spacing.
+- Keep the accent replaceable through a documented, accessible theme contract.
+
+## Visual direction
+
+Precision comes from consistent alignment, spacing, hierarchy, and interaction states. Group related information through proximity and separators; use a panel when it represents a meaningful group. Give the main task the strongest visual emphasis.
+
+Use restrained rounding and quiet surface treatments. Gradients, glow, backdrop blur, and animated decoration are not default component treatments. Motion should communicate a state change or spatial relationship.
+
+## Selected visual foundation
+
+The neutral palette, larger-text direction, Pretendard, and the reviewed content-width recommendations are selected. The user also accepted the recommended comfortable spacing, demonstrated state direction, and short transitions. Engineering and compatibility decisions are consolidated in the linked specification. These are naeil decisions, not assertions about Linear's product UI.
+
+### Color and surfaces
+
+Define semantic roles before choosing final palette values:
+
+| Role | Purpose |
+| --- | --- |
+| canvas | Application background |
+| surface | Grouped content and panels |
+| surface-raised | Menus, popovers, dialogs |
+| surface-hover | Pointer hover on interactive surfaces |
+| surface-selected | Persistent selection, distinct from hover |
+| text-primary / secondary / disabled | Text hierarchy with explicit use restrictions |
+| border / border-strong | Group boundaries and control boundaries |
+| action / action-hover / action-pressed / on-action | Primary action colors |
+| focus | Keyboard focus indicator |
+| success / warning / error / info | Feedback, each with text and subtle-surface companions |
+
+Use neutral surfaces, neutral selection backgrounds, and a neutral action palette as the shared default. The user selected neutral over blue and teal after comparing the revised study. Purple actions and purple selection backgrounds were rejected. Blue and teal remain comparison history, not required shipped themes. Provide complete light/dark roles and validate actual text and control states before publishing.
+
+Brand/action, muted surface, and focus are separate semantic decisions even when some share a color. A project accent override must include its foreground and interaction states; replacing a single hue must not silently break legibility.
+
+Normal text must meet 4.5:1 contrast, large text 3:1, and essential control boundaries and state indicators 3:1 against adjacent colors. Validate rendered combinations, including opacity. Decorative separators need not be treated as control boundaries. Disabled styles must not be reused for readable metadata.
+
+### Typography
+
+Selected UI family: Pretendard for Korean/Latin UI, with Noto Sans JP used for Japanese in the reviewed samples. JetBrains Mono for code and identifiers is still a proposal; it was not part of the font comparison. Font delivery must be documented for package consumers. Verify all three languages in specimens.
+
+| Role | Size / line height | Weight |
+| --- | --- | --- |
+| Page title | 32 / 42px | 600 |
+| Section title | 20 / 29px | 600 |
+| Component title | 16 / 25px | 600 |
+| UI body | 16 / 25px | 400 |
+| Reading body | 16 / 30px | 400 |
+| Label and control | 16 / 25px | 500 |
+| Supporting text | 14 / 22px | 400 |
+| Metadata | 13 / 20px | 400 |
+
+Do not tighten body letter spacing to imitate a marketing headline. Metadata remains readable. Form labels, errors, and essential information must not shrink to badge-sized text. Preserve mobile input sizing where needed to avoid browser auto-zoom.
+
+### Size, spacing, and shape
+
+- Foundation: 4, 8, 12, 16, 24, 32, 48, 64px; allow named 2px optical adjustments for icons and indicators.
+- Default control height: 40px. Compact control height: 36px, for deliberate dense layouts. Touch interaction areas: at least 44px, without overlapping adjacent targets.
+- Default form/panel padding: 24px; compact form padding: 20px. Use 8px within a field and 24px between field groups, reduced to 16px in compact forms. Explicitly small surfaces may use 16px padding.
+- Small tags: 4px radius. Buttons and inputs: 8px. Panels and dialogs: 12px. Circular avatars remain circular.
+- Layout density must be consistent within a control group; individual consumers should not invent independent padding scales.
+
+### Motion
+
+Use named fast (120ms) and standard (180ms) transitions for color and opacity, with at most a small movement for notifications. Reduced-motion mode removes transitions and spatial movement. Do not add default spring, bounce, magnetic, or decorative motion. Kinetics was inspected as a reference; its effects were not adopted.
+
+## Components and composition
+
+First implement the foundation and existing eight families: Button, Input, Card, Dialog, DropdownMenu, Badge, Avatar, and Toaster. Align shared title primitives and theme controls with the same foundation.
+
+- Button: clear primary/secondary/quiet/destructive hierarchy; specified hover, pressed, focus, disabled, and loading behavior.
+- Input: visible field boundaries, label/help/error composition, and clear focus/invalid states.
+- Card: grouping and surface role, without implying that every content block needs a card. Distinguish static and interactive examples.
+- Dialog and menu: coherent raised surfaces, keyboard interaction, visible focus, and appropriate dismissal behavior.
+- Badge and toast: status meaning conveyed by text or icon as well as color.
+- Avatar: readable fallback initials; imagery supplied by the consumer.
+
+Demonstrate the system in three neutral compositions: a settings form, a selectable list with metadata, and a detail panel with actions. These are library examples, not a redesign of a particular website. Additional public components require a demonstrated composition need.
+
+### Application frame and content widths
+
+The application frame owns navigation placement and outer gutters; each content region owns its purpose-specific width. A narrow settings form inside that frame must not move the shared navigation. For routes using the same frame, keep navigation anchors stable at the same viewport, language and theme, including loading and changing summary counts. A shared Header import alone does not establish this consistency.
+
+Choose a product's frame width from its tasks, information density and representative content. A dashboard name or a wide monitor alone does not justify filling all available space. Inspect sparse as well as dense content before selecting a cap or fluid layout. The shared reading/settings/list defaults remain content rules, not a universal application maximum; RelayDock's 1600px decision is not a shared token.
+
+Internal columns must respond to the space available inside their region. Use container queries or an equivalent content-aware layout when viewport breakpoints no longer represent that space. Keep wide tables locally scrollable; check localized labels, wrapping and controls inside cells as well as page overflow. See the [consumer composition guide](docs/design/v2-migration.md#앱-전체-틀과-콘텐츠-폭) for application ownership and checks.
+
+## Connection to implementation
+
+Use one canonical token source to generate the CSS that the package actually exports and that contrast checks inspect. Wire typography, radii, spacing, elevation, and motion into that same system. The visual design brief explains roles; numeric implementation values must be synchronized with the token source.
+
+Preserve Radix interaction behavior and the existing React/Tailwind integration unless a concrete requirement warrants a change. Inventory current public exports before migration. Existing Nav, Footer, Logo, project colors, and deep import contracts need explicit compatibility decisions; do not silently remove them during a visual pass.
+
+Consumer and repository agent guidance must explicitly point to this design document and the component APIs. External examples may fill an identified gap, and their adopted rules or code must be attributed. No custom skill or plugin is required to deliver v2. Installing a tool is a separate decision from selecting a design reference.
+
+## Evaluation and acceptance
+
+Compare the same compositions and content in light/dark themes, desktop/mobile widths, and Korean/Japanese/English. Include long labels, multiline content, keyboard focus, errors, disabled controls, and loading examples.
+
+Before release, verify generated token consistency, public-package consumption, component behavior and accessibility, and visual results. Review actual screenshots or a working preview; a token table alone does not establish visual quality.
+
+For application layout changes, compare affected routes side by side under the same conditions and verify the frame invariants separately from each page's component checks. Record functional checks, shared-design compliance and visual composition as distinct results. Keep prior findings open until remeasured or explicitly scoped out; a layout review does not close unrelated contrast, nested-control or touch findings.
+
+The visual comparisons and implementation scope are accepted. Token generation, component behavior, packed consumption, and actual browser examples have been implemented and checked; see the verification report for results and limits.
+
+## Historical design studies
+
+The sections below record prototype-stage decisions and checks as they occurred. Their references to pending production work describe that earlier stage; current implementation status is above.
+
+## Accepted direction — typography and content widths
+
+The accepted comparison artifact is `docs/design/v2-typography-width.html`. It retains the selected neutral palette and compares font family and width independently. The original composition study remains in `docs/design/v2-preview.html`. These review screens do not modify the production library.
+
+- Compare Pretendard (current recommendation) and Noto Sans KR with identical Korean/English text, 16px body, 14px supporting text, 20px headings, and matching weights/spacing. Both use explicitly loaded Noto Sans JP for Japanese samples; this is a shared Japanese companion, not a comparison between Japanese font candidates. Monospace font selection is outside this review.
+- Let either font drive the same reading, settings, and task-table examples. Font loading status is visible; a fallback rendering must not be presented as a successful candidate comparison.
+- Compare maximum outer content widths: reading 560/640/800px, settings 480/640/800px, and task lists 960/1,200px/available width. The user accepted 640px for reading and settings, and 1,200px for task lists as design defaults. These still need to be implemented as tokens. Short forms may use 480px; data-heavy layouts may need available width.
+- Maximum widths shrink to available space on small screens. The comparison stage and its padding are review-page scaffolding, not a proposed universal application shell. A wide table scrolls inside its region on mobile, while reading and forms reflow.
+
+Sources: [Pretendard](https://github.com/orioncactus/pretendard), [Noto Sans KR](https://fonts.google.com/noto/specimen/Noto+Sans+KR), and [Noto Sans JP](https://fonts.google.com/noto/specimen/Noto+Sans+JP). The prototype loads fonts through jsDelivr and Google Fonts; production delivery remains to be decided.
+
+Browser checks at 1440px confirmed candidate font loads and all nine width choices. At 390px the three layouts fit without page-level horizontal overflow, the table retains internal scrolling, and form inputs retain 16px text. These checks support the visual review and do not replace production accessibility or cross-browser testing. Subsequent spacing/state/motion recommendations have also been accepted; production coverage and verification remain outstanding.
+
+## Accepted direction — spacing, states, and motion
+
+`docs/design/v2-spacing-states.html` reuses the interactive neutral composition, with an independent settings example capped at 640px and a list/detail example capped at 1,200px. It preserves 16px main text and compares comfortable/compact spacing (40/36px controls, minimum 72/60px list rows). Mobile targets keep their larger sizes.
+
+Review controls expose normal, loading, empty, and recoverable error list states. The existing email validation/recovery, simulated save, selected task, disabled action, language combobox, dialog, and toast remain available. Scenario data is simulated and resets on reload.
+
+The user accepted the motion recommendation: short color transitions (120ms), menu entrance opacity (120ms), and dialog/toast transitions (180ms), alongside an explicit no-motion option. OS reduced-motion settings take priority. These are our selected rules, not adaptations from Kinetics or output from Impeccable. A subsequent reference review confirmed the Select gap and retained Radix as the implementation basis; see the specification for sources. Production component coverage, accessibility checks, and polish remain outstanding.
+
+Browser verification confirmed the 640/1,200px example widths, all four list scenarios, error retry, task creation from the empty-state action, invalid email and recovery, and simulated save completion. Density retained 16px task titles; the compact two-line rows grew above their 60px minimum to fit their content. Motion-off disabled the dialog animation. At 390px there was no page overflow and inputs remained 44px high. OS reduced-motion behavior is specified in CSS but was not separately emulated in this browser check.
+
+## Composition study — selected neutral direction
+
+The standalone review artifact is `docs/design/v2-preview.html`. It is a disposable HTML/CSS/JavaScript prototype; the package implementation is unchanged. Open it directly or serve it locally. The specimen uses CDN-hosted Pretendard with system fallbacks. Form saves and tasks are simulated in memory and reset on reload.
+
+The user requested larger typography, alternatives to the purple action and selected surfaces, and a coherent language dropdown. The current study uses 16px body/control/label text, 14px supporting text, and 13px metadata. Default/compact controls are 40/36px and task rows 72/60px; mobile controls remain at least 44px. Density changes spacing, not font size.
+
+The current preview uses the selected neutral palette and retains light/dark and density controls. Palette comparison controls have been removed. Selected surfaces are #262626 in dark mode and #ebebeb in light mode. Selected-list indicators use the accent-text role for contrast against the selected surface. The comparison values below are retained as decision history.
+
+| Palette | Dark action / foreground | Light action / foreground | Action text contrast, dark / light |
+| --- | --- | --- | --- |
+| Neutral (selected default) | #e5e5e5 / #171717 | #292929 / #ffffff | 14.23 / 14.55 |
+| Blue (comparison only) | #3269ce / #ffffff | #245ec7 / #ffffff | 5.19 / 6.00 |
+| Teal (comparison only) | #16756b / #ffffff | #116e64 / #ffffff | 5.54 / 6.11 |
+
+The neutral default includes hover, focus, and accent-text roles; the earlier comparisons also supplied these roles. These measured button text pairs are not a complete accessibility certification. Semantic success/warning/error colors remain distinct from the replaceable action palette.
+
+The language control now demonstrates a styled select-only combobox and opaque listbox in the browser's popover top layer. The menu matches the trigger width, marks the selected option, and opens above when space below is insufficient. It supports arrows, Home/End, Enter/Space, Escape, Tab dismissal, and text lookup. Selection updates a hidden form value; it does not translate the page. This is a visual/interaction probe: production implementation should use the established accessible primitives and undergo assistive-technology testing.
+
+The prototype also demonstrates a settings form, searchable task list, detail panel, new-task dialog, toast, status badges, disabled controls, and invalid/recovered input. The revised dark desktop and light mobile layouts, menu visibility, and primary button text contrast were inspected in a browser. Broader component, language, and accessibility verification belongs to implementation.
+
+### Previous study
+
+Study 01 proposed purple actions (#6863dc dark / #6057cf light), purple selected surfaces, 14px controls and 12px metadata, and a native language select. Those choices have been superseded by study 02 in response to user feedback. Linear remains the structural reference; its brand color is not prescribed.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 naeil-dev contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,36 +1,99 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# @naeil/ui
 
-## Getting Started
+React components, semantic design tokens, and shared styles for naeil products. The approved system uses a neutral light/dark palette, Pretendard, 16px controls, comfortable or compact density, purpose-specific content widths, and restrained motion. Radix supplies interaction behavior.
 
-First, run the development server:
+This repository also contains the **naeil.dev brand/example website** and an **optional agent reference workflow**. Choose the path you need:
 
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+| Path | Start here | Tools / keys |
+| --- | --- | --- |
+| Use the UI in an app | [Consumer guide](docs/design/v2-migration.md) | React 19, Tailwind 4; **no Next.js or API keys** for `/ui` |
+| Develop the shared UI | Commands below and [contributing](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/CONTRIBUTING.md) | Node.js 22+, pnpm; no Supabase or 21st key |
+| Use frontend references with an agent | [Optional workflow setup](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/docs/design/frontend-tooling.md) | Supported agent; Python for bundled helpers; your own 21st key only for optional MCP |
+| Develop the brand/example website | [Site setup](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/docs/site-development.md) | Next.js and a separate Supabase project for site authentication |
+
+## Use the UI
+
+This guide targets **@naeil/ui 0.3.0** with React 19 / ReactDOM 19 and Tailwind 4. UI v2 names the design generation, independently of npm versioning. Install the exact version in your app:
+
+```sh
+pnpm add --save-exact @naeil/ui@0.3.0
+# npm install --save-exact @naeil/ui@0.3.0
+```
+
+The command requires that version to be available in your registry. For source checkout validation before publication, use the local package workflow below. The [changelog](CHANGELOG.md) describes this version's changes; this guide does not assert the registry's current `latest` tag.
+
+Import primitives from the dedicated entrypoint:
+
+```tsx
+import { Input } from '@naeil/ui/ui';
+
+export function NameField() {
+  return <label>Name <Input name="name" /></label>;
+}
+```
+
+In a Tailwind 4 app, load the styles once and register the package's classes (adjust the source path relative to your CSS file):
+
+```css
+@import "@naeil/ui/globals.css";
+@source "../node_modules/@naeil/ui/dist";
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+If your app already owns its Tailwind/base styles, import both `@naeil/ui/theme.css` and `@naeil/ui/components.css` instead of globals, and keep the same `@source` registration.
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+Fonts are consumer-owned. One locally bundled option is:
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+```sh
+pnpm add --save-exact pretendard@1.3.9 @fontsource/noto-sans-jp@5.3.0
+```
 
-## Learn More
+```tsx
+// In the app entrypoint; choose the faces your content needs.
+import 'pretendard/dist/web/static/pretendard.css';
+import '@fontsource/noto-sans-jp/400.css';
+import '@fontsource/noto-sans-jp/500.css';
+import '@fontsource/noto-sans-jp/600.css';
+```
+
+Mark Japanese content with `lang="ja"`. Keep font OFL notices with redistributed builds; shared CSS uses system fallbacks when fonts fail. The package adds no font runtime dependency.
+
+Shared CSS follows the OS theme unless the document root has `class="light"` or `class="dark"`. For compact spacing, set `data-ui-density="compact"` on that root; omit it for comfortable spacing. Density changes spacing while retaining 16px control text and minimum mobile touch sizes. React apps can also use `ThemeProvider` from `@naeil/ui/components/theme-provider` with `attribute="class"`.
+
+The [13 component guides](docs/components/README.md) cover exact APIs, state composition and accessibility responsibilities. Each has a built Storybook Docs page and runnable Usage example. The [consumer guide](docs/design/v2-migration.md) covers peer dependencies, fonts, themes, density, Select versus DropdownMenu, overrides, and layout ownership. Fonts are delivered by the consumer; shared CSS does not fetch them automatically. `/ui` and `/utils` work without Next.js. The legacy root remains a framework compatibility entry with static Next/next-intl imports; install those optional peers when using it, Nav, Footer or i18n/routing. ThemeProvider/controls and Toaster retain the React library next-themes. Shared deep imports use the exact [allowlist and migration](docs/design/v2-migration.md#03-package-boundary); website-only paths belong in your application.
+
+## Develop the shared UI
+
+From the repository root:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm storybook
+# http://localhost:6006 — UI v2 / Workspace
+```
+
+Storybook uses the actual public components with simulated example data. It needs no Supabase project or external design API. For local package consumption:
+
+```sh
+pnpm build:pkg
+pnpm pack --pack-destination /tmp
+# In your consumer app: pnpm add /tmp/naeil-ui-0.3.0.tgz
+```
 
-To learn more about Next.js, take a look at the following resources:
+| Command | Purpose |
+| --- | --- |
+| `pnpm build:tokens` | Generate theme CSS from `src/tokens/*.json` |
+| `pnpm check:contrast` | Check declared light/dark color combinations |
+| `pnpm test` / `pnpm check:types` / `pnpm lint` | Unit tests / types / lint |
+| `pnpm build:storybook` / `pnpm test:browser` | Build Docs/examples / Chromium, Firefox and WebKit checks (install configured Playwright engines first) |
+| `pnpm build:pkg` / `pnpm check:package` | Build package / inspect package boundary and independently install/build packed React + Next consumers |
+| `pnpm dev` / `pnpm build` | Brand/example website development / build |
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+A [reusable React consumer example](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/examples/react/README.md) shows a settings form. [Release policy](docs/package-release.md) and [changelog](CHANGELOG.md) distinguish implementation, publication and deployment. CI verifies the package and separate website/Storybook. Downloadable preview artifacts include notices and local fonts. The hosted Docs destination is [naeil-dev.github.io/naeil-ui](https://naeil-dev.github.io/naeil-ui/), configured for workflow builds and main-only deployment. See [Docs deployment status](https://github.com/naeil-dev/naeil-ui/actions/workflows/publish-docs-manual.yml); live availability is confirmed separately in [release evidence](https://github.com/naeil-dev/naeil-ui/releases) with deployment and hosted HTTP/navigation results. See [preview instructions](docs/package-release.md#storybook-preview-artifact) and [support limits](docs/design/public-ui-support.md).
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+Read [DESIGN.md](DESIGN.md) before shared UI changes. Numeric values live in `src/tokens/`; generated CSS is not edited by hand. Shared styles live in `src/styles/`, site-only styles in `src/app/`. Hero art, 3D scenes, cursor effects, and site content belong to the example website.
 
-## Deploy on Vercel
+[Documentation index](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/docs/README.md) separates maintained guides from dated implementation/review evidence. Historical checks describe their recorded revision and scope; publishing, merging, and site deployment are separate actions.
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+## Project and license
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+Maintained in [naeil-dev/naeil-ui](https://github.com/naeil-dev/naeil-ui). See [contributing](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/CONTRIBUTING.md), [security reporting](https://github.com/naeil-dev/naeil-ui/blob/81fd395031dc5b20074c4d915a8585360ce2d28a/SECURITY.md), [MIT license](LICENSE), and [third-party notices](THIRD_PARTY_NOTICES.md). Third-party code, fonts, and brand assets have their own attribution and scope limits.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,49 @@
+# Third-party notices and provenance
+
+Original repository software is MIT licensed. Upstream code and fonts retain their notices. Brand names/logos and assets with unknown provenance are not relicensed by the repository's MIT notice.
+
+## Copied/adapted component code
+
+Setup commit `8e614421eee6a1a3c6b148fe12d5af2b8446abab` explicitly records shadcn/ui and its Button. Commit `2965e3b976002056a1181305ea7b93543cf64f51` adds the eight-family customization (Avatar, Badge, Button, Card, Dialog, DropdownMenu, Input, Sonner). Current `src/components/ui/` files are customized descendants and newer Radix wrappers. No exact upstream registry revision was recorded; this notice does not invent one. Preserve the following shadcn notice when distributing adapted components.
+
+Original license read 2026-10-02: https://github.com/shadcn-ui/ui/blob/main/LICENSE.md. It matches the installed shadcn package notice.
+
+```text
+MIT License
+
+Copyright (c) 2023 shadcn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## Fonts
+
+Shared package styles declare families; consumers own font delivery. The website imports Pretendard Variable from `pretendard`; Storybook imports Pretendard static CSS and `@fontsource/noto-sans-jp` 400/500/600. Both installed packages carry SIL Open Font License 1.1. Exact installed notices are preserved in [Pretendard](licenses/Pretendard-OFL.txt) and [Noto Sans JP](licenses/Noto-Sans-JP-OFL.txt). Keep the notice/license when redistributing font files; modified fonts must follow reserved-name rules.
+
+Storybook 10.4.6 also bundles Nunito Sans for its manager interface. The original Google Fonts OFL body was read on 2026-10-02 and is preserved in [Nunito Sans](licenses/Nunito-Sans-OFL.txt), including the original project-author notice; documentation preview output carries this notice as well. This manager font is Storybook tooling, not a new shared UI font choice.
+
+The site's `src/app/layout.tsx` separately requests JetBrains Mono via `next/font/google`; no copied font binary is tracked here. Before redistributing fetched site-build fonts, retain the original license/notice supplied with that font (https://github.com/JetBrains/JetBrainsMono). This audit did not inspect the fetched Google font binary/license and does not certify a deployed site's font-notice bundle. Prototype HTML uses external CDNs separately from packed UI styles.
+
+## Dependencies and references
+
+Radix, Sonner, Lucide, React, Next.js and other npm dependencies carry licenses in their own distributions. They are not newly attributed as copied sources here; preserve their notices if bundling their code. DESIGN.md's Linear analysis is design reference material, not an official Linear specification or a component license. The optional workflow grants no blanket license to 21st catalog code; inspect each retrieved original before adoption.
+
+## Website-only assets: unresolved provenance
+
+`public/images/`, `public/svg/`, and `public/coral-concepts.html` contain brand/hero art. History records additions and normalization (`8252a3e`, `9a15ff0`, `e57c21c`) but does not establish each original artist, generation service, source license or redistribution permission. No such provenance is invented here. `public/next.svg`, `public/vercel.svg` and other starter SVGs entered during Next.js setup; logos remain the respective owners' marks. These assets are outside shared UI requirements and the current npm file allowlist. Establish their rights or replace them before a separate public asset/site redistribution claim. This unresolved site-art audit is not package release approval.

package/dist/chunk-JBTDRVZ7.js

@@ -0,0 +1,46 @@
+"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;
+};
+
+// src/lib/utils.ts
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}
+
+export {
+  __spreadValues,
+  __spreadProps,
+  __objRest,
+  cn
+};