WICG Explainer

A plain-language proposal document in a Web Incubator Community Group repository that opens every Blink web-platform feature to public scrutiny before any code is merged.

The Explainer is the artifact a Chromium contributor writes first, not last. A team that has working code, a green test suite, and an internal sign-off cannot post an Intent to Prototype until an Explainer exists in a public WICG repository at a stable URL. The document precedes the prototype, names the user problem the feature solves, sketches the proposed API surface, lists the alternatives the team considered and rejected, addresses the security and privacy implications, and identifies the open questions the team wants standards-body input on. It is the first thing other-vendor representatives, downstream maintainers, and the API owners themselves read when a new feature appears on blink-dev.

Context

A new Blink web-platform feature has cleared internal review at one of the contributing organizations. The engineers are confident the proposal is sound. Management has signed off. The natural next move is to land an implementation behind a flag and run a developer trial. The Intent to Ship Pipeline blocks that move: every Blink feature must move through a public process whose first gate is an Explainer in a Web Incubator Community Group (WICG) repository on GitHub. The pipeline’s later gates — the Intent to Prototype, the Origin Trial, the three API-owner LGTMs at Intent to Ship — all read against the document the Explainer establishes. A feature posted to blink-dev without an Explainer link is bounced before substantive review begins.

The WICG itself is a W3C Community Group, chartered under the Community and Business Group Process the W3C adopted in 2011. The group’s working surface is a set of GitHub repositories at github.com/WICG, each typically corresponding to a single proposal. The contribution and intellectual-property terms are uniform across the WICG: anyone may contribute under the Community Contributor License Agreement, and proposals graduate to the relevant W3C Working Group when they mature enough to enter the standards track. The format is light by design — short Markdown documents, public from the first commit, no required formal grammar.

Problem

A feature owner inside any contributing organization can produce a working prototype faster than the cross-vendor consensus on whether the feature should exist. The owner’s mental model of the user problem is shaped by their organization’s surface. Microsoft Edge engineers think first about enterprise integration; Google engineers about ads, identity, and the open-web frontier; Igalia engineers about embedded-runtime and standards-quality concerns. Each of these is partial. A feature that looks essential from inside one organization can break a use case the other contributors haven’t surfaced, or duplicate a capability the W3C Technical Architecture Group already routed elsewhere, or expose a privacy regression the security team would have raised had they been on the design call.

The recurring problem is how the project turns one organization’s prototype into a proposal the entire contributor population can read, argue with, and either improve or reject before the implementation accretes irreversible weight. The asymmetry runs the wrong way: an unreviewed prototype is cheap to produce and expensive to remove once it has any user surface. A reviewed proposal is cheaper to revise than a shipped feature is to retract.

Forces

• Public accountability vs. private polish. Teams want to refine their proposal internally before exposing it to scrutiny; the project’s review depends on the proposal being public early, when revisions are still cheap.
• Specification rigor vs. accessibility. A formal Web IDL specification is precise but illegible to most readers; a marketing document is legible but useless to API owners. The Explainer sits between and serves both.
• Author intent vs. reader interpretation. The team that knows what the feature does cannot easily anticipate which framings will surprise an outside reader; the public format forces the framing to survive readers the team did not pre-select.
• Inter-vendor commitment vs. vendor independence. The Explainer invites Mozilla and WebKit positions on the public record; those positions inform whether the proposal is suitable for Stable, even though no other vendor has authority over Chromium’s launch decision.
• Standards-process speed vs. specification cost. Drafting a complete formal specification before any prototyping happens is slow and often wasteful; the Explainer is the project’s compromise — a publishable artifact that precedes the specification but commits to the same scrutiny.

Solution

The Chromium project requires every new Blink web-platform feature to begin with an Explainer published in a WICG repository at a stable URL. The Explainer follows a conventional template captured in the WICG starter kit, the project’s docs/process/web_idl_interfaces.md, and the W3C TAG’s Web Platform Design Principles. The template asks the author to answer specific questions in this order:

• What is the user-visible problem being solved? Stated in plain language, with concrete user scenarios. A feature whose problem statement starts with the proposed API rather than the user’s situation has already failed this question.
• What is the proposed solution? A sketch of the API surface, the IDL the team expects to define, and the user-visible behavior. Not a formal specification — a sketch detailed enough that a reviewer can see what the API looks like in use.
• What alternatives were considered? Each alternative the team evaluated, with a brief statement of why it was rejected. The strongest Explainers list real candidates with named tradeoffs; the weakest list one alternative as a strawman.
• What are the security and privacy implications? Cross-origin behavior, fingerprinting surface, capability leakage, persistence implications, and any new attack surface the feature introduces. This is the section the security team and the API Owners read first.
• Where does the proposal stand with respect to backward compatibility? Whether existing surface is unchanged, whether shipped pages will continue to work, and whether the proposal collides with any other shipped or proposed feature. The project’s Web Platform Backward Compatibility commitment is operationalized through this section.
• What are the open questions? The things the team has not yet resolved and wants standards-body or other-vendor input on. The Explainer’s intellectual honesty is most visible in this section: a list of open questions signals a team engaging with reviewers; an empty list signals a team that thinks the work is done.

The document lives in a WICG repository, typically as README.md or explainer.md in a repo whose name matches the proposed feature. Issues on the repository capture early discussion before the Intent to Prototype thread opens; pull requests track revisions to the document as the proposal evolves. The Explainer is never “frozen” — it is updated alongside the proposal across every Intent stage, and the final version on the day of Intent to Ship is the document the three approving API owners read.

The Web Platform Design Principles maintained by the W3C TAG at w3ctag.github.io/design-principles/ shape the Explainer’s review expectations. A team writing a proposal that ignores those principles can expect API owners to cite them in the LGTM thread.

