diff --git a/packages/web-components/fast-components/docs/api-report.md b/packages/web-components/fast-components/docs/api-report.md index bb0a625c2e0..538914b6e40 100644 --- a/packages/web-components/fast-components/docs/api-report.md +++ b/packages/web-components/fast-components/docs/api-report.md @@ -389,137 +389,73 @@ export const fastDesignSystemDefaults: FASTDesignSystem; // @public export class FASTDesignSystemProvider extends DesignSystemProvider implements FASTDesignSystem { accentBaseColor: string; - // (undocumented) accentFillActiveDelta: number; - // (undocumented) accentFillFocusDelta: number; - // (undocumented) accentFillHoverDelta: number; - // (undocumented) accentFillRestDelta: number; - // (undocumented) accentFillSelectedDelta: number; - // (undocumented) accentForegroundActiveDelta: number; - // (undocumented) accentForegroundFocusDelta: number; - // (undocumented) accentForegroundHoverDelta: number; - // (undocumented) accentForegroundRestDelta: number; accentPalette: string[]; backgroundColor: string; - // (undocumented) baseHeightMultiplier: number; - // (undocumented) baseHorizontalSpacingMultiplier: number; - // (undocumented) baseLayerLuminance: number; - // (undocumented) cornerRadius: number; - // (undocumented) density: 0; - // (undocumented) designUnit: number; - // (undocumented) direction: Direction; - // (undocumented) disabledOpacity: number; - // (undocumented) focusOutlineWidth: number; - // (undocumented) neutralDividerRestDelta: number; - // (undocumented) neutralFillActiveDelta: number; - // (undocumented) neutralFillCardDelta: number; - // (undocumented) neutralFillFocusDelta: number; - // (undocumented) neutralFillHoverDelta: number; - // (undocumented) neutralFillInputActiveDelta: number; - // (undocumented) neutralFillInputFocusDelta: number; - // (undocumented) neutralFillInputHoverDelta: number; - // (undocumented) neutralFillInputRestDelta: number; - // (undocumented) neutralFillInputSelectedDelta: number; - // (undocumented) neutralFillRestDelta: number; - // (undocumented) neutralFillSelectedDelta: number; - // (undocumented) neutralFillStealthActiveDelta: number; - // (undocumented) neutralFillStealthFocusDelta: number; - // (undocumented) neutralFillStealthHoverDelta: number; - // (undocumented) neutralFillStealthRestDelta: number; - // (undocumented) neutralFillStealthSelectedDelta: number; - // (undocumented) neutralFillToggleActiveDelta: number; - // (undocumented) neutralFillToggleFocusDelta: number; - // (undocumented) neutralFillToggleHoverDelta: number; - // (undocumented) neutralForegroundActiveDelta: number; - // (undocumented) neutralForegroundFocusDelta: number; - // (undocumented) neutralForegroundHoverDelta: number; - // (undocumented) neutralOutlineActiveDelta: number; - // (undocumented) neutralOutlineFocusDelta: number; - // (undocumented) neutralOutlineHoverDelta: number; - // (undocumented) neutralOutlineRestDelta: number; neutralPalette: string[]; noPaint: boolean; - // (undocumented) outlineWidth: number; - // (undocumented) typeRampBaseFontSize: string; - // (undocumented) typeRampBaseLineHeight: string; - // (undocumented) typeRampMinus1FontSize: string; - // (undocumented) typeRampMinus1LineHeight: string; - // (undocumented) typeRampMinus2FontSize: string; - // (undocumented) typeRampMinus2LineHeight: string; - // (undocumented) typeRampPlus1FontSize: string; - // (undocumented) typeRampPlus1LineHeight: string; - // (undocumented) typeRampPlus2FontSize: string; - // (undocumented) typeRampPlus2LineHeight: string; - // (undocumented) typeRampPlus3FontSize: string; - // (undocumented) typeRampPlus3LineHeight: string; - // (undocumented) typeRampPlus4FontSize: string; - // (undocumented) typeRampPlus4LineHeight: string; - // (undocumented) typeRampPlus5FontSize: string; - // (undocumented) typeRampPlus5LineHeight: string; - // (undocumented) typeRampPlus6FontSize: string; - // (undocumented) typeRampPlus6LineHeight: string; } @@ -711,6 +647,9 @@ export const neutralFillInputRestBehavior: import("@microsoft/fast-foundation"). // @internal (undocumented) export const neutralFillInputSelected: ColorRecipe; +// @public +export const neutralFillInputSelectedBehavior: import("@microsoft/fast-foundation").CSSCustomPropertyBehavior; + // Warning: (ae-internal-missing-underscore) The name "neutralFillRest" should be prefixed with an underscore because the declaration is marked as @internal // // @internal (undocumented) diff --git a/packages/web-components/fast-components/docs/design/design-system.md b/packages/web-components/fast-components/docs/design/design-system.md deleted file mode 100644 index dd59bbf96cf..00000000000 --- a/packages/web-components/fast-components/docs/design/design-system.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -id: design-system -title: Design System -custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-components/docs/design/design-system.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*](/docs/components/design-system-provider). - -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. | diff --git a/packages/web-components/fast-components/docs/design/type-ramp.md b/packages/web-components/fast-components/docs/design/type-ramp.md deleted file mode 100644 index 6466c3651e8..00000000000 --- a/packages/web-components/fast-components/docs/design/type-ramp.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -id: type-ramp -title: Type ramp -custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-components/docs/design/type-ramp.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` | diff --git a/packages/web-components/fast-components/src/design-system-provider/index.ts b/packages/web-components/fast-components/src/design-system-provider/index.ts index d65522fdbce..27d0d36a8e3 100644 --- a/packages/web-components/fast-components/src/design-system-provider/index.ts +++ b/packages/web-components/fast-components/src/design-system-provider/index.ts @@ -46,7 +46,7 @@ export class FASTDesignSystemProvider extends DesignSystemProvider * background-color and color properties * * @remarks - * HTML boolean boolean attribute: no-paint + * HTML boolean attribute: no-paint */ @attr({ attribute: "no-paint", mode: "boolean" }) public noPaint = false; @@ -60,6 +60,10 @@ export class FASTDesignSystemProvider extends DesignSystemProvider /** * Define design system property attributes + * @remarks + * HTML attribute: background-color + * + * CSS custom property: --background-color */ @designSystemProperty({ attribute: "background-color", @@ -73,8 +77,13 @@ export class FASTDesignSystemProvider extends DesignSystemProvider } /** - * This color is intended to be the *source color* of the FASTDesignSystem.accentPalette. - * When setting this value, you should be sure to *also* update the FASTDesignSystem.accentPalette. + * This color is intended to be the *source color* of the {@link FASTDesignSystemProvider.accentPalette|accentPalette}. + * When setting this value, you should be sure to *also* update the {@link FASTDesignSystemProvider.accentPalette|accentPalette}. + * + * @remarks + * HTML attribute: accent-base-color + * + * CSS custom property: N/A */ @designSystemProperty({ attribute: "accent-base-color", @@ -86,6 +95,11 @@ export class FASTDesignSystemProvider extends DesignSystemProvider /** * Defines the palette that all neutral color recipes are derived from. * This is an array for hexadecimal color strings ordered from light to dark. + * + * @remarks + * HTML attribute: N/A + * + * CSS custom property: N/A */ @designSystemProperty({ attribute: false, @@ -98,8 +112,13 @@ export class FASTDesignSystemProvider extends DesignSystemProvider * Defines the palette that all accent color recipes are derived from. * This is an array for hexadecimal color strings ordered from light to dark. * - * When setting this property, be sure to *also* set FASTDesignSystem.accentBaseColor to + * When setting this property, be sure to *also* set {@link FASTDesignSystemProvider.accentBaseColor|accentBaseColor} to * the base color deriving this palette. + * + * @remarks + * HTML attribute: N/A + * + * CSS custom property: N/A */ @designSystemProperty({ attribute: false, @@ -108,12 +127,29 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public accentPalette: string[]; + /** + * + * The density offset, used with designUnit to calculate height and spacing. + * + * @remarks + * HTML attribute: density + * + * CSS custom property: --density + */ @designSystemProperty({ default: fastDesignSystemDefaults.density, converter: nullableNumberConverter, }) public density: 0; + /** + * The grid-unit that UI dimensions are derived from in pixels. + * + * @remarks + * HTML attribute: design-unit + * + * CSS custom property: --design-unit + */ @designSystemProperty({ attribute: "design-unit", converter: nullableNumberConverter, @@ -121,6 +157,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public designUnit: number; + /** + * The primary document direction. + * + * @remarks + * HTML attribute: direction + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "direction", cssCustomProperty: false, @@ -128,6 +172,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public direction: Direction; + /** + * The number of designUnits used for component height at the base density. + * + * @remarks + * HTML attribute: base-height-multiplier + * + * CSS custom property: --base-height-multiplier + */ @designSystemProperty({ attribute: "base-height-multiplier", default: fastDesignSystemDefaults.baseHeightMultiplier, @@ -135,6 +187,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public baseHeightMultiplier: number; + /** + * The number of designUnits used for horizontal spacing at the base density. + * + * @remarks + * HTML attribute: base-horizontal-spacing-multiplier + * + * CSS custom property: --base-horizontal-spacing-multiplier + */ @designSystemProperty({ attribute: "base-horizontal-spacing-multiplier", converter: nullableNumberConverter, @@ -142,6 +202,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public baseHorizontalSpacingMultiplier: number; + /** + * The corner radius applied to controls. + * + * @remarks + * HTML attribute: corner-radius + * + * CSS custom property: --corner-radius + */ @designSystemProperty({ attribute: "corner-radius", converter: nullableNumberConverter, @@ -149,6 +217,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public cornerRadius: number; + /** + * The width of the standard outline applied to outline components in pixels. + * + * @remarks + * HTML attribute: outline-width + * + * CSS custom property: --outline-width + */ @designSystemProperty({ attribute: "outline-width", converter: nullableNumberConverter, @@ -156,6 +232,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public outlineWidth: number; + /** + * The width of the standard focus outline in pixels. + * + * @remarks + * HTML attribute: focus-outline-width + * + * CSS custom property: --focus-outline-width + */ @designSystemProperty({ attribute: "focus-outline-width", converter: nullableNumberConverter, @@ -163,6 +247,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public focusOutlineWidth: number; + /** + * The opacity of a disabled control. + * + * @remarks + * HTML attribute: disabled-opacity + * + * CSS custom property: --disabled-opacity + */ @designSystemProperty({ attribute: "disabled-opacity", converter: nullableNumberConverter, @@ -170,114 +262,266 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public disabledOpacity: number; + /** + * The font-size two steps below the base font-size + * + * @remarks + * HTML attribute: type-ramp-minus-2-font-size + * + * CSS custom property: --type-ramp-minus-2-font-size + */ @designSystemProperty({ attribute: "type-ramp-minus-2-font-size", default: fastDesignSystemDefaults.typeRampMinus2FontSize, }) public typeRampMinus2FontSize: string; + /** + * The line-height two steps below the base line-height + * + * @remarks + * HTML attribute: type-ramp-minus-2-line-height + * + * CSS custom property: --type-ramp-minus-2-line-height + */ @designSystemProperty({ attribute: "type-ramp-minus-2-line-height", default: fastDesignSystemDefaults.typeRampMinus2LineHeight, }) public typeRampMinus2LineHeight: string; + /** + * The font-size one step below the base font-size + * + * @remarks + * HTML attribute: type-ramp-minus-1-font-size + * + * CSS custom property: --type-ramp-minus-1-font-size + */ @designSystemProperty({ attribute: "type-ramp-minus-1-font-size", default: fastDesignSystemDefaults.typeRampMinus1FontSize, }) public typeRampMinus1FontSize: string; + /** + * The line-height one step below the base line-height + * + * @remarks + * HTML attribute: type-ramp-minus-1-line-height + * + * CSS custom property: --type-ramp-minus-1-line-height + */ @designSystemProperty({ attribute: "type-ramp-minus-1-line-height", default: fastDesignSystemDefaults.typeRampMinus1LineHeight, }) public typeRampMinus1LineHeight: string; + /** + * The base font-size of the relative type-ramp scale + * + * @remarks + * HTML attribute: type-ramp-base-font-size + * + * CSS custom property: --type-ramp-base-font-size + */ @designSystemProperty({ attribute: "type-ramp-base-font-size", default: fastDesignSystemDefaults.typeRampBaseFontSize, }) public typeRampBaseFontSize: string; + /** + * The base line-height of the relative type-ramp scale + * + * @remarks + * HTML attribute: type-ramp-base-line-height + * + * CSS custom property: --type-ramp-base-line-height + */ @designSystemProperty({ attribute: "type-ramp-base-line-height", default: fastDesignSystemDefaults.typeRampBaseLineHeight, }) public typeRampBaseLineHeight: string; + /** + * The font-size one step above the base font-size + * + * @remarks + * HTML attribute: type-ramp-plus-1-font-size + * + * CSS custom property: --type-ramp-plus-1-font-size + */ @designSystemProperty({ attribute: "type-ramp-plus-1-font-size", default: fastDesignSystemDefaults.typeRampPlus1FontSize, }) public typeRampPlus1FontSize: string; + /** + * The line-height one step above the base line-height + * + * @remarks + * HTML attribute: type-ramp-plus-1-line-height + * + * CSS custom property: --type-ramp-plus-1-line-height + */ @designSystemProperty({ attribute: "type-ramp-plus-1-line-height", default: fastDesignSystemDefaults.typeRampPlus1LineHeight, }) public typeRampPlus1LineHeight: string; + /** + * The font-size two steps above the base font-size + * + * @remarks + * HTML attribute: type-ramp-plus-2-font-size + * + * CSS custom property: --type-ramp-plus-2-font-size + */ @designSystemProperty({ attribute: "type-ramp-plus-2-font-size", default: fastDesignSystemDefaults.typeRampPlus2FontSize, }) public typeRampPlus2FontSize: string; + /** + * The line-height two steps above the base line-height + * + * @remarks + * HTML attribute: type-ramp-plus-2-line-height + * + * CSS custom property: --type-ramp-plus-2-line-height + */ @designSystemProperty({ attribute: "type-ramp-plus-2-line-height", default: fastDesignSystemDefaults.typeRampPlus2LineHeight, }) public typeRampPlus2LineHeight: string; + /** + * The font-size three steps above the base font-size + * + * @remarks + * HTML attribute: type-ramp-plus-3-font-size + * + * CSS custom property: --type-ramp-plus-3-font-size + */ @designSystemProperty({ attribute: "type-ramp-plus-3-font-size", default: fastDesignSystemDefaults.typeRampPlus3FontSize, }) public typeRampPlus3FontSize: string; + /** + * The line-height three steps above the base line-height + * + * @remarks + * HTML attribute: type-ramp-plus-3-line-height + * + * CSS custom property: --type-ramp-plus-3-line-height + */ @designSystemProperty({ attribute: "type-ramp-plus-3-line-height", default: fastDesignSystemDefaults.typeRampPlus3LineHeight, }) public typeRampPlus3LineHeight: string; + /** + * The font-size four steps above the base font-size + * + * @remarks + * HTML attribute: type-ramp-plus-4-font-size + * + * CSS custom property: --type-ramp-plus-4-font-size + */ @designSystemProperty({ attribute: "type-ramp-plus-4-font-size", default: fastDesignSystemDefaults.typeRampPlus4FontSize, }) public typeRampPlus4FontSize: string; + /** + * The line-height four steps above the base line-height + * + * @remarks + * HTML attribute: type-ramp-plus-4-line-height + * + * CSS custom property: --type-ramp-plus-4-line-height + */ @designSystemProperty({ attribute: "type-ramp-plus-4-line-height", default: fastDesignSystemDefaults.typeRampPlus4LineHeight, }) public typeRampPlus4LineHeight: string; + /** + * The font-size five steps above the base font-size + * + * @remarks + * HTML attribute: type-ramp-plus-5-font-size + * + * CSS custom property: --type-ramp-plus-5-font-size + */ @designSystemProperty({ attribute: "type-ramp-plus-5-font-size", default: fastDesignSystemDefaults.typeRampPlus5FontSize, }) public typeRampPlus5FontSize: string; + /** + * The line-height five steps above the base line-height + * + * @remarks + * HTML attribute: type-ramp-plus-5-line-height + * + * CSS custom property: --type-ramp-plus-5-line-height + */ @designSystemProperty({ attribute: "type-ramp-plus-5-line-height", default: fastDesignSystemDefaults.typeRampPlus5LineHeight, }) public typeRampPlus5LineHeight: string; + /** + * The font-size six steps above the base font-size + * + * @remarks + * HTML attribute: type-ramp-plus-6-font-size + * + * CSS custom property: --type-ramp-plus-6-font-size + */ @designSystemProperty({ attribute: "type-ramp-plus-6-font-size", default: fastDesignSystemDefaults.typeRampPlus6FontSize, }) public typeRampPlus6FontSize: string; + /** + * The line-height six steps above the base line-height + * + * @remarks + * HTML attribute: type-ramp-plus-6-line-height + * + * CSS custom property: --type-ramp-plus-6-line-height + */ @designSystemProperty({ attribute: "type-ramp-plus-6-line-height", default: fastDesignSystemDefaults.typeRampPlus6LineHeight, }) public typeRampPlus6LineHeight: string; + /** + * The distance from the resolved accent fill color for the rest state of the accent-fill recipe. See {@link @microsoft/fast-components#accentFillRestBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: accent-fill-rest-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "accent-fill-rest-delta", converter: nullableNumberConverter, @@ -286,6 +530,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public accentFillRestDelta: number; + /** + * The distance from the resolved accent fill color for the hover state of the accent-fill recipe. See {@link @microsoft/fast-components#accentFillHoverBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: accent-fill-hover-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "accent-fill-hover-delta", cssCustomProperty: false, @@ -294,6 +546,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public accentFillHoverDelta: number; + /** + * The distance from the resolved accent fill color for the active state of the accent-fill recipe. See {@link @microsoft/fast-components#accentFillActiveBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: accent-fill-active-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "accent-fill-active-delta", cssCustomProperty: false, @@ -302,6 +562,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public accentFillActiveDelta: number; + /** + * The distance from the resolved accent fill color for the focus state of the accent-fill recipe. See {@link @microsoft/fast-components#accentFillFocusBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: accent-fill-focus-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "accent-fill-focus-delta", converter: nullableNumberConverter, @@ -310,6 +578,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public accentFillFocusDelta: number; + /** + * The distance from the resolved accent fill color for the selected state of the accent-fill recipe. See {@link @microsoft/fast-components#accentFillSelectedBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: accent-fill-selected-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "accent-fill-selected-delta", converter: nullableNumberConverter, @@ -318,6 +594,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public accentFillSelectedDelta: number; + /** + * The distance from the resolved accent foreground color for the rest state of the accent-foreground recipe. See {@link @microsoft/fast-components#accentForegroundRestBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: accent-foreground-rest-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "accent-foreground-rest-delta", converter: nullableNumberConverter, @@ -326,6 +610,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public accentForegroundRestDelta: number; + /** + * The distance from the resolved accent foreground color for the hover state of the accent-foreground recipe. See {@link @microsoft/fast-components#accentForegroundHoverBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: accent-foreground-hover-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "accent-foreground-hover-delta", converter: nullableNumberConverter, @@ -334,6 +626,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public accentForegroundHoverDelta: number; + /** + * The distance from the resolved accent foreground color for the active state of the accent-foreground recipe. See {@link @microsoft/fast-components#accentForegroundActiveBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: accent-foreground-active-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "accent-foreground-active-delta", converter: nullableNumberConverter, @@ -342,6 +642,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public accentForegroundActiveDelta: number; + /** + * The distance from the resolved accent foreground color for the focus state of the accent-foreground recipe. See {@link @microsoft/fast-components#accentForegroundFocusBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: accent-foreground-focus-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "accent-foreground-focus-delta", converter: nullableNumberConverter, @@ -350,6 +658,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public accentForegroundFocusDelta: number; + /** + * The distance from the resolved neutral fill color for the rest state of the neutral-fill recipe. See {@link @microsoft/fast-components#neutralFillRestBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-rest-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-rest-delta", converter: nullableNumberConverter, @@ -358,6 +674,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillRestDelta: number; + /** + * The distance from the resolved neutral fill color for the hover state of the neutral-fill recipe. See {@link @microsoft/fast-components#neutralFillHoverBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-hover-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-hover-delta", converter: nullableNumberConverter, @@ -366,6 +690,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillHoverDelta: number; + /** + * The distance from the resolved neutral fill color for the active state of the neutral-fill recipe. See {@link @microsoft/fast-components#neutralFillActiveBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-active-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-active-delta", converter: nullableNumberConverter, @@ -374,6 +706,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillActiveDelta: number; + /** + * The distance from the resolved neutral fill color for the focus state of the neutral-fill recipe. See {@link @microsoft/fast-components#neutralFillFocusBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-focus-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-focus-delta", converter: nullableNumberConverter, @@ -382,6 +722,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillFocusDelta: number; + /** + * The distance from the resolved neutral fill color for the selected state of the neutral-fill recipe. See {@link @microsoft/fast-components#neutralFillSelectedBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-selected-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-selected-delta", converter: nullableNumberConverter, @@ -390,6 +738,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillSelectedDelta: number; + /** + * The distance from the resolved neutral fill input color for the rest state of the neutral-fill-input recipe. See {@link @microsoft/fast-components#neutralFillInputRestBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-input-rest-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-input-rest-delta", converter: nullableNumberConverter, @@ -398,6 +754,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillInputRestDelta: number; + /** + * The distance from the resolved neutral fill input color for the hover state of the neutral-fill-input recipe. See {@link @microsoft/fast-components#neutralFillInputHoverBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-input-hover-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-input-hover-delta", converter: nullableNumberConverter, @@ -406,6 +770,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillInputHoverDelta: number; + /** + * The distance from the resolved neutral fill input color for the active state of the neutral-fill-input recipe. See {@link @microsoft/fast-components#neutralFillInputActiveBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-input-active-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-input-active-delta", converter: nullableNumberConverter, @@ -414,6 +786,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillInputActiveDelta: number; + /** + * The distance from the resolved neutral fill input color for the focus state of the neutral-fill-input recipe. See {@link @microsoft/fast-components#neutralFillInputFocusBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-input-focus-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-input-focus-delta", converter: nullableNumberConverter, @@ -422,6 +802,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillInputFocusDelta: number; + /** + * The distance from the resolved neutral fill input color for the selected state of the neutral-fill-input recipe. See {@link @microsoft/fast-components#neutralFillInputSelectedBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-input-selected-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-input-selected-delta", converter: nullableNumberConverter, @@ -430,6 +818,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillInputSelectedDelta: number; + /** + * The distance from the resolved neutral fill stealth color for the rest state of the neutral-fill-stealth recipe. See {@link @microsoft/fast-components#neutralFillStealthRestBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-stealth-rest-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-stealth-rest-delta", converter: nullableNumberConverter, @@ -438,6 +834,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillStealthRestDelta: number; + /** + * The distance from the resolved neutral fill stealth color for the hover state of the neutral-fill-stealth recipe. See {@link @microsoft/fast-components#neutralFillStealthHoverBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-stealth-hover-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-stealth-hover-delta", converter: nullableNumberConverter, @@ -446,6 +850,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillStealthHoverDelta: number; + /** + * The distance from the resolved neutral fill stealth color for the active state of the neutral-fill-stealth recipe. See {@link @microsoft/fast-components#neutralFillStealthActiveBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-stealth-active-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-stealth-active-delta", converter: nullableNumberConverter, @@ -454,6 +866,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillStealthActiveDelta: number; + /** + * The distance from the resolved neutral fill stealth color for the focus state of the neutral-fill-stealth recipe. See {@link @microsoft/fast-components#neutralFillStealthFocusBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-stealth-focus-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-stealth-focus-delta", converter: nullableNumberConverter, @@ -462,6 +882,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillStealthFocusDelta: number; + /** + * The distance from the resolved neutral fill stealth color for the selected state of the neutral-fill-stealth recipe. See {@link @microsoft/fast-components#neutralFillStealthSelectedBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-stealth-selected-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-stealth-selected-delta", converter: nullableNumberConverter, @@ -470,6 +898,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillStealthSelectedDelta: number; + /** + * The distance from the resolved neutral fill toggle color for the hover state of the neutral-fill-toggle recipe. See {@link @microsoft/fast-components#neutralFillToggleHoverBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-toggle-hover-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-toggle-hover-delta", converter: nullableNumberConverter, @@ -478,22 +914,48 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillToggleHoverDelta: number; + /** + * The distance from the resolved neutral fill toggle color for the active state of the neutral-fill-toggle recipe. See {@link @microsoft/fast-components#neutralFillToggleActiveBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-toggle-active-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ - attribute: "neutral-fill-toggle-hover-active", + attribute: "neutral-fill-toggle-active-delta", converter: nullableNumberConverter, cssCustomProperty: false, default: fastDesignSystemDefaults.neutralFillToggleActiveDelta, }) public neutralFillToggleActiveDelta: number; + /** + * The distance from the resolved neutral fill toggle color for the focus state of the neutral-fill-toggle recipe. See {@link @microsoft/fast-components#neutralFillToggleFocusBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-toggle-focus-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ - attribute: "neutral-fill-toggle-hover-focus", + attribute: "neutral-fill-toggle-focus-delta", converter: nullableNumberConverter, cssCustomProperty: false, default: fastDesignSystemDefaults.neutralFillToggleFocusDelta, }) public neutralFillToggleFocusDelta: number; + /** + * The {@link https://www.w3.org/WAI/GL/wiki/Relative_luminance#:~:text=WCAG%20definition%20of%20relative%20luminance,and%201%20for%20lightest%20white|relative luminance} of the base layer of the application. + * + * @remarks + * When set to a number between 0 and 1, this values controls the output of {@link @microsoft/fast-components#neutralLayerCardBehavior}, {@link @microsoft/fast-components#neutralLayerCardContainerBehavior}, {@link @microsoft/fast-components#neutralLayerFloatingBehavior}, {@link @microsoft/fast-components#neutralLayerL1AltBehavior}, {@link @microsoft/fast-components#neutralLayerL1Behavior}, {@link @microsoft/fast-components#neutralLayerL2Behavior}, {@link @microsoft/fast-components#neutralLayerL3Behavior}, {@link @microsoft/fast-components#neutralLayerL4Behavior}. + * + * HTML attribute: base-layer-luminance + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "base-layer-luminance", converter: nullableNumberConverter, @@ -502,6 +964,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public baseLayerLuminance: number; // 0...1 + /** + * The distance from the background-color to resolve the card background. See {@link @microsoft/fast-components#neutralFillCardRestBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-fill-card-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-fill-card-delta", converter: nullableNumberConverter, @@ -510,6 +980,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralFillCardDelta: number; + /** + * The distance from the resolved neutral foreground color for the hover state of the neutral-foreground recipe. See {@link @microsoft/fast-components#neutralForegroundHoverBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-foreground-hover-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-foreground-hover-delta", converter: nullableNumberConverter, @@ -518,6 +996,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralForegroundHoverDelta: number; + /** + * The distance from the resolved neutral foreground color for the active state of the neutral-foreground recipe. See {@link @microsoft/fast-components#neutralForegroundActiveBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-foreground-active-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-foreground-active-delta", converter: nullableNumberConverter, @@ -526,6 +1012,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralForegroundActiveDelta: number; + /** + * The distance from the resolved neutral foreground color for the focus state of the neutral-foreground recipe. See {@link @microsoft/fast-components#neutralForegroundFocusBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-foreground-focus-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-foreground-focus-delta", converter: nullableNumberConverter, @@ -534,6 +1028,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralForegroundFocusDelta: number; + /** + * The distance from the resolved neutral divider color for the rest state of the neutral-foreground recipe. See {@link @microsoft/fast-components#neutralDividerRestBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-divider-rest-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-divider-rest-delta", converter: nullableNumberConverter, @@ -542,6 +1044,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralDividerRestDelta: number; + /** + * The distance from the resolved neutral outline color for the rest state of the neutral-outline recipe. See {@link @microsoft/fast-components#neutralOutlineRestBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-outline-rest-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-outline-rest-delta", converter: nullableNumberConverter, @@ -550,6 +1060,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralOutlineRestDelta: number; + /** + * The distance from the resolved neutral outline color for the hover state of the neutral-outline recipe. See {@link @microsoft/fast-components#neutralOutlineHoverBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-outline-hover-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-outline-hover-delta", converter: nullableNumberConverter, @@ -558,6 +1076,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralOutlineHoverDelta: number; + /** + * The distance from the resolved neutral outline color for the active state of the neutral-outline recipe. See {@link @microsoft/fast-components#neutralOutlineActiveBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-outline-active-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-outline-active-delta", converter: nullableNumberConverter, @@ -566,6 +1092,14 @@ export class FASTDesignSystemProvider extends DesignSystemProvider }) public neutralOutlineActiveDelta: number; + /** + * The distance from the resolved neutral outline color for the focus state of the neutral-outline recipe. See {@link @microsoft/fast-components#neutralOutlineFocusBehavior} for usage in CSS. + * + * @remarks + * HTML attribute: neutral-outline-focus-delta + * + * CSS custom property: N/A + */ @designSystemProperty({ attribute: "neutral-outline-focus-delta", converter: nullableNumberConverter, diff --git a/packages/web-components/fast-components/src/fast-design-system.ts b/packages/web-components/fast-components/src/fast-design-system.ts index 160b022b288..da4cc670779 100644 --- a/packages/web-components/fast-components/src/fast-design-system.ts +++ b/packages/web-components/fast-components/src/fast-design-system.ts @@ -89,17 +89,17 @@ export interface FASTDesignSystem { cornerRadius: number; /** - * The width of the outline applied to outline components in pixels. + * The width of the standard outline applied to outline components in pixels. */ outlineWidth: number; /** - * The width of the outline for focus state in pixels. + * The width of the standard focus outline in pixels. */ focusOutlineWidth: number; /** - * The opacity to use for disabled component state. + * The opacity of a disabled control. */ disabledOpacity: number; diff --git a/packages/web-components/fast-components/src/styles/recipes.ts b/packages/web-components/fast-components/src/styles/recipes.ts index df41ffafdc5..b9f9668e84c 100644 --- a/packages/web-components/fast-components/src/styles/recipes.ts +++ b/packages/web-components/fast-components/src/styles/recipes.ts @@ -337,6 +337,15 @@ export const neutralFillInputActiveBehavior = cssCustomPropertyBehaviorFactory( x => neutralFillInput(x).active, FASTDesignSystemProvider.findProvider ); +/** + * Behavior to resolve and make available the neutral-fill-input-selected CSS custom property. + * @public + */ +export const neutralFillInputSelectedBehavior = cssCustomPropertyBehaviorFactory( + "neutral-fill-input-selected", + x => neutralFillInput(x).selected, + FASTDesignSystemProvider.findProvider +); /** * Behavior to resolve and make available the neutral-fill-input-focus CSS custom property. * @public diff --git a/packages/web-components/fast-foundation/docs/api-report.md b/packages/web-components/fast-foundation/docs/api-report.md index f1760efdb54..43a0668ca74 100644 --- a/packages/web-components/fast-foundation/docs/api-report.md +++ b/packages/web-components/fast-foundation/docs/api-report.md @@ -223,6 +223,9 @@ export interface DecoratorDesignSystemPropertyConfiguration extends Omit(providerCtor: T) => void; + // @public export class DelegatesARIAButton extends ARIAGlobalStatesAndProperties { ariaExpanded: "true" | "false" | undefined; @@ -275,8 +278,10 @@ export class DesignSystemProvider extends FASTElement implements CSSCustomProper useDefaults: boolean; } -// @public -export function designSystemProvider(nameOrDef: string | PartialFASTElementDefinition): (providerCtor: T) => void; +// Warning: (ae-internal-missing-underscore) The name "designSystemProvider" should be prefixed with an underscore because the declaration is marked as @internal +// +// @internal @deprecated (undocumented) +export const designSystemProvider: typeof defineDesignSystemProvider; // @public export const DesignSystemProviderTemplate: import("@microsoft/fast-element").ViewTemplate; diff --git a/packages/web-components/fast-foundation/src/design-system-provider/README.md b/packages/web-components/fast-foundation/src/design-system-provider/README.md deleted file mode 100644 index 24a8d7fa519..00000000000 --- a/packages/web-components/fast-foundation/src/design-system-provider/README.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -id: design-system-provider -title: fast-design-system-provider -sidebar_label: design-system-provider -custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-foundation/src/design-system-provider/README.md ---- - -## What is a design system? - -The _design system_ can generally be thought of as a collection of named values that inform visual rendering. It quantifies concepts such as type-ramp, color palettes, design units, etc to be used in UI components. Other common names for this concept are _design variables_, _design tokens_ or _theme_. - -These values are mutable throughout a UI tree. Where UI tree _A_ may see their contextual _design-unit_ as `4px`, tree _B_ may have its scale increased by providing a _design-unit_ of `6px`. Or, tree _C_ may see a contextual _background color_ of `#FFF` where tree _D_ may see a contextual _background color_ as `#000`. - -## Design system provider - -A _design system_ isn't much use without convenient mechanisms to surface the _design system_ values to UI components and change values where desired. This is where the _Design System Provider_ comes in. `@microsoft/fast-components` exports the `FASTDesignSystemProvider` Web Components to help with: - -1. Declaring _design system_ properties and default values. -2. Surfacing _design system_ values as [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*). -3. Surfacing the _design system_ as a JavaScript object accessible on the Custom Element. -4. Facilitate _design system_ composition in _document order_. -5. Registering CSS Custom Property definitions to create arbitrary CSS Custom Properties as a function of the _design system_. - -### FAST design system provider - -The easiest way to get up-and-running is to use the `FASTDesignSystemProvider`. This Web Component is an implementation of the `DesignSystemProvider` that is configured with _design system_ properties used by the Web Components in the `@microsoft/fast-components` library. - -**EXAMPLE: Using the FASTDesignSystemProvider** - -```js -import { FASTDesignSystemProvider } from "@microsoft/fast-components"; -``` - -```html - - Hello World - -``` - -_Design system_ properties can be overridden by setting the property or attribute on the `fast-design-system-provider`. See [FAST Design System Properties](#FAST-Design-System-Properties) for a comprehensive list of properties. - -**EXAMPLE: Setting design system properties** - -```html - - Hello world! - -``` - -### `use-defaults` - -In general, a _Design System Provider_ element with the `use-defaults` attribute should exist as an ancestor to all rendered UI - this will ensure that all the values enumerated in the _design system_ are expressed as _CSS custom properties_. - -Notice below that none of the code-samples initialize a value to a declared _design system_ property. This is because the _design system_ is designed to function as a waterfall of values - where values assigned lower in the DOM tree override values defined by ancestors. Initializing the value on the instance assigns the value to every instance of the _Design System Provider_ which is generally un-desired. - -**EXAMPLE: initialized vs non-initialized properties** - -```ts -class ExampleClass { - public nonInitialized; - // vs - public initialized = true; -} -``` - -The `use-defaults` boolean attribute exposes a mechanism to apply the default values to an element while still allowing nested design system elements to intentionally override specific values. For details on how to set default values, see [Declaring Design System Properties](#Declaring-Design-System-Properties) - -### Composing design system providers - -*Design System Providers* are designed to compose their values with ancestor *Design System Providers* to facilitate changing values for decedents of the provider. - -```html - -

4px

-

#FFFFFF

- - -

8px

-

#FFFFFF

- - -``` - - -### Recipes - -There are some things that CSS just can't do. Advanced math, array manipulation, and conditionals are simply not possible with today's CSS. - -To address this gap, the _DesignSystemProvider_ is capable of registering `CSSCustomPropertyDefinition` types through the `registerCSSCustomProperty` method: - -**EXAMPLE: Register a CSS custom property that is a function of the _design system_** - -```ts -DesignSystemProvider.registerCSSCustomProperty({ - name: "design-unit-12th", - value: designSystem => Math.pow(designSystem.designUnit, 12), -}); -``` - -In the above example, the value function will be re-evaluated if the _design system_ ever changes. - -The above API is made especially useful when defining a [component stylesheet](https://github.com/microsoft/fast/blob/master/packages/web-components/fast-element/docs/building-components.md#defining-css) - individual stylesheets can declare dependencies on CSS custom properties that are functions of the element instance's *design system*. - -**EXAMPLE: creating a recipe dependency** -```ts -import { css } from "@microsoft/fast-element"; -import { cssCustomPropertyBehaviorFactory, FASTDesignSystemProvider } from "@microsoft/fast-components"; - -const styles = css` - :host { - height: var(--fancy-height); - } -`.withBehaviors( - cssCustomPropertyBehaviorFactory( - "fancy-height", - designSystem => Math.pow(designSystem.designUnit, 12), - FASTDesignSystemProvider.findProvider - ) -) -``` - -### Creating a design system provider - -To create a new _Design System Provider_, extend the `DesignSystemProvider` class and decorate it with the `@designSystemProvider` decorator, providing the decorator the element _tag name_ you wish to use: - -**EXAMPLE: Creating a custom Design System Provider** - -```ts -import { DesignSystemProvider, designSystemProvider, DesignSystemProviderTemplate as template } from "@microsoft/fast-foundation"; -import { MyDesignSystemProviderStyles as styles} from "../design-system-provider.styles.ts"; - -@designSystemProvider({name: "fancy-design-system-provider", template, styles}) -class FancyDesignSystemProvider extends DesignSystemProvider {} -``` - -```html - - Hello Fancy World! - -``` - -#### Declaring design system properties - -Building off the above, _design system_ properties can be declared using the `@designSystemProperty` decorator. - -**EXAMPLE: Creating a design system property declaration** - -```ts -// .. -@designSystemProvider({name: "fancy-design-system-provider", template, styles}) -class FancyDesignSystemProvider extends DesignSystemProvider { - @attr({attribute: "fancy-property"}) - @designSystemProperty({ cssCustomProperty: "fancy-property", default: "red" }) - public fancyProperty; -} -``` - -```html - -

Red text!

- -``` - -Declaring a _design system_ property will do several things. By default, the property name being decorated will become a CSS custom property when the value is set. This name can be customized by setting `cssCustomProperty` on the provided config object. - -```ts -// Will create a CSS custom property accessible by `var(--fooBar)` -@designSystemProperty({default: "foo"}) -public fooBar; -``` - -```ts -// Will create a CSS custom property accessible by `var(--foo-bar)` -@designSystemProperty({default: "foo", cssCustomProperty: "foo-bar"}) -public fooBar; -``` - -Additionally, creation of CSS custom properties can also be disabled by setting `cssCustomProperty` to `false`; - -```ts -// No CSS custom property will be created -@designSystemProperty({default: "foo", cssCustomProperty: false}) -public fooBar; -``` - -The default value _must_ be set through the `default` property on the supplied config. This is the value that will be applied when the `use-defaults` attribute is used and no override property is provided. \ No newline at end of file diff --git a/packages/web-components/fast-foundation/src/design-system-provider/design-system-provider.ts b/packages/web-components/fast-foundation/src/design-system-provider/design-system-provider.ts index 4d5efcc7d05..5751027aca5 100644 --- a/packages/web-components/fast-foundation/src/design-system-provider/design-system-provider.ts +++ b/packages/web-components/fast-foundation/src/design-system-provider/design-system-provider.ts @@ -497,7 +497,9 @@ export class DesignSystemProvider extends FASTElement * @param nameOrDef - the name or {@link @microsoft/fast-element#PartialFASTElementDefinition | element definition} * @public */ -export function designSystemProvider(nameOrDef: string | PartialFASTElementDefinition) { +export function defineDesignSystemProvider( + nameOrDef: string | PartialFASTElementDefinition +) { return (providerCtor: T): void => { customElement(nameOrDef)(providerCtor); providerCtor.registerTagName( @@ -505,3 +507,9 @@ export function designSystemProvider(nameOrDef: string | PartialFASTElementDefin ); }; } + +/** + * @internal + * @deprecated - use {@link defineDesignSystemProvider} + */ +export const designSystemProvider = defineDesignSystemProvider; diff --git a/sites/website/sidebars.js b/sites/website/sidebars.js index d9aa9418074..5acf996b3b4 100644 --- a/sites/website/sidebars.js +++ b/sites/website/sidebars.js @@ -19,7 +19,6 @@ module.exports = { "components/button", "components/card", "components/checkbox", - "components/design-system-provider", "components/dialog", "components/divider", "components/flipper", @@ -42,9 +41,6 @@ module.exports = { label: "Design", items: [ "design/introduction", - "design/design-system", - "design/type-ramp", - "design/color", "design/localization", "design/match-media-stylesheets", ], @@ -65,6 +61,16 @@ module.exports = { "fast-element/next-steps", ], }, + { + type: "category", + label: "Design Systems", + items: [ + "design-systems/overview", + "design-systems/fast-frame", + "design-systems/using-the-design-system", + "design-systems/creating-a-design-system", + ], + }, { type: "category", label: "Tools", diff --git a/sites/website/src/docs/design-systems/creating-a-design-system.md b/sites/website/src/docs/design-systems/creating-a-design-system.md new file mode 100644 index 00000000000..3c7697b49e9 --- /dev/null +++ b/sites/website/src/docs/design-systems/creating-a-design-system.md @@ -0,0 +1,124 @@ +--- +id: creating-a-design-system +title: Creating a Design System +sidebar_label: Creating a Design System +custom_edit_url: https://github.com/microsoft/fast/edit/master/sites/website/src/docs/design-systems/creating-a-design-system.md +--- +Creating a design system involves two steps: +1. Determine what information the Design System should hold +2. Creating a [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider) to communicate the Design System + +The Design System holds information dictated by a project's design guidelines, philosophies, and capabilities which may vary widely across projects. Therefore, this documentation will focus on creating and configuring a [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider) and not data in the Design System. + +## Defining a DesignSystemProvider +As discussed in the [overview](/docs/design-systems/overview#the-designSystemProvider), the [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider) is an HTML element designed to communicate the Design System. To create a [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider) element, we'll declare a new [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider) element using the [defineDesignSystemProvider](/docs/api/fast-foundation.definedesignsystemprovider) decorator: + +```ts +import { css } from "@microsoft/fast-element"; +import { + DesignSystemProvider, + defineDesignSystemProvider, + DesignSystemProviderTemplate as template, +} from "@microsoft/fast-foundation"; + +@defineDesignSystemProvider({ + name: "my-design-system-provider", + template, + styles: css`:host { display: block }` +}) +export class MyDesignSystemProvider extends DesignSystemProvider {} +``` +:::note +You may notice that this syntax looks a lot like the [customElement](docs/api/fast-element.customelement) function from `@microsoft/fast-element` - thats because under the hood [designSystemProvider](/docs/api/fast-foundation.designsystemprovider) uses [customElement](docs/api/fast-element.customelement). In fact, it supports the same type signature as [customElement](docs/api/fast-element.customelement). +::: + +Loading the script with the above definition, you can now use the following HTML: + +```html + + hello world + +``` +### Extending an existing DesignSystemProvider +The same steps can be followed to *extend* an existing provider. Instead of extending the [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider), instead extend the existing provider. + +**Example: Extending FAST Frame's FASTDesignSystemProvider** +```ts +import { FASTDesignSystemProvider } from "@microsoft/fast-components"; +import { + designSystemProvider, + DesignSystemProviderTemplate as template, +} from "@microsoft/fast-foundation"; + +@designSystemProvider({ + name: "my-design-system-provider", + template, + styles: css`:host { display: block }` +}) +export class MyDesignSystemProvider extends FASTDesignSystemProvider {} +``` + +## Declaring the Design System +The above HTML at this point doesn't do much. Let's change that by exploring how to creates properties of the design system using [`designSystemProperty()`](/docs/api/fast-foundation.designsystemproperty). Let's say that we want to add `font-size-large` to our Design System: + +```ts +// ... +import { designSystemProperty } from "@microsoft/fast-foundation"; + +// ... +export class MyDesignSystemProvider extends DesignSystemProvider { + @designSystemProperty({ + attribute: "font-size-large", + cssCustomProperty: "font-size-large", + default: "28px" + }) + public fontSizeLarge: string; +} +``` + +The above declares the `fontSizeLarge` property on the `MyDesignSystemProvider` and decorates it as a property of the Design System. Let's take a closer look at the configuration object provided to the decorator. + +### `attribute` +The `attribute` property is used to set the HTML attribute that should correspond to the decorated property. This property is optional and defaults to the name of the decorated property; it can also be set to `false` to omit the HTML attribute association. In this case, the `attribute` property is being used to spinal-case the property name for more conventional use in HTML: + +**Example: Setting the property from the HTML attribute** +```html + +``` + +### `cssCustomProperty` +The `cssCustomProperty` property is used to define the name of the [CSS custom property](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) to which the value is mapped. This allows easy use of the Design System value in CSS stylesheets. This property is optional and defaults to the attribute name of the decorated property; it can also be set to `false` to omit the [CSS custom property](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) association. In this case, the `cssCustomProperty` property is being used to spinal-case the property name. + +```ts +const styles = css`:host { font-size: var(--font-size-large)}`; +``` +### `default` +The `default` property naturally defines the default value for the Design System property. This is the value that gets used when an app author applies the `use-defaults` attribute (see [`use-defaults`](#use-defaults)). + +:::important +Notice the the default value is assigned as a property of the config and not directly to the *property itself*; the property is declared but never assigned a value. This is important because each instance of a provider inherits unset properties from a parent provider (if it exists); if each provider *set* each property explicitly to the default then there would be no inheritance. +::: + +### `converter` +Much like [`@attr()`](/docs/api/fast-element.attr), [`designSystemProperty()`](/docs/api/fast-foundation.designsystemproperty) also supports a `converter` property to convert HTML attributes into JavaScript properties. This is useful when the Design System property value should be represented as a data-type other than a string: + +**Example: Using a nullableNumberConverter** +```ts + // ... + @designSystemProperty({ + attribute: "design-unit", + cssCustomProperty: "design-unit" + default: 4, + converter: nullableNumberConverter, + }) + public baseHeightMultiplier: number; + // ... +``` + +## `use-defaults` +The `use-defaults` boolean attribute exists for all [DesignSystemProviders](/docs/api/fast-foundation.designsystemprovider) and exposes a mechanism to apply the default values to an element while still allowing nested design system elements to intentionally override specific values. For details on how to set default values, see [Declaring Design System Properties](#declaring-the-design-system). + +In general, a [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider) element with the `use-defaults` attribute should exist as an ancestor to all rendered UI; this will ensure that all the values enumerated in the Design System are defined. + +## Done! +Thats it! Once you've configured all the Design System properties you can use your Design System Provider in your page. See [Using the Design System](/docs/design-systems/using-the-design-system) for more information on how to use the Design System values provided by your DesignSystemProvider. diff --git a/packages/web-components/fast-components/docs/design/color.md b/sites/website/src/docs/design-systems/fast-frame.md similarity index 60% rename from packages/web-components/fast-components/docs/design/color.md rename to sites/website/src/docs/design-systems/fast-frame.md index cb068ab28da..b3b42ca4ba9 100644 --- a/packages/web-components/fast-components/docs/design/color.md +++ b/sites/website/src/docs/design-systems/fast-frame.md @@ -1,35 +1,68 @@ --- -id: color -title: Color -custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-components/docs/design/color.md +id: fast-frame +title: The FAST Frame Design System +sidebar_label: FAST Frame +custom_edit_url: https://github.com/microsoft/fast/edit/master/sites/website/src/docs/design-systems/fast-frame.md --- +The FAST Frame Design System is the Design System that comes with the `@microsoft/fast-components` package. -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. +## What's in the FAST Frame Design System? +Every piece of Design System data in the FAST Frame Design System exists in the [`FASTDesignSystem`](/docs/api/fast-components.fastdesignsystem) interface. The [`FASTDesignSystemProvider`](/docs/api/fast-components.fastdesignsystemprovider) *implements* the [`FASTDesignSystem`](/docs/api/fast-components.fastdesignsystem). These two resources are the best place to look for a catalog of what Design System data exists in FAST Frame, as well as which CSS custom properties exist and which HTML attributes / JavaScript properties are used to configure the Design System. -## Algorithmic colors (recipes) +Each Design System property in the [`FASTDesignSystemProvider`](/docs/api/fast-components.fastdesignsystemprovider) will list the HTML attribute on the `` that controls the property, and also whether it creates a corresponding CSS custom property. For more information on how to *set* each Design System property see [Setting Design System Properties](/docs/design-systems/using-the-design-system#setting-design-system-properties), and for information on how to use Design System CSS custom properties see [Using Design System CSS Custom Properties](/docs/design-systems/using-the-design-system#css-custom-properties). -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*. +## Using the FAST Frame Design System +To use the FAST Frame Design System, simply ensure the [`FASTDesignSystemProvider`](/docs/api/fast-components.fastdesignsystemprovider) is defined and use the element in your view: -### Inputs +**Example: Using the [`FASTDesignSystemProvider`](/docs/api/fast-components.fastdesignsystemprovider)** +```ts +import { FASTDesignSystemProvider } from "@microsoft/fast-components"; -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. +FASTDesignSystemProvider; // Prevent tree shaking +``` +```html + + Hello world + +``` + +:::note +We recommend to add the `` at the root of your view with the `use-defaults` attribute. This ensures that all Design System properties are initialized. For more info see the [`use-defaults`](/docs/design-systems/using-the-design-system#use-defaults) +::: + +### Type-ramp +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` | + +### Adaptive Color +FAST Frame implements 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 background colors. -### Palettes +To accomplish these goals, FAST Frame makes heavy use of algorithmic colors; named colors that are a product of the Design System in which they are calculated. In the documentation below, these algorithmic colors will be referred to as [Recipes](/docs/design-systems/fast-frame#color-recipes). [Recipes](/docs/design-systems/fast-frame#color-recipes) operate on three primary inputs: [Palettes](/docs/design-systems/fast-frame#palettes), [the background color](/docs/design-systems/fast-frame#background-color), and [offsets / deltas](/docs/design-systems/fast-frame#offsets-deltas). -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`. +#### Palettes +Each color recipe operates on a palette. A palette is an array of hexadecimal colors ordered from light to dark by [relative luminance](https://www.w3.org/WAI/GL/wiki/Relative_luminance#:~:text=WCAG%20definition%20of%20relative%20luminance,and%201%20for%20lightest%20white). By default, FAST components leverage the `neutralPalette` and the `accentPalette`. See [accentPalette](api/fast-components.fastdesignsystemprovider.accentpalette.md) and [neutralPalette](api/fast-components.fastdesignsystemprovider.neutralpalette.md) for more details. -#### Replacing palettes - +##### Generating and Replacing Palettes `@microsoft/fast-components` exposes a convenient function to generate a color palette from an arbitrary source color, and this function is how the default `neutralPalette` and `accentPalette` are generated. You can generate a new palette by choosing a palette source color and invoking the palette generation function: -##### Replacing the neutral palette - +###### Replacing the neutral palette ```js import { parseColorHexRGB } from "@microsoft/fast-colors"; import { createColorPalette } from "@microsoft/fast-components"; @@ -46,8 +79,7 @@ const provider = document.querySelector("fast-design-system-provider"); provider.neutralPalette = palette; ``` -##### Replacing the accent palette - +###### Replacing the accent palette The same approach can be taken for the `accentPalette`, but when doing so the `accentPaletteBaseColor` should *also* be replaced: ```js @@ -62,20 +94,21 @@ provider.accentBaseColor = accent; provider.accentPalette = palette; ``` -### Background color - +#### 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. See [backgroundColor](api/fast-components.fastdesignsystemprovider.backgroundcolor.md) for more details. -### 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). +#### Offsets / Deltas +If you look at the properties of the [`FASTDesignSystem`](/docs/api/fast-components.fastdesignsystem), you'll notice a number of "Delta" properties. These are used by color recipes to *shift* the colors derived from recipes by index of the palette. You can adjust these values to fine-tune each individual color recipe. -## Color recipes +#### Color recipes +Color recipes are algorithmic colors generated relative to a context. Recipes can be thought of and used as named colors, however they are more than simple variables; they are generated values where the value of the Recipe will change depending on the context in which it is generated. The primary inputs to any color recipe are [Palettes](/docs/design-systems/fast-frame#palettes), the [background color](/docs/design-systems/fast-frame#background-color), and [offsets / deltas](/docs/design-systems/fast-frame#offsets-deltas), which come from the nearest ancestor ``. -### Using color recipes +We created the [Color Explorer](https://color.fast.design/) as a visualization tool to help see what each of the following color recipes does. -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. +##### Using Color Recipes +First, ensure the UI element has a [`FASTDesignSystemProvider`](/docs/api/fast-components.fastdesignsystemprovider) ancestor element - this element will *resolve* the recipe for a component within it that declares a dependency on the recipe. ```html @@ -83,10 +116,7 @@ First, ensure the UI element has a *FASTDesignSystemProvider* ancestor element - ``` -*For more information on the DesignSystemProvider, see the [DesignSystemProvider documentation](/docs/components/design-system-provider)* - - -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: +Next - declare the recipe as a dependent *behavior* of a FAST Component's stylesheet. Then use the recipe as a CSS Custom Property in the stylesheet: ```js import { css } from "@microsoft/fast-element"; @@ -101,10 +131,14 @@ const styles = css` ); ``` -### Neutral recipes +Then, define a [FAST element](/docs/fast-element/defining-elements) and use the element in your page! -#### Layer recipes +:::note +For more information on what this is doing, see [CSS Custom Property Behaviors](/docs/design-systems/using-the-design-system#csscustompropertybehavior) +::: +##### 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. | Behavior Name | CSS Custom Property | Description | @@ -118,8 +152,7 @@ Layer recipes represent the UI layers and surfaces that individual UI elements a | `neutralLayerL3Behavior` | `--neutral-layer-l3` | Used as the background for secondary command surfaces, logically below L2. | | `neutralLayerL4Behavior` | `--neutral-layer-l4`| Used as the background for the lowest command surface or title bar, logically below L3. | -#### Text - +###### Text Neutral text recipes address *most* cases of text used in a UI, from interactive element text, headings, and body text. | Behavior Name | CSS Custom Property | Description | @@ -130,8 +163,7 @@ Neutral text recipes address *most* cases of text used in a UI, from interactive | `neutralForegroundHintBehavior` | `--neutral-foreground-hint`| 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 ratioBehavior to the background. | | `neutralForegroundHintLargeBehavior` | `--neutral-foreground-hint-large`| 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) - +###### Fills (backgrounds) Neutral fills are indented to be used as fill colors (background) to UI elements to distinguish them from the background. | Behavior Name | CSS Custom Property | Description | @@ -145,8 +177,7 @@ Neutral fills are indented to be used as fill colors (background) to UI elements | `neutralFillStealthActiveBehavior`| `--neutral-fill-stealth-active` | Used as the fill of a `neutralFillStealth` element when active. | | `neutralFillStealthSelectedBehavior`| `--neutral-fill-stealth-selected` | Used as the fill of a `neutralFillStealth` element when selected. | -#### Outlines and dividers - +###### Outlines and dividers Neutral outlines are used to construct outline controls and dividers. | Behavior Name | CSS Custom Property | Description | @@ -156,8 +187,7 @@ Neutral outlines are used to construct outline controls and dividers. | `neutralOutlineActiveBehavior` | `--neutral-outline-active` | Used as the outline of a `neutralOutline` control when active. | | `neutralDividerRestBehavior` | `--neutral-divider-rest` | Used as the color for divider elements. | -#### Toggles - +###### Toggles Toggle elements such as checkboxes and switches use a specific set of recipes. | Behavior Name | CSS Custom Property | Description | @@ -168,8 +198,7 @@ Toggle elements such as checkboxes and switches use a specific set of recipes. | `neutralFillToggleHoverBehavior` | `--neutral-foreground-hover` | Used as the fill of a `neutralFillToggle` element when hovered. | | `neutralFillToggleActiveBehavior` | `--neutral-foreground-active` | Used as the fill of a `neutralFillToggle` element when active. | -#### Inputs - +###### Inputs Text input elements also have a set of recipes specifically tailored. | Behavior Name | CSS Custom Property | Description | @@ -179,15 +208,13 @@ Text input elements also have a set of recipes specifically tailored. | `neutralFillInputActiveBehavior` | `--neutral-fill-input-active` | Used as the fill of the text input when active. | | `neutralFillInputSelectedBehavior` | `--neutral-fill-input-selected` | Used as the fill of the text input when selected. | -#### Document focus - +###### Document focus | Behavior Name | CSS Custom Property | Description | |---------------|---------------------|-------------| | `neutralFocusBehavior` | `--neutral-focus` | The color of the focus indicator when the element has document focus. | | `neutralFocusInnerAccentBehavior` | `--neutral-focus-inner-accent` | The color of the inner focus-indicator when an *accent fill* element has document focus. | -### Accent recipes - +##### Accent recipes Accent recipes use the accent palette and are intended to bring attention or otherwise distinguish the element on the page. | Behavior Name | CSS Custom Property | Description | @@ -201,4 +228,4 @@ Accent recipes use the accent palette and are intended to bring attention or oth | `accentFillLargeActiveBehavior` | `--accent-fill-large-active` | Used as the fill of an accent fill large element when active. | | `accentFillLargeSelectedBehavior` | `--accent-fill-large-selected` | Used as the fill of an accent fill large element when selected. | | `accentForegroundCutBehavior` | `--accent-foreground-cut` | Used as foreground color of text used *over* accent fill fill. | -| `accentForegroundCutLargeBehavior` | `--accent-foreground-cut-large` | Used as foreground color of text used *over* accent fill large fill. | \ No newline at end of file +| `accentForegroundCutLargeBehavior` | `--accent-foreground-cut-large` | Used as foreground color of text used *over* accent fill large fill. | diff --git a/sites/website/src/docs/design-systems/overview.md b/sites/website/src/docs/design-systems/overview.md new file mode 100644 index 00000000000..ad224b2cee9 --- /dev/null +++ b/sites/website/src/docs/design-systems/overview.md @@ -0,0 +1,64 @@ +--- +id: overview +title: What is the Design System? +sidebar_label: Overview +custom_edit_url: https://github.com/microsoft/fast/edit/master/sites/website/src/docs/design-systems/overview.md +--- +A *Design System* is somewhat of an amorphous term but can generally be thought of as a collection of resources for interactive media that promotes brand alignment. While that definition is intentionally broad, in UI development, Design Systems generally manifest as component libraries surrounded by usage guidance and design principles. + +FAST uses "Design System" in a narrower sense than the above; the Design System is a dictionary of data that informs the visual (and sometimes functional) representation of UI elements. The Design System captures, stores, and reflects any information that should inform the rendering of a UI element. This data is often referred to as *Design Tokens*. Common examples of data in a Design System are: +- UI Colors +- Fonts and type ramps +- Motion data such as timings and easing curves +- UI Density +- Spacing values + +## How the Design System is used +There are two ways that Design System values (Design Tokens) are used: +1. In CSS +2. In JavaScript + +### Design System in CSS +Many Design Tokens are used as CSS property values in component stylesheets. Assume for a moment that a Design Token `font-size-large` exists in a Design System, you may see something like the following: + +```css +:host { + font-size: var(--font-size-large); +} +``` + +### Design System in JavaScript +The Design System can also be required by JavaScript. Assume for a moment that a Design Token `fadeInDuration` exists in a Design System, you may see something like the following: + +```js +const keyFrames = new KeyframeEffect( + targetElement, + [{ opacity: "0"}, {opacity: "1"}], + {duration: designSystem.fadeInDuration} +) +``` + +## The DesignSystemProvider +The Design System itself manifests through a [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider): it is the vessel through which the Design System is expressed. The [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider) is an HTML element that facilitates usage, configuration, and propagation of the Design System through a UI view. The [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider) is responsible for expressing the Design System both as a readable JavaScript property *and* as CSS custom properties. + +### Design System flow +The Design System is mutable and inherited. Think of the Design System as a flow of data through the DOM toward leaf nodes, where every [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider) element inherits Design System data from it's closest ancestor [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider) and provides opportunity to *change* that data for all descendent elements. Let's visualize this, and assume there is a `font-size-large` Design Token in the Design System: + +**Example: The Design System flows data down the DOM hierarchy** +```html + + + My font size is 29px + + + + + My font size is 15px + + + +``` + +As shown above, the `font-size-large` Design System property is set on each [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider) instance. The [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider) reflects that value to a CSS custom property ([more on that later](/docs/design-systems/using-the-design-system#css-custom-properties)), which the `` element uses in it's stylesheet. + +But we can *also* access that hierarchical information from JavaScript, which opens up many advanced scenarios that will be explored in the [FAST Frame Design System](/docs/design-systems/fast-frame). diff --git a/sites/website/src/docs/design-systems/using-the-design-system.md b/sites/website/src/docs/design-systems/using-the-design-system.md new file mode 100644 index 00000000000..020a9b07ae5 --- /dev/null +++ b/sites/website/src/docs/design-systems/using-the-design-system.md @@ -0,0 +1,130 @@ +--- +id: using-the-design-system +title: Using the FAST Design System +sidebar_label: Using the Design System +custom_edit_url: https://github.com/microsoft/fast/edit/master/sites/website/src/docs/design-systems/using-the-design-system.md +--- + +This section goes into further detail on how the Design System can be used. It will use [FAST Frame](/docs/design-systems/fast-frame) Design System in the examples but none are *specific* to [FAST Frame](/docs/design-systems/fast-frame); use these features with your own Design System if you're not using [FAST Frame](/docs/design-systems/fast-frame). + +### Setting Design System Properties +Design System properties can always be set by simple property assignment in JavaScript; obtain a reference to the Custom Element instance and assign the property. + +**Example: Setting a Design System value by property assignment** +```ts +const provider = document.querySelector('fast-design-system-provider'); +provider.designUnit = 6; // Set the Design System property. +``` + +or with FAST Element's [property bindings](/docs/fast-element/declaring-templates#properties): + +```ts +import { html } from "@microsoft/fast-element"; + +export const template = html` + + +` +``` + +*Most* Design System properties can be set by setting an HTML *attribute* on the element instance. The attribute name for the Design System property will be the corresponding JavaScript property name by default, but it can be customized or disabled for each Design System property. See [Declaring the Design System](/docs/design-systems/creating-a-design-system#declaring-the-design-system) for more info. + +**Example: Setting a Design System value by HTML attribute** +```html + + + +``` + +## `use-defaults` +Every [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider) supports the `use-defaults` boolean attribute. `use-defaults` is a mechanism to assign the [default Design System values](/docs/design-systems/creating-a-design-system#default) to the [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider). + +It is a good idea to have a [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider) with the `use-defaults` attribute wrapping all of the app UI to ensure all properties used by descendent components are defined. This is especially important if the Design System properties reflect to CSS custom properties because the CSS custom properties are only created when the value is set. + +**Example: using `use-defaults` at the page root** +```html + + + + + + + + + + + +``` + +`use-defaults` can also be used in conjunction with explicit Design System property attribute assignment. If both `use-defaults` *and* an attribute setting a Design System property exist, the explicit attribute assignment takes priority. + +**Example: `use-defaults` with attribute assignment** +```html + + + +``` + +### Composing Design System Providers +Remember from the [overview](/docs/design-systems/overview#design-system-flow) that the Design System values are inherited and propagate down the DOM tree. This can be used to scope regions of a page with Design System changes. + +```html + + +

