link-text-design

Installation
SKILL.md

Link Text Design

Write link text that tells users where they're going before they get there. Screen reader users often navigate by pulling up a list of all links on a page — if every link says "click here" or "read more", that list is useless.

Core Principle

Every link should make sense when read completely on its own, outside of any surrounding sentence or context.

Rules

Link Text Describes the Destination

  • Good: "View your order history"
  • Bad: "Click here"
  • Good: "Download the accessibility guidelines (PDF, 2.4MB)"
  • Bad: "Download"
  • Good: "Read the full Q3 performance report"
  • Bad: "Read more"

Never Use Generic Link Text

These phrases mean nothing out of context:

  • "Click here"
  • "Read more"
  • "Learn more"
  • "Here"
  • "This"
  • "More"
  • "Link"

If you find yourself writing these, ask: more about what? Here where? That answer is your link text.

Same Text, Same Destination

If two links have the same text, they must go to the same place. Two different "Learn more" links going to different pages is confusing for everyone and disorienting for screen reader users.

Different Destinations, Different Text

If two links go to different places, their text must be different.

  • Bad: "View details" / "View details" (going to different products)
  • Good: "View details for Standard Plan" / "View details for Pro Plan"

Special Cases

Links That Open New Windows or Tabs

  • Warn the user: "View the policy (opens in new tab)"
  • Or use a visible external link icon with alt text

Links to Files

  • State the file type and size: "Annual report (PDF, 3.1MB)"
  • This helps users decide before committing to a download

Links Within Body Text

  • The link text should be the meaningful phrase, not the whole sentence
  • Good: "See the full list of supported languages"
  • Bad: "To see the full list of supported languages, click here"
  • Don't link URLs as text unless the URL itself is the information

Image Links

  • The image's alt text serves as the link text
  • A linked logo: alt="Company name — home page"
  • A linked icon: alt describes the action, not the icon

Assessment Checklist

  • Every link makes sense read on its own
  • No generic "click here" or "read more" links
  • Same link text always goes to the same destination
  • File links state type and size
  • New-window links warn the user
  • Image links have descriptive alt text
Weekly Installs
8
GitHub Stars
36
First Seen
Mar 19, 2026