Skip to content

Add themed Text component and make the component skills more flexible #4303

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jason Morse (JasonVMo) merged 2 commits into from
Sep 2, 2026
Merged

Add themed Text component and make the component skills more flexible #4303

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0cb8062
add theme aware text component
JasonVMo Sep 1, 2026
4bf23df
make component authoring skills more flexible
JasonVMo Sep 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/quiet-text-inherits.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@fluentui-react-native/components": minor
---

Add a theme-aware Text primitive and use it for component text content.
37 changes: 17 additions & 20 deletions .github/skills/agentic-component-authoring/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,32 +25,29 @@ authoring rule in one always-loaded instruction file.

## Load focused references

| Work | Reference |
| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Flex component source resolution, React Native contract adaptation, provenance, or divergences | [Flex source adaptation](references/spec-source-adaptation.md) |
| Public props, slots, state types, native prop exposure, or exports | [Types and slots](references/types-and-slots.md) |
| Defaults, derived state, interaction hooks, accessibility, or slot construction | [State and accessibility](references/state-and-accessibility.md) |
| Tokens, style factories, theme caching, state precedence, or slot style application | [Styles and tokens](references/styles-and-tokens.md) |
| Pure slot rendering, component assembly, or display names | [Rendering and assembly](references/rendering.md) |
| Runtime tests, type tests, snapshots, Storybook stories, or validation | [Tests and stories](references/tests-and-stories.md) |
| Native React Native Windows Fabric components, codegen, registration, or UIA | [Windows Fabric native components](references/windows-fabric-native-components.md) |
| Cross-component duplication, shared helper extraction, or dependency hygiene | [Package optimization](../agentic-component-optimization/SKILL.md) |
| Work | Reference |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Source interpretation, provenance, contract drafting, review, or divergences | [Contract authoring](../agentic-component-contract-authoring/SKILL.md) |
| Public props, slots, state types, native prop exposure, or exports | [Types and slots](references/types-and-slots.md) |
| Defaults, derived state, interaction hooks, accessibility, or slots | [State and accessibility](references/state-and-accessibility.md) |
| Tokens, theme caching, state precedence, or slot style application | [Styles and tokens](references/styles-and-tokens.md) |
| Pure slot rendering, component assembly, or display names | [Rendering and assembly](references/rendering.md) |
| Runtime tests, type tests, snapshots, Storybook stories, or validation | [Tests and stories](references/tests-and-stories.md) |
| Native React Native Windows Fabric components, codegen, registration, or UIA | [Windows Fabric native components](references/windows-fabric-native-components.md) |
| Cross-component duplication, shared extraction, or dependency hygiene | [Package optimization](../agentic-component-optimization/SKILL.md) |

A new higher-order component normally needs every reference. A focused fix should load only the affected reference and
its immediate neighbors. Keep the component's colocated `SPEC.md` and companion files authoritative for its contract.

## Workflow

1. For a higher-order component, start Agency with the repository's
`flex-authoring` profile, invoke `flex-components:<name>`, and follow the
[Flex source adaptation](references/spec-source-adaptation.md) reference.
Record source identities without copying source bodies.
2. Read the repository and package instructions, the component `SPEC.md`,
`spec/source.json`, and every React Native companion referenced by the
spec. For a new component, draft and review those local contract files
before implementation. Use the package-wide optimization guidance only when
the change clearly involves repeated patterns or shared dependency
boundaries.
1. Read the repository and package instructions, the component `SPEC.md`,
`spec/source.json`, and every React Native companion referenced by the spec.
2. Use an existing reviewed contract directly when its source evidence and
requested behavior are unchanged. If the contract is absent, stale, still a
draft, or accompanied by new source evidence, run the
[contract authoring workflow](../agentic-component-contract-authoring/SKILL.md)
and complete its pre-code review gate first.
3. Inspect the closest canonical implementation. Use
[`components/button`](../../../packages/agentic/components/src/components/button) for a styled higher-order component
and [`primitives/icon`](../../../packages/agentic/components/src/primitives/icon) for a direct primitive.
Expand Down
84 changes: 6 additions & 78 deletions .github/skills/agentic-component-authoring/references/spec-source-adaptation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,81 +1,9 @@
# Flex source adaptation

Use this reference when creating or revising a higher-order component contract.
Flex skills provide design evidence; local React Native documents define FURN
behavior.
Contract creation now belongs to the
[agentic component contract authoring skill](../../agentic-component-contract-authoring/SKILL.md).
For pinned Flex component skills and X3 lineage, use its
[Flex and X3 source adapter](../../agentic-component-contract-authoring/references/sources/flex-x3.md).

## Resolve one immutable source set

