Front-End Checklist User Guide

The Front-End Checklist is an exhaustive, priority-tagged checklist of everything to verify before shipping an HTML page to production. It is not software you install — there is nothing to compile, no daemon to run, and no API. The product is a single, long README.md file you read, copy into your own workflow, and tick off, with companion configuration that maintains its quality (Prettier, markdownlint, Lychee).

This guide is for front-end developers, QA engineers, technical leads, and team architects who want to apply the checklist to real launches — as a pre-launch gate, a code-review reference, an onboarding artifact, or the seed of an internal team standard. It explains what the checklist covers, how to decode its priority system, how to run focused passes (accessibility-only, SEO-only, performance triage), and how to contribute back when you spot a gap.

Important

The LICENSE file in the repository is Creative Commons CC0 1.0 Universal (public-domain dedication). You may copy, fork, translate, embed, or rebrand the checklist for any purpose — including commercial — with no attribution required. The package.json license field reads "CC-BY-4.0", which is a known inconsistency; the LICENSE file's CC0 1.0 text is the authoritative legal grant. See §3 Configuration for the resolution.

Table of Contents

1. Quick Start
2. Installation
3. Configuration
4. Core Usage
5. Common Tasks
6. Troubleshooting
7. FAQ

1. Quick Start

You do not install the Front-End Checklist. You read it.

The 30-second path: read it on GitHub

1. Open github.com/thedaviddias/Front-End-Checklist.
2. GitHub renders README.md as the landing page.
3. Use the Table of Contents at the top to jump to a section.
4. Scan items by their inline coloured priority badge: red ([image: High] High), orange ([image: Medium] Medium), green ([image: Low] Low).

That is enough to use the checklist on a real launch. Everything below is optional polish.

The 2-minute path: a tickable copy in your own repo

GitHub renders - [ ] task-list checkboxes as interactive only inside Issues and Pull Requests — not on a repo's README landing page. To actually click checkboxes, paste the content into a fresh Issue:

1. In your own product repository, click Issues → New issue.
2. Title it Launch checklist — <project>.
3. Open the upstream README in Raw mode (raw README.md) and copy the full text.
4. Paste into the Issue body.
5. Submit new issue. Every - [ ] item is now an interactive checkbox you and any collaborator can tick.

Tip

The fastest way to use the checklist on a real project is: create a pre-launch Issue titled Launch checklist — <project>, paste the full upstream README.md content into the body, and assign reviewers. GitHub will let every collaborator tick items in place. Pin the Issue after launch as a historical record of what was checked, what was waived, and who approved each waiver.

Other entry paths

Minimal example: an item, decoded

A typical line in the README looks like this:

- [ ] **Doctype:** ![High][high_img] The Doctype is HTML5 and is at the top of all your HTML pages.

```html
<!-- HTML5 Doctype (Uppercase preferred) -->
<!DOCTYPE html>

• 📖 Determining the registered doctype - W3C

That single bullet packages five things: a checkbox, a labelled rule (**Doctype**), a coloured priority badge (![High] High = mandatory), a one-sentence rationale, a copy-pasteable HTML example, and a link to the W3C tip article (📖 = documentation). Internalize the four visual signals — checkbox, label, badge, emoji — and you can scan the whole 850-line file in minutes.

### What to try next

- [§2 Installation](#2-installation) — three ways to keep a working copy (browser, clone, fork).
- [§4 Core Usage](#4-core-usage) — every category enumerated, priority breakdown, resource emoji legend.
- [§5 Common Tasks](#5-common-tasks) — full pre-launch pass, accessibility-only audit, SEO-only audit, performance triage, security review, contribute a missing item.

---

## 2. Installation

The Front-End Checklist has nothing to compile, install via npm, or deploy. "Installation" means *getting a copy you can read or edit*.

### 2.1 Read in the browser (zero-install)

Just visit [github.com/thedaviddias/Front-End-Checklist](https://github.com/thedaviddias/Front-End-Checklist). No tooling required.

### 2.2 Clone for offline use

```bash
git clone https://github.com/thedaviddias/Front-End-Checklist.git
cd Front-End-Checklist

Cloning into 'Front-End-Checklist'...
remote: Enumerating objects: ...
Resolving deltas: ..., done.

Open README.md in any Markdown viewer (VS Code, Typora, Obsidian, grip, the GitHub Markdown preview). Everything ships in one file. The clone is ~5 MB.

Important

