docs: fix remaining review issues and align API claims

Author: RtlZeroMemory

.claude/skills/rezi-add-widget/SKILL.md

@@ -56,8 +56,8 @@ Use this skill when:
 
 6. **Add design system support** (if the widget is interactive):
    - Register the new widget kind in `packages/core/src/widgets/protocol.ts`
-   - Add DS props as needed (`dsVariant`, `dsTone`, `dsSize`) to the widget's props type
-   - Wire recipe-based rendering so DS styling auto-activates when `ThemeDefinition` semantic tokens are available (no `dsVariant` required for baseline styling)
+   - Add optional DS props as needed (`dsVariant?`, `dsTone?`, `dsSize?`) for advanced customization
+   - Wire recipe-based rendering so baseline DS styling auto-activates when `ThemeDefinition` semantic tokens are available; DS props override defaults when specified
    - See `docs/guide/widget-authoring.md` for the full pattern
 
 7. **Export** both props type and factory from `packages/core/src/index.ts`

.claude/skills/rezi-create-screen/SKILL.md

@@ -50,7 +50,7 @@ Use this skill when:
    })
    ```
 
-   Use `dsVariant` / `dsTone` / `dsSize` only when you need finer control.
+   Use `dsVariant`, `dsTone`, or `dsSize` only when you need finer control.
 
 2. **Use `ui.column()` or `ui.row()`** as the root container
 
@@ -61,20 +61,18 @@ Use this skill when:
    const AnimatedScreen = defineWidget<{ target: number }>((props, ctx) => {
      const drift = useTransition(ctx, props.target, {
        duration: 180,
-       easing: "easeOutExpo",
-       onComplete: () => console.log("drift transition complete"),
+       easing: "easeOutCubic",
      });
      const spring = useSpring(ctx, props.target, {
        stiffness: 190,
        damping: 22,
-       onComplete: () => console.log("spring settle complete"),
      });
 
      return ui.box(
        {
          width: Math.round(20 + drift),
          opacity: Math.max(0.35, Math.min(1, spring / 100)),
-         transition: { duration: 180, easing: "easeOutBounce", properties: ["size", "opacity"] },
+         transition: { duration: 180, easing: "easeInOutCubic", properties: ["size", "opacity"] },
        },
        [ui.text("Animated screen")],
      );

.claude/skills/rezi-forms/SKILL.md

@@ -45,12 +45,12 @@ Use this skill when:
        ui.field({
          label: "Name",
          error: form.errors.name,
-         children: ui.input({ ...form.bind("name") }),
+         children: ui.input({ id: "field-name", ...form.bind("name") }),
        }),
        ui.field({
          label: "Email",
          error: form.errors.email,
-         children: ui.input({ ...form.bind("email") }),
+         children: ui.input({ id: "field-email", ...form.bind("email") }),
        }),
        ui.button({ id: "submit", label: "Submit", intent: "primary", onPress: form.submit }),
      ]);
@@ -65,7 +65,8 @@ Use this skill when:
 
 ## Design system note
 
-Inputs are recipe-styled by default when a `ThemeDefinition` preset is active.
+Inputs are recipe-styled by default when semantic color tokens are available (for example via a `ThemeDefinition` preset).
+Manual overrides merge on top via the same `mergeTextStyle(baseStyle, ownStyle)` pattern used by the renderer.
 Use manual `style` only for targeted overrides (merged on top of recipe output).
 
 ## Verification

.claude/skills/rezi-keybindings/SKILL.md

@@ -48,14 +48,13 @@ Use this skill when:
    ui.keybindingHelp(app.getBindings())
    ```
 
-## Overlay shortcut enforcement
+## Overlay shortcut hints
 
-Dropdown and CommandPalette item shortcuts are enforced automatically while the
-overlay is open.
+Dropdown and CommandPalette `shortcut` fields are currently display/search hints.
 
-- Declaring `shortcut: "Ctrl+S"` on a dropdown item makes `Ctrl+S` trigger that item.
-- Declaring `shortcut: "Ctrl+S"` on a command palette item does the same.
-- No manual `app.keys()` registration is needed for these overlay-local shortcuts.
+- `routeDropdownKey(...)` handles navigation keys (`Up`, `Down`, `Enter`, `Space`, `Escape`).
+- CommandPalette shows shortcut text and uses it in filtering, but does not auto-bind combos.
+- Register real shortcut combos explicitly with `app.keys()` or `app.modes()`.
 
 ## Key format reference
 

.claude/skills/rezi-write-tests/SKILL.md

@@ -85,10 +85,10 @@ Use this skill when:
    - table emits `action: "rowPress"` with `rowIndex`
    - radio/select flows emit `action: "change"`
 
-10. **For animation `onComplete` behavior**, test:
-   - callback fires on finite completion
-   - callback does not fire for retargeted mid-flight runs
-   - callback does not fire for looping sequences
+10. **For animation hook behavior**, test:
+   - supported easing presets (`linear`, quad, cubic) resolve as expected
+   - retargeted mid-flight runs continue smoothly without jumping
+   - looping sequences (`loop: true`) remain active and deterministic
 
 ## Running tests
 

