@rogieking/figui3 6.4.6 → 6.4.7

package/.cursor/skills/a11y/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: a11y
+description: Guides accessibility review and implementation for FigUI3 web components and playground examples. Use when the user mentions accessibility, a11y, ARIA, screen readers, keyboard navigation, focus rings, labels, roles, disabled states, contrast, dialogs, menus, or form control semantics.
+---
+
+# Accessibility
+
+Use this skill when adding, reviewing, or debugging accessibility behavior in FigUI3.
+
+## Core Principles
+
+1. Preserve native semantics first. Use native controls, form labels, `button`, `input`, `dialog`, and real focus behavior where possible.
+2. Add ARIA only to complete semantics, not to replace correct markup.
+3. Keyboard support is required for every interactive component.
+4. Disabled and readonly states must affect behavior, focusability, ARIA, visuals, and emitted events consistently.
+5. Focus indicators must be visible, token-based, and match existing FigUI3 patterns.
+6. Custom elements must keep semantics stable across light/dark themes and React usage.
+
+## Implementation Checklist
+
+- Confirm the component role and accessible name.
+- Confirm keyboard entry, movement, activation, escape/cancel, and tab order.
+- Confirm focus rings on the visible interactive surface.
+- Confirm `disabled` syncs to `aria-disabled` where the element is not natively disableable.
+- Confirm disabled elements do not emit normal interaction changes.
+- Confirm `aria-*`, `role`, and `tabindex` are updated when attributes change dynamically.
+- Confirm customized built-ins like `<dialog is="fig-dialog">` and `<dialog is="fig-popup">` preserve native dialog behavior.
+- Confirm playground examples demonstrate accessible usage.
+
+## FigUI3 Patterns
+
+### Disabled custom elements
+
+For non-native interactive custom elements:
+
+```js
+const disabled =
+  this.hasAttribute("disabled") && this.getAttribute("disabled") !== "false";
+
+if (disabled) {
+  this.setAttribute("aria-disabled", "true");
+  this.setAttribute("tabindex", "-1");
+} else {
+  this.removeAttribute("aria-disabled");
+  this.setAttribute("tabindex", "0");
+}
+```
+
+If a component uses roving tabindex, keep inactive and disabled items at `tabindex="-1"`.
+
+### Focus rings
+
+Prefer existing token patterns:
+
+```css
+&:focus-visible,
+&[data-focus-visible] {
+  outline: 0;
+  box-shadow: inset 0 0 0 1px var(--figma-color-border-selected);
+}
+```
+
+If focus lands on a hidden native input, apply the ring to the visible host surface:
+
+```css
+fig-button:has(> input:focus-visible) {
+  outline: 0;
+  box-shadow: inset 0 0 0 1px var(--figma-color-border-selected);
+}
+```
+
+### Menus
+
+- Menu popups use `role="menu"`.
+- Items use `role="menuitem"`.
+- Disabled menu items should have `aria-disabled="true"` and should not be included in roving keyboard focus.
+- Arrow keys should skip disabled items.
+
+### Dialogs and popups
+
+- Use `<dialog is="fig-dialog">` for dialog workflows.
+- Use `<dialog is="fig-popup">` for anchored popup surfaces.
+- Verify close buttons have accessible names, usually `aria-label="Close dialog"`.
+- Preserve native `close`/`cancel` behavior unless intentionally overridden.
+
+## Review Output
+
+When reviewing a11y work, lead with concrete issues:
+
+- Missing or incorrect role/name/state.
+- Keyboard trap or unreachable interaction.
+- Focus ring missing on visible surface.
+- Disabled state mismatch between behavior and semantics.
+- Screen reader announcement likely misleading.
+
+Include the component and file path for each finding.

