am 32a035d1: am fa840e2b: Merge "docs: Android Design: v3 update (settings, navigation)" into ics-mr1

* commit '32a035d165f43b72d961a71192c902eba581dd0e':
  docs: Android Design: v3 update (settings, navigation)

docs/html/design/building-blocks/progress.jd

@@ -42,9 +42,9 @@ available space.</p>
       <li class="value-1"><h4>Activity bar (shown with the Holo Dark theme)</h4>
         <p>
 
-An indeterminate activity bar is used at the start of an application download because Google Play hasn't
-been able to contact the server yet, and it's not possible to determine how long it will take for
-the download to begin.
+An indeterminate activity bar is used at the start of an application download because the Play Store
+app hasn't been able to contact the server yet, and it's not possible to determine how long it will
+take for the download to begin.
 
         </p>
       </li>

docs/html/design/building-blocks/tabs.jd

@@ -25,7 +25,7 @@ to the next/previous view, swipe left or right.</p>
       <source src="{@docRoot}design/media/tabs_scrolly.ogv" type="video/ogg">
     </video>
     <div class="figure-caption">
-      Scrolling tabs in Google Play.
+      Scrolling tabs in the Play Store app.
       <div class="video-instructions">&nbsp;</div>
     </div>
 

docs/html/design/design_toc.cs

@@ -35,6 +35,7 @@
       <li><a href="<?cs var:toroot ?>design/patterns/swipe-views.html">Swipe Views</a></li>
       <li><a href="<?cs var:toroot ?>design/patterns/selection.html">Selection</a></li>
       <li><a href="<?cs var:toroot ?>design/patterns/notifications.html">Notifications</a></li>
+      <li><a href="<?cs var:toroot ?>design/patterns/settings.html">Settings</a></li>
       <li><a href="<?cs var:toroot ?>design/patterns/compatibility.html">Compatibility</a></li>
       <li><a href="<?cs var:toroot ?>design/patterns/pure-android.html">Pure Android</a></li>
     </ul>

docs/html/design/downloads/index.jd

@@ -39,7 +39,7 @@ available.</p>
 <p>
   <a class="download-button" href="https://dl-ssl.google.com/android/design/Android_Design_Fireworks_Stencil_20120229.png">Adobe&reg; Fireworks&reg; PNG Stencil</a>
   <a class="download-button" href="https://dl-ssl.google.com/android/design/Android_Design_OmniGraffle_Stencil_20120229.graffle">Omni&reg; OmniGraffle&reg; Stencil</a>
-  <a class="download-button" href="https://dl-ssl.google.com/android/design/Android_Design_Holo_Widgets_20120229.zip">Adobe&reg; Photoshop&reg; Sources</a>
+  <a class="download-button" href="https://dl-ssl.google.com/android/design/Android_Design_Holo_Widgets_20120302.zip">Adobe&reg; Photoshop&reg; Sources</a>
 </p>
 
   </div>

docs/html/design/get-started/principles.jd

@@ -10,7 +10,7 @@ with purpose.</p>
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>Delight me in surprising ways</h4>
+<h4 id="delight-me">Delight me in surprising ways</h4>
 <p>A beautiful surface, a carefully-placed animation, or a well-timed sound effect is a joy to
 experience. Subtle effects contribute to a feeling of effortlessness and a sense that a powerful
 force is at hand.</p>
@@ -28,7 +28,7 @@ force is at hand.</p>
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>Real objects are more fun than buttons and menus</h4>
+<h4 id="real-objects-more-fun">Real objects are more fun than buttons and menus</h4>
 <p>Allow people to directly touch and manipulate objects in your app. It reduces the cognitive effort
 needed to perform a task while making it more emotionally satisfying.</p>
 
@@ -45,7 +45,7 @@ needed to perform a task while making it more emotionally satisfying.</p>
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>Let me make it mine</h4>
+<h4 id="make-it-mine">Let me make it mine</h4>
 <p>People love to add personal touches because it helps them feel at home and in control. Provide
 sensible, beautiful defaults, but also consider fun, optional customizations that don't hinder
 primary tasks.</p>
@@ -63,7 +63,7 @@ primary tasks.</p>
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>Get to know me</h4>
+<h4 id="get-to-know-me">Get to know me</h4>
 <p>Learn peoples' preferences over time. Rather than asking them to make the same choices over and
 over, place previous choices within easy reach.</p>
 
@@ -80,7 +80,7 @@ over, place previous choices within easy reach.</p>
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>Keep it brief</h4>
+<h4 id="keep-it-brief">Keep it brief</h4>
 <p>Use short phrases with simple words. People are likely to skip sentences if they're long.</p>
 
   </div>
@@ -96,7 +96,7 @@ over, place previous choices within easy reach.</p>
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>Pictures are faster than words</h4>
+<h4 id="pictures-faster-than-words">Pictures are faster than words</h4>
 <p>Consider using pictures to explain ideas. They get people's attention and can be much more efficient
 than words.</p>
 
@@ -113,7 +113,7 @@ than words.</p>
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>Decide for me but let me have the final say</h4>
+<h4 id="decide-for-me">Decide for me but let me have the final say</h4>
 <p>Take your best guess and act rather than asking first. Too many choices and decisions make people
 unhappy. Just in case you get it wrong, allow for 'undo'.</p>
 
@@ -130,7 +130,7 @@ unhappy. Just in case you get it wrong, allow for 'undo'.</p>
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>Only show what I need when I need it</h4>
+<h4 id="only-show-when-i-need-it">Only show what I need when I need it</h4>
 <p>People get overwhelmed when they see too much at once. Break tasks and information into small,
 digestible chunks. Hide options that aren't essential at the moment, and teach people as they go.</p>
 
@@ -147,7 +147,7 @@ digestible chunks. Hide options that aren't essential at the moment, and teach p
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>I should always know where I am</h4>
+<h4 id="always-know-where-i-am">I should always know where I am</h4>
 <p>Give people confidence that they know their way around. Make places in your app look distinct and
 use transitions to show relationships among screens. Provide feedback on tasks in progress.</p>
 
@@ -164,7 +164,7 @@ use transitions to show relationships among screens. Provide feedback on tasks i
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>Never lose my stuff</h4>
+<h4 id="never-lose-my-stuff">Never lose my stuff</h4>
 <p>Save what people took time to create and let them access it from anywhere. Remember settings,
 personal touches, and creations across phones, tablets, and computers. It makes upgrading the
 easiest thing in the world.</p>
@@ -182,7 +182,7 @@ easiest thing in the world.</p>
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>If it looks the same, it should act the same</h4>
+<h4 id="looks-same-should-act-same">If it looks the same, it should act the same</h4>
 <p>Help people discern functional differences by making them visually distinct rather than subtle.
 Avoid modes, which are places that look similar but act differently on the same input.</p>
 
@@ -199,7 +199,7 @@ Avoid modes, which are places that look similar but act differently on the same
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>Only interrupt me if it's important</h4>
+<h4 id="interrupt-only-if-important">Only interrupt me if it's important</h4>
 <p>Like a good personal assistant, shield people from unimportant minutiae. People want to stay
 focused, and unless it's critical and time-sensitive, an interruption can be taxing and frustrating.</p>
 
@@ -216,7 +216,7 @@ focused, and unless it's critical and time-sensitive, an interruption can be tax
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>Give me tricks that work everywhere</h4>
+<h4 id="give-me-tricks">Give me tricks that work everywhere</h4>
 <p>People feel great when they figure things out for themselves. Make your app easier to learn by
 leveraging visual patterns and muscle memory from other Android apps. For example, the swipe gesture
 may be a good navigational shortcut.</p>
@@ -234,7 +234,7 @@ may be a good navigational shortcut.</p>
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>It's not my fault</h4>
+<h4 id="its-not-my-fault">It's not my fault</h4>
 <p>Be gentle in how you prompt people to make corrections. They want to feel smart when they use your
 app. If something goes wrong, give clear recovery instructions but spare them the technical details.
 If you can fix it behind the scenes, even better.</p>
@@ -252,7 +252,7 @@ If you can fix it behind the scenes, even better.</p>
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>Sprinkle encouragement</h4>
+<h4 id="sprinkle-encouragement">Sprinkle encouragement</h4>
 <p>Break complex tasks into smaller steps that can be easily accomplished. Give feedback on actions,
 even if it's just a subtle glow.</p>
 
@@ -269,7 +269,7 @@ even if it's just a subtle glow.</p>
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>Do the heavy lifting for me</h4>
+<h4 id="do-heavy-lifting-for-me">Do the heavy lifting for me</h4>
 <p>Make novices feel like experts by enabling them to do things they never thought they could. For
 example, shortcuts that combine multiple photo effects can make amateur photographs look amazing in
 only a few steps.</p>
@@ -287,7 +287,7 @@ only a few steps.</p>
 <div class="layout-content-row">
   <div class="layout-content-col span-7">
 
-<h4>Make important things fast</h4>
+<h4 id="make-important-things-fast">Make important things fast</h4>
 <p>Not all actions are equal. Decide what's most important in your app and make it easy to find and
 fast to use, like the shutter button in a camera, or the pause button in a music player.</p>
 

docs/html/design/patterns/actionbar.jd

@@ -176,7 +176,7 @@ themselves.</p>
       <source src="{@docRoot}design/media/tabs_scrolly.ogv" type="video/ogg">
     </video>
     <div class="figure-caption">
-      Scrolling tabs in Google Play.
+      Scrolling tabs in the Play Store app.
       <div class="video-instructions">&nbsp;</div>
     </div>
 

docs/html/design/patterns/app-structure.jd

@@ -7,7 +7,7 @@ page.title=Application Structure
   single screen</li>
 <li>Apps such as Phone whose main purpose is to switch between different activities without deeper
   navigation</li>
-<li>Apps such as Gmail or Google Play that combine a broad set of data views with deep navigation</li>
+<li>Apps such as Gmail or the Play Store that combine a broad set of data views with deep navigation</li>
 </ul>
 <p>Your app's structure depends largely on the content and tasks you want to surface for your users.</p>
 <h2 id="general-structure">General Structure</h2>
@@ -60,7 +60,7 @@ layouts that are visually engaging and appropriate for the data type and screen
 
     <img src="{@docRoot}design/media/app_structure_market.png">
     <div class="figure-caption">
-      The Google Play app's start screen primarily allows navigation into the stores for Apps, Music, Books,
+      The Play Store app's start screen primarily allows navigation into the stores for Apps, Music, Books,
       Movies and Games. It is also enriched with tailored recommendations and promotions that
       surface content of interest to the user. Search is readily available from the action bar.
     </div>
@@ -145,8 +145,8 @@ minimize navigational effort. Rule of thumb: no more than 5&ndash;7 tabs.</p>
 
     <img src="{@docRoot}design/media/app_structure_scrolltabs.png">
     <div class="figure-caption">
-      Google Play uses tabs to simultaneously show category choice and content. To navigate between
-      categories, users can swipe left/right on the content.
+      The Play Store app uses tabs to simultaneously show category choice and content. To navigate
+      between categories, users can swipe left/right on the content.
     </div>
 
   </div>

docs/html/design/patterns/navigation.jd

@@ -13,32 +13,36 @@ the <em>Up</em> button, consisting of the app icon and a left-point caret.</p>
 
 <h2 id="up-vs-back">Up vs. Back</h2>
 
-<p>The Up button is used to navigate within an application based on the hierarchical relationships
+<p>The Up button is used to navigate within an app based on the hierarchical relationships
 between screens. For instance, if screen A displays a list of items, and selecting an item leads to
 screen B (which presents that item in more detail), then screen B should offer an Up button that
 returns to screen A.</p>
