docs/ui/starter_guide.md - chromium/src.git - Git at Google

 # 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 you scratching your head. Don't spend too long
 trying to figure things out yourself;
 [ask questions](https://chromium.googlesource.com/chromium/src/+/main/docs/ui/ask/index.md)
 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](http://go/cr-ui-process), even if you've been assured
 it passes UX review. Then, while implementing, study the documented
 [best practices](learn/index.md#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](views/platform_style.md), 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](create/examples/theme_aware.md). Users may have
 different needs and abilities, so ensure your design takes
 [accessibility](http://go/gar) 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 difficulty 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](create/examples/login_dialog.md). This should give you
 sufficient context to understand some
 [important parts of the system](views/overview.md). Along the way, if you run
 into jargon you don't understand, you can look for a definition in the
 [glossary](learn/glossary.md) (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](http://crbug.com/) 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.

 1. If it hasn't already happened, send mail to the
 [desktop UI mailing list](http://go/cr-ui-process) 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.

 1. 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.

 1. 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.

 1. Add a [feature flag](/docs/how_to_add_your_feature_flag.md) 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.

 1. When preparing a CL for code review, run through
 [this checklist](learn/bestpractices/prepare_for_code_review.md).

 1. Before considering your feature complete, ensure it has automated test
 coverage:
  - Isolate and unit test your model and/or controller (in `components_unittests`
    or `unit_tests`).
  - Isolate and unit test your presentation layer (in `unit_tests` - or if
    absolutely necessary, in `browser_tests`).
    - Proper MVC separation should allow all of these to be separately unit
      tested with the other parts mocked out.
  - Create end-to-end, critical user journey interaction tests (in
    `interactive_ui_tests`)
    - [Kombucha](/chrome/test/interaction/README.md) is an excellent library for
      writing interaction tests, with many examples in the codebase.
  - If possible, opt in to [pixel tests](/docs/testing/pixel_tests.md) using
    the Kombucha `Screenshot()` verb.

 ## Further Resources

 * If you're a Noogler on the Chrome team, welcome! You should have gotten this
 already, but
 [here](https://sites.google.com/corp/google.com/chrome-top-level/more-resources/new-to-chrome)
 are some hopefully-helpful docs as you ramp up on Chrome in general;
 [here](/docs/contributing.md) are docs on the general contribution process.
 * Is it possible to debug the UI that you're building? Yes!
 [Here](learn/ui_debugging.md) are a few tools to help you.
	# 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 you scratching your head. Don't spend too long
	trying to figure things out yourself;
	[ask questions](https://chromium.googlesource.com/chromium/src/+/main/docs/ui/ask/index.md)
	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](http://go/cr-ui-process), even if you've been assured
	it passes UX review. Then, while implementing, study the documented
	[best practices](learn/index.md#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](views/platform_style.md), 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](create/examples/theme_aware.md). Users may have
	different needs and abilities, so ensure your design takes
	[accessibility](http://go/gar) 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 difficulty 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](create/examples/login_dialog.md). This should give you
	sufficient context to understand some
	[important parts of the system](views/overview.md). Along the way, if you run
	into jargon you don't understand, you can look for a definition in the
	[glossary](learn/glossary.md) (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](http://crbug.com/) 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.

	1. If it hasn't already happened, send mail to the
	[desktop UI mailing list](http://go/cr-ui-process) 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.

	1. 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.

	1. 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.

	1. Add a [feature flag](/docs/how_to_add_your_feature_flag.md) 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.

	1. When preparing a CL for code review, run through
	[this checklist](learn/bestpractices/prepare_for_code_review.md).

	1. Before considering your feature complete, ensure it has automated test
	coverage:
	- Isolate and unit test your model and/or controller (in `components_unittests`
	or `unit_tests`).
	- Isolate and unit test your presentation layer (in `unit_tests` - or if
	absolutely necessary, in `browser_tests`).
	- Proper MVC separation should allow all of these to be separately unit
	tested with the other parts mocked out.
	- Create end-to-end, critical user journey interaction tests (in
	`interactive_ui_tests`)
	- [Kombucha](/chrome/test/interaction/README.md) is an excellent library for
	writing interaction tests, with many examples in the codebase.
	- If possible, opt in to [pixel tests](/docs/testing/pixel_tests.md) using
	the Kombucha `Screenshot()` verb.

	## Further Resources

	* If you're a Noogler on the Chrome team, welcome! You should have gotten this
	already, but
	[here](https://sites.google.com/corp/google.com/chrome-top-level/more-resources/new-to-chrome)
	are some hopefully-helpful docs as you ramp up on Chrome in general;
	[here](/docs/contributing.md) are docs on the general contribution process.
	* Is it possible to debug the UI that you're building? Yes!
	[Here](learn/ui_debugging.md) are a few tools to help you.