feat: DesignToken refactor for FF3 (#6171)

* adding interfaces for new API structure

* adding tests for appendChild / removeChild

* add a stub implementation of DesignToken

* adding minimal design token interface

* save-progress

* adding notification logic

* re-organize notification propagation logic

* adding getTokenValue and tests

* add notification behavior to appndChild

* refactor to use string id

* rename method to retrieve all tokens for a node

* refactor to fix chai bug and issues uncovered when avoiding chai issue

* refactor a bit to centralize notifier for tokens on the token object itself

* adding new test for no notification when assigned the same value

* fixing test

* adding subscription test

* implement isAssigned

* progress on derived tokens

* implement mechanism to notify of static token changes

* make derived token assignments notify down the token tree

* adding and adapting test-cases from original DesignToken implementation

* re-organization of DesignTokenNode

* adding observable map to notify for derived values

* naieve implementation of reflecting upstream derived tokens

* re-oragnize feature and add exports to facilitate testing

* implement circular reference resolution and made a few perf changes

* adding another circular reference test

* adding deleteTokenValue API and privatizing isDerivedFor

* adding subscription tests

* update test names

* further test clean up

* more tests and slight performance improvement

* method organization

* remove observableMap implementation to provide better control over token notification, adds a few tests

* implement more specific notification behavior

* fixing test so it passes w/ new notification behavior

* adding test package

* adds behavior to handle observable value updates

* adding additional observable tests

* refactor token notification to contain mutation type data

* refactor notifications and fix token deletion tests

* adding notification behavior to appending a node

* update readme with perf improvement notes

* in-progress changes for node notification on removal of token and refactoring notification to be single-pass

* refactor notification behavior and fix all test

* batch notifications so the tree is reconciled before subscribers are notified of a change

* implement DesignToken over top of DesignTokenNode, CSS reflection

* isolate design token core from FAST design token implementation

* implement root registration

* Ensure nodes for detached elements can access the defualt node

* passing all tests

* fixing tests

* fixing import

* a bit of cleanup

* refactor type constraints that opens up exporting the token classes instead of an interface/const

* re-organizing files

* re-organize assets, exports, and files. delete legacy design-token

* fix bug in recursive reconciliation of tokens

* update adaptive UI package

* consolidate notification queue

* add children notifier function

* make CSSDesignToken a real CSSDirective

* fixing circular dependency notification bug

* fixing bug in CSS design token css value calculation

* implement observable derived value structure

* refactor to not itterate through all derived values during update

* improving performance of derived tokens

* fixing example

* removing un-necessary method

* adding css directive test

* create tokens with unique name

* lazily create subscriber set for tokens

* implement resolution strategy

* removing debugging spies

* fixing bug in observable bindings where the watcher was not reset if the binding threw

* fixing memory leak caused by observable subscribers

* cleaning up design-token-node tests

* removing tests for scenario that is no longer supported

* adding method comments

* remove test package

* fixing after rebase

* Change files

* Update change/@microsoft-adaptive-ui-881bac8a-4800-4331-9138-0c658998c854.json

* Update change/@microsoft-fast-element-2a4431cf-f1de-44ed-bae4-392f10b74b86.json

* Update change/@microsoft-fast-foundation-d9cdf375-e6b7-4a6e-87e6-81dc37d60605.json

* removing test site from workspaces

* removing readme that is getting processesd by custom element manifest script

* adding API documentation

* removing notes file

* fixing build

* Update change/@microsoft-fast-foundation-d9cdf375-e6b7-4a6e-87e6-81dc37d60605.json

Co-authored-by: Jane Chu <7559015+janechu@users.noreply.github.com>

* Update packages/web-components/fast-foundation/src/design-token/fast-design-token.ts

Co-authored-by: Jane Chu <7559015+janechu@users.noreply.github.com>

Co-authored-by: nicholasrice <nicholasrice@users.noreply.github.com>
Co-authored-by: Jane Chu <7559015+janechu@users.noreply.github.com>

change/@microsoft-adaptive-ui-881bac8a-4800-4331-9138-0c658998c854.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Update design tokens to use new resolve function",
+  "packageName": "@microsoft/adaptive-ui",
+  "email": "nicholasrice@users.noreply.github.com",
+  "dependentChangeType": "prerelease"
+}

