зеркало из https://github.com/microsoft/fast.git
chore: add color recipe documentation (#3187)
* add internal tag to math functions * fill out other color function documentation * address feedback * clarify document * move document * move styling components docs to fast-components * update metadata of doc files * wire docs to sidebar * adding generated files to docs * re-format styling-components into sub parts * update coppied doc * remove title from type-ramp
This commit is contained in:
Nicholas Rice
GitHub
Родитель
b8aad52125
Коммит
3ab443d899
|
|
@ -0,0 +1,148 @@
|
|||
---
|
||||
id: color
|
||||
title: Color
|
||||
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-components/docs/guide/color.doc.md
|
||||
---
|
||||
|
||||
FAST utilizes an adaptive color system that provides some unique advantages:
|
||||
- Ensure text meets [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/) contrast requirements.
|
||||
- Easily swap from light mode to dark, or anywhere in-between.
|
||||
- Color themeing through palette tinting.
|
||||
- Perceptually uniform UI across different background colors.
|
||||
|
||||
## Algorithmic Colors (Recipes)
|
||||
FAST makes heavy use of algorithmic colors; named colors are a product of the *designSystem* object in which they are calculated. In the documentation below, these algorithmic colors will be referred to as *recipes*.
|
||||
|
||||
### Inputs
|
||||
Each color recipe expects as its sole argument the FAST *DesignSystem* object, but there are a few core pieces of data from that object that impact color resolution.
|
||||
|
||||
### Palettes
|
||||
Each color recipe operates on a palette. A palette in an array of hexadecimal colors ordered from light to dark. By default, FAST components leverage the `neutralPalette` and the `accentPalette`.
|
||||
|
||||
### Background color
|
||||
This is the contextual color that the recipe uses to determine what color it is rendering on. The foreground, outline, and divider recipes will use this color to ensure that the color created is accessible and meets contrast requirements. In fill recipes it is sometimes used as the starting location in the appropriate palette to begin resolution.
|
||||
|
||||
### Offsets
|
||||
Some recipes also leverage offset values, typically for *states* (rest, hovered, active, selected). These offsets are used to retrieve a color at the sum of the offset and some reference index (usually the index of the rest color or the background color in the palette).
|
||||
|
||||
## Color Recipes
|
||||
### Using Color Recipes
|
||||
First, ensure the UI element has a *FASTDesignSystemProvider* ancestor element - this element will *resolve* the recipe for a component within it that declares a dependency on the recipe.
|
||||
|
||||
```html
|
||||
<fast-design-system-provider use-defaults>
|
||||
<my-element>I use a color recipe!</my-element>
|
||||
</fast-design-system-provider>
|
||||
```
|
||||
|
||||
*For more information on the DesignSystemProvider, see the [*DesignSystemProvider* documentation](fast-foundation/fast-design-system-provider.md)*
|
||||
|
||||
|
||||
Next - declare the recipe as a dependent *behavior* of a Web Component's stylesheet. Then use the recipe as a CSS Custom Property in the stylesheet:
|
||||
|
||||
```js
|
||||
import { css } from "@microsoft/fast-element";
|
||||
import { neutralFillRest } from "@microsoft/fast-components";
|
||||
|
||||
const styles = css`
|
||||
:host {
|
||||
background: var(--neutral-fill-rest);
|
||||
}
|
||||
`.withBehaviors(
|
||||
neutralFillRest
|
||||
);
|
||||
```
|
||||
|
||||
### Neutral Recipes
|
||||
#### Layer Recipes
|
||||
Layer recipes represent the UI layers and surfaces that individual UI elements are contained within. They are applied to primary regions such as toolbars, sidebars, canvas regions, fly-outs, dialogs, and cards.
|
||||
|
||||
| name | Description |
|
||||
|------|-------------|
|
||||
| `neutralLayerFloating` | Used as the background for floating layers, including context menus and fly-outs. |
|
||||
| `neutralLayerCard` | Used as the background color for cards. Pair with `neutralLayerCardContainer` for the container background. |
|
||||
| `neutralLayerCardContainer` | Used as the background color for card containers. Pair with `neutralLayerCard` for the card backgrounds. |
|
||||
| `neutralLayerL1` | Used as the background color for the primary content layer (L1). |
|
||||
| `neutralLayerL1Alt` | Alternate color for L1 surfaces. |
|
||||
| `neutralLayerL2` | Used as the background for the top command surface, logically below L1. |
|
||||
| `neutralLayerL3` | Used as the background for secondary command surfaces, logically below L2. |
|
||||
| `neutralLayerL4` | Used as the background for the lowest command surface or title bar, logically below L3. |
|
||||
|
||||
#### Text
|
||||
Neutral text recipes address *most* cases of text used in a UI, from interactive element text, headings, and body text.
|
||||
|
||||
| name | Description |
|
||||
|------|-------------|
|
||||
| `neutralForegroundRest` | Primary page text color when the text is in a *rest* state. |
|
||||
| `neutralForegroundHover` | Primary page text color when the text is in a *hover* state. |
|
||||
| `neutralForegroundActive` | Primary page text color when the text is in a *active* (pressed) state. |
|
||||
| `neutralForegroundHint` | Secondary *hinting* text to be used with [non-large text](https://www.w3.org/TR/WCAG/#contrast-minimum) to meet a 4.5:1 contrast ratio to the background. |
|
||||
| `neutralForegroundHintLarge` | Secondary *hinting* text to be used with [large text](https://www.w3.org/TR/WCAG/#contrast-minimum) to meet a 3:1 contrast ratio to the background. |
|
||||
|
||||
#### Fills (Backgrounds)
|
||||
Neutral fills are indented to be used as fill colors (background) to UI elements to distinguish them from the background.
|
||||
|
||||
| name | Description |
|
||||
|------|-------------|
|
||||
| `neutralFillRest`| Used to visually differentiate the UI element from it's background context at rest. |
|
||||
| `neutralFillHover`| Used as the fill of a `neutralFill` element when hovered. |
|
||||
| `neutralFillActive`| Used as the fill of a `neutralFill` element when active. |
|
||||
| `neutralFillSelected`| Used as the fill of a `neutralFill` element when selected. |
|
||||
| `neutralFillStealthRest`| Used when a UI element's fill is visually differentiated when being interacted with by the user. |
|
||||
| `neutralFillStealthHover`| Used as the fill of a `neutralFillStealth` element when hovered. |
|
||||
| `neutralFillStealthActive`| Used as the fill of a `neutralFillStealth` element when active. |
|
||||
| `neutralFillStealthSelected`| Used as the fill of a `neutralFillStealth` element when selected. |
|
||||
|
||||
#### Outlines and Dividers
|
||||
Neutral outlines are used to construct outline controls and dividers.
|
||||
|
||||
| name | Description |
|
||||
|------|-------------|
|
||||
| `neutralOutlineRest` | Used as a rest outline color for outline controls. |
|
||||
| `neutralOutlineHover` | Used as the outline of a `neutralOutline` control when hovered. |
|
||||
| `neutralOutlineActive` | Used as the outline of a `neutralOutline` control when active. |
|
||||
| `neutralDividerRest` | Used as the color for divider elements. |
|
||||
|
||||
#### Toggles
|
||||
Toggle elements such as checkboxes and switches use a specific set of recipes.
|
||||
|
||||
| name | Description |
|
||||
|------|-------------|
|
||||
| `neutralForegroundToggle` | Used as the foreground of toggle elements with [non-large text](https://www.w3.org/TR/WCAG/#contrast-minimum) to meet a 4.5:1 contrast ratio to the background. |
|
||||
| `neutralForegroundToggleLarge` | Used as the foreground of toggle elements with [large text](https://www.w3.org/TR/WCAG/#contrast-minimum) to meet a 3:1 contrast ratio to the background. |
|
||||
| `neutralFillToggleRest` | Used as fill of a *toggle* element like checkbox. |
|
||||
| `neutralFillToggleHover` | Used as the fill of a `neutralFillToggle` element when hovered. |
|
||||
| `neutralFillToggleActive` | Used as the fill of a `neutralFillToggle` element when active. |
|
||||
|
||||
#### Inputs
|
||||
Text input elements also have a set of recipes specifically tailored.
|
||||
|
||||
| name | Description |
|
||||
|------|-------------|
|
||||
| `neutralFillInputRest` | Used as the fill of the text input at rest. |
|
||||
| `neutralFillInputHover` | Used as the fill of the text input when hovered. |
|
||||
| `neutralFillInputActive` | Used as the fill of the text input when active. |
|
||||
| `neutralFillInputSelected` | Used as the fill of the text input when selected. |
|
||||
|
||||
#### Document Focus
|
||||
| name | Description |
|
||||
|------|-------------|
|
||||
| `neutralFocus` | The color of the focus indicator when the element has document focus. |
|
||||
| `neutralFocusInnerAccent` | The color of the inner focus-indicator when an *accent fill* element has document focus. |
|
||||
|
||||
### Accent Recipes
|
||||
Accent recipes use the accent palette and are intended to bring attention or otherwise distinguish the element on the page.
|
||||
|
||||
| name | Description |
|
||||
|------|-------------|
|
||||
| `accentFillRest` | Used as the fill of an accent element at rest. |
|
||||
| `accentFillHover` | Used as the fill of an `accentFill` element when hovered. |
|
||||
| `accentFillActive` | Used as the fill of an `accentFill` element when active. |
|
||||
| `accentFillSelected` | Used as the fill of an `accentFill` element when selected. |
|
||||
| `accentFillLarge` | |
|
||||
| `accentFillLargeRest` | Used as the fill of an accent element at rest that uses [large text](https://www.w3.org/TR/WCAG/#contrast-minimum). |
|
||||
| `accentFillLargeHover` | Used as the fill of an `accentFillLarge` element when hovered. |
|
||||
| `accentFillLargeActive` | Used as the fill of an `accentFillLarge` element when active. |
|
||||
| `accentFillLargeSelected` | Used as the fill of an `accentFillLarge` element when selected. |
|
||||
| `accentForegroundCut` | Used as foreground color of text used *over* `accentFill` fill. |
|
||||
| `accentForegroundCutLarge` | Used as foreground color of text used *over* `accentFillLarge` fill. |
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
---
|
||||
id: design-system
|
||||
title: Design System
|
||||
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-components/docs/guide/design-system.doc.md
|
||||
---
|
||||
|
||||
In FAST, the *design system* is a collection of properties and values that inform the visual design language of the components. These properties are managed and provided through implementations of the [*DesignSystemProvider*](fast-foundation/fast-design-system-provider.md).
|
||||
|
||||
For the purposes of this section, just know the *DesignSystemProvider* is a Custom Element that will create CSS Custom Properties that can be consumed by component stylesheets and provide mechanisms to synchronize, update, and consume those properties programmatically.
|
||||
|
||||
### Design System Properties
|
||||
The following properties are provided by the `FASTDesignSystemProvider` and should be used as appropriate.
|
||||
|
||||
| Name | Type | Description |
|
||||
|----------------------------------------|-------------------- |----------------------------------------------------------------------------|
|
||||
| `--background-color` | `string` (hex color) | Defines the background color of the node. This is used by color recipes and should represent the color UI is rendering on for a given node tree. |
|
||||
| `--density` | `number` | A multiplier to control the density of UI elements. |
|
||||
| `--design-unit` | `number` | The core sizing unit that all sizes are derived from. |
|
||||
| `--base-height-multiplier` | `number` | The number of design units used for component height at the base density. |
|
||||
| `--base-horizontal-spacing-multiplier` | `number` | The number of design units used for horizontal spacing at the base density. |
|
||||
| `--corner-radius` | `number` | The corner radius of controls. |
|
||||
| `--outline-width` | `number` | The width of the outline of outline controls. |
|
||||
| `--focus-outline-width` | `number` | The width of the focus indicator. |
|
||||
| `--disabled-opacity` | `number` | Opacity of disabled controls. |
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
id: intro
|
||||
title: Intro
|
||||
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-components/docs/guide/intro.doc.md
|
||||
---
|
||||
|
||||
`@microsoft/fast-components` leverages `@microsoft/fast-element` to style components. For details on how to apply CSS, see [leveraging CSS](fast-element/leveraging-css.md).
|
||||
|
||||
## Hiding Undefined Elements
|
||||
Custom Elements that have not been [upgraded](https://developers.google.com/web/fundamentals/web-components/customelements#upgrades) and don't have styles attached can still be rendered by the browser but they likely do not look how they are supposed to. To avoid a *flash of un-styled content* (FOUC), visually hide Custom Elements if they have not been *defined*:
|
||||
|
||||
```CSS
|
||||
:not(:defined) {
|
||||
visibility: hidden;
|
||||
}
|
||||
```
|
||||
|
||||
*Note, the consuming application must apply this, as the components themselves do not.*
|
||||
|
|
@ -0,0 +1,48 @@
|
|||
---
|
||||
id: match-media-stylesheets
|
||||
title: MatchMedia Stylesheets
|
||||
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-components/docs/guide/styling-components.doc.md
|
||||
---
|
||||
|
||||
FAST exposes a mechanism to attach stylesheets conditionally based on a [MatchMedia](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) query.
|
||||
|
||||
### MatchMedia Stylesheets
|
||||
`matchMediaStylesheetBehaviorFactory` can be used to construct a Behavior that will conditionally attach stylesheets based on the `matches` property of a [MediaQueryList](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList).
|
||||
|
||||
__Example: Using the `matchMediaStylesheetBehaviorFactory`__
|
||||
```js
|
||||
import { matchMediaStylesheetBehaviorFactory } from "@microsoft/fast-foundation";
|
||||
const query = Window.matchMedia('(max-width: 600px)');
|
||||
const maxWidthStylesheetBehavior = matchMediaStylesheetBehaviorFactory(query)
|
||||
const styles = css`
|
||||
/* ... */
|
||||
`.withBehaviors(
|
||||
maxWidthStylesheetBehavior(css`
|
||||
body {
|
||||
color: red;
|
||||
}
|
||||
`)
|
||||
)
|
||||
```
|
||||
|
||||
### Forced-colors Stylesheets
|
||||
FAST has a commitment to facilitating accessible web experiences and [forced-colors](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/forced-colors) support is a core tenant of that commitment. `@microsoft/fast-components` exports the `forcedColorsStylesheetBehavior` utility to provide a simple mechanism to apply forced-color stylesheets without bloating the component stylesheet in non-forced-color environments. This Behavior is built using [MatchMedia Stylesheets](#matchmedia-stylesheets).
|
||||
|
||||
__Example: Forced-colors stylesheets__
|
||||
```js
|
||||
import { forcedColorsStylesheetBehavior } from "@microsoft/fast-foundation";
|
||||
import { SystemColors } from "@microsoft/fast-web-utilities";
|
||||
const styles = css`
|
||||
/* ... */
|
||||
`.withBehaviors(
|
||||
forcedColorsStylesheetBehavior(css`
|
||||
:host {
|
||||
background: ${SystemColors.Canvas};
|
||||
color: ${SystemColors.CanvasText};
|
||||
}
|
||||
/* ... */
|
||||
`)
|
||||
)
|
||||
```
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
id: type-ramp
|
||||
title: Type ramp
|
||||
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-components/docs/guide/type-ramp.doc.md
|
||||
---
|
||||
|
||||
The FAST type ramp is exposed by the `FASTDesignSystemProvider` as CSS Custom Properties. It organizes the ramp around a _base_ font size and line-height, ascending and descending from the _base_. The CSS Custom Properties that can be used are:
|
||||
|
||||
| Level | Font Size | Line Height |
|
||||
|--------------------|---------------------------------|----------------------------------|
|
||||
| Minus 2 (smallest) | `--type-ramp-minus-2-font-size` | `--type-ramp-minus-2-line-height`|
|
||||
| Minus 1 | `--type-ramp-minus-1-font-size` | `--type-ramp-minus-1-line-height`|
|
||||
| Base (body) | `--type-ramp-base-font-size` | `--type-ramp-base-line-height` |
|
||||
| Plus 1 | `--type-ramp-plus-1-font-size` | `--type-ramp-plus-1-line-height` |
|
||||
| Plus 2 | `--type-ramp-plus-2-font-size` | `--type-ramp-plus-2-line-height` |
|
||||
| Plus 3 | `--type-ramp-plus-3-font-size` | `--type-ramp-plus-3-line-height` |
|
||||
| Plus 4 | `--type-ramp-plus-4-font-size` | `--type-ramp-plus-4-line-height` |
|
||||
| Plus 5 | `--type-ramp-plus-5-font-size` | `--type-ramp-plus-5-line-height` |
|
||||
| Plus 6 (largest) | `--type-ramp-plus-6-font-size` | `--type-ramp-plus-6-line-height` |
|
||||
|
|
@ -48,6 +48,7 @@ const _divide: (
|
|||
);
|
||||
/**
|
||||
* Adds numbers or functions that accept a design system and return a number.
|
||||
* @internal
|
||||
*/
|
||||
export function add<T>(
|
||||
...args: Array<number | ((designSystem: T) => number)>
|
||||
|
|
@ -57,6 +58,7 @@ export function add<T>(
|
|||
|
||||
/**
|
||||
* Subtract numbers or functions that accept a design system and return a number.
|
||||
* @internal
|
||||
*/
|
||||
export function subtract<T>(
|
||||
...args: Array<number | ((designSystem: T) => number)>
|
||||
|
|
@ -66,6 +68,7 @@ export function subtract<T>(
|
|||
|
||||
/**
|
||||
* Multiplies numbers or functions that accept a design system and return a number.
|
||||
* @internal
|
||||
*/
|
||||
export function multiply<T>(
|
||||
...args: Array<number | ((designSystem: T) => number)>
|
||||
|
|
@ -75,6 +78,7 @@ export function multiply<T>(
|
|||
|
||||
/**
|
||||
* Divides numbers or functions that accept a design system and return a number.
|
||||
* @internal
|
||||
*/
|
||||
export function divide<T>(
|
||||
...args: Array<number | ((designSystem: T) => number)>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,148 @@
|
|||
---
|
||||
id: color
|
||||
title: Color
|
||||
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-components/docs/guide/color.doc.md
|
||||
---
|
||||
|
||||
FAST utilizes an adaptive color system that provides some unique advantages:
|
||||
- Ensure text meets [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/) contrast requirements.
|
||||
- Easily swap from light mode to dark, or anywhere in-between.
|
||||
- Color themeing through palette tinting.
|
||||
- Perceptually uniform UI across different background colors.
|
||||
|
||||
## Algorithmic Colors (Recipes)
|
||||
FAST makes heavy use of algorithmic colors; named colors are a product of the *designSystem* object in which they are calculated. In the documentation below, these algorithmic colors will be referred to as *recipes*.
|
||||
|
||||
### Inputs
|
||||
Each color recipe expects as its sole argument the FAST *DesignSystem* object, but there are a few core pieces of data from that object that impact color resolution.
|
||||
|
||||
### Palettes
|
||||
Each color recipe operates on a palette. A palette in an array of hexadecimal colors ordered from light to dark. By default, FAST components leverage the `neutralPalette` and the `accentPalette`.
|
||||
|
||||
### Background color
|
||||
This is the contextual color that the recipe uses to determine what color it is rendering on. The foreground, outline, and divider recipes will use this color to ensure that the color created is accessible and meets contrast requirements. In fill recipes it is sometimes used as the starting location in the appropriate palette to begin resolution.
|
||||
|
||||
### Offsets
|
||||
Some recipes also leverage offset values, typically for *states* (rest, hovered, active, selected). These offsets are used to retrieve a color at the sum of the offset and some reference index (usually the index of the rest color or the background color in the palette).
|
||||
|
||||
## Color Recipes
|
||||
### Using Color Recipes
|
||||
First, ensure the UI element has a *FASTDesignSystemProvider* ancestor element - this element will *resolve* the recipe for a component within it that declares a dependency on the recipe.
|
||||
|
||||
```html
|
||||
<fast-design-system-provider use-defaults>
|
||||
<my-element>I use a color recipe!</my-element>
|
||||
</fast-design-system-provider>
|
||||
```
|
||||
|
||||
*For more information on the DesignSystemProvider, see the [*DesignSystemProvider* documentation](fast-foundation/fast-design-system-provider.md)*
|
||||
|
||||
|
||||
Next - declare the recipe as a dependent *behavior* of a Web Component's stylesheet. Then use the recipe as a CSS Custom Property in the stylesheet:
|
||||
|
||||
```js
|
||||
import { css } from "@microsoft/fast-element";
|
||||
import { neutralFillRest } from "@microsoft/fast-components";
|
||||
|
||||
const styles = css`
|
||||
:host {
|
||||
background: var(--neutral-fill-rest);
|
||||
}
|
||||
`.withBehaviors(
|
||||
neutralFillRest
|
||||
);
|
||||
```
|
||||
|
||||
### Neutral Recipes
|
||||
#### Layer Recipes
|
||||
Layer recipes represent the UI layers and surfaces that individual UI elements are contained within. They are applied to primary regions such as toolbars, sidebars, canvas regions, fly-outs, dialogs, and cards.
|
||||
|
||||
| name | Description |
|
||||
|------|-------------|
|
||||
| `neutralLayerFloating` | Used as the background for floating layers, including context menus and fly-outs. |
|
||||
| `neutralLayerCard` | Used as the background color for cards. Pair with `neutralLayerCardContainer` for the container background. |
|
||||
| `neutralLayerCardContainer` | Used as the background color for card containers. Pair with `neutralLayerCard` for the card backgrounds. |
|
||||
| `neutralLayerL1` | Used as the background color for the primary content layer (L1). |
|
||||
| `neutralLayerL1Alt` | Alternate color for L1 surfaces. |
|
||||
| `neutralLayerL2` | Used as the background for the top command surface, logically below L1. |
|
||||
| `neutralLayerL3` | Used as the background for secondary command surfaces, logically below L2. |
|
||||
| `neutralLayerL4` | Used as the background for the lowest command surface or title bar, logically below L3. |
|
||||
|
||||
#### Text
|
||||
Neutral text recipes address *most* cases of text used in a UI, from interactive element text, headings, and body text.
|
||||
|
||||
| name | Description |
|
||||
|------|-------------|
|
||||
| `neutralForegroundRest` | Primary page text color when the text is in a *rest* state. |
|
||||
| `neutralForegroundHover` | Primary page text color when the text is in a *hover* state. |
|
||||
| `neutralForegroundActive` | Primary page text color when the text is in a *active* (pressed) state. |
|
||||
| `neutralForegroundHint` | Secondary *hinting* text to be used with [non-large text](https://www.w3.org/TR/WCAG/#contrast-minimum) to meet a 4.5:1 contrast ratio to the background. |
|
||||
| `neutralForegroundHintLarge` | Secondary *hinting* text to be used with [large text](https://www.w3.org/TR/WCAG/#contrast-minimum) to meet a 3:1 contrast ratio to the background. |
|
||||
|
||||
#### Fills (Backgrounds)
|
||||
Neutral fills are indented to be used as fill colors (background) to UI elements to distinguish them from the background.
|
||||
|
||||
| name | Description |
|
||||
|------|-------------|
|
||||
| `neutralFillRest`| Used to visually differentiate the UI element from it's background context at rest. |
|
||||
| `neutralFillHover`| Used as the fill of a `neutralFill` element when hovered. |
|
||||
| `neutralFillActive`| Used as the fill of a `neutralFill` element when active. |
|
||||
| `neutralFillSelected`| Used as the fill of a `neutralFill` element when selected. |
|
||||
| `neutralFillStealthRest`| Used when a UI element's fill is visually differentiated when being interacted with by the user. |
|
||||
| `neutralFillStealthHover`| Used as the fill of a `neutralFillStealth` element when hovered. |
|
||||
| `neutralFillStealthActive`| Used as the fill of a `neutralFillStealth` element when active. |
|
||||
| `neutralFillStealthSelected`| Used as the fill of a `neutralFillStealth` element when selected. |
|
||||
|
||||
#### Outlines and Dividers
|
||||
Neutral outlines are used to construct outline controls and dividers.
|
||||
|
||||
| name | Description |
|
||||
|------|-------------|
|
||||
| `neutralOutlineRest` | Used as a rest outline color for outline controls. |
|
||||
| `neutralOutlineHover` | Used as the outline of a `neutralOutline` control when hovered. |
|
||||
| `neutralOutlineActive` | Used as the outline of a `neutralOutline` control when active. |
|
||||
| `neutralDividerRest` | Used as the color for divider elements. |
|
||||
|
||||
#### Toggles
|
||||
Toggle elements such as checkboxes and switches use a specific set of recipes.
|
||||
|
||||
| name | Description |
|
||||
|------|-------------|
|
||||
| `neutralForegroundToggle` | Used as the foreground of toggle elements with [non-large text](https://www.w3.org/TR/WCAG/#contrast-minimum) to meet a 4.5:1 contrast ratio to the background. |
|
||||
| `neutralForegroundToggleLarge` | Used as the foreground of toggle elements with [large text](https://www.w3.org/TR/WCAG/#contrast-minimum) to meet a 3:1 contrast ratio to the background. |
|
||||
| `neutralFillToggleRest` | Used as fill of a *toggle* element like checkbox. |
|
||||
| `neutralFillToggleHover` | Used as the fill of a `neutralFillToggle` element when hovered. |
|
||||
| `neutralFillToggleActive` | Used as the fill of a `neutralFillToggle` element when active. |
|
||||
|
||||
#### Inputs
|
||||
Text input elements also have a set of recipes specifically tailored.
|
||||
|
||||
| name | Description |
|
||||
|------|-------------|
|
||||
| `neutralFillInputRest` | Used as the fill of the text input at rest. |
|
||||
| `neutralFillInputHover` | Used as the fill of the text input when hovered. |
|
||||
| `neutralFillInputActive` | Used as the fill of the text input when active. |
|
||||
| `neutralFillInputSelected` | Used as the fill of the text input when selected. |
|
||||
|
||||
#### Document Focus
|
||||
| name | Description |
|
||||
|------|-------------|
|
||||
| `neutralFocus` | The color of the focus indicator when the element has document focus. |
|
||||
| `neutralFocusInnerAccent` | The color of the inner focus-indicator when an *accent fill* element has document focus. |
|
||||
|
||||
### Accent Recipes
|
||||
Accent recipes use the accent palette and are intended to bring attention or otherwise distinguish the element on the page.
|
||||
|
||||
| name | Description |
|
||||
|------|-------------|
|
||||
| `accentFillRest` | Used as the fill of an accent element at rest. |
|
||||
| `accentFillHover` | Used as the fill of an `accentFill` element when hovered. |
|
||||
| `accentFillActive` | Used as the fill of an `accentFill` element when active. |
|
||||
| `accentFillSelected` | Used as the fill of an `accentFill` element when selected. |
|
||||
| `accentFillLarge` | |
|
||||
| `accentFillLargeRest` | Used as the fill of an accent element at rest that uses [large text](https://www.w3.org/TR/WCAG/#contrast-minimum). |
|
||||
| `accentFillLargeHover` | Used as the fill of an `accentFillLarge` element when hovered. |
|
||||
| `accentFillLargeActive` | Used as the fill of an `accentFillLarge` element when active. |
|
||||
| `accentFillLargeSelected` | Used as the fill of an `accentFillLarge` element when selected. |
|
||||
| `accentForegroundCut` | Used as foreground color of text used *over* `accentFill` fill. |
|
||||
| `accentForegroundCutLarge` | Used as foreground color of text used *over* `accentFillLarge` fill. |
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
---
|
||||
id: design-system
|
||||
title: Design System
|
||||
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-components/docs/guide/design-system.doc.md
|
||||
---
|
||||
|
||||
In FAST, the *design system* is a collection of properties and values that inform the visual design language of the components. These properties are managed and provided through implementations of the [*DesignSystemProvider*](fast-foundation/fast-design-system-provider.md).
|
||||
|
||||
For the purposes of this section, just know the *DesignSystemProvider* is a Custom Element that will create CSS Custom Properties that can be consumed by component stylesheets and provide mechanisms to synchronize, update, and consume those properties programmatically.
|
||||
|
||||
### Design System Properties
|
||||
The following properties are provided by the `FASTDesignSystemProvider` and should be used as appropriate.
|
||||
|
||||
| Name | Type | Description |
|
||||
|----------------------------------------|-------------------- |----------------------------------------------------------------------------|
|
||||
| `--background-color` | `string` (hex color) | Defines the background color of the node. This is used by color recipes and should represent the color UI is rendering on for a given node tree. |
|
||||
| `--density` | `number` | A multiplier to control the density of UI elements. |
|
||||
| `--design-unit` | `number` | The core sizing unit that all sizes are derived from. |
|
||||
| `--base-height-multiplier` | `number` | The number of design units used for component height at the base density. |
|
||||
| `--base-horizontal-spacing-multiplier` | `number` | The number of design units used for horizontal spacing at the base density. |
|
||||
| `--corner-radius` | `number` | The corner radius of controls. |
|
||||
| `--outline-width` | `number` | The width of the outline of outline controls. |
|
||||
| `--focus-outline-width` | `number` | The width of the focus indicator. |
|
||||
| `--disabled-opacity` | `number` | Opacity of disabled controls. |
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
id: intro
|
||||
title: Intro
|
||||
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-components/docs/guide/intro.doc.md
|
||||
---
|
||||
|
||||
`@microsoft/fast-components` leverages `@microsoft/fast-element` to style components. For details on how to apply CSS, see [leveraging CSS](fast-element/leveraging-css.md).
|
||||
|
||||
## Hiding Undefined Elements
|
||||
Custom Elements that have not been [upgraded](https://developers.google.com/web/fundamentals/web-components/customelements#upgrades) and don't have styles attached can still be rendered by the browser but they likely do not look how they are supposed to. To avoid a *flash of un-styled content* (FOUC), visually hide Custom Elements if they have not been *defined*:
|
||||
|
||||
```CSS
|
||||
:not(:defined) {
|
||||
visibility: hidden;
|
||||
}
|
||||
```
|
||||
|
||||
*Note, the consuming application must apply this, as the components themselves do not.*
|
||||
|
|
@ -0,0 +1,48 @@
|
|||
---
|
||||
id: match-media-stylesheets
|
||||
title: MatchMedia Stylesheets
|
||||
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-components/docs/guide/styling-components.doc.md
|
||||
---
|
||||
|
||||
FAST exposes a mechanism to attach stylesheets conditionally based on a [MatchMedia](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) query.
|
||||
|
||||
### MatchMedia Stylesheets
|
||||
`matchMediaStylesheetBehaviorFactory` can be used to construct a Behavior that will conditionally attach stylesheets based on the `matches` property of a [MediaQueryList](https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList).
|
||||
|
||||
__Example: Using the `matchMediaStylesheetBehaviorFactory`__
|
||||
```js
|
||||
import { matchMediaStylesheetBehaviorFactory } from "@microsoft/fast-foundation";
|
||||
const query = Window.matchMedia('(max-width: 600px)');
|
||||
const maxWidthStylesheetBehavior = matchMediaStylesheetBehaviorFactory(query)
|
||||
const styles = css`
|
||||
/* ... */
|
||||
`.withBehaviors(
|
||||
maxWidthStylesheetBehavior(css`
|
||||
body {
|
||||
color: red;
|
||||
}
|
||||
`)
|
||||
)
|
||||
```
|
||||
|
||||
### Forced-colors Stylesheets
|
||||
FAST has a commitment to facilitating accessible web experiences and [forced-colors](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/forced-colors) support is a core tenant of that commitment. `@microsoft/fast-components` exports the `forcedColorsStylesheetBehavior` utility to provide a simple mechanism to apply forced-color stylesheets without bloating the component stylesheet in non-forced-color environments. This Behavior is built using [MatchMedia Stylesheets](#matchmedia-stylesheets).
|
||||
|
||||
__Example: Forced-colors stylesheets__
|
||||
```js
|
||||
import { forcedColorsStylesheetBehavior } from "@microsoft/fast-foundation";
|
||||
import { SystemColors } from "@microsoft/fast-web-utilities";
|
||||
const styles = css`
|
||||
/* ... */
|
||||
`.withBehaviors(
|
||||
forcedColorsStylesheetBehavior(css`
|
||||
:host {
|
||||
background: ${SystemColors.Canvas};
|
||||
color: ${SystemColors.CanvasText};
|
||||
}
|
||||
/* ... */
|
||||
`)
|
||||
)
|
||||
```
|
||||
|
||||
|
||||
|
|
@ -1,14 +1,4 @@
|
|||
---
|
||||
id: styling-components
|
||||
title: Styling Components
|
||||
sidebar_label: Styling Components
|
||||
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-foundation/docs/guide/styling-components.doc.md
|
||||
---
|
||||
## Applying CSS
|
||||
`@microsoft/fast-components` leverages `@microsoft/fast-element` to style components. For details on how to apply CSS, see [leveraging CSS](fast-element/leveraging-css.md).
|
||||
|
||||
## Design System
|
||||
In FAST, the *design system* is a collection of properties and values that inform the visual design language of the components. These properties are managed and provided through implementations of the [*DesignSystemProvider*](fast-foundation/fast-design-system-provider.md).
|
||||
|
||||
For the purposes of this section, just know the *DesignSystemProvider* is a Custom Element that will create CSS Custom Properties that can be consumed by component stylesheets and provide mechanisms to synchronize, update, and consume those properties programmatically.
|
||||
|
||||
|
|
@ -80,15 +70,4 @@ const styles = css`
|
|||
}
|
||||
`)
|
||||
)
|
||||
```
|
||||
|
||||
## Hiding Undefined Elements
|
||||
Custom Elements that have not been [upgraded](https://developers.google.com/web/fundamentals/web-components/customelements#upgrades) and don't have styles attached can still be rendered by the browser but they likely do not look how they are supposed to. To avoid a *flash of un-styled content* (FOUC), visually hide Custom Elements if they have not been *defined*:
|
||||
|
||||
```CSS
|
||||
:not(:defined) {
|
||||
visibility: hidden;
|
||||
}
|
||||
```
|
||||
|
||||
*Note, the consuming application must apply this, as the components themselves do not.*
|
||||
```
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
id: type-ramp
|
||||
title: Type ramp
|
||||
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-components/docs/guide/type-ramp.doc.md
|
||||
---
|
||||
|
||||
The FAST type ramp is exposed by the `FASTDesignSystemProvider` as CSS Custom Properties. It organizes the ramp around a _base_ font size and line-height, ascending and descending from the _base_. The CSS Custom Properties that can be used are:
|
||||
|
||||
| Level | Font Size | Line Height |
|
||||
|--------------------|---------------------------------|----------------------------------|
|
||||
| Minus 2 (smallest) | `--type-ramp-minus-2-font-size` | `--type-ramp-minus-2-line-height`|
|
||||
| Minus 1 | `--type-ramp-minus-1-font-size` | `--type-ramp-minus-1-line-height`|
|
||||
| Base (body) | `--type-ramp-base-font-size` | `--type-ramp-base-line-height` |
|
||||
| Plus 1 | `--type-ramp-plus-1-font-size` | `--type-ramp-plus-1-line-height` |
|
||||
| Plus 2 | `--type-ramp-plus-2-font-size` | `--type-ramp-plus-2-line-height` |
|
||||
| Plus 3 | `--type-ramp-plus-3-font-size` | `--type-ramp-plus-3-line-height` |
|
||||
| Plus 4 | `--type-ramp-plus-4-font-size` | `--type-ramp-plus-4-line-height` |
|
||||
| Plus 5 | `--type-ramp-plus-5-font-size` | `--type-ramp-plus-5-line-height` |
|
||||
| Plus 6 (largest) | `--type-ramp-plus-6-font-size` | `--type-ramp-plus-6-line-height` |
|
||||
|
|
@ -35,7 +35,17 @@ module.exports = {
|
|||
"fast-foundation/fast-text-field",
|
||||
],
|
||||
},
|
||||
"fast-foundation/styling-components",
|
||||
{
|
||||
type: "category",
|
||||
label: "Styling Components",
|
||||
items: [
|
||||
"fast-components/intro",
|
||||
"fast-components/design-system",
|
||||
"fast-components/type-ramp",
|
||||
"fast-components/color",
|
||||
"fast-components/match-media-stylesheets",
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "Integrations",
|
||||
|
|
|
|||
|
|
@ -51,12 +51,24 @@ function copyMarkdown() {
|
|||
const root = "./docs";
|
||||
const folder = identifyPackage(source);
|
||||
const dest = path.join(root, folder, filename);
|
||||
|
||||
fs.copyFile(source, dest, error => {
|
||||
if (error) {
|
||||
console.error(error);
|
||||
}
|
||||
});
|
||||
const copy = () => {
|
||||
fs.copyFile(source, dest, error => {
|
||||
if (error) {
|
||||
console.error(error);
|
||||
}
|
||||
});
|
||||
};
|
||||
if (fs.existsSync(dest)) {
|
||||
copy();
|
||||
} else {
|
||||
fs.mkdir(path.dirname(dest), { recursive: true }, error => {
|
||||
if (error) {
|
||||
console.error(error);
|
||||
} else {
|
||||
copy();
|
||||
}
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
// Copy component docs from fast-foundation.
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче