Skip to content

fix(connections): put the setup caveat behind the card's warning tip - #11463

Merged
bolichen97 merged 1 commit into
mainfrom
fix/connections-caveat-tip
Sep 17, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/connections-caveat-tip

Conversation

@pepmach

@pepmach pepmach commented Sep 17, 2026

Copy link
Copy Markdown
Contributor

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.

Piece Before After
Needs-configuration card (website/src/pages/connections/ConnectionsPage.tsx) 🟥 band with the setup copy above Documentation + Configure OAuth app 🟩 amber triangle (PrerequisiteTip) placed before Configure OAuth app, bubble under the shared Before you connect heading
Review rule (website/AUTOSDE.yaml) none 🟩 blocking connection-card-caveat-tip: a pre-action caveat on a Connections card renders as the triangle, never a band
Owning spec (docs/system-specs/modules/connections.md) described the state as an inline instruction 🟨 a section naming the card's three kinds of content and where each renders; the pre-registered section points at it
Test (website/src/test/ConnectionsPage.coverage.test.tsx) asserted the band text was visible 🟨 asserts the text is absent until the triangle is hovered, and the triangle sits right before the action
Evidence harness (website/scripts/capture-connections-caveat-tip.mjs) none 🟩 renders the built SPA against fixtures and fails if the copy is visible at rest; listed in 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 existing prerequisites_for_provider label and before_you_connect heading, 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.yaml carries the same rule as a blocking: true entry scoped to src/pages/connections/**, with the band as the Bad example, so the review lanes reject the next one on their own. The PrerequisiteTip doc 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; the GitHub prerequisites button and the Configure OAuth app link 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).
  • The existing needs-configuration routing test keeps its badge, no-Connect and Settings-deep-link assertions and drops only the band assertion.
  • 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:

Before: GitHub card with the setup band, Notion stretched with a dead gap

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: gallery at rest, triangle before Configure OAuth app, uniform card heights

After, triangle pinned — the same copy, under the shared heading:

After: GitHub triangle pinned, bubble reads Before you connect with the setup explanation

Light theme

After, light: gallery at rest

After, light: GitHub triangle pinned

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-tip rule in website/AUTOSDE.yaml is that rule, and the spec section it cites is the reference.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@pepmach
pepmach requested review from a team and Zedmor September 17, 2026 05:21
@pepmach

pepmach commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author

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).
Not a goal: changing the setup copy or the Settings → OAuth Apps tab; touching the inline bands that report a live verdict (not-verified, needs-attention) or carry the return-address relay form; any change to how the card decides its state.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 17, 2026
@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 3508f75e239a6359c1cb09f6d732787ffd47a121 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] 3508f75

@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 3508f75e239a6359c1cb09f6d732787ffd47a121 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 3508f75

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 3508f75e239a6359c1cb09f6d732787ffd47a121: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 3508f75e239a6359c1cb09f6d732787ffd47a121 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 3508f75

Verdict parsed from the review's SHA-scoped output markers for commit 3508f75e239a6359c1cb09f6d732787ffd47a121.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 3508f75e239a6359c1cb09f6d732787ffd47a121: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — 🟡 CONCERNS

UX-level review of 3508f75e239a6359c1cb09f6d732787ffd47a121 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: CONCERNS

The amber warning triangle now means "friendly how-to" on half the gallery — the blind reader took it for trouble.

Watch

  • Icon semantics: the blind reader read the changed cards correctly but said "a warning triangle usually means trouble, so this confused me — I can't tell whether the ones on Atlassian and GitLab mean 'helpful note' or 'something is wrong'". With this PR, 4 of 8 cards carry the alarm glyph for reassurance copy ("nothing changes until you save"). Every page visit with unconfigured providers shows it; the cost is misplaced alarm/hesitation, not task failure. Smallest fix: an info-glyph variant of PrerequisiteTip when the bubble is a how-to rather than a blocking prerequisite — or accept it as the maintainer-chosen sibling pattern, knowingly.
  • The triangle's reading on the needs-configuration card was self-rated "a guess (confirmed by shot 3)" — correct, but only certain after seeing the opened bubble; the hover affordance is the sole path to copy that was previously always visible.

Suggestions

  • The bubble heading before_you_connect sits over a card whose only action is Configure OAuth app — no Connect exists there, and the reader already struggled with whether "Needs configuration" means "not connected". A configure-specific heading (e.g. "One-time setup") would close that loop.

[UX-REVIEWED] 3508f75

@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 3508f75e239a6359c1cb09f6d732787ffd47a121 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify the maintainer ruling the new spec section records as history — "the bands never reached main" is, by its own words, checkable nowhere in this repository.

Not justified as shipped

  • Item 2 — rides along: the blocking connection-card-caveat-tip rule is not the card fix; declared, and aimed at a recurrence the diff itself proves (the band landed after the triangle pattern already existed).
  • Item 4 — rides along: the capture harness is evidence tooling, not the fix; declared, and follows the repo's established by-file harness convention in .jscpd.json.
  • Item 5 — rides along: the .jscpd.json exemption exists only to admit item 4.

What this change ships

Inventory (6 items) — 3 justified

Intent: 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.

  1. The needs-configuration card's setup text is hidden until the amber triangle beside Configure OAuth app is hovered or clicked — justified
  2. Review lanes now block any future caveat band on Connections cards (connection-card-caveat-tip) — rides along
  3. connections.md gains the three-kinds-of-card-content section and re-describes the sixth state — justified
  4. A new screenshot harness photographs the card at rest and with the tip pinned — rides along
  5. That harness is exempted from the jscpd duplication check — rides along
  6. The test that pinned the band visible now pins the copy absent until hover — deleted pin, declared in the description with the reproduction — justified

[FIRST-PRINCIPLES-REVIEWED] 3508f75

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 17, 2026
@pepmach

pepmach commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 2 rides along: blocking AUTOSDE rule as the recurrence guard — accepted, kept — span=6d0a0d10e539

The card change removes the instance; the rule removes the class. This PR is the second band on this card (the first was reverted from #8063's review head before merge), so the guard has a named, repeated harm, and the review lanes that read AUTOSDE are the only surface that sees the next card state before it ships.
Its history sentence was verified against the record you asked about: the #8063 bands lived on pushed review heads (e021b7d) and were reverted on the maintainer's ruling before merge. The rule's wording ("tried and reverted") stands; the spec sentence that said "shipped" was corrected on the current head.

@pepmach

pepmach commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 3 rides along: spec section beyond the mandated same-commit update — accepted, kept — span=0f5d428b2e16

The blocking rule cites this section as its reference, and AGENTS.md routes every connections change through this spec before code is touched; without the section the rule would name a taxonomy that exists nowhere in the tree.
It is the durable half of the fix the maintainer asked for ("make sure future agents will follow"), not decoration on the card change.

@pepmach

pepmach commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 4 rides along: capture harness with zero code consumers — accepted, kept — span=a585a467af35

The harness is the evidence generator behind the five attached frames and asserts the layout before each frame (no copy at rest, triangle before Configure, bubble carries heading and copy), which the unit test cannot see in a real browser.
Every capture-*.mjs in website/scripts has zero code consumers by design; the by-file jscpd exemption follows the recorded convention for a harness that descends from a sibling.

@pepmach
pepmach force-pushed the fix/connections-caveat-tip branch from 15e8280 to b4b0b17 Compare September 17, 2026 05:49
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 17, 2026
@pepmach

pepmach commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author
  • Hover-discovery of the setup copy — rebutted: the human ruling this Watch asks for already exists — span=e07167f370b2

The maintainer's instruction for this PR was, verbatim, to hide the caveat behind the triangle exclamation mark like the sibling cards; the same maintainer ruled the same question on #8063 on a rendered comparison ("final human ruling: icon+bubble", disposition on head 0939742) after an always-visible band was tried on a review head and reverted.
The state's badge ("Needs configuration") and its single primary action already carry the decision; the bubble is reassurance about what the button does, which the Watch itself rates low impact. Making it always-visible is the exact change the blocking connection-card-caveat-tip rule this PR adds exists to refuse.

@pepmach

pepmach commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author
  • Per-state heading key ("Before you configure") — rebutted: disproportional, and it forks the pattern being restored — span=f8b0269e6090

"Before you connect" names the goal the whole state is a precondition for, and the bubble's first sentence names the setup step itself ("GitHub needs a one-time setup. Configure OAuth app opens …"), so the reader is not misdirected about what the button does.
One shared heading across every card caveat is the consistency this PR restores and the rule pins ("do not fork a second heading key for a new state"); a state-specific key is a 13-bundle change for a copy nuance. If the maintainer wants the heading varied per action, that is a one-line ruling to record, not a change to make silently here.

@pepmach

pepmach commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 3 rides along: blocking AUTOSDE rule as the recurrence guard — accepted, kept — span=11e8e41e8cb3

The card change removes the instance; the rule removes the class. This PR is the second band on this card (the first lived on #8063's review head e021b7d and was reverted before merge), so the guard answers a repeated, named harm, and the review lanes that read AUTOSDE are the only surface that sees the next card state before it ships.

@pepmach

pepmach commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 6 rides along: capture harness with zero code consumers — accepted, kept — span=e09b98a9a2dd

The harness produced the five attached frames and asserts the layout before each one (no copy at rest, triangle immediately before Configure, bubble carries heading and copy) in a real browser, which the unit test cannot observe; every capture-*.mjs under website/scripts has zero code consumers by design.

@pepmach

pepmach commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 7 rides along: jscpd by-file exemption for the harness — accepted, kept — span=71e06be3693d

The exemption exists only because the harness does, and it follows the recorded convention in website/.jscpd.json for a harness that descends from a sibling (here capture-connections-oauth-clients.mjs): exempt by file, never by directory, with the descent named in the comment so the entry is removed the moment the files stop matching.

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.
@pepmach
pepmach force-pushed the fix/connections-caveat-tip branch from b4b0b17 to 3508f75 Compare September 17, 2026 06:27
@pepmach

pepmach commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author
  • Warning glyph on the setup copy — rebutted: the triangle is the maintainer's explicit choice for this copy, and the copy is a precondition, not reassurance — span=1df2c35168e7

The maintainer's instruction for this PR named the glyph: hide the caveat "behind the triangle exclamation mark", the same one Atlassian and GitLab carry. The card cannot Connect until the setup is done, so "something you must do before this works" is the triangle's meaning here too, not a helpful aside.
One glyph is the point of the pattern: a reader learns once that a triangle beside an action means "read this before pressing"; an info-variant would make every future caveat author classify how-to versus prerequisite, the ambiguity this Watch itself reports. Taking the lane's own second option, knowingly; if the maintainer wants a second glyph, that is his ruling to record.

@pepmach

pepmach commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author
  • Hover-discovery of the setup copy — rebutted: the human ruling this Watch asks for already exists — span=ae3a1ddafbc8

The maintainer's instruction for this PR was to hide this caveat behind the triangle like the sibling cards; the same maintainer ruled the same question on #8063 on a rendered comparison ("final human ruling: icon+bubble", disposition on head 0939742) after an always-visible band was tried on a review head and reverted.
The badge ("Needs configuration") and the single primary action carry the decision; the bubble is what the button entails. Making it always-visible is the change the blocking connection-card-caveat-tip rule in this PR exists to refuse.

@pepmach

pepmach commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author
  • Configure-specific bubble heading — rebutted: disproportional, and it forks the pattern being restored — span=7dc20c71eb40

"Before you connect" names the goal this state is a precondition for, and the bubble's first sentence names the step itself ("GitHub needs a one-time setup. Configure OAuth app opens …"), so the reader is not misdirected about what the button does.
One shared heading across every card caveat is the consistency this PR restores and the rule pins ("do not fork a second heading key for a new state"); a per-state key is a 13-bundle change for a copy nuance. A maintainer ruling to vary the heading per action would be a one-line follow-up, not a silent change here.

@pepmach

pepmach commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 2 rides along: blocking AUTOSDE rule as the recurrence guard — accepted, kept — span=aeb1680437d1

The card change removes the instance; the rule removes the class. As the lane notes, the band landed after the triangle pattern already existed, so precedent alone did not prevent it; the review lanes that read AUTOSDE are the only surface that sees the next card state before it ships.

@pepmach

pepmach commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 4 rides along: capture harness with zero code consumers — accepted, kept — span=9116d8a18f00

The harness produced the five attached frames and asserts the layout before each one (no copy at rest, triangle immediately before Configure, bubble carries heading and copy) in a real browser, which the unit test cannot observe; every capture-*.mjs under website/scripts has zero code consumers by design.

@pepmach

pepmach commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 5 rides along: jscpd by-file exemption for the harness — accepted, kept — span=18188e25bb53

The exemption exists only because the harness does, and follows the recorded convention in website/.jscpd.json for a harness that descends from a sibling (capture-connections-oauth-clients.mjs): exempt by file, never by directory, with the descent named so the entry is removed the moment the files stop matching.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 17, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

@bolichen97
bolichen97 merged commit b9d0b8d into main Sep 17, 2026
115 of 117 checks passed
@bolichen97
bolichen97 deleted the fix/connections-caveat-tip branch September 17, 2026 09:55
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 17, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants