Adaptive UI: add layer recipes and design tokens (#6252)

change/@microsoft-adaptive-ui-3c7fd1ff-e743-4ee8-a3c1-bb8744bff757.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Add layer recipes and design tokens",
+  "packageName": "@microsoft/adaptive-ui",
+  "email": "[email protected]",
+  "dependentChangeType": "prerelease"
+}

packages/utilities/adaptive-ui/docs/api-report.md

@@ -257,9 +257,83 @@ export function interactiveSwatchSetAsOverlay(set: InteractiveSwatchSet, referen
 // @public
 export function isDark(color: RelativeLuminance): boolean;
 
+// @public
+export const LayerBaseLuminance: Readonly<{
+    readonly LightMode: 0.95;
+    readonly DarkMode: 0.13;
+}>;
+
 // @public (undocumented)
 export const layerCornerRadius: CSSDesignToken<number>;
 
+// @public
+export const layerFillActiveDelta: DesignToken<number>;
+
+// @public
+export const layerFillBaseLuminance: DesignToken<number>;
+
+// @public
+export const layerFillDelta: DesignToken<number>;
+
+// @public
+export const layerFillFixedBase: CSSDesignToken<Swatch>;
+
+// @public
+export const layerFillFixedMinus1: CSSDesignToken<Swatch>;
+
+// @public
+export const layerFillFixedMinus2: CSSDesignToken<Swatch>;
+
+// @public
+export const layerFillFixedMinus3: CSSDesignToken<Swatch>;
+
+// @public
+export const layerFillFixedMinus4: CSSDesignToken<Swatch>;
+
+// @public
+export const layerFillFixedPlus1: CSSDesignToken<Swatch>;
+
+// @public
+export const layerFillFixedPlus2: CSSDesignToken<Swatch>;
+
+// @public
+export const layerFillFixedPlus3: CSSDesignToken<Swatch>;
+
+// @public
+export const layerFillFixedPlus4: CSSDesignToken<Swatch>;
+
+// @public
+export const layerFillFixedRecipe: DesignToken<LayerRecipe>;
+
+// @public
+export const layerFillFocusDelta: DesignToken<number>;
+
+// @public
+export const layerFillHoverDelta: DesignToken<number>;
+
+// @public
+export const layerFillInteractiveActive: CSSDesignToken<Swatch>;
+
+// @public
+export const layerFillInteractiveFocus: CSSDesignToken<Swatch>;
+
+// @public
+export const layerFillInteractiveHover: CSSDesignToken<Swatch>;
+
+// @public
+export const layerFillInteractiveRecipe: DesignToken<InteractiveColorRecipe>;
+
+// @public
+export const layerFillInteractiveRest: CSSDesignToken<Swatch>;
+
+// @public
+export const layerPalette: DesignToken<Palette<Swatch>>;
+
+// @public
+export interface LayerRecipe {
+    evaluate(resolve: DesignTokenResolver, index: number): Swatch;
+}
+
 // @public
 export function luminanceSwatch(luminance: number): Swatch;
 
@@ -566,7 +640,7 @@ export type PaletteDirectionValue = typeof PaletteDirectionValue[keyof typeof Pa
 
 // @public
 export class PaletteRGB extends BasePalette<SwatchRGB> {
-    static from(source: SwatchRGB, options?: Partial<PaletteRGBOptions>): PaletteRGB;
+    static from(source: SwatchRGB | string, options?: Partial<PaletteRGBOptions>): PaletteRGB;
 }
 
 // @public

packages/utilities/adaptive-ui/src/color/palette-rgb.spec.ts

@@ -6,21 +6,28 @@ import { contrast } from "./utilities/relative-luminance.js";
 
 const { expect } = chai;
 
-const grey: SwatchRGB = SwatchRGB.from(parseColorHexRGB("#808080")!);
+const greyHex = "#808080";
+const greySwatch: SwatchRGB = SwatchRGB.from(parseColorHexRGB(greyHex)!);
 
 describe("PaletteRGB.from", () => {
     it("should create a palette from the provided swatch", () => {
-        const palette = PaletteRGB.from(grey);
+        const palette = PaletteRGB.from(greySwatch);
 
-        expect(palette.source === grey).to.be.true;
+        expect(palette.source).to.equal(greySwatch);
+    });
+
+    it("should create a palette from the provided hex color", () => {
+        const palette = PaletteRGB.from(greyHex);
+
+        expect(palette.source.toColorString()).to.equal(greyHex);
     });
 
     it("should create a palette with increased contrast", () => {
         const options: Partial<PaletteRGBOptions> = {
             stepContrast: 1.07,
             stepContrastRamp: 0,
         };
-        const palette = PaletteRGB.from(grey, options);
+        const palette = PaletteRGB.from(greySwatch, options);
 
         expect(
             contrast(palette.swatches[0], palette.swatches[1]),
@@ -37,7 +44,7 @@ describe("PaletteRGB.from", () => {
     //     const options: Partial<PaletteRGBOptions> = {
     //             preserveSource: true,
     //     };
-    //     const palette = PaletteRGB.from(grey, options);
+    //     const palette = PaletteRGB.from(greySwatch, options);
 
     //     expect(contrast(palette.swatches[0], palette.swatches[1]), "at least 1.05:1 between 0 and 1").to.be.gte(1.05);
     //     expect(contrast(palette.swatches[20], palette.swatches[21]), "at least 1.05:1 between 0 and 1").to.be.gte(1.05);

packages/utilities/adaptive-ui/src/color/palette-rgb.ts

@@ -5,6 +5,7 @@ import {
     hslToRGB,
     interpolateRGB,
     labToRGB,
+    parseColorHexRGB,
     rgbToHSL,
     rgbToLAB,
     roundToPrecisionSmall,
@@ -293,15 +294,22 @@ export class PaletteRGB extends BasePalette<SwatchRGB> {
      * @param options - Options to specify details of palette generation
      * @returns The PaletteRGB with Swatches based on `source`
      */
-    static from(source: SwatchRGB, options?: Partial<PaletteRGBOptions>): PaletteRGB {
+    static from(
+        source: SwatchRGB | string,
+        options?: Partial<PaletteRGBOptions>
+    ): PaletteRGB {
+        const swatch =
+            source instanceof SwatchRGB
+                ? source
+                : SwatchRGB.from(parseColorHexRGB(source)!);
         const opts =
             options === void 0 || null
                 ? defaultPaletteRGBOptions
                 : { ...defaultPaletteRGBOptions, ...options };
 
         return new PaletteRGB(
-            source,
-            Object.freeze(PaletteRGB.createColorPaletteByContrast(source, opts))
+            swatch,
+            Object.freeze(PaletteRGB.createColorPaletteByContrast(swatch, opts))
         );
     }
 }

packages/utilities/adaptive-ui/src/color/swatch.ts

@@ -66,7 +66,7 @@ export class SwatchRGB implements Swatch {
      * @param green - Green channel expressed as a number between 0 and 1
      * @param blue - Blue channel expressed as a number between 0 and 1
      * @param alpha - Alpha channel expressed as a number between 0 and 1, default 1
-     * @param intendedColor - If `alpha` < 1 this tracks the intended opaque color value for dependent calculations
+     * @param intendedColor - If `alpha` &lt; 1 this tracks the intended opaque color value for dependent calculations
      */
     constructor(
         red: number,

packages/utilities/adaptive-ui/src/color/utilities/luminance-swatch.ts

@@ -1,9 +1,9 @@
 import { Swatch, SwatchRGB } from "../swatch.js";
 
 /**
- * Create a grey swatch for the specified `luminance`. Note this is absolute luminance not 'relative' luminance.
+ * Create a grey {@link Swatch} for the specified `luminance`. Note this is absolute luminance not 'relative' luminance.
  *
- * @param luminance - A value between 0 and 1 representing the desired luminance, for example, 0.5 for middle grey
+ * @param luminance - A value between 0 and 1 representing the desired luminance, for example, 0.5 for middle grey, 0 = black, 1 = white
  * @returns A swatch for the specified grey value
  *
  * @public

packages/utilities/adaptive-ui/src/color/utilities/opacity.ts

@@ -4,10 +4,10 @@ import { Swatch, SwatchRGB } from "../swatch.js";
 /**
  * Returns an opaque {@link Swatch} or a {@link Swatch} with opacity relative to the reference color.
  *
- * @param swatch The opaque intended swatch color
- * @param reference The reference color for a semitransparent swatch
- * @param asOverlay True to return a semitransparent representation of `swatch` relative to `reference`.
- * @returns The requested representation of `swatch`
+ * @param swatch - The opaque intended swatch color.
+ * @param reference - The reference color for a semitransparent swatch.
+ * @param asOverlay - True to return a semitransparent representation of `swatch` relative to `reference`.
+ * @returns The requested representation of `swatch`.
  *
  * @public
  */
@@ -24,10 +24,12 @@ export function swatchAsOverlay(
 /**
  * Returns an interactive set of opaque {@link Swatch}es or {@link Swatch}es with opacity relative to the reference color.
  *
- * @param set
- * @param reference The reference color for a semitransparent swatch
- * @param asOverlay True to return a semitransparent representation of `swatch` relative to `reference`.
- * @returns The requested representation of a `swatch` set
+ * @param set - The swatch set for which to make overlay.
+ * @param reference - The reference color for a semitransparent swatch.
+ * @param asOverlay - True to return a semitransparent representation of `swatch` relative to `reference`.
+ * @returns The requested representation of a `swatch` set.
+ *
+ * @public
  */
 export function interactiveSwatchSetAsOverlay(
     set: InteractiveSwatchSet,

packages/utilities/adaptive-ui/src/design-tokens/color.ts

@@ -26,12 +26,12 @@ import { accentPalette, neutralPalette } from "./palette.js";
  */
 export const ContrastTarget = Object.freeze({
     /**
-     * Minimum contrast for normal (<= 14pt) text (AA rating).
+     * Minimum contrast for normal (&lt;= 14pt) text (AA rating).
      */
     NormalText: 4.5,
 
     /**
-     * Minimum contrast for large (> 14pt) text (AA rating).
+     * Minimum contrast for large (&gt; 14pt) text (AA rating).
      */
     LargeText: 3,
 } as const);
@@ -419,7 +419,7 @@ export const neutralFillInputHoverDelta = createNonCss<number>(
 /** @public */
 export const neutralFillInputActiveDelta = createNonCss<number>(
     "neutral-fill-input-active-delta"
-).withDefault(0);
+).withDefault(-2);
 
 /** @public */
 export const neutralFillInputFocusDelta = createNonCss<number>(

packages/utilities/adaptive-ui/src/design-tokens/index.ts

@@ -2,5 +2,6 @@ export * from "./appearance.js";
 export * from "./color.js";
 export * from "./elevation.js";
 export * from "./general.js";
+export * from "./layer.js";
 export * from "./palette.js";
 export * from "./type.js";