Fix CSS custom property precedence issue

[m-akinc]

Pull Request

📖 Description

Overriding a design token's value in a stylesheet does not always work. A stylesheet containing custom properties for design tokens is added to adoptedStyleSheets alongside other client-defined stylesheets. If a client attempts to override a design token value for an element in CSS, in most cases the order of stylesheets in adoptedStyleSheets won't matter because of specificity-based precedence. But if the client stylesheet overrides the token property using the selector :host, then whichever stylesheet appears later in adoptedStyleSheets will be the one that wins. It seems that the client CSS's override should always take precedence.

This change causes the special stylesheet for design token CSS properties to always be prepended to adoptedStyleSheets so that client stylesheets take precedence when order matters.

🎫 Issues

N/A

👩‍💻 Reviewer Notes

This change was conceived as a workaround to a Chromium bug that affected archives/fast-element-1. See PR #6906 into that branch.

📑 Test Plan

One test case added.

✅ Checklist

General

• I have included a change request file using $ yarn change
• I have added tests for my changes.
• I have tested my changes.
• I have updated the project documentation to reflect my changes.
• I have read the CONTRIBUTING documentation and followed the standards for this project.

[rajsite]

@chrisdholt while we are waiting for reviewers (not sure how long to expect), could the workflows be run to pre-emptively catch any issues?

[rajsite]

Of the reviewers who have merged PRs recently @chrisdholt @scomea @radium-v would someone be willing to run the workflow so we can see if the tests pass so we can make progress on this PR?

[janechu]

My primary issue with this change is that we end up paying a runtime cost for what I consider a very niche problem, I believe structuring CSS properly is more the correct move on a project without the need for allowing overrides. We're in process to remove the @microsoft/fast-foundation package per #6951 and your testing is in that package (which is another issue), so we're looking to close this PR unless there is a compelling reason for adding the functionality.

[m-akinc]

It's not clear to me if/how this issue could manifest outside the use case of design tokens (i.e. without fast-foundation). Since fast-foundation and its design token system are going away, the issue is moot as far as I'm concerned. This change has already gone into the archives/fast-element-1 branch, which was my main priority anyway.

[janechu]

@m-akinc sounds good, I'll close for now then we can always re-open and discuss if there's a pressing need in future.