Start Agency with the repository's `flex-authoring` profile and invoke
`flex-components:<name>`. Confirm that `flex-components`, `flex-system`, and
`flex-tokens` resolve to the release in
`packages/agentic/components/spec-source-lock.json`.

Read the component's shared skill and usage material plus its web companions.
Read mobile companions only when that component provides them. A platform never
falls back to another platform's files, and files from different revisions must
not be combined.

Do not copy source prose or token tables into the public repository. Record
only identifiers and digests in `spec/source.json`.

## Draft the React Native contract

Before implementation, classify every relevant axis, slot, behavior, and token
along two dimensions:

1. Source surface: shared, web, mobile, Flex system, or an existing FURN
implementation.
2. Disposition: adopted, adapted, intentional divergence, not applicable, or
deferred.

Consult the local Flex token map and the closest Win32, macOS, or Windows V1
implementation. Do not use iOS as the desktop compatibility reference.

Write an original local contract:

- public props, slots, defaults, and state ownership in `SPEC.md`;
- actual FURN token bindings in `spec/tokens.yaml`;
- React Native accessibility and UIA/AX behavior in
`spec/accessibility.md`;
- keyboard, pointer, focus, and motion behavior in `spec/interaction.md`;
- FURN usage and examples in `spec/usage.md`.

Give contract requirements stable IDs and map each one to existing or planned
types, tests, stories, or platform evidence in the Conformance table. Record
every divergence in `SPEC.md` with a stable ID, disposition, rationale, status,
and issue when follow-up work is required.

Translate platform concepts deliberately:

| Flex evidence | React Native contract |
| ------------------------------------ | ---------------------------------------------------------------------------------- |
| ARIA attributes or native elements | `accessibilityRole`, `accessibilityState`, labels, and UIA/AX expectations |
| CSS pseudo-classes | explicit interaction state and precedence |
| browser focus selectors and outlines | persistent `FocusVisual`; never conditional `outline*` or native RNW focus visuals |
| CSS pixel or layout rules | React Native layout units, minimum targets, and platform behavior |
| unsupported browser capability | explicit divergence, dependency, or blocker |

Review the draft contract before writing code.

Use `contract-draft` with `review-required` while authoring. A pre-code review
moves the lifecycle to `contract-reviewed`, records only the source surfaces
the reviewer actually consulted, and adds the review date. Planned evidence
paths may remain unrealized at this stage.

## Implement and ratify

Implement the component through the normal types, state, styles, render, and
assembly stages. Derive tests and stories from the requirement IDs. After
validation, reconcile the draft against the realized public types and native
output. Change the contract only through an explicit review; do not make an
accidental implementation choice authoritative after the fact.

Generating or repinning `spec/source.json` requires access to the private
Marketplace and x3 repositories. Set lifecycle to `implemented` and
conformance to `reviewed` only when the contract, implementation, and declared
evidence agree. Updating
the immutable source lock or its recorded file identities clears that review
until each delta is adopted, adapted, rejected, or deferred. Drift at mutable
Marketplace or x3 HEAD is a candidate proposal and does not invalidate a
contract ratified against the pinned release.
This compatibility reference remains so existing links continue to resolve.
Implementation guidance stays in the agentic component authoring skill.
98 changes: 98 additions & 0 deletions .github/skills/agentic-component-contract-authoring/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
---
name: agentic-component-contract-authoring
description: Create or revise reviewed React Native component contracts in packages/agentic/components from Flex/X3, Fluent v9, HTML/CSS, images, local platform foundations, or composite evidence.
license: MIT
---

# Agentic component contract authoring

Turn source material into an original, reviewable Fluent UI React Native
contract. This skill owns source interpretation, authority, provenance,
uncertainty, React Native adaptation, divergences, and requirement planning. It
does not own component implementation.

Use this skill directly for contract-only, feasibility, or implementation-plan
requests. The [component authoring skill](../agentic-component-authoring/SKILL.md)
invokes this workflow before code when a contract is missing, stale, still a
draft, or accompanied by new source evidence.

## Choose the request mode

- **Feasibility or plan only:** inspect the evidence, identify blockers and
unknowns, and describe the contract work without changing implementation.
Commit contract files only when the user requested a contract.
- **Contract only:** create or revise the local contract and stop after its
review state accurately reflects the evidence.
- **Contract plus implementation:** complete this workflow, then return to the
component authoring skill without splitting the implementation into separate
source-specific phases.

## Select source adapters

Load every adapter represented by the supplied evidence, but no others.