change/@microsoft-fast-element-2a4431cf-f1de-44ed-bae4-392f10b74b86.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Fix ExpressionObserer bug where watcher was not reset if the binding threw",
+  "packageName": "@microsoft/fast-element",
+  "email": "nicholasrice@users.noreply.github.com",
+  "dependentChangeType": "prerelease"
+}

change/@microsoft-fast-foundation-d9cdf375-e6b7-4a6e-87e6-81dc37d60605.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Refactor DesignToken to provide a resolve function to derived token values, implements WebComponent implementation on top of isomorphic DesignToken infrastructure",
+  "packageName": "@microsoft/fast-foundation",
+  "email": "nicholasrice@users.noreply.github.com",
+  "dependentChangeType": "prerelease"
+}

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

@@ -7,6 +7,7 @@
 import { CSSDesignToken } from '@microsoft/fast-foundation';
 import { CSSDirective } from '@microsoft/fast-element';
 import { DesignToken } from '@microsoft/fast-foundation';
+import { DesignTokenResolver } from '@microsoft/fast-foundation';
 import { Direction } from '@microsoft/fast-web-utilities';
 
 // @public (undocumented)
@@ -111,7 +112,7 @@ export const bodyFont: CSSDesignToken<string>;
 
 // @public
 export interface ColorRecipe {
-    evaluate(element: HTMLElement, reference?: Swatch): Swatch;
+    evaluate(resolver: DesignTokenResolver, reference?: Swatch): Swatch;
 }
 
 // @public
@@ -185,7 +186,7 @@ export const elevationFlyoutSize: DesignToken<number>;
 
 // @public
 export interface ElevationRecipe {
-    evaluate(element: HTMLElement, size: number): string;
+    evaluate(resolver: DesignTokenResolver, size: number): string;
 }
 
 // @public (undocumented)
@@ -238,7 +239,7 @@ export function idealColorDeltaSwatchSet(palette: Palette, reference: Swatch, mi
 
 // @public
 export interface InteractiveColorRecipe {
-    evaluate(element: HTMLElement, reference?: Swatch): InteractiveSwatchSet;
+    evaluate(resolver: DesignTokenResolver, reference?: Swatch): InteractiveSwatchSet;
 }
 
 // @public

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

@@ -1,3 +1,4 @@
+import { DesignTokenResolver } from "@microsoft/fast-foundation";
 import { Swatch } from "./swatch.js";
 
 /**
@@ -9,10 +10,10 @@ export interface ColorRecipe {
     /**
      * Evaluate a single color value.
      *
-     * @param element - The element for which to evaluate the color recipe
+     * @param resolver - A function that resolves design tokens
      * @param reference - The reference color, implementation defaults to `fillColor`, but sometimes overridden for nested color recipes
      */
-    evaluate(element: HTMLElement, reference?: Swatch): Swatch;
+    evaluate(resolver: DesignTokenResolver, reference?: Swatch): Swatch;
 }
 
 /**
@@ -24,10 +25,10 @@ export interface InteractiveColorRecipe {
     /**
      * Evaluate an interactive color set.
      *
-     * @param element - The element for which to evaluate the color recipe
+     * @param resolver - A function that resolves design tokens
      * @param reference - The reference color, implementation defaults to `fillColor`, but sometimes overridden for nested color recipes
      */
-    evaluate(element: HTMLElement, reference?: Swatch): InteractiveSwatchSet;
+    evaluate(resolver: DesignTokenResolver, reference?: Swatch): InteractiveSwatchSet;
 }
 
 /**