@tcn/ui 0.18.0 → 0.18.1

package/ai-docs/actions.md

@@ -0,0 +1,43 @@
+# Actions
+
+> **Scaffold placeholder.** Read the source files below for full implementation details. This document will be expanded with usage patterns and examples.
+
+---
+
+## Source Files
+
+| File | Purpose |
+|---|---|
+| `src/actions/button/base_button/base_button.tsx` | Core button primitive with base props |
+| `src/actions/button/button/button.tsx` | Extended button with hierarchy variants |
+| `src/actions/button/button_group/button_group.tsx` | Groups multiple buttons |
+| `src/actions/toggle/toggle.tsx` | Toggle switch component |
+| `src/actions/types.ts` | Shared action type definitions |
+
+---
+
+## Imports
+
+```ts
+import { Button, ButtonGroup, Toggle } from '@tcn/ui/actions';
+```
+
+---
+
+## Typing
+
+| Interface | Use for |
+|---|---|
+| `ButtonProps` | Full button API (extends BoxProps) |
+| `ButtonGroupProps` | Button group container |
+| `ToggleProps` | Toggle switch |
+
+---
+
+## Quick Reference
+
+- `Button` uses `data-hierarchy` for visual variants (primary, secondary, tertiary)
+- `data-disabled`, `data-is-loading` for state-driven theming
+- `ButtonGroup` arranges buttons horizontally with consistent spacing
+- `Toggle` is a stateful on/off switch
+- All components use `forwardRef` and expose `tcn-` class names

package/ai-docs/decorators.md

@@ -0,0 +1,34 @@
+# Decorators
+
+> **Scaffold placeholder.** Read the source files below for full implementation details. This document will be expanded with usage patterns and examples.
+
+---
+
+## Source Files
+
+| File | Purpose |
+|---|---|
+| `src/utils/decorators/draggable/draggable.tsx` | Draggable behavior wrapper |
+| `src/utils/decorators/draggable/drag_handle.tsx` | Drag handle component |
+| `src/utils/decorators/draggable/use_draggable.ts` | Draggable hook |
+| `src/utils/decorators/resizable/` | Resizable behavior wrapper |
+| `src/utils/decorators/DECORATOR_PATTERN.md` | Decorator pattern documentation |
+
+---
+
+## Imports
+
+```ts
+import { Draggable, DragHandle, Resizable } from '@tcn/ui/utils';
+```
+
+---
+
+## Quick Reference
+
+- Decorators inject behavior via `cloneElement` — wrap any component to add drag/resize
+- `<Draggable>` makes its child draggable; `<DragHandle>` restricts drag initiation to a handle area
+- `<Resizable>` adds resize handles to its child
+- Decorators can be stacked: `<Draggable><Resizable><Panel /></Resizable></Draggable>`
+- Do **not** add `enableResize*` style props to layout components — use `<Resizable>` wrapper instead
+- Read `DECORATOR_PATTERN.md` for the full pattern guide and how to create new decorators

package/ai-docs/feedback.md

@@ -0,0 +1,31 @@
+# Feedback
+
+> **Scaffold placeholder.** Read the source files below for full implementation details. This document will be expanded with usage patterns and examples.
+
+---
+
+## Source Files
+
+| File | Purpose |
+|---|---|
+| `src/feedback/loading/loading.tsx` | Loading spinner/skeleton indicator |
+| `src/feedback/progress/progress.tsx` | Circular/radial progress indicator |
+| `src/feedback/progress/progress_bar.tsx` | Horizontal progress bar |
+| `src/feedback/lazy/lazy.tsx` | Lazy loading wrapper with suspense |
+
+---
+
+## Imports
+
+```ts
+import { Loading, Progress, ProgressBar, Lazy } from '@tcn/ui/feedback';
+```
+
+---
+
+## Quick Reference
+
+- `Loading` displays a spinner or skeleton while content loads
+- `Progress` shows circular progress (0-100)
+- `ProgressBar` shows horizontal progress (0-100)
+- `Lazy` wraps components for lazy loading with a fallback

package/ai-docs/form.md

