Contribute to WebVitals.tools -- Open-Source Web Performance Reference

Why contribute?

Web performance is a fast-moving field. Google updates the Core Web Vitals thresholds. Framework teams ship new rendering strategies. CDN configurations that worked last year carry subtle regressions today. No single editorial team can monitor every framework, every hosting provider, and every new browser API simultaneously. That is why this project is open-source: the readers who catch a stale benchmark, a misconfigured snippet, or a missing framework fix are the fastest path to keeping the reference accurate.

The site already covers over a hundred pages of guides, fixes, tutorials, and tools built up across 27 days of continuous publishing. Maintaining that content at the level of accuracy developers deserve requires more eyes than any small team provides. A one-line typo fix is as welcome as a full new page. Both go through the same review process and both are credited in the About page contributor list.

Contributions also help you. Writing up a fix you already solved at work turns private knowledge into a public reference, documents your thinking for future teammates, and lands your name on a project that thousands of developers read every month. The changelog records every addition, so your work has a permanent timestamp on the public record.

Ways to help

Contributions fall into three buckets depending on how much you want to take on. All three start with the same GitHub repository at github.com/SensaraIO/webvitals-tools.

Bucket 1

Report issues

Found a broken link, an outdated threshold, a code sample that no longer works, or a missing explanation? Open a GitHub issue and describe what you found. Include the URL of the affected page, the specific sentence or snippet that is wrong, and what the correct information should be. Good issue reports are the lowest-effort contribution and have the highest leverage -- they allow someone else to apply the fix with full context in minutes.

Use the issue tracker for: stale data, broken internal links, code errors, accessibility problems, and missing alt text. You do not need to know how to fix the problem to file a useful report.

Bucket 2

Submit corrections

If you know the fix, send a pull request directly. Corrections include: updated benchmark numbers, revised code samples, expanded explanations for confusing sections, grammar and clarity edits, and meta description rewrites that improve accuracy without exceeding the character limit. Small PRs are reviewed faster than large ones. A PR that fixes a single incorrect threshold on one page is more likely to ship in 24 hours than a PR that rewrites three sections at once.

When submitting corrections, reference the specific line numbers and explain why the new content is more accurate. Link to a primary source -- Google documentation, a Chrome Status entry, or a published CrUX dataset -- wherever possible. Our methodology page describes the sources we trust.

Bucket 3

Propose new pages

If a framework, hosting provider, or performance pattern is not yet covered, propose a new page. Open an issue first and describe the page you want to write: the target slug, the audience, the top three things the page must explain, and whether you plan to write it yourself or are requesting that someone else does. This avoids duplicated effort and lets editors give early feedback on scope before you invest writing time.

Good new-page proposals cover a concrete performance problem for a specific framework or platform, include at least 500 words of body copy, follow the page template described below, and contain at least three internal links to related pages already on the site. See the FAQ for common questions about what kinds of pages we accept.

Editorial standards

All content on WebVitals.tools is held to the same bar regardless of whether it was written by the core team or a community contributor. That bar is described in detail on the methodology page and covers lab tooling, field data sources, statistical methods, and update cadence. Before submitting new content or a correction, read the methodology page in full. It will tell you which tools we use to validate claims and what threshold data you should cite.

The short version: every factual claim about a Core Web Vitals threshold, a p75 benchmark, or a framework-specific behavior must link to a primary source. Primary sources are Google documentation, the web-vitals JavaScript library source, the Chrome User Experience Report dataset, official framework changelogs, and WebPageTest or Lighthouse results that can be reproduced. Secondary sources -- blog posts, talks, Stack Overflow answers -- are acceptable as supplementary context but not as the sole citation for a hard number.

Content that cannot be verified against a primary source will be returned for revision during review. Content that introduces opinion without clearly labeling it as such will also be revised. The goal is a reference that a developer can rely on the way they rely on framework documentation -- not a collection of subjective recommendations.

Page template checklist

Every page on the site follows the same HTML template. This is intentional: a consistent structure lets search engines index the site reliably, gives readers a predictable experience, and makes automated audits simple to run. The full template and contributing guide is available in CONTRIBUTING.md in the GitHub repository. The summary below covers every required element.

Required elements for every page

DOCTYPE and lang attribute: <!DOCTYPE html> and <html lang="en" data-theme="light"> must appear on line 1 and line 2 respectively.
Meta description (155-160 characters): The description must be between 155 and 160 characters -- not shorter, not longer. Use a character counter before submitting. A truncated or over-length description will be returned for revision.
JSON-LD structured data: Every page needs a <script type="application/ld+json"> block with an @graph containing at minimum a WebPage (or appropriate subtype) and a BreadcrumbList. The WebPage @id must be an absolute URL ending in /#webpage. The publisher must be the Organization named "WebVitals.tools".
Vercel Analytics snippet: The two-line Vercel Web Analytics block -- the inline script that initializes window.va and the deferred /_vercel/insights/script.js -- must appear immediately before </head> on every page.
Breadcrumbs: Every page must include a <nav class="breadcrumbs"> block immediately after the opening <main><div class="container">. The current page must carry aria-current="page".
Semantic HTML: Use <header>, <main>, <footer>, <section>, <nav>, and <article> elements for structural landmarks. Do not use <div> where a semantic element is available. Heading hierarchy must be strict: one H1, followed by H2, then H3 -- no skipped levels.
Body copy minimum (500+ words): Every page must contain at least 500 words of body copy, measured with wc -w after stripping tags. Preferred target is 1000+ words for guide and fix pages. Thin pages will be held until expanded.
No emoji: No Unicode emoji anywhere in the HTML source -- not in headings, not in body copy, not in meta descriptions, and not in JSON-LD. Use plain text or SVG icons for visual affordances.
Internal links: Every page must contain at least three internal links to related pages using relative paths (e.g. ../guides/lcp/). Absolute https://webvitals.tools/... URLs must only appear in canonical tags, og:url, and JSON-LD -- never in visible in-body links.

