Add "starter guide" for those new to UI development.

Bug: none
Change-Id: Ia5303c532cf90f4ffc4e45239ee0776dd7383bf9
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4124329
Commit-Queue: Peter Kasting <pkasting@chromium.org>
Auto-Submit: Peter Kasting <pkasting@chromium.org>
Reviewed-by: Elaine Chien <elainechien@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1106385}

docs/ui/ask/index.md

@@ -32,5 +32,5 @@ without a Google account.
 * [Desktop UI Channel](https://chat.google.com/room/AAAA0vhHCUE)
 * [Desktop UI Discussion](https://groups.google.com/a/google.com/forum/#!forum/chrome-desktop-ui)
 * [chrome-desktop-ui@google.com](mailto:chrome-desktop-ui@google.com)
-* [Desktop UI Process](go/cr-ui-process) (internal) has guidance for planning
-  medium-to-large-scale projects.
+* [Desktop UI Process](http://go/cr-ui-process) (internal) has guidance for
+  planning medium-to-large-scale projects.

docs/ui/index.md

@@ -2,6 +2,9 @@
 Developing in Chromium UI? Trying to figure out how to create your UI? Need to
 contact the Views team? You've reached the right place.
 
+If you're new to UI development, read the [starter guide](starter_guide.md).
+Otherwise, look below for more specific documentation.
+
 ## Quick Links
 |||---|||
 

docs/ui/starter_guide.md

@@ -0,0 +1,127 @@
+# 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](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 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](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 testing. In
+most cases, this can be accomplished using
+[`TestBrowserUi`](/docs/testing/test_browser_dialog.md) 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](learn/glossary.md#skia-gold).
+
+## 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.