From 5ee2952659b6a7f2e692a11572dad2caec0214c6 Mon Sep 17 00:00:00 2001
From: AK <144495202+AKnassa@users.noreply.github.com>
Date: Mon, 13 Jul 2026 03:16:56 -0400
Subject: [PATCH 1/2] feat: add ElementStyles.styleNonce for strict Content
 Security Policy

Injected <style> elements carried no nonce, so under a strict style-src
(no 'unsafe-inline') the browser blocked them. Applications can now set
`ElementStyles.styleNonce` (mirrored on FASTElement) and it is stamped onto
every style element FAST creates.

The nonce is read lazily at style-application time, because `css` templates
build their ElementStyles at module evaluation, long before application code runs.

Fixes #5444
---
 ...oft-fast-element-5444-csp-style-nonce.json |   7 +
 packages/fast-element/README.md               |  24 ++
 packages/fast-element/SIZES.md                |  12 +-
 packages/fast-element/docs/api-report.api.md  |   3 +
 .../docs/declarative/api-report.api.md        |   2 +
 .../src/components/element-controller.ts      |  10 +
 .../src/components/fast-element.ts            |  23 +-
 .../fast-element/src/styles/element-styles.ts |  31 ++
 .../fast-element/src/styles/styles.pw.spec.ts | 372 ++++++++++++++++++
 .../3.x/api/fast-element.elementstyles.md     |  21 +
 .../fast-element.elementstyles.stylenonce.md  |  30 ++
 .../fast-element.fastelementconstructor.md    |  44 +++
 ...ement.fastelementconstructor.stylenonce.md |  24 ++
 .../declarative/fast-element.elementstyles.md |  21 +
 .../fast-element.elementstyles.stylenonce.md  |  30 ++
 .../src/docs/3.x/resources/export-sizes.md    |  12 +-
 16 files changed, 650 insertions(+), 16 deletions(-)
 create mode 100644 change/@microsoft-fast-element-5444-csp-style-nonce.json
 create mode 100644 sites/website/src/docs/3.x/api/fast-element.elementstyles.stylenonce.md
 create mode 100644 sites/website/src/docs/3.x/api/fast-element.fastelementconstructor.stylenonce.md
 create mode 100644 sites/website/src/docs/3.x/api/fast-element/declarative/fast-element.elementstyles.stylenonce.md

