📖 Document media query attributes (#32789)

* Create document for responsive attributes

* Link to responsive attribute documentation

* Fix links

* Add example

* Use Crystal's suggested copy

* Add note

extensions/amp-base-carousel/0.1/amp-base-carousel.md

@@ -44,20 +44,7 @@ arrow buttons.
 ### Media Queries
 
 The attributes for `<amp-base-carousel>` can be configured to use different
-options based on a media query. You can also use a value without any media
-queries. The format looks like:
-
-```html
-<amp-base-carousel
-  attr-name="(min-width: 1000px) valueOne, (min-width: 600px) valueTwo, defaultValue"
-></amp-base-carousel>
-```
-
-The media queries are evaluated from left to right, with the first matching
-media query being used. A default value (without a media query) is required. In
-this case, if the page has a screen width of 1000px or more, `valueOne` is used.
-If the width is between 999px and 600px, `valueTwo` is used. When it is 599px or
-smaller, `defaultValue` is used.
+options based on a [media query](./../../../spec/amp-html-responsive-attributes.md).
 
 ### Configuration Options
 

extensions/amp-base-carousel/amp-base-carousel.md

@@ -247,20 +247,7 @@ addition, when changing `visible-slides`, you likely want to change
 ### Media Queries
 
 The attributes for `<amp-base-carousel>` can be configured to use different
-options based on a media query. You can also use a value without any media
-queries. The format looks like:
-
-```html
-<amp-base-carousel
-  attr-name="(min-width: 1000px) valueOne, (min-width: 600px) valueTwo, defaultValue"
-></amp-base-carousel>
-```
-
-The media queries are evaluated from left to right, with the first matching
-media query being used. A default value (without a media query) is required. In
-this case, if the page has a screen width of 1000px or more, `valueOne` is used.
-If the width is between 999px and 600px, `valueTwo` is used. When it is 599px or
-smaller, `defaultValue` is used.
+options based on a [media query](./../../spec/amp-html-responsive-attributes.md).
 
 ### Configuration Options
 

extensions/amp-inline-gallery/0.1/amp-inline-gallery.md

@@ -76,7 +76,7 @@ The `<amp-inline-gallery-pagination>` component determines how a pagination idic
 
 The pagination indicator renders as dots when there are eight or fewer slides in the `amp-base-carousel`. For nine or more slides, the pagination indicator renders the current slide number and total number of slides, aligned to the right.
 
-The pagination indicator location defaults to underneath the carousel. Adding the inset attribute to the `<amp-inline-gallery-pagination>` tag will overlay the pagination indicator on the carousel. To use different styles for different screen sizes, use the media attribute:
+The pagination indicator location defaults to underneath the carousel. Adding the inset attribute to the `<amp-inline-gallery-pagination>` tag will overlay the pagination indicator on the carousel. To use different styles for different screen sizes, use the [media attribute](./../../../spec/amp-html-responsive-attributes.md):
 
 ```html
 <amp-inline-gallery layout="container">
@@ -237,6 +237,11 @@ The example below demonstrates a gallery with thumbnails visible at larger resol
 
 #### `amp-inline-gallery-thumbnails` attributes
 
+##### Media Queries
+
+The attributes for `<amp-inline-gallery-thumbnails>` can be configured to use different
+options based on a [media query](./../../../spec/amp-html-responsive-attributes.md).
+
 ##### `aspect-ratio-height` (optional)
 
 Specifies the aspect ratio when used with `aspect-ratio-width`. The aspect radio defaults to match the slides in `<amp-base-carousel>`.

extensions/amp-inline-gallery/amp-inline-gallery.md

@@ -212,7 +212,7 @@ The `<amp-inline-gallery-pagination>` component determines how a pagination idic
 
 The pagination indicator renders as dots when there are eight or fewer slides in the `amp-base-carousel`. For nine or more slides, the pagination indicator renders the current slide number and total number of slides, aligned to the right.
 
-The pagination indicator location defaults to underneath the carousel. Adding the inset attribute to the `<amp-inline-gallery-pagination>` tag will overlay the pagination indicator on the carousel. To use different styles for different screen sizes, use the media attribute:
+The pagination indicator location defaults to underneath the carousel. Adding the inset attribute to the `<amp-inline-gallery-pagination>` tag will overlay the pagination indicator on the carousel. To use different styles for different screen sizes, use the [media attribute](./../../spec/amp-html-responsive-attributes.md):
 
 ```html
 <amp-inline-gallery layout="container">
@@ -384,6 +384,11 @@ The example below demonstrates a gallery with thumbnails visible at larger resol
 
 #### `amp-inline-gallery-thumbnails` attributes
 
+##### Media Queries
+
+The attributes for `<amp-inline-gallery-thumbnails>` can be configured to use different
+options based on a [media query](./../../spec/amp-html-responsive-attributes.md).
+
 ##### `aspect-ratio` (optional)
 
 Specifies the aspect ratio expressed as `width / height`. The aspect radio defaults to match the slides in `<amp-base-carousel>`.

extensions/amp-stream-gallery/amp-stream-gallery.md

@@ -254,20 +254,7 @@ wrapping element, and use that to center the content.
 ### Media Queries
 
 The attributes for `<amp-stream-gallery>` can be configured to use different
-options based on a media query. You can also use a value without any media
-queries. The format looks like:
-
-```html
-<amp-stream-gallery
-  attr-name="(min-width: 1000px) valueOne, (min-width: 600px) valueTwo, defaultValue"
-></amp-stream-gallery>
-```
-
-The media queries are evaluated from left to right, with the first matching
-media query being used. A default value (without a media query) is required. In
-this case, if the page has a screen width of 1000px or more, `valueOne` is used.
-If the width is between 999px and 600px, `valueTwo` is used. When it is 599px or
-smaller, `defaultValue` is used.
+options based on a [media query](./../../spec/amp-html-responsive-attributes.md).
 
 ### Behavior
 

spec/amp-html-responsive-attributes.md

@@ -0,0 +1,65 @@
+<!---
+Copyright 2021 The AMP HTML Authors. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS-IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# AMP HTML Responsive Attributes
+
+You can apply or remove certain attributes based on screen size. These are responsive attributes, or media attributes. On eligible components, these attributes are applied or removed based on media queries. You can also use a value without any media queries. Media queries evaluate from from left to right, applying the first matching media query. You must include a default value with no media query.
+
+[tip type="note"]
+
+Responsive attributes do not require media queries. You may apply media query eligible attributes the same as regular attributes: `attr-name="attr-value"`.
+
+[/tip]
+
+To apply this behavior to an attribute, use the following format:
+
+```html
+<amp-component
+  attr-name="(min-width: 1000px) valueOne, (min-width: 600px) valueTwo, defaultValue"
+></amp-component>
+```
+
+In the example above, if the page has a screen of `1000px` or more, it applies `valueOne`. If the width is between `999px` and `600px`, it applies `valueTwo`. When the screen is `599px` or smaller, it applies the `defaultValue`.
+
+The following `amp-base-carousel` will show `3` slides at a time when width is greater than or equal to `800px`, and `2` otherwise.
+
+[example preview="top-frame" playground="true" imports="amp-base-carousel:1.0"]
+
+```html
+<amp-base-carousel
+    width="900" height="200"
+    layout="responsive"
+    visible-count="(min-width: 800px) 3, 2">
+  <amp-img src="./img/redgradient.png" layout="flex-item"></amp-img>
+  <amp-img src="./img/greengradient.png" layout="flex-item"></amp-img>
+  <amp-img src="./img/bluegradient.png" layout="flex-item"></amp-img>
+  <amp-img src="./img/orangegradient.png" layout="flex-item"></amp-img>
+  <amp-img src="./img/tealgradient.png" layout="flex-item"></amp-img>
+  <amp-img src="./img/lemonyellowgradient.png" layout="flex-item"></amp-img>
+  <amp-img src="./img/lilacgradient.png" layout="flex-item"></amp-img>
+</amp-base-carousel>
+```
+
+[/example]
+
+## Eligible components
+
+You may apply responsive attribute values to the following components:
+
+-   [amp-base-carousel](./../extensions/amp-base-carousel/amp-base-carousel.md)
+-   [amp-inline-gallery-pagination](./../extensions/amp-inline-gallery/amp-inline-gallery.md#include-pagination-indicators)
+-   [amp-inline-gallery-thumbnails](./../extensions/amp-inline-gallery/amp-inline-gallery.md#include-pagination-thumbnails)
+-   [amp-stream-gallery](./../extensions/amp-stream-gallery/amp-stream-gallery.md)