@@ -0,0 +1,58 @@
+# Form
+
+> **Scaffold placeholder.** Read the source files below for full implementation details. This document will be expanded with usage patterns and examples.
+
+---
+
+## Source Files
+
+| File | Purpose |
+|---|---|
+| `src/form/field/field.tsx` | Base field wrapper |
+| `src/form/field/h_field/h_field.tsx` | Horizontal field layout (label beside input) |
+| `src/form/field/v_field/v_field.tsx` | Vertical field layout (label above input) |
+| `src/form/field/common/field_control/field_control.tsx` | Control area wrapper |
+| `src/form/field/common/status_input/status_input.tsx` | Input with status indicators |
+| `src/form/field/common/field_header.tsx` | Field header (label + description area) |
+| `src/form/field/common/field_label.tsx` | Label element |
+| `src/form/field/common/field_description.tsx` | Helper/description text |
+| `src/form/field/common/field_error.tsx` | Error message display |
+| `src/form/field/field_presenters/field_presenter.tsx` | Generic field state presenter |
+| `src/form/field/field_presenters/options_field_presenter.tsx` | Presenter for option-based fields (select, radio) |
+| `src/form/field_set/field_set.tsx` | Groups related fields |
+| `src/form/field_set/legend.tsx` | Fieldset legend/title |
+| `src/form/form_field.tsx` | High-level form field component |
+
+---
+
+## Imports
+
+```ts
+import {
+  Field, HField, VField,
+  FieldSet, Legend,
+  FieldPresenter, OptionsFieldPresenter,
+  FormField,
+} from '@tcn/ui/form';
+```
+
+---
+
+## Typing
+
+| Interface | Use for |
+|---|---|
+| `FieldProps` | Base field container |
+| `HFieldProps` / `VFieldProps` | Horizontal / vertical field layout |
+| `FieldPresenterProps` | Connecting field state to UI |
+| `OptionsFieldPresenterProps` | Connecting option-based field state to UI |
+
+---
+
+## Quick Reference
+
+- Form fields are composed from small parts: `Field` > `FieldHeader` + `FieldControl` + `FieldErrorMessage`
+- Use `HField` for horizontal label-input layout, `VField` for vertical
+- `FieldPresenter` and `OptionsFieldPresenter` follow the presenter pattern from `@tcn/state`
+- `FieldSet` + `Legend` group related fields semantically
+- Form and Inputs are tightly coupled — inputs slot into the `FieldControl` area

package/ai-docs/inputs.md