package/.cursor/skills/css-render-performance/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: css-render-performance
+description: Guides CSS rendering and layout performance tests for component UIs. Use when checking selector cost, layout thrash, paint work, animation smoothness, CSS containment, computed styles, or visual regressions caused by CSS changes.
+---
+
+# CSS Render Performance
+
+Test CSS performance in a browser with real stylesheets loaded. Pair this with `css-component-testing` when the risk is both correctness and render cost.
+
+## Performance Risks
+
+- Layout thrash from alternating DOM writes and layout reads.
+- Expensive selectors over large component trees.
+- Paint-heavy effects: filters, shadows, backdrops, gradients, large clipping, and opacity stacks.
+- Animation of layout properties instead of transform/opacity.
+- Missing containment around isolated panels, popups, lists, or preview surfaces.
+- Theme/token changes that trigger broad restyles.
+
+## Measurement Pattern
+
+1. Mount a scaled fixture: enough nodes to expose the cost, but still deterministic.
+2. Wait for styles, custom elements, and fonts to settle.
+3. Measure a single operation: class toggle, attribute change, theme switch, popup open, resize, or list update.
+4. Read layout at controlled points using `getBoundingClientRect` or computed styles.
+5. Use `requestAnimationFrame` to separate write, style/layout flush, and visual completion.
+
+## Useful Browser APIs
+
+- `performance.now()` for scoped timings.
+- `requestAnimationFrame` for frame-boundary checks.
+- `getComputedStyle` for resolved token/state assertions.
+- `getBoundingClientRect` for layout cost and final geometry.
+- `PerformanceObserver` for long tasks when supported by the browser under test.
+
+## CSS Fix Preferences
+
+- Prefer transform/opacity for motion.
+- Prefer `contain` or `content-visibility` only when it preserves layout, accessibility, and interaction behavior.
+- Prefer narrower DOM updates over broader selector work.
+- Keep selector specificity maintainable; do not trade readability for theoretical wins without measurement.
+
+## Avoid
+
+- Timing raw selector queries without the real component tree.
+- Replacing stable computed-style assertions with broad screenshots.
+- Adding CSS containment that breaks popups, focus rings, sticky positioning, or overlay geometry.

package/.cursor/skills/frontend-performance-testing/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: frontend-performance-testing
+description: Guides browser-based performance testing for HTML, CSS, JavaScript, and UI interactions. Use when measuring frontend performance, adding Playwright perf tests, checking regressions, profiling load/render/interaction cost, or discussing performance budgets.
+---
+
+# Frontend Performance Testing
+
+Use real browsers for performance checks. In this repo, prefer Playwright because `playwright.config.ts` already boots `bun server.ts` and runs against Chromium.
+
+## What To Measure
+
+- Load readiness: time to fixture boot, first usable UI, and custom element definitions.
+- Interaction latency: click, keyboard, pointer drag, slider movement, picker open/close.
+- Render cost: layout, style recalculation, paint, animation frames, and DOM update loops.
+- Bundle/build changes: output size and runtime behavior after `bun build`.
+- Regressions under scale: repeated components, large option lists, nested controls, and overlay stacks.
+
+## Test Pattern
+
+1. Mount the smallest deterministic fixture that reproduces the performance risk.
+2. Warm up once before measuring.
+3. Use browser APIs inside `page.evaluate`: `performance.now()`, `PerformanceObserver`, `requestAnimationFrame`, `getBoundingClientRect`, and `document.fonts.ready` when relevant.
+4. Repeat enough times to reduce noise; assert on median or bounded worst case, not one sample.
+5. Keep budgets local and named after the scenario, not global magic numbers.
+
+## Playwright Guidance
+
+- Put stable performance checks near `tests/figui` unless they need a separate fixture.
+- Fail on page errors and unexpected console errors before trusting timing data.
+- Use `test.slow()` for intentionally heavier regression scenarios.
+- Capture traces only for failing or investigative runs; do not turn every perf test into a trace artifact.
+- Prefer `expect.poll` for readiness, then measure a synchronous scenario.
+
+## Budget Rules
+
+- Budgets should catch meaningful regressions without flaking on normal machine variance.
+- Use relative comparisons when possible: changed implementation vs baseline path in the same page.
+- Avoid hard sub-millisecond thresholds.
+- Document what user-facing lag the budget protects.
+
+## Avoid
+
+- jsdom performance conclusions.
+- Network-dependent timing assertions.
+- Screenshot diffs as a proxy for performance.
+- Microbenchmarks that skip the actual DOM/CSS/component path.

package/.cursor/skills/js-runtime-performance/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: js-runtime-performance
+description: Guides JavaScript runtime performance testing for frontend components. Use when profiling event handlers, DOM update loops, memory leaks, timers, animation frames, pointer/keyboard interactions, or regressions in vanilla JS component code.
+---
+
+# JS Runtime Performance
+
+Measure JavaScript cost through real user-facing paths. For FigUI3, that usually means interactions on `fig-*` elements in Playwright, not isolated functions.
+
+## What To Check
+
+- Event handlers stay short during pointer drag, key repeat, input, and resize.
+- Attribute/property updates avoid redundant DOM writes.
+- Repeated mount/unmount cycles clean listeners, timers, observers, and animation frames.
+- Expensive parsing or serialization does not run on every frame.
+- Overlay and picker positioning does not do repeated forced layout work.
+- Component registration and upgrade do not block page boot unexpectedly.
+
+## Test Pattern
+
+1. Reproduce the user path with real DOM and real events.
+2. Warm up once, then measure repeated runs.
+3. Collect timings with `performance.now()` around the smallest meaningful operation.
+4. For leak risks, mount/unmount repeatedly and count retained DOM/listeners through observable public effects.
+5. Assert behavior first, then assert timing or bounded operation counts.
+
+## Instrumentation Ideas
+
+- Wrap public methods or callbacks temporarily inside `page.evaluate` to count calls.
+- Count emitted `input` and `change` events during interactions.
+- Use `requestAnimationFrame` loops to detect frame starvation.
+- Use console timing only for manual investigation; tests should return structured values to Playwright.
+
+## Fix Preferences
+
+- Batch DOM writes before layout reads.
+- Cache parsed static data, but invalidate when public attributes/properties change.
+- Prefer one listener on a stable root over many per-child listeners when behavior allows.
+- Cancel timers, observers, and frame callbacks in `disconnectedCallback`.
+
+## Avoid
+
+- Optimizing private code paths that do not affect measured UI behavior.
+- Adding debounce/throttle that changes `input` vs `change` semantics.
+- Hiding slow work behind `setTimeout` without proving user-perceived latency improves.

package/.cursor/skills/web-component-performance/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: web-component-performance
+description: Guides performance testing for native Web Components and custom elements. Use when measuring custom element registration, upgrade cost, connected/disconnected callbacks, attributeChangedCallback churn, Shadow DOM work, slots, or fig-* component scalability.
+---
+
+# Web Component Performance
+
+Measure custom element performance in real browsers. Pair this with `web-component-testing` when validating both behavior contracts and performance regressions.
+
+## Hot Paths
+
+- `customElements.define` and `customElements.whenDefined` during boot.
+- Initial upgrade of many existing elements.
+- `connectedCallback` and `disconnectedCallback` during repeated mount/unmount.
+- `attributeChangedCallback` and property setters during state sync.
+- Shadow DOM creation, slot distribution, and internal event wiring.
+- Form-style event emission during fast interactions.
+
+## Test Pattern
+
+1. Create a scaled fixture with representative `fig-*` markup.
+2. Wait for definitions, then separate upgrade timing from interaction timing.
+3. Measure repeated mount/unmount cycles for cleanup and callback cost.
+4. Stress public APIs: attributes, properties, slots, and user interactions.
+5. Assert no page errors, no console errors, correct final state, and bounded timing.
+
+## Useful Checks
+
+- Count how many times lifecycle callbacks run for one user-visible operation.
+- Verify attribute writes do not emit user interaction events unless the component contract says so.
+- Compare one component vs many components in the same page to catch nonlinear scaling.
+- Test overlay/picker components with nested popups because geometry work can multiply.
+- Confirm cleanup by removing hosts, re-adding them, and checking events are not duplicated.
+
+## Fix Preferences
+
+- Avoid rebuilding Shadow DOM when a targeted text/style/value update is enough.
+- Coalesce repeated attribute/property sync when the public contract allows it.
+- Keep event listeners stable and remove external listeners in `disconnectedCallback`.
+- Prefer public host state for tests; inspect internals only to prove a suspected performance issue.
+
+## Avoid
+
+- Measuring autonomous custom elements in jsdom.
+- Benchmarking constructors alone when the real cost is upgrade plus connected work.
+- Adding caches that make attribute/property reflection stale.
+- Changing public event timing to pass a benchmark.

package/README.md

@@ -17,6 +17,18 @@ A lightweight, zero-dependency web components library for building Figma plugin
 - Accessible with ARIA attributes and keyboard navigation
 - Framework agnostic (React, Vue, Svelte, or vanilla JS)
 
+## Accessibility Coverage
+
+FigUI3 components are built to preserve native semantics where possible and add ARIA only where custom elements need extra state or naming.
+
+- Form primitives forward accessible names and state to their native controls, including combo inputs, dropdowns, text, number, slider, checkbox, radio, switch, color, and fill inputs.
+- Selection components use standard keyboard patterns: tabs use roving focus and `aria-controls`, segmented controls expose a radio-group pattern with focus following arrow selection, choosers expose listbox/options, and menus support trigger state, item focus, Escape close, and disabled items.
+- Dialog, popup, tooltip, and toast surfaces expose names, close affordances, live-region behavior, Escape dismissal, and focus return behavior appropriate to their role.
+- Media components render their visual surface inside `fig-preview`; image/video semantics stay on the native media element, upload controls remain keyboard reachable, slotted image overlays stay in light DOM for framework ownership, and generated video controls render below the preview instead of as an overlay.
+- Display and pointer components expose useful semantics when interactive or informative: handles, chits, color tips, layers, spinners, shimmers, and skeletons sync names, busy states, disabled states, keyboard movement, inert states, or hidden states as appropriate.
+- Focus styling uses shared `--figma-focus-outline`, `--figma-focus-outline-offset`, and `--figma-focus-outline-radius` tokens so visible focus treatment stays consistent across components.
+- Component contracts include Playwright keyboard/focus coverage plus an axe smoke suite for representative form, media, overlay, selection, and loading fixtures.
+
 ## Quick Start
 
 Install:
@@ -32,7 +44,14 @@ import "@rogieking/figui3/fig.css";
 import "@rogieking/figui3/fig.js";
 ```
 
-Opt into the full Figma-style fill picker when you need it:
+Opt into `<fig-layer>` when you need collapsible layer lists:
+
+```js
+import "@rogieking/figui3/fig-layer.css";
+import "@rogieking/figui3/fig-layer.js";
+```
+
+Opt into editor components like the full Figma-style fill picker when you need them:
 
 ```js
 import "@rogieking/figui3/fig-editor.css";
