@povio/ui 5.0.0-rc.1 → 5.0.0-rc.11

package/.rulesync/rules/ui-buttons-and-content.md

@@ -0,0 +1,56 @@
+---
+targets: ["*"]
+description: "@povio/ui buttons, labels, status feedback, and text-content APIs"
+globs:
+  - "packages/ui/src/components/buttons/**/*"
+  - "packages/ui/src/components/text/**/*"
+  - "packages/ui/src/components/status/**/*"
+  - "packages/ui/src/components/shared/pagination/**/*"
+---
+
+# Buttons, text, and status components
+
+## Button
+
+Use `Button` for an action. Its content is `children`; use `link` only when it navigates through the configured `LinkContext`.
+
+- Visual variants: `contained`, `solid`, `outlined`, `outline`, `subtle`, `text`, `ghost`. The default CVA styles `solid` like `contained` and `outline` like `outlined`, but passes every value through unchanged so UI overrides can redefine either value.
+- Colors: `primary`, `secondary`, `error` (destructive theme tokens), and Atlas-specific `dual`. Text buttons with `dual` use primary text and secondary icons. Only primary text buttons support `inverted`, using the primary foreground token.
+- Sizes: `sm` (alias `s`), `default`, and `none` (zero padding); omit the size prop for `default`. Legacy sizes (`xs`, `small`, `m`, `md`, `l`, `lg`) are not supported.
+- Use `fullWidth`; `width="fill"` and `width="hug"` remain valid.
+- Use `loading` or `isLoading`; loading disables the button by default. `disableWhileLoading={false}` opts out; `noDisableWhenLoading` is the legacy inverse.
+- Use `startIcon` and `endIcon`. `icon` plus `iconPosition="left" | "right"` remains supported.
+- Use `IconButton` for icon-only actions and supply `ariaLabel` or `label`. `InlineIconButton` is the text-style icon-only variant.
+- Use `ToggleButton` for one independently toggled state (`isSelected`, `defaultSelected`, `onChange`). It defaults to outlined primary but honors supplied `variant` and `color`.
+- Use `SplitButton` only for a primary action with menu alternatives; use `ButtonGroup` for peer actions.
+- `variant`, `size`, and other CVA props belong to the active override. Never normalize their values inside a component; define default compatibility aliases as CVA entries instead.
+- Use `BadgeButton` from `@povio/ui/badge-button` for a compact, badge-styled action. It has its own CVA but follows the same variant contract: `solid` and `outline` are default aliases and are passed unchanged to `badgeButton.cva` overrides.
+
+## Tags, links, typography
+
+Typography sizes are `headline-l`, `h1`–`h4`, `lead`, `body`, `large`, and `small`; There is no typography `variant`; use `className="font-bold"` or `className="italic"` for emphasis. `large` and `small` do not add font weight; use explicit emphasis when needed. Use the same size on mobile and desktop unless explicitly overridden.
+
+- `Badge` and `Tag` are display components, not generic buttons. Use `dismissible` and `onRemove` for removal; `dismissable` and `onDismiss` are legacy forms.
+- `Badge` and `BadgeButton` support primary, secondary, success, warning, and error colors with contained, outlined, and subtle variants. Their padding is 2px vertically and 8px horizontally, or 6px horizontally when an icon/dismiss control is present. `Badge isSelected` displays the toggled state; use `BadgeButton toggle` for an interactive toggle. Toggled colors use the same state modifiers as buttons.
+- Pass remove-button behavior through `dismissButtonProps`; arbitrary button props do not belong on the display container.
+- Use `Link` for navigation and `Button` for actions.
+- Use `Typography` with semantic `as` elements (`h1`, `h2`, `p`, `span`) and library typography variants/sizes. Token changes belong in UI overrides, not consumers.
+
+## Feedback
+
+- Use `Alert` for persistent inline status, `Toast`/`useToast` for transient notifications, `Spinner` for indeterminate progress, and `Progress` for numeric progress.
+- For alerts and toasts, keep `variant` (`contained`/`outlined`) separate from semantic `color` (`neutral`, `success`, `warning`, `error`).
+- Alert and Toast message text uses `large` typography. Outlined messages use `surface-default-card-foreground` text and primary text-button actions. Contained messages use `surface-inverted-card-foreground` for neutral, `surface-success-inverted-base` for success, `surface-warning-inverted-base` for warning, and `surface-destructive-inverted-base` for error; actions use inverted primary text buttons. Actions use `size="none"`, with `toast-gap-action` spacing between them. Alert's `rightContent` is caller supplied, so configure its actions with `TextButton size="none" color="primary" inverted={variant === "contained"}`.
+- Toast actions are `{ text, onPress }`; keep them short and non-destructive.
+
+## Reference
+
+- `packages/ui/src/components/buttons/Button/Button.tsx` — Button behavior and compatibility.
+- `packages/ui/src/components/text/Tag/Tag.tsx` — dismissible tag contract.
+- `packages/ui/src/components/status/Toast/Toast.tsx` — toast content and actions.
+
+## When refactoring
+
+- `Button` uses `icon` only for a conventional start/end icon → use `startIcon` or `endIcon`.
+- An icon-only action has no accessible name → use `IconButton` with `ariaLabel` or `label`.
+- A tag/pill receives `onPress` to represent selection → use `ToggleButton` or `ToggleGroup`.

