docs: Material L Preview engineering review fixes

Change-Id: I3fc95b65515ae75d6c74a62f9614f994cfb83df3

11 files changed, 305 insertions, 202 deletions

diff --git a/docs/html/preview/material/animations.jd b/docs/html/preview/material/animations.jd
index cee782a..b8d063b 100644
--- a/docs/html/preview/material/animations.jd
+++ b/docs/html/preview/material/animations.jd
@@ -10,8 +10,9 @@ page.title=Animations
   <li><a href="#reveal">Reveal Effect</a></li>
   <li><a href="#transitions">Activity Transitions</a></li>
   <li><a href="#curvedmotion">Curved Motion</a></li>
-  <li><a href="#viewstate">View State Changes</a></li>
+  <li><a href="#viewstate">Animating View State Changes</a></li>
   <li><a href="#drawabletint">Drawable Tinting</a></li>
+  <li><a href="#colorextract">Extracting Colors from an Image</a></li>
 </ol>
 </div>
 </div>
@@ -32,19 +33,26 @@ APIs that let you customize these animations and create new ones:</p>
 
 <h2 id="touch">Touch Feedback</h2>
 
-<p>In the Android L Developer Preview the default touch feedback animations for buttons use the new
+<p>The default touch feedback animations for buttons use the new
 <code>RippleDrawable</code> class, which transitions between different states with a ripple
 effect.</p>
 
-<p>To use this functionality in your custom views, create a <code>RippleDrawable</code> and set
-it as the background of your view. You can define a <code>RippleDrawable</code> as an XML resource
-using the <code>ripple</code> element.</p>
+<p>In most cases, this functionality should be applied in your view XML by specifying the
+background as <code>?android:attr/selectableItemBackground</code> for a bounded ripple or
+<code>?android:attr/selectableItemBackgroundBorderless</code> for a ripple that extends beyond
+the view bounds. You can also create a <code>RippleDrawable</code> and set
+it as the background of your view. Alternatively, you can define a <code>RippleDrawable</code>
+as an XML resource using the <code>ripple</code> element. The
+Android L Developer Preview animates the selection color with a ripple effect.</p>
+
+<p>You can assign a color to <code>RippleDrawable</code> objects. To change the default touch
+feedback color, use the theme's <code>android:colorControlHighlight</code> attribute.</p>
 
 
 <h2 id="reveal">Reveal Effect</h2>
 
-<p>The <code>View.createRevealAnimator</code> method enables you to animate a clipping circle
-to reveal or hide a view.</p>
+<p>The <code>ViewAnimationUtils.createCircularReveal</code> method enables you to animate a
+clipping circle to reveal or hide a view.</p>
 
 <p>To reveal a previously invisible view using this effect:</p>
 
@@ -61,7 +69,8 @@ int finalRadius = myView.getWidth();
 
 // create and start the animator for this view
 // (the start radius is zero)
-ValueAnimator anim = myView.createRevealAnimator(cx, cy, 0, finalRadius);
+ValueAnimator anim =
+    ViewAnimationUtils.createCircularReveal(myView, cx, cy, 0, finalRadius);
 anim.start();
 </pre>
 
@@ -79,7 +88,8 @@ int cy = (myView.getTop() + myView.getBottom()) / 2;
 int initialRadius = myView.getWidth();
 
 // create the animation (the final radius is zero)
-ValueAnimator anim = myView.createRevealAnimator(cx, cy, initialRadius, 0);
+ValueAnimator anim =
+    ViewAnimationUtils.createCircularReveal(myView, cx, cy, initialRadius, 0);
 
 // make the view invisible when the animation is done
 anim.addListener(new AnimatorListenerAdapter() {
@@ -97,25 +107,48 @@ anim.start();
 
 <h2 id="transitions">Activity Transitions</h2>
 
-<p>The Android L Developer Preview enables your app to customize the default animations for
-activity transitions. You can specify custom animations for enter and exit transitions and for
+<p>You can specify custom animations for enter and exit transitions and for
 transitions of shared elements between activities.</p>
 
 <ul>
-  <li>An <strong>enter</strong> transition determines how views in an activity enter the scene.
-  For example, in the <em>explode</em> enter transition the views enter the scene from outside
-  and fly in towards the center of the screen.</li>
-
-  <li>An <strong>exit</strong> transition determines how views in an activity exit the scene. For
-  example, in the <em>explode</em> exit transition the views exit the scene away from the
-  center.</li>
-
-  <li>A <strong>shared elements</strong> transition determines how views that are shared between
-  two activities transition between these activities. For example, if two activities have the same
-  image in different positions and sizes, the <em>moveImage</em> shared element transition
-  translates and scales the image smoothly between these activities.</li>
+<li>An <strong>enter</strong> transition determines how views in an activity enter the scene.
+For example, in the <em>explode</em> enter transition, the views enter the scene from the outside
+and fly in towards the center of the screen.</li>
+
+<li>An <strong>exit</strong> transition determines how views in an activity exit the scene. For
+  example, in the <em>explode</em> exit transition, the views exit the scene away from the
+center.</li>
+
+<li>A <strong>shared elements</strong> transition determines how views that are shared between
+two activities transition between these activities. For example, if two activities have the same
+image in different positions and sizes, the <em>moveImage</em> shared element transition
+translates and scales the image smoothly between these activities.</li>
+</ul>
+
+<p>The Android L Developer Preview supports these enter and exit transitions:</p>
+
+<ul>
+<li><em>explode</em> - Moves views in or out from the center of the scene.</li>
+<li><em>slide</em> - Moves views in or out from one of the edges of the scene.</li>
+<li><em>fade</em> - Mades views in or out of the scene.</li>
 </ul>
 
+<p>Any transition that extends the <code>android.transition.Visibility</code> class is supported
+as an enter or exit transition. For more information, see the API reference for the
+<code>android.transition.Transition</code> class.</p>
+
+<p>The Android L Developer Preview also supports these shared elements transitions:</p>
+
+<ul>
+<li><em>changeBounds</em> - Animates the changes in layout bounds of target views.</li>
+<li><em>changeClipBounds</em> - Animates the changes in clip bounds of target views.</li>
+<li><em>changeTransform</em> - Animates the changes in scale and rotation of target views.</li>
+<li><em>moveImage</em> - Animates changes in size and scale type for an image view.</li>
+</ul>
+
+<p>When you enable activity transitions in your app, the default cross-fading transition is
+activated between the entering and exiting activities.</p>
+
 <img src="/preview/material/images/SceneTransition.png" alt=""
      id="figure1" style="width:600px;margin-top:20px"/>
 <p class="img-caption">
@@ -125,7 +158,8 @@ transitions of shared elements between activities.</p>
 <h3>Specify custom transitions</h3>
 
 <p>First, enable window content transitions with the <code>android:windowContentTransitions</code>
-attribute when you define a style that inherits from the material theme:</p>
+attribute when you define a style that inherits from the material theme. You can also specify
+enter, exit, and shared element transitions in your style definition:</p>
 
 <pre>
 &lt;style name="BaseAppTheme" parent="android:Theme.Material">
@@ -144,21 +178,13 @@ attribute when you define a style that inherits from the material theme:</p>
 &lt;/style>
 </pre>
 
-<p>You can also specify enter, exit, and shared element transitions in your style definition.
-The <code>move_image</code> transition in this example is defined as follows:</p>
+<p>The <code>move_image</code> transition in this example is defined as follows:</p>
 
 <pre>
 &lt;!-- res/transition/move_image.xml -->
 &lt;!-- (see also Shared Transitions below) -->
 &lt;transitionSet xmlns:android="http://schemas.android.com/apk/res/android">
-  &lt;moveImage>
-    &lt;targets>
-      &lt;!-- shared view in the first activity -->
-      &lt;target android:targetId="@id/image_small" />
-      &lt;!-- shared view in the second activity -->
-      &lt;target android:targetId="@id/image_big" />
-    &lt;/targets>
-  &lt;/moveImage>
+  &lt;moveImage/>
 &lt;/transitionSet>
 </pre>
 
@@ -170,7 +196,7 @@ class. For more information, see the API reference for <code>android.transition.
 <code>Window.requestFeature</code> method:</p>
 
 <pre>
-// inside your activity
+// inside your activity (if you did not enable transitions in your theme)
 getWindow().requestFeature(Window.FEATURE_CONTENT_TRANSITIONS);
 
 // set an exit transition
@@ -187,6 +213,20 @@ object:</p>
   <li><code>Window.setSharedElementExitTransition</code></li>
 </ul>
 
+<p>The <code>setExitTransition</code> and <code>setSharedElementExitTransition</code> methods
+define the exit transition for the calling activity. The <code>setEnterTransition</code> and
+<code>setSharedElementEnterTransition</code> methods define the enter transition for the called
+activity.</p>
+
+<p>To get the full effect of a transition, you must enable window content transitions on both the
+calling and called activities. Otherwise, the calling activity will start the exit transition,
+but then you'll see a window transition (like scale or fade).</p>
+
+<p>To start an enter transition as soon as possible, use the
+<code>Window.setAllowEnterTransitionOverlap</code> method on the called activity. This lets you
+have more dramatic enter transitions. The same applies for the calling activity and exit
+transitions with the <code>Window.setAllowExitTransitionOverlap</code> method.</p>
+
 <h3>Start an activity using transitions</h3>
 
 <p>If you enable transitions and set an exit transition for an activity, the transition is activated
@@ -201,7 +241,7 @@ starts.</p>
 <ol>
 <li>Enable window content transitions in your style.</li>
 <li>Specify a shared elements transition in your style.</li>
-<li>Define your transition as an XML resource specifying the IDs of the target views.</li>
+<li>Define your transition as an XML resource.</li>
 <li>Assign a common name to the shared elements in both layouts with the
     <code>android:viewName</code> attribute.</li>
 <li>Use the <code>ActivityOptions.makeSceneTransitionAnimation</code> method.</li>
@@ -212,7 +252,7 @@ starts.</p>
 final View imgContainerView = findViewById(R.id.img_container);
 
 // get the common element for the transition in this activity
-final View androidRobotView = findViewById(R.id.android_robot_img);
+final View androidRobotView = findViewById(R.id.image_small);
 
 // define a click listener
 imgContainerView.setOnClickListener(new View.OnClickListener() {
@@ -232,6 +272,9 @@ imgContainerView.setOnClickListener(new View.OnClickListener() {
 <p>For shared dynamic views that you generate in your code, use the <code>View.setViewName</code>
 method to specify a common element name in both activities.</p>
 
+<p>To reverse the scene transition animation when you finish the second activity, call the
+<code>Activity.finishAfterTransition</code> method instead of <code>Activity.finish</code>.</p>
+
 <h3>Multiple shared elements</h3>
 
 <p>To make a scene transition animation between two activities that have more than one shared
@@ -241,12 +284,8 @@ attribute (or use the <code>View.setViewName</code> in both activities), and cre
 
 <pre>
 ActivityOptions options = ActivityOptions.makeSceneTransitionAnimation(this,
-    new Pair[] {
         Pair.create(view1, "agreedName1"),
-        Pair.create(view2, "agreedName2"),
-        ...
-    }
-);
+        Pair.create(view2, "agreedName2"));
 </pre>
 
 
@@ -279,7 +318,7 @@ material design specification:</p>
 </ul>
 
 <p>You can pass a <code>PathInterpolator</code> object to the
-<code>Animation.setInterpolation</code> method.</p>
+<code>Animator.setInterpolation</code> method.</p>
 
 <p>The <code>ObjectAnimator</code> class has new constructors that enable you to animate
 coordinates along a path using two or more properties at once. For example, the following animator
@@ -293,20 +332,20 @@ mAnimator.start();
 </pre>
 
 
-<h2 id="viewstate">View State Changes</h2>
+<h2 id="viewstate">Animating View State Changes</h2>
 
 <p>The new <code>StateListAnimator</code> class lets you define animators that run when the state
 of a view changes. The following example shows how to define an <code>StateListAnimator</code> as
 an XML resource:</p>
 
 <pre>
-&lt;!-- animate the elevation property of a view when pressed -->
+&lt;!-- animate the translationZ property of a view when pressed -->
 &lt;selector xmlns:android="http://schemas.android.com/apk/res/android">
   &lt;item android:state_pressed="true">
     &lt;set>
-      &lt;objectAnimator android:propertyName="elevation"
+      &lt;objectAnimator android:propertyName="translationZ"
         android:duration="100"
-        android:valueTo="60"
+        android:valueTo="2"
         android:valueType="floatType"/>
         &lt;!-- you could have other objectAnimator elements
              here for "x" and "y", or other properties -->
@@ -316,15 +355,19 @@ an XML resource:</p>
     android:state_pressed="false"
     android:state_focused="true">
     &lt;set>
-      &lt;objectAnimator android:propertyName="elevation"
+      &lt;objectAnimator android:propertyName="translationZ"
         android:duration="100"
-        android:valueTo="10"
+        android:valueTo="2"
         android:valueType="floatType"/>
     &lt;/set>
   &lt;/item>
 &lt;/selector>
 </pre>
 
+<p class="note"><strong>Note:</strong> There is a known issue in the L Developer Preview release
+that requires valueFrom values to be provided in StateListAnimator animations to get the correct
+behavior.</p>
+
 <p>The new <code>AnimatedStateListDrawable</code> class lets you create drawables that show
 animations between state changes of the associated view. Some of the system widgets in the
 Android L Developer Preview use these animations by default. The following example shows how
@@ -337,9 +380,9 @@ to define an <code>AnimatedStateListDrawable</code> as an XML resource:</p>
 
     &lt;!-- provide a different drawable for each state-->
     &lt;item android:id="@+id/pressed" android:drawable="@drawable/drawableP"
-        android:state-pressed="true"/>
+        android:state_pressed="true"/>
     &lt;item android:id="@+id/focused" android:drawable="@drawable/drawableF"
-        android:state-focused="true"/>
+        android:state_focused="true"/>
     &lt;item android:id="@id/default"
         android:drawable="@drawable/drawableD"/>
 
@@ -358,21 +401,41 @@ to define an <code>AnimatedStateListDrawable</code> as an XML resource:</p>
 
 <h2 id="drawabletint">Drawable Tinting</h2>
 
-<p>The Android L Developer Preview enables you to define bitmaps as an alpha mask and to tint
-them using a color resource or a theme attribute that resolves to a color resource. You can
-create these assets only once and color them automatically to match your theme.</p>
+<p>The Android L Developer Preview enables you to define bitmaps or nine-patches as alpha masks and
+to tint them using a color resource or a theme attribute that resolves to a color resource (for
+example, <code>?android:attr/colorPrimary</code>). You can create these assets only once and color them
+automatically to match your theme.</p>
 
-<p>To apply a tint to a bitmap in your code, use the <code>setTint</code> method in these
-classes:</p>
+<p>To apply a tint to a bitmap, use the <code>setTint</code> method or the <code>android:tint</code>
+attribute for <code>BitmapDrawable</code> and <code>NinePatchDrawable</code>.</p>
+
+<p>The <code>setTint</code> method also lets you set the Porter-Duff mode used to blend the
+tint color for <code>NinePatchDrawable</code> and <code>BitmapDrawable</code> objects in your code.
+To set the tint mode in your layouts, use the <code>android:tintMode</code> attribute.</p>
+
+
+<h2 id="colorextract">Extracting Prominent Colors from an Image</h2>
+
+<p>The Android L Developer Preview Support Library includes the <code>Palette</code> class,
+which lets you extract prominent colors from an image. This class extracts the following
+prominent colors:</p>
 
 <ul>
-<li><code>PaintDrawable</code></li>
-<li><code>NinePatchDrawable</code></li>
-<li><code>RippleDrawable</code></li>
+<li>Vibrant</li>
+<li>Vibrant dark</li>
+<li>Vibrant light</li>
+<li>Muted</li>
+<li>Muted dark</li>
+<li>Muted light</li>
 </ul>
 
-<p>In your layouts, use the <code>android:tint</code> attribute instead.</p>
+<p>To extract these colors, pass a <code>Bitmap</code> object to the
+<code>Palette.generate</code> static method in the background thread where you load your images.
+If you can't use that thread, call the <code>Palette.generateAsync</code> method instead and
+provide a listener.</p>
+
+<p>To retrieve the prominent colors from the image, use the getter methods in the
+<code>Palette</code> class, such as <code>Palette.getVibrantColor</code>.</p>
 
-<p>The <code>setTint</code> method also lets you set the tint blending mode for
-<code>NinePatchDrawable</code> and <code>RippleDrawable</code> objects in your code. To set the
-tint mode in your layouts, use the <code>android:tintMode</code> attribute.</p>
+<p>For more information, see the API reference for the
+<code>android.support.v7.graphics.Palette</code> class.</p>
\ No newline at end of file
diff --git a/docs/html/preview/material/compatibility.jd b/docs/html/preview/material/compatibility.jd
index ce04e9e..fb97112 100644
--- a/docs/html/preview/material/compatibility.jd
+++ b/docs/html/preview/material/compatibility.jd
@@ -14,7 +14,7 @@ page.title=Compatibility
 </div>
 </div>
 
-<p>The new material design features (like the material theme and custom animations) are only
+<p>The new material design features (like the material theme and activity transitions) are only
 available in the Android L Developer Preview. However, you can design your apps to make use of
 these features when running on devices with the Android L Developer Preview and still be
 compatible with previous releases of Android.</p>
@@ -49,15 +49,34 @@ alternative layouts to customize how your app looks on earlier versions of Andro
 and your alternative layout files for earlier versions of Android inside <code>res/layout/</code>.
 Alternative layouts have the same file name.</p>
 
+<p>To avoid duplication of code, define your styles inside <code>res/values/</code> and modify the
+styles in <code>res/values-v21/</code> for the new APIs.</p>
+
 
 <h2 id="widgets">UI Widgets</h2>
 
 <p>The <code>RecyclerView</code> and <code>CardView</code> widgets are included in the Android L
-Developer Preview Support Library, so they are available in earlier versions of Android.</p>
+Developer Preview Support Library, so they are available in earlier versions of Android with
+these limitations:</p>
+
+<ul>
+<li><code>CardView</code> falls back to a programmatic shadow implementation using additional padding.</li>
+<li><code>CardView</code> does not clip its children views that intersect with rounded corners.</li>
+</ul>
+
+<p>These limitations do not apply to the Android L Developer Preview.</p>
 
 
 <h2 id="animation">Animation APIs</h2>
 
-<p>The new APIs for custom animations are only available in the Android L Developer Preview. To
-preserve compatibility with earlier verisons of Android, check the system version at runtime before
-you invoke these APIs.</p>
\ No newline at end of file
+<p>The following new APIs are only available in the Android L Developer Preview:</p>
+
+<ul>
+<li>Activity transitions</li>
+<li>Touch feedback</li>
+<li>Reveal animations</li>
+<li>Path-based animations</li>
+</ul>
+
+<p>To preserve compatibility with earlier verisons of Android, check the system version at
+runtime before you invoke these APIs.</p>
\ No newline at end of file
diff --git a/docs/html/preview/material/get-started.jd b/docs/html/preview/material/get-started.jd
index 9c0e55d..7d0625e 100644
--- a/docs/html/preview/material/get-started.jd
+++ b/docs/html/preview/material/get-started.jd
@@ -8,9 +8,9 @@ page.title=Get Started
 <ol>
   <li><a href="#applytheme">Apply the Material Theme</a></li>
   <li><a href="#layouts">Design Your Layouts</a></li>
-  <li><a href="#depth">Specify Depth in Your Views</a></li>
+  <li><a href="#depth">Specify Elevation in Your Views</a></li>
   <li><a href="#widgets">Use the New UI Widgets</a></li>
-  <li><a href="#apis">Use the New APIs</a></li>
+  <li><a href="#animations">Customize Your Animations</a></li>
 </ol>
 </div>
 </div>
@@ -19,7 +19,8 @@ page.title=Get Started
 
 <ol>
   <li style="margin-bottom:10px">
-    Take a look at the <a href="">material design specification</a>.</li>
+    Take a look at the <a href="http://www.google.com/design/spec">material design
+    specification</a>.</li>
   <li style="margin-bottom:10px">
     Apply the material <strong>theme</strong> to your app.</li>
   <li style="margin-bottom:10px">
@@ -27,11 +28,11 @@ page.title=Get Started
   <li style="margin-bottom:10px">
     Create your <strong>layouts</strong> following material design guidelines.</li>
   <li style="margin-bottom:10px">
-    Specify the <strong>depth</strong> for views to cast appropriate shadows.</li>
+    Specify the <strong>elevation</strong> of your views to cast appropriate shadows.</li>
   <li style="margin-bottom:10px">
     Use the new <strong>widgets</strong> for complex views, such as lists and cards.</li>
   <li style="margin-bottom:10px">
-    Use the new <strong>APIs</strong> to customize the animations in your app.</li>
+    Use the new APIs to customize the <strong>animations</strong> in your app.</li>
 </ol>
 
 <h3>Update Your App for the Android L Developer Preview</h3>
@@ -42,15 +43,16 @@ incorporating depth, touch feedback and animations in your UI.</p>
 
 <h3>Create New Apps for the Android L Developer Preview</h3>
 
-<p>If you are creating a new app for the Android L Developer Preview, the material design
-guidelines provide you with a solid design framework for your app. Follow these guidelines and
+<p>If you are creating a new app for the Android L Developer Preview, the <a
+href="http://www.google.com/design/spec">material design guidelines</a> provide you with a
+cohesive design framework for your app. Follow these guidelines and
 use the new functionality in the Android framework to design and develop your app.</p>
 
 
 <h2 id="applytheme">Apply the Material Theme</h2>
 
 <p>To apply the material theme in your app, specify a style that inherits from
-<code>android:theme.Material</code>:</p>
+<code>android:Theme.Material</code>:</p>
 
 <pre>
 &lt;!-- res/values/styles.xml -->
@@ -70,8 +72,8 @@ animations for touch feedback and activity transitions. For more details, see
 <h2 id="layouts">Design Your Layouts</h2>
 
 <p>In addition to applying and customizing the material theme, your layouts should conform to
-the material design guidelines. When you design your layouts, pay special attention to the
-following:</p>
+the <a href="http://www.google.com/design/spec">material design guidelines</a>. When you design
+your layouts, pay special attention to the following:</p>
 
 <ul>
 <li>Baseline grids</li>
@@ -81,37 +83,36 @@ following:</p>
 <li>Layout structure</li>
 </ul>
 
-<p>You still define layouts inside XML files using the standard tools from the Android framework.
-For details on the material design guidelines, see the <a href="">material design
-specification</a>.</p>
 
+<h2 id="depth">Specify Elevation in Your Views</h2>
 
-<h2 id="depth">Specify Depth in Your Views</h2>
-
-<p>In the Android L Developer Preview, views can cast shadows. The elevation value of a view
-determines the size of its shadow. To set the elevation of a view, use the
+<p>Views can cast shadows, and the elevation value of a view
+determines the size of its shadow and its drawing order. To set the elevation of a view, use the
 <code>android:elevation</code> attribute in your layouts:</p>
 
 <pre>
-&lt;Button
-    android:id="@+id/my_button"
+&lt;TextView
+    android:id="@+id/my_textview"
     android:layout_width="wrap_content"
     android:layout_height="wrap_content"
     android:text="@string/next"
-    <strong>android:elevation</strong>="10dp" />
+    android:background="@color/white"
+    <strong>android:elevation</strong>="5dp" />
 </pre>
 
+<p>The new <code>translationZ</code> property lets you create animations that reflect temporary
+changes in the elevation of a view. For example, this is useful to respond to touch gestures.</p>
+
 <p>For more details, see <a href="{@docRoot}preview/material/views-shadows.html">Views and
 Shadows</a>.</p>
 
 
 <h2 id="widgets">Use the New UI Widgets</h2>
 
-<p>The Android L Developer Preview includes two new UI widgets for complex views,
-<code>RecyclerView</code> and <code>CardView</code>. <code>RecyclerView</code> is a more advanced
-version of <code>ListView</code> that provides performance improvements and is easier to use.
-<code>CardView</code> lets you show pieces of information inside cards with a consistent look
-across apps. To include a <code>CardView</code> in your layout:</p>
+<p><code>RecyclerView</code> is a more advanced version of <code>ListView</code> that provides
+performance improvements and is easier to use. <code>CardView</code> lets you show pieces of
+information inside cards with a consistent look across apps. To include a <code>CardView</code>
+in your layout:</p>
 
 <pre>
 &lt;android.support.v7.widget.CardView
@@ -126,7 +127,7 @@ across apps. To include a <code>CardView</code> in your layout:</p>
 <p>For more information, see <a href="{@docRoot}preview/material/ui-widgets.html">UI Widgets</a>.</p>
 
 
-<h2 id="apis">Use the APIs to Customize Your Animations</h2>
+<h2 id="animations">Customize Your Animations</h2>
 
 <p>The Android L Developer Preview includes new APIs to create custom animations in your app.
 For example, you can enable activity transitions and define an exit transition inside an
diff --git a/docs/html/preview/material/images/MaterialDark.png b/docs/html/preview/material/images/MaterialDark.png
index 6a72280..f1018af 100644
--- a/docs/html/preview/material/images/MaterialDark.png
+++ b/docs/html/preview/material/images/MaterialDark.png
diff --git a/docs/html/preview/material/images/MaterialLight.png b/docs/html/preview/material/images/MaterialLight.png
index 0e85528..4ed7d5c 100644
--- a/docs/html/preview/material/images/MaterialLight.png
+++ b/docs/html/preview/material/images/MaterialLight.png
diff --git a/docs/html/preview/material/images/card_travel.png b/docs/html/preview/material/images/card_travel.png
index a804ca0..19752a8 100644
--- a/docs/html/preview/material/images/card_travel.png
+++ b/docs/html/preview/material/images/card_travel.png
diff --git a/docs/html/preview/material/images/list_mail.png b/docs/html/preview/material/images/list_mail.png
index ca53ee1..bd107ff 100644
--- a/docs/html/preview/material/images/list_mail.png
+++ b/docs/html/preview/material/images/list_mail.png
diff --git a/docs/html/preview/material/index.jd b/docs/html/preview/material/index.jd
index b7abcb4..d9a276f 100644
--- a/docs/html/preview/material/index.jd
+++ b/docs/html/preview/material/index.jd
@@ -3,11 +3,11 @@ page.type=design
 
 @jd:body
 
-<p itemprop="description">The Android L Developer Preview includes support for material design apps. Material design
-is a comprehensive guide for visual, motion, and interaction design across platforms and devices.
-To use material design in your Android apps, follow the guidelines defined in the
-<a href="">material design specification</a> and use the new components and functionality
-available in the Android L Developer Preview.</p>
+<p itemprop="description">The Android L Developer Preview includes support for material design
+apps. Material design is a comprehensive guide for visual, motion, and interaction design across
+platforms and devices. To use material design in your Android apps, follow the guidelines defined
+in the <a href="http://www.google.com/design/spec">material design specification</a> and use the
+new components and functionality available in the Android L Developer Preview.</p>
 
 <p>The Android L Developer Preview provides the following elements for you to build material
 design apps:</p>
@@ -27,13 +27,13 @@ their color palette, and default animations for touch feedback and activity tran
 <!-- two columns -->
 <div style="width:700px;margin-top:25px;margin-bottom:20px">
 <div style="float:left;width:250px;margin-left:40px;margin-right:60px;">
-  <img src="{@docRoot}preview/material/images/MaterialDark.png" style="width:250px;"/>
+  <img src="{@docRoot}preview/material/images/MaterialDark.png" width="500" height="238"/>
   <div style="width:140px;margin:0 auto">
   <p style="margin-top:8px">Dark Material theme</p>
   </div>
 </div>
 <div style="float:left;width:250px;margin-right:0px;">
-  <img src="{@docRoot}preview/material/images/MaterialLight.png" style="width:250px;"/>
+  <img src="{@docRoot}preview/material/images/MaterialLight.png" width="500" height="238"/>
   <div style="width:140px;margin:0 auto">
   <p style="margin-top:8px">Light Material theme</p>
   </div>
@@ -49,12 +49,12 @@ their color palette, and default animations for touch feedback and activity tran
 <!-- two columns -->
 <div style="width:700px;margin-top:25px;margin-bottom:20px">
 <div style="float:left;width:250px;margin-left:40px;margin-right:60px;">
-  <img src="{@docRoot}preview/material/images/list_mail.png" style="width:250px;"/>
+  <img src="{@docRoot}preview/material/images/list_mail.png" width="500" height="426"/>
   <p>The new <code>RecyclerView</code> widget is a more advanced version of <code>ListView</code>
-  provides performance improvements for dynamic views and is easier to use.</p>
+  that provides performance improvements for dynamic views and is easier to use.</p>
 </div>
 <div style="float:left;width:250px;margin-right:0px;">
-  <img src="{@docRoot}preview/material/images/card_travel.png" style="width:250px;"/>
+  <img src="{@docRoot}preview/material/images/card_travel.png" width="500" height="426"/>
   <p>The new <code>CardView</code> widget lets you display important pieces of information inside
   cards that have a consistent look and feel.</p>
 </div>
@@ -64,9 +64,13 @@ their color palette, and default animations for touch feedback and activity tran
 
 <h3>View Shadows</h3>
 
-<p>In addition to the X and Y components, views in the Android L Developer Preview have a Z
-component. This new component represents the elevation of a view, which determines the size of
-its shadow: views with higher Z values cast bigger shadows.</p>
+<p>In addition to the X and Y properties, views in the Android L Developer Preview have a Z
+property. This new property represents the elevation of a view, which determines:</p>
+
+<ul>
+<li>The size of the shadow - Views with higher Z values cast bigger shadows.</li>
+<li>The drawing order - Views with higher Z values appear on top of other views.</li>
+</ul>
 
 <div style="width:290px;margin-left:35px;float:right">
   <div class="framed-nexus5-port-span-5">
@@ -86,7 +90,7 @@ its shadow: views with higher Z values cast bigger shadows.</p>
 <p>The Android L Developer Preview provides new APIs that let you create custom animations for
 touch feedback in UI controls, view state changes, and activity transitions.</p>
 
-<p>The new animation APIs in the Android L Developer Preview let you:</p>
+<p>The new animation APIs let you:</p>
 
 <ul>
 <li style="margin-bottom:15px">
@@ -99,7 +103,7 @@ Hide and show views with <strong>reveal effect</strong> animations.
 Switch between activities with custom <strong>activity transition</strong> animations.
 </li>
 <li style="margin-bottom:15px">
-Create custom animation patterns with <strong>curved motion</strong>.
+Create more natural animations with <strong>curved motion</strong>.
 </li>
 <li style="margin-bottom:15px">
 Animate changes in one or more view properties with <strong>view state change</strong> animations.
@@ -109,9 +113,16 @@ Show animations in <strong>state list drawables</strong> between view state chan
 </li>
 </ul>
 
+<p>Touch feedback animations are built into several standard views, such as buttons. The new APIs
+let you customize these animations and add animations to your custom views.</p>
+
 
 <h3>New Capabilities for Drawables</h3>
 
 <p>The Android L Developer Preview supports <strong>drawable tinting</strong>: you can define
-bitmaps as an alpha mask and tint them using a color resource. You can create these assets only
-once and color each instance to match your theme.</p>
+bitmaps as an alpha mask and tint them using a color resource. You create these assets only
+once and color each instance to match your theme. Drawables also now support specifying most XML
+properties as <strong>theme attributes</strong>.</p>
+
+<p>The Android L Developer Preview Support Library includes a <strong>color extraction</strong>
+library that lets you automatically extract prominent colors from a bitmap image.</p>
\ No newline at end of file
diff --git a/docs/html/preview/material/theme.jd b/docs/html/preview/material/theme.jd
index b954960..5e4bcdf 100644
--- a/docs/html/preview/material/theme.jd
+++ b/docs/html/preview/material/theme.jd
@@ -8,7 +8,7 @@ page.title=Material Theme
 <ol>
   <li><a href="#colorpalette">Customize the Colot Palette</a></li>
   <li><a href="#statusbar">Customize the Status Bar</a></li>
-  <li><a href="#inheritance">Theme Inheritance</a></li>
+  <li><a href="#inheritance">Theme Individual Views</a></li>
 </ol>
 </div>
 </div>
@@ -21,18 +21,18 @@ page.title=Material Theme
   <li>Activity transition animations</li>
 </ul>
 
-<p>The Android L Developer Preview lets you easily customize the look of the material theme
-according to your brand identity with a color palette you control. You can tint the app bar and
+<p>You can customize the look of the material theme
+according to your brand identity with a color palette you control. You can tint the action bar and
 the status bar using theme attributes, as shown in Figure 1.</p>
 
-<div style="float:right;margin-left:25px;margin-top:-25px">
+<div style="float:right;margin-left:25px;margin-top:-50px">
 <img src="{@docRoot}preview/material/images/ThemeColors.png" style="width:250px"/>
-<p class="img-caption"><strong>Figure 1.</strong> Customizing the material theme.</p>
+<p class="img-caption" style="margin-bottom:0px">
+<strong>Figure 1.</strong> Customizing the material theme.</p>
 </div>
 
-<p>The system widgets have a new design and touch feedback animations. Activity transitions help
-users navigate your app by providing visual continuity. You can customize the color palette,
-the touch feedback animations, and the activity transitions for your app.</p>
+<p>The system widgets have a new design and touch feedback animations. You can customize the
+color palette, the touch feedback animations, and the activity transitions for your app.</p>
 
 <p>The material theme is defined as:</p>
 
@@ -43,7 +43,7 @@ the touch feedback animations, and the activity transitions for your app.</p>
 </ul>
 
 <p>For a list of material styles that you can use, see the API reference for
-<code>android.R.styles</code>.</p>
+<code>android.R.style</code>.</p>
 
 <p class="note">
 <strong>Note:</strong> The material theme is only available in the Android L Developer Preview.
@@ -53,8 +53,8 @@ For more information, see <a href="{@docRoot}preview/material/compatibility.html
 
 <h2 id="colorpalette">Customize the Color Palette</h2>
 
-<p>To customize the theme's base colors to fit your brand, define your custom colors using
-theme attributes when you inherit from the material theme:</p>
+<p style="margin-bottom:30px">To customize the theme's base colors to fit your brand, define
+your custom colors using theme attributes when you inherit from the material theme:</p>
 
 <pre>
 &lt;resources>
@@ -63,28 +63,27 @@ theme attributes when you inherit from the material theme:</p>
     &lt;!-- Main theme colors -->
     &lt;!--   your app's branding color (for the app bar) -->
     &lt;item name="android:colorPrimary">@color/primary&lt;/item>
-    &lt;!--   darker variant of colorPrimary (for contextual app bars) -->
+    &lt;!--   darker variant of colorPrimary (for status bar, contextual app bars) -->
     &lt;item name="android:colorPrimaryDark">@color/primary_dark&lt;/item>
-
-    &lt;!-- other theme colors -->
-    &lt;item name="android:colorButtonNormal">@color/button_normal&lt;/item>
-    &lt;item name="android:windowBackground">@color/wbackground&lt;/item>
+    &lt;!--   theme UI controls like checkboxes and text fields -->
+    &lt;item name="android:colorAccent">@color/accent&lt;/item>
   &lt;/style>
 &lt;/resources>
 </pre>
 
 
-<h2 id="statusbar">Customize the Status Bar</h2>
+<h2 id="statusbar">Customize the Status and Navigation Bar</h2>
 
 <p>The material theme lets you easily customize the status bar, so you can specify a
-color which fits your brand and provides enough contrast to show the white status icons. To
+color that fits your brand and provides enough contrast to show the white status icons. To
 set a custom color for the status bar, use the <code>android:statusBarColor</code> attribute when
-you extend the material theme.</p>
+you extend the material theme. By default, <code>android:statusBarColor</code> inherits the
+value of <code>android:colorPrimaryDark</code>.</p>
 
 <p>To handle the color of the status bar yourself (for example, by adding a gradient in the
 background), set the <code>android:statusBarColor</code> attribute to
-<code>&#64;android:color/transparent</code>. You can also use the
-<code>Window.setStatusBarColor</code> method for animations or fading.</p>
+<code>&#64;android:color/transparent</code> and adjust the window flags as required. You can
+also use the <code>Window.setStatusBarColor</code> method for animations or fading.</p>
 
 <p class="note"><strong>Note:</strong>
 The status bar should almost always have a clear delineation from the primary toolbar, except for
@@ -92,9 +91,9 @@ full-bleed imagery cases and when you use a gradient as a protection.
 </p>
 
 
-<h2 id="inheritance">Theme Inheritance</h3>
+<h2 id="inheritance">Theme Individual Views</h3>
 
-<p>In the Android L Developer Preview, elements in XML layout definitions can specify the
-<code>android:theme</code> attribute, which references a theme resource. This attribute modifies
-the theme for the element and any elements inflated below it, which is useful to alter theme
-color palettes in a specific portion of an interface.</p>
\ No newline at end of file
+<p>Elements in XML layout definitions can specify the <code>android:theme</code> attribute,
+which references a theme resource. This attribute modifies the theme for the element and any
+elements inflated below it, which is useful to alter theme color palettes in a specific portion
+of an interface.</p>
\ No newline at end of file
diff --git a/docs/html/preview/material/ui-widgets.jd b/docs/html/preview/material/ui-widgets.jd
index f18bff9..31604d6 100644
--- a/docs/html/preview/material/ui-widgets.jd
+++ b/docs/html/preview/material/ui-widgets.jd
@@ -14,19 +14,20 @@ page.title=UI Widgets
 
 <p>The support library in the Android L Developer Preview contains two new widgets,
 <code>RecyclerView</code> and <code>CardView</code>. Use these widgets to show complex lists
-and cards in your app. These widgets have material design styles and animations by default.</p>
+and cards in your app. These widgets have material design style by default.</p>
 
 
 <h2 id="recyclerview">RecyclerView</h2>
 
-<p><code>RecyclerView</code> is a more advanced version of <code>ListView</code>. This widget is
-a container for large sets of views that can be recycled and scrolled very efficiently. Use the
-<code>RecyclerView</code> widget when you have lists with elements that change dynamically.</p>
+<p><code>RecyclerView</code> is a more advanced and flexible version of <code>ListView</code>.
+This widget is a container for large sets of views that can be recycled and scrolled very
+efficiently. Use the <code>RecyclerView</code> widget when you have lists with elements that
+change dynamically.</p>
 
 <p><code>RecyclerView</code> is easy to use, because it provides:</p>
 
 <ul>
-  <li>A set of layout managers for positioning items</li>
+  <li>A layout manager for positioning items</li>
   <li>Default animations for common item operations</li>
 </ul>
 
@@ -34,20 +35,9 @@ a container for large sets of views that can be recycled and scrolled very effic
 widget.</p>
 
 <p>To use the <code>RecyclerView</code> widget, you have to specify an adapter and a layout
-manager. An <strong>adapter</strong> provides a binding from a dataset to views that are displayed
-within a <code>RecyclerView</code>. For example, if your dataset is an array of strings displayed
-as <code>TextView</code> items, the layout manager asks the adapter to:
-</p>
-
-<ul>
-  <li>Set the text of an existing <code>TextView</code> to one of the strings in the dataset</li>
-  <li>Create new <code>TextView</code> objects</li>
-  <li>Determine the size of the dataset</li>
-</ul>
-
-<p>To create an adapter, you extend the <code>RecyclerView.Adapter</code> class. The details of
-the implementation depend on the specifics of your dataset and the type of views. Fore more
-information, see the examples below.</p>
+manager. To create an adapter, you extend the <code>RecyclerView.Adapter</code> class. The details
+of the implementation depend on the specifics of your dataset and the type of views. For more
+information, see the <a href="#rvexamples">examples</a> below.</p>
 
 <img src="/preview/material/images/RecyclerView.png" alt="" id="figure1" style="width:550px"/>
 <p class="img-caption">
@@ -62,16 +52,17 @@ performance by avoiding the creation of unnecessary views or performing expensiv
 <code>findViewById</code> lookups.
 </p>
 
-<p><code>RecyclerView</code> provides two layout managers you can use:</p>
+<p><code>RecyclerView</code> provides <code>LinearLayoutManager</code>, which shows the items in a
+vertical or horizontal scrolling list. To create a custom layout, you extend the
+<code>RecyclerView.LayoutManager</code> class.</p>
 
-<ul>
-  <li><code>LinearLayoutManager</code> shows the items in a vertically scrolling list.</li>
-  <li><code>GridLayoutManager</code> shows the items in a rectangular grid.</li>
-</ul>
+<h3>Animations</h3>
 
-<p>To create a custom layout, you extend the <code>RecyclerView.LayoutManager</code> class.</p>
+<p>Animations for adding and removing items are enabled by default in <code>RecyclerView</code>.
+To customize these animations, extend the <code>RecyclerView.ItemAnimator</code> class and use
+the <code>RecyclerView.setItemAnimator</code> method.</p>
 
-<h3>Examples</h3>
+<h3 id="rvexamples">Examples</h3>
 
 <p>To include a <code>RecyclerView</code> in your layout:</p>
 
@@ -87,7 +78,7 @@ performance by avoiding the creation of unnecessary views or performing expensiv
 <p>To get the <code>RecyclerView</code> object in your activity:</p>
 
 <pre>
-public class MyActivity extends ActionBarActivity {
+public class MyActivity extends Activity {
     private RecyclerView mRecyclerView;
     private RecyclerView.Adapter mAdapter;
     private RecyclerView.LayoutManager mLayoutManager;
@@ -98,7 +89,8 @@ public class MyActivity extends ActionBarActivity {
         setContentView(R.layout.my_activity);
         mRecyclerView = (RecyclerView) findViewById(R.id.my_recycler_view);
 
-        // improve performance if the size is fixed
+        // improve performance if you know that changes in content
+        // do not change the size of the RecyclerView
         mRecyclerView.setHasFixedSize(true);
 
         // use a linear layout manager
@@ -139,7 +131,8 @@ public class MyAdapter extends RecyclerView.Adapter&lt;MyAdapter.ViewHolder> {
     public MyAdapter.ViewHolder onCreateViewHolder(ViewGroup parent,
                                                    int viewType) {
         // create a new view
-        View v = new TextView(parent.getContext());
+        View v = LayoutInflater.from(parent.getContext())
+                               .inflate(R.layout.my_text_view, null);
         // set the view's size, margins, paddings and layout parameters
         ...
         ViewHolder vh = new ViewHolder(v);
@@ -167,22 +160,30 @@ public class MyAdapter extends RecyclerView.Adapter&lt;MyAdapter.ViewHolder> {
 <h2 id="cardview">CardView</h2>
 
 <p><code>CardView</code> extends the <code>FrameLayout</code> class and lets you show information
-inside a card with optional rounded corners:</p>
+inside cards that have a consistent look on any app. <code>CardView</code> widgets can have
+shadows and rounded corners.</p>
+
+<p>To create a card with a shadow, use the <code>android:elevation</code> attribute.
+<code>CardView</code> uses real elevation and dynamic shadows
+and falls back to a programmatic shadow implementation on earlier versions. For more information,
+see <a href="{@docRoot}preview/material/compatibility.html">Compatibility</a>.</p>
+
+<p>Here's how to specify properties of <code>CardView</code>:</p>
 
 <ul>
   <li>To set the corner radius in your layouts, use the <code>android:cardCornerRadius</code>
   attribute.</li>
   <li>To set the corner radius in your code, use the <code>CardView.setRadius</code> method.</li>
+  <li>To set the background color of a card, use the <code>android:cardBackgroundColor</code>
+attribute.</li>
 </ul>
 
-<p>To set the background color of a card, use the <code>android:cardBackgroundColor</code>
-attribute.</p>
-
 <p>To include a <code>CardView</code> in your layout:</p>
 
 <pre>
 &lt;!-- A CardView that contains a TextView -->
 &lt;android.support.v7.widget.CardView
+    xmlns:card_view="http://schemas.android.com/apk/res-auto"
     android:id="@+id/card_view"
     android:layout_gravity="center"
     android:layout_width="200dp"
diff --git a/docs/html/preview/material/views-shadows.jd b/docs/html/preview/material/views-shadows.jd
index c5884d6..f7682f5 100644
--- a/docs/html/preview/material/views-shadows.jd
+++ b/docs/html/preview/material/views-shadows.jd
@@ -13,10 +13,12 @@ page.title=Views and Shadows
 </div>
 </div>
 
-<p>In apps with material design, depth has meaning. You should assign higher elevation values to more
-important UI elements in your app. The elevation value of a view determines the size of its
-shadow: views with higher Z values cast bigger shadows. Views only cast shadows on the Z=0 plane
-under an orthographic projection (the views do not scale for different values of Z).</p>
+<p>The elevation of a view determines the size of its shadow:
+views with higher Z values cast bigger shadows. Views only cast shadows on the Z=0 plane under an
+orthographic projection (the views do not scale for different values of Z).</p>
+
+<p>Elevation is also useful to create animations where widgets temporarily rise above the
+view plane when performing some action.</p>
 
 
 <h2 id="elevation">View Elevation</h2>
@@ -35,52 +37,59 @@ static component, and the translation is used for animations:</p>
 
 <p>To set the translation of a view, use the <code>View.setTranslationZ</code> method.</p>
 
-<p>The Z values are measured in the same units as the X and Y values (like <code>dp</code> or
-<code>px</code>).</p>
+<p>The new <code>ViewPropertyAnimator.z</code> and <code>ViewPropertyAnimator.translationZ</code>
+methods enable you to easily animate the elevation of views. For more information, see
+the API reference for <code>ViewPropertyAnimator</code> and the <a
+href="{@docRoot}guide/topics/graphics/prop-animation.html#object-animator">Property Animation</a>
+developer guide.</p>
+
+<p>The Z values are measured in the same units as the X and Y values.</p>
 
 
 <h2 id="shadows">Shadows and Outlines</h2>
 
-<p>The bounds of a view's background drawable determine the default shape of its shadow. To define
-a custom shape for a shadow, such as an oval, use the <code>View.setOutline</code> method:</p>
+<p>The bounds of a view's background drawable determine the default shape of its shadow.
+<strong>Outlines</strong> represent the outer shape of a graphics object and define the ripple
+area for touch feedback.</p>
+
+<p>For example, if you define a view with a background drawable:</p>
 
 <pre>
-View v = findViewById(R.id.my_view);
+&lt;TextView
+    android:id="@+id/myview"
+    ...
+    android:elevation="2dp"
+    android:background="@drawable/myrect" />
+</pre>
 
-// add 10px to the static elevation
-v.setTranslationZ(10);
+<p>where the background drawable is defined as a rectangle with rounded corners:</p>
 
-// set an oval shadow
-Outline outline = new Outline();
-outline.setOval(v.getLeft(), v.getTop(), v.getRight(), v.getBottom());
-myView.setOutline(outline);
+<pre>
+&lt;!-- res/drawable/myrect.xml -->
+&lt;shape xmlns:android="http://schemas.android.com/apk/res/android"
+       android:shape="rectangle">
+    &lt;solid android:color="#42000000" />
+    &lt;corners android:radius="5dp" />
+&lt;/shape>
 </pre>
 
-<p>An <code>Outline</code> represents the outer shape of a graphics object. You can create
-<code>Outline</code> objects as in this example, or you can obtain the outline from a
-<code>Drawable</code> object with the <code>getOutline</code> method.</p>
+<p>Then this view and drawable cast the appropiate shadow.</p>
 
-<p>The outline of a view also defines the ripple area for touch feedback.</p>
+<p>You can also create outlines in your code using the methods in the <code>Outline</code> class,
+and you can assign them to views with the <code>View.setOutline</code> method.</p>
 
 <p>To prevent a view from casting a shadow, set its outline to <code>null</code>.</p>
 
 
 <h2 id="clip">Clipping Views</h2>
 
-<p>The Android L Developer Preview lets you clip a view to its outline area using the
+<p>Clip a view to its outline area using the
 <code>View.setClipToOutline</code> method. Only rectangle, circle, and round rectangle outlines
 support clipping, as determined by the <code>Outline.canClip</code> method.</p>
 
-<p>To determine if a view has been clipped, use the <code>View.getClipToOutline</code> method.</p>
+<p>To clip a view to the shape of a drawable, set the drawable as the background of the view
+(as shown above) and call the <code>View.setClipToOutline</code> method.</p>
 
-<pre>
-// clip a view to an oval
-View v = findViewById(R.id.my_view);
-outline.setOval(v.getLeft(), v.getTop(), v.getRight(), v.getBottom());
-myView.setOutline(outline);
-
-// if the view is not already clipped
-if (v.getClipToOutline() == false) {
-    v.setClipToOutline(true);
-}
-</pre>
\ No newline at end of file
+<p>Because clipping views is an expensive operation, don't animate the shape you use to
+clip a view. To achieve this effect, use a <a
+href="{@docRoot}preview/material/animations.html#reveal">Reveal Effect</a> animation.</p>
\ No newline at end of file