@@ -94,8 +113,9 @@ Minimal example:
 | [Popup](#popup) | `<fig-popup>` | Anchored floating surface |
 | [Toast](#toast) | `<fig-toast>` | Toast notification |
 | [Tooltip](#tooltip) | `<fig-tooltip>` | Hover/click tooltip |
+| [Menu](#menu) | `<fig-menu>` | Triggered menu with keyboard navigation |
 | [Header](#header) | `<fig-header>` | Section header |
-| [Layer](#layer) | `<fig-layer>` | Collapsible layer list item |
+| [Layer](#layer) | `<fig-layer>` | Collapsible layer list item from `fig-layer.js` |
 | [Preview](#preview) | `<fig-preview>` | Thin visual preview layer |
 | [Media](#media) | `<fig-media>` | Shared media host for image/video |
 | [Image](#image) | `<fig-image>` | Image display/upload |
@@ -134,6 +154,8 @@ Minimal example:
 </fig-button>
 ```
 
+`type="select"` and `type="upload"` are visual wrappers for native select/file controls. They avoid nested native buttons, show the shared focus outline on the wrapper, and open the native picker from keyboard activation where supported.
+
 ---
 
 #### Dropdown
@@ -145,6 +167,8 @@ Minimal example:
 | `value` | string | — | Selected value |
 | `type` | string | `"select"` | `"select"` or `"dropdown"` |
 | `experimental` | string | — | Feature flags (e.g. `"modern"` for `appearance: base-select`) |
+| `label` | string | — | Accessible label for the generated native `<select>` |
+| `disabled` | boolean | `false` | Disabled state |
 
 ```html
 <fig-dropdown value="2">
@@ -153,6 +177,8 @@ Minimal example:
 </fig-dropdown>
 ```
 
+Keyboard activation follows the native select pattern. Enter opens the closed picker, and when `experimental="modern"` is open, Enter is left to the browser so the focused option commits normally.
+
 ---
 
 #### Combo Input
@@ -239,7 +265,7 @@ Minimal example:
 | Attribute | Type | Default | Description |
 |---|---|---|---|
 | `type` | string | `"range"` | `"range"`, `"hue"`, `"opacity"`, `"delta"`, `"stepper"` |
-| `value` | number | — | Current value |
+| `value` | number | midpoint for `type="range"` | Current value |
 | `min` | number | `0` | Minimum |
 | `max` | number | `100` | Maximum |
 | `step` | number | `1` | Step increment |
@@ -261,6 +287,8 @@ Minimal example:
 <fig-slider type="opacity" value="75" color="#FF5733" units="%"></fig-slider>
 ```
 
+For `type="range"`, omitting `value` follows native range behavior and starts at the midpoint of `min` and `max`. Arrow keys move by `step`; hold Shift to move by a larger step.
+
 ---
 
 #### Field Slider
@@ -467,6 +495,8 @@ An editable palette of solid colors, each rendered as a `<fig-input-color>` swat
 <fig-input-palette value='[{"color":"#FF0000","alpha":0.5},{"color":"#00FF00","alpha":1}]' open></fig-input-palette>
 ```
 
+The collapsed palette is a single tab stop. Enter or Space expands it, and focus styling uses the shared focus outline tokens on the visible swatch row.
+
 ---
 
 #### Gradient Input
@@ -516,6 +546,8 @@ A comprehensive fill input supporting solid, gradient, image, and video fills. W
 | `alpha` | boolean | `true` | Show alpha controls |
 | `picker-*` | string | — | Forwarded to `<fig-fill-picker>` when the optional picker is registered |
 
+Add `aria-label` to name the generated picker, hex field, and opacity field as one fill control group.
+
 **Events:**
 
 | Event | Detail |
@@ -572,6 +604,8 @@ Optional full fill picker dialog supporting solid, gradient, image, video, and w
 
 **Events:** `input`, `change` with selected tab value.
 
+Tabs use `role="tablist"` / `role="tab"` and roving focus. Use `content="#panel-id"` on each `<fig-tab>` to associate generated tab panels. Focus-visible tabs use the shared focus outline tokens.
+
 ```html
 <fig-tabs value="tab1">
   <fig-tab value="tab1">General</fig-tab>
@@ -594,6 +628,8 @@ Optional full fill picker dialog supporting solid, gradient, image, video, and w
 
 **Events:** `input`, `change` — detail contains the selected value.
 
+Segmented controls expose a radio-group pattern. Arrow keys, Home, and End move selection between enabled segments and move focus to the selected segment.
+
 ```html
 <fig-segmented-control>
   <fig-segment value="left" selected="true">Left</fig-segment>
@@ -658,6 +694,7 @@ A 2D position input control with optional X/Y fields.
 | `fields` | boolean | `false` | Show X/Y inputs |
 | `coordinates` | string | `"screen"` | `"screen"` (0,0 top-left) or `"math"` (0,0 bottom-left) |
 | `aspect-ratio` | string | `"1 / 1"` | Plane ratio |
+| `axis-labels` | string | — | Comma- or space-delimited labels. 1 value: top. 2 values: x y. 4 values: left right top bottom |
 
 **Events:**
 
@@ -670,6 +707,8 @@ A 2D position input control with optional X/Y fields.
 <fig-joystick value="50% 50%" fields="true" precision="2"></fig-joystick>
 ```
 
+Keyboard focus lands on the internal handle. Arrow keys move the handle and keep focus on it during interaction.
+
 ---
 
 #### Origin Grid
@@ -697,6 +736,8 @@ A transform-origin grid control with a draggable handle and optional X/Y percent
 <fig-origin-grid value="50% 50%" drag="true" fields="true"></fig-origin-grid>
 ```
 
+The internal handle uses the shared focus outline and supports Arrow, Shift+Arrow, Home, and End keyboard movement.
+
 ---
 
 #### Easing Curve
@@ -726,6 +767,8 @@ An interactive bezier or spring easing curve editor with a preset dropdown and m
 <fig-easing-curve value="spring(200, 15, 1)" edit="false"></fig-easing-curve>
 ```
 
+Editable bezier and spring handles are keyboard operable. Bezier handles keep tab order aligned with the visual handle order.
+
 ---
 
 #### 3D Rotate
@@ -798,6 +841,8 @@ A draggable handle element. Positioned on a `drag-surface` container with axis c
 </div>
 ```
 
+When `drag="true"`, focused handles support Arrow key movement, Home/End jumps, and a tokenized focus outline with a 1px offset.
+
 ---
 
 #### Canvas Control
@@ -892,6 +937,8 @@ A modal/non-modal dialog. Uses `is="fig-dialog"` on a native `<dialog>` element.
 </dialog>
 ```
 
+Dialog close paths restore focus to the element that opened the dialog.
+
 ---
 
 #### Popup
@@ -920,6 +967,8 @@ An anchored floating surface built on `<dialog>` with collision-aware positionin
 </dialog>
 ```
 
+Popups restore focus on close. Escape dismissal is scoped so nested menu and overlay behavior can keep its own keyboard handling.
+
 ---
 
 #### Toast
@@ -927,12 +976,14 @@ An anchored floating surface built on `<dialog>` with collision-aware positionin
 `<fig-toast>` — [demo](https://rog.ie/figui3/#toast)
 
 A toast notification. Uses `is="fig-toast"` on a native `<dialog>`.
+Defaults to `role="status"`, `aria-live="polite"`, and `aria-atomic="true"`. Use `live="assertive"` or `theme="danger"` for assertive announcements.
 
 | Attribute | Type | Default | Description |
 |---|---|---|---|
 | `duration` | number | `5000` | Auto-dismiss ms (0 = no dismiss) |
 | `offset` | number | `16` | Distance from bottom |
 | `theme` | string | `"dark"` | `"dark"`, `"light"`, `"danger"`, `"brand"`, `"auto"` |
+| `live` | string | — | `"assertive"` for urgent announcements |
 
 ```html
 <dialog is="fig-toast" id="myToast" theme="brand" duration="3000">
@@ -964,6 +1015,36 @@ Contextual tooltip on hover or click. Auto-repositions when the child element mo
 </fig-tooltip>
 ```
 
+Escape dismisses an open tooltip and returns focus to its trigger.
+
+---
+
+#### Menu
+
+`<fig-menu>` / `<fig-menu-item>` / `<fig-menu-separator>` — [demo](https://rog.ie/figui3/#menu)
+
+Triggered menu with native keyboard patterns. The trigger gets `aria-haspopup="menu"`, `aria-expanded`, and `aria-controls`; menu items use `role="menuitem"` and disabled items are skipped by keyboard navigation.
+
+| Attribute | Type | Default | Description |
+|---|---|---|---|
+| `open` | boolean | `false` | Open state |
+| `disabled` | boolean | `false` | Disable trigger/menu |
+| `position` | string | `"bottom left"` | Popup placement |
+| `offset` | string | — | Popup offset |
+| `closedby` | string | — | Popup close behavior |
+
+**Keyboard:** Arrow keys move between enabled items, Home/End jump to edges, Enter/Space selects, Escape closes and returns focus to the trigger.
+
+```html
+<fig-menu position="bottom left">
+  <fig-button fig-menu-trigger>Actions</fig-button>
+  <fig-menu-item value="copy">Copy</fig-menu-item>
+  <fig-menu-item value="paste">Paste</fig-menu-item>
+  <fig-menu-separator></fig-menu-separator>
+  <fig-menu-item value="delete" disabled>Delete</fig-menu-item>
+</fig-menu>
+```
+
 ---
 
 #### Header
@@ -982,7 +1063,8 @@ A section header component.
 
 `<fig-layer>` — [demo](https://rog.ie/figui3/#layer)
 
-A collapsible layer list item with expand/collapse and visibility toggling. Supports nesting.
+A collapsible layer list item with expand/collapse and visibility toggling. Supports nesting and exposes `role="treeitem"`, `aria-expanded`, `aria-hidden`, `aria-disabled`, and a keyboard-toggleable chevron button.
+Import `fig-layer.js` and `fig-layer.css` to register and style it. `fig-editor.js` also includes the layer registration.
 
 | Attribute | Type | Default | Description |
 |---|---|---|---|
@@ -1036,7 +1118,7 @@ A thin styled layer for arbitrary visual content. Use it for generated previews,
 
 `<fig-media>`
 
-Unified media component that supports image/video modes and shared sizing/upload behavior. Renders a real `<img>` or `<video>` inside the host. By default the host shrinkwraps to the inner media's intrinsic size; set `size` for a token-sized square, or `aspect-ratio` to fill the container width with a fixed ratio.
+Unified media component that supports image/video modes and shared sizing/upload behavior. The media surface is rendered inside a `fig-preview`; generated video controls render below that preview rather than as an overlay. Set `size` for a token-sized square, or `aspect-ratio` to fill the container width with a fixed ratio.
 
 | Attribute | Type | Default | Description |
 |---|---|---|---|
@@ -1054,11 +1136,14 @@ Unified media component that supports image/video modes and shared sizing/upload
 | `loop` | boolean | `false` | Video loop |
 | `muted` | boolean | `false` | Video muted |
 | `poster` | string | — | Video poster URL |
+| `aria-label` | string | — | Accessible label forwarded to generated videos |
+
+Use meaningful `alt` text for informative images. Use `alt=""` only when the image is decorative or already described by nearby text.
 
 ```html
-<fig-media type="image" src="photo.jpg"></fig-media>
-<fig-media type="image" src="photo.jpg" aspect-ratio="16 / 9" fit="cover"></fig-media>
-<fig-media type="video" src="clip.mp4" controls muted></fig-media>
+<fig-media type="image" src="photo.jpg" alt="Selected image"></fig-media>
+<fig-media type="image" src="photo.jpg" alt="Cover image" aspect-ratio="16 / 9" fit="cover"></fig-media>
+<fig-media type="video" src="clip.mp4" aria-label="Product demo video" controls muted></fig-media>
 ```
 
 ---
@@ -1067,7 +1152,7 @@ Unified media component that supports image/video modes and shared sizing/upload
 
 `<fig-image>` — [demo](https://rog.ie/figui3/#image)
 
-An image display component with optional upload, aspect ratio, and object-fit control. Renders a real `<img>` inside the host; by default the host shrinkwraps to the image's intrinsic size.
+An image display component with optional upload, aspect ratio, and object-fit control. Renders a real `<img>` inside a `fig-preview`.
 
 | Attribute | Type | Default | Description |
 |---|---|---|---|
@@ -1080,19 +1165,26 @@ An image display component with optional upload, aspect ratio, and object-fit co
 | `fit` | string | `"contain"` | CSS object-fit (`"cover"`, `"contain"`, etc.) |
 | `checkerboard` | boolean | `false` | Show checkerboard behind transparent images |
 
+Use meaningful `alt` text for informative images. Use `alt=""` for decorative previews, thumbnails with visible labels, or upload placeholders.
+
 ```html
-<fig-image src="photo.jpg"></fig-image>
-<fig-image src="photo.jpg" aspect-ratio="16 / 9" fit="cover"></fig-image>
-<fig-image upload label="Upload Image"></fig-image>
+<fig-image src="photo.jpg" alt="Selected image"></fig-image>
+<fig-image src="photo.jpg" alt="Cover image" aspect-ratio="16 / 9" fit="cover"></fig-image>
+<fig-image upload label="Upload Image" alt=""></fig-image>
+<fig-image src="photo.jpg" alt="Selected image">
+  <fig-input-file slot="overlay" variant="overlay" label="Change image"></fig-input-file>
+</fig-image>
 ```
 
+Use `slot="overlay"` for custom overlay controls. Slotted overlays stay as direct light-DOM children so frameworks like React keep ownership of their nodes, while CSS places them over the preview and keeps them visible on hover, focus, and active interaction.
+
 ---
 
 #### Video
 
 `<fig-video>`
 
-Video display/upload component with the same host styling model as `fig-image`. Renders a real `<video>` inside the host; by default the host shrinkwraps to the video's intrinsic size.
+Video display/upload component with the same preview styling model as `fig-image`. Renders a real `<video>` inside a `fig-preview`; generated playback controls tack onto the bottom.
 
 | Attribute | Type | Default | Description |
 |---|---|---|---|
@@ -1107,11 +1199,14 @@ Video display/upload component with the same host styling model as `fig-image`.
 | `loop` | boolean | `false` | Loop video |
 | `muted` | boolean | `false` | Mute video |
 | `poster` | string | — | Poster image URL (forwarded to inner `<video>`) |
+| `aria-label` | string | — | Accessible label forwarded to the generated `<video>` |
+
+Prefer `controls` for videos that play motion. Add captions with a slotted `<track>` when the video includes speech or essential audio.
 
 ```html
-<fig-video src="clip.mp4"></fig-video>
-<fig-video src="clip.mp4" aspect-ratio="16 / 9" controls></fig-video>
-<fig-video upload label="Upload Video" controls muted></fig-video>
+<fig-video src="clip.mp4" aria-label="Product demo video" controls></fig-video>
+<fig-video src="clip.mp4" aria-label="Product demo video" aspect-ratio="16 / 9" controls></fig-video>
+<fig-video upload label="Upload Video" aria-label="Uploaded video preview" controls muted></fig-video>
 ```
 
 ---
@@ -1162,6 +1257,8 @@ Legacy: `<span class="fig-mask-icon" style="--icon: var(--icon-24-add)"></span>`
 
 A loading spinner.
 
+Defaults to `role="status"` and `aria-label="Loading"`; override the label when the loading target needs a more specific name.
+
 ```html
 <fig-spinner></fig-spinner>
 ```
@@ -1179,6 +1276,8 @@ A shimmer loading placeholder.
 | `duration` | string | `"1.5s"` | Animation cycle duration |
 | `playing` | boolean | `true` | Whether animating |
 
+Shimmer and skeleton placeholders are hidden from assistive tech unless you add `aria-label` or `aria-labelledby`; named placeholders expose `role="status"` and `aria-busy`.
+
 ```html
 <fig-shimmer style="width: 200px; height: 20px;"></fig-shimmer>
 ```
@@ -1189,7 +1288,7 @@ A shimmer loading placeholder.
 
 `<fig-skeleton>`
 
-Extends `<fig-shimmer>` with no additional attributes. Use for structured loading placeholders.
+Extends `<fig-shimmer>` for structured loading placeholders. Skeletons are inert by default, so any placeholder inputs or buttons inside them are removed from tab focus while loading.
 
 ```html
 <fig-skeleton style="width: 100%; height: 1rem; border-radius: 4px;"></fig-skeleton>
@@ -1222,6 +1321,16 @@ Force a theme manually:
 </body>
 ```
 
+Focus indicators are controlled with shared tokens:
+
+```css
+--figma-focus-outline
+--figma-focus-outline-offset
+--figma-focus-outline-radius
+```
+
+`--figma-focus-outline-radius` defaults to `inherit`, so focused controls can inherit their component radius unless a component overrides it for a specific shape.
+
 ---
 
 ## Framework Integration