@chromvoid/uikit 0.1.0 → 0.2.0

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@chromvoid/uikit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Thin Lit UI kit on top of @chromvoid/headless-ui",
   "homepage": "https://github.com/chromvoid/uikit#readme",
   "bugs": {
     "url": "https://github.com/chromvoid/uikit/issues"
   },
-  "license": "AGPL-3.0-only",
+  "license": "MIT",
   "author": "ChromVoid Team",
   "repository": {
     "type": "git",
@@ -98,6 +98,10 @@
     "access": "public"
   },
   "scripts": {
+    "generate:uno": "node ./scripts/generate-uno-inline.mjs",
+    "prebuild": "npm run generate:uno",
+    "pretest:unit": "npm run generate:uno",
+    "prelint": "npm run generate:uno",
     "build": "rm -rf dist && tsc -p tsconfig.build.json && node ./scripts/postbuild.mjs",
     "check:bundle": "npm run build && node ./scripts/check-bundle-contract.mjs",
     "check:entry-imports": "node ./scripts/check-entry-imports.mjs",
@@ -120,8 +124,8 @@
     "test:unit": "vitest run --config ./vitest.config.ts"
   },
   "dependencies": {
-    "@chromvoid/headless-ui": "0.1.1",
-    "@reatom/core": "^1000.15.0"
+    "@chromvoid/headless-ui": "0.2.0",
+    "@reatom/core": "^1001.0.0"
   },
   "devDependencies": {
     "@types/node": "^24.11.0",
@@ -131,7 +135,7 @@
     "lit": "^3.3.1",
     "oxfmt": "^0.41.0",
     "oxlint": "^1.51.0",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.2",
     "unocss": "^66.6.7",
     "vite": "^7.1.0",
     "vitepress": "^1.6.3",

package/specs/components/bottom-sheet.md

@@ -0,0 +1,93 @@
+# cv-bottom-sheet
+
+Mobile modal sheet primitive that reuses `cv-dialog` for modal state, focus management, scroll lock, backdrop dismissal, Escape handling, and lifecycle events.
+
+## Usage
+
+```html
+<cv-bottom-sheet open no-header>
+  <span slot="title">Player</span>
+  <div>Sheet content</div>
+</cv-bottom-sheet>
+```
+
+## Anatomy
+
+```
+<cv-bottom-sheet> (host)
+└── <cv-dialog exportparts="...">
+    └── <button part="handle">
+        └── <span part="grabber">
+    └── <slot>
+```
+
+The underlying dialog exports `trigger`, `overlay`, `content`, `header`, `title`, `description`, `header-close`, `body`, and `footer` parts. `cv-bottom-sheet` adds `handle` and `grabber`.
+
+## Attributes
+
+| Attribute                  | Type    | Default        | Description                                                |
+| -------------------------- | ------- | -------------- | ---------------------------------------------------------- |
+| `open`                     | Boolean | `false`        | Whether the sheet is visible                               |
+| `modal`                    | Boolean | `true`         | Enables dialog modal behavior                              |
+| `type`                     | String  | `"dialog"`     | ARIA role type: `dialog` \| `alertdialog`                  |
+| `close-on-escape`          | Boolean | `true`         | Whether Escape closes the sheet                            |
+| `close-on-outside-pointer` | Boolean | `true`         | Whether backdrop pointer/click closes the sheet            |
+| `close-on-outside-focus`   | Boolean | `true`         | Whether outside focus closes the sheet                     |
+| `initial-focus-id`         | String  | ---            | Id of element to focus when the sheet opens                |
+| `no-header`                | Boolean | `false`        | Hides the dialog header                                    |
+| `show-handle`              | Boolean | `true`         | Renders the drag affordance                                |
+| `drag-to-close`            | Boolean | `true`         | Enables pull-down close from the handle                    |
+| `detents`                  | String  | `""`           | Space/comma-separated detents: `collapsed middle expanded` |
+| `detent`                   | String  | `expanded`     | Active detent: `collapsed` \| `middle` \| `expanded`       |
+| `handle-label`             | String  | `Resize sheet` | Accessible label for the handle button                     |
+
+## Slots
+
+| Slot           | Description                                     |
+| -------------- | ----------------------------------------------- |
+| `(default)`    | Sheet body content                              |
+| `title`        | Accessible title forwarded to `cv-dialog`       |
+| `description`  | Accessible description forwarded to `cv-dialog` |
+| `header-close` | Header close icon forwarded to `cv-dialog`      |
+| `footer`       | Footer content forwarded to `cv-dialog`         |
+
+## CSS Custom Properties
+
+| Property                             | Default                           | Description                      |
+| ------------------------------------ | --------------------------------- | -------------------------------- |
+| `--cv-bottom-sheet-z-index`          | `40`                              | Overlay stack level              |
+| `--cv-bottom-sheet-width`            | `100%`                            | Sheet inline size                |
+| `--cv-bottom-sheet-max-width`        | `100%`                            | Sheet maximum inline size        |
+| `--cv-bottom-sheet-max-height`       | `min(82dvh, calc(100dvh - 32px))` | Sheet maximum block size         |
+| `--cv-bottom-sheet-collapsed-height` | `148px`                           | Collapsed detent height          |
+| `--cv-bottom-sheet-middle-height`    | `min(52dvh, 440px)`               | Middle detent height             |
+| `--cv-bottom-sheet-expanded-height`  | `min(92dvh, calc(100dvh - 32px))` | Expanded detent height           |
+| `--cv-bottom-sheet-overlay-color`    | `var(--cv-color-overlay)`         | Backdrop color                   |
+| `--cv-bottom-sheet-border-radius`    | top corners rounded               | Sheet corner radius              |
+| `--cv-bottom-sheet-grabber-color`    | `var(--cv-color-border-strong)`   | Grabber color                    |
+| `--cv-bottom-sheet-dismiss-duration` | `180ms`                           | Drag dismiss transition duration |
+
+When available, the app-level `--visual-viewport-block-size` token supplies the visible viewport
+height used for sheet sizing while software keyboards are open. Keyboard clearance still flows
+through `--cv-bottom-sheet-keyboard-inset` / `--visual-viewport-bottom-inset`.
+
+`cv-bottom-sheet` composes with `cv-dialog` presence state by overriding dialog content motion variables. The sheet uses bottom-up `translateY(...)` transforms for open, close, drag, detent, and dismiss states instead of the centered dialog scale transform.
+
+## Events
+
+Matches `cv-dialog`: `cv-input`, `cv-change`, `cv-show`, `cv-after-show`, `cv-hide`, and `cv-after-hide`.
+
+`cv-after-show` and `cv-after-hide` follow the underlying `cv-dialog` presence transition. Reduced-motion and zero-duration paths complete immediately.
+
+`cv-input` and `cv-change` fire for dialog user interactions, successful drag-to-close, and user-driven detent changes. Programmatic `open` / `detent` changes do not emit input/change.
+
+When `detents` is set, event detail is `{open, detent}`. In default open-close mode, event detail remains `{open}`.
+
+## Interaction Rules
+
+- Backdrop pointer/click and Escape are delegated to `cv-dialog`.
+- Drag starts only from `part="handle"`.
+- Without `detents`, drag closes at `96px` downward movement or `0.75px/ms` downward velocity.
+- With `detents`, upward/downward drags snap one detent at a time; dragging down from the smallest detent dismisses when `drag-to-close` is enabled.
+- Tapping the handle advances to the next larger detent when one exists.
+- Below-threshold drags snap back without changing `open` or `detent`.

package/specs/components/button.md

@@ -27,6 +27,7 @@ Interactive element that triggers an action or toggles a pressed state.
 | `pressed`  | Boolean | `false`     | Pressed state (only meaningful when `toggle` is `true`)       |
 | `loading`  | Boolean | `false`     | Shows spinner and blocks interaction                          |
 | `variant`  | String  | `"default"` | Visual variant: `default` \| `primary` \| `danger` \| `ghost` |
+| `preset`   | String  | —           | Semantic preset: `action-primary` \| `action-primary-subtle`  |
 | `outline`  | Boolean | `false`     | Outlined appearance (transparent background, visible border)  |
 | `pill`     | Boolean | `false`     | Fully rounded edges (`border-radius: 999px`)                  |
 | `size`     | String  | `"medium"`  | Size: `small` \| `medium` \| `large`                          |
@@ -53,6 +54,13 @@ Interactive element that triggers an action or toggles a pressed state.
 
 The `outline` boolean modifier can be combined with any variant to produce an outlined appearance (transparent background, visible border tinted by variant color).
 
+## Presets
+
+| Preset                  | Description                                           |
+| ----------------------- | ----------------------------------------------------- |
+| `action-primary`        | Strong primary action surface for form/footer actions |
+| `action-primary-subtle` | Softer primary action surface for inline edit actions |
+
 ## Sizes
 
 | Size     | `--cv-button-min-height` | `--cv-button-padding-inline` | `--cv-button-padding-block` | `--cv-button-font-size`          |

package/specs/components/callout.md

@@ -21,6 +21,7 @@ Static supplementary content block that highlights important information using `
 | Attribute  | Type    | Default  | Description                                                                         |
 | ---------- | ------- | -------- | ----------------------------------------------------------------------------------- |
 | `variant`  | String  | `"info"` | Visual variant: `"info"` \| `"success"` \| `"warning"` \| `"danger"` \| `"neutral"` |
+| `density`  | String  | —        | Density preset: `compact` \| `dense`                                                |
 | `closable` | Boolean | `false`  | Renders a dismiss button and enables the `cv-close` event                           |
 | `open`     | Boolean | `true`   | Controls visibility of the callout                                                  |
 
@@ -34,6 +35,13 @@ Static supplementary content block that highlights important information using `
 | `danger`  | Danger-tinted background and border using `--cv-color-danger`   |
 | `neutral` | Muted style with surface background and border                  |
 
+## Densities
+
+| Density   | Description                                     |
+| --------- | ----------------------------------------------- |
+| `compact` | Reduced padding/radius for route-level callouts |
+| `dense`   | Smallest density for status and inline callouts |
+
 ## Slots
 
 | Slot        | Description                                    |

package/specs/components/copy-button.md

@@ -20,12 +20,23 @@ Button that copies a value to the system clipboard with three-state visual feedb
 
 ## Attributes
 
-| Attribute           | Type    | Default    | Description                                                                                                                                      |
-| ------------------- | ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `value`             | String  | `''`       | Text to copy. Property also accepts `(() => Promise<string>)` for lazy/sensitive values (property-only, not reflected as attribute for security) |
-| `disabled`          | Boolean | `false`    | Prevents interaction                                                                                                                             |
-| `feedback-duration` | Number  | `1500`     | Milliseconds to show success/error feedback before reverting to idle                                                                             |
-| `size`              | String  | `"medium"` | Size: `small` \| `medium` \| `large`                                                                                                             |
+| Attribute           | Type    | Default         | Description                                                                                                                                      |
+| ------------------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `value`             | String  | `''`            | Text to copy. Property also accepts `(() => Promise<string>)` for lazy/sensitive values (property-only, not reflected as attribute for security) |
+| `disabled`          | Boolean | `false`         | Prevents interaction                                                                                                                             |
+| `feedback-duration` | Number  | `1500`          | Milliseconds to show success/error feedback before reverting to idle                                                                             |
+| `size`              | String  | `"medium"`      | Size: `small` \| `medium` \| `large`                                                                                                             |
+| `appearance`        | String  | `"default"`     | Appearance: `default` \| `plain`                                                                                                                 |
+| `success-label`     | String  | `"Copied"`      | Text used for success `aria-label` and live-region feedback                                                                                      |
+| `error-label`       | String  | `"Copy failed"` | Text used for error `aria-label` and live-region feedback                                                                                        |
+| `aria-label`        | String  | unset           | Accessible label used while idle                                                                                                                 |
+
+Property-only options:
+
+| Property    | Type                                         | Description                                                                               |
+| ----------- | -------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `value`     | `string \| (() => Promise<string>)`          | Text or async getter to copy; never reflected as an attribute                             |
+| `clipboard` | `{ writeText(text: string): Promise<void> }` | Injectable clipboard adapter for app-specific clipboard policies such as domain auto-wipe |
 
 ## Sizes
 
@@ -55,12 +66,23 @@ Button that copies a value to the system clipboard with three-state visual feedb
 
 ## CSS Custom Properties
 
-| Property                         | Default                            | Description                            |
-| -------------------------------- | ---------------------------------- | -------------------------------------- |
-| `--cv-copy-button-size`          | `36px`                             | Overall button size (width and height) |
-| `--cv-copy-button-border-radius` | `var(--cv-radius-sm, 6px)`         | Border radius for button shape         |
-| `--cv-copy-button-success-color` | `var(--cv-color-success, #4ade80)` | Color applied during success state     |
-| `--cv-copy-button-error-color`   | `var(--cv-color-danger, #ff7d86)`  | Color applied during error state       |
+| Property                                    | Default                               | Description                            |
+| ------------------------------------------- | ------------------------------------- | -------------------------------------- |
+| `--cv-copy-button-size`                     | `36px`                                | Overall button size (width and height) |
+| `--cv-copy-button-border-radius`            | `var(--cv-radius-sm, 6px)`            | Border radius for button shape         |
+| `--cv-copy-button-success-color`            | `var(--cv-color-success, #4ade80)`    | Color applied during success state     |
+| `--cv-copy-button-error-color`              | `var(--cv-color-danger, #ff7d86)`     | Color applied during error state       |
+| `--cv-copy-button-background`               | `var(--cv-color-surface)`             | Base background                        |
+| `--cv-copy-button-border-color`             | `var(--cv-color-border)`              | Base border color                      |
+| `--cv-copy-button-color`                    | `var(--cv-color-text)`                | Base text/icon color                   |
+| `--cv-copy-button-hover-background`         | `--cv-copy-button-background`         | Hover background                       |
+| `--cv-copy-button-hover-border-color`       | `var(--cv-color-primary)`             | Hover border color                     |
+| `--cv-copy-button-hover-color`              | `--cv-copy-button-color`              | Hover text/icon color                  |
+| `--cv-copy-button-plain-background`         | `transparent`                         | Plain appearance background            |
+| `--cv-copy-button-plain-border-color`       | `transparent`                         | Plain appearance border                |
+| `--cv-copy-button-plain-hover-background`   | `--cv-copy-button-hover-background`   | Plain hover background                 |
+| `--cv-copy-button-plain-hover-border-color` | `--cv-copy-button-plain-border-color` | Plain hover border                     |
+| `--cv-copy-button-plain-hover-color`        | `--cv-copy-button-hover-color`        | Plain hover text/icon color            |
 
 Additionally, component styles depend on theme tokens through fallback values:
 
@@ -93,11 +115,15 @@ Additionally, component styles depend on theme tokens through fallback values:
 
 ### UIKit properties to headless actions
 
-| UIKit Property      | Direction      | Headless Binding                     |
-| ------------------- | -------------- | ------------------------------------ |
-| `disabled`          | attr -> action | `actions.setDisabled(value)`         |
-| `feedback-duration` | attr -> action | `actions.setFeedbackDuration(value)` |
-| `value`             | prop -> action | `actions.setValue(value)`            |
+| UIKit Property      | Direction            | Headless Binding                                    |
+| ------------------- | -------------------- | --------------------------------------------------- |
+| `disabled`          | attr -> action       | `actions.setDisabled(value)`                        |
+| `feedback-duration` | attr -> action       | `actions.setFeedbackDuration(value)`                |
+| `value`             | prop -> action       | `actions.setValue(value)`                           |
+| `clipboard`         | prop -> model option | Recreates the model with the injected adapter       |
+| `aria-label`        | attr -> model option | Recreates the model with the idle label             |
+| `success-label`     | attr -> model option | Recreates the model with localized success feedback |
+| `error-label`       | attr -> model option | Recreates the model with localized error feedback   |
 
 ### Headless state to DOM reflection
 
@@ -125,12 +151,16 @@ Additionally, component styles depend on theme tokens through fallback values:
 | `feedback-duration` | `feedbackDuration` | Numeric attribute, defaults to `1500`                      |
 | `disabled`          | `isDisabled`       | Boolean attribute                                          |
 | `aria-label`        | `ariaLabel`        | Standard ARIA labeling                                     |
+| `success-label`     | `successLabel`     | Localized success feedback label                           |
+| `error-label`       | `errorLabel`       | Localized error feedback label                             |
+| `clipboard`         | `clipboard`        | Property-only injectable clipboard adapter                 |
 
 ### UIKit-only concerns (not in headless)
 
 - Icon rendering via slotted content (`copy-icon`, `success-icon`, `error-icon` slots with default SVG icons)
 - CSS custom properties for sizing and colors (`--cv-copy-button-*`)
 - `size` attribute controlling icon/button dimensions
+- `appearance` attribute controlling default or plain visual treatment
 - `cv-copy` and `cv-error` custom events dispatched on the host element
 - Pulse/scale animation on copy activation
 
@@ -170,6 +200,13 @@ Events are dispatched by the UIKit adapter by providing `onCopy` and `onError` c
 <!-- Custom feedback duration (3 seconds) -->
 <cv-copy-button value="hello" feedback-duration="3000"></cv-copy-button>
 
+<!-- Domain-specific clipboard adapter and localized feedback -->
+<cv-copy-button
+  aria-label="Copy password"
+  success-label="Copied"
+  error-label="Failed to copy"
+></cv-copy-button>
+
 <!-- Custom icons via slots -->
 <cv-copy-button value="hello">
   <svg

package/specs/components/dialog.md

@@ -8,21 +8,30 @@ Modal or non-modal dialog overlay for presenting focused content, confirmations,
 
 ```
 <cv-dialog> (host)
-├── <button part="trigger">
+├── <button part="trigger"> (legacy, deprecated)
 │   └── <slot name="trigger">
-└── <div part="overlay"> (hidden when closed)
-    └── <section part="content" role="dialog|alertdialog">
-        ├── <header part="header">
-        │   ├── <h2 part="title" id="...">
-        │   │   └── <slot name="title">
-        │   ├── <p part="description" id="...">
-        │   │   └── <slot name="description">
-        │   └── <button part="header-close" aria-label="Close">
-        │       └── <slot name="header-close">
-        ├── <div part="body">
-        │   └── <slot>
-        └── <footer part="footer">
-            └── <slot name="footer">
+└── modal=true:
+    └── <dialog class="portal-shell"> (top layer)
+        └── <div part="overlay">
+            └── <section part="content" role="dialog|alertdialog">
+                ├── <header part="header">
+                │   ├── <h2 part="title" id="...">
+                │   │   └── <slot name="title">
+                │   ├── <p part="description" id="...">
+                │   │   └── <slot name="description">
+                │   └── <button part="header-close" aria-label="Close">
+                │       └── <slot name="header-close">
+                ├── <div part="body">
+                │   └── <slot>
+                └── <footer part="footer">
+                    └── <slot name="footer">
+└── modal=false:
+    └── <div class="portal-shell popover-shell" popover="manual"> (top layer)
+        └── <div part="overlay">
+            └── <section part="content" role="dialog|alertdialog">
+                ├── <header part="header">
+                ├── <div part="body">
+                └── <footer part="footer">
 ```
 
 ## Attributes
@@ -40,20 +49,20 @@ Modal or non-modal dialog overlay for presenting focused content, confirmations,
 
 ## Slots
 
-| Slot           | Description                                              |
-| -------------- | -------------------------------------------------------- |
-| `(default)`    | Dialog body content                                      |
-| `trigger`      | Content for the trigger button                           |
-| `title`        | Dialog title text                                        |
-| `description`  | Description text below the title                         |
-| `header-close` | Icon content for the header close button (defaults to X) |
-| `footer`       | Footer content (action buttons, etc.)                    |
+| Slot           | Description                                               |
+| -------------- | --------------------------------------------------------- |
+| `(default)`    | Dialog body content                                       |
+| `trigger`      | Deprecated legacy content for the built-in trigger button |
+| `title`        | Dialog title text                                         |
+| `description`  | Description text below the title                          |
+| `header-close` | Icon content for the header close button (defaults to X)  |
+| `footer`       | Footer content (action buttons, etc.)                     |
 
 ## CSS Parts
 
 | Part           | Element     | Description                                                       |
 | -------------- | ----------- | ----------------------------------------------------------------- |
-| `trigger`      | `<button>`  | Trigger button that opens the dialog                              |
+| `trigger`      | `<button>`  | Deprecated built-in trigger button                                |
 | `overlay`      | `<div>`     | Backdrop/overlay container                                        |
 | `content`      | `<section>` | Dialog content panel with `role="dialog"` or `role="alertdialog"` |
 | `header`       | `<header>`  | Header area containing title, description, and close button       |
@@ -65,25 +74,36 @@ Modal or non-modal dialog overlay for presenting focused content, confirmations,
 
 ## CSS Custom Properties
 
-| Property                     | Default                                       | Description                         |
-| ---------------------------- | --------------------------------------------- | ----------------------------------- |
-| `--cv-dialog-width`          | `min(560px, calc(100vw - 32px))`              | Preferred dialog inline size        |
-| `--cv-dialog-max-height`     | `calc(100dvh - 32px)`                         | Maximum block size before scrolling |
-| `--cv-dialog-header-spacing` | `var(--cv-space-4, 16px)`                     | Header padding                      |
-| `--cv-dialog-body-spacing`   | `var(--cv-space-4, 16px)`                     | Body padding                        |
-| `--cv-dialog-footer-spacing` | `var(--cv-space-4, 16px)`                     | Footer padding                      |
-| `--cv-dialog-overlay-color`  | `color-mix(in oklab, black 56%, transparent)` | Backdrop overlay color              |
-| `--cv-dialog-border-radius`  | `var(--cv-radius-lg, 14px)`                   | Panel border radius                 |
+| Property                               | Default                                                    | Description                          |
+| -------------------------------------- | ---------------------------------------------------------- | ------------------------------------ |
+| `--cv-dialog-width`                    | `var(--cv-dialog-width-m, min(560px, calc(100vw - 32px)))` | Preferred dialog inline size         |
+| `--cv-dialog-width-s`                  | app/theme provided                                         | Standard small dialog inline size    |
+| `--cv-dialog-width-m`                  | app/theme provided                                         | Standard medium dialog inline size   |
+| `--cv-dialog-width-l`                  | app/theme provided                                         | Standard large dialog inline size    |
+| `--cv-dialog-width-xl`                 | app/theme provided                                         | Standard extra-large dialog size     |
+| `--cv-dialog-max-height`               | `calc(100dvh - 32px)`                                      | Maximum block size before scrolling  |
+| `--cv-dialog-header-spacing`           | `var(--cv-space-4, 16px)`                                  | Header padding                       |
+| `--cv-dialog-body-spacing`             | `var(--cv-space-4, 16px)`                                  | Body padding                         |
+| `--cv-dialog-footer-spacing`           | `var(--cv-space-4, 16px)`                                  | Footer padding                       |
+| `--cv-dialog-overlay-color`            | `var(--cv-color-overlay)`                                  | Backdrop overlay color               |
+| `--cv-dialog-border-radius`            | `var(--cv-radius-lg, 14px)`                                | Panel border radius                  |
+| `--cv-dialog-transition-duration`      | `var(--cv-duration-fast, 120ms)`                           | Presence transition duration         |
+| `--cv-dialog-transition-easing-open`   | `var(--cv-easing-decelerate)`                              | Opening transition easing            |
+| `--cv-dialog-transition-easing-close`  | `var(--cv-easing-accelerate)`                              | Closing transition easing            |
+| `--cv-dialog-content-closed-transform` | `translate3d(0, 8px, 0) scale(0.98)`                       | Panel transform while closed/closing |
+| `--cv-dialog-content-open-transform`   | `translate3d(0, 0, 0) scale(1)`                            | Panel transform while open           |
 
 ## Visual States
 
 | Host selector                 | Description                                           |
 | ----------------------------- | ----------------------------------------------------- |
-| `:host([open])`               | Dialog visible, overlay shown                         |
+| `:host([open])`               | Dialog logical state is open                          |
 | `:host([modal])`              | Modal mode active (focus trap, scroll lock, backdrop) |
 | `:host([type="alertdialog"])` | Alert dialog mode with `role="alertdialog"`           |
 | `:host([no-header])`          | Header section hidden                                 |
 
+The top-layer shell, overlay, and content expose `data-state="closed|opening|open|closing"` internally. The shell remains mounted during `closing` so the exit transition can finish before native dialog/popover cleanup.
+
 ## Events
 
 | Event           | Detail            | Description                                        |
@@ -97,6 +117,8 @@ Modal or non-modal dialog overlay for presenting focused content, confirmations,
 
 `cv-input` and `cv-change` fire only for user-initiated state changes (trigger click, Escape, outside pointer, outside focus, header close). Programmatic `open` attribute changes do not emit these events.
 
+`cv-after-show` and `cv-after-hide` fire after the presence transition completes. Reduced-motion and zero-duration paths complete immediately.
+
 ## Reactive State Mapping
 
 `cv-dialog` is a visual adapter over headless `createDialog`.
@@ -129,15 +151,17 @@ Modal or non-modal dialog overlay for presenting focused content, confirmations,
 - `contracts.getDescriptionProps()` is spread onto `[part="description"]` to apply the `id` for `aria-describedby`.
 - `contracts.getHeaderCloseButtonProps()` is spread onto `[part="header-close"]` to apply `role`, `tabindex`, `aria-label: 'Close'`, and click handler.
 - UIKit dispatches `cv-input` and `cv-change` events by observing `isOpen` changes triggered by user interaction (not by controlled `open` attribute changes).
-- UIKit dispatches `cv-show`/`cv-after-show`/`cv-hide`/`cv-after-hide` lifecycle events to bracket CSS transitions.
+- UIKit dispatches `cv-show`/`cv-hide` immediately and `cv-after-show`/`cv-after-hide` after presence transitions.
+- UIKit renders the visible dialog through native top-layer primitives (`<dialog>` for modal, popover root for non-modal) so it is not clipped by ancestor `overflow`, `contain`, `transform`, or `isolation`.
 - UIKit owns scroll lock implementation, focus trap implementation, focus restoration, backdrop rendering, and CSS transitions — headless provides signals, UIKit applies side effects.
+- UIKit keeps modal scroll lock and native top-layer presence active during the close transition, then restores focus after the shell has closed.
 
 ## Usage
 
 ```html
-<!-- Basic dialog -->
-<cv-dialog>
-  <span slot="trigger">Open</span>
+<!-- Controlled dialog -->
+<button type="button" onclick="dialog.open = true">Open</button>
+<cv-dialog id="dialog">
   <span slot="title">Confirm action</span>
   <span slot="description">Are you sure you want to proceed?</span>
   <p>This action cannot be undone.</p>
@@ -148,8 +172,8 @@ Modal or non-modal dialog overlay for presenting focused content, confirmations,
 </cv-dialog>
 
 <!-- Alert dialog -->
-<cv-dialog type="alertdialog">
-  <span slot="trigger">Delete</span>
+<button type="button" onclick="alertDialog.open = true">Delete</button>
+<cv-dialog id="alertDialog" type="alertdialog">
   <span slot="title">Delete item?</span>
   <span slot="description">This will permanently delete the item.</span>
   <div slot="footer">
@@ -159,15 +183,14 @@ Modal or non-modal dialog overlay for presenting focused content, confirmations,
 </cv-dialog>
 
 <!-- Non-modal dialog -->
-<cv-dialog modal="false">
-  <span slot="trigger">Show info</span>
+<button type="button" onclick="infoDialog.open = true">Show info</button>
+<cv-dialog id="infoDialog" modal="false">
   <span slot="title">Information</span>
   <p>This dialog does not block the page.</p>
 </cv-dialog>
 
 <!-- Without header -->
 <cv-dialog no-header>
-  <span slot="trigger">Quick action</span>
   <p>Minimal dialog with body content only.</p>
   <div slot="footer">
     <cv-button variant="primary">OK</cv-button>
@@ -176,9 +199,15 @@ Modal or non-modal dialog overlay for presenting focused content, confirmations,
 
 <!-- Custom header close icon -->
 <cv-dialog>
-  <span slot="trigger">Open</span>
   <span slot="title">Settings</span>
   <icon-close slot="header-close"></icon-close>
   <p>Dialog content here.</p>
 </cv-dialog>
+
+<!-- Legacy built-in trigger (deprecated) -->
+<cv-dialog>
+  <span slot="trigger">Open</span>
+  <span slot="title">Legacy trigger</span>
+  <p>Prefer external triggers with controlled .open.</p>
+</cv-dialog>
 ```

package/specs/components/drawer.md

@@ -38,6 +38,7 @@ Slide-out panel dialog anchored to a viewport edge, used for navigation, forms,
 | `close-on-outside-focus`   | Boolean | `true`     | Whether focusing outside closes the drawer                         |
 | `initial-focus-id`         | String  | ---        | Id of element to focus when drawer opens                           |
 | `no-header`                | Boolean | `false`    | Hides the header (title, description, header close button)         |
+| `drag-to-close`            | Boolean | `false`    | Enables touch drag dismissal in the drawer's closing direction     |
 
 ## Slots
 
@@ -66,19 +67,22 @@ Slide-out panel dialog anchored to a viewport edge, used for navigation, forms,
 
 ## CSS Custom Properties
 
-| Property                                  | Default                                       | Description                                                                                           |
-| ----------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `--cv-drawer-z-index`                     | `40`                                          | Z-index of the overlay layer                                                                          |
-| `--cv-drawer-size`                        | `360px`                                       | Inline size (for `start`/`end`) or block size (for `top`/`bottom`) of the panel                       |
-| `--cv-drawer-max-size`                    | `calc(100dvh - 32px)`                         | Maximum size before internal scrolling (block axis for `top`/`bottom`, inline axis for `start`/`end`) |
-| `--cv-drawer-header-spacing`              | `var(--cv-space-4, 16px)`                     | Header padding                                                                                        |
-| `--cv-drawer-body-spacing`                | `var(--cv-space-4, 16px)`                     | Body padding                                                                                          |
-| `--cv-drawer-footer-spacing`              | `var(--cv-space-4, 16px)`                     | Footer padding                                                                                        |
-| `--cv-drawer-overlay-color`               | `color-mix(in oklab, black 56%, transparent)` | Backdrop overlay color                                                                                |
-| `--cv-drawer-overlay-transition-duration` | `0ms`                                         | Overlay opacity transition duration                                                                   |
-| `--cv-drawer-overlay-closed-opacity`      | `1`                                           | Overlay opacity while the panel is animating out or before the panel animates in                      |
-| `--cv-drawer-border-radius`               | `var(--cv-radius-lg, 14px)`                   | Panel border radius (applied to the inward edge only)                                                 |
-| `--cv-drawer-transition-duration`         | `250ms`                                       | Slide transition duration                                                                             |
+| Property                                  | Default                     | Description                                                                                           |
+| ----------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `--cv-drawer-z-index`                     | `40`                        | Z-index of the overlay layer                                                                          |
+| `--cv-drawer-size`                        | `360px`                     | Inline size (for `start`/`end`) or block size (for `top`/`bottom`) of the panel                       |
+| `--cv-drawer-max-size`                    | `calc(100dvh - 32px)`       | Maximum size before internal scrolling (block axis for `top`/`bottom`, inline axis for `start`/`end`) |
+| `--cv-drawer-header-spacing`              | `var(--cv-space-4, 16px)`   | Header padding                                                                                        |
+| `--cv-drawer-body-spacing`                | `var(--cv-space-4, 16px)`   | Body padding                                                                                          |
+| `--cv-drawer-footer-spacing`              | `var(--cv-space-4, 16px)`   | Footer padding                                                                                        |
+| `--cv-drawer-overlay-color`               | `var(--cv-color-overlay)`   | Backdrop overlay color                                                                                |
+| `--cv-drawer-overlay-transition-duration` | `0ms`                       | Overlay opacity transition duration                                                                   |
+| `--cv-drawer-overlay-closed-opacity`      | `1`                         | Overlay opacity while the panel is animating out or before the panel animates in                      |
+| `--cv-drawer-border-radius`               | `var(--cv-radius-lg, 14px)` | Panel border radius (applied to the inward edge only)                                                 |
+| `--cv-drawer-transition-duration`         | `250ms`                     | Slide transition duration                                                                             |
+| `--cv-drawer-drag-offset-x`               | `0px`                       | Internal horizontal drag offset applied while touch dragging                                          |
+| `--cv-drawer-drag-offset-y`               | `0px`                       | Internal vertical drag offset applied while touch dragging                                            |
+| `--cv-drawer-drag-overlay-opacity`        | `1`                         | Internal overlay opacity applied while touch dragging                                                 |
 
 ## Visual States
 
@@ -92,6 +96,7 @@ Slide-out panel dialog anchored to a viewport edge, used for navigation, forms,
 | `:host([placement="end"])`    | Panel anchored to the inline-end edge (right in LTR, left in RTL)   |
 | `:host([placement="top"])`    | Panel anchored to the top edge                                      |
 | `:host([placement="bottom"])` | Panel anchored to the bottom edge                                   |
+| `:host([drag-to-close])`      | Touch drag dismissal is enabled                                     |
 
 ### Placement layout rules
 

package/specs/components/guidance-anchor.md

@@ -0,0 +1,64 @@
+# cv-guidance-anchor
+
+Lightweight semantic anchor wrapper for product guidance registration.
+
+`cv-guidance-anchor` is a registration primitive only. It does not render guidance UI, own guidance progress, compute eligibility, or import app-layer guidance models. The wrapper host itself is the registered target element.
+
+## Anatomy
+
+```
+<cv-guidance-anchor> (host)
+└── <slot>
+```
+
+## Attributes
+
+| Attribute   | Type   | Default | Description                                           |
+| ----------- | ------ | ------- | ----------------------------------------------------- |
+| `anchor-id` | String | `""`    | Stable semantic identifier for the UI action or area. |
+| `surface`   | String | `""`    | Product surface where the anchor is available.        |
+| `owner`     | String | `""`    | Owning feature or team metadata.                      |
+
+## Slots
+
+| Slot        | Description                                       |
+| ----------- | ------------------------------------------------- |
+| `(default)` | Action or content visually associated with anchor |
+
+## CSS Parts
+
+None.
+
+## CSS Custom Properties
+
+None. `cv-guidance-anchor` is a light wrapper with `display: contents` by default.
+
+## Visual States
+
+| Host selector     | Description                                  |
+| ----------------- | -------------------------------------------- |
+| `:host`           | Uses `display: contents` for wrapper layout. |
+| `:host([hidden])` | Hides the wrapper and its slotted content.   |
+
+## Events
+
+| Event                        | When                           | Detail                                |
+| ---------------------------- | ------------------------------ | ------------------------------------- |
+| `guidance-anchor-register`   | On connect and semantic update | `{anchorId, surface, owner, element}` |
+| `guidance-anchor-unregister` | On disconnect                  | `{anchorId, surface, owner, element}` |
+
+Both events bubble and are composed so an app-level guidance host can observe anchors across shadow boundaries. `detail.element` is always the `cv-guidance-anchor` host.
+
+## Behavior
+
+- Re-dispatches `guidance-anchor-register` when `anchor-id`, `surface`, or `owner` changes.
+- Does not query slotted children, child shadow roots, global document selectors, translated text, or coordinates.
+- Complex components whose real target is inside Shadow DOM should dispatch the same events manually with the actual `HTMLElement`.
+
+## Usage
+
+```html
+<cv-guidance-anchor anchor-id="files.create-or-upload" surface="files" owner="files">
+  <button type="button">Upload</button>
+</cv-guidance-anchor>
+```