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
.execarries far more risk than a labeled1.2 MB PDFwithout 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 loneDownload
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-Lengthor 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
Name the file, format, and size in the link text
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.
<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">↓</span>
<span class="visually-hidden">Download</span>
</a><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.
<a href="/files/user-guide.pdf" download aria-label="Download">
<span aria-hidden="true">↓</span>
</a>
<a href="/files/user-guide.pdf" download>
<span class="visually-hidden">Download</span>
<span aria-hidden="true">Get the PDF</span>
</a><a href="/files/user-guide.pdf" download>
<span aria-hidden="true">↓</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.
<!-- 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><!-- 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.
<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><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.
Known Limitations
- Visible text only: the check reads the rendered text of the link, so a size shown in a
titleattribute, a tooltip, aaria-label, or adata-sizeattribute is treated as absent even though some users can perceive it. - English and Polish verbs only: the download-verb pattern matches
Download
andPobierz
, so a download link phrased in French, German, or Spanish is not recognized unless thedownloadattribute 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, as2400 KB
with a thousands separator, or as a localized2,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
- Link purpose in context: explains how descriptive link text supports users who navigate lists of links out of context, the scenario this rule targets, at W3C WAI Understanding link purpose in context.
- HTML download attribute: the reference for the
downloadattribute that flags a link as a download for this rule, at MDN HTML anchor download attribute. - Accessible name computation: shows how anchor text and
aria-labelcombine into an accessible name, useful when restructuring icon links, at W3C Accessible Name and Description Computation. - Content-Length semantics: documents the response header a server reports for file size, the value worth mirroring in the link label, at MDN Content-Length header.
- Link text best practice: collects current writing guidance on descriptive link text, at W3C WAI link purpose guidance.
Rule
- Audit: accessibility
- Standard: SiteLint
- Level: Best practices
- Success Criteria: N/A
- Rule ID:
download_link_missing_information