-<p>If a screen is the topmost one in an app (i.e. the home of the app), it should not present an Up
+<p>If a screen is the topmost one in an app (that is, the app's home), it should not present an Up
 button.</p>
-<p>The system Back key is used to navigate based on the history of screens the user has recently seen,
-in reverse chronological order&mdash;in effect, the temporal relationships between screens.</p>
+
+<p>The system Back button is used to navigate, in reverse chronological order, through the history
+of screens the user has recently worked with. It is generally based on the temporal relationships
+between screens, rather than the app's hierarchy.</p>
+
 <p>When the previously viewed screen is also the hierarchical parent of the current screen, pressing
-the Back key will have the same result as pressing an Up button -- this is a common occurrence.
-However, unlike the Up button, which ensures the user remains within your app, the Back key can
-return the user to the Home screen, or even to a different application.</p>
+the Back button has the same result as pressing an Up button&mdash;this is a common
+occurrence. However, unlike the Up button, which ensures the user remains within your app, the Back
+button can return the user to the Home screen, or even to a different app.</p>
 
 <img src="{@docRoot}design/media/navigation_up_vs_back_gmail.png">
 
-<p>The Back key also supports a few behaviors not directly tied to screen-to-screen navigation:</p>
+<p>The Back button also supports a few behaviors not directly tied to screen-to-screen navigation:
+</p>
 <ul>
-<li>Back dismisses floating windows (dialogs, popups)</li>
-<li>Back dismisses contextual action bars, and removes the highlight from the selected items</li>
-<li>Back hides the onscreen keyboard (IME)</li>
+<li>Dismisses floating windows (dialogs, popups)</li>
+<li>Dismisses contextual action bars, and removes the highlight from the selected items</li>
+<li>Hides the onscreen keyboard (IME)</li>
 </ul>
 <h2 id="within-app">Navigation Within Your App</h2>
 
 <h4>Navigating to screens with multiple entry points</h4>
 <p>Sometimes a screen doesn't have a strict position within the app's hierarchy, and can be reached
-from multiple entry points&mdash;e.g., a settings screen which can be navigated to from any screen
+from multiple entry points&mdash;such as a settings screen that can be reached from any other screen
 in your app. In this case, the Up button should choose to return to the referring screen, behaving
 identically to Back.</p>
 <h4>Changing view within a screen</h4>
@@ -50,7 +54,7 @@ in the same place within the app's hierarchy, and no new navigation history is c
 <li>Switching views using a dropdown (aka collapsed tabs)</li>
 <li>Filtering a list</li>
 <li>Sorting a list</li>
-<li>Changing display characteristics (e.g. zooming)</li>
+<li>Changing display characteristics (such as zooming)</li>
 </ul>
 <h4>Navigating between sibling screens</h4>
 <p>When your app supports navigation from a list of items to a detail view of one of those items, it's
@@ -61,56 +65,140 @@ navigation does not change the behavior of Up or Back.</p>
 
 <img src="{@docRoot}design/media/navigation_between_siblings_gmail.png">
 
-<p>However, a notable exception to this occurs when browsing between "related" detail views not tied
-together by the referring list&mdash;for example, when browsing on Google Play between apps from
+<p>However, a notable exception to this occurs when browsing between related detail views not tied
+together by the referring list&mdash;for example, when browsing in the Play Store between apps from
 the same developer, or albums by the same artist. In these cases, following each link does create
-history, causing the Back button to step through each screen of related content which has been
-viewed. Up should continue to bypass these related screens and navigate to the most recently viewed
-container screen.</p>
+history, causing the Back button to step through each previously viewed screen. Up should continue
+to bypass these related screens and navigate to the most recently viewed container screen.</p>
 
 <img src="{@docRoot}design/media/navigation_between_siblings_market1.png">
 
 <p>You have the ability to make the Up behavior even smarter based on your knowledge of detail
-view. If we extend our Google Play sample from above, imagine the user has navigated from the last Book
-viewed to the details for the Movie adaptation. In that case, Up can return to a container (Movies)
-which the user had not previously navigated through.</p>
+view. Extending the Play Store example from above, imagine the user has navigated from the last
+Book viewed to the details for the Movie adaptation. In that case, Up can return to a container
+(Movies) which the user hasn't previously navigated through.</p>
 
 <img src="{@docRoot}design/media/navigation_between_siblings_market2.png">
 
-<h2 id="from-outside">Navigation From Outside Your App</h2>
+<h2 id="into-your-app">Navigation into Your App via Home Screen Widgets and Notifications</h2>
+
+<p>You can use Home screen widgets or notifications to help your users navigate directly to screens
+deep within your app's hierarchy. For example, Gmail's Inbox widget and new message notification can
+both bypass the Inbox screen, taking the user directly to a conversation view.</p>
+
+<p>For both of these cases, handle the Up button as follows:</p>
 
-<p>There are two categories of navigation from outside your app to screens deep within the app's
-hierarchy:</p>
 <ul>
-<li>App-to-app navigation, such as via intent completion.</li>
-<li>System-to-app navigation, such as via notifications and home screen widgets.</li>
+<li><em>If the destination screen is typically reached from one particular screen within your
+app</em>, Up should navigate to that screen.</li>
+<li><em>Otherwise</em>, Up should navigate to the topmost ("Home") screen of your app.</li>
 </ul>
-<p>Gmail provides examples of each of these. For app-to-app navigation, a "Share" intent goes directly
-to the compose screen. For system-to-app navigation, both a new message notification and a home
-screen widget can bypass the Inbox screen, taking the user directly to a conversation view.</p>
-<h4>App-to-app navigation</h4>
-<p>When navigating deep into your app's hierarchy directly from another app via an intent, Back will
-return to the referring app.</p>
-<p>The Up button is handled as follows:
-- If the destination screen is typically reached from one particular screen within your app, Up
-  should navigate to that screen.
-- Otherwise, Up should navigate to the topmost ("Home") screen of your app.</p>
-<p>For example, after choosing to share a book being viewed on Google Play, the user navigates directly to
-Gmail's compose screen. From there, Up returns to the Inbox (which happens to be both the
-typical referrer to compose, as well as the topmost screen of the app), while Back returns to
-Google Play.</p>
 
-<img src="{@docRoot}design/media/navigation_from_outside_up.png">
+<p>In the case of the Back button, you should make navigation more predictable by inserting into the
+task's back stack the complete upward navigation path to the app's topmost screen. This allows users
+who've forgotten how they entered your app to navigate to the app's topmost screen before
+exiting.</p>
 
-<h4>System-to-app navigation</h4>
-<p>If your app was reached via the system mechanisms of notifications or home screen widgets, Up
-behaves as described for app-to-app navigation, above.</p>
-<p>For the Back key, you should make navigation more predictably by inserting into the task's back
-stack the complete upward navigation path to the app's topmost screen. This way, a user who has
-forgotten how they entered your app can safely navigate to the app's topmost screen before exiting
-it.</p>
-<p>For example, Gmail's Home screen widget has a button for diving directly to its compose screen.
-After following that path, the Back key first returns to the Inbox, and from there continues to
-Home.</p>
+<p>As an example, Gmail's Home screen widget has a button for diving directly to its compose
+screen. Up or Back from the compose screen would take the user to the Inbox, and from there the
+Back button continues to Home.</p>
 
 <img src="{@docRoot}design/media/navigation_from_outside_back.png">