package/.rulesync/rules/ui-inputs-and-forms.md

@@ -0,0 +1,62 @@
+---
+targets: ["*"]
+description: "@povio/ui form fields, selection controls, pickers, uploads, and React Hook Form integration"
+globs:
+  - "packages/ui/src/components/inputs/**/*"
+  - "packages/ui/src/hooks/useForm*.ts"
+---
+
+# Inputs and forms
+
+## Shared field contract
+
+- Sizes: `small` and `default` only. Omit `size` for the default; `extra-small` and `large` are not supported. This shared input API has no `sm` or `s` aliases.
+- Use `label`, `helperText`, `error`, `isRequired`, and `isDisabled` as the base field contract.
+- `Input`, `TextArea`, and `NumberField` also accept `errorMessage`, `required`, and `disabled`. Their visual layout is `layout="default" | "floating" | "filter" | "inline"`; `as` remains the legacy layout prop and is not polymorphic element selection.
+- Use `variant="outlined" | "filled"` for text-like inputs. Keep layout separate from variant.
+- Use `isClearable`, `leadingIcon`, `trailingIcon`, `action`, `unit`, `placeholder`, and `inputClassName` only where exposed; do not recreate input chrome in consumers.
+- Controlled fields use `value` and `onChange`; uncontrolled fields use `defaultValue`. Preserve callback value types: strings for text, `number | null` for number fields, and component-specific date values for pickers.
+
+## Selection controls
+
+- `Checkbox` uses `isSelected`, `defaultSelected`, and `onChange(boolean)`; `children` may be any `ReactNode`.
+- `Switch` uses the same boolean selection contract.
+- `RadioGroup` takes `options: { label, value }[]` and scalar `value`/`defaultValue`/`onChange`.
+- `CheckboxGroup` takes the same options shape and array values. `allValue` is an Atlas extension for all-selected representation.
+- `ToggleGroup`, `Select`, and `Autocomplete` use `selectionMode="single" | "multiple"`. Single values are `Key | null`; multiple values are `Key[]`.
+- `Select` is a closed selection field. `Autocomplete` is the searchable/combobox form of the same item API. Both take `items: { id, label, content?, isDisabled? }[]`.
+- Preserve Select capabilities: `isSearchable`, `isClearable`, `showSelectAllOption`, `showSelectionBar`, `showNewItemOption`, `onNewItemOption`, async `isLoading`/`hasLoadMore`/`onLoadMore`, and `virtualizerOptions`.
+- Use `QuerySelect` and `QueryAutocomplete` only with the package TanStack Query adapter; they are not generic async-select replacements.
+
+## Dates, ranges, files, rich text
+
+- Use `DatePicker`, `DateRangePicker`, `TimePicker`, and `DateTimePicker` for React Aria date values. Preserve `minValue`, `maxValue`, `granularity`, `isClearable`, and date-input options rather than replacing them with native inputs.
+- Use `Slider` with numeric `value`/`defaultValue`; set `isRange` for two-thumb values.
+- Use `FileInput` for controlled form file values and `FileUpload` for upload lifecycle, progress, cancellation, and uploaded-file display. Both accept `multiple` or `allowsMultiple`.
+- Import `RichTextEditor` from `@povio/ui/rich-text-editor`, not the main package entry point.
+
+## Forms
+
+```tsx
+// TanStack Form (native binding, e.g. import from "@povio/ui/tanstack/input")
+<Input label="Name" field={{ form, name: "name" }} />
+
+// React Hook Form (adapter, e.g. import from "@povio/ui/rhf/input")
+<Input label="Name" formControl={{ control: form.control, name: "name" }} />
+```
+
+- `field` (TanStack) and `formControl` (React Hook Form) each own `value`, `onChange`, and `onBlur`; do not supply competing controlled props alongside either.
+- `Form` and `Inputs` are Zod schema helpers, available in both the TanStack-native and React Hook Form flavors. Use a regular HTML `<form>` with individual fields when schema-generated rendering is not needed.
+
+## Reference
+
+- `packages/ui/src/components/inputs/Input/Input.tsx` — core text-field API.
+- `packages/ui/src/components/inputs/Selection/shared/SelectBase.tsx` — selection and async capabilities.
+- `packages/ui/src/components/inputs/shared/form.types.ts` — typed `field` (TanStack) contract.
+- `packages/ui/src/rhf/form.types.ts` — typed `formControl` (React Hook Form) contract.
+
+## When refactoring
+
+- A consumer uses `as` to select a DOM element → use `layout`; `as` controls legacy input presentation.
+- App code checks `allowsMultiple` → prefer `multiple` in new code.
+- A select hand-rolls filtering or virtualized results → use the exposed Select/Autocomplete props before adding consumer-side overlay logic.