| Evidence | Adapter |
| --------------------------------------------- | -------------------------------------------------------------- |
| Pinned Flex component skill and X3 lineage | [Flex and X3](references/sources/flex-x3.md) |
| Fluent UI v9 source or specification | [Fluent v9](references/sources/fluent-v9.md) |
| HTML, CSS, computed styles, or browser output | [HTML and CSS](references/sources/html-css.md) |
| Images, screenshots, or design renders | [Visual reference](references/sources/visual-reference.md) |
| Public native API plus repository precedent | [Local foundation](references/sources/local-foundation.md) |
| More than one of the preceding source sets | [Composite evidence](references/sources/composite-evidence.md) |

## Workflow

1. Read the package instructions, the existing `SPEC.md`, all companions under
`spec/`, and `SPEC-SOURCE.md`. Preserve a reviewed contract unless new
evidence or an explicit requested behavior change requires re-review.
2. Inventory the source sets. Give each source a stable kebab-case ID, classify
its authority, pin immutable identities where possible, and record only
public or redistributable evidence.
3. Separate observations from inferences. A source governs only what it can
establish: images do not prove semantics, CSS does not prove native
interaction, and a web implementation does not define React Native
platform behavior.
4. Resolve authority per requirement. For multiple sources, record sorted
source IDs on every requirement and document conflicts explicitly; never
choose one source as globally authoritative merely for convenience.
5. Draft the original React Native contract:
- public API, slots, defaults, state ownership, and requirement IDs in
`SPEC.md`;
- FURN token bindings and gaps in `spec/tokens.yaml`;
- native accessibility in `spec/accessibility.md`;
- keyboard, pointer, focus, and motion behavior in
`spec/interaction.md`;
- FURN examples and constraints in `spec/usage.md`;
- lifecycle, provenance, divergences, and requirement evidence in
`spec/source.json`.
6. Classify every relevant source claim as adopted, adapted, intentionally
divergent, not applicable, deferred, or unknown. Do not turn missing
evidence into an inferred guarantee.
7. Review the contract before code. Keep `contract-draft`,
`review-required`, and a null review date until the source interpretation,
native adaptation, authority decisions, and planned evidence are coherent.
Move to `contract-reviewed` only after that explicit review.
8. Run the package contract checker. Source refresh tools may update provenance
but never approve a contract or populate reviewed surfaces automatically.

## Contract rules

- `spec/source.json` uses schema version 2 and a sorted, non-empty `sources[]`.
Source IDs are unique. Keep this generated, digest-heavy metadata in JSON;
`spec/tokens.yaml` remains YAML because token mappings are human-authored.
- Supported source kinds are `flex-skill`, `git-files`, `html-css`,
`visual-reference`, and `local-foundation`.
- A source's `authority` describes how it may govern requirements. Requirement
`sources` identify the actual source set used for that decision.
- `git-files` records a repository, full commit SHA, and sorted file paths with
SHA-256 digests. `html-css` and `visual-reference` record immutable artifact
digests; repository-relative artifacts are verified locally.
- A `local-foundation` source is valid only when no Flex catalog component
exists and must be the contract's sole source.
- Only `flex-skill` has automated release and candidate drift reporting.
Other immutable sources report Flex drift as `not-applicable`; refresh their
identities through an explicit source review.
- A reviewed local contract is normative for FURN. New upstream evidence is a
change proposal, not an automatic rewrite.
- Do not copy or lightly transform private source bodies into this public
repository. Record identities and write original React Native documentation.
36 changes: 36 additions & 0 deletions ...s/agentic-component-contract-authoring/references/sources/composite-evidence.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Composite evidence adapter

Use multiple `sources[]` entries when no single source can establish the full
React Native contract. Composite evidence is a resolution method, not a source
kind.

## Resolve authority per requirement

For every requirement, list the sorted source IDs that govern or support it.
Do not assign one global precedence order to an entire component. A common
division is:

| Requirement area | Likely authority |
| ------------------------ | ---------------------------------------------------- |
| design intent and tokens | normative design source plus token reference |
| public API and state | product specification or reviewed behavior reference |
| native semantics | React Native/platform contract |
| visual fidelity | normative design source plus visual evidence |
| compatibility | existing FURN implementation |

One source may be authoritative for one requirement and merely corroborating
for another. If sources disagree, record the conflicting claims, chosen
resolution, rationale, and divergence or follow-up issue. If evidence is
insufficient, keep the behavior unknown or deferred.

## Keep the contract reviewable

- Give each source a stable ID and use the source-specific adapter schema.
- Keep `sources[]` sorted and unique.
- Require every requirement to identify at least one source when more than one
source is present.
- Do not duplicate one artifact across source entries to manufacture
corroboration.
- Re-review only the requirements affected by changed evidence, but keep the
document-level conformance state at `review-required` until the combined
contract is coherent again.
Loading
Loading