@naeil/ui 0.2.0 → 0.4.0

package/dist/tokens.ts

@@ -0,0 +1,217 @@
+/**
+ * Auto-generated by build-tokens.ts — DO NOT EDIT
+ */
+
+export const color = {
+  gray: {
+    "50": "oklch(0.985 0 0)",
+    "100": "oklch(0.970 0 0)",
+    "200": "oklch(0.922 0 0)",
+    "300": "oklch(0.870 0 0)",
+    "400": "oklch(0.708 0 0)",
+    "500": "oklch(0.556 0 0)",
+    "600": "oklch(0.439 0 0)",
+    "700": "oklch(0.371 0 0)",
+    "800": "oklch(0.269 0 0)",
+    "900": "oklch(0.205 0 0)",
+    "950": "oklch(0.145 0 0)",
+  },
+  accent: {
+    "50": "oklch(0.970 0.014 254)",
+    "100": "oklch(0.932 0.032 255)",
+    "200": "oklch(0.882 0.059 254)",
+    "300": "oklch(0.809 0.105 254)",
+    "400": "oklch(0.707 0.165 254)",
+    "500": "oklch(0.623 0.214 259)",
+    "600": "oklch(0.546 0.245 263)",
+    "700": "oklch(0.488 0.243 264.376)",
+    "800": "oklch(0.424 0.199 265)",
+    "900": "oklch(0.379 0.146 265)",
+    "950": "oklch(0.282 0.091 267)",
+  },
+  destructive: {
+    "50": "oklch(0.971 0.013 17)",
+    "100": "oklch(0.936 0.032 17)",
+    "200": "oklch(0.885 0.062 18)",
+    "300": "oklch(0.808 0.114 19)",
+    "400": "oklch(0.704 0.191 22.216)",
+    "500": "oklch(0.637 0.237 25)",
+    "600": "oklch(0.577 0.245 27.325)",
+    "700": "oklch(0.505 0.213 27)",
+    "800": "oklch(0.444 0.177 26)",
+    "900": "oklch(0.396 0.141 25)",
+    "950": "oklch(0.258 0.092 26)",
+  },
+  project: {
+    cc: "oklch(0.704 0.140 181)",
+    sa: "oklch(0.723 0.219 149)",
+    pkm: "oklch(0.627 0.265 303)",
+    naeilUi: "oklch(0.623 0.214 259)",
+    baby: "oklch(0.769 0.188 70.08)",
+  },
+  white: "oklch(1 0 0)",
+  black: "oklch(0 0 0)",
+} as const;
+
+export const font = {
+  family: {
+    sans: ["Pretendard Variable","Pretendard","Noto Sans JP","-apple-system","system-ui","sans-serif"],
+    mono: ["JetBrains Mono","Geist Mono","ui-monospace","monospace"],
+  },
+  size: {
+    "xs": "0.8125rem",
+    "sm": "0.875rem",
+    "base": "1rem",
+    "lg": "1.125rem",
+    "xl": "1.25rem",
+    "2xl": "1.5rem",
+    "3xl": "2rem",
+    "4xl": "2.25rem",
+  },
+  weight: {
+    normal: 400,
+    medium: 500,
+    bold: 700,
+    semibold: 600,
+  },
+  lineHeight: {
+    tight: 1.25,
+    normal: 1.5625,
+    relaxed: 1.875,
+  },
+} as const;
+
+export const spacing = {
+  "0": "0px",
+  "1": "4px",
+  "2": "8px",
+  "3": "12px",
+  "4": "16px",
+  "5": "20px",
+  "6": "24px",
+  "8": "32px",
+  "10": "40px",
+  "12": "48px",
+  "16": "64px",
+} as const;
+
+export const radius = {
+  none: "0px",
+  sm: "4px",
+  md: "8px",
+  lg: "12px",
+} as const;
+
+export const shadow = {
+  sm: "0 1px 2px 0 oklch(0 0 0 / 0.05)",
+  md: "0 4px 6px -1px oklch(0 0 0 / 0.1), 0 2px 4px -2px oklch(0 0 0 / 0.1)",
+} as const;
+
+export const semantic = {
+  light: {
+    "background": "#f7f8fa",
+    "foreground": "#202127",
+    "card": "#ffffff",
+    "card-foreground": "#202127",
+    "popover": "#ffffff",
+    "popover-foreground": "#202127",
+    "primary": "#292929",
+    "primary-foreground": "#ffffff",
+    "secondary": "#ebebeb",
+    "secondary-foreground": "#202127",
+    "muted": "#f0f1f5",
+    "muted-foreground": "#5f626e",
+    "accent": "#ebebeb",
+    "accent-foreground": "#202127",
+    "destructive": "#b73a45",
+    "destructive-foreground": "#ffffff",
+    "border": "#e2e3e9",
+    "border-subtle": "#e2e3e9",
+    "border-subtle-hover": "#8c8f9b",
+    "surface-subtle": "#f0f1f5",
+    "input": "#8c8f9b",
+    "ring": "#616161",
+    "chart-1": "oklch(0.646 0.222 41.116)",
+    "chart-2": "oklch(0.6 0.118 184.704)",
+    "chart-3": "oklch(0.398 0.07 227.392)",
+    "chart-4": "oklch(0.828 0.189 84.429)",
+    "chart-5": "oklch(0.769 0.188 70.08)",
+    "sidebar": "#ffffff",
+    "sidebar-foreground": "#202127",
+    "sidebar-primary": "#292929",
+    "sidebar-primary-foreground": "#ffffff",
+    "sidebar-accent": "#ebebeb",
+    "sidebar-accent-foreground": "#202127",
+    "sidebar-border": "#e2e3e9",
+    "sidebar-ring": "#616161",
+    "card-elevated": "#ffffff",
+    "primary-hover": "#414141",
+    "surface-selected": "#ebebeb",
+    "border-strong": "#8c8f9b",
+    "error": "#b73a45",
+    "error-bg": "#fff0f1",
+    "success": "#246a49",
+    "success-bg": "#e9f5ee",
+    "warning": "#865d17",
+    "warning-bg": "#fff3da",
+    "info": "#245ec7",
+    "info-bg": "#edf3ff",
+  },
+  dark: {
+    "background": "#0b0c0e",
+    "foreground": "#eff0f3",
+    "card": "#111215",
+    "card-foreground": "#eff0f3",
+    "popover": "#191a1f",
+    "popover-foreground": "#eff0f3",
+    "primary": "#e5e5e5",
+    "primary-foreground": "#171717",
+    "secondary": "#262626",
+    "secondary-foreground": "#eff0f3",
+    "muted": "#202127",
+    "muted-foreground": "#a4a6b0",
+    "accent": "#262626",
+    "accent-foreground": "#eff0f3",
+    "destructive": "#b73a45",
+    "destructive-foreground": "#ffffff",
+    "border": "#292b33",
+    "border-subtle": "#292b33",
+    "border-subtle-hover": "#646773",
+    "surface-subtle": "#202127",
+    "input": "#646773",
+    "ring": "#b5b5b5",
+    "chart-1": "oklch(0.488 0.243 264.376)",
+    "chart-2": "oklch(0.696 0.17 162.48)",
+    "chart-3": "oklch(0.769 0.188 70.08)",
+    "chart-4": "oklch(0.627 0.265 303.9)",
+    "chart-5": "oklch(0.645 0.246 16.439)",
+    "sidebar": "#111215",
+    "sidebar-foreground": "#eff0f3",
+    "sidebar-primary": "#e5e5e5",
+    "sidebar-primary-foreground": "#171717",
+    "sidebar-accent": "#262626",
+    "sidebar-accent-foreground": "#eff0f3",
+    "sidebar-border": "#292b33",
+    "sidebar-ring": "#b5b5b5",
+    "card-elevated": "#191a1f",
+    "primary-hover": "#cccccc",
+    "surface-selected": "#262626",
+    "border-strong": "#646773",
+    "error": "#f0a0a0",
+    "error-bg": "#342021",
+    "success": "#87c9a6",
+    "success-bg": "#182b23",
+    "warning": "#e4bf78",
+    "warning-bg": "#302819",
+    "info": "#a2c2ff",
+    "info-bg": "#18263f",
+  },
+} as const;
+
+export type ColorScale = keyof typeof color.gray;
+export type AccentScale = keyof typeof color.accent;
+export type SemanticToken = keyof typeof semantic.dark;
+export type SpacingToken = keyof typeof spacing;
+export type RadiusToken = keyof typeof radius;
+export type FontSize = keyof typeof font.size;
+export type FontWeight = keyof typeof font.weight;

package/docs/components/README.md

@@ -0,0 +1,21 @@
+# Component usage guides
+
+Published `@naeil/ui@0.3.0` (2026-10-03; [release](https://github.com/naeil-dev/naeil-ui/releases/tag/v0.3.0)). [Setup, themes, fonts and shared responsibilities](common.md). Open the [live Storybook](https://naeil-dev.github.io/naeil-ui/) or run `pnpm storybook` and choose each family’s Docs or Usage entry. Select chooses a value; DropdownMenu chooses an action.
+
+| Family | Guide | Runnable story |
+| --- | --- | --- |
+| Button | [Button](./button.md) | UI / Button / Usage |
+| Input | [Input](./input.md) | UI / Input / Usage |
+| Card | [Card](./card.md) | UI / Card / Usage |
+| Dialog | [Dialog](./dialog.md) | UI / Dialog / Usage |
+| DropdownMenu | [DropdownMenu](./dropdown-menu.md) | UI / DropdownMenu / Usage |
+| Badge | [Badge](./badge.md) | UI / Badge / Usage |
+| Avatar | [Avatar](./avatar.md) | UI / Avatar / Usage |
+| Toaster | [Toaster](./sonner.md) | UI / Toaster / Usage |
+| Select | [Select](./select.md) | UI / Select / Usage |
+| Switch | [Switch](./switch.md) | UI / Switch / Usage |
+| Checkbox | [Checkbox](./checkbox.md) | UI / Checkbox / Usage |
+| Tabs | [Tabs](./tabs.md) | UI / Tabs / Usage |
+| Textarea | [Textarea](./textarea.md) | UI / Textarea / Usage |
+
+[Field, native radio, Select and action composition](./composition.md) explains consumer state and semantic choices. [Demand decision](../design/component-demand.md) records why these two families were added.

package/docs/components/avatar.md

@@ -0,0 +1,47 @@
+# Avatar
+
+Use Avatar for a person/team identity image with a fallback. Prefer plain names when imagery adds no value; put actions on a named Button/link rather than on the Avatar span.
+
+## API and wrapper defaults
+
+Exports: `Avatar`, `AvatarImage`, `AvatarFallback`, `AvatarBadge`, `AvatarGroup`, `AvatarGroupCount`.
+
+Avatar forwards Radix Root span props and defaults **size="default"**; sizes `sm`/`default`/`lg` render 24/32/40px graphics. Image forwards native image props and `onLoadingStatusChange`. Fallback accepts `delayMs`; wrapper sets no delay default. Badge is a span; Group/GroupCount are divs. These have styling, not automatic presence, count, tooltip or click logic.
+
+Inherited [Avatar 1.1.10 declaration](https://unpkg.com/@radix-ui/react-avatar@1.1.10/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/avatar.tsx) is the API authority.
+
+## Composition
+
+```tsx
+<div className="flex items-center gap-3">
+  <Avatar><AvatarImage src={person.photo} alt="" />
+    <AvatarFallback aria-hidden="true">AL</AvatarFallback></Avatar>
+  <span>{person.name}</span>
+</div>
+```
+
+Import the named components from `@naeil/ui/ui`. Variables/handlers in snippets are consumer-owned. Run **UI / Avatar / Usage** in Storybook for a complete interactive example; its Docs page renders this same guide.
+
+## Keyboard, focus and accessible content
+
+Use alt="" and hide redundant initials when an adjacent name conveys the identity; otherwise provide meaningful alt and a labeled fallback (e.g. role="img" aria-label="Alex Lee"). Avatar itself is not a button/tab stop. Presence markers/counts need visible or accessible text; color alone is insufficient.
+
+For a named group, supply `role="group"` with `aria-label` on AvatarGroup. AvatarGroupCount is a generic div: convey the count with actual text rather than `aria-label`. For example, hide the visual shorthand and provide the full meaning as screen-reader text:
+
+```tsx
+<AvatarGroup role="group" aria-label="Team members">
+  {/* Consumer-owned member avatars */}
+  <AvatarGroupCount>
+    <span aria-hidden="true">+3</span>
+    <span className="sr-only">3 additional members</span>
+  </AvatarGroupCount>
+</AvatarGroup>
+```
+
+## States, resilience and mistakes
+
+Loading or failed image falls back; demonstrate missing/error/loaded images. Empty identity needs a consumer placeholder, not fabricated initials. Disabled does not apply to the graphic. GroupCount is supplied by consumers and does not compute hidden members. Long Korean/English/Japanese names belong beside the fixed graphic and wrap; keep meaningful counts accessible and do not turn tiny avatar imagery into an undersized target.
+
+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/badge.md

@@ -0,0 +1,29 @@
+# Badge
+
+Use Badge for concise status/category text. Prefer readable body/helper text for essential instructions, Button for actions, and a real link for navigation.
+
+## API and wrapper defaults
+
+Exports: `Badge`, `badgeVariants`. Native span props plus `variant` and `asChild`. Defaults: **variant="default", asChild=false**. Variants: `default`, `secondary`, `outline`, `destructive`, `success`, `warning`, `error`, `info`. asChild uses Slot.Root; no disabled/loading or announcement API. Default text is intentionally small and single-line.
+
+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/badge.tsx) is the API authority.
+
+## Composition
+
+```tsx
+<Badge variant="success">Complete</Badge>
+<Badge variant="error">Save failed</Badge>
+<Badge asChild variant="outline"><a href="/activity">Activity</a></Badge>
+```
+
+Import the named components from `@naeil/ui/ui`. Variables/handlers in snippets are consumer-owned. Run **UI / Badge / Usage** in Storybook for a complete interactive example; its Docs page renders this same guide.
+
+## Keyboard, focus and accessible content
+
+Static badges are not focusable. Name status by text, not only color/icon. Dynamic important status needs an appropriate surrounding status/alert region; Badge alone does not announce changes. asChild links use native keyboard behavior; an icon-only badge needs an accessible text equivalent.
+
+## States, resilience and mistakes
+
+Pending/empty/error are literal status content; disabled is inapplicable to a static badge. Avoid essential long text in tiny tags; use a paragraph instead, or deliberate `whitespace-normal break-words max-w-full` overrides and review. Do not infer interactivity from hover or pass disabled to a span/link.
+
+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/button.md

@@ -0,0 +1,39 @@
+# Button
+
+Use Button for an action, a native anchor for navigation, and Select for a value. Prefer one clear primary action per task.
+
+## API and wrapper defaults
+
+Exports: `Button`, `buttonVariants`.
+
+| Prop | Contract / wrapper default |
+| --- | --- |
+| `variant` | `default` (default), `destructive`, `outline`, `secondary`, `ghost`, `link` |
+| `size` | `default` (default), `xs`, `sm`, `lg`, `icon`, `icon-xs`, `icon-sm`, `icon-lg` |
+| `asChild` | `false`; Slot.Root composes one supplied element |
+| Native props | `type`, `disabled`, `onClick`, `name`, `value`, form and ARIA props; no wrapper `type` default |
+
+`size` names are preserved; shared CSS controls actual height (40/36px; lg adds 4px; mobile minimum 44px). `xs` does not imply an extra-small touch target. `loading` is not an 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/button.tsx) is the API authority.
+
+## Composition
+
+```tsx
+<Button type="button" disabled={saving} aria-busy={saving}
+  onClick={save}>{saving ? 'Saving…' : 'Save settings'}</Button>
+<p role="status">{result}</p>
+<Button asChild variant="link"><a href="/settings">Settings</a></Button>
+```
+
+Import the named components from `@naeil/ui/ui`. Variables/handlers in snippets are consumer-owned. Run **UI / Button / Usage** in Storybook for a complete interactive example; its Docs page renders this same guide.
+
+## Keyboard, focus and accessible content
+
+Native buttons activate with Enter/Space and show focus-visible; disabled buttons leave the tab sequence. Name icon buttons with aria-label. Keep loading text meaningful and announce completion/error near the form; restore enabled state after failure. A button without type inside a form submits by browser default.
+
+## States, resilience and mistakes
+
+Demonstrate normal, disabled, saving and recovery; no-data/error belong to the operation. Do not nest Button in a link or treat variant="link" as navigation. With asChild anchors, own href/activation/disabled policy. For long translated actions use `className="h-auto min-h-11 whitespace-normal py-2"` and check both densities.
+
+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/card.md

@@ -0,0 +1,32 @@
+# Card
+
+Use Card to group related information or a form. Use plain sections/headings for content that needs no surface, Dialog for a modal task. CardElevated expresses an elevated surface; neither is an interactive control.
+
+## API and wrapper defaults
+
+Exports: `Card`, `CardElevated`, `CardHeader`, `CardFooter`, `CardTitle`, `CardAction`, `CardDescription`, `CardContent`. All accept `React.ComponentProps<"div">`; no variant/size/asChild/loading API. Card and CardElevated use `data-slot="card"`, default panel spacing and consumer className; CardElevated adds shadow/elevated dark surface. CardTitle is a **div**, not a semantic heading. CardAction occupies the second header column.
+
+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/card.tsx) is the API authority.
+
+## Composition
+
+```tsx
+<Card>
+  <CardHeader><CardTitle><h2>Profile</h2></CardTitle>
+    <CardDescription>Public account details.</CardDescription></CardHeader>
+  <CardContent><p>No profile description yet.</p></CardContent>
+  <CardFooter><Button type="button">Edit profile</Button></CardFooter>
+</Card>
+```
+
+Import the named components from `@naeil/ui/ui`. Variables/handlers in snippets are consumer-owned. Run **UI / Card / Usage** in Storybook for a complete interactive example; its Docs page renders this same guide.
+
+## Keyboard, focus and accessible content
+
+Static cards are not tab stops. Put real buttons/links inside and a semantic heading inside CardTitle. A region label is the consumer’s choice; do not add button role/tabIndex to a card containing other controls.
+
+## States, resilience and mistakes
+
+Loading/empty/error are consumer content with status/retry actions, not Card props; disabled is inapplicable to the static surface. Keep CardAction concise, wrap long localized headings and use `w-full max-w-*` instead of fixed widths. Avoid nested cards and implicit clickable-card behavior; an entire link card must contain no nested controls.
+
+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/checkbox.md

@@ -0,0 +1,35 @@
+# Checkbox
+
+Use Checkbox for independent selections, consent or a mixed group-selection state. Use Switch for an on/off preference and Select for one mutually exclusive value.
+
+## API and wrapper defaults
+
+Export: `Checkbox`. Forwards Radix Root props: `checked`/`defaultChecked`/`onCheckedChange` with **boolean | "indeterminate"**, `disabled`, `required`, `name`, `value`, `form`, `id`, button/ARIA props. Wrapper sets no checked default and renders its own Indicator (check/minus icons); no public Indicator, size or loading API. Graphic is 18×18px with a 44px pseudo-element hit area. The consumer computes mixed state from child selections.
+
+Inherited [Checkbox 1.3.3 declaration](https://unpkg.com/@radix-ui/react-checkbox@1.3.3/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/checkbox.tsx) is the API authority.
+
+## Composition
+
+```tsx
+<label className="ui-choice-label">
+  <Checkbox name="notifications" value="email" />Email notifications
+</label>
+<Checkbox checked={selectedCount === total ? true : selectedCount ? 'indeterminate' : false}
+  onCheckedChange={selectAll} aria-label="Select all items" />
+```
+
+Import the named components from `@naeil/ui/ui`. Variables/handlers in snippets are consumer-owned. Run **UI / Checkbox / Usage** in Storybook for a complete interactive example; its Docs page renders this same guide.
+
+The additional **Required consent** Storybook example demonstrates a consumer-owned required error, focus, pending confirmation and recovery using the same public props.
+
+## Keyboard, focus and accessible content
+
+Tab focuses enabled checkboxes; Space toggles. Mixed state exposes aria-checked="mixed" and a minus glyph; onCheckedChange receives boolean/mixed, so handle it intentionally (checked === true when coercing). Checked values submit; unchecked, indeterminate and disabled values do not represent selected items in FormData. Label consent clearly; use fieldset/legend for a related group.
+
+## States, resilience and mistakes
+
+Demonstrate unchecked/checked/mixed/disabled and required error/recovery. Loading/error/empty are group or operation state, not Checkbox props. Keep descriptive errors visible and connected; do not replace a disabled checkbox with unlabeled decoration. Use 44px label rows/gaps, wrap long Korean/English/Japanese labels, and verify indicators remain visible with forced colors. Do not invent an automatic select-all relationship.
+
+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/common.md

@@ -0,0 +1,31 @@
+# Shared usage contract
+
+These guides describe **@naeil/ui 0.3.0, published 2026-10-03** ([release](https://github.com/naeil-dev/naeil-ui/releases/tag/v0.3.0)); [live Docs and Usage examples](https://naeil-dev.github.io/naeil-ui/) are available. Start with the [consumer setup and migration](../design/v2-migration.md). All listed exports are available from `@naeil/ui/ui`; the legacy root needs the optional Next/next-intl peers. Examples import real wrappers; product state, validation and network requests belong to consumers.
+
+## Styling, themes and overrides
+
+Import `@naeil/ui/globals.css` once and register `@source` for the installed package's `dist` in your Tailwind 4 build. Alternatively load both theme.css and components.css alongside your existing Tailwind setup. Deliver Pretendard and, for Japanese, Noto Sans JP locally through your app's font pipeline; the package does not fetch fonts. Keep font OFL notices with redistributed binaries. The independent React example demonstrates consumer-owned delivery.
+
+Use `.light`/`.dark` on the document root to override OS theme. Root `data-ui-density="compact"` changes spacing, not text size: default controls are 40px, compact 36px, small screens/coarse pointers at least 44px. Portals use document-level styles/density, so a locally themed subtree alone does not theme portaled content. Purpose-specific reading/settings/list widths are 640/640/1200px caps that shrink to available space; the product owns its application frame.
+
+`className` is merged by `cn` (clsx + tailwind-merge). Consumer classes and primitive props remain available. Recheck specificity, text/control/focus contrast, mobile targets and portaled content after overriding. Override semantic color companions together; do not replace only an action hue or remove focus outlines. Reduced-motion rules remove shared transitions/animations. Custom consumer animation still needs its own reduced-motion treatment.
+
+## Semantics and state ownership
+
+Give every input/action a visible accessible name. Connect native labels with IDs, helper/error text with `aria-describedby`, invalid controls with `aria-invalid`, and async outcomes with an appropriate status/alert region. Placeholder is not a label. Preserve input on failure, give a recovery action, and enforce server validation in your application.
+
+Loading is composition: state + meaningful text + `aria-busy`, with `disabled` when repeating the operation is invalid. Button has no `loading` prop. Static Card/Badge/Avatar do not gain loading/disabled/error behavior merely from an ARIA attribute. Use meaningful content and surrounding status messages. Native links are not disabled by a `disabled` prop forwarded through `asChild`.
+
+Avoid nested buttons/links or embedding unrelated controls in a single clickable surface. A small Switch/Checkbox graphic has a 44px pseudo-element target; keep label rows at least 44px and leave room so adjacent targets do not overlap. Test actual pointer hit areas, keyboard focus and text wrapping in the consumer.
+
+## Long and localized content
+
+Examples include Korean, English and Japanese. Set `lang` on translated content (Japanese selects Noto Sans JP in shared globals). Use responsive widths, `min-width: 0`, flexible heights and consumer wrapping classes for long actions/status text. The wrappers may use single-line truncation; retain the complete accessible name and offer the full value elsewhere if necessary. Do not shrink essential text to fit.
+
+Run each affected composition under matching light/dark, comfortable/compact, mobile and long-content conditions. Check 320 CSS-pixel reflow, text scaling, CSS zoom and actual native browser zoom separately. Axe and keyboard automation do not replace assistive-technology use. Follow the [manual acceptance and support matrix](../design/public-ui-support.md) and [dated verification](../design/public-ui-stage3-verification.md).
+
+[Field/choice composition](./composition.md) gives complete label/error and native-radio guidance. [Tabs](./tabs.md) and [Textarea](./textarea.md) extend the same shared contract; current extension results are in [Stage 4 verification](../design/public-ui-stage4-verification.md).
+
+## Exact inherited contracts
+
+Native wrappers use React 19 element props: inspect your installed `@types/react/index.d.ts`, or infer `React.ComponentProps<typeof Component>`. Radix wrappers use `React.ComponentProps<typeof Primitive.Part>`; inspect the installed declarations reached through `radix-ui/dist/index.d.ts`. Per-family guides link pinned declarations inspected locally during this work. Those links describe the inherited contract, not a promise that all primitive configurations have been tested. Wrapper defaults below are separate from primitive defaults; omitted primitive defaults are not invented here. Consumer examples and browser checks demonstrate only their recorded configuration.

package/docs/components/composition.md

@@ -0,0 +1,68 @@
+# Fields and choice composition
+
+The screen owns form state, validation, IDs and asynchronous work. `@naeil/ui` adds no FormField wrapper, form-state context or RadioGroup API. Existing HTML plus shared controls covers the observed common contract; see the [demand decision](../design/component-demand.md).
+
+## Label, help, error and recovery
+
+```tsx
+import { useId, useRef, useState } from 'react';
+import { Button, Textarea } from '@naeil/ui/ui';
+
+function NotesForm() {
+  const id = useId();
+  const field = useRef<HTMLTextAreaElement>(null);
+  const [invalid, setInvalid] = useState(false);
+  const [status, setStatus] = useState('');
+  return <form noValidate onSubmit={event => {
+    event.preventDefault();
+    const valid = field.current!.validity.valid;
+    setInvalid(!valid);
+    if (!valid) { field.current!.focus(); return; }
+    // Application-owned persistence and server validation go here.
+    setStatus('Notes accepted for this example.');
+  }} className="grid gap-6">
+    <div className="grid gap-2">
+      <label htmlFor={id}>Notes</label>
+      <Textarea ref={field} id={id} name="notes" required
+        aria-invalid={invalid} aria-describedby={`${id}-help ${id}-error`}
+        onChange={() => { setInvalid(false); setStatus(''); }} />
+      <p id={`${id}-help`}>Enter a description. Enter starts a new line.</p>
+      <p id={`${id}-error`} role="alert">{invalid ? 'Enter notes before saving.' : ''}</p>
+    </div>
+    <Button type="submit">Save notes</Button>
+    <p role="status">{status}</p>
+  </form>;
+}
+```
+
+Use the same label/help/error relationship with [Input](./input.md); put it on [SelectTrigger](./select.md) for Select. Keep existing description IDs when appending an error ID. Do not use placeholder as a name or nest multiple controls inside one label. `useId` avoids collisions when a composition repeats. Announce persistent errors once and preserve drafts; disable repeated submission with meaningful busy text when necessary. Disabled fields are omitted from FormData; read-only values remain included. HTML client validation is not server validation.
+
+## Choose values with native radios or Select
+
+For a small visible set of mutually exclusive values, use a `fieldset`/`legend` and native radios sharing one `name`. The label row provides the 44px target; leave space between rows. Native checked state, arrow navigation, form values and required validation remain native.
+
+```tsx
+<fieldset>
+  <legend>Delivery channel</legend>
+  <label className="ui-choice-label">
+    <input className="ui-focus accent-primary" type="radio"
+      name="delivery" value="instant" defaultChecked required />
+    Instant delivery
+  </label>
+  <label className="ui-choice-label">
+    <input className="ui-focus accent-primary" type="radio"
+      name="delivery" value="digest" />
+    Daily digest
+  </label>
+</fieldset>
+```
+
+Use a unique group name for separate forms/groups, or controlled `checked`/`onChange` when the product owns state. Connect group help/errors through `aria-describedby` and associate field-level errors where needed. A card selection still needs a value-input contract; visual selection or `aria-pressed` alone does not create radio semantics.
+
+Use [Select](./select.md) for a compact finite value input, for example a language, and preserve its `name` for form submission. Checkbox means independent boolean choices; Switch means an on/off preference. Do not use DropdownMenu action-radio items as the form's ordinary value input.
+
+## Actions, toggle actions and panels
+
+A Button performs an action such as clearing a draft. A toggle action such as pinning a preview uses a stable visible label and `aria-pressed`; it is not automatically a mutually exclusive form option. DropdownMenu groups commands. Tabs switches related panels; links navigate routes. These choices depend on the task, not the shape of the control.
+
+Run **UI / Textarea / Usage** for the complete field/radio/Select/action/toggle specimen and **UI / Tabs / Usage** for panel state/mount responsibility. Both use actual public controls. Apply the [shared contract](common.md) and preserve the product's application frame outside purpose-specific settings/reading/list widths. Check keyboard, native FormData, errors, long text, themes/density and overrides. [Manual acceptance](../design/public-ui-support.md) remains separate from automated checks.

package/docs/components/dialog.md

@@ -0,0 +1,41 @@
+# Dialog
+
+Use Dialog for a focused modal task or detail that requires an interruption. Prefer an inline panel for ordinary editing and a native confirmation flow suited to destructive actions; this package does not export AlertDialog.
+
+## API and wrapper defaults
+
+Exports: `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`, `DialogDescription`, `DialogClose`, `DialogPortal`, `DialogOverlay`.
+
+Root forwards Radix `open`/`defaultOpen`/`onOpenChange`/`modal`; wrapper adds no root defaults. Trigger/Close accept primitive button props including `asChild`. Content forwards primitive focus/outside/Escape handlers and **defaults `showCloseButton=true`**; it creates its own Portal and Overlay. Footer is a div with **`showCloseButton=false`**. Header is a div; Title/Description wrap primitive semantic elements. Built-in close labels are English `Close`. For localized close controls set Content showCloseButton=false and compose DialogClose. Content does not expose a portal `container` prop; the separately exported DialogPortal is for a custom composition.
+
+Inherited [Dialog 1.1.15 declaration](https://unpkg.com/@radix-ui/react-dialog@1.1.15/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/dialog.tsx) is the API authority.
+
+## Composition
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild><Button type="button">Edit name</Button></DialogTrigger>
+  <DialogContent showCloseButton={false}>
+    <DialogHeader><DialogTitle>Edit name</DialogTitle>
+      <DialogDescription>Change your display name.</DialogDescription></DialogHeader>
+    <label htmlFor="name">Name</label><Input id="name" />
+    <DialogFooter><DialogClose asChild>
+      <Button type="button" variant="outline">Cancel</Button>
+    </DialogClose></DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+Import the named components from `@naeil/ui/ui`. Variables/handlers in snippets are consumer-owned. Run **UI / Dialog / Usage** in Storybook for a complete interactive example; its Docs page renders this same guide.
+
+## Keyboard, focus and accessible content
+
+For the modal example, opening moves focus inside, Tab/Shift+Tab stay inside, Escape dismisses and focus returns to Trigger. Preserve default focus handlers unless you supply an equivalent appropriate destination. Always provide DialogTitle and a relevant Description; use aria-describedby={undefined} only when intentionally omitting a description. A triggerless controlled dialog requires a consumer focus-return destination.
+
+## States, resilience and mistakes
+
+Disabled applies to triggers/actions; loading/error/empty are content state. Keep failed input inside the dialog and enable retry. Long/mobile content should remain scrollable within the viewport (e.g. max-h-[calc(100%-2rem)] overflow-y-auto); do not hide all close actions. Consumer outside-dismissal overrides need keyboard/focus review. Do not nest modal roots casually or prevent Escape without an accessible exit.
+
+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/dropdown-menu.md

@@ -0,0 +1,38 @@
+# DropdownMenu
+
+Use DropdownMenu for actions and view toggles, Select for a form value, and navigation links for destinations. Menu checkbox/radio items are action-menu options, not a substitute for form inputs.
+
+## API and wrapper defaults
+
+Exports: `DropdownMenu`, `DropdownMenuPortal`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuGroup`, `DropdownMenuLabel`, `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`, `DropdownMenuSeparator`, `DropdownMenuShortcut`, `DropdownMenuSub`, `DropdownMenuSubTrigger`, `DropdownMenuSubContent`.
+
+Root: primitive `open`/`defaultOpen`/`onOpenChange`, `modal`, `dir`; no wrapper root defaults. Trigger supports `asChild` and `disabled`. Content creates Portal and defaults `sideOffset=4`; forwards align/side/collision/focus/outside handlers. Item defaults `variant="default"`, accepts `destructive` and `inset`; uses `onSelect`, `disabled`, `textValue`. Label/SubTrigger accept `inset`. CheckboxItem accepts boolean/indeterminate `checked` and `onCheckedChange`; RadioGroup accepts value/onValueChange, RadioItem requires value. Sub forwards open state; SubContent does not create a Portal automatically. Shortcut is a styled span and does **not** register a keyboard shortcut.
+
+Inherited [DropdownMenu 2.1.16 declaration](https://unpkg.com/@radix-ui/react-dropdown-menu@2.1.16/dist/index.d.ts), including its inherited Menu types.
+
+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/dropdown-menu.tsx) is the API authority.
+
+## Composition
+
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild><Button type="button" variant="outline">Actions</Button></DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem onSelect={copy}>Copy reference</DropdownMenuItem>
+    <DropdownMenuItem disabled>Archive (unavailable)</DropdownMenuItem>
+    <DropdownMenuItem variant="destructive" onSelect={confirmDelete}>Delete…</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+Import the named components from `@naeil/ui/ui`. Variables/handlers in snippets are consumer-owned. Run **UI / DropdownMenu / Usage** in Storybook for a complete interactive example; its Docs page renders this same guide.
+
+## Keyboard, focus and accessible content
+
+Enter/Space/ArrowDown open a trigger; arrows/Home/End/typeahead navigate enabled items, Enter selects, Escape closes and returns focus in the tested composition. Submenus use ArrowRight/ArrowLeft for LTR. Name icon-only triggers. Use onSelect for keyboard and pointer activation; announce operation success/failure outside the transient menu.
+
+## States, resilience and mistakes
+
+Disabled items remain descriptive but cannot select. Loading/empty/error belong to action state or an external status region; disable unavailable actions and supply recovery outside. Do not nest buttons inside menu items. Long localized actions must wrap within a viewport-bounded Content; pass className="max-w-[calc(100vw-2rem)]" and wrapping styles as needed. Do not imply shortcuts work unless the consumer registers them.
+
+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).