package/.rulesync/rules/ui-overlays-navigation-and-styling.md

@@ -0,0 +1,49 @@
+---
+targets: ["*"]
+description: "@povio/ui overlays, navigation, tables, accessibility, and styling conventions"
+globs:
+  - "packages/ui/src/components/overlays/**/*"
+  - "packages/ui/src/components/navigation/**/*"
+  - "packages/ui/src/components/DropdownMenu/**/*"
+  - "packages/ui/src/components/Breadcrumbs/**/*"
+  - "packages/ui/src/components/table/**/*"
+  - "packages/ui/src/components/**/*.cva.ts"
+---
+
+# Overlays, navigation, tables, and styling
+
+## Overlays and navigation
+
+- Use `Dialog` with controlled `isOpen`; handle transitions with `onOpenChange`. `onClose` remains available for close-only behavior.
+- Use `AlertDialog` for confirmations with a primary action and optional secondary action.
+- Use `Drawer` for a side panel and `BottomSheet` for a mobile bottom sheet. Both own focus trapping and dismissal; do not mount parallel ad-hoc overlays.
+- `Popover` renders a desktop popover and mobile bottom sheet. It requires a trigger, controlled state, and accessible `sheetLabel`.
+- Use `Tooltip` for supplemental text only; it must not be the sole accessible label for an icon action.
+- Use `DropdownMenu` with `trigger`, `items`, and `onAction`. Menu items are `{ id, label, content?, link?, children? }`; nested `children` create submenus.
+- Use `Accordion` for expandable content, `Stepper` for step progress, `Breadcrumbs` for hierarchy, and `Pagination`/`PaginationList` for page navigation.
+
+## Tables
+
+- `Table` is the base TanStack wrapper. Use `PaginatedTable` or `InfiniteTable` only when their data-loading contracts match the view.
+- Keep table columns in the consumer domain. Use `CellText` and `HeaderText` for consistent text treatment; use `ColumnConfigModal` for persisted visibility/configuration behavior.
+
+## Styling and accessibility
+
+- Components use class-variance-authority, `UIOverrides`, and tokenized Tailwind classes. Add visual variants through the relevant `*.cva.ts` definition and expose a typed variant prop; do not add hard-coded color values in consumers.
+- Use `UIConfig` for package-wide defaults and `UIOverrides` for recipe overrides. Do not duplicate component markup to bypass them.
+- Preserve React Aria state props/data attributes (`isDisabled`, `isSelected`, `isInvalid`, `data-selected`) when wrapping controls.
+- Root styling uses `className`. Prefer existing slot props (`inputClassName`, `dialogClassName`, `overlayClassName`, `containerClassName`) over selectors reaching into library internals.
+- Keep button-like controls keyboard accessible. Icon-only actions need an accessible name; labels remain associated with fields.
+- Avoid nested runtime ternaries in rendering or prop normalization. Use a named helper, map, or explicit branch.
+
+## Reference
+
+- `packages/ui/src/components/overlays/Dialog/Dialog.tsx` — controlled dialog behavior.
+- `packages/ui/src/components/DropdownMenu/DropdownMenu.tsx` — responsive menu boundary.
+- `packages/ui/src/config/uiOverrides.context.tsx` — recipe override system.
+
+## When refactoring
+
+- A component hard-codes a visual token already represented by a CVA recipe → add or reuse a typed recipe variant.
+- An icon-only trigger relies only on a tooltip → add an `aria-label`/`ariaLabel` or visible label.
+- Overlay state is duplicated in an app wrapper and a UI component → make controlled `isOpen`/`onOpenChange` the source of truth.

package/.rulesync/rules/ui-overview.md

