SiteLint documentation and guidelines

Download links should clearly identify the downloaded file and indicate its file type and size.

Description

A download link that simply reads Get the file or Click here forces every visitor to start a transfer before finding out what arrives. When the anchor text names the file, states its format, and gives its size, people can judge before committing – and screen reader users, who often navigate a list of links out of context, get the same information from the accessible name that sighted users read visually.

This SiteLint rule locates every link that behaves like a download – it carries the download attribute, it points at a file extension such as .pdf or .zip, or its text begins with a download verb such as Download or Pobierz – then inspects the visible link text for a file type and a file size. Missing information produces three distinct findings: neither type nor size present, size present without type, and type present without size. Labeling links clearly is a long-standing usability practice endorsed by the W3C Understanding document on link purpose in context, and it also feeds contextual meaning to search engines that evaluate link anchor text.

Disabilities impacted

  • Visual: sighted users who scan a page of download links see only a filename or a generic label, so they must click and wait for the transfer to start before learning the format and the download weight, which matters most on metered or slow connections.
  • Cognitive: users with cognitive or learning disabilities cannot predict the commitment a download represents. A file described as a short PDF may turn out to be a 900 MB archive, and an unlabeled .exe carries far more risk than a labeled 1.2 MB PDF without any extra reading effort.
  • Motor: users who operate the page by voice, switch, or head pointer frequently activate the wrong link when several anchors read identically. Distinct, descriptive labels give voice control users unambiguous spoken commands to target.
  • Screen reader users: links are commonly listed out of context, so a link named only Download announces without any indication of the payload. Textual file type and size information is announced as part of the link name, restoring that missing context.

Why it matters

Descriptive download links behave like a built-in user agent. They let visitors abort a 4 GB video before it starts, let them skip a compressed archive when they only wanted a spreadsheet, and let them recognize a file format they cannot open before wasting time on it. On metered connections, roaming, and assistive technology setups where every kilobyte and every download prompt has a cost, that information is a practical safeguard rather than a nicety.

The same clarity improves machine consumption. Search engines treat anchor text as a strong relevance signal, and a bare Download keyword repeated across dozens of links tells a crawler nothing about which asset a page offers. Teams also gain maintainability: when every link name states format and size, a stale label becomes a visible signal that the file changed and the label needs updating. Format disclosure additionally supports ADA and Section 508 expectations that users be able to anticipate the nature of a file before transferring it, particularly for screen reader and low-bandwidth users.

Coding problems and solutions

Common coding problems

  • Generic link text: labels such as Click here, Get started, or a lone Download name the action but never the payload, so the user has no way to know what the transfer will deliver.
  • Filename without extension: Annual-report-2025 hides the format, forcing the user to start the download to discover whether it is a PDF, a spreadsheet, or an archive.
  • Extension without size: Annual-report-2025.pdf states the type but not the weight, so mobile and low-bandwidth visitors cannot judge whether the transfer is reasonable.
  • Unlabeled icon links: a download link built from an icon font, a sprite, or a background image with a bare aria-label="download" exposes no filename, format, or size in the accessible name.
  • Dynamic size not synchronized: JavaScript updates the Content-Length or the stored asset but leaves the static size text in the markup, so the published size silently drifts from the real file.
  • Raw filename with URL encoding: quarterly%20results%20(final)%20v2.pdf exposes percent escapes and internal version suffixes, and usually still lacks the size a visitor needs before committing.
  • Size stated without a unit: Budget spreadsheet 2400 gives a bare number, so the unit is ambiguous and the file type may be missing entirely.

How to fix it

Write the anchor text as a short phrase that includes the human-readable filename, the file extension, and the download size, with the size expressed in a real unit. Keep the descriptive words inside the anchor so the accessible name carries them automatically.

Incorrect example
<a href="/files/annual-report-2025.pdf" download>Download</a>

<a href="/files/annual-report-2025.pdf">Annual report 2025</a>

<a href="/files/dataset.zip" download>dataset.zip</a>

<a href="/files/installer.exe" download>
  <span aria-hidden="true">&#x2193;</span>
  <span class="visually-hidden">Download</span>
</a>
Correct example
<a href="/files/annual-report-2025.pdf" download>
  Annual report 2025 (PDF, 10 pages, 2.4 MB)
</a>

<a href="/files/dataset.zip" download>
  Open data dataset (ZIP, 128 MB)
</a>

<a href="/files/installer.exe" download>
  Windows installer (EXE, 84 MB)
</a>

Keep the accessible name in sync with the visual label

When a link is built from an icon, keep the visible text as the accessible name. If you must add extra context for screen reader users, hide the redundant text visually rather than replacing the visible label with an aria-label that omits the filename, format, and size.

Incorrect example
<a href="/files/user-guide.pdf" download aria-label="Download">
  <span aria-hidden="true">&#x2193;</span>
</a>