+
+<h4>Indirect notifications</h4>
+
+<p>When your app needs to present information about multiple events simultaneously, it can use a
+single notification that directs the user to an interstitial screen. This screen summarizes these
+events, and provides paths for the user to dive deeply into the app. Notifications of this style are
+called <em>indirect notifications</em>.</p>
+
+<p>Unlike standard (direct) notifications, pressing Back from an indirect notification's
+interstitial screen returns the user to the point the notification was triggered from&mdash;no
+additional screens are inserted into the back stack. Once the user proceeds into the app from its
+interstitial screen, Up and Back behave as for standard notifications, as described above:
+navigating within the app rather than returning to the interstitial.</p>
+
+<p>For example, suppose a user in Gmail receives an indirect notification from Calendar. Touching
+this notification opens the interstitial screen, which displays reminders for several different
+events. Touching Back from the interstitial returns the user to Gmail. Touching on a particular
+event takes the user away from the interstitial and into the full Calendar app to display details of
+the event. From the event details, Up and Back navigate to the top-level view of Calendar.</p>
+
+<img src="{@docRoot}design/media/navigation_indirect_notification.png">
+
+<h4>Pop-up notifications</h4>
+
+<p><em>Pop-up notifications</em> bypass the notification drawer, instead appearing directly in
+front of the user. They are rarely used, and <strong>should be reserved for occasions where a timely
+response is required and the interruption of the user's context is necessary</strong>. For example,
+Talk uses this style to alert the user of an invitation from a friend to join a video chat, as this
+invitation will automatically expire after a few seconds.</p>
+
+<p>In terms of navigation behavior, pop-up notifications closely follow the behavior of an indirect
+notification's interstitial screen. Back dismisses the pop-up notification. If the user navigates
+from the pop-up into the notifying app, Up and Back follow the rules for standard notifications,
+navigating within the app.</p>
+
+<img src="{@docRoot}design/media/navigation_popup_notification.png">
+
+<h2 id="between-apps">Navigation Between Apps</h2>
+
+<p>One of the fundamental strengths of the Android system is the ability for apps to activate each
+other, giving the user the ability to navigate directly from one app into another. For example, an
+app that needs to capture a photo can activate the Camera app, which will return the photo
+to the referring app. This is a tremendous benefit to both the developer, who can easily leverage
+code from other apps, and the user, who enjoys a consistent experience for commonly performed
+actions.</p>
+
+<p>To understand app-to-app navigation, it's important to understand the Android framework behavior
+discussed below.</p>
+
+<h4>Activities, tasks, and intents</h4>
+
+<p>In Android, an <strong>activity</strong> is an application component that defines a screen of
+information and all of the associated actions the user can perform. Your app is a collection of
+activities, consisting of both the activities you create and those you re-use from other apps.</p>
+
+<p>A <strong>task</strong> is the sequence of activities a user follows to accomplish a goal. A
+single task can make use of activities from just one app, or may draw on activities from a number
+of different apps.</p>
+
+<p>An <strong>intent</strong> is a mechanism for one app to signal it would like another
+app's assistance in performing an action. An app's activities can indicate which intents
+they can respond to. For common intents such as "Share", the user may have many apps installed
+that can fulfill that request.</p>
+
+<h4>Example: navigating between apps to support sharing</h4>
+
+<p>To understand how activities, tasks, and intents work together, consider how one app allows users
+to share content by using another app. For example, launching the Play Store app from Home begins
+new Task A (see figure below). After navigating through the Play Store and touching a promoted book
+to see its details, the user remains in the same task, extending it by adding activities. Triggering
+the Share action prompts the user with a dialog listing each of the activities (from different apps)
+which have registered to handle the Share intent.</p>
+
+<img src="{@docRoot}design/media/navigation_between_apps_inward.png">
+
+<p>When the user elects to share via Gmail, Gmail's compose activity is added as a continuation of
+Task A&mdash;no new task is created. If Gmail had its own task running in the background, it would
+be unaffected.</p>
+
+<p>From the compose activity, sending the message or touching the Back button returns the user to
+the book details activity. Subsequent touches of Back continue to navigate back through the Play
+Store, ultimately arriving at Home.</p>
+
+<img src="{@docRoot}design/media/navigation_between_apps_back.png">
+
+<p>However, by touching Up from the compose activity, the user indicates a desire to remain within
+Gmail. Gmail's conversation list activity appears, and a new Task B is created for it. New tasks are
+always rooted to Home, so touching Back from the conversation list returns there.</p>
+
+<img src="{@docRoot}design/media/navigation_between_apps_up.png">
+
+<p>Task A persists in the background, and the user may return to it later (for example, via the
+Recents screen). If Gmail already had its own task running in the background, it would be replaced
+with Task B&mdash;the prior context is abandoned in favor of the user's new goal.</p>
+
+<p>When your app registers to handle intents with an activity deep within the app's hierarchy,
+refer to <a href="#into-your-app">Navigation into Your App via Home Screen Widgets and
+Notifications</a> for guidance on how to specify Up navigation.</p>

docs/html/design/patterns/pure-android.jd

@@ -48,7 +48,8 @@ conventions of a different platform.</p>
 document or deleting.</p>
 <p>As you are migrating your app to Android, please swap out platform-specific icons with their Android
 counterparts.</p>
-<p>You can find a wide variety of icons for use in your app in the Android SDK.</p>
+<p>You can find a wide variety of icons for use in your app on the
+<a href="{@docRoot}design/downloads/index.html">Downloads</a> page.</p>
 
   </div>
   <div class="layout-content-col span-8">
@@ -86,6 +87,33 @@ platform and to avoid confusion between actions and view switching on Android.</
   </div>
 </div>
 
+<div class="layout-content-row">
+  <div class="layout-content-col span-5">
+
+<h4>Don't hardcode links to other apps</h4>
+<p>In some cases you might want your app to take advantage of another app's feature set. For
+example, you may want to share the content that your app created via a social network or messaging
+app, or view the content of a weblink in a browser. Don't use hard-coded, explicit links to
+particular apps to achieve this. Instead, use Android's intent API to launch an activity chooser
+which lists all applications that are set up to handle the particular request. This lets the user
+complete the task with their preferred app. For sharing in particular, consider using the <em>Share
+Action Provider</em> in your action bar to provide faster access to the user's most recently used
+sharing target.</p>
+
+  </div>
+  <div class="layout-content-col span-8">
+
+    <img src="{@docRoot}design/media/migrating_intents.png">
+    <div class="figure-caption">
+      Link to other apps with the activity chooser or use the <em>Share Action Provider</em> in the
+      action bar.
+    </div>
+
+  </div>
+</div>
+
+<div class="vspace size-2">&nbsp;</div>
+
 <div class="layout-content-row">
   <div class="layout-content-col span-5">
 

docs/html/design/patterns/settings.jd

