Skip to content

feat(web-ui): PROOF9 terminology tooltips and glossary on Proof page (#470)#492

Merged
frankbria merged 2 commits intomainfrom
feat/issue-470-proof9-tooltips-glossary
Mar 24, 2026
Merged

feat(web-ui): PROOF9 terminology tooltips and glossary on Proof page (#470)#492
frankbria merged 2 commits intomainfrom
feat/issue-470-proof9-tooltips-glossary

Conversation

@frankbria
Copy link
Owner

@frankbria frankbria commented Mar 24, 2026

Summary

  • Adds @radix-ui/react-tooltip and creates a new web-ui/src/components/ui/tooltip.tsx shadcn/ui wrapper
  • Column header tooltips (InformationCircleIcon) on Glitch Type, Severity, Gates with contextual definitions
  • Inline status legend between stats bar and table: open (red) / satisfied (green) / waived (gray) with plain-language descriptions
  • Updated page subtitle: "PROOF9 tracks quality requirements with evidence. Requirements must be satisfied or waived before shipping." + "Learn more ↓" anchor
  • In-page help section (#proof9-help) with key terms glossary and requirement lifecycle explanation

Closes #470

Test plan

  • Proof page loads without errors
  • Hover over Glitch Type, Severity, Gates column headers — tooltip appears with correct text
  • Status legend visible between stats bar and table
  • "Learn more ↓" link scrolls to help section at bottom of page
  • Help section explains PROOF9 purpose, key terms, and lifecycle
  • Build passes (npm run build clean)

Summary by CodeRabbit

  • New Features
    • Added informational tooltips to the proof page table headers (Glitch Type, Severity, Gates) for improved clarity.
    • Introduced a status legend above the requirements table to clarify proof states.
    • Added an in-page help section with PROOF9 definitions and lifecycle details.
    • Updated the proof page subtitle copy and included a "Learn more ↓" anchor link.

…470)

- Add @radix-ui/react-tooltip and create shadcn/ui Tooltip wrapper component
- Add InformationCircleIcon tooltips to Glitch Type, Severity, Gates column headers
- Add status legend (open/satisfied/waived) with colored dots between stats and table
- Update page subtitle to explain PROOF9 purpose for new users
- Add in-page help section (#proof9-help) with key terms and lifecycle definitions
@coderabbitai
Copy link
Contributor

coderabbitai bot commented Mar 24, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ecb0bc66-7ee2-437a-8982-385b5dcbfdd8

📥 Commits

Reviewing files that changed from the base of the PR and between adf8109 and f03a1a7.

📒 Files selected for processing (1)
  • web-ui/src/app/proof/page.tsx
🚧 Files skipped from review as they are similar to previous changes (1)
  • web-ui/src/app/proof/page.tsx

Walkthrough

Adds Radix-based tooltip support and a tooltip component, updates package dependencies, and enhances the Proof page with header tooltips, a status legend, revised subtitle copy, and an in-page PROOF9 help section.

Changes

Cohort / File(s) Summary
Tooltip Component
web-ui/src/components/ui/tooltip.tsx
New Radix-based tooltip module exporting Tooltip, TooltipTrigger, TooltipProvider, and TooltipContent with default side offset, styling, portal usage, and forwarded refs.
Proof Page
web-ui/src/app/proof/page.tsx
Wrapped page in TooltipProvider; replaced plain headers for “Glitch Type”, “Severity”, and “Gates” with info-icon tooltip triggers and content; updated subtitle copy; added a status legend and an in-page help/glossary section (#proof9-help).
Package Dependencies
web-ui/package.json
Added dependency @radix-ui/react-tooltip (^1.2.8) to enable tooltip primitives.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Poem

🐰 I hopped in with a tiny tooltip cheer,
Little icons whispering meanings clear.
Legends and help tucked right in sight,
PROOF9 made softer, polite and bright.
✨🔎

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately describes the main changes: adding PROOF9 tooltips and a glossary to the Proof page, which aligns with the changeset.
Linked Issues check ✅ Passed All acceptance criteria from issue #470 are met: tooltips added to column headers, status legend visible, page intro updated, and help section provided.
Out of Scope Changes check ✅ Passed All changes are directly related to the PR objectives: adding Radix tooltip dependency, creating tooltip component wrapper, and updating the Proof page with tooltips and help documentation.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

📋 Issue Planner

Built with CodeRabbit's Coding Plans for faster development and fewer bugs.

View plan used: #470

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/issue-470-proof9-tooltips-glossary

Comment @coderabbitai help to get the list of available commands and usage tips.

@claude
Copy link

claude bot commented Mar 24, 2026

PR Review - PROOF9 Tooltips and Glossary

Clean, focused UI enhancement. The implementation follows the existing shadcn/ui patterns well.

What works well:

  • tooltip.tsx is a textbook shadcn/ui wrapper — forwardRef, Portal, sideOffset default, animation classes all correct
  • Status legend with color dots is clear and scannable
  • Help section content is accurate and well-organized into two columns
  • TooltipTrigger asChild with an icon wrapper is the right pattern

Issues to address:

  1. cursor-default on info icons should be cursor-help — The icon triggers use cursor-default which signals a non-interactive element. For tooltip triggers, cursor-help is semantically correct and communicates to users that hovering yields more info. All three column-header icon spans need this change.

  2. TooltipProvider belongs at app level, not per-page — Radix recommends a single TooltipProvider near the root. Having it per-page means tooltip state resets on navigation. Move it to web-ui/src/app/layout.tsx and remove the wrapper from page.tsx. As more pages add tooltips this will matter.

  3. Add delayDuration to TooltipProvider — The default is 700ms, which feels sluggish for column header info icons. 300–400ms is more comfortable: <TooltipProvider delayDuration={300}>.

  4. Severity tooltip vs. help section are inconsistent in detail — The Severity tooltip says "critical, high, medium, or low" but the help section says "critical blocks ship, high strongly recommended, medium/low advisory." Worth aligning the detail level between the two.

  5. Dot size inconsistency — Status legend uses h-2.5 w-2.5 dots; the help section lifecycle uses h-2 w-2. Pick one size.

Non-blocking: The plain <a href="#proof9-help"> anchor is fine — Next.js Link is not needed for in-page scroll targets. max-w-xs on TooltipContent is appropriate for these short descriptions.

Feature is solid. Main asks: move the Provider to layout, swap cursor class, add a delay duration.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@web-ui/src/app/proof/page.tsx`:
- Around line 222-225: The TooltipTrigger currently wraps non-focusable <span>
elements (the ones rendering InformationCircleIcon) which prevents keyboard
users from opening the tooltips; update each TooltipTrigger instance (the ones
near the table headers for "Proof", "Severity", and "Gates") to wrap a semantic
<button> instead, keep the existing className styling, add type="button" and an
appropriate aria-label (e.g., "Show glossary for Proof", "Show glossary for
Severity", "Show glossary for Gates"), and preserve the asChild prop and
InformationCircleIcon usage so keyboard focus and screen-reader access work
correctly.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1763dbfe-1a46-481e-978c-e97c57fbfec4

📥 Commits

Reviewing files that changed from the base of the PR and between 59f5fa9 and adf8109.

⛔ Files ignored due to path filters (1)
  • web-ui/package-lock.json is excluded by !**/package-lock.json
📒 Files selected for processing (3)
  • web-ui/package.json
  • web-ui/src/app/proof/page.tsx
  • web-ui/src/components/ui/tooltip.tsx

@claude
Copy link

claude bot commented Mar 24, 2026

Code Review: feat(web-ui) PROOF9 terminology tooltips and glossary (#492)

This is a focused UI enhancement adding educational context to the Proof page. The implementation is generally solid. Here is my analysis.


Summary

The PR adds three things: a tooltip.tsx shadcn/ui wrapper component, inline tooltips on three table column headers, and an in-page #proof9-help glossary section. It is scoped entirely to web-ui/ and does not touch any core or CLI modules, which is correct per the CLAUDE.md architecture rules.


What Works Well

  • The tooltip.tsx component follows the established shadcn/ui pattern already used for button, input, textarea, etc. in this codebase. Consistent, maintainable.
  • aria-label on each tooltip trigger button is correct and supports screen readers. aria-hidden="true" on the decorative icon is also correct.
  • focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 on the trigger buttons means keyboard users can discover the tooltips, which is a meaningful accessibility win.
  • Using TooltipPrimitive.Portal in TooltipContent is the right default — it avoids z-index/overflow clipping issues with table cells.
  • The glossary content is accurate and consistent between the tooltip text, the status legend, and the help section. No terminology drift.
  • max-w-xs on TooltipContent prevents runaway tooltip widths on long strings.

Issues and Recommendations

Critical

None.

Important

1. TooltipProvider placement creates a wrapping imbalance in JSX

In page.tsx, the <TooltipProvider> wraps the entire return, but the indentation was not adjusted. The closing </TooltipProvider> appears after the closing </main>, which means <main> is the direct child of TooltipProvider. This works at runtime, but the indentation in the diff reads as though <main> and </TooltipProvider> are siblings of </div>:

  return (
    <TooltipProvider>
    <main className="min-h-screen bg-background">   // <-- not indented under TooltipProvider
      ...
    </main>
    </TooltipProvider>   // <-- misaligned
  );

This is a readability and linting concern. The correct form is:

  return (
    <TooltipProvider>
      <main className="min-h-screen bg-background">
        ...
      </main>
    </TooltipProvider>
  );

2. TooltipProvider scope is broader than necessary

Wrapping the entire page with TooltipProvider is fine for now, but if other pages or parent layouts later add their own TooltipProvider, nested providers will cause the inner one to shadow the outer. A better long-term pattern is to add a single TooltipProvider in the root layout (web-ui/src/app/layout.tsx) so all pages share one provider. This avoids future bugs when tooltips are added to other pages.

3. Tooltip content is not accessible to mobile/touch users

@radix-ui/react-tooltip only triggers on hover and focus. On touch-only devices, the info icon will be visible but tapping it will not reveal the tooltip text. Since the glossary section already exists at #proof9-help, this is not a blocking issue, but consider either:

  • Adding delayDuration={0} and a touch fallback, or
  • Noting this limitation in comments so future contributors are aware.

Nice-to-have

4. Three near-identical tooltip trigger blocks should be extracted

The three column header tooltip blocks are structurally identical: label text, a button with aria-label, an icon, and TooltipContent. This repetition (approximately 12 lines each, 36 lines total) is a DRY violation. A small helper component would reduce noise and make future edits to all three consistent:

function ColumnHeaderWithTooltip({ label, description }: { label: string; description: string }) {
  return (
    <span className="flex items-center gap-1">
      {label}
      <Tooltip>
        <TooltipTrigger asChild>
          <button
            type="button"
            aria-label={`Explain ${label}`}
            className="inline-flex cursor-help text-muted-foreground/60 hover:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
          >
            <InformationCircleIcon className="h-3.5 w-3.5" aria-hidden="true" />
          </button>
        </TooltipTrigger>
        <TooltipContent>{description}</TooltipContent>
      </Tooltip>
    </span>
  );
}

This is a refactor for a follow-up; it does not need to block this PR.

5. Status legend color dots use hardcoded Tailwind color classes

bg-red-400, bg-green-400, and bg-gray-400 are hardcoded in both the status legend and the help section. If the design system ever defines semantic status colors (e.g., bg-status-open), these would need two-location updates. The ProofStatusBadge component presumably already maps status to color — consider whether the legend dots could derive their color from that same mapping to avoid drift.

6. The Learn more ↓ anchor is a bare <a> tag

The page uses Next.js Link for the nav links elsewhere. While this is an in-page anchor (no route change) and a bare <a> is technically correct here, adding className="text-sm" or ensuring the font size is consistent with the surrounding paragraph text would be worth verifying at render time.

7. No tests added

The test plan items in the PR description are all manual. The CLAUDE.md test conventions focus on backend/core coverage, so there is no strong expectation of UI unit tests here. However, if this project later adds Playwright or Cypress end-to-end tests, this feature (scroll-to-anchor, tooltip visibility) would be a natural candidate.


Security

No security concerns. This change is entirely presentational, introduces no data inputs, makes no API calls, and adds no new attack surface.

Performance

No performance concerns. The Radix tooltip library is tree-shaken, the animation classes use CSS transforms, and there are no new useEffect hooks or data fetches.

Architecture Compliance

This PR is correctly scoped. All changes are inside web-ui/ with no imports into codeframe/core/. The CLAUDE.md rules state the frontend is legacy/reference and to not expand frontend scope during Golden Path work — however, this PR addresses a concrete closed issue (#470) and adds only documentation UX to an existing page without redesigning anything. That is a reasonable exception.


Overall Assessment

The implementation is clean and production-ready as-is. The indentation issue (item 1) and the TooltipProvider placement (item 2) are the only changes I would recommend before merge. The DRY refactor (item 4) can be deferred to a follow-up.

@frankbria frankbria merged commit 49ff38b into main Mar 24, 2026
10 checks passed
@frankbria frankbria deleted the feat/issue-470-proof9-tooltips-glossary branch March 24, 2026 23:28
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.

UX: Add PROOF9 terminology tooltips and glossary to Proof page

1 participant