@@ -0,0 +1,71 @@
+# Inputs
+
+> **Scaffold placeholder.** Read the source files below for full implementation details. This document will be expanded with usage patterns and examples.
+
+---
+
+## Source Files
+
+| File | Purpose |
+|---|---|
+| `src/inputs/input/input.tsx` | Text input field |
+| `src/inputs/textarea/textarea.tsx` | Multi-line text input |
+| `src/inputs/checkbox/checkbox.tsx` | Checkbox input |
+| `src/inputs/radio/radio.tsx` | Radio button input |
+| `src/inputs/switch/switch.tsx` | Toggle switch input |
+| `src/inputs/select/select.tsx` | Dropdown select |
+| `src/inputs/combo_box/combo_box.tsx` | Autocomplete dropdown |
+| `src/inputs/multi_combo_box/multi_combo_box.tsx` | Multi-select autocomplete |
+| `src/inputs/multiselect/multiselect.tsx` | Multi-select dropdown |
+| `src/inputs/date_picker/` | Date selection (day, header, body, input, presenter) |
+| `src/inputs/slider/slider.tsx` | Range slider input |
+| `src/inputs/color_input/color_input.tsx` | Color picker input |
+| `src/inputs/color_input/color_picker.tsx` | Color selection interface |
+| `src/inputs/phone_number_input/phone_number_input.tsx` | International phone number |
+| `src/inputs/mask_input/` | Masked text input (character types, cursor, presenter) |
+| `src/inputs/unit_input/unit_input.tsx` | Numeric input with unit selector |
+| `src/inputs/control/control.tsx` | Generic control wrapper |
+| `src/inputs/control_set/control_set.tsx` | Groups related controls |
+| `src/inputs/options/option.tsx` | Individual option item |
+| `src/inputs/select_group/select_group.tsx` | Multi-select group |
+| `src/inputs/select_group/single_select_group.tsx` | Single-select group |
+| `src/inputs/suggestions/` | Suggestion list components |
+
+---
+
+## Imports
+
+```ts
+import {
+  Input, Textarea, Checkbox, Radio, Switch,
+  Select, ComboBox, MultiComboBox, Multiselect,
+  DatePicker, SliderInput, ColorInput,
+  PhoneNumberInput, MaskInput, UnitInput,
+  Control, ControlSet, Option,
+} from '@tcn/ui/inputs';
+```
+
+---
+
+## Typing
+
+| Interface | Use for |
+|---|---|
+| `InputProps` | Text input |
+| `SelectProps` | Dropdown select |
+| `ComboBoxProps` | Autocomplete select |
+| `OptionProps` | Individual option in select/combo |
+| `DatePickerProps` | Date picker |
+| `MaskInputProps` | Masked input |
+
+---
+
+## Quick Reference
+
+- `onChange` passes value first, event second (not raw React events)
+- Options use composition: `<Select><Option value="a">A</Option></Select>`
+- `ComboBox` and `MultiComboBox` support type-ahead filtering
+- `MaskInput` supports 6 character types for formatted input (phone, SSN, etc.)
+- `DatePicker` is a complex component with sub-components (day, header, body, input)
+- Inputs are tightly coupled with Form — they slot into `FieldControl`
+- All inputs use `data-disabled`, `data-size` for theme-driven state styling

package/ai-docs/layouts.md

@@ -0,0 +1,76 @@
+# Layouts
+
+> **Scaffold placeholder.** Read the source files below for full implementation details. This document will be expanded with usage patterns and examples.
+
+---
+
+## Source Files
+
+| File | Purpose |
+|---|---|
+| `src/layouts/containers/scaffold.tsx` | Vertical page scaffold (VStack-based) |
+| `src/layouts/containers/rail.tsx` | Horizontal rail layout (HStack-based) |
+| `src/layouts/containers/columns/columns.tsx` | Equal-width column grid |
+| `src/layouts/containers/columns/column.tsx` | Single column in grid |
+| `src/layouts/containers/rows/rows.tsx` | Row flex container |
+| `src/layouts/containers/rows/row.tsx` | Single row |
+| `src/layouts/header/header.tsx` | Page/section header bar |
+| `src/layouts/footer/footer.tsx` | Page/section footer bar |
+| `src/layouts/bar/bar.tsx` | Generic horizontal bar |
+| `src/layouts/utility_bar/utility_bar.tsx` | Utility action bar |
+| `src/layouts/containers/utility_strip/utility_strip.tsx` | Compact utility action strip |
+| `src/layouts/section/section.tsx` | Content section with heading |
+| `src/layouts/section/heading.tsx` | Section heading |
+| `src/layouts/section/detail.tsx` | Section detail text |
+| `src/layouts/divider/divider.tsx` | Visual divider |
+| `src/layouts/grid/grid.tsx` | CSS grid layout |
+| `src/layouts/list/list.tsx` | Ordered/unordered list |
+| `src/layouts/list/item.tsx` | List item |
+| `src/layouts/table/table.tsx` | Semantic table (TTable, THead, TBody, TFoot, TR, TH, TD) |
+| `src/layouts/responsive/responsive.tsx` | Container-query responsive wrapper |
+| `src/layouts/responsive/breakpoint.tsx` | Breakpoint-based rendering |
+| `src/layouts/sidebar_start/sidebar_start.tsx` | Left sidebar |
+| `src/layouts/sidebar_end/sidebar_end.tsx` | Right sidebar |
+| `src/layouts/group/group.tsx` | Visual grouping container |
+
+---
+
+## Imports
+
+```ts
+import {
+  Scaffold, Rail, Header, Footer, Bar, UtilityBar,
+  Section, Heading, Detail, Divider,
+  Columns, Column, Rows, Row,
+  Grid, List, Item,
+  Responsive, Breakpoint,
+  SidebarStart, SidebarEnd,
+} from '@tcn/ui/layouts';
+```
+
+---
+
+## Typing
+
+| Interface | Use for |
+|---|---|
+| `ScaffoldProps` | Vertical page structure (extends VStackProps) |
+| `RailProps` | Horizontal layout (extends HStackProps) |
+| `ColumnsProps` / `ColumnProps` | Equal-width column grids |
+| `RowsProps` / `RowProps` | Row-based flex layouts |
+| `ResponsiveProps` | Container-query responsive wrapper |
+| `BreakpointProps` | Viewport-based conditional rendering |
+
+---
+
+## Quick Reference
+
+- Layouts provide **structure inside surfaces** — start with a surface (Panel, Card, Page), then use layouts for its internal structure
+- Standard pattern: `<Panel>` → `<Header>` + `<Scaffold>` (body) + `<Footer>`
+- `Scaffold` is the vertical layout container; `Rail` is the horizontal layout container
+- `Header` and `Footer` are horizontal bars at top/bottom; the `Scaffold` body fills remaining space
+- `Section` > `Heading` + content for semantic grouping within a body
+- `Columns` creates equal-width columns; `Rows` creates stacked rows
+- `Responsive` uses container queries; `Breakpoint` uses viewport queries
+- All layout components are thin compositions of stacks — they expose stack props
+- Use `<Resizable>` decorator wrapper for resizable regions, not layout props

package/ai-docs/mobile.md

@@ -0,0 +1,34 @@
+# Mobile
+
+> **Scaffold placeholder.** Read the source files below for full implementation details. This document will be expanded with usage patterns and examples.
+
+---
+
+## Source Files
+
+| File | Purpose |
+|---|---|
+| `src/mobile/viewport/` | MobileViewport — visual viewport tracking wrapper |
+| `src/mobile/portal/` | MobilePortal — portal for mobile overlays |
+| `src/mobile/actions/` | Mobile action components (FloatingActionButton, MobileButton) |
+| `src/mobile/inputs/date_picker/` | Mobile date picker variant |
+
+---
+
+## Imports
+
+```ts
+// Mobile components are exported from the root entry point
+import { MobileViewport, MobilePortal } from '@tcn/ui';
+```
+
+---
+
+## Quick Reference
+
+- Mobile uses **separate roots**, not responsive leaves — phone and tablet get their own component trees
+- `MobileViewport` tracks the visual viewport (handles keyboard, address bar) and provides context
+- `MobilePortal` renders overlays within the mobile viewport context
+- Mobile inputs (e.g., date picker) are full-viewport experiences, not inline dropdowns
+- Phone vs tablet: phone uses single-column with bottom navigation; tablet uses sidebar layouts
+- Mobile components do not have a separate entry point — import from `@tcn/ui`

package/ai-docs/navigation.md

@@ -0,0 +1,48 @@
+# Navigation
+
+> **Scaffold placeholder.** Read the source files below for full implementation details. This document will be expanded with usage patterns and examples.
+
+---
+
+## Source Files
+
+| File | Purpose |
+|---|---|
+| `src/navigation/tabs/state/context.tsx` | Stateful tabs context (Tabs, useTabs) |
+| `src/navigation/tabs/state/tab.tsx` | Individual tab item |
+| `src/navigation/tabs/state/nav_bar.tsx` | Tabs navigation bar |
+| `src/navigation/tabs/state/link/tab_link.tsx` | Tab with routing integration |
+| `src/navigation/tabs/primitives/tabs_bar.tsx` | Unstyled tabs bar primitive |
+| `src/navigation/tabs/primitives/tabs_list.tsx` | Tabs list primitive (TabsList, TabItem) |
+
+---
+
+## Imports
+
+```ts
+// Stateful tabs (managed selection state)
+import { Tabs, Tab, TabsNavbar, TabLink, useTabs } from '@tcn/ui/navigation';
+
+// Primitive tabs (bring your own state)
+import { TabsBar, TabsList, TabItem } from '@tcn/ui/navigation';
+```
+
+---
+
+## Typing
+
+| Interface | Use for |
+|---|---|
+| `TabsProps` | Stateful tabs container |
+| `TabProps` | Individual tab |
+| `TabLinkProps` | Tab with route navigation |
+| `TabsBarProps` | Primitive tabs bar |
+
+---
+
+## Quick Reference
+
+- Two APIs: **stateful** (Tabs/Tab — manages selection) and **primitive** (TabsBar/TabsList — bring your own state)
+- Stateful tabs use `useTabs` hook for programmatic control
+- `TabLink` integrates with routing for URL-driven tab navigation
+- Primitive tabs are unstyled and fully controlled