@@ -0,0 +1,33 @@
+---
+root: true
+targets: ["*"]
+description: "@povio/ui public API and component-selection guidance"
+globs: ["packages/ui/**/*"]
+---
+
+# @povio/ui component-library overview
+
+`@povio/ui` is a React 19, TypeScript, Tailwind 4 component library built on React Aria Components. Import components and hooks from component-scoped subpaths (e.g. `@povio/ui/dialog`, `@povio/ui/rich-text-editor`), or from the broader `@povio/ui/rhf` (React Hook Form) or `@povio/ui/tanstack` (TanStack Form) entries; internal `src/components/**` paths are not consumer APIs.
+
+## Public API and naming
+
+- `src/rhf.ts` and `src/tanstack.ts` are the authoritative barrels for the two form-integration flavors; `src/entries/*.ts` (plus `src/entries/rhf/*.ts` and `src/entries/tanstack/*.ts` for form-capable components) back the individual `package.json#exports` subpaths. Add or change a public component in all three places together with its prop type.
+- Component names are canonical and final: `Input`, `NumberField`, `FileInput`, `Switch`, `ToggleGroup`, `DropdownMenu`, `Dialog`, `AlertDialog`, `Popover`, `Spinner`, `Progress`, `Badge`, `RichTextEditor` (exported from `@povio/ui/rich-text-editor`).
+- Use `ButtonGroup` for grouped independent actions. Use `ToggleGroup` only when the group represents selected value(s).
+
+## Common conventions
+
+- Components use React Aria event names (`onPress`, `onChange`, `isDisabled`, `isSelected`) as their base API.
+- Form-capable components speak a native `field: { form, name }` TanStack Form binding. Consumers on `@povio/ui/rhf/*` get the same components wrapped with a `formControl: { control, name }` React Hook Form adapter instead. Do not pass `value`, `onChange`, or `onBlur` together with `field`/`formControl`.
+- Keep public props semantic and domain-independent. Use `className` for root styling and component-specific `*ClassName` props only for independently styled internal slots.
+- Prefer `ReactNode` for display content and preserve `aria-*` props through to the interactive element.
+
+## Reference
+
+- `packages/ui/src/rhf.ts` / `packages/ui/src/tanstack.ts` — public exports per form-integration flavor.
+- `packages/ui/src/config/uiConfig.context.tsx` — runtime component defaults.
+
+## When refactoring
+
+- A consumer imports from `src/components/...` → switch it to a package subpath export.
+- A stateful segmented control is used as an action toolbar → use `ButtonGroup` and `Button`s instead.

package/README.md

@@ -12,6 +12,7 @@ Use component and feature subpaths in application code. Each subpath resolves to
 
 ```tsx
 import { Button } from "@povio/ui/button";
+import { BadgeButton } from "@povio/ui/badge-button";
 import { Dialog } from "@povio/ui/dialog";
 import { Select } from "@povio/ui/tanstack/select";
 import { useForm } from "@povio/ui/tanstack/form";
@@ -25,7 +26,7 @@ The broad `@povio/ui`, `@povio/ui/rhf`, and `@povio/ui/tanstack` entries remain
 
 Feature dependencies are optional peers. Install the matching packages when using date/calendar entries, `@povio/ui/tanstack/table`, RHF/TanStack Form inputs, or the rich text editor. Basic components such as Button, Typography, and Dialog do not require table, drag-and-drop, calendar, or TipTap packages.
 
-React Aria is an internal `@povio/ui` dependency and does not need to be installed separately. Povio component entries include the React Aria implementation they use. Component-scoped escape-hatch entries expose only the corresponding React Aria primitive and its types for custom implementations:
+React Aria is an internal `@povio/ui` dependency and does not need to be installed separately. The build keeps `react-aria` and all its subpaths external so providers and Povio components share the installed module contexts. Component-scoped escape-hatch entries expose only the corresponding React Aria primitive and its types for custom implementations:
 
 ```tsx
 import { Link, type LinkProps } from "@povio/ui/link/react-aria";
@@ -40,6 +41,23 @@ The React Aria hooks used by Povio are similarly isolated under `use-text-field`
 
 Each emitted entry is independently bundled and tree-shaken; it does not forward React Aria's aggregate barrel or share a generated aggregate chunk with unrelated controls. Ordinary Povio component imports do not include the escape-hatch entries.
 
+Use `Badge` for display content, `BadgeButton` for a compact, badge-styled action, and `ToggleButton` or `ToggleGroup` for selection. `BadgeButton` uses the theme's `badge-*` spacing and radius tokens; customize its recipe through `UIOverrides.badgeButton`.
+
+## Theme configurator
+
+The live theme editor ships separately as `@povio/ui/ui-configurator`, with its stylesheet at `@povio/ui/ui-configurator/styles`. It is independent of Storybook and is excluded from ordinary component imports. For only the `parseThemeCss` / `exportCss` helpers and token types, use the lightweight `@povio/ui/ui-configurator/theme` entry.
+
+To save its Tailwind CSS export directly to your app's theme during development, add the bundled Vite plugin:
+
+```ts
+import { uiConfigurator } from "@povio/ui/ui-configurator/vite";
+
+// In your Vite plugins array:
+uiConfigurator({ themeFile: "src/styles/theme.css" });
+```
+
+The path defaults to `src/styles/theme.css` relative to this app's Vite root. **Advanced → Export → Tailwind CSS → Save theme** updates that file's token declarations and lets Vite reload the CSS. Each app writes only its own configured theme. Apply remains session-only; Cancel does not undo a file save. The plugin and save action are absent from builds and preview servers. See [the configurator guide](./src/configurator/README.md) for provider setup, preview behavior, and supported theme blocks.
+
 ## Button sizes
 
 `Button` supports `sm` (with `s` as an equivalent alias), `default`, and `none` (zero padding). Omitting `size` uses `default`. The same sizes apply to `IconButton`, `InlineIconButton`, `TextButton`, `ToggleButton`, and `SplitButton`.
@@ -54,6 +72,10 @@ Inputs support `size="small"` and `default`. Omit `size` for the default. This a
 
 Replace `size="extra-small"` with `size="small"`, and remove `size="large"` or `size="default"` to use the default. Small and default retain their existing spacing.
 
+## Built-package tests
+
+From `packages/ui`, run `bun run test:package` to build the publishable package and run its Chromium regressions. The tests resolve public imports through `dist/package.json`, covering both date pickers with empty and populated values in static and editable modes, including locale switches without remounting.
+
 ## Versioning
 
 `^2.1` still corresponds to Atlas 2.1. All versions after that currently target Atlas 2.2 and follow semantic versioning — breaking changes bump the major version.
@@ -62,21 +84,15 @@ Replace `size="extra-small"` with `size="small"`, and remove `size="large"` or `
 
 The package ships RuleSync source rules in `.rulesync/` and `rulesync.jsonc`. They document the public component API, standard aliases, form contracts, accessibility expectations, and styling conventions for AI coding tools. Generated tool files are deliberately excluded from the published npm package.
 
-To generate the UI rules into a consuming project's repository root, run the executable bundled with `@povio/ui`:
-
-```bash
-pnpm exec povio-ui-rules
-```
-
-With npm, use:
+To generate the UI rules into a consuming project's repository root, install [`rulesync`](https://github.com/dyoshikawa/rulesync) (`^8.15.0`) in that project, then run the executable bundled with `@povio/ui`:
 
 ```bash
-npx povio-ui-rules
+bunx --package @povio/ui povio-ui-rules
 ```
 
-This generates the relevant Cursor, Claude Code, and Codex CLI files in the consuming repository. Add generated files to that repository's `.gitignore` unless they are intentionally versioned. Re-run the command after upgrading `@povio/ui`; verify without writing files by adding `--check` (for example, `pnpm exec povio-ui-rules --check`).
+This generates the relevant Cursor, Claude Code, and Codex CLI files in the consuming repository. Add generated files to that repository's `.gitignore` unless they are intentionally versioned. Re-run the command after upgrading `@povio/ui`; verify without writing files by adding `--check` (for example, `bunx --package @povio/ui povio-ui-rules --check`).
 
-Within this monorepo, the equivalent package-local commands are `pnpm --filter @povio/ui rules:gen` and `pnpm --filter @povio/ui rules:check`.
+Within this monorepo, the equivalent package-local commands are `bun run --filter @povio/ui rules:gen` and `bun run --filter @povio/ui rules:check`.
 
 ## Publishing
 
@@ -130,9 +146,9 @@ We also use a custom tailwind plugin to shorten some selectors inside the @povio
 @plugin "@povio/ui/tw-ui-plugin";
 ```
 
-### Background tint utility
+### State color utilities
 
-Import the color utilities in your application's Tailwind stylesheet. This import is required because `@povio/ui` button styles use these utilities:
+Import the color utilities in your application's Tailwind stylesheet. This import is required because `@povio/ui` components use these utilities:
 
 ```css
 @import "tailwindcss";
@@ -140,18 +156,39 @@ Import the color utilities in your application's Tailwind stylesheet. This impor
 @import "@povio/ui/color-utilities";
 ```
 
-Use `bg-tint-<color>/<percentage>` to mix a theme color with white in sRGB. The color name resolves to your theme's `--color-<color>` token. The required modifier is an integer from `0` to `100`: `/80` keeps 80% of the original color and adds 20% white, `/100` keeps the original color, and `/0` produces white. Lower numbers produce lighter tints.
+Use `bg-state-<color>/<state>`, `border-state-<color>/<state>`, `border-b-state-<color>/<state>`, or `text-state-<color>/<state>` to mix a theme color with a named state color in sRGB. The color resolves to `--color-<color>`. For each state, define `--states-<state>-color` and `--states-<state>-opacity` in the light and dark themes, then expose them as `--state-color-<state>` and `--state-opacity-<state>` in `@theme inline`. The theme export supplies these aliases, so additional state names require no change to the utilities.
 
 ```tsx
 <button
   type="button"
-  className="bg-interactive-primary-background text-interactive-primary-foreground hover:bg-tint-interactive-primary-background/80"
+  className="bg-interactive-primary-background border-interactive-primary-background text-interactive-primary-foreground hover:bg-state-interactive-primary-background/hover hover:border-state-interactive-primary-background/hover"
 >
-  Hover to lighten
+  Hover to change state color
 </button>
 ```
 