The priority badges ([image: High], [image: Medium], [image: Low]) load via Markdown image references defined at the very bottom of README.md. The URLs point at raw.githubusercontent.com/thedaviddias/Front-End-Checklist/refs/heads/main/data/images/priority/*.svg. If your viewer cannot reach raw.githubusercontent.com (corporate proxy, air-gapped environment), the badges will appear as broken-image icons. The text is unaffected; the colour cue is lost. See §6 Troubleshooting for fixes.

2.3 Fork for team customization

If you want to maintain a team-tailored version that diverges from upstream:

1. Click Fork on github.com/thedaviddias/Front-End-Checklist.
2. Clone your fork: git clone https://github.com/<you>/Front-End-Checklist.git.
3. Edit README.md to add, remove, or reprioritize items for your industry (government → promote a11y items to High; healthcare → promote security headers; e-commerce → emphasize SEO and Performance).
4. Publish or keep private — CC0 1.0 imposes no constraint.

Tip

A fork is the right answer when your industry has stricter rules than the generic web (government accessibility, HIPAA, PCI-DSS). Promote relevant items by editing the priority image reference from low.svg to medium.svg, or medium.svg to high.svg. Document each promotion in a fork CHANGELOG.md so your team understands why your version is stricter than upstream.

2.4 Install the maintainer's tooling (only if contributing)

If you plan to open a pull request against the upstream, install Node + pnpm and the dev dependencies. This is not required to use the checklist — only to format-check it.

# Install pnpm (if not already)
npm install -g pnpm

# In the repo root
pnpm install

Lockfile is up to date, resolution step is skipped
Done in 1.2s

This installs three devDependencies pinned in pnpm-lock.yaml:

Note

The repo uses pnpm (pnpm-lock.yaml is committed). npm install also works but produces a competing package-lock.json that you should delete before committing. Stick with pnpm to keep PR diffs clean.

2.5 System requirements

For reading: a browser, or a Markdown viewer. Nothing else.

For contributing (running the dev tooling):

2.6 Verify the install

pnpm format:check

Checking formatting...
All matched files use Prettier code style!

If the README is Prettier-clean, this prints the success line and exits 0. If formatting drift exists locally, it lists the affected files. Run pnpm format:fix to apply Prettier and then re-run markdownlint.

3. Configuration

End users do not configure the Front-End Checklist — it is a static document. The "configuration" surfaces are:

• Priority interpretation — three coloured badges (Low / Medium / High) you triage by.
• Resource emoji legend — three emojis (📖 / 🛠 / 📹) classifying follow-up bullets.
• Maintainer tooling config — five files (.editorconfig, .prettierrc, .markdownlint.json, lychee.toml, package.json) that govern the repo's editorial pipeline.

For the deep configuration reference (every key in every file with its rationale), see the Admin Guide → §3 Configuration Reference.

3.1 Priority levels

Every checklist item carries one of three priority badges, rendered inline as a small coloured SVG.

Important

On a time crunch? Run the High-priority items first. They are the set that, if skipped, will break something visible or measurable in production.

The recommended triage when you cannot complete every item before launch:

1. Pass 1 — High only. Walk every section and tick every [image: High] item. If any are failing, they block the launch.
2. Pass 2 — Medium, scoped by section. Prioritize sections that match your product's risk profile. An e-commerce page must clear the Medium items in Security, Performance, and SEO; an internal dashboard can safely defer Medium items in SEO and Social meta.
3. Pass 3 — Low, post-launch. Turn Low items into a post-launch backlog ticket rather than delay the release.

Caution

The priority tiers are the author's opinions, not a spec. If your industry has stricter rules — government accessibility (Section 508, EN 301 549), security in healthcare (HIPAA), privacy in finance (PCI-DSS), or content rules in regulated markets — promote the relevant items to High in your own fork and document why in a fork CHANGELOG.md.

3.2 Resource emoji legend

Supplementary bullets under each check point to external material. Three emojis classify the kind of material:

Note

The emojis are applied inconsistently on a small number of items — the checklist is hand-maintained and the occasional bullet is missing its leading emoji. When present, the emoji is the authoritative type tag; when absent, infer from context.

3.3 License and attribution

The repository's LICENSE file is Creative Commons CC0 1.0 Universal (public-domain dedication). You can copy, fork, translate, embed, or rebrand the checklist for any purpose, including commercial use, with no attribution required.

The package.json license field reads "CC-BY-4.0", which conflicts with LICENSE. The LICENSE file is legally authoritative: the SPDX, ChooseALicense, and npm conventions all treat it as controlling when it differs from package.json. For all practical purposes, the checklist is CC0 1.0.

Warning

If your legal team is strict about license metadata, raise the package.json field as a known inconsistency and recommend the upstream patch noted in the Admin Guide → §12 Potential Improvements. Until upstream fixes it, document in your own fork's README.md that you treat the work as CC0 1.0 per the LICENSE file.

3.4 Anchor-link conventions

Every H2 and H3 heading in README.md produces a GitHub-style anchor that survives edits as long as the heading text does not change. Use these for stable citations during code review:

https://github.com/thedaviddias/Front-End-Checklist#accessibility
https://github.com/thedaviddias/Front-End-Checklist#meta-tag
https://github.com/thedaviddias/Front-End-Checklist#headings

Anchor slugs are GitHub auto-generated: lowercase the heading, strip punctuation, replace spaces with hyphens, drop leading emoji. ## 📚 Table of Contents becomes #-table-of-contents. The trailing ? on ## How to use? is stripped, producing #how-to-use.

4. Core Usage

The checklist's content is its product. This section enumerates every category, the kind of items inside, and what they do not cover.

4.1 The category structure

README.md is a strictly hierarchical flat-section document. The full top-level structure at commit 09d56df (2025-02-14):

🗂 Front-End Checklist
├── 📚 Table of Contents
├── How to use?
├── Head
│   ├── Meta tag
│   ├── HTML tags
│   └── Social meta
├── HTML
│   ├── Best practices
│   └── HTML testing
├── Webfonts
├── CSS
│   ├── Performance
│   └── CSS testing
├── Images
│   └── Best practices
├── JavaScript
│   ├── Best practices
│   └── JavaScript testing
├── Security
│   ├── Scan and check your web site
│   └── Best practices
├── Performance
│   ├── Best practices
│   ├── Preparing upcoming requests
│   └── Performance testing
├── Accessibility
│   ├── Best practices
│   ├── Headings
│   ├── Semantics
│   ├── Form
│   └── Accessibility testing
├── SEO
├── Translations
├── Support
├── Contributors
├── Backers
├── Sponsors
└── License

Ten technical categories (Head through SEO) and six meta categories (Translations through License).

4.2 The ten technical categories

Note

Some items are dated. The project's last substantive content edit was commit 09d56df on 2025-02-14. You will find references to Internet Explorer conditional comments, Modernizr, and jQuery-era performance advice that modern projects can usually skip. Treat them as informational; the bulk (accessibility, SEO, security headers, image optimization, CSS performance) remains current.

4.3 What the checklist deliberately does not cover

4.4 Reading any single item

Every technical item follows the same micro-structure. Internalize it once, scan the whole file in minutes:

- [ ] **Label:** ![Priority][priority_img] Short rationale sentence, sometimes with
      wrapped continuation lines.

```html
<!-- Optional code example showing the correct markup -->

• 📖 Reference link title
• 🛠 Tool link title

The five parts:

1. **`- [ ]`** — a GitHub task-list checkbox. Renders as an interactive checkbox in Issues and Pull Requests.
2. **`**Label:**`** — the short name of the check (for example, **Doctype**, **Canonical**, **Alt text**).
3. **`![Priority][priority_img]`** — an image reference resolving to one of three SVG badges. Sits inline immediately after the label.
4. **Rationale sentence** — one or two lines explaining what the check means and why it matters. Sometimes includes a concrete threshold (for example, "no more than 150 characters" for `meta description`).
5. **Code block** *(optional)* — a minimal copy-pasteable example, often wrapped in `<!-- prettier-ignore-start -->` guards in the source so Prettier does not reflow the HTML.
6. **Bullet list of resources** *(optional)* — each starts with 📖 / 🛠 / 📹.

> [!TIP]
> Four visual signals per item: the **checkbox** (are we done?), the **bold label** (what is this?), the **coloured priority badge** (how important is this?), and the **resource emoji** on follow-up bullets (is this a doc, a tool, or a video?). Internalize the four and you can scan the file in minutes.

### 4.5 Approximate item counts by priority

At commit `09d56df`, the README contains roughly:

| Tier | Count | Share |
|---|---|---|
| ![High] High | ~50 | ~40 % |
| ![Medium] Medium | ~40 | ~30 % |
| ![Low] Low | ~40 | ~30 % |

The exact counts drift as the file is edited. Do not memorize the numbers; use the badges as your source of truth on any given read. To count locally:

```bash
grep -c "high_img" README.md     # High count
grep -c "medium_img" README.md   # Medium count
grep -c "low_img" README.md      # Low count
grep -c "priority_img" README.md # Total items

50
40
40
130

4.6 Section cross-reference

Use this routing table for "where do I look for X?" questions:

5. Common Tasks

Six recipes covering the realistic ways a team applies the checklist.

5.1 Recipe: full pre-launch pass

Goal: gate a launch on a complete walk-through of every checklist item.

Prerequisites: a GitHub Issues-enabled repo for the product being launched; a maintainer with the authority to block the deploy.

Steps:

• [x] Create an Issue in your project repo titled Launch checklist — <project> — <YYYY-MM-DD>.
• [x] Open the upstream README at raw.githubusercontent.com/thedaviddias/Front-End-Checklist/main/README.md, copy the full content, and paste into the Issue body.
• [x] Assign one owner per category (Head, HTML, CSS, Images, etc.) — or one owner total for small teams.
• [x] Pass 1: every owner ticks every [image: High] item in their category, or files a sub-issue for each that fails.
• [x] Pass 2: Medium items, scoped by category to the product's risk profile.
• [x] Pass 3: Low items become post-launch backlog tickets.
• [x] Block the deploy until every High box is ticked or carries a written waiver comment.

Verify: open the Issue and confirm every High checkbox is ticked. If a High item has a waiver, the comment should reference an approver and a follow-up ticket.

Tip

Pin the Issue after launch and never close it. It becomes a historical record of what was checked, what was waived, and who signed off — invaluable when the same product launches a feature six months later.

If it fails: if a critical High item cannot be fixed before launch, the responsible engineering lead must approve a written waiver in the Issue thread, with a follow-up ticket linked. No silent waivers.

5.2 Recipe: accessibility-only audit

Goal: ship an accessibility-improved version of an existing page without doing a full launch checklist pass.

Prerequisites: a copy of the page in a staging environment; one of the linked screen readers installed (NVDA on Windows, VoiceOver on macOS, Orca on Linux); the WAVE browser extension or wave.webaim.org.

Steps:

• [x] Read the Accessibility category in the upstream README (github.com/thedaviddias/Front-End-Checklist#accessibility).
• [x] Walk all five Accessibility subsections in order:
  1. Best practices — progressive enhancement, color contrast (WCAG AA minimum, AAA on mobile), zoom behavior.
  2. Headings — exactly one <h1> per page, semantic heading hierarchy, no level skips.
  3. Semantics — HTML5 semantic elements (<header>, <main>, <nav>, <article>, <section>, <footer>), valid input types.
  4. Form — every input has a <label>, errors are announced, required fields marked.
  5. Accessibility testing — WAVE, axe-core, keyboard-only nav, screen-reader pass.

Verify: run WAVE on the page and confirm 0 errors, 0 contrast errors. Tab through the page using only the keyboard — every interactive element receives visible focus, focus order matches visual order, no focus traps.

Important

WCAG AA is the floor, not the ceiling. For public-sector products, government, education, healthcare, or finance, target WCAG AA at minimum and consider AAA for color contrast and link recognition. Use axe DevTools and Pa11y for automated coverage; nothing replaces a manual screen-reader pass.

If it fails: if a screen reader cannot complete a primary task (sign in, submit a form, navigate the menu), block the launch. Accessibility regressions are very expensive to fix after launch and create legal exposure.

5.3 Recipe: SEO-only audit

Goal: verify a page's SEO basics before submitting to Google Search Console.

Prerequisites: the page deployed to a public URL (or accessible via Search Console's URL Inspection on a verified property); access to Google Search Console for the domain.

Steps:

• [x] Read the SEO category in the upstream README (github.com/thedaviddias/Front-End-Checklist#seo).
• [x] Tick the SEO [image: High] items: Google Analytics installed and reporting, Search Console verified, heading logic in place, sitemap.xml exists and references the page, robots.txt exists and does not block the page, structured data (JSON-LD recommended) validates in Google's Rich Results Test.
• [x] Tick the cross-cutting SEO items in Head: <title> tag is unique and < 55 characters, <meta name="description"> is unique and < 150 characters, canonical URL is correct, hreflang and x-default are correct for multilingual sites.
• [x] Submit the URL via Search Console → URL Inspection → Request Indexing.

Verify: Google Rich Results Test reports no errors on the JSON-LD; Search Console URL Inspection reports the URL as Crawlable and Indexable; PageSpeed Insights reports no Core Web Vitals warnings.

Note

The checklist mentions PageSpeed ≥ 90 as a target. Modern PageSpeed Insights uses Lighthouse audits (LCP, TBT, CLS). 90 is a directional goal, not a hard gate. Aim for "all green" Core Web Vitals first, then push the score.

If it fails: if Search Console reports the page as Not Indexed even after submission, check robots.txt for accidental disallow rules, check the <meta name="robots"> tag for noindex, and check the canonical URL — a wrong canonical silently de-indexes the page in favor of a non-existent target.

5.4 Recipe: performance triage

Goal: diagnose why a page is slow and apply the highest-leverage fix from the checklist.

Prerequisites: access to PageSpeed Insights, Chrome or Firefox DevTools, and the ability to deploy a fix to a staging URL.

Steps:

• [x] Run PageSpeed Insights against the slow page. Note the LCP, TBT, CLS, and FID/INP scores.
• [x] Read the Performance category in the upstream README (github.com/thedaviddias/Front-End-Checklist#performance).
• [x] Cross-reference your slow metric to the checklist:
  • Slow LCP? Check Performance → Best practices for image lazy-loading, image format, critical-CSS extraction, and HTML minification. Check Images for <picture> / srcset / width / height.
  • High TBT? Check JavaScript → Best practices for async/defer, library count, library size. Check CSS → Performance for unused-CSS removal.
  • Bad CLS? Check Images for explicit width / height, Webfonts for font-display: swap and reserved space, JavaScript for late-injected DOM.
  • Slow TTFB? Out of scope for the checklist — investigate server-side rendering, CDN cache headers, and origin compute.
• [x] Pick the single [image: High] item that addresses your worst metric. Apply the fix on staging.
• [x] Re-run PageSpeed Insights. Compare scores.

Verify: the worst metric improves by ≥ 20 % on the staging URL. If not, you fixed the wrong thing — re-read the metric definition and pick a different [image: High] item.

Tip

The checklist names a 170 KB gzipped budget for the critical render path. This is a 2018-era target that aligns reasonably with modern Core Web Vitals: at typical 3G speeds, 170 KB gzipped translates to roughly 1 second of download time, which leaves room for an LCP under 2.5 s. Treat 170 KB as the target; treat 250 KB as the upper bound where Core Web Vitals start failing on real-world mobile.

If it fails: if PageSpeed flags items not covered in the main checklist (CDN cache headers, server-side rendering, edge compute), pull in the Front-End Performance Checklist sibling repo, which covers the deeper layers.

5.5 Recipe: security review

Goal: verify a page's security headers, CSP, and basic hardening before exposing it on the public internet.

Prerequisites: a publicly reachable URL; access to a CLI or a tool like securityheaders.com; knowledge of which third-party scripts the page loads.

Steps:

• [x] Read the Security category in the upstream README (github.com/thedaviddias/Front-End-Checklist#security).
• [x] Run securityheaders.com against the URL. Confirm:
  • HTTPS is enforced (redirect from http:// to https://).
  • HSTS is present with max-age ≥ 31536000 (one year), includeSubDomains, and ideally preload.
  • X-Content-Type-Options: nosniff is set.
  • X-Frame-Options: DENY or SAMEORIGIN is set (or use CSP frame-ancestors).
  • Content Security Policy (CSP) is set with at least default-src 'self' and explicit allow-lists for inline scripts and third-party origins.
• [x] Verify all third-party scripts are loaded over HTTPS, not HTTP.
• [x] Verify forms use POST + CSRF tokens (server-side concern; the checklist points the way).
• [x] Test for XSS by injecting <script>alert(1)</script> into every text input. Confirm output is HTML-escaped.

Verify: securityheaders.com returns at least an A grade; Mozilla Observatory returns at least a B; SSL Labs returns at least an A.

Caution

A badly-configured CSP silently breaks the page by blocking legitimate scripts. Roll out CSP in Content-Security-Policy-Report-Only mode first, monitor the report endpoint for false positives, then promote to enforcement mode. Never deploy a fresh CSP straight to production.

If it fails: if securityheaders.com flags a missing header that is set correctly on the origin, the issue is usually a CDN or reverse proxy stripping headers. Check your CDN's response-header passthrough rules.

5.6 Recipe: contribute a missing item

Goal: add a new check to the upstream Front-End Checklist via a pull request.

Prerequisites: a GitHub account; Node + pnpm installed (see §2.4 Install the maintainer's tooling); the proposed item is genuinely missing (search the README first).

Steps:

• [x] Read CONTRIBUTING.md in the upstream repo for the contribution rubric.

• [x] Fork the repo, clone your fork, create a branch: git checkout -b add-<item-name>.

• [x] Open README.md and locate the right category. Insert your item at the topical right place (alphabetical within a subsection, or grouped near related items):

  - [ ] **Your label:** ![Medium][medium_img] Your one-or-two-line rationale.
  
  ```html
  <!-- Optional minimal code example wrapped in prettier-ignore -->
  <!-- prettier-ignore-start -->
  <element attribute="value">
  <!-- prettier-ignore-end -->
  

  • 📖 Authoritative source
  • 🛠 Tool to verify

• [x] Run the format pipeline:

  pnpm format:fix
  

  README.md 1.2s
  

• [x] Commit and push:

  git commit -am "Add <category>: <item label>"
  git push -u origin add-<item-name>
  

• [x] Open a Pull Request against thedaviddias/Front-End-Checklist:main. PR description should explain: what the item is, why it belongs in the checklist, what tier you chose and why, and one concrete way to verify it.

Verify: PR shows green CI for pnpm format:check, and the link-check (Lychee) reports any new external URL as live.

Warning

Single-purpose PRs merge fastest. One item, one rationale, one or two reference links. PRs that bundle five new items, reformat unrelated sections, or add framework-specific advice (React-only, Vue-only) tend to sit unreviewed or get rejected with a redirect.

If it fails: if the PR sits unreviewed for several weeks, leave one polite reminder comment on the PR. The project is hand-maintained by David Dias on a best-effort cadence — patience pays off; a duplicate PR or a tag-the-author-on-Twitter approach does not.

6. Troubleshooting

The checklist is a Markdown file on GitHub, so most troubleshooting is editorial rather than operational.

Error: A 📖 or 🛠 link returns 404 or redirects to a parked domain

Cause: linked tools and articles age. The repo runs a Lychee link-check (lychee.toml) that catches most rot, but false negatives occur — tools that quietly become abandonware, articles whose hosts go down briefly, or ownership transfers.

Solution:

1. Search the article title on the Wayback Machine — the original is often archived.
2. For tools, search the tool name plus "alternative" — front-end testing tools have long half-lives and usually have a modern replacement.
3. Open an issue on the repo titled Broken link: <item name> and reference the item's anchor.

Prevention: when you cite a checklist item in code review, append ? to the anchor URL to defeat the raw.githubusercontent.com cache, or pin to a commit SHA when the item is essential to your team's standard.

See issue #521 (GA Checker link rot) as a real example of how the project handles broken links.

Error: A priority tier seems wrong for my context

Cause: the tiers are author opinions calibrated for a generic public website. Industries with stricter rules (government accessibility, HIPAA, PCI-DSS, EU regulations) often require items the checklist marks Low or Medium to be treated as Mandatory.

Solution:

1. Fork the repo.
2. Edit the priority image reference for the affected items: ![Low][low_img] → ![High][high_img] (and analogous for Low → Medium, Medium → High).
3. Commit and document the change in a fork CHANGELOG.md.

Prevention: before adopting the upstream wholesale, read every Low and Medium item once, ask "would my industry tolerate skipping this?", and reprioritize as needed in your fork.

Error: GitHub renders the priority badges as broken images

Cause: the priority badges load from raw.githubusercontent.com/thedaviddias/Front-End-Checklist/refs/heads/main/data/images/priority/{low,medium,high}.svg. If GitHub or your corporate proxy blocks raw.githubusercontent.com, the badges show as broken-image icons.

Solution:

1. Clone the repo and view README.md locally — the SVGs are in data/images/priority/ and load via your filesystem.
2. In your fork, edit the link-reference URLs at the bottom of README.md to relative paths:

   [low_img]: ./data/images/priority/low.svg
   [medium_img]: ./data/images/priority/medium.svg
   [high_img]: ./data/images/priority/high.svg
   

3. Add raw.githubusercontent.com to your proxy allow-list.

Prevention: when you create an internal fork, immediately swap the URL form to relative paths so your team's access does not depend on raw.githubusercontent.com.

Error: I cannot tick the checkboxes on the repo landing page

Cause: GitHub renders - [ ] as interactive checkboxes only inside Issues and Pull Requests, not on a repo's README landing page. This is a GitHub product decision, not a repo bug.

Solution: create an Issue in your own product repository, paste the upstream README's content into the Issue body, and submit. Every - [ ] is now an interactive checkbox you and any collaborator can tick.

Prevention: see §5.1 Recipe: full pre-launch pass for the canonical Issue-based workflow.

Error: A virus scanner flagged the repo

Cause: false positive. The repo contains only Markdown, SVG, and configuration files — no executables. Scanners sometimes flag external links to older tools that themselves have been quarantined, or trigger heuristics on the high external-link density.

Solution:

1. Verify with a second scanner (VirusTotal accepts URL submissions).
2. Report the false positive to your scanner vendor with the repo URL as the known-good reference.
3. Whitelist the repo URL in your scanner.

See issue #549 "Virus?!?" for the canonical resolution thread on this exact concern.

Prevention: if your environment requires zero external network calls during scanning, clone the repo and view it offline.

Error: The README.md has a paragraph that appears twice

Cause: a content-duplication bug. The repo is hand-maintained, and occasional editing slips happen.

Solution: open a one-line PR removing the duplicate paragraph. See issue #522 for an example of this exact bug being reported and fixed.

Prevention: reviewers should read the diff carefully on PRs that re-flow long prose sections — Prettier-driven reflow can occasionally introduce duplicates.

Error: An item references a deprecated library or tool

Cause: tools age. Examples in the current checklist include older references to jQuery-era performance advice, Modernizr (maintenance mode since 2023), and the deprecated Twitter Card validator URL (replaced by X's internal debugger).

Solution: apply the principle of the item, substitute the modern tool. The item exists because the underlying problem (cross-browser compatibility, image format polyfills, social-card preview) still matters, even when the tool of choice has changed.

Prevention: when contributing, prefer evergreen sources (MDN, W3C, WHATWG specs) over tool-specific blog posts that age out.

Error: My PR was not reviewed

Cause: the project is hand-maintained by a single author (David Dias) and reviews are best-effort.

Solution:

1. Keep PRs small (one item, one rationale, one or two reference links).
2. Follow the existing formatting exactly.
3. Wait. After several weeks, leave one polite comment on the PR.

Prevention: do not open duplicate PRs. Do not @-mention the author on social media. Do not bundle five items into one PR — they take five times the review time.

Error: An item is ambiguous — "You don't have any JavaScript code inline"

Cause: some items are terse one-liners. The author's expectation is that you click the 📖 link for the full explanation.

Solution:

1. Click the linked 📖 article — it is almost always the longer explanation.
2. If no link is present, search MDN or a recent authoritative source for the item's label.
3. If still unclear, open an Issue requesting a rationale clarification.

Prevention: none — terseness is the format's nature. Trust the linked sources.

Error: An item conflicts with what another source says

Cause: front-end best practice has factions. The classic example is "concatenate CSS files into one" — ![High] here, but HTTP/2 multiplexing makes that advice dated for modern servers (the checklist acknowledges the exception inline with (Not for HTTP/2)).

Solution: prefer the newer, more specific source. Document the choice in your team's fork or internal standard so reviewers know why your team's version diverges.

Prevention: date-tag your fork's items with the spec or article version that justifies them. When the upstream's advice ages out, your fork's notes explain why you keep diverging.

Error: The repository looks abandoned — last commit is months old

Cause: "content stable" is different from "abandoned." The checklist's content covers foundational front-end concerns that do not change rapidly. A multi-month gap between commits is normal.

Solution:

1. Verify the author's activity by looking at his profile (github.com/thedaviddias) or the project's open issues for recent engagement.
2. If you must have an actively-maintained alternative, search for community forks (fork:true filter on GitHub).

Prevention: none. Slow cadence is part of the editorial model.

Error: Some code blocks are wrapped in <!-- prettier-ignore-start --> / <!-- prettier-ignore-end -->

Cause: these guards are for the maintainer's Prettier run. They stop Prettier from reflowing short inline HTML examples in ways that break readability.

Solution: ignore them. They have no effect on rendering in a browser or Markdown viewer.

Prevention: if you contribute a code block that Prettier mangles on pnpm format:fix, wrap it in the same guards.

Error: I want an offline, searchable copy

Cause: you are on a plane / locked-down network / want grep-style search.

Solution:

git clone https://github.com/thedaviddias/Front-End-Checklist.git
cd Front-End-Checklist
grep -ni "srcset" README.md

496:      - [ ] **Picture/Srcset:** ![Medium][medium_img] You use picture/srcset...

grep -ni <term> is the fastest way to jump to any check by keyword. For more polished offline usage, pipe through Pandoc:

pandoc README.md -o checklist.pdf --pdf-engine=xelatex

Prevention: clone the repo to a folder you sync (Dropbox, OneDrive, iCloud), and grep there.

7. FAQ

Q: Is the Front-End Checklist a software library I can install via npm?

No. The package.json in the repo exists only to run the maintainer's linters (prettier, markdownlint-cli, husky). There is no exported JavaScript, no main or exports field, and no runtime code. The product is README.md. End users do not run npm install.

Q: What version of the checklist does this guide describe?

Source commit 09d56df from 2025-02-14. The English README.md is the single source of truth. Subsequent commits may have added or edited items; consult the upstream main branch for the freshest version.

Q: Can I contribute a new item?

Yes. Read CONTRIBUTING.md, then open a PR that adds a new - [ ] **Label:** ![Priority][priority_img] rationale. line in the appropriate section. Include one 📖 or 🛠 reference link if possible. Small, single-purpose PRs merge fastest. See §5.6 Recipe: contribute a missing item for the full workflow.

Q: Can I contribute a translation?

The project does not maintain in-repo translations. Translations live as independent forks, each maintained by a different person. To add one: fork the repo, translate README.md into your target language, publish your fork, then open an issue on the upstream linking to your fork URL. The maintainer adds the row to the Translations section. See issue #511 (Persian Translation) as a template.

Q: Can I embed the checklist in a commercial product (SaaS, training course, book)?

Yes. The LICENSE file is CC0 1.0 Universal — a public-domain dedication. No attribution required, though attribution is appreciated. (Note: package.json lists CC-BY-4.0. The LICENSE file's CC0 text is legally authoritative.)

Q: Where can I discuss the checklist with other users?

The author publishes on X and runs a Discord server. The GitHub Issues page is for content reports and PRs, not general discussion.

Q: How do I print a clean PDF?

Open the GitHub README, press Ctrl+P / Cmd+P, save as PDF (~25-30 pages). For a more polished print, clone and pipe through Pandoc:

pandoc README.md -o checklist.pdf --pdf-engine=xelatex

Tune margins in a LaTeX template if needed.

Q: The checklist mentions Google PageSpeed ≥ 90. PageSpeed Insights now uses Lighthouse. Should I still aim for 90?

The 90 threshold is a directional rule of thumb, not a spec. The modern PageSpeed Insights score is composed from Lighthouse audits (LCP, TBT, CLS). Aim for "all green" Core Web Vitals first; treat 90 as a useful proxy.

Q: What is the difference between the Front-End Checklist, the Front-End Performance Checklist, and the Front-End Design Checklist?

The three are by the same author. The Front-End Checklist (this guide) is the launch-readiness generalist. The Performance Checklist is a deep dive on speed. The Design Checklist is a deep dive on visual fidelity. Most teams use all three: the main one for launch gating, Performance when investigating a slow page, Design during the design-to-code handoff.

Q: Some items reference Internet Explorer. Should I skip those?

For new projects that do not support IE — skip them. Conditional comments, IE-specific polyfills, and the msapplication-config tile metadata are mostly historical. Keep them only if you actively maintain a site with legacy IE users (rare outside specific enterprises, government, or embedded systems).

Q: Does the checklist cover accessibility in enough depth?

It covers WCAG AA fundamentals: heading hierarchy, lang, form labels, keyboard navigation, color contrast, alt text, screen-reader testing, visible focus. For a WCAG AA or AAA audit on a critical product, supplement with the W3C's WCAG 2.1 specification and tools like axe-core, Pa11y, or WAVE. The checklist points you to those resources but does not replace them.

Q: Why is there a lychee.toml in the repo?

To automate link-rot detection against the checklist's many external references. End users do not need to run Lychee locally — it is part of the maintainer's CI gate. See the Admin Guide → §3 Configuration Reference for the exact configuration.

Q: Is there an official mobile app or web app for ticking items?

No official one. Community forks have wrapped the checklist in small Vue / React / Angular apps; search GitHub for "front-end-checklist" app. None are endorsed by the upstream author, and quality varies. The canonical interactive experience remains "paste into a GitHub Issue."

Q: Can I use the checklist for an internal dashboard instead of a public website?

Yes. Skip the SEO section entirely, de-prioritize Social meta, and keep the Accessibility, Security, and Performance sections — internal dashboards benefit especially from keyboard-navigation and screen-reader checks (your colleagues with disabilities use them too).

Q: Is there a stricter, more opinionated version?

Not from this author. Related but stricter guides include Google's web.dev Lighthouse Baseline, the GOV.UK Service Standard for government sites, and the Web Almanac. Pair the Front-End Checklist with one of those for a richer standard.

Q: What happens if the upstream repo is archived or deleted?

CC0 1.0 lets anyone fork and continue the work with no legal friction. Your fork, or any of the 13 translation forks, can become a successor. The content is permanently free.

Q: How current is this guide?

This guide describes the checklist at commit 09d56df (2025-02-14).