package/ai-docs/overlay.md

@@ -0,0 +1,58 @@
+# Overlay
+
+> **Scaffold placeholder.** Read the source files below for full implementation details. This document will be expanded with usage patterns and examples.
+
+---
+
+## Source Files
+
+| File | Purpose |
+|---|---|
+| `src/overlay/portal/portal.tsx` | React portal — renders children outside DOM hierarchy |
+| `src/overlay/frame/frame.tsx` | Overlay frame/backdrop container |
+| `src/overlay/menu/menu.tsx` | Dropdown menu |
+| `src/overlay/context_menu/context_menu.tsx` | Right-click context menu |
+| `src/overlay/tethered/tethered.tsx` | Position element relative to trigger |
+| `src/overlay/tethered/element_tethered.tsx` | Element-anchored tethering |
+| `src/overlay/tethered/types.ts` | Tether position type definitions |
+| `src/overlay/popper/base/base_popper.tsx` | Base popper positioning engine |
+| `src/overlay/popper/base/dismissal_decorator.tsx` | Click-outside dismissal |
+| `src/overlay/popper/preview_popper.tsx` | Preview/tooltip popper |
+| `src/overlay/popper/context_popper.tsx` | Context menu popper |
+| `src/overlay/popper/element_popper.tsx` | Element-anchored popper |
+| `src/overlay/popper/legacy/popper.tsx` | Legacy popper API |
+
+---
+
+## Imports
+
+```ts
+import {
+  Portal, Frame, Menu, ContextMenu,
+  Tethered, ElementTethered,
+  BasePopper, PreviewPopper, ContextPopper, ElementPopper,
+} from '@tcn/ui/overlay';
+```
+
+---
+
+## Typing
+
+| Interface | Use for |
+|---|---|
+| `PortalProps` | Portal container |
+| `MenuProps` | Dropdown menu |
+| `TetheredProps` | Positioned overlay |
+| `BasePopperProps` | Base popper |
+| `HorizontalTether` / `VerticalTether` | Tether position enums |
+
+---
+
+## Quick Reference
+
+- `Portal` renders into a DOM node outside the React tree (for z-index isolation)
+- `Tethered` / `ElementTethered` position an overlay relative to a trigger element
+- `BasePopper` is the low-level positioning engine; use `PreviewPopper`, `ContextPopper`, or `ElementPopper` for specific patterns
+- `Menu` and `ContextMenu` compose Popper + list for dropdown/right-click menus
+- `Frame` provides a backdrop/overlay container
+- Overlay often composes with Surface components (Modal, Drawer, Popover use Portal + Popper internally)

package/ai-docs/stacks.md