-The utility supports standard Tailwind variants such as `hover:`, `focus-visible:`, and `dark:`. With an opaque starting color, the result remains fully opaque and does not depend on the background behind the element. This differs from the standard `bg-<color>/80` opacity modifier. It mixes with white rather than adjusting OKLCH lightness, and only changes the background color; text and children are unaffected.
+The utilities support standard Tailwind variants such as `hover:`, `focus-visible:`, and `dark:`. With an opaque starting color and state mix color, the result remains opaque. Using the same base color and state for background and border gives them exactly the same result. The state mix color can be white, black, or another color supplied by the theme.
+
+### Icon slots
+
+`IconSlot` reserves the Figma `icons-size` spacing token (`--spacing-icons-size`, exposed as `size-icons-size`) and centers an SVG at 80% of that size. Buttons and input icon props use it automatically, whether you pass a component reference or an element. Export this token in your Tailwind theme alongside the other Figma spacing tokens.
+
+```tsx
+import { Plus } from "lucide-react";
+import { IconSlot } from "@povio/ui/icon-slot";
+
+<IconSlot icon={Plus} />;
+<IconSlot
+  icon={<Plus strokeWidth={1.5} />}
+  scale={0.8}
+/>;
+```
+
+`IconSlot` is also exported from `@povio/ui`, `@povio/ui/rhf`, `@povio/ui/tanstack`, and `@povio/ui/icons`. `className` styles the outer slot; `iconClassName` styles the SVG. The slot controls SVG dimensions, including supplied SVGs with their own size classes. Use the inherited CSS variable `--icons-scale` to change the default ratio throughout a theme, or `scale` to override one slot. A 20px token at `0.8` produces a 16px SVG; a 24px token produces a 19.2px SVG. Stroke width continues to follow the icon's own configuration.
+
+Override the shared recipe through `UIOverrides` at `iconSlot.cva`. Component-specific icon recipes, such as `button.iconSize`, now style the outer slot. An explicitly configured slot passed to a button or input keeps its configuration without nesting another slot.
+
+Storybook's **UI / Components / Icons / IconSlot** page includes a playground, raw-versus-slotted comparisons, and button/input examples. Adjust `tokenSize` and `scale` in Controls and enable slot outlines to compare against the Figma frame at 100% browser zoom.
 
 ### Z-Index
 