<a href="/files/user-guide.pdf" download>
  <span class="visually-hidden">Download</span>
  <span aria-hidden="true">Get the PDF</span>
</a>
Correct example
<a href="/files/user-guide.pdf" download>
  <span aria-hidden="true">&#x2193;</span>
  User guide (PDF, 10 pages, 5.1 MB)
</a>

<a href="/files/user-guide.pdf" download>
  <span class="visually-hidden">Download the </span>User guide (PDF, 10 pages, 5.1 MB)
</a>

Generate the size and format from a single source of truth

Hard-coded sizes drift the moment a file is replaced. Read the byte length from the stored asset at build time or serve it from a JSON manifest, and render the label from that single source so the markup, the manifest, and the file on disk cannot disagree.

Incorrect example
<!-- Size typed by hand, already wrong after the file was re-exported -->
<a href="/files/guide.pdf" download>User guide (PDF, 10 pages, 5.1 MB)</a>
Correct example
<!-- manifest.json: { "guide.pdf": { "bytes": 5346289 } } -->
<script>
  const formatBytes = (bytes) => `${(bytes / 1048576).toFixed(1)} MB`;

  const renderDownloadLink = (asset) => {
    const anchor = document.querySelector('[data-download="guide.pdf"]');

    if (anchor === null) {
      return;
    }

    anchor.textContent = `${asset.label} (${asset.extension.toUpperCase()}, ${formatBytes(asset.bytes)})`;
  };

  globalThis.fetch('/assets/manifest.json')
    .then((response) => response.json())
    .then((manifest) => renderDownloadLink(manifest['guide.pdf']))
    .catch((error) => {
      console.error('Download manifest failed to load', error);
    });
</script>

<a href="/files/guide.pdf" download data-download="guide.pdf">User guide</a>

Describe the file in a surrounding list or table

When a page offers many files, present each one in a list or table where a column states the format and another states the size. The row header then holds the file name, and each link can read naturally without repeating every attribute in the anchor text, while the format and size remain programmatically available to assistive technology.

Incorrect example
<ul>
  <li><a href="/files/whitepaper.pdf" download>Whitepaper</a></li>
  <li><a href="/files/case-study.pdf" download>Case study</a></li>
  <li><a href="/files/pricing.xlsx" download>Pricing</a></li>
</ul>
Correct example
<table>
  <caption>Available resources</caption>
  <thead>
    <tr>
      <th scope="col">Resource</th>
      <th scope="col">Format</th>
      <th scope="col">Size</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">
        <a href="/files/whitepaper.pdf" download>Whitepaper</a>
      </th>
      <td>PDF</td>
      <td>1.8 MB</td>
    </tr>
    <tr>
      <th scope="row">
        <a href="/files/pricing.xlsx" download>Pricing</a>
      </th>
      <td>XLSX</td>
      <td>96 KB</td>
    </tr>
  </tbody>
</table>

If you consider adding a title attribute to a short link such as Whitepaper (PDF, 1.8 MB) or to a file-type abbreviation such as PDF, treat it as a redundant hint only. The information must already exist in the visible text or in table cell content.

Note that support for the title attribute varies across screen readers. For instance, VoiceOver by default has Hints set to ‘Never’ or ‘Speak after delay’, which may prevent the title from being announced. Do not rely solely on title for critical information.

Known Limitations

  • Visible text only: the check reads the rendered text of the link, so a size shown in a title attribute, a tooltip, a aria-label, or a data-size attribute is treated as absent even though some users can perceive it.
  • English and Polish verbs only: the download-verb pattern matches Download and Pobierz, so a download link phrased in French, German, or Spanish is not recognized unless the download attribute or a recognized file extension is present.
  • Fixed extension list: file types outside the frozen list of roughly fifty extensions, including modern containers such as .avif, .woff2, .json, or .parquet, are not recognized as download targets by the extension check.
  • Size formats: a size written as 1.2M without a space, as 2400 KB with a thousands separator, or as a localized 2,4 Mo in French does not match the size pattern and is reported as missing.
  • Context-blind link targeting: the rule inspects individual anchors and cannot understand the surrounding page, so a link reading Download the report (PDF) is reported for a missing size even when the size is stated in the paragraph directly above the link.
  • Shadow DOM and portals: links rendered inside shadow roots or injected through a portal into a detached subtree are missed, because the query only collects anchors present in the audited document tree.
  • Frames and post-load mutation: anchors inside iframes are audited only if that frame is included in the scan, and download links rendered only after a user interaction may not exist at the time the rule runs.
  • No accuracy verification: the rule confirms that a size and a format are stated, not that they are correct, so a label claiming 2 MB on a 200 MB file passes without complaint.

Resources

Rule

  • Audit: accessibility
  • Standard: SiteLint
  • Level: Best practices
  • Success Criteria: N/A
  • Rule ID: download_link_missing_information