Changes for the UX review items on PAP-9436:
- Highlights are now translucent boxes with state-specific outlines instead
of baseline borders. Focused open anchors get a 2px primary outline plus
fill so they read as a real "lift"; stale anchors get a dashed amber
outline plus a ⚠ glyph at the run end; resolved anchors stay dashed and
dim.
- Document count chip lives inside the document header row (next to the
rev/updated chrome) via a new DocumentAnnotationsCountChip component, so
it stays visible while the document is folded and conforms to neighbor
rhythm. IssueDocumentAnnotations now exposes only the body wrapper +
side panel and accepts controlled panelOpen state from the section.
- Comment authors render as `<name> · <role>` (e.g. `Dotta · board`,
`UXDesigner · agent`) using the same agentMap / userProfileMap that
IssueDetail already builds for IssueComments. Maps flow through
IssueDocumentsSection → IssueDocumentAnnotations → DocumentAnnotationPanel.
- Side panel header drops the duplicate "PLAN" pill — the doc key already
brought the user here. Header now reads `Comments / rev N`.
- Filter chips are real low-contrast chips (rounded ghost buttons with an
active background tint) instead of three-weight Button variants.
- Thread action row is now Resolve (secondary) + Reply (primary), with
Copy link collapsed into a `…` overflow dropdown.
- Persistent "+ New comment on selection" CTA pinned to the bottom of the
panel with a ⌘⇧M keyboard shortcut. The CTA disables itself when a draft
is dirty / conflicted / previewing history, matching the same gate the
body selection toolbar already enforced.
- ThreadCard expanded state now uses `ring-1 ring-ring/70` rather than
`border-primary/60` so the focus affordance is the standard
design-system ring.
- Mobile bottom sheet is now the real shadcn Sheet (`SheetContent
side="bottom"`) — backdrop, focus trap, drag handle, motion all come
from the primitive.
- IssueDocumentsSection accepts storybook-only seeds
(`defaultAnnotationPanelOpenKeys`, `defaultAnnotationFocusedThreadIds`,
`forceEditDocumentKey`) so we can capture deterministic integrated
screenshots instead of Storybook-isolated panel mocks.
- New integrated Storybook stories render the real IssueDocumentsSection
chrome at 1440×900 desktop + 390×844 mobile, with edit-mode and dirty-
draft variants. Stale state-only stories kept for visual debugging.
- design/PAP-9436-doc-annotation-ui/screenshots/ refreshed: the old
Storybook-isolated captures are removed; 5 new integrated captures
(01–05) replace them, and 4 isolated state captures (10–13) remain for
reference.
Tests:
- Existing unit tests updated to the controlled-panel contract; new tests
cover author identity rendering (`<name> · <role>`) and the persistent
CTA.
- `pnpm vitest run` over the annotation surface (4 files, 23 tests) green.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