diff --git a/change/@microsoft-fast-element-5444-csp-style-nonce.json b/change/@microsoft-fast-element-5444-csp-style-nonce.json
new file mode 100644
index 00000000000..712f9810540
--- /dev/null
+++ b/change/@microsoft-fast-element-5444-csp-style-nonce.json
@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Add ElementStyles.styleNonce (aliased as FASTElement.styleNonce) to apply a Content Security Policy nonce to injected style elements.",
+  "packageName": "@microsoft/fast-element",
+  "email": "144495202+AKnassa@users.noreply.github.com",
+  "dependentChangeType": "none"
+}
diff --git a/packages/fast-element/README.md b/packages/fast-element/README.md
index 2ac45a7e9c9..dfaba8ffff4 100644
--- a/packages/fast-element/README.md
+++ b/packages/fast-element/README.md
@@ -279,3 +279,27 @@ class MyComponent extends FASTElement {
 MyComponent.define({ name: "my-component", template, styles }, [logger()]);
 ```
 Each extension receives the full `FASTElementDefinition`, which includes the resolved element name, type, template, styles, and attribute metadata. Extensions run before `customElements.define()`, so any setup they perform is available when existing DOM elements are upgraded.
+
+## Security
+
+### Content Security Policy
+
+Where the browser supports [adopted stylesheets](https://developer.mozilla.org/docs/Web/API/Document/adoptedStyleSheets), FAST Element applies component styles by adopting constructed stylesheets. Those are not inline styles, so they are not subject to the `style-src` directive and need no additional configuration.
+
+When adopted stylesheets are unavailable, styles are applied by injecting `<style>` elements instead. Under a strict Content Security Policy — a `style-src` without `'unsafe-inline'` — those elements are blocked unless they carry the policy's nonce. Set `ElementStyles.styleNonce` to the nonce your server emits and it will be applied to every `<style>` element FAST Element creates:
+
+```ts
+import { ElementStyles } from "@microsoft/fast-element";
+
+ElementStyles.styleNonce = "{nonce}";
+```
+
+`FASTElement.styleNonce` is an alias of the same value, so either may be used:
+
+```ts
+import { FASTElement } from "@microsoft/fast-element";
+
+FASTElement.styleNonce = "{nonce}";
+```
+
+The nonce is read each time styles are applied rather than when they are created. Because `css` tagged templates are usually evaluated at module scope, the nonce can be configured after those styles exist — it only needs to be set before the elements using them are connected.
diff --git a/packages/fast-element/SIZES.md b/packages/fast-element/SIZES.md
index 92d854e5126..24c71e3ff01 100644
--- a/packages/fast-element/SIZES.md
+++ b/packages/fast-element/SIZES.md
@@ -4,8 +4,8 @@ Bundle sizes for `@microsoft/fast-element` exports.
 
 | Export | Minified | Gzip | Brotli |
 |--------|----------|------|--------|
-| CDN Rollup Bundle | 78.61 KB | 23.40 KB | 20.77 KB |
-| FASTElement (@microsoft/fast-element/fast-element.js) | 23.11 KB | 7.12 KB | 6.41 KB |
+| CDN Rollup Bundle | 78.86 KB | 23.48 KB | 20.84 KB |
+| FASTElement (@microsoft/fast-element/fast-element.js) | 23.34 KB | 7.23 KB | 6.49 KB |
 | Updates (@microsoft/fast-element/updates.js) | 473 B | 335 B | 290 B |
 | Observable (@microsoft/fast-element/observable.js) | 6.75 KB | 2.51 KB | 2.23 KB |
 | observable (@microsoft/fast-element/observable.js) | 6.79 KB | 2.52 KB | 2.24 KB |
@@ -17,9 +17,9 @@ Bundle sizes for `@microsoft/fast-element` exports.
 | when (@microsoft/fast-element/when.js) | 1.88 KB | 731 B | 589 B |
 | html (@microsoft/fast-element/html.js) | 27.73 KB | 8.96 KB | 8.02 KB |
 | repeat (@microsoft/fast-element/repeat.js) | 31.80 KB | 10.00 KB | 9.03 KB |
-| css (@microsoft/fast-element/css.js) | 2.43 KB | 1.00 KB | 911 B |
-| enableHydration (@microsoft/fast-element/hydration.js) | 46.53 KB | 13.91 KB | 12.49 KB |
+| css (@microsoft/fast-element/css.js) | 2.53 KB | 1.05 KB | 951 B |
+| enableHydration (@microsoft/fast-element/hydration.js) | 46.68 KB | 13.98 KB | 12.55 KB |
 | declarativeTemplate (@microsoft/fast-element/declarative.js) | 62.15 KB | 19.46 KB | 17.42 KB |
 | ArrayObserver (@microsoft/fast-element/arrays.js) | 12.55 KB | 4.46 KB | 4.03 KB |
-| observerMap (@microsoft/fast-element/observer-map.js) | 21.96 KB | 7.73 KB | 6.97 KB |
-| attributeMap (@microsoft/fast-element/attribute-map.js) | 15.31 KB | 5.41 KB | 4.88 KB |
+| observerMap (@microsoft/fast-element/observer-map.js) | 22.07 KB | 7.77 KB | 7.00 KB |
+| attributeMap (@microsoft/fast-element/attribute-map.js) | 15.42 KB | 5.46 KB | 4.91 KB |
diff --git a/packages/fast-element/docs/api-report.api.md b/packages/fast-element/docs/api-report.api.md
index 5a660bf37f0..69090b68b49 100644
--- a/packages/fast-element/docs/api-report.api.md
+++ b/packages/fast-element/docs/api-report.api.md
@@ -434,6 +434,8 @@ export class ElementStyles {
     removeStylesFrom(target: StyleTarget): void;
     static setDefaultStrategy(Strategy: ConstructibleStyleStrategy): void;
     get strategy(): StyleStrategy;
+    static get styleNonce(): string | null;
+    static set styleNonce(value: string | null);
     // (undocumented)
     readonly styles: ReadonlyArray<ComposableStyles>;
     static readonly supportsAdoptedStyleSheets: boolean;
@@ -543,6 +545,7 @@ export interface FASTElementConstructor {
     from<TBase extends typeof HTMLElement>(BaseType: TBase): {
         new (): InstanceType<TBase> & FASTElement;
     };
+    styleNonce: string | null;
 }
 
 // @public
diff --git a/packages/fast-element/docs/declarative/api-report.api.md b/packages/fast-element/docs/declarative/api-report.api.md
index cd1f7e08af9..ad0bf78c67e 100644
--- a/packages/fast-element/docs/declarative/api-report.api.md
+++ b/packages/fast-element/docs/declarative/api-report.api.md
@@ -167,6 +167,8 @@ export class ElementStyles {
     removeStylesFrom(target: StyleTarget): void;
     static setDefaultStrategy(Strategy: ConstructibleStyleStrategy): void;
     get strategy(): StyleStrategy;
+    static get styleNonce(): string | null;
+    static set styleNonce(value: string | null);
     // (undocumented)
     readonly styles: ReadonlyArray<ComposableStyles>;
     static readonly supportsAdoptedStyleSheets: boolean;
diff --git a/packages/fast-element/src/components/element-controller.ts b/packages/fast-element/src/components/element-controller.ts
index 4c0ce799b48..ce35b51f9ba 100644
--- a/packages/fast-element/src/components/element-controller.ts
+++ b/packages/fast-element/src/components/element-controller.ts
@@ -1006,11 +1006,21 @@ export class StyleElementStrategy implements StyleStrategy {
 
         const styles = this.styles;
         const styleClass = this.styleClass;
+        // Read the nonce here rather than in the constructor, since styles are
+        // usually created at module scope, before an app can configure a nonce.
+        const nonce = ElementStyles.styleNonce;
 
         for (let i = 0; i < styles.length; i++) {
             const element = document.createElement("style");
             element.innerHTML = styles[i];
             element.className = styleClass;
+
+            if (nonce) {
+                // Must be set before the element is appended, since that is when
+                // the Content Security Policy is evaluated against it.
+                element.setAttribute("nonce", nonce);
+            }
+
             target.append(element);
         }
     }
diff --git a/packages/fast-element/src/components/fast-element.ts b/packages/fast-element/src/components/fast-element.ts
index 0becd961017..1040a8ba615 100644
--- a/packages/fast-element/src/components/fast-element.ts
+++ b/packages/fast-element/src/components/fast-element.ts
@@ -1,4 +1,5 @@
 import { type Constructable, isFunction } from "../interfaces.js";
+import { ElementStyles } from "../styles/element-styles.js";
 import { ElementController } from "./element-controller.js";
 import {
     applyFASTElementExtensions,
@@ -196,6 +197,12 @@ export interface FASTElementConstructor {
     from<TBase extends typeof HTMLElement>(
         BaseType: TBase,
     ): { new (): InstanceType<TBase> & FASTElement };
+
+    /**
+     * The nonce to apply to style elements created when styles are applied with
+     * a style element based strategy. An alias of {@link ElementStyles.styleNonce}.
+     */
+    styleNonce: string | null;
 }
 
 /**
@@ -203,9 +210,8 @@ export interface FASTElementConstructor {
  * static helpers for working with FASTElements.
  * @public
  */
-export const FASTElement: FASTElementConstructor = Object.assign(
-    createFASTElement(HTMLElement),
-    {
+export const FASTElement: FASTElementConstructor = Object.defineProperty(
+    Object.assign(createFASTElement(HTMLElement), {
         /**
          * Creates a new FASTElement base class inherited from the
          * provided base type.
@@ -220,8 +226,17 @@ export const FASTElement: FASTElementConstructor = Object.assign(
          * that describes the element to define.
          */
         define,
+    }),
+    // Defined as an accessor that forwards to ElementStyles so that the nonce has
+    // a single source of truth. Object.assign would copy the value, not the accessor.
+    "styleNonce",
+    {
+        get: (): string | null => ElementStyles.styleNonce,
+        set: (value: string | null) => {
+            ElementStyles.styleNonce = value;
+        },
     },
-);
+) as FASTElementConstructor;
 
 /**
  * Decorator: Defines a platform custom element based on `FASTElement`.
diff --git a/packages/fast-element/src/styles/element-styles.ts b/packages/fast-element/src/styles/element-styles.ts
index c840e3269be..fb98f1c9a20 100644
--- a/packages/fast-element/src/styles/element-styles.ts
+++ b/packages/fast-element/src/styles/element-styles.ts
@@ -19,6 +19,7 @@ export type ConstructibleStyleStrategy = {
 };
 
 let DefaultStyleStrategy: ConstructibleStyleStrategy | undefined;
+let styleNonce: string | null = null;
 
 function reduceStyles(
     styles: ReadonlyArray<ComposableStyles>,
@@ -100,6 +101,30 @@ export class ElementStyles {
         DefaultStyleStrategy = Strategy;
     }
 
+    /**
+     * The nonce to apply to style elements created when styles are applied
+     * with a style element based strategy. Set this to the nonce of the page's
+     * Content Security Policy to allow the styles under a strict `style-src`
+     * that does not include `'unsafe-inline'`. Styles applied with adopted
+     * style sheets are not subject to `style-src` and are unaffected.
+     *
+     * @remarks
+     * The nonce is read each time styles are applied, so it can be configured
+     * after styles have been created. This matters because `css` tagged
+     * templates are typically evaluated at module scope, long before an
+     * application has a chance to set the nonce.
+     */
+    public static get styleNonce(): string | null {
+        return styleNonce;
+    }
+
+    public static set styleNonce(value: string | null) {
+        // Normalized so that a nonce sourced from the DOM by a JS consumer, eg.
+        // document.querySelector("meta[name=csp-nonce]")?.content, cannot leave
+        // undefined behind for the getter to hand back.
+        styleNonce = value ?? null;
+    }
+
     /**
      * Normalizes a set of composable style options.
      * @param styles - The style options to normalize.
@@ -179,11 +204,17 @@ function createStyleElementStrategy(): ConstructibleStyleStrategy {
 
         addStylesTo(target: StyleTarget): void {
             const t = target === (document as any) ? document.body : target;
+            const nonce = styleNonce;
 
             for (let i = 0; i < this.styles.length; i++) {
                 const element = document.createElement("style");
                 element.innerHTML = this.styles[i];
                 element.className = this.styleClass;
+
+                if (nonce) {
+                    element.setAttribute("nonce", nonce);
+                }
+
                 (t as any).append(element);
             }
         }
diff --git a/packages/fast-element/src/styles/styles.pw.spec.ts b/packages/fast-element/src/styles/styles.pw.spec.ts
index 0c78210a192..5252af8c907 100644
--- a/packages/fast-element/src/styles/styles.pw.spec.ts
+++ b/packages/fast-element/src/styles/styles.pw.spec.ts
@@ -1002,3 +1002,375 @@ test.describe("cssPartial", () => {
         expect(isElementStyles).toBe(true);
     });
 });
+
+test.describe("ElementStyles.styleNonce", () => {
+    test("should not set a nonce attribute when no nonce is configured", async ({
+        page,
+    }) => {
+        await page.goto("/");
+
+        const hasNonce = await page.evaluate(async () => {
+            // @ts-expect-error: Client module.
+            const { StyleElementStrategy } = await import("/main.js");
+
+            const strategy = new StyleElementStrategy([":host{color:red}"]);
+            const shadowRoot = document
+                .createElement("div")
+                .attachShadow({ mode: "open" });
+
+            strategy.addStylesTo(shadowRoot);
+
+            return (shadowRoot.childNodes[0] as HTMLStyleElement).hasAttribute("nonce");
+        });
+
+        expect(hasNonce).toBe(false);
+    });
+
+    test("should apply a nonce configured after the ElementStyles are constructed", async ({
+        page,
+    }) => {
+        await page.goto("/");
+
+        const { attribute, property } = await page.evaluate(async () => {
+            // @ts-expect-error: Client module.
+            const { ElementStyles, StyleElementStrategy } = await import("/main.js");
+
+            // The styles are constructed *before* the nonce is configured, which
+            // is what happens when a `css` tagged template is evaluated at module
+            // scope. The nonce must therefore be read when the styles are applied.
+            const elementStyles = new ElementStyles([":host{color:red}"]).withStrategy(
+                StyleElementStrategy,
+            );
+
+            ElementStyles.styleNonce = "test-nonce";
+
+            const shadowRoot = document
+                .createElement("div")
+                .attachShadow({ mode: "open" });
+
+            elementStyles.addStylesTo(shadowRoot);
+
+            const element = shadowRoot.childNodes[0] as HTMLStyleElement;
+
+            return {
+                attribute: element.getAttribute("nonce"),
+                property: element.nonce,
+            };
+        });
+
+        expect(attribute).toBe("test-nonce");
+        expect(property).toBe("test-nonce");
+    });
+
+    test("should apply a nonce to styles created by the css tagged template", async ({
+        page,
+    }) => {
+        await page.goto("/");
+
+        const nonce = await page.evaluate(async () => {
+            // @ts-expect-error: Client module.
+            const { css, ElementStyles, StyleElementStrategy } = await import("/main.js");
+
+            const styles = css`
+                :host {
+                    color: red;
+                }
+            `.withStrategy(StyleElementStrategy);
+
+            ElementStyles.styleNonce = "css-nonce";
+
+            const shadowRoot = document
+                .createElement("div")
+                .attachShadow({ mode: "open" });
+
+            styles.addStylesTo(shadowRoot);
+
+            return (shadowRoot.childNodes[0] as HTMLStyleElement).getAttribute("nonce");
+        });
+
+        expect(nonce).toBe("css-nonce");
+    });
+
+    test("should apply the nonce to every style element that is created", async ({
+        page,
+    }) => {
+        await page.goto("/");
+
+        const nonces = await page.evaluate(async () => {
+            // @ts-expect-error: Client module.
+            const { ElementStyles, StyleElementStrategy } = await import("/main.js");
+
+            ElementStyles.styleNonce = "multi-nonce";
+
+            const strategy = new StyleElementStrategy([
+                "body{color:red;}",
+                "body{color:green;}",
+            ]);
+            const shadowRoot = document
+                .createElement("div")
+                .attachShadow({ mode: "open" });
+
+            strategy.addStylesTo(shadowRoot);
+
+            return Array.from(shadowRoot.querySelectorAll("style")).map(x =>
+                x.getAttribute("nonce"),
+            );
+        });
+
+        expect(nonces).toEqual(["multi-nonce", "multi-nonce"]);
+    });
+
+    test("should read the nonce on every application rather than caching it", async ({
+        page,
+    }) => {
+        await page.goto("/");
+
+        const { first, second } = await page.evaluate(async () => {
+            // @ts-expect-error: Client module.
+            const { ElementStyles, StyleElementStrategy } = await import("/main.js");
+
+            const strategy = new StyleElementStrategy([":host{color:red}"]);
+            const createShadowRoot = () =>
+                document.createElement("div").attachShadow({ mode: "open" });
+
+            ElementStyles.styleNonce = "first-nonce";
+            const firstTarget = createShadowRoot();
+            strategy.addStylesTo(firstTarget);
+
+            ElementStyles.styleNonce = "second-nonce";
+            const secondTarget = createShadowRoot();
+            strategy.addStylesTo(secondTarget);
+
+            return {
+                first: (firstTarget.childNodes[0] as HTMLStyleElement).getAttribute(
+                    "nonce",
+                ),
+                second: (secondTarget.childNodes[0] as HTMLStyleElement).getAttribute(
+                    "nonce",
+                ),
+            };
+        });
+
+        expect(first).toBe("first-nonce");
+        expect(second).toBe("second-nonce");
+    });
+
+    test("should stop applying a nonce when the nonce is reset to null", async ({
+        page,
+    }) => {
+        await page.goto("/");
+
+        const { withNonce, afterReset } = await page.evaluate(async () => {
+            // @ts-expect-error: Client module.
+            const { ElementStyles, StyleElementStrategy } = await import("/main.js");
+
+            const strategy = new StyleElementStrategy([":host{color:red}"]);
+            const createShadowRoot = () =>
+                document.createElement("div").attachShadow({ mode: "open" });
+
+            ElementStyles.styleNonce = "temporary-nonce";
+            const withNonceTarget = createShadowRoot();
+            strategy.addStylesTo(withNonceTarget);
+
+            ElementStyles.styleNonce = null;
+            const afterResetTarget = createShadowRoot();
+            strategy.addStylesTo(afterResetTarget);
+
+            return {
+                withNonce: (
+                    withNonceTarget.childNodes[0] as HTMLStyleElement
+                ).hasAttribute("nonce"),
+                afterReset: (
+                    afterResetTarget.childNodes[0] as HTMLStyleElement
+                ).hasAttribute("nonce"),
+            };
+        });
+
+        expect(withNonce).toBe(true);
+        expect(afterReset).toBe(false);
+    });
+
+    test("should default to a null nonce", async ({ page }) => {
+        await page.goto("/");
+
+        const nonce = await page.evaluate(async () => {
+            // @ts-expect-error: Client module.
+            const { ElementStyles } = await import("/main.js");
+
+            return ElementStyles.styleNonce;
+        });
+
+        expect(nonce).toBe(null);
+    });
+
+    test("should still remove nonced style elements from a target", async ({ page }) => {
+        await page.goto("/");
+
+        const afterRemoveLength = await page.evaluate(async () => {
+            // @ts-expect-error: Client module.
+            const { ElementStyles, StyleElementStrategy } = await import("/main.js");
+
+            ElementStyles.styleNonce = "remove-nonce";
+
+            const strategy = new StyleElementStrategy([":host{color:red}"]);
+            const shadowRoot = document
+                .createElement("div")
+                .attachShadow({ mode: "open" });
+
+            strategy.addStylesTo(shadowRoot);
+            strategy.removeStylesFrom(shadowRoot);
+
+            return shadowRoot.childNodes.length;
+        });
+
+        expect(afterRemoveLength).toBe(0);
+    });
+
+    test("should apply the nonce to styles applied to a FASTElement shadow root", async ({
+        page,
+    }) => {
+        await page.goto("/");
+
+        const nonce = await page.evaluate(async () => {
+            const {
+                css,
+                ElementStyles,
+                FASTElement,
+                html,
+                StyleElementStrategy,
+                uniqueElementName,
+            } =
+                // @ts-expect-error: Client module.
+                await import("/main.js");
+
+            const styles = css`
+                :host {
+                    color: red;
+                }
+            `.withStrategy(StyleElementStrategy);
+
+            ElementStyles.styleNonce = "element-nonce";
+
+            const name = uniqueElementName();
+
+            await FASTElement.define({
+                name,
+                template: html`
+                    <p></p>
+                `,
+                styles,
+            });
+
+            const element = document.createElement(name);
+            document.body.appendChild(element);
+
+            const style = element.shadowRoot!.querySelector("style")!;
+            const result = style.getAttribute("nonce");
+
+            document.body.removeChild(element);
+
+            return result;
+        });
+
+        expect(nonce).toBe("element-nonce");
+    });
+
+    test("should be mirrored by FASTElement.styleNonce", async ({ page }) => {
+        await page.goto("/");
+
+        const { fromFASTElement, fromElementStyles } = await page.evaluate(async () => {
+            // @ts-expect-error: Client module.
+            const { ElementStyles, FASTElement } = await import("/main.js");
+
+            FASTElement.styleNonce = "mirrored-nonce";
+            const fromElementStyles = ElementStyles.styleNonce;
+
+            ElementStyles.styleNonce = "reverse-nonce";
+            const fromFASTElement = FASTElement.styleNonce;
+
+            return { fromFASTElement, fromElementStyles };
+        });
+
+        expect(fromElementStyles).toBe("mirrored-nonce");
+        expect(fromFASTElement).toBe("reverse-nonce");
+    });
+
+    test("should not create style elements when there are no styles", async ({
+        page,
+    }) => {
+        await page.goto("/");
+
+        const childCount = await page.evaluate(async () => {
+            // @ts-expect-error: Client module.
+            const { ElementStyles, StyleElementStrategy } = await import("/main.js");
+
+            ElementStyles.styleNonce = "empty-nonce";
+
+            const strategy = new StyleElementStrategy([]);
+            const shadowRoot = document
+                .createElement("div")
+                .attachShadow({ mode: "open" });
+
+            strategy.addStylesTo(shadowRoot);
+
+            return shadowRoot.childNodes.length;
+        });
+
+        expect(childCount).toBe(0);
+    });
+    test("should not set a nonce attribute when the nonce is undefined", async ({
+        page,
+    }) => {
+        await page.goto("/");
+
+        const { hasNonce, nonce } = await page.evaluate(async () => {
+            // @ts-expect-error: Client module.
+            const { ElementStyles, StyleElementStrategy } = await import("/main.js");
+
+            // A JS consumer sourcing the nonce from the DOM gets undefined when
+            // the element is missing, eg. document.querySelector(...)?.content
+            ElementStyles.styleNonce = undefined;
+
+            const strategy = new StyleElementStrategy([":host{color:red}"]);
+            const shadowRoot = document
+                .createElement("div")
+                .attachShadow({ mode: "open" });
+
+            strategy.addStylesTo(shadowRoot);
+
+            return {
+                hasNonce: (shadowRoot.childNodes[0] as HTMLStyleElement).hasAttribute(
+                    "nonce",
+                ),
+                nonce: ElementStyles.styleNonce,
+            };
+        });
+
+        expect(hasNonce).toBe(false);
+        expect(nonce).toBe(null);
+    });
+
+    test("should not set a nonce attribute when the nonce is an empty string", async ({
+        page,
+    }) => {
+        await page.goto("/");
+
+        const hasNonce = await page.evaluate(async () => {
+            // @ts-expect-error: Client module.
+            const { ElementStyles, StyleElementStrategy } = await import("/main.js");
+
+            ElementStyles.styleNonce = "";
+
+            const strategy = new StyleElementStrategy([":host{color:red}"]);
+            const shadowRoot = document
+                .createElement("div")
+                .attachShadow({ mode: "open" });
+
+            strategy.addStylesTo(shadowRoot);
+
+            return (shadowRoot.childNodes[0] as HTMLStyleElement).hasAttribute("nonce");
+        });
+
+        expect(hasNonce).toBe(false);
+    });
+});
diff --git a/sites/website/src/docs/3.x/api/fast-element.elementstyles.md b/sites/website/src/docs/3.x/api/fast-element.elementstyles.md
index 7de37e7a117..4c02371bffb 100644
--- a/sites/website/src/docs/3.x/api/fast-element.elementstyles.md
+++ b/sites/website/src/docs/3.x/api/fast-element.elementstyles.md
@@ -100,6 +100,27 @@ Description
 Gets the StyleStrategy associated with these element styles.
 
 
+</td></tr>
+<tr><td>
+
+[styleNonce](../fast-element.elementstyles.stylenonce/)
+
+
+</td><td>
+
+`static`
+
+
+</td><td>
+
+string \| null
+
+
+</td><td>
+
+The nonce to apply to style elements created when styles are applied with a style element based strategy. Set this to the nonce of the page's Content Security Policy to allow the styles under a strict `style-src` that does not include `'unsafe-inline'`<!-- -->. Styles applied with adopted style sheets are not subject to `style-src` and are unaffected.
+
+
 </td></tr>
 <tr><td>
 
diff --git a/sites/website/src/docs/3.x/api/fast-element.elementstyles.stylenonce.md b/sites/website/src/docs/3.x/api/fast-element.elementstyles.stylenonce.md
new file mode 100644
index 00000000000..e1916fae566
--- /dev/null
+++ b/sites/website/src/docs/3.x/api/fast-element.elementstyles.stylenonce.md
@@ -0,0 +1,30 @@
+---
+id: "fast-element.elementstyles.stylenonce"
+title: "ElementStyles.styleNonce property"
+layout: 3x-api
+eleventyNavigation:
+  key: "api3xfast-element.elementstyles.stylenonce"
+  parent: "api3xfast-element"
+  title: "ElementStyles.styleNonce property"
+navigationOptions:
+  activeKey: "api3xfast-element.elementstyles.stylenonce"
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[@microsoft/fast-element](../fast-element/index.html) &gt; [ElementStyles](../fast-element.elementstyles/index.html) &gt; [styleNonce](../fast-element.elementstyles.stylenonce/index.html)
+
+## ElementStyles.styleNonce property
+
+The nonce to apply to style elements created when styles are applied with a style element based strategy. Set this to the nonce of the page's Content Security Policy to allow the styles under a strict `style-src` that does not include `'unsafe-inline'`<!-- -->. Styles applied with adopted style sheets are not subject to `style-src` and are unaffected.
+
+**Signature:**
+
+```typescript
+static get styleNonce(): string | null;
+
+static set styleNonce(value: string | null);
+```
+
+## Remarks
+
+The nonce is read each time styles are applied, so it can be configured after styles have been created. This matters because `css` tagged templates are typically evaluated at module scope, long before an application has a chance to set the nonce.
diff --git a/sites/website/src/docs/3.x/api/fast-element.fastelementconstructor.md b/sites/website/src/docs/3.x/api/fast-element.fastelementconstructor.md
index beb9f5284e0..2d9484cd114 100644
--- a/sites/website/src/docs/3.x/api/fast-element.fastelementconstructor.md
+++ b/sites/website/src/docs/3.x/api/fast-element.fastelementconstructor.md
@@ -23,6 +23,50 @@ The FASTElement constructor and static registration helpers.
 export interface FASTElementConstructor
 ```
 
+## Properties
+
+<table><thead><tr><th>
+
+Property
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[styleNonce](../fast-element.fastelementconstructor.stylenonce/)
+
+
+</td><td>
+
+
+</td><td>
+
+string \| null
+
+
+</td><td>
+
+The nonce to apply to style elements created when styles are applied with a style element based strategy. An alias of [ElementStyles.styleNonce](../fast-element.elementstyles.stylenonce/)<!-- -->.
+
+
+</td></tr>
+</tbody></table>
+
 ## Methods
 
 <table><thead><tr><th>
diff --git a/sites/website/src/docs/3.x/api/fast-element.fastelementconstructor.stylenonce.md b/sites/website/src/docs/3.x/api/fast-element.fastelementconstructor.stylenonce.md
new file mode 100644
index 00000000000..868198e5cfb
--- /dev/null
+++ b/sites/website/src/docs/3.x/api/fast-element.fastelementconstructor.stylenonce.md
@@ -0,0 +1,24 @@
+---
+id: "fast-element.fastelementconstructor.stylenonce"
+title: "FASTElementConstructor.styleNonce property"
+layout: 3x-api
+eleventyNavigation:
+  key: "api3xfast-element.fastelementconstructor.stylenonce"
+  parent: "api3xfast-element"
+  title: "FASTElementConstructor.styleNonce property"
+navigationOptions:
+  activeKey: "api3xfast-element.fastelementconstructor.stylenonce"
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[@microsoft/fast-element](../fast-element/index.html) &gt; [FASTElementConstructor](../fast-element.fastelementconstructor/index.html) &gt; [styleNonce](../fast-element.fastelementconstructor.stylenonce/index.html)
+
+## FASTElementConstructor.styleNonce property
+
+The nonce to apply to style elements created when styles are applied with a style element based strategy. An alias of [ElementStyles.styleNonce](../fast-element.elementstyles.stylenonce/)<!-- -->.
+
+**Signature:**
+
+```typescript
+styleNonce: string | null;
+```
\ No newline at end of file
diff --git a/sites/website/src/docs/3.x/api/fast-element/declarative/fast-element.elementstyles.md b/sites/website/src/docs/3.x/api/fast-element/declarative/fast-element.elementstyles.md
index 6196129c4ad..a8330b26443 100644
--- a/sites/website/src/docs/3.x/api/fast-element/declarative/fast-element.elementstyles.md
+++ b/sites/website/src/docs/3.x/api/fast-element/declarative/fast-element.elementstyles.md
@@ -100,6 +100,27 @@ Description
 Gets the StyleStrategy associated with these element styles.
 
 
+</td></tr>
+<tr><td>
+
+[styleNonce](../fast-element.elementstyles.stylenonce/)
+
+
+</td><td>
+
+`static`
+
+
+</td><td>
+
+string \| null
+
+
+</td><td>
+
+The nonce to apply to style elements created when styles are applied with a style element based strategy. Set this to the nonce of the page's Content Security Policy to allow the styles under a strict `style-src` that does not include `'unsafe-inline'`<!-- -->. Styles applied with adopted style sheets are not subject to `style-src` and are unaffected.
+
+
 </td></tr>
 <tr><td>
 
diff --git a/sites/website/src/docs/3.x/api/fast-element/declarative/fast-element.elementstyles.stylenonce.md b/sites/website/src/docs/3.x/api/fast-element/declarative/fast-element.elementstyles.stylenonce.md
new file mode 100644
index 00000000000..416f20dd609
--- /dev/null
+++ b/sites/website/src/docs/3.x/api/fast-element/declarative/fast-element.elementstyles.stylenonce.md
@@ -0,0 +1,30 @@
+---
+id: "fast-element.elementstyles.stylenonce"
+title: "ElementStyles.styleNonce property"
+layout: 3x-api
+eleventyNavigation:
+  key: "declarative.jsapi3xfast-element.elementstyles.stylenonce"
+  parent: "@microsoft/fast-element/declarative.js3x"
+  title: "ElementStyles.styleNonce property"
+navigationOptions:
+  activeKey: "declarative.jsapi3xfast-element.elementstyles.stylenonce"
+---
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[@microsoft/fast-element/declarative.js](../fast-element/index.html) &gt; [ElementStyles](../fast-element.elementstyles/index.html) &gt; [styleNonce](../fast-element.elementstyles.stylenonce/index.html)
+
+## ElementStyles.styleNonce property
+
+The nonce to apply to style elements created when styles are applied with a style element based strategy. Set this to the nonce of the page's Content Security Policy to allow the styles under a strict `style-src` that does not include `'unsafe-inline'`<!-- -->. Styles applied with adopted style sheets are not subject to `style-src` and are unaffected.
+
+**Signature:**
+
+```typescript
+static get styleNonce(): string | null;
+
+static set styleNonce(value: string | null);
+```
+
+## Remarks
+
+The nonce is read each time styles are applied, so it can be configured after styles have been created. This matters because `css` tagged templates are typically evaluated at module scope, long before an application has a chance to set the nonce.
diff --git a/sites/website/src/docs/3.x/resources/export-sizes.md b/sites/website/src/docs/3.x/resources/export-sizes.md
index 8cc65070e6d..30c018e2615 100644
--- a/sites/website/src/docs/3.x/resources/export-sizes.md
+++ b/sites/website/src/docs/3.x/resources/export-sizes.md
@@ -19,8 +19,8 @@ Bundle sizes for `@microsoft/fast-element` exports.
 
 | Export | Minified | Gzip | Brotli |
 |--------|----------|------|--------|
-| CDN Rollup Bundle | 78.61 KB | 23.40 KB | 20.77 KB |
-| FASTElement (@microsoft/fast-element/fast-element.js) | 23.11 KB | 7.12 KB | 6.41 KB |
+| CDN Rollup Bundle | 78.86 KB | 23.48 KB | 20.84 KB |
+| FASTElement (@microsoft/fast-element/fast-element.js) | 23.34 KB | 7.23 KB | 6.49 KB |
 | Updates (@microsoft/fast-element/updates.js) | 473 B | 335 B | 290 B |
 | Observable (@microsoft/fast-element/observable.js) | 6.75 KB | 2.51 KB | 2.23 KB |
 | observable (@microsoft/fast-element/observable.js) | 6.79 KB | 2.52 KB | 2.24 KB |
@@ -32,9 +32,9 @@ Bundle sizes for `@microsoft/fast-element` exports.
 | when (@microsoft/fast-element/when.js) | 1.88 KB | 731 B | 589 B |
 | html (@microsoft/fast-element/html.js) | 27.73 KB | 8.96 KB | 8.02 KB |
 | repeat (@microsoft/fast-element/repeat.js) | 31.80 KB | 10.00 KB | 9.03 KB |
-| css (@microsoft/fast-element/css.js) | 2.43 KB | 1.00 KB | 911 B |
-| enableHydration (@microsoft/fast-element/hydration.js) | 46.53 KB | 13.91 KB | 12.49 KB |
+| css (@microsoft/fast-element/css.js) | 2.53 KB | 1.05 KB | 951 B |
+| enableHydration (@microsoft/fast-element/hydration.js) | 46.68 KB | 13.98 KB | 12.55 KB |
 | declarativeTemplate (@microsoft/fast-element/declarative.js) | 62.15 KB | 19.46 KB | 17.42 KB |
 | ArrayObserver (@microsoft/fast-element/arrays.js) | 12.55 KB | 4.46 KB | 4.03 KB |
-| observerMap (@microsoft/fast-element/observer-map.js) | 21.96 KB | 7.73 KB | 6.97 KB |
-| attributeMap (@microsoft/fast-element/attribute-map.js) | 15.31 KB | 5.41 KB | 4.88 KB |
+| observerMap (@microsoft/fast-element/observer-map.js) | 22.07 KB | 7.77 KB | 7.00 KB |
+| attributeMap (@microsoft/fast-element/attribute-map.js) | 15.42 KB | 5.46 KB | 4.91 KB |

From 81b48f587fc213afbb8b3432d9ece8e1ce1a605c Mon Sep 17 00:00:00 2001
From: AK <144495202+AKnassa@users.noreply.github.com>
Date: Thu, 16 Jul 2026 23:44:25 -0400
Subject: [PATCH 2/2] docs: document styleNonce in DESIGN.md and the 3.x styles
 guide

---
 packages/fast-element/DESIGN.md               |  9 +++++++++
 .../docs/3.x/getting-started/css-templates.md | 20 ++++++++++++++++++-
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/packages/fast-element/DESIGN.md b/packages/fast-element/DESIGN.md
index 5e6a8a8c6fb..cefc11a8e6c 100644
--- a/packages/fast-element/DESIGN.md
+++ b/packages/fast-element/DESIGN.md
@@ -390,6 +390,15 @@ CSS during template composition, but runtime CSS bindings and style-attached
 through `ElementController.addStyles()` / `removeStyles()`; `ElementStyles`
 itself is a static container.
 
+When styles are applied through a style-element strategy, each created
+`<style>` node is stamped with the nonce from `ElementStyles.styleNonce`
+(aliased as `FASTElement.styleNonce`), allowing those styles to load under a
+strict Content Security Policy `style-src` that omits `'unsafe-inline'`. The
+nonce is read when styles are applied — not when the `ElementStyles` is
+constructed — so an application can set it at startup even though module-scope
+`css` templates have already been evaluated. Adopted stylesheets are not
+subject to `style-src` and are unaffected.
+
 ---
 
 ### Dependency Injection (DI)
diff --git a/sites/website/src/docs/3.x/getting-started/css-templates.md b/sites/website/src/docs/3.x/getting-started/css-templates.md
index b4663f941ef..328286cb6b3 100644
--- a/sites/website/src/docs/3.x/getting-started/css-templates.md
+++ b/sites/website/src/docs/3.x/getting-started/css-templates.md
@@ -12,6 +12,8 @@ keywords:
   - css
   - template
   - web components
+  - content security policy
+  - nonce
 ---
 
 # CSS Templates
@@ -20,7 +22,7 @@ Custom elements are typically styled by attaching a `<style>` element to their s
 
 Styles created with `css` produce an `ElementStyles` object that FAST applies to the component's shadow root. Because the Shadow DOM encapsulates style scope, selectors authored there match only elements within the component's shadow tree, so the styles do not affect the rest of the document. When the same styles are used across many instances of a component, FAST reuses a single underlying constructable stylesheet rather than duplicating it. Unlike HTML templates, `css` templates are static and do not support binding expressions.
 
-This document describes how to author styles with the `css` function, including composing styles, partial CSS fragments, CSS directives, and changing styles at runtime.
+This document describes how to author styles with the `css` function, including composing styles, partial CSS fragments, CSS directives, changing styles at runtime, and applying styles under a Content Security Policy.
 
 ## Defining Styles
 
@@ -251,3 +253,19 @@ my-element {
 ```
 
 Because the property inherits into the shadow tree, the component picks up the consumer's value wherever it reads `var(--accent-color)`. Design token systems build on this behavior, exposing a component's customizable values as custom properties.
+
+## Styles and Content Security Policy
+
+Where the browser supports [adopted stylesheets](https://developer.mozilla.org/docs/Web/API/Document/adoptedStyleSheets) — every browser FAST supports — `ElementStyles` are applied by adopting constructed stylesheets. Those are not inline styles, so a page's [`style-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src) Content Security Policy directive does not apply to them, and the default path needs no configuration.
+
+A style-element strategy — selected with `withStrategy()` or `setDefaultStrategy()`, or used automatically as a fallback where adopted stylesheets are absent — creates `<style>` elements instead. Under a strict policy, a `style-src` without `'unsafe-inline'`, the browser blocks those elements unless they carry the policy's nonce. Set `ElementStyles.styleNonce` to the nonce your server emits, and FAST applies it to every `<style>` element it creates:
+
+```ts
+import { ElementStyles } from "@microsoft/fast-element";
+
+ElementStyles.styleNonce = "{nonce}";
+```
+
+`FASTElement.styleNonce` is an alias of the same value, so either may be used.
+
+The nonce is read each time styles are applied rather than when they are created. Because `css` tagged templates are usually evaluated at module scope, the nonce can be configured after those styles exist — it only needs to be set before the elements using them are connected. Setting it once at application startup is enough.