@@ -0,0 +1,59 @@
+# Stacks
+
+> **Scaffold placeholder.** Read the source files below for full implementation details. This document will be expanded with usage patterns and examples.
+
+---
+
+## Source Files
+
+| File | Purpose |
+|---|---|
+| `src/stacks/v_stack.tsx` | Vertical flexbox stack |
+| `src/stacks/h_stack.tsx` | Horizontal flexbox stack |
+| `src/stacks/z_stack.tsx` | Z-axis layering stack |
+| `src/stacks/box/box.tsx` | Base box container (non-directional) |
+| `src/stacks/box/types.ts` | Box type definitions |
+| `src/stacks/spacer.tsx` | Flexible spacer between items |
+| `src/stacks/v_collapsible_box.tsx` | Collapsible vertical container |
+| `src/stacks/h_collapsible_box.tsx` | Collapsible horizontal container |
+| `src/stacks/types/` | Alignment, sizing, and common type definitions |
+
+---
+
+## Imports
+
+```ts
+import {
+  VStack, HStack, ZStack, Box, Spacer,
+  VCollapsibleBox, HCollapsibleBox,
+} from '@tcn/ui/stacks';
+
+// Type imports
+import type { Alignment, As } from '@tcn/ui/stacks';
+```
+
+---
+
+## Typing
+
+| Interface | Use for |
+|---|---|
+| `VStackProps<E>` | Vertical stack (generic over HTML element) |
+| `HStackProps<E>` | Horizontal stack |
+| `ZStackProps<E>` | Z-axis layering stack |
+| `BoxProps<E>` | Base box |
+| `Alignment` | Alignment values for hAlign/vAlign |
+
+---
+
+## Quick Reference
+
+- Stacks are the **atomic primitives** underneath layouts and surfaces — most apps should use named layout components (Scaffold, Rail, Header, Section) and surfaces (Panel, Card, Page) instead
+- **Use stacks when building custom reusable components**, not for app-level UI composition
+- Common props: `hAlign`, `vAlign`, `width`, `height`, `gap`, `growWeight`, `shrinkWeight`, `padding`, `margin`
+- Sizing accepts: `'default' | 'flex' | 'auto' | 'fill' | string | number`
+- `VStack` = vertical flex, `HStack` = horizontal flex, `ZStack` = absolute positioning layers
+- `Box` is a non-directional container (no flex direction)
+- `Spacer` fills available space between siblings
+- Polymorphic `as` prop changes the rendered HTML element
+- All stacks use `forwardRef` with generic element type

package/ai-docs/surfaces.md

@@ -0,0 +1,79 @@
+# Surfaces
+
+> **Scaffold placeholder.** Read the source files below for full implementation details. This document will be expanded with usage patterns and examples.
+
+Surfaces are the **starting point** for building UI. They are styled containers that provide themed visual treatment (borders, shadows, backgrounds). Use layouts inside surfaces to build their internal structure — headers, footers, sections, columns.
+
+---
+
+## Surface Categories
+
+**Container surfaces** — wrap a `Scaffold` internally, designed for complex layout composition:
+- `Panel`, `Card`, `Page`, `Aside` — inline containers for content regions
+- `Modal`, `Window`, `Drawer` — overlay containers (positioned/animated, but still Scaffold-based inside)
+
+**Functional surfaces** — styled overlays for contextual feedback, simpler internal structure:
+- `Tooltip` — hover-triggered label overlay
+- `Popover` — floating content overlay
+- `PopConfirm` — confirmation overlay anchored to an element
+- `Alert`, `Confirm` — notification/confirmation dialogs
+
+---
+
+## Source Files
+
+| File | Purpose |
+|---|---|
+| `src/surfaces/panel/panel.tsx` | Panel — primary content container (wraps Scaffold) |
+| `src/surfaces/card/card.tsx` | Card — secondary content container (wraps Scaffold) |
+| `src/surfaces/page/page.tsx` | Page — full page surface (wraps Scaffold) |
+| `src/surfaces/aside/aside.tsx` | Aside — sidebar surface (wraps Scaffold) |
+| `src/surfaces/modal/modal.tsx` | Modal — overlay dialog (Frame + Scaffold) |
+| `src/surfaces/window/window.tsx` | Window — draggable/resizable overlay (Frame + Scaffold) |
+| `src/surfaces/drawer/drawer.tsx` | Drawer — slide-out panel (Slide + Scaffold) |
+| `src/surfaces/tooltip/tooltip.tsx` | Tooltip — hover label overlay |
+| `src/surfaces/popover/popover.tsx` | Popover — floating content overlay |
+| `src/surfaces/pop_confirm/pop_confirm.tsx` | PopConfirm — anchored confirmation overlay |
+| `src/surfaces/alert/alert.tsx` | Alert — notification dialog |
+| `src/surfaces/confirm/confirm.tsx` | Confirm — confirmation dialog |
+
+---
+
+## Imports
+
+```ts
+import {
+  Panel, Card, Page, Aside,
+  Modal, Window, Drawer,
+  Tooltip, Popover, PopConfirm,
+  Alert, Confirm,
+} from '@tcn/ui/surfaces';
+```
+
+---
+
+## Typing
+
+| Interface | Use for |
+|---|---|
+| `PanelProps` | Panel container |
+| `CardProps` | Card container |
+| `PageProps` | Full page surface |
+| `AsideProps` | Sidebar surface |
+| `ModalProps` | Modal dialog |
+| `DrawerProps` | Slide-out drawer |
+| `WindowProps` | Draggable window |
+| `TooltipProps` | Tooltip overlay |
+| `PopoverProps` | Floating popover |
+
+---
+
+## Quick Reference
+
+- **Start with a surface**, then use layouts for internal structure (see [layouts.md](layouts.md))
+- Container surfaces (Panel, Card, Page) wrap Scaffold — use `Header`, `Footer`, `Section`, `Columns` inside them
+- The standard pattern: `<Panel>` → `<Header>` + `<Scaffold>` (body) + `<Footer>`
+- Overlay surfaces (Modal, Drawer, Window) follow the same internal layout pattern, just positioned differently
+- `Alert` uses `data-severity` for themed severity levels (info, warning, error)
+- `Window` supports drag and resize via Frame (compose with decorators for additional behavior)
+- All surfaces expose `tcn-` class names — themes control all visual appearance contextually

