From bd0e3c9377c4d9751a80bf959dfd62cc921ec151 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mariano=20Guti=C3=A9rrez=20Xavier?= Date: Thu, 3 Sep 2026 20:54:40 -0300 Subject: [PATCH 1/3] docs: add multi-framework design system scaffold Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- README.md | 8 ++++++++ docs/design-system-repository.md | 29 +++++++++++++++++++++++++++ packages/flask-ui/README.md | 27 +++++++++++++++++++++++++ packages/flask-ui/package.json | 11 ++++++++++ packages/flask-ui/templates/README.md | 5 +++++ 5 files changed, 80 insertions(+) create mode 100644 docs/design-system-repository.md create mode 100644 packages/flask-ui/README.md create mode 100644 packages/flask-ui/package.json create mode 100644 packages/flask-ui/templates/README.md diff --git a/README.md b/README.md index f57e18143be43e..87d429ae2b1f51 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,14 @@ The following table will help you navigate the 3 projects and understand their d > Why are there two React versions? Fluent UI v8 is still widely used. We encourage you to migrate to Fluent UI v9. See the [Migration overview](https://react.fluentui.dev/?path=/docs/concepts-migration-from-v8-component-mapping--docs). +## Multi-framework design system + +Fluent UI keeps shared tokens, guidance, and framework integrations in one +repository. React components live under `packages/react-components/`; the +Flask/Jinja integration scaffold lives under `packages/flask-ui/`. See the +[design system repository structure](docs/design-system-repository.md) for +branching and ownership guidance. + ## FluentUI Insights [Fluent UI Insights](https://docs.microsoft.com/en-us/shows/fluent-ui-insights?utm_source=github) is a series that describes the design and decisions behind the Fluent UI design system. diff --git a/docs/design-system-repository.md b/docs/design-system-repository.md new file mode 100644 index 00000000000000..d1a7b250082c15 --- /dev/null +++ b/docs/design-system-repository.md @@ -0,0 +1,29 @@ +# Design system repository structure + +Fluent UI supports multiple delivery models in one repository. The repository +is the source of truth for shared design tokens, accessibility requirements, +component behavior, and documentation. Each framework integration owns its +runtime and packaging details. + +## Integration boundaries + +| Integration | Location | Consumer | +| --- | --- | --- | +| Shared tokens | `packages/tokens/` | All integrations | +| React components | `packages/react-components/` | React applications | +| Flask/Jinja integration | `packages/flask-ui/` | Flask applications | + +The existing React packages remain unchanged. The Flask package is currently a +private scaffold so its API can be designed without prematurely publishing an +incomplete package. + +## Branch and repository policy + +Use one repository and short-lived feature branches. Do not maintain permanent +framework branches: they drift, make shared token changes harder to review, and +prevent one pull request from showing the complete cross-framework impact. + +Use a separate repository only if an integration requires different access +controls, release ownership, or a substantially different contribution +workflow. A separate repository should still consume the shared token contract +and publish compatibility documentation. diff --git a/packages/flask-ui/README.md b/packages/flask-ui/README.md new file mode 100644 index 00000000000000..84868ccd9995ee --- /dev/null +++ b/packages/flask-ui/README.md @@ -0,0 +1,27 @@ +# Fluent UI Flask integration + +This package is the Flask/Jinja integration surface for the Fluent UI design +system. It is intentionally private while the integration contract is being +defined. + +## Scope + +- Jinja macros and templates for server-rendered applications +- CSS custom properties generated from the shared Fluent token source +- Accessibility and interaction guidance shared with the React implementation + +The package must not duplicate design tokens. Token names and values are owned +by `@fluentui/tokens`; Flask assets should consume the generated token output. + +## Planned layout + +```text +packages/flask-ui/ +├── templates/ # Jinja macros and base templates +├── static/ # Generated CSS and other browser assets +└── README.md +``` + +React consumers continue to use the existing `@fluentui/react-components` +package. Both integrations share the token source and design documentation, +but they can evolve and release independently. diff --git a/packages/flask-ui/package.json b/packages/flask-ui/package.json new file mode 100644 index 00000000000000..54d3ea67f0146a --- /dev/null +++ b/packages/flask-ui/package.json @@ -0,0 +1,11 @@ +{ + "name": "@fluentui/flask-ui", + "version": "0.0.0", + "description": "Fluent UI integration points for Flask and Jinja applications", + "private": true, + "license": "MIT", + "files": [ + "templates", + "README.md" + ] +} diff --git a/packages/flask-ui/templates/README.md b/packages/flask-ui/templates/README.md new file mode 100644 index 00000000000000..1b313242a86af7 --- /dev/null +++ b/packages/flask-ui/templates/README.md @@ -0,0 +1,5 @@ +# Flask templates + +Jinja templates and macros will be added here once the server-rendered +component contract is approved. Keep templates framework-specific and consume +generated Fluent design tokens rather than defining a second token system. From 0f3f4cfc017c7e2c648665a71bf35eda44e37eea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mariano=20Guti=C3=A9rrez=20Xavier?= Date: Thu, 3 Sep 2026 21:10:43 -0300 Subject: [PATCH 2/3] chore: update lockfile for flask workspace Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- yarn.lock | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/yarn.lock b/yarn.lock index bc2a2274150b38..70bc4b78715431 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2767,6 +2767,12 @@ __metadata: languageName: unknown linkType: soft +"@fluentui/flask-ui@workspace:packages/flask-ui": + version: 0.0.0-use.local + resolution: "@fluentui/flask-ui@workspace:packages/flask-ui" + languageName: unknown + linkType: soft + "@fluentui/fluent2-theme@npm:*, @fluentui/fluent2-theme@npm:^8.107.154, @fluentui/fluent2-theme@workspace:packages/fluent2-theme": version: 0.0.0-use.local resolution: "@fluentui/fluent2-theme@workspace:packages/fluent2-theme" From 513c560566cb172f03fdb1924cbad8faeda8d2fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mariano=20Guti=C3=A9rrez=20Xavier?= Date: Fri, 4 Sep 2026 14:08:19 -0300 Subject: [PATCH 3/3] docs: format design system repository guide Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/design-system-repository.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/design-system-repository.md b/docs/design-system-repository.md index d1a7b250082c15..307451859e4423 100644 --- a/docs/design-system-repository.md +++ b/docs/design-system-repository.md @@ -7,11 +7,11 @@ runtime and packaging details. ## Integration boundaries -| Integration | Location | Consumer | -| --- | --- | --- | -| Shared tokens | `packages/tokens/` | All integrations | -| React components | `packages/react-components/` | React applications | -| Flask/Jinja integration | `packages/flask-ui/` | Flask applications | +| Integration | Location | Consumer | +| ----------------------- | ---------------------------- | ------------------ | +| Shared tokens | `packages/tokens/` | All integrations | +| React components | `packages/react-components/` | React applications | +| Flask/Jinja integration | `packages/flask-ui/` | Flask applications | The existing React packages remain unchanged. The Flask package is currently a private scaffold so its API can be designed without prematurely publishing an