.codex/skills/rezi-add-widget/SKILL.md

@@ -56,8 +56,8 @@ Use this skill when:
 
 6. **Add design system support** (if the widget is interactive):
    - Register the new widget kind in `packages/core/src/widgets/protocol.ts`
-   - Add DS props as needed (`dsVariant`, `dsTone`, `dsSize`) to the widget's props type
-   - Wire recipe-based rendering so DS styling auto-activates when `ThemeDefinition` semantic tokens are available (no `dsVariant` required for baseline styling)
+   - Add optional DS props as needed (`dsVariant?`, `dsTone?`, `dsSize?`) for advanced customization
+   - Wire recipe-based rendering so baseline DS styling auto-activates when `ThemeDefinition` semantic tokens are available; DS props override defaults when specified
    - See `docs/guide/widget-authoring.md` for the full pattern
 
 7. **Export** both props type and factory from `packages/core/src/index.ts`

.codex/skills/rezi-create-screen/SKILL.md

@@ -50,7 +50,7 @@ Use this skill when:
    })
    ```
 
-   Use `dsVariant` / `dsTone` / `dsSize` only when you need finer control.
+   Use `dsVariant`, `dsTone`, or `dsSize` only when you need finer control.
 
 2. **Use `ui.column()` or `ui.row()`** as the root container
 
@@ -61,20 +61,18 @@ Use this skill when:
    const AnimatedScreen = defineWidget<{ target: number }>((props, ctx) => {
      const drift = useTransition(ctx, props.target, {
        duration: 180,
-       easing: "easeOutExpo",
-       onComplete: () => console.log("drift transition complete"),
+       easing: "easeOutCubic",
      });
      const spring = useSpring(ctx, props.target, {
        stiffness: 190,
        damping: 22,
-       onComplete: () => console.log("spring settle complete"),
      });
 
      return ui.box(
        {
          width: Math.round(20 + drift),
          opacity: Math.max(0.35, Math.min(1, spring / 100)),
-         transition: { duration: 180, easing: "easeOutBounce", properties: ["size", "opacity"] },
+         transition: { duration: 180, easing: "easeInOutCubic", properties: ["size", "opacity"] },
        },
        [ui.text("Animated screen")],
      );

.codex/skills/rezi-forms/SKILL.md

@@ -45,12 +45,12 @@ Use this skill when:
        ui.field({
          label: "Name",
          error: form.errors.name,
-         children: ui.input({ ...form.bind("name") }),
+         children: ui.input({ id: "field-name", ...form.bind("name") }),
        }),
        ui.field({
          label: "Email",
          error: form.errors.email,
-         children: ui.input({ ...form.bind("email") }),
+         children: ui.input({ id: "field-email", ...form.bind("email") }),
        }),
        ui.button({ id: "submit", label: "Submit", intent: "primary", onPress: form.submit }),
      ]);
@@ -65,7 +65,8 @@ Use this skill when:
 
 ## Design system note
 
-Inputs are recipe-styled by default when a `ThemeDefinition` preset is active.
+Inputs are recipe-styled by default when semantic color tokens are available (for example via a `ThemeDefinition` preset).
+Manual overrides merge on top via the same `mergeTextStyle(baseStyle, ownStyle)` pattern used by the renderer.
 Use manual `style` only for targeted overrides (merged on top of recipe output).
 
 ## Verification

.codex/skills/rezi-keybindings/SKILL.md

@@ -48,14 +48,13 @@ Use this skill when:
    ui.keybindingHelp(app.getBindings())
    ```
 
-## Overlay shortcut enforcement
+## Overlay shortcut hints
 
-Dropdown and CommandPalette item shortcuts are enforced automatically while the
-overlay is open.
+Dropdown and CommandPalette `shortcut` fields are currently display/search hints.
 
-- Declaring `shortcut: "Ctrl+S"` on a dropdown item makes `Ctrl+S` trigger that item.
-- Declaring `shortcut: "Ctrl+S"` on a command palette item does the same.
-- No manual `app.keys()` registration is needed for these overlay-local shortcuts.
+- `routeDropdownKey(...)` handles navigation keys (`Up`, `Down`, `Enter`, `Space`, `Escape`).
+- CommandPalette shows shortcut text and uses it in filtering, but does not auto-bind combos.
+- Register real shortcut combos explicitly with `app.keys()` or `app.modes()`.
 
 ## Key format reference
 

.codex/skills/rezi-write-tests/SKILL.md

@@ -85,10 +85,10 @@ Use this skill when:
    - table emits `action: "rowPress"` with `rowIndex`
    - radio/select flows emit `action: "change"`
 
-10. **For animation `onComplete` behavior**, test:
-   - callback fires on finite completion
-   - callback does not fire for retargeted mid-flight runs
-   - callback does not fire for looping sequences
+10. **For animation hook behavior**, test:
+   - supported easing presets (`linear`, quad, cubic) resolve as expected
+   - retargeted mid-flight runs continue smoothly without jumping
+   - looping sequences (`loop: true`) remain active and deterministic
 
 ## Running tests