# 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](#3-configuration) for the resolution.

## Table of Contents

1. [Quick Start](#1-quick-start)
2. [Installation](#2-installation)
3. [Configuration](#3-configuration)
4. [Core Usage](#4-core-usage)
5. [Common Tasks](#5-common-tasks)
6. [Troubleshooting](#6-troubleshooting)
7. [FAQ](#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](https://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 (![High] High), orange (![Medium] Medium), green (![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](https://raw.githubusercontent.com/thedaviddias/Front-End-Checklist/main/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

| Path | Best for | How |
|---|---|---|
| **Offline clone** | Editing locally, grep search, custom build | `git clone https://github.com/thedaviddias/Front-End-Checklist.git` |
| **Printable PDF** | Pre-launch binder, formal review meeting | Open the GitHub README → `Ctrl+P` / `Cmd+P` → Save as PDF (~25-30 pages) |
| **Translation forks** | Reading in your native language | See the **Translations** section of the upstream README — 13 community forks (Japanese, Spanish, Chinese SC+TC, Korean, Portuguese, Vietnamese, French, Russian, Turkish, German, Polish, Indonesian) |
| **Sibling checklists** | Deeper performance or design coverage | [Front-End Performance Checklist](https://github.com/thedaviddias/Front-End-Performance-Checklist) and [Front-End Design Checklist](https://github.com/thedaviddias/Front-End-Design-Checklist) |
| **Pandoc to LaTeX** | Polished print, custom margins | `pandoc README.md -o checklist.pdf --pdf-engine=xelatex` |

[Low]: https://raw.githubusercontent.com/thedaviddias/Front-End-Checklist/refs/heads/main/data/images/priority/low.svg
[Medium]: https://raw.githubusercontent.com/thedaviddias/Front-End-Checklist/refs/heads/main/data/images/priority/medium.svg
[High]: https://raw.githubusercontent.com/thedaviddias/Front-End-Checklist/refs/heads/main/data/images/priority/high.svg

### Minimal example: an item, decoded

A typical line in the README looks like this:

```markdown
- [ ] **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](https://www.w3.org/QA/Tips/Doctype)
```

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
```

```text
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 (![High], ![Medium], ![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](#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](https://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.

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

# In the repo root
pnpm install
```

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

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

| Package | Version | Role |
|---|---|---|
| `prettier` | `^3.3.3` | Reflow Markdown to the repo's style |
| `markdownlint-cli` | `^0.42.0` | Structural lint of the README |
| `husky` | `^9.1.6` | Git hook runner (the `prepare` script installs hooks) |

> [!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):

| Tool | Required | Notes |
|---|---|---|
| Node.js | Yes | Any LTS (20.x, 22.x). No `engines` field in `package.json`, so any reasonably modern Node works. |
| pnpm | Recommended | ≥ 8 |
| Git | Yes | Any recent version |
| Lychee | Optional | The repo's link-checker. Install as a standalone binary (not an npm dependency). |

### 2.6 Verify the install

```bash
pnpm format:check
```

```text
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.

| Badge | Tier | Meaning | When to omit |
|---|---|---|---|
| ![Low] (green dot) | **Low** | Recommended. Nice to have for completeness or edge-case coverage. | Omit freely when scope or schedule is tight. |
| ![Medium] (orange dot) | **Medium** | Highly recommended. Omission has a measurable cost (SEO dip, performance regression, worse UX for a minority of users). | Omit only with a documented reason. |
| ![High] (red dot) | **High** | Mandatory. Omitting causes page malfunction, accessibility failure, security hole, or major SEO loss. | Do not omit. |

> [!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 ![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:

| Emoji | Kind | Examples |
|---|---|---|
| 📖 | Documentation or article | MDN pages, W3C specs, Google Webmaster docs, CSS-Tricks articles, OWASP cheat sheets |
| 🛠 | Online tool or testing tool | W3C Validator, Favicon Generator, WAVE, PageSpeed Insights, Lychee, stylelint |
| 📹 | Media or video content | A11ycasts YouTube playlists, recorded talks |

> [!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:

```text
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):

```text
🗂 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

| Category | Subsections | Focus |
|---|---|---|
| **Head** | Meta tag, HTML tags, Social meta | `<head>` element completeness: Doctype, charset, viewport, title, description, favicons, Apple Web App meta, Windows tiles, canonical, HTML tags (`lang`, `dir`, `hreflang`, `x-default`), conditional comments, RSS, critical CSS, CSS order, Open Graph, Twitter Card |
| **HTML** | Best practices, HTML testing | HTML5 semantic elements, error pages, `rel="noopener"`, comment cleaning; W3C validator, HTML linters, broken-link checkers, adblocker test |
| **Webfonts** | (flat) | Supported formats (WOFF, WOFF2, TTF), size ceiling (~2 MB across all variants), web-font loader strategies |
| **CSS** | Performance, CSS testing | Responsive design, print stylesheets, preprocessors, unique IDs, reset CSS, JS prefix convention, embedded-CSS rules, vendor prefixes; concatenation, minification, non-blocking loads, unused-CSS removal; stylelint, breakpoints at 320 / 768 / 1024, CSS validator, cross-browser, cross-OS, RTL, design fidelity |
| **Images** | Best practices | Optimization (Imagemin, ImageOptim, TinyPNG, SVGO), `<picture>`/`srcset`, retina support, spritesheets, `width`/`height` attributes, `alt` text, lazy loading |
| **JavaScript** | Best practices, JavaScript testing | No inline JS, concatenation, minification, security (OWASP), `<noscript>` fallback, async/defer loading, updated and necessary libraries, Modernizr use; ESLint |
| **Security** | Scan and check, Best practices | HTTPS, HSTS, CSRF, XSS, `X-Content-Type-Options`, `X-Frame-Options`, Content Security Policy, security scan tools |
| **Performance** | Best practices, Preparing upcoming requests, Performance testing | FMP < 1s, TTI < 5s on mid-tier Android/3G, critical budget < 170 KB gzipped, minified HTML, lazy loading, cookie size (< 4096 B each, < 20 per domain), third-party iframe handling, `dns-prefetch` / `preconnect` / `prefetch` / `preload`, PageSpeed ≥ 90 |
| **Accessibility** | Best practices, Headings, Semantics, Form, Accessibility testing | Progressive enhancement, color contrast (WCAG AA, AAA on mobile), heading hierarchy (H1 uniqueness), semantic HTML5 input types, form labels, WAVE, keyboard navigation, screen readers, visible focus |
| **SEO** | (flat) | Google Analytics, Search Console, heading logic, `sitemap.xml`, `robots.txt`, structured data (JSON-LD / Microdata / Schema.org), HTML sitemap |

> [!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

| Out of scope | Where to look instead |
|---|---|
| Framework-specific patterns (React, Vue, Angular, Svelte, Solid, Astro) | Each framework's own docs and lint rules |
| Build tooling (Webpack, Vite, esbuild, Parcel) | The bundler's docs |
| Backend / API architecture | REST/GraphQL/security-focused resources |
| Deep performance engineering | [Front-End Performance Checklist](https://github.com/thedaviddias/Front-End-Performance-Checklist) — sibling repo by the same author |
| Designer-developer handoff | [Front-End Design Checklist](https://github.com/thedaviddias/Front-End-Design-Checklist) — sibling repo by the same author |
| Deployment infrastructure (CDN, monitoring, runbooks) | DevOps-specific resources |

### 4.4 Reading any single item

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

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

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

- 📖 [Reference link title](https://example.com/article)
- 🛠 [Tool link title](https://example.com/tool)
```

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
```

```text
50
40
40
130
```

### 4.6 Section cross-reference

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

| If you are looking for… | Go to | Notable item(s) |
|---|---|---|
| Character encoding, viewport | Head → Meta tag | **Charset**, **Viewport** (both ![High]) |
| Open Graph / Twitter Card | Head → Social meta | **Facebook Open Graph**, **Twitter Card** |
| `lang` attribute on `<html>` | Head → HTML tags | **Language attribute** (![High]) |
| Canonical URL / hreflang | Head → HTML tags | **Canonical**, **Alternate language**, **x-default** |
| Critical CSS | Head → HTML tags | **CSS Critical** (![Medium]) |
| 404 / 5xx pages | HTML → Best practices | **Error pages** (![High]) |
| `rel="noopener"` | HTML → Best practices | **Noopener** (![Medium]) |
| W3C validation | HTML → HTML testing | **W3C compliant** (![High]) |
| Responsive breakpoints | CSS → CSS testing | **Responsive web design** (320 / 768 / 1024) |
| RTL / LTR | CSS → CSS testing | **Reading direction** (![High]) |
| `alt` text | Images → Best practices | **Alternative text** (![High]) |
| `srcset` / `<picture>` | Images → Best practices | **Picture/Srcset** (![Medium]) |
| Async / defer | JavaScript → Best practices | **Non-blocking** (![Medium]) |
| ESLint | JavaScript → JavaScript testing | **ESLint** (![High]) |
| HTTPS / HSTS | Security → Best practices | **HTTPS** (![High]), **HSTS** (![Medium]) |
| Content Security Policy | Security → Best practices | **CSP** (![Medium]) |
| Cross-Site Scripting (XSS) | Security → Best practices | **XSS** (![High]) |
| Cookie size / count | Performance → Best practices | **Cookie size** (4096 B, 20 per domain) |
| `dns-prefetch` / `preconnect` | Performance → Preparing upcoming requests | All four resource hints |
| PageSpeed target | Performance → Performance testing | **Google PageSpeed** ≥ 90 (![High]) |
| WCAG AA color contrast | Accessibility → Best practices | **Color contrast** (![Medium]) |
| H1 uniqueness | Accessibility → Headings | **H1**, **Headings** (![High]) |
| Form labels | Accessibility → Form | **Label** (![High]) |
| Keyboard navigation | Accessibility → Accessibility testing | **Keyboard navigation** (![High]) |
| `sitemap.xml` / `robots.txt` | SEO | Both ![High] |
| Structured data | SEO | **Structured Data** (![High]), JSON-LD / Microdata / Schema.org |

---

## 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](https://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 ![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](https://wave.webaim.org).

**Steps:**

- [x] Read the **Accessibility** category in the upstream README ([github.com/thedaviddias/Front-End-Checklist#accessibility](https://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](https://wave.webaim.org) 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](https://www.deque.com/axe/devtools/) and [Pa11y](https://pa11y.org/) 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](https://github.com/thedaviddias/Front-End-Checklist#seo)).
- [x] Tick the SEO ![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](https://search.google.com/test/rich-results) 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](https://pagespeed.web.dev), Chrome or Firefox DevTools, and the ability to deploy a fix to a staging URL.

**Steps:**

- [x] Run [PageSpeed Insights](https://pagespeed.web.dev) 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](https://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 ![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 ![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](https://github.com/thedaviddias/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](https://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](https://github.com/thedaviddias/Front-End-Checklist#security)).
- [x] Run [securityheaders.com](https://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](https://securityheaders.com) returns at least an **A** grade; [Mozilla Observatory](https://observatory.mozilla.org) returns at least a **B**; [SSL Labs](https://www.ssllabs.com/ssltest/) 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](#24-install-the-maintainers-tooling-only-if-contributing)); the proposed item is genuinely missing (search the README first).

**Steps:**

- [x] Read [`CONTRIBUTING.md`](https://github.com/thedaviddias/Front-End-Checklist/blob/main/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):
    ```markdown
    - [ ] **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](https://example.com/spec)
    - 🛠 [Tool to verify](https://example.com/tool)
    ```
- [x] Run the format pipeline:
    ```bash
    pnpm format:fix
    ```

    ```text
    README.md 1.2s
    ```

- [x] Commit and push:
    ```bash
    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](https://thedaviddias.com/) 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](https://web.archive.org/) — 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](https://github.com/thedaviddias/Front-End-Checklist/issues/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:
    ```markdown
    [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](#51-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?!?"](https://github.com/thedaviddias/Front-End-Checklist/issues/549) 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](https://github.com/thedaviddias/Front-End-Checklist/issues/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](https://thedaviddias.com/)) 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](https://github.com/thedaviddias)) or the project's [open issues](https://github.com/thedaviddias/Front-End-Checklist/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:**

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

```text
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:

```bash
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`](https://github.com/thedaviddias/Front-End-Checklist/blob/main/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](#56-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)](https://github.com/thedaviddias/Front-End-Checklist/issues/511) 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](https://ddias.link/x) and runs a [Discord server](https://ddias.link/discord). The GitHub [Issues](https://github.com/thedaviddias/Front-End-Checklist/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:

```bash
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](https://github.com/thedaviddias/Front-End-Performance-Checklist) is a deep dive on speed. The [Design Checklist](https://github.com/thedaviddias/Front-End-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](https://www.w3.org/TR/WCAG21/) 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](https://web.dev/lighthouse-performance/), the [GOV.UK Service Standard](https://www.gov.uk/service-manual/service-standard) for government sites, and the [Web Almanac](https://almanac.httparchive.org/). 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).

---

_Generated April 2026 from thedaviddias/Front-End-Checklist at 09d56df. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._