Fix CSS custom property precedence issue

change/@microsoft-fast-element-af94cffe-06a2-45f2-a5d6-ea40b67867ec.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Fix CSS custom property precedence issue",
+  "packageName": "@microsoft/fast-element",
+  "email": "7282195+m-akinc@users.noreply.github.com",
+  "dependentChangeType": "prerelease"
+}

change/@microsoft-fast-foundation-5af478ef-11f0-4516-8bd1-36a6844f5e29.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Fix CSS custom property precedence issue",
+  "packageName": "@microsoft/fast-foundation",
+  "email": "7282195+m-akinc@users.noreply.github.com",
+  "dependentChangeType": "prerelease"
+}

packages/web-components/fast-element/docs/api-report.md

@@ -678,6 +678,9 @@ export interface PartialHTMLDirectiveDefinition {
     aspected?: boolean;
 }
 
+// @public
+export const prependToAdoptedStyleSheetsSymbol: unique symbol;
+
 // @public
 export class PropertyChangeNotifier implements Notifier {
     constructor(subject: any);

packages/web-components/fast-element/src/components/element-controller.ts

@@ -645,8 +645,27 @@ export class StyleElementStrategy implements StyleStrategy {
     }
 }
 
+/**
+ * A Symbol that can be added to a CSSStyleSheet to cause it to be prepended (rather than appended) to adoptedStyleSheets.
+ * @public
+ */
+export const prependToAdoptedStyleSheetsSymbol = Symbol("prependToAdoptedStyleSheets");
+
+function separateSheetsToPrepend(sheets: CSSStyleSheet[]): {
+    prepend: CSSStyleSheet[];
+    append: CSSStyleSheet[];
+} {
+    const prepend: CSSStyleSheet[] = [];
+    const append: CSSStyleSheet[] = [];
+    sheets.forEach(x =>
+        (x[prependToAdoptedStyleSheetsSymbol] ? prepend : append).push(x)
+    );
+    return { prepend, append };
+}
+
 let addAdoptedStyleSheets = (target: Required<StyleTarget>, sheets: CSSStyleSheet[]) => {
-    target.adoptedStyleSheets = [...target.adoptedStyleSheets!, ...sheets];
+    const { prepend, append } = separateSheetsToPrepend(sheets);
+    target.adoptedStyleSheets = [...prepend, ...target.adoptedStyleSheets!, ...append];
 };
 let removeAdoptedStyleSheets = (
     target: Required<StyleTarget>,
@@ -666,7 +685,9 @@ if (ElementStyles.supportsAdoptedStyleSheets) {
         (document as any).adoptedStyleSheets.push();
         (document as any).adoptedStyleSheets.splice();
         addAdoptedStyleSheets = (target, sheets) => {
-            target.adoptedStyleSheets.push(...sheets);
+            const { prepend, append } = separateSheetsToPrepend(sheets);
+            target.adoptedStyleSheets.splice(0, 0, ...prepend);
+            target.adoptedStyleSheets.push(...append);
         };
         removeAdoptedStyleSheets = (target, sheets) => {
             for (const sheet of sheets) {

packages/web-components/fast-element/src/index.ts

@@ -148,4 +148,5 @@ export {
 export {
     ElementController,
     ElementControllerStrategy,
+    prependToAdoptedStyleSheetsSymbol,
 } from "./components/element-controller.js";

packages/web-components/fast-foundation/src/design-token/custom-property-manager.ts

@@ -3,7 +3,13 @@ import type {
     ElementController,
     FASTElement,
 } from "@microsoft/fast-element";
-import { ElementStyles, observable, Observable, Updates } from "@microsoft/fast-element";
+import {
+    ElementStyles,
+    observable,
+    Observable,
+    prependToAdoptedStyleSheetsSymbol,
+    Updates,
+} from "@microsoft/fast-element";
 
 /**
  * A target that can have key/value pairs set and removed.
@@ -33,6 +39,7 @@ class ConstructableStyleSheetTarget extends QueuedStyleSheetTarget {
         super();
 
         const sheet = new CSSStyleSheet();
+        sheet[prependToAdoptedStyleSheetsSymbol] = true;
         this.target = (sheet.cssRules[sheet.insertRule(":host{}")] as CSSStyleRule).style;
         source.$fastController.addStyles(new ElementStyles([sheet]));
     }

packages/web-components/fast-foundation/src/design-token/fast-design-token.pw.spec.ts

@@ -1061,6 +1061,25 @@ test.describe("A DesignToken", () => {
                 })
             ).toBe("12px");
         });
+        test("should allow stylesheet to override token's CSS custom property", async () => {
+            expect(
+                await page.evaluate(async () => {
+                    const target = addElement();
+                    const token = DesignToken.create<number>(uniqueTokenName());
+                    const styles = css`
+                        :host {
+                            ${token.cssCustomProperty}: 34;
+                            width: calc(${token} * 1px);
+                        }
+                    `;
+                    target.$fastController.addStyles(styles);
+                    token.setValueFor(target, 12);
+
+                    await Updates.next();
+                    return window.getComputedStyle(target).getPropertyValue("width");
+                })
+            ).toBe("34px");
+        });
     });
 
     test.describe("with a default value set", () => {