Repository navigation
fix(connections): put the setup caveat behind the card's warning tip - #11463
Conversation
|
Intent: On a Connections card, a caveat about the action the user is about to press (here the needs-configuration state's one-time-setup explanation) renders behind the amber warning triangle beside that action, like every other card caveat -- and the repo records that rule where the next card state's author and reviewers will read it (owning spec, blocking AUTOSDE rule, a frontend test pin). |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing to check. [DESIGN-REVIEWED] 3508f75 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 4.8 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
UX Review (Fable 5) — 🟡 CONCERNSUX-level review of UX-Verdict: CONCERNS The amber warning triangle now means "friendly how-to" on half the gallery — the blind reader took it for trouble. Watch
Suggestions
[UX-REVIEWED] 3508f75 |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify the maintainer ruling the new spec section records as history — "the bands never reached Not justified as shipped
What this change shipsInventory (6 items) — 3 justifiedIntent: stop the needs-configuration Connections card from printing its one-time-setup instructions as an always-visible band, keeping them behind the same warning triangle every other card caveat uses — a FIX.
[FIRST-PRINCIPLES-REVIEWED] 3508f75 |
|
|
|
15e8280 to
b4b0b17
Compare
|
|
|
|
|
The needs-configuration card rendered its one-time OAuth-app setup explanation as an always-visible band above the action row, while every other pre-action caveat on a Connections card (GitLab's Duo requirement, Atlassian's site requirement) rides behind the amber warning triangle beside the action. The band made the card taller than its row partner, which stretched to match and left a dead gap, and buried the one control the state exists for under three lines of prose. The explanation now rides in the same PrerequisiteTip, placed before Configure OAuth app, under the shared "Before you connect" heading. The owning spec gains a section naming the card's three kinds of content (badge, pre-action caveat behind the triangle, inline verdict or form) and website/AUTOSDE.yaml gains a blocking connection-card-caveat-tip rule so the review lanes reject the next band. A frontend test pins the explanation as absent from the document until the triangle is used, and a capture script reproduces the evidence frames.
b4b0b17 to
3508f75
Compare
|
|
|
|
|
|
bolichen97
left a comment
There was a problem hiding this comment.
Reviewed the full diff on head 3508f75 as part of the 2026-09-17 readiness audit (evidence: pr-ready-audit-20260917-0835). Verified before approving: readiness: passed in place, required status PR Readiness success on this head, no CHANGES_REQUESTED, no unresolved human hold, main-drift checked against files this PR touches, last push by pepmach. Merge follows through the normal protected path (no bypass).
…irodotdev#11463) The needs-configuration card rendered its one-time OAuth-app setup explanation as an always-visible band above the action row, while every other pre-action caveat on a Connections card (GitLab's Duo requirement, Atlassian's site requirement) rides behind the amber warning triangle beside the action. The band made the card taller than its row partner, which stretched to match and left a dead gap, and buried the one control the state exists for under three lines of prose. The explanation now rides in the same PrerequisiteTip, placed before Configure OAuth app, under the shared "Before you connect" heading. The owning spec gains a section naming the card's three kinds of content (badge, pre-action caveat behind the triangle, inline verdict or form) and website/AUTOSDE.yaml gains a blocking connection-card-caveat-tip rule so the review lanes reject the next band. A frontend test pins the explanation as absent from the document until the triangle is used, and a capture script reproduces the evidence frames.
Problem / Motivation
On the Connections page, a pre-registered provider whose OAuth app is not configured yet (GitHub, Asana) shows a Needs configuration card. That card printed its one-time-setup explanation as an always-visible band above the action row: three lines of prose, a lock icon, its own border. Every other caveat on a Connections card — GitLab's Duo requirement, Atlassian's site requirement — sits behind the amber warning triangle beside the action and shows on hover or click. The card looked like it belonged to a different product, and the maintainer flagged it as such.
Why it matters
The gallery is a grid of identical cards. A band is paid by every card that reaches the state, forever, for prose a user reads once: the GitHub card grew by the band's height, its row partner (Notion) stretched to match and left a dead gap, and the one control the state exists for sat under three lines of explanation. The triangle costs one 24px slot and keeps every card the same shape. This pattern was chosen once already, after bands were tried and reverted; the fix has to make the choice durable, not just repair the two cards.
What changed (motivation → approach → change)
A GitHub or Asana card that still needs its OAuth app configured no longer carries a band of setup instructions in its body. The same text now sits behind the amber warning triangle beside Configure OAuth app, shown on hover or click, exactly where every other Connections card keeps a caveat about its action — and the repo now says so in three places, so the band cannot come back.
website/src/pages/connections/ConnectionsPage.tsx)PrerequisiteTip) placed before Configure OAuth app, bubble under the shared Before you connect headingwebsite/AUTOSDE.yaml)connection-card-caveat-tip: a pre-action caveat on a Connections card renders as the triangle, never a banddocs/system-specs/modules/connections.md)website/src/test/ConnectionsPage.coverage.test.tsx)website/scripts/capture-connections-caveat-tip.mjs)website/.jscpd.json's by-file capture-harness exemptions, the established form for a harness that shares its fixture preamble with the sibling it descends from🟩 added · 🟨 changed · 🟥 removed
The card change is small on purpose. The copy is the same catalog key (
needs_configuration_help), so no bundle changes; the tip reuses the existingprerequisites_for_providerlabel andbefore_you_connectheading, so no new key. The only difference is where the copy renders: in the bubble the user asks for, not in the card body.The durable part is the rule. The spec now says a card has exactly three kinds of content — the state badge, a pre-action caveat behind the triangle, and an inline band only for a verdict about the current state or a form the state needs — and draws the line by what the copy is about: a verdict reports a fact, a caveat annotates a button.
website/AUTOSDE.yamlcarries the same rule as ablocking: trueentry scoped tosrc/pages/connections/**, with the band as the Bad example, so the review lanes reject the next one on their own. ThePrerequisiteTipdoc comment says the same thing at the component.Tests
keeps the one-time-setup explanation behind the warning tip beside Configure, not in a band(new): the setup copy is not in the document at rest; theGitHub prerequisitesbutton and theConfigure OAuth applink share a parent with the button first; hover opens a tooltip carrying Before you connect and the full copy; click pins it and an outside press dismisses it. Fails on the previous component (the band put the copy in the document at rest).ConnectionsPage.coverage.test.tsx: 113 passed.Manual verification
The capture harness renders the real built bundle against API fixtures and asserts the layout before taking each frame: no setup copy and no open tooltip at rest, the triangle immediately before Configure OAuth app, the bubble carrying the heading and the copy once pinned. Both themes pass. A live gateway shows the same card by default for GitHub and Asana (no client configured), so no further setup is needed to see it.
Screenshots / video
Before — the band, and the row partner stretched to match it:
After, at rest — every card the same height, triangle before Configure on GitHub and Asana exactly as it sits before Connect on Atlassian and GitLab:
After, triangle pinned — the same copy, under the shared heading:
Light theme
Related Issues
no linked issue: the regression was reported by the maintainer from a Nightly build, not filed as an issue.
Pattern harvest
Rule candidate: review-prompt
Pattern: a new card state introduces its own inline explanatory band instead of the surface the sibling states already use for the same kind of copy — the
connection-card-caveat-tiprule inwebsite/AUTOSDE.yamlis that rule, and the spec section it cites is the reference.Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)