Design unit is 12px.

+ + +

Design unit is 6px

+ +``` + +### CSS Custom Properties +Many Design System properties are intended to be consumed directly in CSS. When a Design System property is [configured](/docs/design-systems/creating-a-design-system#declaring-the-design-system) to emit a [CSS custom property](https://developer.mozilla.org/en-US/docs/Web/CSS/--*), the [CSS custom property](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) can be used in CSS for any descendent of the [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider). + +**Example: Using CSS Custom Properties** +```css +p { + margin: calc(var(--design-unit) * 2px) 0; +} +``` +```html + +

vertical margin is 12px

+ +``` + +### CSS Custom Property Registry +There are some things that CSS just can't do: advanced math, complex data structures, and conditionals are simply not possible with CSS today. + +To address this, the [DesignSystemProvider](/docs/api/fast-foundation.designsystemprovider) provides a mechanism to register a JavaScript function that accepts the Design System object and returns a value to be written as a [CSS custom property](https://developer.mozilla.org/en-US/docs/Web/CSS/--*). The registered function will be re-evaluated when the Design System is mutated. + +**Example: Register a CSS custom property that is a function of the Design System** +```ts +DesignSystemProvider.registerCSSCustomProperty({ + name: "design-unit-to-the-12th", + value: designSystem => Math.pow(designSystem.designUnit, 12), +}); +``` + +#### CSSCustomPropertyBehavior +The above API is especially useful when defining a [component stylesheet](docs/fast-element/leveraging-css); individual stylesheets can declare dependencies on CSS custom properties that are functions of the element instance's Design System through with the [CSSCustomPropertyBehavior](/docs/api/fast-foundation.csscustompropertybehavior). This is how the [FAST Frame Color Recipes](/docs/design-systems/fast-frame#color-recipes) are constructed. + +**Example: creating a recipe dependency** +```ts +import { css } from "@microsoft/fast-element"; +import { CSSCustomPropertyBehavior } from "@microsoft/fast-foundation"; +import { FASTDesignSystemProvider } from "@microsoft/fast-components"; + +const designUnitToTheTwelfth = new CSSCustomPropertyBehavior( + "design-unit-to-the-12th", + designSystem => Math.pow(designSystem.designUnit, 12), + FASTDesignSystemProvider.findProvider +) +const styles = css` + :host { + height: ${designUnitToTheTwelfth.var}; + } +`.withBehaviors( + designUnitToTheTwelfth +) +``` diff --git a/sites/website/src/docs/resources/glossary.md b/sites/website/src/docs/resources/glossary.md index e186acecb34..ae8d1361332 100644 --- a/sites/website/src/docs/resources/glossary.md +++ b/sites/website/src/docs/resources/glossary.md @@ -4,6 +4,8 @@ title: Glossary sidebar_label: Glossary custom_edit_url: https://github.com/microsoft/fast/edit/master/sites/website/src/docs/resources/glossary.md --- +#### Design System +In FAST, the Design System is a collection of properties that informs visual rendering. It generally contains information about fonts, type-ramps, colors, etc. #### ES2015