Skip to content

Latest commit

 

History

History
127 lines (106 loc) · 6.97 KB

starter_guide.md

File metadata and controls

127 lines (106 loc) · 6.97 KB
Raw

Starter Guide

You just got tasked with implementing some new UI surface in Chrome, the UX designer gave you a few mocks, and your tech lead told you they expect it should only take you a few days. Help! You've never built UI before! What do you do?

Take a deep breath. We're here to help. Hopefully the following will get you started.

General Principles

  • Ignorance is ok. UI is a specialized field, and if you haven't worked with it before, there's no reason you should know everything. Even if you have done UI development on other products or on the web, the Views toolkit has some differences that might leave yourself scratching your head. Don't spend too long trying to figure things out yourself; ask questions early and often, before you discover in code review that that lovely solution you found is actually a pattern the team is trying to eliminate.

  • Don't cargo-cult. Just as you may be ignorant, others may be too: specifically, both the designers of your feature, and the authors of other UI in Chrome. Blindly following is unsafe, so start by sending your feature to the desktop UI mailing list, even if you've been assured it passes UX review. Then, while implementing, study the documented best practices, and ensure your code adheres to them, even if other code you're referencing does not.

  • Support all users. Chrome ships on multiple platforms, so try to build and test on multiple platforms yourself. Users have different themes, so make sure your design works for the built-in light and dark themes as well as custom themes. Users may have different needs and abilities, so ensure your design takes accessibility sufficiently into account.

  • Build for the long term. Chrome has a rapid release schedule in part so we don't feel pressure to ship changes before they're ready. It's easy for engineers to ship UI and leave it unmaintained, adding to the deifficulty of future refactors and stylistic changes. So expect reviewers to set a high bar. Ask how to structure your classes in keeping with MVC (Model-View-Controller) principles. Write automated tests for your feature, including both functional tests and pixel tests. And make sure your subteam, or another subteam, is explicitly signed up to own the code you write going forward and has a triage process to categorize and address bugs in it.

Necessary Background

The Views toolkit was purpose-built to render Chrome's UI on desktop platforms. It lacks many features of general-purpose UI toolkits, and adds features on request, rather than speculatively. It's possible that over time, more UI will be built with web technologies, as some of the original design constraints that led to Views' creation become less applicable, and since it is difficult to justify the engineering investment necessary to implement significant modern UI toolkit features (e.g. declarative UI or stylesheets).

The best way to familiarize yourself with Views is to build a simple UI example. This should give you sufficient context to understand some important parts of the system. Along the way, if you run into jargon you don't understand, you can look for a definition in the glossary (or request one, if you don't see what you need).

At this point, you should be ready to start building your UI, following the steps below.

Building Your UI

  1. Make sure there is a bug on file with a description of the UI you're building, and a link to any relevant design docs or mocks. Assume readers aren't familiar with your subteam/product area already and provide enough background that, without clicking through to other documentation, a new code reviewer can understand the basic idea you're trying to accomplish.

  2. If it hasn't already happened, send mail to the desktop UI mailing list describing the proposed UX. The primary purpose is for knowledgeable folks on this list to flag designs that are atypical in Chrome or will be difficult to implement; these might require further tweaks from the UX designers. This can be a frustrating process if you assume UX mocks are set in stone, but the goal is not to derail your feature; it's to ensure everyone is aware of what tradeoffs must be made to implement the feature in a way that supports all users and is maintainable for the indefinite future.

  3. Ensure your UX mocks are semantic, not physical. That is, they should explain what a feature does and how it relates to other similar UI (e.g. "use standard dialog borders" or "match accent color used for radio buttons elsewhere"), ideally by referencing standardized color or layout names/tokens; they should not simply give you hardcoded values ("16 dp", "Google Grey 300"). Hardcoded values cannot be systematized in a way that accommodates users with different font sizes or themes, or changes over time in Chrome's systematic design aesthetic. Semantics tell you how to obtain the desired values from classes in Chrome that are designed to provide the appropriate physical values for your context.

  4. Look for similar UI implementations in Chrome and study how they function, but don't blindly copy them. The majority of Chrome UI is years old and was written before current best practices were established and documented, so while existing code can be a good source of inspiration, it usually needs modification before it's fit for reuse.

  5. Add a feature flag to gate your UI, and implement it locally. Some engineers prefer to send CLs as they implement each small piece, while others prefer to get something mostly complete done locally before polishing things for review; either way, ensure the changes you send for review are small enough to be manageable but still provide sufficient context for your reviewer to understand what's happening.

  6. When preparing a CL for code review, run through this checklist.

  7. Before considering your feature complete, ensure it has automated testing. In most cases, this can be accomplished using TestBrowserUi or an appropriate subclass; if the feature is built using MVC design principles, you can hopefully also unit-test the business logic separately. If possible, opt in to pixel tests using Skia Gold.

Further Resources

  • If you're a Noogler on the Chrome team, welcome! You should have gotten this already, but here are some hopefully-helpful docs as you ramp up on Chrome in general; here are docs on the general contribution process.
  • Is it possible to debug the UI that you're building? Yes! Here are a few tools to help you.