Skip to content

thedaviddias/Front-End-Checklist / skills/link-text

link-text

Verified

Use when reviewing rendered HTML, interactive components, or design-system patterns related to Use descriptive link text. Check native semantics first, then inspect keyboard behavior, focus flow, accessible names, and screen-reader output where relevant.

FileKindSize
SKILL.mdskill md2.1 KB
references/rule.mdmarkdown3.6 KB

references/rule.md

View on GitHub
# Use descriptive link text

> Link text clearly describes the destination or purpose without relying on surrounding context.

**Priority:** high · **Difficulty:** beginner · **Time:** 10 min

---
Link text should clearly describe where the link goes or what it does, without relying on surrounding context.

## Code Example

```html
<!-- ❌ Bad: Generic, meaningless out of context -->
<a href="/pricing">Click here</a>
<a href="/docs">Read more</a>
<a href="/signup">Learn more</a>

<!-- ✅ Good: Descriptive, understandable alone -->
<a href="/pricing">View pricing plans</a>
<a href="/docs">Read the documentation</a>
<a href="/signup">Create your free account</a>
```

## Why It Matters

- **Screen Reader Navigation**: Users often use a shortcut to list all links on a page; descriptive text makes this list meaningful.
- **Cognitive Accessibility**: Clear labels help users with cognitive disabilities understand what will happen when they click a link.
- **SEO**: Search engines use link text (anchor text) to understand the content of the linked page.
- **Context Independence**: Users should be able to understand the link even if they don't read the surrounding paragraph.
- **Correct Semantics**: Links should navigate to another URL. If the interaction opens a menu, submits a form, or toggles UI state, use a button instead.

### Links vs Buttons

```html
<!-- ❌ Bad: button used for navigation -->
<button type="button" onclick="window.location.href='/pricing'">
  View pricing
</button>

<!-- ✅ Good: link used for navigation -->
<a href="/pricing">View pricing</a>
```

## Common Patterns

### "Read More" Links

```html
<!-- ❌ Bad: Multiple "Read more" links -->
<article>
  <h3>Getting Started with React</h3>
  <p>Learn the basics of React...</p>
  <a href="/react-intro">Read more</a>
</article>

<!-- ✅ Good: Descriptive link text -->
<article>
  <h3>Getting Started with React</h3>
  <p>Learn the basics of React...</p>
  <a href="/react-intro">Read the React introduction guide</a>
</article>

<!-- ✅ Also good: Visually hidden expanded text -->
<article>
  <h3>Getting Started with React</h3>
  <p>Learn the basics of React...</p>
  <a href="/react-intro">
    Read more<span class="sr-only"> about Getting Started with React</span>
  </a>
</article>
```

### Download Links

```html
<!-- ❌ Bad: No file information -->
<a href="/report.pdf">Download</a>

<!-- ✅ Good: Includes file type and size -->
<a href="/report.pdf">Download annual report (PDF, 2.4 MB)</a>
```

### External Links

```html
<!-- ✅ Good: Indicate external links -->
<a href="https://github.com" target="_blank" rel="noopener noreferrer">
  View the project on GitHub (opens in new tab)
</a>
```

## Exceptions

- Evaluate the rendered experience before treating a static-code smell as a blocker; interaction timing, browser behavior, and assistive technology output often determine severity.
- Not every secondary accessibility issue deserves equal weight; prioritize the issue that most directly blocks perception, operation, or understanding.
- Avoid adding redundant markup or ARIA solely to satisfy a rule when a simpler semantic implementation would eliminate the issue entirely.

## Verification

### Automated Checks

- Inspect the browser accessibility tree or accessibility pane for the relevant element, role, or accessible name.
- Run an automated accessibility checker such as axe or Lighthouse where applicable.

### Manual Checks

- Test the affected UI with keyboard-only navigation and confirm the rule holds in the rendered experience.
- Re-test one representative user flow with a screen reader if this rule affects a key interaction.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall