From a33792b475fd44bb1288d587d9adce49d8362571 Mon Sep 17 00:00:00 2001
From: Rob Eisenberg <rob@bluespire.com>
Date: Wed, 13 Apr 2022 10:46:55 -0400
Subject: [PATCH 1/7] feat: new CSSDirective design

---
 .../fast-element/docs/api-report.md           | 23 +++++-
 .../fast-element/src/styles/css-directive.ts  | 56 +++++++++++---
 .../fast-element/src/styles/css.ts            | 48 +++++-------
 .../fast-element/src/styles/styles.spec.ts    | 77 ++++++++++++-------
 4 files changed, 134 insertions(+), 70 deletions(-)

diff --git a/packages/web-components/fast-element/docs/api-report.md b/packages/web-components/fast-element/docs/api-report.md
index d8ef1f1174a..c62d55ee170 100644
--- a/packages/web-components/fast-element/docs/api-report.md
+++ b/packages/web-components/fast-element/docs/api-report.md
@@ -11,6 +11,9 @@ export interface Accessor {
     setValue(source: any, value: any): void;
 }
 
+// @public
+export type AddBehavior = (behavior: Behavior<HTMLElement>) => void;
+
 // @public
 export type AddViewBehaviorFactory = (factory: ViewBehaviorFactory) => string;
 
@@ -230,9 +233,23 @@ export function createTypeRegistry<TDefinition extends TypeDefinition>(): TypeRe
 export function css(strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]): ElementStyles;
 
 // @public
