# Purposeful Motion Disclosures Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Give pointer-owned Project, decision-history, research-result, and chat-tool disclosures bounded expansion and icon motion while keyboard and reduced-motion paths remain immediate. **Architecture:** Consume slice 1's app-owned `collapse` contract and add its bounded CSS recipe, then inject that structural contract into editor-owned surfaces so `@chopin/editor` never depends on the web app. One shared wrapper owns retained exit, interruption, `inert`, and `aria-hidden`; each consumer keeps its state, content, and accessible trigger. **Tech Stack:** React 19, TypeScript, native CSS transitions, `useTransitionPresence`, Bun tests, Playwright. --- ## Dependency gate and file map Do not implement against the current detached design commit. After slice 1 merges: ```bash git switch -c maggie/motion-disclosures git fetch origin git rebase origin/main rg -n "MotionKind|MOTION_STATES|motionContract|closeDuration" apps/web/src --glob '*.{ts,tsx}' ``` Expected: `apps/web/src/motion-contract.ts` already owns `collapse` with a 250ms close duration and the shared motion states. Slice 2 consumes that shipped contract rather than changing or duplicating it. Files: - `apps/web/src/theme.css`, `theme.test.ts`: collapse CSS states and icon motion. - New `packages/editor/src/disclosure-motion.tsx` and test; `packages/editor/src/index.ts`: shared retained wrapper. - `apps/web/src/project-sidebar.tsx`, `navigation-chrome.test.ts`: Projects. - `packages/editor/src/decisions.tsx`, `decisions.test.tsx`: resolved history. - `packages/editor/src/background-work.tsx`, `background-work.test.ts`: research results. - `apps/web/src/chat/transcript.tsx`: finished tool logs. - `apps/web/src/room-workspace.tsx`: inject the app contract and input sampler into editor surfaces. - `e2e/document-navigation.e2e.ts`, `sidecar.e2e.ts`, `jobs.e2e.ts`, `smoke.e2e.ts`: browser policy. ### Task 1: Implement the shipped collapse contract in CSS **Files:** - Modify: `apps/web/src/theme.css` - Modify: `apps/web/src/theme.test.ts` - [ ] **Step 1: Write failing static CSS assertions** Add a `disclosure motion` suite to `theme.test.ts` that asserts the shipped contract's recipe: ```ts expect(THEME).toMatch(/\.motion-collapse\s*{[^}]*var\(--acc-expand\)[^}]*var\(--motion-move\)/s); expect(THEME).toMatch(/\.motion-collapse\.is-closing\s*{[^}]*var\(--acc-collapse\)/s); expect(THEME).toMatch( /:root\[data-motion-input="pointer"\][^{]*\.motion-disclosure-icon[^}]*var\(--icon-swap-dur\)/s, ); expect(THEME).toMatch( /@media \(prefers-reduced-motion: reduce\)[\s\S]*\.motion-collapse[^{]*{[^}]*transition:\s*none/s, ); ``` - [ ] **Step 2: Verify red** Run: `bun test apps/web/src/theme.test.ts` Expected: FAIL because the `collapse` selectors are absent. - [ ] **Step 3: Add the bounded CSS recipe** Keep slice 1's `--acc-expand` and `--acc-collapse` at 250ms, matching the shipped registry duration, then add: ```css .motion-collapse { display: grid; grid-template-rows: 0fr; transition: grid-template-rows var(--acc-expand) var(--motion-move); } .motion-collapse-content { min-height: 0; overflow: hidden; opacity: 0; transform: translateY(-4px); transition: opacity var(--acc-expand) var(--motion-move), transform var(--acc-expand) var(--motion-move); } .motion-collapse.is-open { grid-template-rows: 1fr; } .motion-collapse.is-open > .motion-collapse-content { opacity: 1; transform: translateY(0); } .motion-collapse.is-closing { grid-template-rows: 0fr; transition-duration: var(--acc-collapse); } .motion-collapse.is-closing > .motion-collapse-content { opacity: 0; transform: translateY(-4px); transition-duration: var(--acc-collapse); } .motion-disclosure-icon { display: inline-flex; transform: rotate(0deg); } :root[data-motion-input="pointer"] .motion-disclosure-icon { transition: transform var(--icon-swap-dur) var(--motion-smooth-out); } .motion-disclosure-icon[data-open] { transform: rotate(90deg); } ``` Add `.motion-collapse`, `.motion-collapse-content`, and `.motion-disclosure-icon` to the existing reduced-motion rule with `transition: none`. - [ ] **Step 4: Verify green and commit** Run: `bun test apps/web/src/motion-contract.test.ts apps/web/src/theme.test.ts` ```bash git add apps/web/src/theme.css apps/web/src/theme.test.ts git commit -m "Add collapse motion contract" ``` ### Task 2: Add shared retained disclosure content **Files:** - Create: `packages/editor/src/disclosure-motion.tsx` - Create: `packages/editor/src/disclosure-motion.test.tsx` - Modify: `packages/editor/src/index.ts` - [ ] **Step 1: Write the failing wrapper tests** Server-render `MotionDisclosure` with `motion={{ className: "motion-collapse", closeDuration: 250 }}`. Assert an open render contains its id, `data-motion-disclosure`, and `motion-collapse-content`; assert a closed render is empty. Also assert: ```ts expect(disclosureAccessibility("closing")).toEqual({ ariaHidden: "true", inert: true, }); ``` - [ ] **Step 2: Verify red** Run: `bun test packages/editor/src/disclosure-motion.test.tsx` Expected: FAIL because the module is missing. - [ ] **Step 3: Implement the injected wrapper** ```tsx import { useTransitionPresence } from "./transition-presence"; import type { PresencePhase } from "./transition-presence"; import type { ReactNode } from "react"; export type MotionDisclosureContract = { readonly className: string; readonly closeDuration: number; }; export function disclosureAccessibility(phase: PresencePhase) { let active = phase !== "closing"; return { ariaHidden: active ? undefined : "true" as const, inert: !active }; } export function MotionDisclosure( { children, className = "", id, immediately, motion, open, surface }: { children: ReactNode; className?: string; id: string; immediately: boolean; motion: MotionDisclosureContract; open: boolean; surface: string; }, ) { let presence = useTransitionPresence(open ? true : undefined, motion.closeDuration, immediately); if (presence.phase === "closed") return null; let accessibility = disclosureAccessibility(presence.phase); return (
{children}
); } export function MotionDisclosureIcon({ children, open }: { children: ReactNode; open: boolean }) { return ( ); } ``` Export both components, `disclosureAccessibility`, and `MotionDisclosureContract` from `index.ts`. - [ ] **Step 4: Verify and commit** Run: `bun test packages/editor/src/disclosure-motion.test.tsx && bun run types` ```bash git add docs/superpowers/plans/2026-08-25-motion-disclosures.md packages/editor/src/disclosure-motion.tsx \ packages/editor/src/disclosure-motion.test.tsx packages/editor/src/index.ts git commit -m "Add shared disclosure motion presence" ``` ### Task 3: Animate Project expansion **Files:** `apps/web/src/project-sidebar.tsx`, `apps/web/src/navigation-chrome.test.ts`, `e2e/document-navigation.e2e.ts` - [ ] **Step 1: Write failing tests** The markup test asserts an expanded Project trigger has `aria-controls`, and its body has `data-motion-disclosure="projects"`. The browser test pointer-collapses the seeded `score` Project, asserts the trigger drops `aria-controls` while retained content is immediately `aria-hidden` and `inert`, then clicks the trigger during exit and asserts the reference and same content become active with no duplicate. Run: `bun test apps/web/src/navigation-chrome.test.ts` Expected: FAIL because the body conditionally unmounts. - [ ] **Step 2: Wrap the existing body** In `Project`, add `useId`, `MotionDisclosure`, `motionContract`, and `motionImmediately`: ```tsx let contentId = useId(); let collapseMotion = motionContract("collapse"); ``` Set `aria-controls={expanded ? contentId : undefined}` on the existing trigger so it only references the mounted region. Move the existing unavailable, error, loading, channel/research, loading-more, and load-more branches unchanged inside: ```tsx
{projectContent}
; ``` Use a local `projectContent` React node containing those existing branches; do not animate updates while the Project is already open. - [ ] **Step 3: Verify and commit** Run: `bun test apps/web/src/navigation-chrome.test.ts` Run: `bun run e2e -- e2e/document-navigation.e2e.ts` ```bash git add apps/web/src/project-sidebar.tsx apps/web/src/navigation-chrome.test.ts e2e/document-navigation.e2e.ts git commit -m "Animate Project disclosures" ``` ### Task 4: Animate decision history and caret state **Files:** `packages/editor/src/decisions.tsx`, `decisions.test.tsx`, `apps/web/src/room-workspace.tsx`, `e2e/sidecar.e2e.ts` - [ ] **Step 1: Write failing tests** Extend the server-render helper with the fixture contract. Assert closed history has no `aria-controls`; restored open history has `aria-controls`, `data-motion-disclosure="decision-history"`, and one `.motion-disclosure-icon[data-open]`. In Playwright, focus `1 resolved`, press Space, assert content and its reference appear without `is-closing`; press Space again and assert the reference and content immediately unmount. Run: `bun test packages/editor/src/decisions.test.tsx` - [ ] **Step 2: Retain history and rotate one caret** Add required `motion: MotionDisclosureContract` and optional `motionImmediately?: () => boolean` props, plus `useId`. Set `aria-controls={history ? historyId : undefined}` on the trigger. Remove `CaretDownIcon`; render: ```tsx
{settled.map(question)}
``` In `RoomWorkspace`, pass `motion={motionContract("collapse")}` and the existing `settleMotionImmediately` function. Do not change storage, reveal focus, highlights, or ordering. - [ ] **Step 3: Verify and commit** Run: `bun test packages/editor/src/decisions.test.tsx` Run: `bun run e2e -- e2e/sidecar.e2e.ts` ```bash git add packages/editor/src/decisions.tsx packages/editor/src/decisions.test.tsx \ apps/web/src/room-workspace.tsx e2e/sidecar.e2e.ts git commit -m "Animate decision history disclosure" ``` ### Task 5: Animate completed research results **Files:** `packages/editor/src/background-work.tsx`, `background-work.test.ts`, `apps/web/src/room-workspace.tsx`, `e2e/jobs.e2e.ts` - [ ] **Step 1: Write failing tests** Server-render `BackgroundJob` with a completed result and fixture contract; assert the closed trigger has no `aria-controls` and no result content. Add a pure regression proving a toggle's input sample survives delayed detail resolution and is replaced on the next toggle. Add Playwright coverage that reduced motion opens immediately, pointer-close enters retained `aria-hidden`/`inert`, and enabling reduced motion during exit unmounts immediately. - [ ] **Step 2: Wrap resolved detail without delaying its fetch** Add `motion: MotionDisclosureContract` and `motionImmediately?: () => boolean` to `BackgroundWorkProps`, pass them to `BackgroundJob`, and add `useId`. Keep `store.detail(job.id)` in the existing toggle. Capture `motionImmediately?.() ?? false` in the disclosure state inside every toggle so delayed detail uses the event that initiated it. Set `aria-controls` only while `open && detail !== undefined`, and replace both result conditionals with: ```tsx {artifact ? (

{artifact.title}

{artifact.summary}

) :

Result is unavailable.

}
; ``` Pass the app contract and sampler from `RoomWorkspace`. Do not animate progress, running status, artifact arrival before detail resolves, cancellation, or errors. - [ ] **Step 3: Verify and commit** Run: `bun test packages/editor/src/background-work.test.ts` Run: `bun run e2e -- e2e/jobs.e2e.ts` ```bash git add packages/editor/src/background-work.tsx packages/editor/src/background-work.test.ts \ apps/web/src/room-workspace.tsx e2e/jobs.e2e.ts git commit -m "Animate research result disclosures" ``` ### Task 6: Animate finished chat tool logs and caret state **Files:** `apps/web/src/chat/transcript.tsx`, `e2e/smoke.e2e.ts` - [ ] **Step 1: Write the failing browser assertion** Extend `chat groups authors and collapses a finished tool run`: assert the closed trigger has no `aria-controls`; after opening, assert its reference and one icon has `data-open`; close and assert the reference disappears while the log remains `aria-hidden` and `inert`; reopen before exit completes and assert the reference, same log, and icon become open. Run: `bun run e2e -- e2e/smoke.e2e.ts --grep "chat groups authors"` - [ ] **Step 2: Retain the log and rotate one right caret** Add `useId`, the shared disclosure pieces, `motionContract`, and `motionImmediately`. Remove the down-chevron import. Keep the running tool row unchanged. Set `aria-controls={open ? contentId : undefined}` on the finished-run trigger, wrap the existing right-chevron image in `MotionDisclosureIcon`, and wrap the existing `