Code style

WebVitals.tools is built entirely with static HTML, CSS, and a small vanilla JavaScript file for theme toggling and mobile navigation. There is no build step, no framework, no bundler, and no server-side rendering. Each page is a single index.html file that loads two stylesheets and one script. This is intentional: static HTML is the fastest possible delivery for a reference site, it requires no runtime dependencies, and it is trivially deployable to Vercel via the auto-deploy pipeline. See the About page for the full technical rationale.

Color palette

The site uses two primary brand colors. Navy (#0f172a) is the background and primary dark surface. Accent green (#22c55e) is used for highlights, interactive elements, tags, and decorative SVGs. Both colors are exposed as CSS custom properties (--color-navy and --color-accent) in the base stylesheet. Do not hardcode hex values for these in contributed pages; use the custom properties so light and dark mode both work correctly.

Font stack

Three typefaces are loaded on every page. Cabinet Grotesk (weights 400, 500, 700, 800) is the display font used for headings and the logo -- reference it via var(--font-display). Satoshi (weights 300, 400, 500, 700) is the body font -- reference it via var(--font-body). JetBrains Mono (weights 400, 500, 600, 700) is the monospace font for code blocks -- reference it via var(--font-mono). Both Cabinet Grotesk and Satoshi are loaded from the Fontshare API; JetBrains Mono is loaded from Google Fonts. The font links are included in the shared head boilerplate and must not be modified.

CSS classes

Use the existing utility classes defined in styles/main.css. Key classes include .section, .section__header, .section__title, .section__desc, .card-grid, .guide-card, .guide-card__tag, .callout, and .faq-list. Inline styles are permitted for layout polish but should use the same CSS custom properties (spacing, typography, color) rather than hardcoded values. Do not add new global CSS rules to the shared stylesheets in the same PR as a page contribution -- open a separate PR for any stylesheet changes.

GitHub workflow

All contributions go through pull requests on the GitHub repository. The workflow below is the same for corrections, new pages, and stylesheet changes. Deployments to the live site are automatic: every merge to the master branch triggers a Vercel production deploy, which typically completes in under 60 seconds.

1
Fork the repository
Navigate to github.com/SensaraIO/webvitals-tools and click Fork. Work from your personal fork so that you can push branches freely without needing write access to the upstream repository.
2
Create a feature branch
Branch names should be descriptive and hyphen-separated. For a new page use a prefix like page/fixes-lcp-gatsby. For a correction use fix/lcp-guide-threshold-update. Do not commit directly to master in your fork -- the PR reviewer will ask you to rebase if you do.
3
Commit with your email
Use a clear, imperative commit message: "Add LCP fix page for Gatsby" or "Fix incorrect INP threshold on INP guide". Configure your Git identity so that your commits carry your real name and email. For maintainer commits, the contact email is zac@sensara.io. Community contributions should use the contributor's own email. Each commit should represent one logical change -- avoid squashing unrelated edits into a single commit.
4
Open a pull request
Open a PR from your branch to master in the upstream repository. In the PR description, state what you changed, why, and which pages are affected. For new pages, include the word count from wc -w and confirm the page template checklist items are all present. If the PR closes an existing issue, reference it with Closes #123.
5
Review and revisions
A maintainer will review the PR within a few days. Reviews focus on editorial accuracy, adherence to the page template checklist, internal link coverage, and word count. Requested changes will be left as inline GitHub comments. Address each comment on the same branch and push the updates -- the PR will update automatically.
6
Merge and auto-deploy
Once approved, a maintainer will squash-merge the PR into master. Vercel detects the push and deploys the new content to production automatically. The changelog is updated on the next daily build cycle to record the addition. Your contribution goes live within minutes of the merge.

Recognition

Every contributor whose pull request is merged into the repository is credited on the About page. The credit includes your name (or GitHub handle, if you prefer), a link to the PR or to the page you contributed, and the date of the contribution. This is a permanent public record: the About page is versioned in the repository just like any other page, and the changelog records the date each contribution was published.

We do not ask for CLA agreements or copyright assignments. By submitting a pull request you agree that your contribution is licensed under the same MIT license that covers the rest of the project. The MIT license permits anyone to use, copy, modify, and distribute the content freely, including for commercial purposes, provided the copyright notice is preserved. If you are contributing on behalf of an employer, check your employment agreement before submitting -- most open-source-friendly companies permit this kind of contribution but it is your responsibility to confirm.

If you have contributed a significant new page -- a full guide, a fix page, or a tutorial -- you may also request authorship credit in the page's own byline. Bylines appear at the top of the relevant page and carry your name alongside the publication date. See existing guide pages such as the LCP guide for examples of how bylines are formatted. Authorship credit is at editorial discretion and is offered when the contribution represents original research or writing rather than a correction to existing content.

Still have questions?

The FAQ hub covers common questions about contribution scope, review timelines, attribution, and what kinds of pages we are currently prioritizing. If your question is not answered there, open an issue on the GitHub repository with the label question.

You can also browse the full changelog to understand the scope and pace of recent additions, which should give you a sense of where the gaps are and what kind of contribution would have the most impact right now.