diff --git a/docs/components/icon.md b/docs/components/icon.md new file mode 100644 index 0000000000..cf0539fe7c --- /dev/null +++ b/docs/components/icon.md @@ -0,0 +1,203 @@ +# Icon + + + + + + + +[Icons](https://m3.material.io/styles/icons/overview) can be used to +represent common actions. Material Symbols are a set of variable icon fonts +created at seven weights across three different styles. + +![Array of icons with various stylistic attributes](images/icon/hero.gif) + +* [Design article](https://m3.material.io/styles/icons) +* API Documentation (*coming soon*) +* [Source code](https://github.com/material-components/material-web/tree/master/icon) + + +## Usage + +Icons can be specified by name, unicode code point, or have an `` child +element. + +![Settings icon as ligature, check box icon as codepoint, and house icon as SVG](images/icon/usage.png "Example icons") + +```html +settings + + +``` + +The full range of icons can be found on the +[Material Symbols](https://fonts.google.com/icons) font page. + +Material Symbols icons are available in three styles: **outlined**, **rounded**, +and **sharp**. + +In addition, Material Symbols have four adjustable stylistic variable font +attributes called axes. An axis is a typographic term referring to the attribute +of a symbol that can be altered to create visual variations. + +Each style symbol contains four axes: **weight**, **fill**, **grade**, and +**optical size**. + +The `weight` and `optical size` attributes are handled automatically, but the +`fill` and `grade` attributes are custom to the Material Symbols font, and must +be set with the +[`font-variation-settings`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variation-settings) +property. + +### Outlined + +Outlined symbols use stroke and fill attributes for a light, clean style that +works well in dense UIs. The stroke weight of outlined icons can be adjusted to +complement or contrast the weight of your typography. + +Load the font with + +```html + +``` + +### Rounded + +![Settings, checkbox, and house icons in Rounded style](images/icon/usage_rounded.png "Rounded Icons") + +Rounded symbols use a corner radius that pairs well with brands that use heavier +typography, curved logos, or circular elements to express their style. + +Load the font with + +```html + +``` + +To use Rounded icons, set `--md-icon-font` to `'Material Symbols Rounded'`. + +### Sharp + +![Settings, checkbox, and house icons in Sharp style](images/icon/usage_sharp.png "Sharp Icons") + +Sharp symbols display corners with straight edges, for a crisp style that +remains legible even at smaller scales. These rectangular shapes can support +brand styles that aren’t well-reflected by rounded shapes. + +Load the font with + +```html + +``` + +To use Sharp icons, set `--md-icon-font` to `'Material Symbols Sharp'`. + +### Fill + +![Filed settings, checkbox, and house icons](images/icon/usage_filled.png "Filled Icons") + +Filled Icons gives you the ability to transition from a more outlined style to a +reversed or more filled style. + +A fill attribute can be used to convey a state of transition, such as unfilled +and filled states. Values range from `0` to `1`, with `1` being completely +filled. Along with weight, fill is a primary attribute that impacts the overall +look of a symbol. + +All styles of Material Symbols can be filled by setting +`--md-icon-font-variation-settings` to `'FILL' 1`. + +## Accessibility + +Icons are mostly intended to be used inside of other components that have +accessibility settings. + +If used on their own, Icons should be given an accessible name if they are +focusable. If you use icons by name, they will be announced by screen readers +without any extra steps. + +If using codepoints, wrap the codepoint in a `` with an +[`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) +attribute. + +```html + +``` + +If using SVG icons, add an `aria-label` attribute to the SVG element. + +```html + +``` + +## Theming + +### Tokens + +Token | Default value +----------------------------------- | ----------------------------- +`--md-icon-color` | `inherit` +`--md-icon-font` | `'Material Symbols Outlined'` +`--md-icon-font-variation-settings` | `inherit` +`--md-icon-size` | `24px` +`--md-icon-weight` | `400` + +* [All tokens](https://github.com/material-components/material-web/blob/master/icon/lib/_md-comp-icon.scss) + + +### Example + +![Image of icons with a different theme applied](images/icon/theming.png "Icon theming example.") + +```html + + + + + + +

Outlined

+ + settings + check_box + house + settings + check_box + house + +

Rounded

+ + settings + check_box + house + settings + check_box + house + +

Sharp

+ + settings + check_box + house + settings + check_box + house + +``` diff --git a/docs/components/images/icon/hero.gif b/docs/components/images/icon/hero.gif new file mode 100644 index 0000000000..cdca63bbad Binary files /dev/null and b/docs/components/images/icon/hero.gif differ diff --git a/docs/components/images/icon/theming.png b/docs/components/images/icon/theming.png new file mode 100644 index 0000000000..da784b1276 Binary files /dev/null and b/docs/components/images/icon/theming.png differ diff --git a/docs/components/images/icon/usage.png b/docs/components/images/icon/usage.png new file mode 100644 index 0000000000..544f5a2437 Binary files /dev/null and b/docs/components/images/icon/usage.png differ diff --git a/docs/components/images/icon/usage_filled.png b/docs/components/images/icon/usage_filled.png new file mode 100644 index 0000000000..309466b7ce Binary files /dev/null and b/docs/components/images/icon/usage_filled.png differ diff --git a/docs/components/images/icon/usage_rounded.png b/docs/components/images/icon/usage_rounded.png new file mode 100644 index 0000000000..2bcf914a09 Binary files /dev/null and b/docs/components/images/icon/usage_rounded.png differ diff --git a/docs/components/images/icon/usage_sharp.png b/docs/components/images/icon/usage_sharp.png new file mode 100644 index 0000000000..531dbbbe78 Binary files /dev/null and b/docs/components/images/icon/usage_sharp.png differ