docs(product): design coaching keyboard-discoverability tooltips (RIG-2530) - #569
Open
rigel-mintaka wants to merge 1 commit into
Open
docs(product): design coaching keyboard-discoverability tooltips (RIG-2530)#569rigel-mintaka wants to merge 1 commit into
rigel-mintaka wants to merge 1 commit into
Conversation
|
Compass engineering docs preview: https://compass-ux-rig-2530-coaching.compass-eng-docs.pages.dev Deployed from Changed pages: |
rigel-mintaka
force-pushed
the
compass-ux/rig-2530-coaching-tooltips
branch
2 times, most recently
from
August 24, 2026 02:41
08465c5 to
ba67b85
Compare
…-2530) Design record for a coaching keyboard-discoverability tooltip layer: a reusable `CoachTip` component that shows a control's label plus its keyboard chord on hover AND focus, adopted across command-backed chrome so mouse and keyboard users passively learn the shortcuts — Linear's discoverability move. This is the deferred RIG-2530, refining DL-234's point-of-use net; distinct from RIG-2484's chord *mechanics* (this is the coaching/push layer, not the reference/pull one). ## What's here - `docs/designs/product/compass-coaching-tooltips/design.md` — the frozen-quality design record (Problem · Global Constraints · Approach A1-A5 · Alternatives · Plan T1-T3 · Resolved decisions D1-D5 · Deferred). - Ledger delta in `DECISIONS.md`: DL-245 (Kobalte-v2-alpha `Tooltip` adoption), DL-246 (sequence-aware chord rendering via `shortcutFor`), DL-247 (the `title=` convert/keep boundary + the two sidebar-toggle registrations). All Active, refining DL-234, no row superseded. ## Approach `CoachTip` builds on the installed Kobalte v2-alpha `Tooltip` primitive (a tooltip's hard parts are DL-150's a11y-hard scope), styles the existing `.cx-tooltip` box, reveals on hover and focus, and resolves its chord only via `shortcutFor` (DL-234 single-derivation, never hand-authored). Forward-compatible with RIG-2484 leader chords: it renders `Ctrl+B` through `ShortcutChip` today and `G then B` as plain text automatically once #544 lands — never blocked on it. The adoption sweep converts the seven command-backed `title=` sites (removing the native `title`, keeping `aria-keyshortcuts`); every other `title=` stays native. ## Design pass Drafted by a design subagent, red-teamed by a design-critic (Kobalte v2-alpha `Tooltip` API verified exact against installed `node_modules` types; Solid-v2 component shape confirmed; the `title=` census verified complete). One load-bearing fork ruled by Matt: the two topbar sidebar-toggle chords (`Mod+\`, `Mod+Shift+\`) are dead today (keymap rows, no registration), so the record registers `sidebar.toggleLeft`/`sidebar.toggleRight` beside their existing store behavior and coaches all seven sites, rather than shrinking the sweep to five live ones. ## CI note Base `fb234f33` carries a pre-existing DL-239 duplicate (two lanes collided on the id: #538/RIG-2453 and #524/RIG-2490), which reds the fail-closed `design-ledger-gate` on every ledger-touching PR. #560 (RIG-2602) fixes it. This PR's ledger gate goes green on rebase once #560 merges; its own delta (DL-245..247) introduces no new duplicate. Spec-impact: none. Refs RIG-2530 Co-authored-by: Matt Wilkinson <matt@rigel.build>
rigel-mintaka
force-pushed
the
compass-ux/rig-2530-coaching-tooltips
branch
from
August 24, 2026 02:51
ba67b85 to
ceb88b3
Compare
rigel-mintaka
marked this pull request as ready for review
August 24, 2026 02:52
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Design record for a coaching keyboard-discoverability tooltip layer: a reusable
CoachTipcomponent that shows a control's label plus its keyboard chord on hover AND focus, adopted across command-backed chrome so mouse and keyboard users passively learn the shortcuts — Linear's discoverability move. This is the deferred RIG-2530, refining DL-234's point-of-use net; distinct from RIG-2484's chord mechanics (this is the coaching/push layer, not the reference/pull one).What's here
docs/designs/product/compass-coaching-tooltips/design.md— the frozen-quality design record (Problem · Global Constraints · Approach A1-A5 · Alternatives · Plan T1-T3 · Resolved decisions D1-D5 · Deferred).DECISIONS.md: DL-245 (Kobalte-v2-alphaTooltipadoption), DL-246 (sequence-aware chord rendering viashortcutFor), DL-247 (thetitle=convert/keep boundary + the two sidebar-toggle registrations). All Active, refining DL-234, no row superseded.Approach
CoachTipbuilds on the installed Kobalte v2-alphaTooltipprimitive (a tooltip's hard parts are DL-150's a11y-hard scope), styles the existing.cx-tooltipbox, reveals on hover and focus, and resolves its chord only viashortcutFor(DL-234 single-derivation, never hand-authored). Forward-compatible with RIG-2484 leader chords: it rendersCtrl+BthroughShortcutChiptoday andG then Bas plain text automatically once #544 lands — never blocked on it. The adoption sweep converts the seven command-backedtitle=sites (removing the nativetitle, keepingaria-keyshortcuts); every othertitle=stays native.Design pass
Drafted by a design subagent, red-teamed by a design-critic (Kobalte v2-alpha
TooltipAPI verified exact against installednode_modulestypes; Solid-v2 component shape confirmed; thetitle=census verified complete). One load-bearing fork ruled by Matt: the two topbar sidebar-toggle chords (Mod+\,Mod+Shift+\) are dead today (keymap rows, no registration), so the record registerssidebar.toggleLeft/sidebar.toggleRightbeside their existing store behavior and coaches all seven sites, rather than shrinking the sweep to five live ones.CI note
Base
fb234f33carries a pre-existing DL-239 duplicate (two lanes collided on the id: #538/RIG-2453 and #524/RIG-2490), which reds the fail-closeddesign-ledger-gateon every ledger-touching PR. #560 (RIG-2602) fixes it. This PR's ledger gate goes green on rebase once #560 merges; its own delta (DL-245..247) introduces no new duplicate.Spec-impact: none. Refs RIG-2530
Co-authored-by: Matt Wilkinson matt@rigel.build