package/ai-docs/themes.md

@@ -0,0 +1,47 @@
+# Themes
+
+> **Scaffold placeholder.** Read the source files below for full implementation details. This document will be expanded with usage patterns and examples.
+
+---
+
+## Source Files
+
+| File | Purpose |
+|---|---|
+| `src/themes/theme.tsx` | Theme provider component |
+| `src/themes/theme_variables.ts` | CSS custom property definitions (colors, spacing, font, status) |
+| `src/themes/build_stylesheet.ts` | Theme stylesheet builder utility |
+| `src/themes/stylesheets/reset.ts` | CSS reset export |
+| `src/themes/stylesheets/reset.css` | Browser reset stylesheet |
+| `src/themes/themes/ergo/ergo_theme.ts` | Ergo theme (default) |
+| `src/themes/themes/ergo/ergo_theme.css` | Ergo theme stylesheet |
+| `src/themes/themes/ergo/parts/` | Ergo theme parts (actions, base, form, inputs, navigation) |
+| `src/themes/themes/ergo/tokens/` | Ergo tokens (system_tokens.css, theme_tokens.css) |
+| `src/themes/themes/windows_98/windows_98_theme.ts` | Windows 98 retro theme |
+| `src/themes/themes/windows_98/windows_98.css` | Windows 98 stylesheet |
+| `src/css/layers.css` | CSS cascade layer definitions |
+
+---
+
+## Imports
+
+```ts
+// Theme system
+import { theme, theme_variables, reset } from '@tcn/ui/themes';
+
+// Specific themes
+import { ergo_theme } from '@tcn/ui/themes/ergo';
+import { windows_98_theme } from '@tcn/ui/themes/windows98';
+```
+
+---
+
+## Quick Reference
+
+- Components are **theme-agnostic** — the same JSX renders differently depending on which theme stylesheet is active
+- Three CSS cascade layers enforce precedence: `tcn-reset` < `tcn-system` (`:where()`) < `tcn-theme`
+- Themes target `tcn-*` class names and `data-*` attributes in the `tcn-theme` layer
+- `theme_variables` provides CSS custom properties: colors, spacing, font, status, `--scalar`
+- The `--scalar` variable enables proportional scaling across all components
+- **Custom components** should use `theme_variables` instead of hardcoded values
+- Contextual theming: a `Button` inside a `UtilityBar` inside a `Panel` can have a unique appearance — all controlled by the theme