How we operate when carrying out a design review


An important function of the TAG is in providing design review, for proposed changes to the web.

Authors of new proposals can ask the TAG to review a proposal or to resolve a technical dispute.

This document describes how the TAG handles these requests.


Once a request is made, we periodically triage new issues and make assignments.

Review is performed both synchronously in calls, and asynchronously, depending on the complexity of a review request. Sometimes we invite the requestor or another expert from the wider community to discuss something with us on a call.

We track the status of review requests with issue labels. Labels describe how we intend to conduct a review, who we believe is responsible for any outstanding actions, and any resolution to the review.

During a review, we my use the issue thread to ask questions, make suggestions, and report our current thinking. We also update the issue labels, milestones, and assignees as the review progresses. Other stakeholders may also update the thread with additional information if they think it will help the review.

When the review is complete, we will close the issue with a concluding comment, and add a label that describes the disposition of the review.

Making a request

We provide an issue template for new review requests, and all review requests must provide an explainer.

Please make it clear in your issue description:

Preparing to review


First, we check all relevant information is included, that the explainer is in sufficient detail and the correct format, that all required fields in the issue template have been filled in. If not, we will ask the requestor to complete this before we proceed further.

We apply labels according to the following, to help us decide how to proceed with a review:

During triage, we might decline a request for any reason (see below). For reviews that we accept, we will label review requests with a mode:

The mode may change as a review progresses and new information comes to light, particularly as different areas are reviewed in more depth. For instance, mode: async may be appropriate for the API design, but the issue may be changed to mode: extra for privacy review if that seems necessary.

Milestones are used to denote the week of a breakout in which we will next discuss the issue, or the deadline for asynchronous work to be done by the assignees. We do our best to address the issue in the week of the milestone assigned, and to be realistic about when we can respond, but sometimes requests must be rescheduled.


When prioritising issues to work on, we:

Review areas

It is usually best to review new features/specifications/proposals with expertise from several different areas.

We do this by passing a review between different TAG members, depending on the area they are best equipped to cover. We use labels to indicate the status of each part of the review (eg. API review: pending / API review: complete). A review is complete when all areas have been marked as complete (or not applicable).

Broadly, the areas we cover most commonly are:

API design is essentially review in line with the design principles.

Security, Privacy, a11y and i18n map to horizontal review groups. These should get picked up by such groups - our job is to reinforce any concerns, and flag anything resulting from the features’ situation in the broader platform (eg. how it might interact with another feature that the HR group wasn’t thinking/doesn’t know about). For early reviews we may have to do more - but mainly prompting conversations with other HR groups, or flagging things for the requestor to look more closely at, rather than deep review.

Web architecture: how does it fit with the rest of the web platform? Implications for other existing or emerging features/areas? Is it consistent, technically and conceptually? Is it likely to be widely and consistently implemented? Any knock-on effects or opportunities from doing so?


At least two TAG members are assigned for each area of each review request. All assignees should know which part(s) of the review they are responsible for. Issues may be reassigned to different people as a review progresses.

Conducting a review

We communicate the progress of our reviews by commenting in the issue thread, and updating labels.

Depending on the complexity of a review, work may be done synchronously (on calls, typically with three or more TAG members present) or asynchronously (by one or two TAG members).

The complexity of a review usually depends on things like:

Synchronously (on calls)

We have a schedule of “breakout” calls each week across several timezones; TAG members are expected to attend at least two of these. The agenda is prepared in advance by the chairs, based on milestones assigned to design review issues, and the expected attendees of the breakouts. We use these for:

We also have a “plenary” call every two weeks, which all TAG members are expected to attend. We use these for:


If any area of a review can be completed asynchronously, any individual TAG member with the appropriate domain expertise can do so. Most reviews will be conducted by at least two people; often one who is leading and another who is checking over comments before they are posted. This can happen in Slack, between breakouts.

We keep each other updated about any reviews that were completed asynchronously during our plenary calls.


When we complete a review, we use labels to indicate the disposition of the review. The definitions of these are as follows.