@@ -231,3 +268,51 @@ We're using a helper class for flex, so make sure to add this into your base css
   flex: 1 0 0;
 }
 ```
+
+## App canvas page (`/_canvas`)
+
+From RC.9, Povio UI includes a ready-made page for inspecting all your TanStack Router pages. Install `@povio/ui@5.0.0-rc.9` and retain your application's existing `@tanstack/react-router` dependency (an optional peer for this integration).
+
+For file-based routing, create `src/routes/[_]canvas.tsx` (or use your configured routes directory). The brackets escape TanStack's pathless-layout underscore convention:
+
+```tsx
+import "@povio/ui/app-canvas/styles";
+import { appCanvasRouteOptions } from "@povio/ui/app-canvas/tanstack";
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/_canvas")(appCanvasRouteOptions({ enabled: import.meta.env.DEV }));
+```
+
+Mount `AppCanvasBridge` once beneath the existing router and `UIConfigurationProvider`, alongside the root `Outlet`. The provider must be shared by the canvas route and the normal application pages; keep its existing theme defaults and persistence. If the app does not yet have this provider, add one using `parseThemeCss` on its theme source.
+
+```tsx
+import { isAppCanvasFrame } from "@povio/ui/app-canvas";
+import { AppCanvasBridge, useIsAppCanvasPage } from "@povio/ui/app-canvas/tanstack";
+
+// Inside the app's root component, under its UIConfigurationProvider:
+const canvasPage = useIsAppCanvasPage();
+return (
+  <>
+    <AppCanvasBridge />
+    <Outlet />
+    {!canvasPage && !isAppCanvasFrame() && <ExistingConfigurationLauncher />}
+  </>
+);
+```
+
+`ExistingConfigurationLauncher` represents your existing launcher/editor, if any. Do not render a second `UIConfigurationModal` on `/_canvas`: the supplied page includes its own draggable editor. Keep app-specific debug overlays out of canvas frames too.
+
+For code-based routing, add the package route to the existing root's children **before** creating the router:
+
+```tsx
+import "@povio/ui/app-canvas/styles";
+import { createAppCanvasRoute } from "@povio/ui/app-canvas/tanstack";
+const canvasRoute = createAppCanvasRoute({
+  getParentRoute: () => rootRoute,
+  enabled: import.meta.env.DEV,
+  canvas: { examples: { "/projects/$projectId": { params: { projectId: "example-id" } } } },
+});
+const routeTree = rootRoute.addChildren([homeRoute, projectsRoute, canvasRoute]);
+```
+
+Then open `/_canvas` directly. `enabled` accepts a boolean or a synchronous predicate; false produces a not-found route. Apply your existing access policy if enabling it outside development. Normal page authentication and loaders still run inside the frames. The canvas excludes its own pathname, and dynamic pages without example parameters remain explicitly unresolved. The lower-level `AppCanvasPage` and `AppCanvas` components remain available from `@povio/ui/app-canvas` for custom integrations.

package/dist/{Accordion-CzFKi8Bp.js → Accordion-BzwO4_ml.js}

@@ -1,12 +1,15 @@
 import { t as ChevronDown } from "./chevron-down-B4Pr8bD3.js";
 import { t as clsx } from "./clsx-CnD0nOiA.js";
+import { t as UIOverrides } from "./uiOverrides.context-BTCH9y5a.js";
+import { t as IconSlot } from "./IconSlot-DSK7qNxc.js";
 import { n as $7230ffa83bc0c2cf$export$29f1550f4b0d4415, o as $7230ffa83bc0c2cf$export$c62b8e45d58ddad9, r as $7230ffa83bc0c2cf$export$4d86445c2cf5e3, s as $7230ffa83bc0c2cf$export$df3a06d6289f983e, t as $7230ffa83bc0c2cf$export$2881499e37b75b9a } from "./utils-Czcqspm7.js";
 import { n as $7705c033048f6da7$export$353f5b6fc5456de1, t as $7705c033048f6da7$export$24d547caef80ccd1 } from "./Button-D6KlWSFL.js";
 import { t as $2ec61d1d4f780267$export$a8a3e93435678ff9 } from "./Heading-nI1_VOaE.js";
-import { t as UIOverrides } from "./uiOverrides.context-Bfm2n-n8.js";
-import { t as Typography } from "./Typography-B0Gp1lpc.js";
+import { t as Typography } from "./Typography-LU4z2pR1.js";
+import { a as accordionHeadingTitleDefinition, c as accordionPanelContentDefinition, i as accordionHeadingSubtitleDefinition, l as accordionPanelDefinition, n as accordionDefinition, o as accordionIconDefinition, r as accordionHeadingDefinition, s as accordionItemDefinition, t as accordionChevronDefinition, u as accordionTriggerDefinition } from "./accordion.cva-CL1bVscW.js";
 import $ahdqC$react, { createContext, forwardRef, useContext } from "react";
 import { c } from "react/compiler-runtime";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { mergeProps } from "react-aria/mergeProps";
 import { mergeRefs } from "react-aria/mergeRefs";
 import { filterDOMProps } from "react-aria/filterDOMProps";
@@ -15,7 +18,6 @@ import { useId as useId$1 } from "react-aria/useId";
 import { useDisclosure } from "react-aria/useDisclosure";
 import { useDisclosureGroupState } from "react-stately/useDisclosureGroupState";
 import { useDisclosureState } from "react-stately/useDisclosureState";
-import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region ../../node_modules/.bun/react-aria-components@1.21.1+67f6792bdf102c28/node_modules/react-aria-components/dist/private/Disclosure.mjs
 const $a3e16eab0ea4036c$export$1d40e3e0cc4d5de = /*#__PURE__*/ createContext(null);
 const $a3e16eab0ea4036c$export$944aceb4f8c89f10 = /*#__PURE__*/ forwardRef(function DisclosureGroup(props, ref) {
@@ -113,133 +115,6 @@ const $a3e16eab0ea4036c$export$feabaa331e1d464c = /*#__PURE__*/ forwardRef(funct
 	}, /*#__PURE__*/ $ahdqC$react.createElement($7230ffa83bc0c2cf$export$2881499e37b75b9a, { values: [[$7705c033048f6da7$export$24d547caef80ccd1, null]] }, props.children));
 });
 //#endregion
-//#region src/components/navigation/Accordion/accordion.cva.ts
-const accordionDefinition = UIOverrides.defineConfig({
-	base: ["flex w-full flex-col"],
-	config: {
-		variants: {
-			variant: {
-				filled: "gap-1",
-				outlined: ""
-			},
-			singleItem: {
-				true: "",
-				false: ""
-			}
-		},
-		defaultVariants: {
-			variant: "filled",
-			singleItem: false
-		},
-		compoundVariants: [{
-			variant: "outlined",
-			singleItem: false,
-			className: "rounded-global-rounding-s border border-border-default-subtle"
-		}]
-	}
-});
-const accordionItemDefinition = UIOverrides.defineConfig({
-	base: ["flex w-full flex-col"],
-	config: {
-		variants: {
-			variant: {
-				filled: "rounded-accordion-rounding-filled bg-surface-default-background",
-				outlined: ""
-			},
-			singleItem: {
-				true: "",
-				false: ""
-			}
-		},
-		defaultVariants: {
-			variant: "filled",
-			singleItem: false
-		},
-		compoundVariants: [{
-			singleItem: true,
-			variant: "outlined",
-			className: "border-border-default-subtle border-b"
-		}, {
-			singleItem: false,
-			variant: "outlined",
-			className: "not-last:border-border-default-subtle not-last:border-b"
-		}]
-	}
-});
-const accordionTriggerDefinition = UIOverrides.defineConfig({
-	base: [
-		"group flex w-full items-center gap-accordion-gap-content-to-arrow",
-		"px-accordion-side-accordion py-accordion-height-accordion",
-		"outline-none focus-visible:ring-2 focus-visible:ring-interactive-ring"
-	],
-	config: {
-		variants: {
-			variant: {
-				outlined: "rounded-accordion-rounding-outlined hover:bg-tint-surface-default-popover/80",
-				filled: "rounded-accordion-rounding-filled bg-surface-default-background hover:bg-tint-surface-default-popover/80"
-			},
-			actionPosition: {
-				left: "flex-row-reverse",
-				right: "flex-row"
-			},
-			disabled: { true: "opacity-50" }
-		},
-		defaultVariants: {
-			variant: "filled",
-			actionPosition: "right"
-		}
-	}
-});
-const accordionHeadingDefinition = UIOverrides.defineConfig({
-	base: ["flex flex-1 items-center justify-between gap-accordion-gap-content-to-arrow"],
-	config: {
-		variants: {},
-		defaultVariants: {}
-	}
-});
-const accordionHeadingTitleDefinition = UIOverrides.defineConfig({
-	base: ["flex-1 text-left text-surface-default-card-foreground"],
-	config: {
-		variants: {},
-		defaultVariants: {}
-	}
-});
-const accordionHeadingSubtitleDefinition = UIOverrides.defineConfig({
-	base: ["flex-1 text-left text-surface-default-foreground"],
-	config: {
-		variants: {},
-		defaultVariants: {}
-	}
-});
-const accordionChevronDefinition = UIOverrides.defineConfig({
-	base: ["size-6 shrink-0 text-surface-default-popover-foreground transition-transform duration-200"],
-	config: {
-		variants: { isExpanded: {
-			true: "rotate-180",
-			false: "rotate-0"
-		} },
-		defaultVariants: { isExpanded: false }
-	}
-});
-const accordionIconDefinition = UIOverrides.defineConfig({
-	base: ["size-6 shrink-0 text-surface-default-popover-foreground"],
-	config: {
-		variants: {},
-		defaultVariants: {}
-	}
-});
-const accordionPanelDefinition = UIOverrides.defineConfig({
-	base: [""],
-	config: { variants: { isExpanded: { true: "px-accordion-side-accordion pt-0 pb-accordion-height-accordion" } } }
-});
-const accordionPanelContentDefinition = UIOverrides.defineConfig({
-	base: ["py-accordion-height-content"],
-	config: {
-		variants: {},
-		defaultVariants: {}
-	}
-});
-//#endregion
 //#region src/components/navigation/Accordion/AccordionItem.tsx
 const AccordionItem = (t0) => {
 	const $ = c(25);
@@ -282,7 +157,10 @@ const AccordionItem = (t0) => {
 					children: /* @__PURE__ */ jsxs("div", {
 						className: "flex flex-1 items-center gap-accordion-gap-icon-to-text",
 						children: [
-							Icon && /* @__PURE__ */ jsx(Icon, { className: iconCva({}) }),
+							Icon && /* @__PURE__ */ jsx(IconSlot, {
+								icon: Icon,
+								className: iconCva({})
+							}),
 							/* @__PURE__ */ jsx(Typography, {
 								size: "small",
 								className: headingTitleCva({}),
@@ -295,12 +173,18 @@ const AccordionItem = (t0) => {
 							})
 						]
 					})
-				}), /* @__PURE__ */ jsx(ChevronDown, { className: chevronCva({ isExpanded }) })]
+				}), /* @__PURE__ */ jsx(IconSlot, {
+					icon: ChevronDown,
+					className: chevronCva({ isExpanded })
+				})]
 			}) }), /* @__PURE__ */ jsx($a3e16eab0ea4036c$export$feabaa331e1d464c, {
-				className: panelCva({ isExpanded }),
+				className: clsx("h-(--disclosure-panel-height) overflow-clip transition-[height,opacity] duration-200 ease-out motion-reduce:transition-none", isExpanded ? "opacity-100" : "opacity-0"),
 				children: /* @__PURE__ */ jsx("div", {
-					className: panelContentCva({}),
-					children
+					className: panelCva({ isExpanded }),
+					children: /* @__PURE__ */ jsx("div", {
+						className: panelContentCva({}),
+						children
+					})
 				})
 			})] });
 		};
@@ -411,4 +295,4 @@ const Accordion = (t0) => {
 	return t7;
 };
 //#endregion
-export { accordionHeadingSubtitleDefinition as a, accordionItemDefinition as c, accordionTriggerDefinition as d, accordionHeadingDefinition as i, accordionPanelContentDefinition as l, accordionChevronDefinition as n, accordionHeadingTitleDefinition as o, accordionDefinition as r, accordionIconDefinition as s, Accordion as t, accordionPanelDefinition as u };
+export { Accordion as t };