feat(examples): add CSS-only design system package#7524
Merged
janechu merged 9 commits intoMay 21, 2026
Conversation
Add @microsoft/fast-examples-design-system shared workspace package exposing CSS custom-property tokens (color, type ramp, spacing, radius, stroke, shadow, motion) with light/dark theming via the data-theme attribute and prefers-color-scheme fallback. Refactor examples/todo-app to consume the tokens and demonstrate a theme toggle. Add examples/README.md and examples/DESIGN.md describing the token taxonomy, naming pattern, and contribution guidelines. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Rework the shared example-apps design system into a CSS-only package with
semantic, role-based token names, and split the published surface into
three hand-authored stylesheets.
Design-system package (examples/design-system):
- Remove all JavaScript/TypeScript: delete src/themes.ts, src/index.ts,
tsconfig.json, scripts/copy-css.mjs, and the dist/ build output. The
package no longer has a build step.
- Move the token CSS up to the package root and split into:
* tokens.css — combined entry, light defaults plus
[data-theme="dark"] and prefers-color-scheme
dark overrides.
* tokens-light.css — single-theme light stylesheet.
* tokens-dark.css — single-theme dark stylesheet.
- Simplify package.json: drop main/types/scripts and expose only the
three CSS files via the exports field.
- Rename every token to a semantic role-based scheme
(--fast-{category}-{role}[-{variant}][-{state}]) — for example
--fast-color-background-default, --fast-color-foreground-on-accent,
--fast-color-feedback-danger-foreground, --fast-spacing-md,
--fast-radius-lg, --fast-border-width-sm, --fast-shadow-md, type-ramp
names (--fast-font-size-body-1, --fast-font-size-title-3, ...),
--fast-duration-fast, --fast-easing-standard.
- Rewrite README.md and DESIGN.md as agent-facing guidance: quickstart,
token catalog, naming grammar, role/variant/state catalogs, theme
model, authoring rules, and anti-patterns. Both documents explicitly
call out the no-JavaScript constraint.
examples/README.md and examples/DESIGN.md:
- Updated to reflect the CSS-only scope and the semantic naming model.
- New-app checklist instructs apps to import one of the three
stylesheets and to manage themes with the data-theme attribute on
<html> using plain DOM APIs.
Todo app (examples/todo-app):
- Remove the import of any JavaScript from
@microsoft/fast-examples-design-system. The CSS import stays.
- Re-implement the three-state light/dark/auto toggle inline in
src/todo-app.ts using
document.documentElement.setAttribute("data-theme", ...) and
removeAttribute(...) for the auto state.
- Update src/design-system.d.ts to declare ambient modules for all
three CSS entries.
- Refresh component styles (todo-app.styles.ts, todo-form.styles.ts)
and index.html to use the new semantic token names.
- Rewrite the README to describe the CSS-only design system and the
inline data-theme toggle pattern.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
janechu
changed the title
janechu
changed the title
This design system is not formally aligned with any specific external design language. Remove references to 'Fluent 2', 'Fluent brand blue', and the @fluentui/web-components and fluent2.microsoft.design comparisons / external links from the README, DESIGN, and package.json files in: - examples/design-system/README.md - examples/design-system/DESIGN.md - examples/design-system/package.json - examples/README.md - examples/DESIGN.md The shipped CSS, the semantic token names, and the theme model are unchanged. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
janechu
changed the title
…tic taxonomy
Rename the FAST example apps' design system to use the MS Semantic Tokens
("smtc") taxonomy used by mai-ui, keeping the --fast- prefix. Token names
are now organized by use-site (background-web-page, background-ctrl-brand,
foreground-ctrl-neutral-primary, stroke-divider, status-danger-tint, etc.)
rather than abstract color roles. State vocabulary is now rest/hover/
pressed/disabled (mai-ui idiom).
Highlights
- text-global ramp (caption2..display1, lower number = larger) replaces
font-size/line-height pairs; text-style-* replaces font-family/weight.
- padding-content-* and gap-between-content-* (full t-shirt scale) replace
the unified spacing-* scale.
- corner-{none,small,medium,large,circular} replaces radius-*.
- stroke-width-* replaces border-width-*; stroke-divider-* and
stroke-ctrl-on-outline-* replace color-border-*.
- background-{web-page,layer,ctrl-brand,ctrl-subtle} replace
color-background and color-accent fills; foreground-ctrl-{neutral,brand,
hint,on-brand} replace color-foreground.
- status-{danger,success,warning}-{solid,tint} replaces color-feedback-*.
Destructive button uses status-danger-tint-* per mai-ui's destructive
pattern.
- Dedicated ctrl-focus-outer-stroke[-width] tokens replace generic focus
ring styling.
- Shadows split into key+ambient atomic pairs plus a composed alias
(shadow-card-rest) consumers can use directly.
- Motion stays under standalone duration-* / curve-* categories (mai-ui
uses the same Fluent 2 motion vocabulary).
Updates the todo-app consumer (styles, template HTML, README) to use the
new tokens. Rewrites DESIGN.md and README.md at both package and workspace
levels to document the new taxonomy. No JavaScript exports remain in
@microsoft/fast-examples-design-system — the package is still CSS-only.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
janechu
changed the title
Rewrite design-system docs and stylesheet header comments to describe the
naming model generically ("semantic, use-site-oriented" tokens) instead
of attributing it to a specific external taxonomy by name. No token names,
values, or runtime behavior change.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
janechu
changed the title
The design-system package is not formally aligned with Fluent 2; describe it generically as a shared semantic-tokens package. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ng light-dark() Replace the three-file token entry (tokens.css + tokens-light.css + tokens-dark.css) with a single tokens.css that uses the CSS light-dark() function. Color and elevation values now carry both their light and dark resolutions on the same declaration, and the active theme is selected by the inherited color-scheme — which follows prefers-color-scheme by default and is overridden by the data-theme attribute on <html>. Behavior is preserved: - No data-theme → follows prefers-color-scheme - data-theme="light" → forced light - data-theme="dark" → forced dark The @media (prefers-color-scheme: dark) block is gone; color-scheme + light-dark() handle the same resolution with fewer declarations. Drops: - examples/design-system/tokens-light.css - examples/design-system/tokens-dark.css - Their exports entries in package.json - Their declare module entries in todo-app/src/design-system.d.ts Docs (DESIGN.md and README.md, both at the package and workspace level) updated to describe the single-file model and note the light-dark() browser support requirement (Chrome / Edge 123+, Firefox 120+, Safari 17.5+). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
janechu
changed the title
…fast-example-apps
Per design intent for the todo-app example, the only changes relative to
main should be:
1. Pull in the shared @microsoft/fast-examples-design-system tokens.
2. Update component styles to reference --fast-* tokens via var(...).
This commit removes the runtime theme toggle that an earlier round of the
PR added to demonstrate dark/auto switching, and locks the app to the
light theme by setting <html data-theme="light"> statically in index.html.
Specifically:
- Restore todo-app.ts and todo-app.template.ts to their main baselines
(no Theme observable, no toggleTheme method, no toolbar / theme-toggle
button in the template).
- Drop the .toolbar and .theme-toggle rules from todo-app.styles.ts.
- Hard-code data-theme="light" on <html> in index.html.
- Rewrite the Theme toggle section of todo-app/README.md to note that
the app is intentionally single-theme.
- Update workspace and design-system docs (examples/DESIGN.md,
examples/README.md, examples/design-system/README.md) to stop pointing
to the todo-app as the theme-toggle reference.
The design-system package itself still supports dark and
prefers-color-scheme themes via the data-theme attribute; this commit
just removes the toggle UI from the todo-app example.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
janechu
changed the title
chrisdholt
approved these changes
May 21, 2026
janechu
deleted the
users/janechu/add-design-system-language-to-fast-example-apps
branch
5 tasks
janechu
added a commit
that referenced
this pull request
May 21, 2026
Introduces `@microsoft/fast-examples-design-system`, a private, CSS-only design system shared across `examples/*`. The package ships a single stylesheet (`tokens.css`) with semantic, use-site-oriented design tokens — colors, typography, spacing, shape, elevation, and motion — under the `--fast-` prefix.
Color and elevation tokens use the CSS `light-dark()` function, so each declaration carries both its light and dark resolution side by side. Theme is driven by `prefers-color-scheme` by default and can be forced via `<html data-theme="light"|"dark">`. The package contains no JavaScript or TypeScript — consumer apps wire any theme switching themselves with two lines of DOM code.
The todo-app example is updated to consume the package: it pulls in `tokens.css`, replaces hard-coded design values with `var(--fast-*)` references, and statically sets `<html data-theme="light">`. Workspace and package documentation (`examples/DESIGN.md`, `examples/README.md`, `examples/design-system/DESIGN.md`, `examples/design-system/README.md`, `examples/todo-app/README.md`) covers the naming grammar, theme model, authoring guidance for humans and coding agents, and anti-patterns. The repo `copilot-instructions.md` is updated to mention the new package.
Both packages stay `"private": true`; no Beachball change file is required.
- `light-dark()` requires Chrome / Edge 123+, Firefox 120+, or Safari 17.5+ (all shipped 2023–2024). No fallback is shipped — these examples target evergreen browsers.
- Design-system is intentionally CSS-only: no JS / TS exports, no theme runtime, no component layer. Theme switching is delegated to consumer apps.
- The todo-app deliberately does not implement a runtime theme toggle. It hard-codes `<html data-theme="light">` and demonstrates only token consumption. Apps that need a toggle can add one with DOM APIs (`document.documentElement.setAttribute("data-theme", ...)`).
From the repo root:
```bash
npm run build # ✅ all packages build
npx biome check examples/ # ✅ clean
npm run checkchange # ✅ "No change files are needed" (both example packages are private)
```
Manual smoke: `npm start -w examples/todo-app`. The app should render in light theme; the primary action button should style correctly across rest/hover/pressed; the per-row delete button should use the `status-danger-tint-*` variants; focus rings should resolve via the dedicated `ctrl-focus-outer-*` tokens.
- [ ] I have included a change request file using `$ npm run change`
- [ ] I have added tests for my changes.
- [x] I have tested my changes.
- [x] I have updated the project documentation to reflect my changes.
- [x] I have read the [CONTRIBUTING](https://github.com/microsoft/fast/blob/main/CONTRIBUTING.md) documentation and followed the [standards](https://github.com/microsoft/fast/blob/main/CODE_OF_CONDUCT.md#our-standards) for this project.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull Request
📖 Description
Introduces
@microsoft/fast-examples-design-system, a private, CSS-only design system shared acrossexamples/*. The package ships a single stylesheet (tokens.css) with semantic, use-site-oriented design tokens — colors, typography, spacing, shape, elevation, and motion — under the--fast-prefix.Color and elevation tokens use the CSS
light-dark()function, so each declaration carries both its light and dark resolution side by side. Theme is driven byprefers-color-schemeby default and can be forced via<html data-theme="light"|"dark">. The package contains no JavaScript or TypeScript — consumer apps wire any theme switching themselves with two lines of DOM code.The todo-app example is updated to consume the package: it pulls in
tokens.css, replaces hard-coded design values withvar(--fast-*)references, and statically sets<html data-theme="light">. Workspace and package documentation (examples/DESIGN.md,examples/README.md,examples/design-system/DESIGN.md,examples/design-system/README.md,examples/todo-app/README.md) covers the naming grammar, theme model, authoring guidance for humans and coding agents, and anti-patterns. The repocopilot-instructions.mdis updated to mention the new package.Both packages stay
"private": true; no Beachball change file is required.👩💻 Reviewer Notes
light-dark()requires Chrome / Edge 123+, Firefox 120+, or Safari 17.5+ (all shipped 2023–2024). No fallback is shipped — these examples target evergreen browsers.<html data-theme="light">and demonstrates only token consumption. Apps that need a toggle can add one with DOM APIs (document.documentElement.setAttribute("data-theme", ...)).📑 Test Plan
From the repo root:
Manual smoke:
npm start -w examples/todo-app. The app should render in light theme; the primary action button should style correctly across rest/hover/pressed; the per-row delete button should use thestatus-danger-tint-*variants; focus rings should resolve via the dedicatedctrl-focus-outer-*tokens.✅ Checklist
General
$ npm run change