@@ -0,0 +1,689 @@
+page.title=Settings
+@jd:body
+
+<p>Settings is a place in your app where users indicate their preferences for how your app should
+behave. This benefits users because:</p>
+
+<ul>
+<li>You don't need to interrupt them with the same questions over and over when certain situations
+arise. The settings predetermine what will always happen in those situations (see design
+principle: <a href="{@docRoot}design/get-started/principles.html#decide-for-me">Decide for me but
+let me have the final say</a>).</li>
+<li>You help them feel at home and in control (see design principle:
+<a href="{@docRoot}design/get-started/principles.html#make-it-mine">Let me make it mine</a>).</li>
+</ul>
+
+<h2 id="flow-structure">Flow and Structure</h2>
+
+<h4 id="settings-access">Provide access to Settings in the action overflow</h4>
+
+<p>Settings is given low prominence in the UI because it's not frequently needed. Even if there's
+room in the <a href="{@docRoot}design/patterns/actionbar.html">action bar</a>, never make Settings
+an action button. Always keep it in the action overflow and label it "Settings". Place it below
+all other items except "Help".</p>
+
+<img src="{@docRoot}design/media/settings_overflow.png">
+
+<div class="vspace size-2">&nbsp;</div>
+
+<h4 id="what-to-make-a-setting">Avoid the temptation to make everything a setting</h4>
+
+<p>Because Settings is a few navigational steps away, no matter how many items you have, they'll
+never clutter up the core part of your UI. This may seem like good news, but it also poses a
+challenge.</p>
+
+<p>Settings can be a tempting place to keep a lot of stuff&mdash;like a hall closet where things
+get stashed when you tidy up before company comes over. It's not a place where you spend lots of
+time, so it's easy to rationalize and ignore its cluttered condition. But when users visit
+Settings&mdash;however infrequently&mdash;they'll have the same expectations for the experience as
+they do everywhere else in your app. More settings means more choices to make, and too many are
+overwhelming.</p>
+
+<p>So don't punt on the difficult product decisions and debates that can bring on the urge to
+"just make it a setting". For each control you're considering adding to Settings, make sure it
+meets the bar:</p>
+
+<img src="{@docRoot}design/media/settings_flowchart.png">
+
+<div class="vspace size-3">&nbsp;</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-5 with-callouts">
+
+<h4 id="group-settings">If you still have lots of settings, group related settings together</h4>
+
+<p>The number of items an average human can hold in short-term memory is 7&plusmn;2. If you
+present a list of 10 or more settings (even after applying the criteria above), users will have
+more difficulty scanning, comprehending, and processing them.</p>
+
+<p>You can remedy this by dividing some or all of the settings into groups, effectively turning
+one long list into multiple shorter lists. A group of related settings can be presented in one of
+two ways:</p>
+
+<ol>
+<li><h4>Under a section divider</h4></li>
+<li><h4>In a separate subscreen</h4></li>
+</ol>
+
+<p>You can use one or both these grouping techniques to organize your app's settings.</p>
+
+<p>For example, in the main screen of the Android Settings app, each item in the list navigates
+to a subscreen of related settings. In addition, the items themselves are grouped under section
+dividers.</p>
+
+  </div>
+  <div class="layout-content-col span-8">
+
+    <img src="{@docRoot}design/media/settings_grouping.png">
+
+  </div>
+</div>
+
+<p>Grouping settings is not an exact science, but here's some advice for how to approach it, based
+on the total number of settings in your app.</p>
+
+<div class="vspace size-1">&nbsp;</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-2">
+
+<h4>7 or fewer</h4>
+
+  </div>
+  <div class="layout-content-col span-11">
+
+<p>Don't group them at all. It won't benefit users and will seem like overkill.</p>
+
+  </div>
+</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-2">
+
+<h4>8 to 10</h4>
+
+  </div>
+  <div class="layout-content-col span-11">
+
+<p>Try grouping related settings under 1 or 2 section dividers. If you have any "singletons"
+(settings that don't relate to any other settings and can't be grouped under your section
+dividers), treat them as follows:</p>
+
+<ul>
+<li>If they include some of your most important settings, list them at the top without a section
+divider.</li>
+<li>Otherwise, list them at the bottom with a section divider called "OTHER", in order of
+importance.</li>
+</ul>
+
+  </div>
+</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-2">
+
+<h4>11 to 15</h4>
+
+  </div>
+  <div class="layout-content-col span-11">
+
+<p>Same advice as above, but try 2 to 4 section dividers.</p>
+
+<p>Also, try the following to reduce the list:</p>
+
+<ul>
+<li>If 2 or more of the settings are mainly for power users, move them out of your main Settings
+screen and into an "Advanced" subscreen. Place an item in the action overflow called "Advanced" to
+navigate to it.</li>
+<li>Look for "doubles": two settings that relate to one another, but not to any other settings.
+Try to combine them into one setting, using the design patterns described later in this section.
+For example, you might be able to redesign two related checkbox settings into one multiple choice
+setting.</li>
+</ul>
+
+  </div>
+</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-2">
+
+<h4>16 or more</h4>
+
+  </div>
+  <div class="layout-content-col span-11">
+
+<p>If you have any instances of 4 or more related settings, group them under a subscreen. Then use
+the advice suggested above for the reduced list size.</p>
+
+  </div>
+</div>
+
+
+<h2 id="patterns">Design Patterns</h2>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-3">
+
+<h4>Checkbox</h4>
+<p>Use this pattern for a setting that is either selected or not selected.</p>
+
+  </div>
+  <div class="layout-content-col span-10">
+
+<img src="{@docRoot}design/media/settings_checkbox.png">
+
+  </div>
+</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-3">
+
+<h4>Multiple choice</h4>
+<p>Use this pattern for a setting that needs to present a discrete set of options, from which the
+user can choose only one.</p>
+
+  </div>
+  <div class="layout-content-col span-10">
+
+<img src="{@docRoot}design/media/settings_multiple_choice.png">
+
+  </div>
+</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-3">
+
+<h4>Slider</h4>
+<p>Use this pattern for a setting where the range of values are not discrete and fall along a
+continuum.</p>
+
+  </div>
+  <div class="layout-content-col span-10">
+
+<img src="{@docRoot}design/media/settings_slider.png">
+
+  </div>
+</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-3">
+
+<h4>Date/time</h4>
+<p>Use this pattern for a setting that needs to collect a date and/or time from the user.</p>
+
+  </div>
+  <div class="layout-content-col span-10">
+
+<img src="{@docRoot}design/media/settings_date_time.png">
+
+  </div>
+</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-3">
+
+<h4>Subscreen navigation</h4>
+<p>Use this pattern for navigating to a subscreen or sequence of subscreens that guide the user
+through a more complex setup process.</p>
+<ul>
+<li>If navigating to a single subscreen, use the same title in both the subscreen and the label
+navigating to it.</li>
+<li>If navigating to a sequence of subscreens (as in this example), use a title that describes the
+first step in the sequence.</li>
+</ul>
+
+  </div>
+  <div class="layout-content-col span-10">
+
+<img src="{@docRoot}design/media/settings_subscreen_navigation.png">
+
+  </div>
+</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-3">
+
+<h4>List subscreen</h4>
+<p>Use this pattern for a setting or category of settings that contains a list of equivalent items.
+</p>
+<p>The label provides the name of the item, and secondary text may be used for status. (In this
+example, status is reinforced with an icon to the right of the label.) Any actions associated with
+the list appear in the action bar rather than the list itself.</p>
+
+  </div>
+  <div class="layout-content-col span-10">
+
+<img src="{@docRoot}design/media/settings_list_subscreen.png">
+
+  </div>
+</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-3">
+
+<h4>Master on/off switch</h4>
+<p>Use this pattern for a category of settings that need a mechanism for turning on or off as a
+whole.</p>
+<p>An on/off switch is placed as the first item in the action bar of a subscreen. When the switch
+is turned off, the items in the list disappear, replaced by text that describes why the list is
+empty. If any actions require the switch to be on, they become disabled.</p>
+
+  </div>
+  <div class="layout-content-col span-10">
+
+<img src="{@docRoot}design/media/settings_master_on_off.png">
+
+  </div>
+</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-3">
+
+<div class="vspace size-2">&nbsp;</div>
+
+<p>You can also echo the master on/off switch in the menu item that leads to the subscreen.
+However, you should only do this in cases where users rarely need to access the subscreen once
+it's initially set up and more often just want to toggle the switch.</p>
+
+  </div>
+  <div class="layout-content-col span-10">
+
+<img src="{@docRoot}design/media/settings_master_on_off_2.png">
+
+  </div>
+</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-3">
+
+<h4>Individual on/off switch</h4>
+<p>Use this pattern for an individual setting that requires a more elaborate description than can
+be provided in checkbox form.</p>
+<p>The on/off switch only appears in the subscreen so that users aren't able to toggle it without
+also being exposed to the descriptive text. Secondary text appears below the setting label to
+reflect the current selection.</p>
+<p>In this example, Android Beam is on by default. Since users might not know what this setting
+does, we made the status more descriptive than just "On".</p>
+
+  </div>
+  <div class="layout-content-col span-10">
+
+<img src="{@docRoot}design/media/settings_individual_on_off.png">
+
+  </div>
+</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-3">
+
+<h4>Dependency</h4>
+<p>Use this pattern for a setting that changes availability based on the value of another setting.
+</p>
+<p>The disabled setting appears below its dependency, without any indentation. If the setting
+includes a status line, it says "Unavailable", and if the reason isn't obvious, a brief
+explanation is included in the status.</p>
+<p>If a given setting is a dependency to 3 or more settings, consider using a subscreen with a
+master on/off switch so that your main settings screen isn't cluttered by lots of disabled items.
+</p>
+
+  </div>
+  <div class="layout-content-col span-10">
+
+<img src="{@docRoot}design/media/settings_dependency.png">
+
+  </div>
+</div>
+
+<h2 id="defaults">Defaults</h2>
+
+<p>Take great care in choosing default values for each of your settings. Because settings
+determine app behavior, your choices will contribute to users' first impressions of your app. Even
+though users can change settings, they'll expect the initial states to be sensible. The following
+questions (when applicable) may help inform your decisions:</p>
+
+<ul>
+<li>Which choice would most users be likely to choose on their own if there were no default?</li>
+<li>Which choice is the most neutral or middle-of-the-road?</li>
+<li>Which choice is the least risky, controversial, or over-the-top?</li>
+<li>Which choice uses the least amount of battery or mobile data?</li>
+<li>Which choice best supports the design principle
+<a href="{@docRoot}design/get-started/principles.html#never-lose-my-stuff">Never lose my stuff</a>?</li>
+<li>Which choice best supports the design principle
+<a href="{@docRoot}design/get-started/principles.html#interrupt-only-if-important">Only interrupt
+me if it's important</a>?
+</li>
+</ul>
+
+<h2 id="writing">Writing Guidelines</h2>
+
+<h4>Label clearly and concisely</h4>
+
+<p>Writing a good label for a setting can be challenging because space is very limited. You only
+get one line, and it's incredibly short on the smallest of devices. Follow these guidelines to
+make your labels brief, meaningful, and scannable:</p>
+
+<ul>
+<li>Write each label in sentence case (i.e. only the first word and proper nouns are capitalized).
+</li>
+<li>Don't start a label with an instructional verb like "Set", "Change", "Edit", "Modify",
+"Manage", "Use", "Select", or "Choose". Users already understand that they can do these things to
+settings.</li>
+<li>Likewise, don't end a label with a word like "setting" or "settings". It's already implied.
+</li>
+<li>If the setting is part of a grouping, don't repeat the word(s) used in the section divider or
+subscreen title.</li>
+<li>Avoid starting a label with a negative word like "Don't" or "Never". For example, "Don't
+allow" could be rephrased to "Block".</li>
+<li>Steer clear of technical jargon as much as possible, unless it's a term widely understood by
+your target users. Use common verbs and nouns to convey the setting's purpose rather than its
+underlying technology.</li>
+<li>Don't refer to the user. For example, for a setting allowing the user to turn notifications on
+or off, label it "Notifications" instead of "Notify me".</li>
+</ul>
+
+<p>Once you've decided on labels for your settings, be sure to preview them on an
+<a href="{@docRoot}design/style/metrics-grids.html">LDPI handset</a> in portrait to make sure
+they'll fit everywhere.</p>
+
+<h4>Secondary text below is for status, not description&hellip;</h4>
+
+<p>Before Ice Cream Sandwich, we often displayed secondary text below a label to further describe
+it or provide instructions. Starting in Ice Cream Sandwich, we're using secondary text for status.
+</p>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-4">
+
+    <div class="do-dont-label bad emulate-content-left-padding">Before</div>
+
+    <table class="ui-table bad emulate-content-left-padding">
+    <thead>
+      <tr>
+        <th class="label">
+        Screen timeout
+        </th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td class="secondary-text">
+        Adjust the delay before the screen automatically turns off
+        </td>
+      </tr>
+    </tbody>
+    </table>
+
+  </div>
+  <div class="layout-content-col span-4">
+
+    <div class="do-dont-label good">After</div>
+
+    <table class="ui-table good">
+    <thead>
+      <tr>
+        <th class="label">
+        Sleep
+        </th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td class="secondary-text">
+        After 10 minutes of activity
+        </td>
+      </tr>
+    </tbody>
+    </table>
+
+  </div>
+</div>
+
+<p>Status in secondary text has the following benefits:</p>
+<ul>
+<li>Users can see at a glance what the current value of a setting is without having to navigate
+any further.</li>
+<li>It applies the design principle
+<a href="{@docRoot}design/get-started/principles.html#keep-it-brief">Keep it brief</a>, which
+users greatly appreciate.</li>
+</ul>
+
+<h4>&hellip;unless it's a checkbox setting</h4>
+<p>There's one important exception to the using secondary text for status: checkbox settings.
+Here, use secondary text for description, not status. Status below a checkbox is unnecessary
+because the checkbox already indicates it. The reason why it's appropriate to have a description
+below a checkbox setting is because&mdash;unlike other controls&mdash;it doesn't display a dialog
+or navigate to another screen where additional information can be provided.</p>
+
+<p>That said, if a checkbox setting's label is clear enough on its own, there's no need to also
+provide a description. Only include one if necessary.</p>
+
+<p>Follow these guidelines to write checkbox setting descriptions:</p>
+<ul>
+<li>Keep it to one sentence and don't use ending punctuation.</li>
+<li>Convey what happens when the setting is checked, phrased in the form of a command. Example:
+"Allow data exchange", not "Allows data exchange".</li>
+<li>Avoid repetition by choosing words that don't already appear in the label.</li>
+<li>Don't refer to the user unless it's necessary for understanding the setting.</li>
+<li>If you must refer to the user, do so in the second person ("you") rather than the first person
+("I"). Android speaks to users, not on behalf of them.</li>
+</ul>
+
+<h4>Writing examples</h4>
+
+<p>The following are examples of changes we made to labels and secondary text in the Settings app
+in Ice Cream Sandwich.</p>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-4">
+
+    <div class="do-dont-label bad emulate-content-left-padding">Before</div>
+
+    <table class="ui-table bad emulate-content-left-padding">
+    <thead>
+      <tr>
+        <th class="label">
+        Use tactile feedback
+        </th>
+      </tr>
+    </thead>
+    </table>
+
+  </div>
+  <div class="layout-content-col span-4">
+
+    <div class="do-dont-label good">After</div>
+
+    <table class="ui-table good">
+    <thead>
+      <tr>
+        <th class="label">
+        Vibrate on touch
+        </th>
+      </tr>
+    </thead>
+    </table>
+
+  </div>
+  <div class="layout-content-col span-5">
+
+<p>In this checkbox setting, we eliminated the throwaway word "Use" and rephrased the label to be
+more direct and understandable.</p>
+
+  </div>
+
+</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-4">
+
+    <div class="do-dont-label bad emulate-content-left-padding">Before</div>
+
+    <table class="ui-table bad emulate-content-left-padding">
+    <thead>
+      <tr>
+        <th class="label">
+        Screen timeout
+        </th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td class="secondary-text">
+        Adjust the delay before the screen automatically turns off
+        </td>
+      </tr>
+    </tbody>
+    </table>
+
+  </div>
+  <div class="layout-content-col span-4">
+
+    <div class="do-dont-label good">After</div>
+
+    <table class="ui-table good">
+    <thead>
+      <tr>
+        <th class="label">
+        Sleep
+        </th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td class="secondary-text">
+        After 10 minutes of activity
+        </td>
+      </tr>
+    </tbody>
+    </table>
+
+  </div>
+  <div class="layout-content-col span-5">
+
+<p>In this multiple choice setting, we changed the label to a friendlier term and also replaced
+the description with status. We put some descriptive words around the selected value, "10
+minutes", because on its own, the meaning could be misinterpreted as "sleep for 10 minutes".</p>
+
+  </div>
+</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-4">
+
+    <div class="do-dont-label bad emulate-content-left-padding">Before</div>
+
+    <table class="ui-table bad emulate-content-left-padding">
+    <thead>
+      <tr>
+        <th class="label">
+        Change screen lock
+        </th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td class="secondary-text">
+        Change or disable pattern, PIN, or password security
+        </td>
+      </tr>
+    </tbody>
+    </table>
+
+  </div>
+  <div class="layout-content-col span-4">
+
+    <div class="do-dont-label good">After</div>
+
+    <table class="ui-table good">
+    <thead>
+      <tr>
+        <th class="label">
+        Screen lock
+        </th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td class="secondary-text">
+        Pattern
+        </td>
+      </tr>
+    </tbody>
+    </table>
+
+  </div>
+  <div class="layout-content-col span-5">
+
+<p>This setting navigates to a a sequence of subscreens that allow users to choose a type of
+screen lock and then set it up. We eliminated the throwaway word "Change" in the label, and
+replaced the description with the current type of screen lock set up by the user. If the user
+hasn't set up a screen lock, the secondary text says "None".</p>
+
+  </div>
+</div>
+
+<div class="layout-content-row">
+  <div class="layout-content-col span-4">
+
+    <div class="do-dont-label bad emulate-content-left-padding">Before</div>
+
+    <table class="ui-table bad emulate-content-left-padding">
+    <thead>
+      <tr>
+        <th class="label">
+        NFC
+        </th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td class="secondary-text">
+        Use Near Field Communication to read and exchange tags
+        </td>
+      </tr>
+    </tbody>
+    </table>
+
+  </div>
+  <div class="layout-content-col span-4">
+
+    <div class="do-dont-label good">After</div>
+
+    <table class="ui-table good">
+    <thead>
+      <tr>
+        <th class="label">
+        NFC
+        </th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td class="secondary-text">
+        Allow data exchange when the phone touches another device
+        </td>
+      </tr>
+    </tbody>
+    </table>
+
+  </div>
+  <div class="layout-content-col span-5">
+
+<p>In this checkbox setting&mdash;although it's technical jargon&mdash;we kept the "NFC" label
+because: (1) we couldn't find a clear, concise alternative, and (2) user familiarity with the
+acronym is expected to increase dramatically in the next couple of years.</p>
+<p>We did, however, rewrite the description. It's far less technical than before and does a better
+job of conveying how and why you'd use NFC. We didn't include what the acronym stands for because
+it doesn't mean anything to most users and would have taken up a lot of space.</p>
+
+  </div>
+</div>
+
+<h2 id="checklist">Checklist</h2>
+<ul>
+<li><p>Make sure each item in Settings meets the criteria for belonging there.</p></li>
+<li><p>If you have more than 7 items, explore ways to group related settings.</p></li>
+<li><p>Use design patterns wherever applicable so users don't face a learning curve.</p></li>
+<li><p>Choose defaults that are safe, neutral, and fit the majority of users.</p></li>
+<li><p>Give each setting a clear, concise label and use secondary text appropriately.</p></li>
+</ul>

docs/html/design/style/writing.jd

@@ -1,58 +1,6 @@
 page.title=Writing Style
 @jd:body
 
-<style>
-
-/* UI tables */
-
-.ui_table {
-  width: 100%;
-  background: #282828;
-  color: #fff;
-  border-radius: 2px;
-  box-shadow: 0 2px 4px rgba(0,0,0,0.25);
-  border-collapse: separate;
-}
-
-.ui_table th,
-.ui_table td {
-  padding: 5px 10px;
-}
-
-.ui_table thead th {
-  font-weight: 600;
-}
-
-.ui_table tfoot td {
-  border-top: 1px solid #494949;
-  border-right: 1px solid #494949;
-  text-align: center;
-}
-
-.ui_table tfoot td:last-child {
-  border-right: 0;
-}
-
-.list_item_margins {
-  margin-left: 30px !important;
-}
-
-.example_label {
-  margin-bottom: 10px;
-  padding-left: 20px;
-  background: transparent none no-repeat scroll 0px 3px;
-}
-
-.example_label.bad {
-  background-image: url({@docRoot}assets/design/ico_wrong.png);
-}
-
-.example_label.good {
-  background-image: url({@docRoot}assets/design/ico_good.png);
-}
-
-</style>
-
 <p>When choosing words for your app:</p>
 <ol>
 <li>
