The examples/ workspace hosts small, focused applications that show how to
build real UI with FAST using production-shaped tooling, app structure, and
styling. It is aimed at contributors, library consumers, and anyone evaluating
FAST patterns in a complete app context.
| Folder | Package | Purpose |
|---|---|---|
design-system |
@microsoft/fast-examples-design-system |
Shared CSS design tokens (no JS) consumed by every example app. |
csr/todo-app |
@microsoft/fast-todo-app-example |
A To-Do app demonstrating @microsoft/fast-element patterns end to end, styled with the shared design-system tokens (light theme, no runtime toggle). |
csr/todo-mobx-app |
@microsoft/fast-todo-mobx-app-example |
A To-Do app showing how to integrate MobX state with @microsoft/fast-element using a single autorun per component (no custom bridge code), styled with the shared design-system tokens. |
ssr/chat-app |
@microsoft/fast-chat-app-example |
A declarative FAST chat demo that pre-renders with @microsoft/fast-build and streams canned assistant replies into the transcript, styled with the shared design-system tokens (dark theme, no runtime toggle). |
ssr/webui-todo-app |
@microsoft/fast-webui-todo-app-example |
A To-Do app pre-rendered by @microsoft/webui and hydrated by @microsoft/fast-element/declarative.js, styled with the shared design-system tokens (light theme, no runtime toggle). |
Example apps are grouped by rendering strategy. Client-side-rendered (CSR)
apps live under examples/csr/ and server-side-rendered (SSR) apps
live under examples/ssr/.
Every example app must consume @microsoft/fast-examples-design-system. The
package is CSS-only — it ships a single stylesheet (tokens.css) and no
JavaScript or TypeScript. Apps wire theme switching themselves using the
data-theme attribute on <html>.
The package exposes a single import:
| Import | What it does |
|---|---|
@microsoft/fast-examples-design-system/tokens.css |
Declares every token on :root. Color and elevation values use light-dark(); theme is controlled by prefers-color-scheme (default) or <html data-theme="light"|"dark"> (forced). |
Style components with semantic tokens such as
--fast-background-layer-primary-solid,
--fast-foreground-ctrl-neutral-primary-rest,
--fast-background-ctrl-brand-rest, --fast-text-global-body3-font-size,
--fast-padding-content-medium, and --fast-corner-large. Never hard-code
colors, font sizes, padding, gaps, corners, stroke widths, shadows,
durations, or curves.
See:
examples/design-system/README.md— quickstart, available imports, token catalog.examples/design-system/DESIGN.md— naming grammar, role catalog, theme model, and rules for adding tokens (the canonical authoring guide for both humans and coding agents).examples/DESIGN.md— workspace-level guidance for building new example apps on top of the design system.
- Scaffold a new folder under the appropriate rendering-strategy subfolder
(CSR apps go under
examples/csr/<your-app>/; SSR apps go underexamples/ssr/<your-app>/). - Use
examples/csr/todo-app/as a reference for CSR apps, orexamples/ssr/chat-app//examples/ssr/webui-todo-app/as a reference for SSR apps (package.json,tsconfig.json, build config, entry HTML). - Add
"@microsoft/fast-examples-design-system": "^1.0.0"to the new app'sdependenciesand runnpm installfrom the repo root. - Import
@microsoft/fast-examples-design-system/tokens.cssexactly once at the app entry point (typicallysrc/main.tsorsrc/index.ts). For an intentionally single-theme app, hard-code<html data-theme="light">(or"dark") in the entry HTML and never touch it from JavaScript. - Reference tokens via
var(--fast-...)in componentcsstemplate literals or.cssfiles — do not hard-code design values. - If the app needs a theme toggle, set or remove the
data-themeattribute on<html>from your app code:Do not import any JavaScript from the design-system package — it intentionally exposes none.document.documentElement.setAttribute("data-theme", "dark"); document.documentElement.removeAttribute("data-theme"); // restore system
- Add the new app to the table at the top of this file.
From the repository root:
npm install
npm start -w @microsoft/fast-<your-app>-exampleFor the existing example apps:
npm start -w @microsoft/fast-todo-app-example
npm start -w @microsoft/fast-todo-mobx-app-example
npm start -w @microsoft/fast-chat-app-example
npm start -w @microsoft/fast-webui-todo-app-example