diff --git a/_layouts/default.html b/_layouts/default.html
index ae864b2c78..716e478fce 100644
--- a/_layouts/default.html
+++ b/_layouts/default.html
@@ -22,7 +22,7 @@
-
+
{% include top-nav.html %}
{{page.title}}
diff --git a/articles/accessible-web-components.md b/articles/accessible-web-components.md
index e9a877798e..1c99a5a646 100644
--- a/articles/accessible-web-components.md
+++ b/articles/accessible-web-components.md
@@ -1,7 +1,6 @@
---
layout: default
-type: core
-navgroup: docs
+type: guide
shortname: Articles
title: "Accessible Web Components - Part 1"
subtitle: Improving the accessibility of Web Components
@@ -39,21 +38,21 @@ When designing for accessibility, there are four key areas of disability to cons
* Ensure all user interface elements can be used with assistive technologies such as screen readers, magnifiers and braille displays. This entails ensuring that elements are marked up such that accessibility APIs can programmatically determine the *role*, *state*, *value* and *title* of any element.
-**Hearing** issues mean a user may have issues hearing sound emitted from a page.
+**Hearing** issues mean a user may have issues hearing sound emitted from a page.
-* Make the content understandable using [text alternatives](http://www.w3.org/TR/WCAG20/#media-equiv-av-only-alt) for all content that is not strictly text.
+* Make the content understandable using [text alternatives](http://www.w3.org/TR/WCAG20/#media-equiv-av-only-alt) for all content that is not strictly text.
* Ensure you test that your elements are still functional [without sound](http://www.w3.org/TR/2008/REC-WCAG20-20081211/#content-structure-separation-understanding).
-**Mobility** issues can include the inability to operate a mouse, a keyboard or touch-screen.
+**Mobility** issues can include the inability to operate a mouse, a keyboard or touch-screen.
* Make the content of your elements [functionally accessible from a keyboard](http://www.w3.org/TR/wai-aria-practices/#keyboard) for any actions one would otherwise use a mouse for.
* Ensure user interface elements are correctly marked up for assistive technologies; these users may use technologies such as voice control software and physical switch controls, which tend to use the same APIs as other assistive technologies like screen readers.
-**Cognitive** issues mean a user may require assistive technologies to help them with reading text, so it’s important to ensure text alternatives exist.
+**Cognitive** issues mean a user may require assistive technologies to help them with reading text, so it’s important to ensure text alternatives exist.
-* Avoid a visual presentation that is [repetitive](http://www.w3.org/TR/WCAG20/#time-limits) or flashing as this can cause some users [issues](http://www.w3.org/TR/WCAG20/#seizure).
+* Avoid a visual presentation that is [repetitive](http://www.w3.org/TR/WCAG20/#time-limits) or flashing as this can cause some users [issues](http://www.w3.org/TR/WCAG20/#seizure).
* Avoid interactions that are timing-based.
@@ -79,13 +78,13 @@ Native controls (such as `` and ``) have accessibility built-in
Custom elements (with the exception of elements that extend native elements like ``) do not have any built-in functionality, including accessibility, so this needs to be provided by you. A good place to start when implementing accessibility is to compare your custom element to an analogous native element (or a combination of several native elements, depending on how complex your component is).
-The following is a list of questions you can ask yourself when attempting to make your custom elements more accessible.
+The following is a list of questions you can ask yourself when attempting to make your custom elements more accessible.
-### Can your element be used with the keyboard alone?
+### Can your element be used with the keyboard alone?
-Ideally, ensure that all functionality in your element can be reached by a keyboard. During your UX design, think about how you would use your element with the keyboard alone, and figure out a consistent set of keyboard interactions.
+Ideally, ensure that all functionality in your element can be reached by a keyboard. During your UX design, think about how you would use your element with the keyboard alone, and figure out a consistent set of keyboard interactions.
-Firstly, ensure that you have a sensible **focus** target for each element. For example, a complex element like a menu may be one focus target within a page, but should then manage focus within itself so that the active menu item always takes focus.
+Firstly, ensure that you have a sensible **focus** target for each element. For example, a complex element like a menu may be one focus target within a page, but should then manage focus within itself so that the active menu item always takes focus.
![Menu displaying how to manage focus](/articles/images/accessible-web-components/image_0.png)
@@ -136,7 +135,7 @@ Any element which displays an image should provide a mechanism for providing alt
Assistive technology conveys semantic information which is otherwise expressed to sighted users via visual cues such as formatting, cursor style, or position. Native elements have this semantic information built-in by the browser, but for custom elements you need to use [ARIA](http://www.w3.org/WAI/PF/aria/) to add this information in.
-One technology which is critical for custom element accessibility is [WAI-ARIA](http://www.w3.org/WAI/PF/aria/). ARIA is a specification defining support for accessible web apps. It defines markup extensions (implemented as attributes on elements), which can be used to provide additional information about the semantics of elements to assistive technologies like screen readers.
+One technology which is critical for custom element accessibility is [WAI-ARIA](http://www.w3.org/WAI/PF/aria/). ARIA is a specification defining support for accessible web apps. It defines markup extensions (implemented as attributes on elements), which can be used to provide additional information about the semantics of elements to assistive technologies like screen readers.
As a rule of thumb, any element which listens to a mouse click or hover event should not only have some kind of keyboard event listener, but also an ARIA role and potentially ARIA states and attributes.
@@ -156,7 +155,7 @@ Color shouldn’t be used as the only means of conveying information, such as in
Any text content displayed in your element should meet the [minimum (AA) contrast bar](http://www.w3.org/TR/2008/REC-WCAG20-20081211/#visual-audio-contrast-contrast). Consider providing a high-contrast theme which meets the [higher (AAA) bar](http://www.w3.org/TR/2008/REC-WCAG20-20081211/#visual-audio-contrast7), and also ensure that user agent style sheets can be applied if users require extreme contrast or different colors. You can use this [Color Contrast Checker](http://webaim.org/resources/contrastchecker/) as an aid when doing design.
-### Is the moving or flashing content in your elements stoppable and safe?
+### Is the moving or flashing content in your elements stoppable and safe?
Content that moves, scrolls or blinks that lasts for anything more than 5 seconds should be able to be paused, stopped or hidden. In general, try to flash no more than three times per second.
diff --git a/articles/communication.md b/articles/communication.md
index b808c7b698..ef2fff8cdc 100644
--- a/articles/communication.md
+++ b/articles/communication.md
@@ -1,7 +1,6 @@
---
layout: default
-type: core
-navgroup: docs
+type: guide
shortname: Articles
title: "Communication & Message Passing"
subtitle: Common techniques for sharing information between custom elements
@@ -50,7 +49,7 @@ We'll cover the following techniques:
1. [Data binding](#binding)
1. [Changed watchers](#changedwatchers)
1. [Custom events](#events)
-1. [Using an element's API](#api)
+1. [Using an element's API](#api)
### 1. Data binding {#binding}
@@ -114,7 +113,7 @@ When a {{site.project_title}} element [publishes](/docs/polymer/polymer.html#pub
`.items` and `.value` are bound together with "list":
{% raw %}
-
+
{% endraw %}
@@ -271,7 +270,7 @@ a user of `` can setup a handler for the event:
As with normal DOM events outside of {{site.project_title}}, you can attach additional data to a custom event. This makes **events an ideal way to distribute arbitrary information to other elements**.
-**Example:** include the `name` property as part of the payload:
+**Example:** include the `name` property as part of the payload:
sayHi: function() {
this.fire('said-hello', {name: this.name});
@@ -348,7 +347,7 @@ Things become very interesting when several elements need to respond to an event
first: function(e, detail, sender) {
logger('first():', detail, sender);
},
- second: function(e, detail, sender) {
+ second: function(e, detail, sender) {
logger('second():', detail, sender);
},
third: function(e, detail, sender) {
@@ -398,7 +397,7 @@ sibling or child elements. That is:
When `` fires `said-hello`, it bubbles and `sayHi()` handles it.
However, suppose `` has setup an internal listener for the same event.
It wants in on the action! Unfortunately, this means we can no longer exploit
-the benefits of event bubbling...by itself.
+the benefits of event bubbling...by itself.
This particular problem isn't new to the web but you can easily handle it in
{{site.project_title}}. Just use event delegation and manually fire the event
@@ -492,7 +491,7 @@ other frameworks for a long time, so technically it's not a new concept.
Whether you're inside or outside a ``, there are plenty of
ways to send instructions/messages/data to other web components. Hopefully,
you're seeing that nothing has changed in the world of custom elements. That's
-the point :) It's the same web we've always known...just more powerful!
+the point :) It's the same web we've always known...just more powerful!
@@ -255,7 +254,7 @@ event that signifies all elements have been upgraded.
@@ -341,7 +340,7 @@ see [styling distributed nodes](#style-distributed).
I'm black
-
+
**Note**: For complex styling like distribute nodes, {{site.project_title}} provides the `polyfill-*`
selectors to polyfill certain Shadow DOM features. See the [Styling reference](/docs/polymer/styling.html#directives) for more information on the directives.
{: .alert .alert-info }
@@ -353,7 +352,7 @@ selectors to polyfill certain Shadow DOM features. See the [Styling reference](/
color: green;
}
.red {
- color: red;
+ color: red;
}
@@ -373,7 +372,7 @@ selectors to polyfill certain Shadow DOM features. See the [Styling reference](/
color: green;
}
.red {
- color: red;
+ color: red;
}
@@ -394,14 +393,14 @@ The `::shadow` pseudo-element and the `/deep/` combinator pierce through Shadow
#### The `::shadow` pseudo-element {#hat}
-If an element has at least one shadow tree, the `::shadow` pseudo-element matches the shadow roots themselves.
-For example, say you wanted to style x-foo's internal `p` element. Writing `x-foo::shadow` selects x-foo's shadow root. From there, you can write a normal descendant selector to get at the `p`:
+If an element has at least one shadow tree, the `::shadow` pseudo-element matches the shadow roots themselves.
+For example, say you wanted to style x-foo's internal `p` element. Writing `x-foo::shadow` selects x-foo's shadow root. From there, you can write a normal descendant selector to get at the `p`:
-Now you can display the icon with `core-icon` using the same
+Now you can display the icon with `core-icon` using the same
iconset-name : icon-name
format used for built-in icon sets. For example, to display the icon
defined above use `custom-icons:fancy-circles` as the `icon` attribute.
@@ -235,8 +234,8 @@ Produces:
## Using icons with other elements {#icons-in-other-core-components}
-You can use icons on their own, but also use them with other elements, such as buttons. You can use the built-in
-and custom icon sets with any `core-` or `paper-` element that has an `icon` attribute. Remember to include the
+You can use icons on their own, but also use them with other elements, such as buttons. You can use the built-in
+and custom icon sets with any `core-` or `paper-` element that has an `icon` attribute. Remember to include the
appropriate icon set before referring to an icon, otherwise the icon will not render.
The following examples use `core-icon-button`, `core-menu-button` and `core-item` with
@@ -254,7 +253,7 @@ Produces:
-There are two ways to style the icons inside another element. Since `color` is an
+There are two ways to style the icons inside another element. Since `color` is an
inherited property, you can set `color` on the parent element: