docs: establish multi-framework design system structure

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.

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.

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.

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"
+  ]
+}

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.

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"