How It Plays Out

A team at a contributing organization has a working prototype of a new web-platform feature. Before posting an Intent to Prototype, they create a WICG repository named for the feature, push an explainer.md to it, and open it for issues. The first week’s issues come from another contributing organization, the W3C TAG, and a downstream embedded-runtime maintainer. Two of the issues point out a use case the team had not considered; one identifies an interaction with a shipped feature the team had not noticed; the fourth proposes a different API shape that the team finds compelling enough to incorporate. The Explainer is revised; the alternatives-considered section grows; the security section addresses a concern the original draft glossed. The Intent to Prototype thread is posted three weeks after the initial publication, and the public record already contains the proposal’s working history.

A second team posts an Intent to Prototype with an Explainer linked. An API owner reads the document and notices that the proposed-solution section reads as a description of the team’s implementation rather than a specification of the API. The owner asks on the thread for the document to be revised. The team rewrites the section to address the user-visible behavior rather than the implementation; the revision is committed to the WICG repository; the Intent to Prototype clears with the document in its revised form. The same Explainer, further refined, is the document the three API owners read at the Intent to Ship gate a year later.

A third team is asked, after shipping a feature, to explain why a downstream Electron application has begun to fail. The application’s maintainer is reading the original Explainer’s compatibility section, which had committed to not changing the behavior of an existing surface. The team’s implementation had changed it in a way the Explainer didn’t document. The downstream maintainer’s issue, filed on the WICG repository, is the project’s first signal that the deployed code is out of sync with the document the API owners had approved. The repair lands in a follow-up Intent to Ship, with the Explainer updated to match the actual behavior, and the team carries a public record of the gap as a lesson the next feature owner can cite.

Consequences

Benefits. The Explainer creates a public artifact that survives team turnover, vendor reorganization, and the multi-year lifetime of a web-platform feature. A maintainer of a downstream Chromium-based product asked to evaluate a five-year-old feature can read the Explainer that motivated it — including the alternatives the team rejected and the open questions the project resolved — without reconstructing the rationale from blink-dev archives. The format is light enough that proposals can be written by working engineers rather than dedicated standards staff, which keeps the cost of public-first development inside the budget of every contributing organization, not just Google’s. The other contributing vendors and the W3C bodies have a shared document to comment on, which is what makes cross-vendor review possible at the cadence the project ships at. The Three-LGTM API Owner Gate at Intent to Ship rests on the Explainer being a real document, kept current.

Liabilities. Writing an Explainer isn’t free. A team that prototypes in two weeks may spend another two writing the document well, and weak Explainers — the alternatives section padded with strawmen, the security section glossing real concerns, the open-questions section empty — cost the team another Intent cycle to repair. The format’s lightness is a real strength when used honestly and a real liability when used dishonestly: an Explainer that performs scrutiny without absorbing it produces the appearance of public review without the substance. The WICG repository surface is also wide and uneven: a curious reader can find a five-year-old explainer that was never updated alongside a current one, with no UI signal of which is which. The project’s response is partial — periodic culling of stale repositories, occasional explicit “abandoned” annotations — but the cost is borne by readers who arrive without context.

The Explainer doesn’t make a feature good. It makes the feature’s reasoning visible to the population whose review the project’s launch process counts.

Notes for Agent Context

When generating any Chromium contribution that adds or changes Blink web-platform surface, surface the Explainer artifact the change will need before marking the work complete. The artifact must be a public WICG-hosted document at a stable URL; an internal design document is not a substitute. Refuse to claim Intent-to-Prototype readiness without an Explainer link, a stated user problem, a sketched API surface, an alternatives-considered section with at least two real alternatives, and a security-and-privacy section that addresses cross-origin behavior, fingerprinting, and any new attack surface. When proposing revisions to an existing Explainer, preserve the open-questions section as a living record; do not delete unresolved questions to make the document read as more settled than it is. Treat the W3C TAG Web Platform Design Principles as binding context for Explainer review; cite them when proposing a design that competes with their guidance.

Related Patterns

Sources

The Web Incubator Community Group operates under the W3C Community and Business Group Process, established in 2011 and chartered to lower the barrier to public early-stage proposals on the web platform. Alex Russell and the early WICG participants framed the group’s working surface as a community-of-practice rather than a standards body; the Explainer format reflects that working stance. The Chromium project’s “Launching Features” guide on chromium.org named the Explainer as a required first artifact of the Intent pipeline at roughly the same time the WICG was founded. The W3C Technical Architecture Group’s Web Platform Design Principles, maintained at w3ctag.github.io/design-principles/ by the rotating TAG membership across W3C member organizations, shape the review expectations every Explainer is read against. The WICG starter-kit template, kept at github.com/WICG/starter-kit, is the working compromise the community arrived at between specification rigor and accessible early-stage proposal writing.

Technical Drill-Down

• WICG home and repository index — the entry point; the home page links the current WICG repositories and the participation terms.
• WICG starter kit — the template repository every new Explainer is structured against; the README enumerates the required sections.
• Chromium “Launching Features” guide — the canonical process-from-the-feature-owner’s-perspective document; names the Explainer as the pipeline’s first required artifact.
• W3C TAG Web Platform Design Principles — the principles every Explainer is reviewed against; reviewer comments on Intent threads frequently cite specific sections by URL.
• W3C Community and Business Group Process — the chartered framework under which the WICG operates; defines the IPR terms and the graduation path to a W3C Working Group.
• docs/process/blink/web_idl_interfaces.md — the Blink launch-process documentation in chromium/src; the Explainer requirement is stated in its opening section.