Skip to content

fix(a11y): always show subtle underline on markdown links#1911

Open
bluzername wants to merge 1 commit intopaperclipai:masterfrom
bluzername:fix/markdown-link-underline
Open

fix(a11y): always show subtle underline on markdown links#1911
bluzername wants to merge 1 commit intopaperclipai:masterfrom
bluzername:fix/markdown-link-underline

Conversation

@bluzername
Copy link
Copy Markdown

@bluzername bluzername commented Mar 27, 2026

Thinking Path

  • Paperclip orchestrates ai-agents for zero-human companies
  • But humans want to watch the agents and oversee their work
  • Agents have instructions, issues, and other content that is written in markdown
  • The dashboard renders this markdown so humans can read it nicely
  • But links inside rendered markdown had no underline by default - only a very slight color shift from surrounding text
  • The underline only appear when you hover, so without moving your mouse you cannot tell which text is clickable
  • This is a WCAG accessibility problem - links should be distinguishable from regular text without relying only on color
  • This pull request makes markdown links always show a subtle underline at 30% opacity, and on hover underline goes to full opacity
  • The benefit is users with low vision, colorblindness, or bright screen conditions can now identify links without needing to hover over every word

Problem

Links in rendered markdown content had text-decoration: none by default. The underline only appear on hover. This mean if you just look at the page without moving your mouse, you cannot tell which text is a link and which is regular text. The only difference is a slight color shift which is not enough for many users.

This is a WCAG accessibility concern - links should be visually distinguishable from surrounding text without relying only on color. Users with low vision, colorblindness, or just bright screen conditions may not notice the subtle color difference.

I noticed this when reading agent instructions that had several links mixed in with regular text. Had to hover over random words to discover which ones are clickable.

What I changed

Instead of removing the underline completely, now links have a very subtle underline at all times:

  • At rest: underline visible at 30% opacity (color-mix(in oklab, currentColor 30%, transparent))
  • On hover: underline goes to full opacity for stronger visual feedback

The 30% opacity underline is light enough to not make text look cluttered or distracting, but strong enough that you can tell "this text is a link" without hovering. Similar to how GitHub renders links in markdown.

How to test

  1. Go to any issue or agent that has markdown with links
  2. Without hovering, links should have a faint underline visible
  3. Hover over a link - underline should get more prominent
  4. Check in both light and dark mode

1 file, 4 lines changed.

Links in markdown content was only underlined on hover. If you
don't hover over the text, you cannot tell what is a link and
what is just colored text. This is specially bad for users who
have difficulty perceiving color differences.

Changed from text-decoration:none to a subtle always-visible
underline using 30% opacity of the link color. On hover the
underline become full opacity for stronger feedback.

This way links are clearly distinguishable from regular text
at rest, but the underline is subtle enough to not make the
text look cluttered or hard to read.

Affect all markdown content across the app: agent instructions,
issue descriptions, comments, goal descriptions, etc.
@greptile-apps
Copy link
Copy Markdown
Contributor

greptile-apps bot commented Mar 27, 2026

Greptile Summary

This PR fixes a WCAG accessibility issue by giving markdown links a faint underline (30% opacity) at rest, stepping up to full opacity on hover. The 4-line CSS change is clean and correct — color-mix(in oklab, ...) is already used elsewhere in the file for consistency. No functional issues found with the code itself.\n\nA few notes based on the contribution guidelines:\n\n- Missing "thinking path": Per CONTRIBUTING.md, PR descriptions should start with a "thinking path" — a short narrative from the top of the project down to the specific change. Please add this section to the top of the PR description.\n\n- Missing before/after screenshots: CONTRIBUTING.md asks for before/after screenshots (or a short video) for any visible change. Since this is a UI styling change, please add screenshots showing the link appearance in both light and dark mode before and after the fix.\n\n- Minor CSS redundancy (non-blocking): text-underline-offset: 0.15em in the :hover rule is now redundant since it's already declared in the base .paperclip-markdown a rule and will inherit. Similarly, because text-decoration: underline (a shorthand) already resets text-decoration-color to currentColor, the explicit text-decoration-color: currentColor on hover is technically redundant — though it does make the intent clear, which is fine.

Confidence Score: 5/5

Safe to merge — the 4-line CSS change is correct and addresses a real WCAG accessibility gap with no side-effects.

All findings are P2 or lower. The CSS logic is sound: color-mix is already used in the same rule, browser support is consistent, and the opacity-based underline approach is idiomatic. The only outstanding items are contribution-guideline housekeeping (thinking path, screenshots) and a trivial CSS redundancy — none of which affect correctness or runtime behavior.

No files require special attention.

Important Files Changed

Filename Overview
ui/src/index.css Adds a subtle 30%-opacity underline to .paperclip-markdown a at rest, upgrading to full-opacity on hover; correct CSS, addresses WCAG 1.4.1 link distinguishability.

Reviews (1): Last reviewed commit: "fix(a11y): make markdown links always un..." | Re-trigger Greptile

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.

1 participant