@@ -90,20 +38,20 @@ page.title=Writing Style
 <ol><li class="value-1"><strong>Keep it brief.</strong> From the setup wizard:</ol>
 
 <div class="layout-content-row">
-  <div class="layout-content-col span-6 list_item_margins">
+  <div class="layout-content-col span-6 layout-with-list-item-margins">
 
-    <div class="example_label bad">Too formal</div>
+    <div class="do-dont-label bad">Too formal</div>
 
-    <table class="ui_table good"><tbody><tr><td>
+    <table class="ui-table good"><tbody><tr><td>
     Consult the documentation that came with your phone for further instructions.
     </td></tr></tbody></table>
 
   </div>
   <div class="layout-content-col span-6">
 
-    <div class="example_label good">Better</div>
+    <div class="do-dont-label good">Better</div>
 
-    <table class="ui_table good"><tbody><tr><td>
+    <table class="ui-table good"><tbody><tr><td>
     Read the instructions that came with your phone.
     </td></tr></tbody></table>
 
@@ -115,11 +63,11 @@ page.title=Writing Style
 <ol><li class="value-2"><strong>Keep it simple.</strong> From the Location settings screen:</ol>
 
 <div class="layout-content-row">
-  <div class="layout-content-col span-6 list_item_margins">
+  <div class="layout-content-col span-6 layout-with-list-item-margins">
 