-export class CSSDirective {
-    createBehavior(): Behavior<HTMLElement> | undefined;
-    createCSS(): ComposableStyles;
+export interface CSSDirective {
+    createCSS(add: AddBehavior): ComposableStyles;
+}
+
+// @public
+export const CSSDirective: Readonly<{
+    getForInstance: (object: any) => CSSDirectiveDefinition<Constructable<CSSDirective>> | undefined;
+    getByType: (key: Function) => CSSDirectiveDefinition<Constructable<CSSDirective>> | undefined;
+    define<TType extends Constructable<CSSDirective>>(type: any): TType;
+}>;
+
+// @public
+export function cssDirective(): (type: Constructable<CSSDirective>) => void;
+
+// @public
+export interface CSSDirectiveDefinition<TType extends Constructable<CSSDirective> = Constructable<CSSDirective>> {
+    readonly type: TType;
 }
 
 // @public
diff --git a/packages/web-components/fast-element/src/styles/css-directive.ts b/packages/web-components/fast-element/src/styles/css-directive.ts
index 0e51a85c995..74f26c4586c 100644
--- a/packages/web-components/fast-element/src/styles/css-directive.ts
+++ b/packages/web-components/fast-element/src/styles/css-directive.ts
@@ -1,25 +1,63 @@
+import type { Constructable } from "../interfaces.js";
 import type { Behavior } from "../observation/behavior.js";
+import { createTypeRegistry } from "../platform.js";
 import type { ComposableStyles } from "./element-styles.js";
 
+/**
+ * Used to add behaviors when constructing styles.
+ * @public
+ */
+export type AddBehavior = (behavior: Behavior<HTMLElement>) => void;
+
 /**
  * Directive for use in {@link css}.
  *
  * @public
  */
-export class CSSDirective {
+export interface CSSDirective {
     /**
      * Creates a CSS fragment to interpolate into the CSS document.
      * @returns - the string to interpolate into CSS
      */
-    public createCSS(): ComposableStyles {
-        return "";
-    }
+    createCSS(add: AddBehavior): ComposableStyles;
+}
 
+/**
+ * Defines metadata for a CSSDirective.
+ * @public
+ */
+export interface CSSDirectiveDefinition<
+    TType extends Constructable<CSSDirective> = Constructable<CSSDirective>
+> {
     /**
-     * Creates a behavior to bind to the host element.
-     * @returns - the behavior to bind to the host element, or undefined.
+     * The type that the definition provides metadata for.
      */
-    public createBehavior(): Behavior<HTMLElement> | undefined {
-        return undefined;
-    }
+    readonly type: TType;
+}
+
+const registry = createTypeRegistry<CSSDirectiveDefinition>();
+
+/**
+ * Instructs the css engine to provide dynamic styles or
+ * associate behaviors with styles.
+ * @public
+ */
+export const CSSDirective = Object.freeze({
+    getForInstance: registry.getForInstance,
+    getByType: registry.getByType,
+    define<TType extends Constructable<CSSDirective>>(type): TType {
+        registry.register({ type });
+        return type;
+    },
+});
+
+/**
+ * Decorator: Defines a CSSDirective.
+ * @public
+ */
+export function cssDirective() {
+    /* eslint-disable-next-line @typescript-eslint/explicit-function-return-type */
+    return function (type: Constructable<CSSDirective>) {
+        CSSDirective.define(type);
+    };
 }
diff --git a/packages/web-components/fast-element/src/styles/css.ts b/packages/web-components/fast-element/src/styles/css.ts
index 73caf675903..e6fcd3d6970 100644
--- a/packages/web-components/fast-element/src/styles/css.ts
+++ b/packages/web-components/fast-element/src/styles/css.ts
@@ -1,7 +1,7 @@
 import type { FASTElement } from "../components/fast-element.js";
 import { isString } from "../interfaces.js";
 import type { Behavior } from "../observation/behavior.js";
-import { CSSDirective } from "./css-directive.js";
+import { AddBehavior, CSSDirective } from "./css-directive.js";
 import { ComposableStyles, ElementStyles } from "./element-styles.js";
 
 function collectStyles(
@@ -11,18 +11,16 @@ function collectStyles(
     const styles: ComposableStyles[] = [];
     let cssString = "";
     const behaviors: Behavior<HTMLElement>[] = [];
+    const add = (behavior: Behavior<HTMLElement>): void => {
+        behaviors.push(behavior);
+    };
 
     for (let i = 0, ii = strings.length - 1; i < ii; ++i) {
         cssString += strings[i];
         let value = values[i];
 
-        if (value instanceof CSSDirective) {
-            const behavior = value.createBehavior();
-            value = value.createCSS();
-
-            if (behavior) {
-                behaviors.push(behavior);
-            }
+        if (CSSDirective.getForInstance(value) !== void 0) {
+            value = (value as CSSDirective).createCSS(add);
         }
 
         if (value instanceof ElementStyles || value instanceof CSSStyleSheet) {
@@ -66,12 +64,11 @@ export function css(
     return behaviors.length ? elementStyles.withBehaviors(...behaviors) : elementStyles;
 }
 
-class CSSPartial extends CSSDirective implements Behavior<HTMLElement> {
+class CSSPartial implements CSSDirective, Behavior<HTMLElement> {
     private css: string = "";
     private styles?: ElementStyles;
-    constructor(styles: ComposableStyles[], private behaviors: Behavior<HTMLElement>[]) {
-        super();
 
+    constructor(styles: ComposableStyles[], private behaviors: Behavior<HTMLElement>[]) {
         const stylesheets: ReadonlyArray<Exclude<
             ComposableStyles,
             string
@@ -85,6 +82,7 @@ class CSSPartial extends CSSDirective implements Behavior<HTMLElement> {
                 } else {
                     accumulated.push(current);
                 }
+
                 return accumulated;
             },
             []
@@ -95,35 +93,27 @@ class CSSPartial extends CSSDirective implements Behavior<HTMLElement> {
         }
     }
 
-    createBehavior(): Behavior<HTMLElement> {
-        return this;
-    }
+    createCSS(add: AddBehavior): string {
+        this.behaviors.forEach(add);
+
+        if (this.styles) {
+            add(this);
+        }
 
-    createCSS(): string {
         return this.css;
     }
 
     bind(el: FASTElement): void {
-        if (this.styles) {
-            el.$fastController.addStyles(this.styles);
-        }
-
-        if (this.behaviors.length) {
-            el.$fastController.addBehaviors(this.behaviors);
-        }
+        el.$fastController.addStyles(this.styles);
     }
 
     unbind(el: FASTElement): void {
-        if (this.styles) {
-            el.$fastController.removeStyles(this.styles);
-        }
-
-        if (this.behaviors.length) {
-            el.$fastController.removeBehaviors(this.behaviors);
-        }
+        el.$fastController.removeStyles(this.styles);
     }
 }
 
+CSSDirective.define(CSSPartial);
+
 /**
  * Transforms a template literal string into partial CSS.
  * @param strings - The string fragments that are interpolated with the values.
diff --git a/packages/web-components/fast-element/src/styles/styles.spec.ts b/packages/web-components/fast-element/src/styles/styles.spec.ts
index 634a166a247..3172e643bc2 100644
--- a/packages/web-components/fast-element/src/styles/styles.spec.ts
+++ b/packages/web-components/fast-element/src/styles/styles.spec.ts
@@ -1,13 +1,13 @@
 import { expect } from "chai";
 import {
     AdoptedStyleSheetsStrategy,
+    ComposableStyles,
     ElementStyles,
 } from "./element-styles";
 import { DOM } from "../dom";
-import { CSSDirective } from "./css-directive";
+import { AddBehavior, cssDirective, CSSDirective } from "./css-directive";
 import { css, cssPartial } from "./css";
 import type { Behavior } from "../observation/behavior";
-import type { FASTElement } from "..";
 import { StyleElementStrategy } from "../polyfills";
 import type { StyleTarget } from "../interfaces";
 import { ExecutionContext } from "../observation/observable";
@@ -242,7 +242,8 @@ describe("css", () => {
     describe("with a CSSDirective", () => {
         describe("should interpolate the product of CSSDirective.createCSS() into the resulting ElementStyles CSS", () => {
             it("when the result is a string", () => {
-                class Directive extends CSSDirective {
+                @cssDirective()
+                class Directive implements CSSDirective {
                     createCSS() {
                         return "red";
                     }
@@ -254,7 +255,9 @@ describe("css", () => {
 
             it("when the result is an ElementStyles", () => {
                 const _styles = css`:host{color: red}`
-                class Directive extends CSSDirective {
+
+                @cssDirective()
+                class Directive implements CSSDirective {
                     createCSS() {
                         return _styles;
                     }
@@ -267,7 +270,9 @@ describe("css", () => {
             if (DOM.supportsAdoptedStyleSheets) {
                 it("when the result is a CSSStyleSheet", () => {
                     const _styles = new CSSStyleSheet();
-                    class Directive extends CSSDirective {
+
+                    @cssDirective()
+                    class Directive implements CSSDirective {
                         createCSS() {
                             return _styles;
                         }
@@ -286,9 +291,11 @@ describe("css", () => {
                 unbind(){}
             }
 
-            class Directive extends CSSDirective {
-                createBehavior() {
-                    return behavior;
+            @cssDirective()
+            class Directive implements CSSDirective {
+                createCSS(add: AddBehavior): ComposableStyles {
+                    add(behavior);
+                    return "";
                 }
             }
 
@@ -301,16 +308,18 @@ describe("css", () => {
 
 describe("cssPartial", () => {
     it("should have a createCSS method that is the CSS string interpolated with the createCSS product of any CSSDirectives", () => {
-        class myDirective extends CSSDirective {
+        const add = () => void 0;
+
+        @cssDirective()
+        class myDirective implements CSSDirective {
             createCSS() { return "red" };
-            createBehavior() { return undefined; }
         }
 
         const partial = cssPartial`color: ${new myDirective}`;
-        expect (partial.createCSS()).to.equal("color: red");
+        expect (partial.createCSS(add)).to.equal("color: red");
     });
 
-    it("Should add behaviors from interpolated CSS directives when bound to an element", () => {
+    it("Should add behaviors from interpolated CSS directives", () => {
         const behavior = {
             bind() {},
             unbind() {},
@@ -318,26 +327,30 @@ describe("cssPartial", () => {
 
         const behavior2 = {...behavior};
 
-        class directive extends CSSDirective {
-            createCSS() { return "" };
-            createBehavior() { return behavior; }
+        @cssDirective()
+        class directive implements CSSDirective {
+            createCSS(add: AddBehavior) {
+                add(behavior);
+                return ""
+            };
         }
-        class directive2 extends CSSDirective {
-            createCSS() { return "" };
-            createBehavior() { return behavior2; }
+
+        @cssDirective()
+        class directive2 implements CSSDirective {
+            createCSS(add: AddBehavior) {
+                add(behavior2);
+                return ""
+            };
         }
 
         const partial = cssPartial`${new directive}${new directive2}`;
-        const el = {
-            $fastController: {
-                addBehaviors(behaviors: Behavior<HTMLElement>[]) {
-                    expect(behaviors[0]).to.equal(behavior);
-                    expect(behaviors[1]).to.equal(behavior2);
-                }
-            }
-        } as FASTElement;
+        const behaviors: Behavior<HTMLElement>[] = [];
+        const add = (x: Behavior) => behaviors.push(x);
+
+        partial.createCSS(add);
 
-        partial.createBehavior()?.bind(el, ExecutionContext.default)
+        expect(behaviors[0]).to.equal(behavior);
+        expect(behaviors[1]).to.equal(behavior2);
     });
 
     it("should add any ElementStyles interpolated into the template function when bound to an element", () => {
@@ -351,9 +364,15 @@ describe("cssPartial", () => {
                     called = true;
                 }
             }
-        } as FASTElement;
+        };
+
+        const behaviors: Behavior<HTMLElement>[] = [];
+        const add = (x: Behavior) => behaviors.push(x);
+        partial.createCSS(add);
+
+        expect(behaviors[0]).to.equal(partial);
 
-        partial.createBehavior()?.bind(el, ExecutionContext.default)
+        (partial as any as Behavior).bind(el, ExecutionContext.default);
 
         expect(called).to.be.true;
     })

From baae64cb29b2b182154b7a941fbca3c7d4297441 Mon Sep 17 00:00:00 2001
From: Rob Eisenberg <rob@bluespire.com>
Date: Wed, 13 Apr 2022 11:44:09 -0400
Subject: [PATCH 2/7] feat: attach the partial helper to the css helper

---
 .../fast-element/src/styles/css.ts            | 34 ++++++++++++-------
 .../fast-element/src/styles/styles.spec.ts    |  8 ++---
 2 files changed, 26 insertions(+), 16 deletions(-)

diff --git a/packages/web-components/fast-element/src/styles/css.ts b/packages/web-components/fast-element/src/styles/css.ts
index e6fcd3d6970..4e5d1111ab4 100644
--- a/packages/web-components/fast-element/src/styles/css.ts
+++ b/packages/web-components/fast-element/src/styles/css.ts
@@ -47,6 +47,22 @@ function collectStyles(
     };
 }
 
+export type CSSTemplateTag = ((
+    strings: TemplateStringsArray,
+    ...values: (ComposableStyles | CSSDirective)[]
+) => ElementStyles) & {
+    /**
+     * Transforms a template literal string into partial CSS.
+     * @param strings - The string fragments that are interpolated with the values.
+     * @param values - The values that are interpolated with the string fragments.
+     * @public
+     */
+    partial(
+        strings: TemplateStringsArray,
+        ...values: (ComposableStyles | CSSDirective)[]
+    ): CSSDirective;
+};
+
 /**
  * Transforms a template literal string into styles.
  * @param strings - The string fragments that are interpolated with the values.
@@ -55,14 +71,14 @@ function collectStyles(
  * The css helper supports interpolation of strings and ElementStyle instances.
  * @public
  */
-export function css(
+export const css: CSSTemplateTag = ((
     strings: TemplateStringsArray,
     ...values: (ComposableStyles | CSSDirective)[]
-): ElementStyles {
+): ElementStyles => {
     const { styles, behaviors } = collectStyles(strings, values);
     const elementStyles = new ElementStyles(styles);
     return behaviors.length ? elementStyles.withBehaviors(...behaviors) : elementStyles;
-}
+}) as any;
 
 class CSSPartial implements CSSDirective, Behavior<HTMLElement> {
     private css: string = "";
@@ -114,16 +130,10 @@ class CSSPartial implements CSSDirective, Behavior<HTMLElement> {
 
 CSSDirective.define(CSSPartial);
 
-/**
- * Transforms a template literal string into partial CSS.
- * @param strings - The string fragments that are interpolated with the values.
- * @param values - The values that are interpolated with the string fragments.
- * @public
- */
-export function cssPartial(
+css.partial = (
     strings: TemplateStringsArray,
     ...values: (ComposableStyles | CSSDirective)[]
-): CSSDirective {
+): CSSDirective => {
     const { styles, behaviors } = collectStyles(strings, values);
     return new CSSPartial(styles, behaviors);
-}
+};
diff --git a/packages/web-components/fast-element/src/styles/styles.spec.ts b/packages/web-components/fast-element/src/styles/styles.spec.ts
index 3172e643bc2..ece6fdbe0f8 100644
--- a/packages/web-components/fast-element/src/styles/styles.spec.ts
+++ b/packages/web-components/fast-element/src/styles/styles.spec.ts
@@ -6,7 +6,7 @@ import {
 } from "./element-styles";
 import { DOM } from "../dom";
 import { AddBehavior, cssDirective, CSSDirective } from "./css-directive";
-import { css, cssPartial } from "./css";
+import { css } from "./css";
 import type { Behavior } from "../observation/behavior";
 import { StyleElementStrategy } from "../polyfills";
 import type { StyleTarget } from "../interfaces";
@@ -315,7 +315,7 @@ describe("cssPartial", () => {
             createCSS() { return "red" };
         }
 
-        const partial = cssPartial`color: ${new myDirective}`;
+        const partial = css.partial`color: ${new myDirective}`;
         expect (partial.createCSS(add)).to.equal("color: red");
     });
 
@@ -343,7 +343,7 @@ describe("cssPartial", () => {
             };
         }
 
-        const partial = cssPartial`${new directive}${new directive2}`;
+        const partial = css.partial`${new directive}${new directive2}`;
         const behaviors: Behavior<HTMLElement>[] = [];
         const add = (x: Behavior) => behaviors.push(x);
 
@@ -355,7 +355,7 @@ describe("cssPartial", () => {
 
     it("should add any ElementStyles interpolated into the template function when bound to an element", () => {
         const styles = css`:host {color: blue; }`;
-        const partial = cssPartial`${styles}`;
+        const partial = css.partial`${styles}`;
         let called = false;
         const el = {
             $fastController: {

From 78df9caa16a09c6f4b32c5c9a8be5ad044968c2a Mon Sep 17 00:00:00 2001
From: Rob Eisenberg <rob@bluespire.com>
Date: Wed, 13 Apr 2022 11:48:18 -0400
Subject: [PATCH 3/7] fix: update foundation to new CSSDirective API

---
 packages/web-components/fast-element/docs/api-report.md   | 8 +++++---
 .../fast-foundation/src/design-token/design-token.spec.ts | 4 ++--
 .../fast-foundation/src/design-token/design-token.ts      | 7 ++-----
 3 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/packages/web-components/fast-element/docs/api-report.md b/packages/web-components/fast-element/docs/api-report.md
index c62d55ee170..a93a65dcf0f 100644
--- a/packages/web-components/fast-element/docs/api-report.md
+++ b/packages/web-components/fast-element/docs/api-report.md
@@ -230,7 +230,7 @@ export class Controller<TElement extends HTMLElement = HTMLElement> extends Prop
 export function createTypeRegistry<TDefinition extends TypeDefinition>(): TypeRegistry<TDefinition>;
 
 // @public
-export function css(strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]): ElementStyles;
+export const css: CSSTemplateTag;
 
 // @public
 export interface CSSDirective {
@@ -252,8 +252,10 @@ export interface CSSDirectiveDefinition<TType extends Constructable<CSSDirective
     readonly type: TType;
 }
 
-// @public
-export function cssPartial(strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]): CSSDirective;
+// @public (undocumented)
+export type CSSTemplateTag = ((strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]) => ElementStyles) & {
+    partial(strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]): CSSDirective;
+};
 
 // @public
 export function customElement(nameOrDef: string | PartialFASTElementDefinition): (type: Constructable<HTMLElement>) => void;
diff --git a/packages/web-components/fast-foundation/src/design-token/design-token.spec.ts b/packages/web-components/fast-foundation/src/design-token/design-token.spec.ts
index db91dd94503..ebb904cda5f 100644
--- a/packages/web-components/fast-foundation/src/design-token/design-token.spec.ts
+++ b/packages/web-components/fast-foundation/src/design-token/design-token.spec.ts
@@ -4,7 +4,6 @@ import { DesignSystem } from "../design-system";
 import { uniqueElementName } from "../test-utilities/fixture";
 import { FoundationElement } from "../foundation-element";
 import { CSSDesignToken, DesignToken, DesignTokenChangeRecord, DesignTokenSubscriber } from "./design-token";
-import { defaultElement } from "./custom-property-manager";
 import spies from "chai-spies";
 
 chia.use(spies);
@@ -54,7 +53,8 @@ describe("A DesignToken", () => {
 
     describe("that is a CSSDesignToken", () => {
         it("should have a createCSS() method that returns a string with the name property formatted as a CSS variable", () => {
-            expect(DesignToken.create<number>("implicit").createCSS()).to.equal("var(--implicit)");
+            const add = () => void 0;
+            expect(DesignToken.create<number>("implicit").createCSS(add)).to.equal("var(--implicit)");
         });
         it("should have a readonly cssCustomProperty property that is the name formatted as a CSS custom property", () => {
             expect(DesignToken.create<number>("implicit").cssCustomProperty).to.equal("--implicit");
diff --git a/packages/web-components/fast-foundation/src/design-token/design-token.ts b/packages/web-components/fast-foundation/src/design-token/design-token.ts
index 9dbbe651091..0a2c562062a 100644
--- a/packages/web-components/fast-foundation/src/design-token/design-token.ts
+++ b/packages/web-components/fast-foundation/src/design-token/design-token.ts
@@ -128,8 +128,8 @@ export interface DesignTokenSubscriber<T extends DesignToken<any>> {
 /**
  * Implementation of {@link (DesignToken:interface)}
  */
-class DesignTokenImpl<T extends { createCSS?(): string }> extends CSSDirective
-    implements DesignToken<T> {
+class DesignTokenImpl<T extends { createCSS?(): string }>
+    implements CSSDirective, DesignToken<T> {
     public readonly name: string;
     public readonly cssCustomProperty: string | undefined;
     public readonly id: string;
@@ -201,8 +201,6 @@ class DesignTokenImpl<T extends { createCSS?(): string }> extends CSSDirective
     }
 
     constructor(configuration: Required<DesignTokenConfiguration>) {
-        super();
-
         this.name = configuration.name;
 
         if (configuration.cssCustomPropertyName !== null) {
@@ -255,7 +253,6 @@ class DesignTokenImpl<T extends { createCSS?(): string }> extends CSSDirective
 
     public withDefault(value: DesignTokenValue<T> | DesignToken<T>) {
         this.setValueFor(defaultElement, value);
-
         return this;
     }
 

From 4d455694337ec25e6db7fb20aa7fe6ed04b139a6 Mon Sep 17 00:00:00 2001
From: Rob Eisenberg <rob@bluespire.com>
Date: Wed, 13 Apr 2022 12:13:46 -0400
Subject: [PATCH 4/7] fix: update components to new CSSDirective API

---
 packages/web-components/fast-components/src/styles/size.ts    | 4 ++--
 .../fast-components/src/tree-item/tree-item.styles.ts         | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/web-components/fast-components/src/styles/size.ts b/packages/web-components/fast-components/src/styles/size.ts
index 2adeff3e4c9..6a715905757 100644
--- a/packages/web-components/fast-components/src/styles/size.ts
+++ b/packages/web-components/fast-components/src/styles/size.ts
@@ -1,4 +1,4 @@
-import { cssPartial } from "@microsoft/fast-element";
+import { css } from "@microsoft/fast-element";
 import { baseHeightMultiplier, density, designUnit } from "../design-tokens.js";
 
 /**
@@ -6,4 +6,4 @@ import { baseHeightMultiplier, density, designUnit } from "../design-tokens.js";
  * Use this as the value of any CSS property that
  * accepts a pixel size.
  */
-export const heightNumber = cssPartial`(${baseHeightMultiplier} + ${density}) * ${designUnit}`;
+export const heightNumber = css.partial`(${baseHeightMultiplier} + ${density}) * ${designUnit}`;
diff --git a/packages/web-components/fast-components/src/tree-item/tree-item.styles.ts b/packages/web-components/fast-components/src/tree-item/tree-item.styles.ts
index 50c444d4b21..6a027e47b8e 100644
--- a/packages/web-components/fast-components/src/tree-item/tree-item.styles.ts
+++ b/packages/web-components/fast-components/src/tree-item/tree-item.styles.ts
@@ -1,4 +1,4 @@
-import { css, cssPartial, ElementStyles } from "@microsoft/fast-element";
+import { css, ElementStyles } from "@microsoft/fast-element";
 import {
     DesignToken,
     disabledCursor,
@@ -68,7 +68,7 @@ const rtl = css`
  * Tree item expand collapse button size CSS Partial
  * @public
  */
-export const expandCollapseButtonSize = cssPartial`((${baseHeightMultiplier} / 2) * ${designUnit}) + ((${designUnit} * ${density}) / 2)`;
+export const expandCollapseButtonSize = css.partial`((${baseHeightMultiplier} / 2) * ${designUnit}) + ((${designUnit} * ${density}) / 2)`;
 
 const expandCollapseHoverBehavior = DesignToken.create<Swatch>(
     "tree-item-expand-collapse-hover"

From 87a49f0dd174be47cb4d2c6081eebfc06409cc87 Mon Sep 17 00:00:00 2001
From: Rob Eisenberg <rob@bluespire.com>
Date: Wed, 13 Apr 2022 12:23:21 -0400
Subject: [PATCH 5/7] docs: add missing docs to CSSTEmplateTag type

---
 packages/web-components/fast-element/docs/api-report.md | 2 +-
 packages/web-components/fast-element/src/styles/css.ts  | 9 +++++++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/packages/web-components/fast-element/docs/api-report.md b/packages/web-components/fast-element/docs/api-report.md
index a93a65dcf0f..dfba4a9c844 100644
--- a/packages/web-components/fast-element/docs/api-report.md
+++ b/packages/web-components/fast-element/docs/api-report.md
@@ -252,7 +252,7 @@ export interface CSSDirectiveDefinition<TType extends Constructable<CSSDirective
     readonly type: TType;
 }
 
-// @public (undocumented)
+// @public
 export type CSSTemplateTag = ((strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]) => ElementStyles) & {
     partial(strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]): CSSDirective;
 };
diff --git a/packages/web-components/fast-element/src/styles/css.ts b/packages/web-components/fast-element/src/styles/css.ts
index 4e5d1111ab4..cf6cd0bdae5 100644
--- a/packages/web-components/fast-element/src/styles/css.ts
+++ b/packages/web-components/fast-element/src/styles/css.ts
@@ -47,6 +47,15 @@ function collectStyles(
     };
 }
 
+/**
+ * Transforms a template literal string into styles.
+ * @param strings - The string fragments that are interpolated with the values.
+ * @param values - The values that are interpolated with the string fragments.
+ * @remarks
+ * The css helper supports interpolation of strings and ElementStyle instances.
+ * Use the .partial method to create partial CSS fragments.
+ * @public
+ */
 export type CSSTemplateTag = ((
     strings: TemplateStringsArray,
     ...values: (ComposableStyles | CSSDirective)[]

From fba59503bc69d7216256a41f3841ad126c49e124 Mon Sep 17 00:00:00 2001
From: EisenbergEffect <roeisenb@microsoft.com>
Date: Wed, 13 Apr 2022 12:49:19 -0400
Subject: [PATCH 6/7] Change files

---
 ...st-components-0f5602ef-a1c2-4f35-83a0-3e883906645e.json | 7 +++++++
 ...-fast-element-e7b9adf7-1b40-4e7e-896f-c29600f26654.json | 7 +++++++
 ...st-foundation-b8a22db2-e6e3-4ba0-a9e1-725a4ef68eda.json | 7 +++++++
 3 files changed, 21 insertions(+)
 create mode 100644 change/@microsoft-fast-components-0f5602ef-a1c2-4f35-83a0-3e883906645e.json
 create mode 100644 change/@microsoft-fast-element-e7b9adf7-1b40-4e7e-896f-c29600f26654.json
 create mode 100644 change/@microsoft-fast-foundation-b8a22db2-e6e3-4ba0-a9e1-725a4ef68eda.json

diff --git a/change/@microsoft-fast-components-0f5602ef-a1c2-4f35-83a0-3e883906645e.json b/change/@microsoft-fast-components-0f5602ef-a1c2-4f35-83a0-3e883906645e.json
new file mode 100644
index 00000000000..cd5498091d8
--- /dev/null
+++ b/change/@microsoft-fast-components-0f5602ef-a1c2-4f35-83a0-3e883906645e.json
@@ -0,0 +1,7 @@
+{
+  "type": "major",
+  "comment": "fix: update components to new CSSDirective API",
+  "packageName": "@microsoft/fast-components",
+  "email": "roeisenb@microsoft.com",
+  "dependentChangeType": "patch"
+}
diff --git a/change/@microsoft-fast-element-e7b9adf7-1b40-4e7e-896f-c29600f26654.json b/change/@microsoft-fast-element-e7b9adf7-1b40-4e7e-896f-c29600f26654.json
new file mode 100644
index 00000000000..009620dbe59
--- /dev/null
+++ b/change/@microsoft-fast-element-e7b9adf7-1b40-4e7e-896f-c29600f26654.json
@@ -0,0 +1,7 @@
+{
+  "type": "major",
+  "comment": "feat: new CSSDirective design",
+  "packageName": "@microsoft/fast-element",
+  "email": "roeisenb@microsoft.com",
+  "dependentChangeType": "patch"
+}
diff --git a/change/@microsoft-fast-foundation-b8a22db2-e6e3-4ba0-a9e1-725a4ef68eda.json b/change/@microsoft-fast-foundation-b8a22db2-e6e3-4ba0-a9e1-725a4ef68eda.json
new file mode 100644
index 00000000000..3251b611cb7
--- /dev/null
+++ b/change/@microsoft-fast-foundation-b8a22db2-e6e3-4ba0-a9e1-725a4ef68eda.json
@@ -0,0 +1,7 @@
+{
+  "type": "major",
+  "comment": "fix: update foundation to new CSSDirective API",
+  "packageName": "@microsoft/fast-foundation",
+  "email": "roeisenb@microsoft.com",
+  "dependentChangeType": "patch"
+}

From 9da4e811e7b87b1af53b861cad1de5af59476dde Mon Sep 17 00:00:00 2001
From: Rob Eisenberg <rob@bluespire.com>
Date: Mon, 18 Apr 2022 18:42:56 -0400
Subject: [PATCH 7/7] fix: add back cssPartial with deprecation message

---
 packages/web-components/fast-element/docs/api-report.md | 3 +++
 packages/web-components/fast-element/src/styles/css.ts  | 6 ++++++
 2 files changed, 9 insertions(+)

diff --git a/packages/web-components/fast-element/docs/api-report.md b/packages/web-components/fast-element/docs/api-report.md
index dfba4a9c844..bd7eb0c6006 100644
--- a/packages/web-components/fast-element/docs/api-report.md
+++ b/packages/web-components/fast-element/docs/api-report.md
@@ -252,6 +252,9 @@ export interface CSSDirectiveDefinition<TType extends Constructable<CSSDirective
     readonly type: TType;
 }
 
+// @public @deprecated (undocumented)
+export const cssPartial: (strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]) => CSSDirective;
+
 // @public
 export type CSSTemplateTag = ((strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]) => ElementStyles) & {
     partial(strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]): CSSDirective;
diff --git a/packages/web-components/fast-element/src/styles/css.ts b/packages/web-components/fast-element/src/styles/css.ts
index cf6cd0bdae5..a9477776eb0 100644
--- a/packages/web-components/fast-element/src/styles/css.ts
+++ b/packages/web-components/fast-element/src/styles/css.ts
@@ -146,3 +146,9 @@ css.partial = (
     const { styles, behaviors } = collectStyles(strings, values);
     return new CSSPartial(styles, behaviors);
 };
+
+/**
+ * @deprecated Use css.partial instead.
+ * @public
+ */
+export const cssPartial = css.partial;