-    <div class="example_label bad">Confusing</div>
+    <div class="do-dont-label bad">Confusing</div>
 
-    <table class="ui_table bad">
+    <table class="ui-table bad">
     <thead>
       <tr>
         <th>
@@ -139,9 +87,9 @@ page.title=Writing Style
   </div>
   <div class="layout-content-col span-6">
 
-    <div class="example_label good">Better</div>
+    <div class="do-dont-label good">Better</div>
 
-    <table class="ui_table good">
+    <table class="ui-table good">
     <thead>
       <tr>
         <th>
@@ -167,12 +115,12 @@ page.title=Writing Style
 crashes:</ol>
 
 <div class="layout-content-row">
-  <div class="layout-content-col span-6 list_item_margins">
+  <div class="layout-content-col span-6 layout-with-list-item-margins">
 
-    <div class="example_label bad">Confusing and annoying&mdash;"Sorry" just rubs salt in the
+    <div class="do-dont-label bad">Confusing and annoying&mdash;"Sorry" just rubs salt in the
     wound.</div>
 
-    <table class="ui_table bad">
+    <table class="ui-table bad">
     <thead>
       <tr>
         <th colspan="3">
@@ -200,9 +148,9 @@ crashes:</ol>
   </div>
   <div class="layout-content-col span-6">
 
-    <div class="example_label good">Shorter, more direct, no faux-apologetic title:<br><br></div>
+    <div class="do-dont-label good">Shorter, more direct, no faux-apologetic title:<br><br></div>
 
-    <table class="ui_table good">
+    <table class="ui-table good">
     <thead>
       <tr>
         <th colspan="3">
@@ -234,20 +182,20 @@ crashes:</ol>
 <ol><li class="value-4"><strong>Put the most important thing first.</strong></ol>
 
 <div class="layout-content-row">
-  <div class="layout-content-col span-6 list_item_margins">
+  <div class="layout-content-col span-6 layout-with-list-item-margins">
 
-    <div class="example_label bad">Top news last</div>
+    <div class="do-dont-label bad">Top news last</div>
 
-    <table class="ui_table bad"><tbody><tr><td>
+    <table class="ui-table bad"><tbody><tr><td>
     77 other people +1'd this, including Larry Page.
     </td></tr></tbody></table>
 
   </div>
   <div class="layout-content-col span-6">
 
-    <div class="example_label good">Top news first</div>
+    <div class="do-dont-label good">Top news first</div>
 
-    <table class="ui_table good"><tbody><tr><td>
+    <table class="ui-table good"><tbody><tr><td>
     Larry Page and 77 others +1'd this.
     </td></tr></tbody></table>
 
@@ -255,20 +203,20 @@ crashes:</ol>
 </div>
 
 <div class="layout-content-row">
-  <div class="layout-content-col span-6 list_item_margins">
+  <div class="layout-content-col span-6 layout-with-list-item-margins">
 
-    <div class="example_label bad">Task last</div>
+    <div class="do-dont-label bad">Task last</div>
 
-    <table class="ui_table bad"><tbody><tr><td>
+    <table class="ui-table bad"><tbody><tr><td>
     Touch Next to complete setup using a Wi-Fi connection.
     </td></tr></tbody></table>
 
   </div>
   <div class="layout-content-col span-6">
 
-    <div class="example_label good">Task first</div>
+    <div class="do-dont-label good">Task first</div>
 
-    <table class="ui_table good"><tbody><tr><td>
+    <table class="ui-table good"><tbody><tr><td>
     To finish setup using Wi-Fi, touch Next.
     </td></tr></tbody></table>
 
@@ -280,11 +228,11 @@ crashes:</ol>
 <ol><li class="value-5"><strong>Describe only what's necessary, and no more.</strong></ol>
 
 <div class="layout-content-row">
-  <div class="layout-content-col span-6 list_item_margins">
+  <div class="layout-content-col span-6 layout-with-list-item-margins">
 
-    <div class="example_label bad">From a Setup Wizard screen</div>
+    <div class="do-dont-label bad">From a Setup Wizard screen</div>
 
-    <table class="ui_table bad">
+    <table class="ui-table bad">
     <thead>
       <tr>
         <th>
@@ -306,9 +254,9 @@ crashes:</ol>
   </div>
   <div class="layout-content-col span-6">
 
-    <div class="example_label good">From a Setup Wizard screen</div>
+    <div class="do-dont-label good">From a Setup Wizard screen</div>
 
-    <table class="ui_table good">
+    <table class="ui-table good">
     <thead>
       <tr>
         <th>