Components: Component readiness model and initial assessment

[JasonVMo]

Summary

Define objective component-readiness levels, publish an initial assessment of every current export, and expose the resulting maturity signal to consumers. The assessment below is only a provisional evidence-backed baseline: promotion cannot become authoritative until the coverage and spec-fidelity checks are standardized and automated.

Observed. The package is published at version 0.2.3 and exports 18 components and
5 primitives with no per-component maturity signal of any kind. There is no README, no
status table, no @beta / @experimental annotation, and no documentation page. The
only maturity signal is the package version and the _unstable suffix on the pipeline
stage exports, which marks the composition API rather than the component.

This document already contains a provisional initial assessment of all 23 exported
items, applied to a proposed level ladder, in
Provisional initial assessment. It is labeled
Inferred and provisional: it is the evidence-backed starting point for the owner
decision, not a published marker. The remaining work in this task is to ratify the
ladder, persist the markers, publish them to consumers, and automate promotion.

Goal

Define what "ready" means for a component in packages/agentic/components, express it
as a small set of levels backed by objective and checkable evidence, decide where the
level is recorded and how it is published to consumers, and publish an initial
assessment of everything the package exports today.

Stage

Stage 1 (beta foundations), with the enforcement half landing in Stage 3.

Why it matters

Observed. The repository already has three tiers of component maturity encoded
structurally - packages/components, packages/experimental, packages/native -
and the agentic library collapses all of them into one package. A consumer looking at
@fluentui-react-native/components cannot tell that button has 15 test cases and
three snapshotted states while divider has three cases and none.

Observed. Coverage depth varies by a factor of five across components, and 15 of
18 have no snapshot coverage, so the underlying evidence is genuinely unequal. See
component-test-strategy.md.

Observed. The local button contract has diverged from the current upstream
button spec (Selected axis, Shape values, icon slots). A component can therefore be
well tested and still be out of date with its source of truth, which is a distinct
readiness dimension from coverage.

Inferred. Beta cannot be declared honestly without this. "Beta" applied to a whole
package asserts the same confidence for its weakest and strongest member, and the
evidence shows those are not the same.

Observed current state

Signals that exist today

Signal	Where	What it actually tells a consumer
Package version 0.2.3	package.json	The package as a whole is pre-1.0
_unstable export suffix	src/index.ts	The state/styles/render pipeline API may change; says nothing about the component
SPEC.md presence	18 / 18 components, 0 / 5 primitives	A contract was authored; not whether it is implemented completely
blockers.md	18 staged specs under specs/	Why a component was not built; no equivalent record for what was built
Changeset history	CHANGELOG.md	Behavioral changes, including a recent Windows Fabric focus-visual crash fix
Storybook on-device harness	apps/storybook/windows-tests/storybook-smoke.test.cjs with scripts/smoke-stories.json	14 story IDs: 3 render cases plus 11 focus assertions. Touches 11 of 18 components, the icon primitive, and Callout; Windows only; invoked by no workflow

Observed. Nothing in the repository maps a component to the upstream spec revision
it was generated from.

Candidate evidence axes

Inferred from the observed baseline, these are the dimensions that actually vary
across the 23 exported items and are therefore worth measuring:

1. Spec fidelity - does the implementation cover every variant axis in its
   SPEC.md, and is that spec current against the pinned upstream revision?
2. Contract coverage - runtime tests over every finite axis, a type test, and
   snapshot coverage where the visual contract is state-dependent.
3. Accessibility - role, name, state, and disabled semantics asserted, and keyboard
   behavior where the component has any.
4. Platform validation - rendered and exercised on macOS and on React Native
   Windows Fabric, not only under the macOS Jest preset.
5. API stability - whether the public props and slots are expected to change, which
   is what a consumer most needs to know before adopting.
6. Token completeness - whether the component styles entirely from Flex tokens or
   carries recorded token gaps.

Provisional level ladder

Inferred, and provisional pending owner approval. This ladder is defined here only
far enough to apply it to today's evidence, so the assessment below is a real result
rather than a promise of one. The owner may change the names, the number of rungs, or
the evidence per rung; the assessment would then be recomputed.

Level	Required evidence
experimental	Implemented, explicitly exported, with a colocated runtime test and a Storybook story. No stability expectation.
preview	Everything above, plus a committed type test, runtime coverage of every finite axis declared in its SPEC.md, asserted accessibility semantics, and recorded spec provenance (upstream path and revision).
beta	Everything above, plus a committed record of the resolved visual contract where that contract is state-dependent, documented on-device validation on both macOS and React Native Windows Fabric, and no unresolved drift against the pinned spec revision. A reviewed manual macOS run may satisfy beta; required CI enforcement belongs to stable.
stable	Everything above, plus CI-enforced evidence, keyboard and screen-reader validation on each supported desktop endpoint, and a stated API-stability commitment.
deprecated	Terminal state, with a migration target recorded.

Resolved primitive policy. The owner decision in
#4250 keeps all five
primitives public from @fluentui-react-native/components/primitives; implementation is
in #4288. Primitives use
the same ladder above. Wherever component evidence refers to SPEC.md, upstream
provenance, or upstream drift, primitive evidence instead uses its colocated
CONTRACT.md, public types, and renderer branches. The lack of an upstream catalog entry
does not cap primitive readiness.

Provisional initial assessment

Inferred, and provisional. Applied to the repository as observed on 2026-08-20.
Every verdict below is derived from evidence that is already in the repository; none
of it is a judgement about component quality.

Two axes fail for every item today

Observed. Two gates fail universally, so all 18 components and all 5 primitives
are provisionally experimental, with no exceptions:

1. Spec provenance. Nothing in the repository records the upstream revision any
   spec was generated from. There is no pinned SHA, no manifest, and no drift check
   (see spec-ingestion-and-generation.md). No
   item can satisfy the preview provenance requirement.
2. Two-platform on-device validation. The only on-device harness is Windows-only
   (storybook-smoke.test.cjs
   under @react-native-windows/automation), and it is invoked by no workflow. No
   documented manual macOS assessment exists either, so no item can satisfy the
   beta platform requirement. A reviewed manual macOS run is sufficient for
   beta; required macOS CI remains a production/stable gate.

Inferred. A flat "everything is experimental" verdict would be true but useless,
so the table below also records the ceiling each item would reach once those two
universal gates clear, and the axis that would still limit it. That is the number that
differentiates the library today.

Components

Observed columns; Inferred ceiling and limiting axis.

Component	Runtime cases	Type test	Snapshot	On-device case	Ceiling once universal gates clear	Limiting axis at that ceiling
accordion	10	yes	no	accordion--default focus	preview	Contract coverage - no resolved-output record for a state-dependent visual contract
avatar	9	yes	no	none	preview	Platform validation - no on-device case at all
badge	6	yes	no	none	preview	Platform validation - no on-device case at all
button	15	no	yes	button--default render, button--overview keyboard	experimental	Contract coverage (the only component with no type test) and spec fidelity (drifted selected, shape, and icon-slot contract)
card	7	yes	no	card--interactive focus	preview	Contract coverage - no resolved-output record
checkbox	13	yes	no	checkbox--default focus	preview	Contract coverage - no resolved-output record
divider	3	yes	no	none	preview	Contract coverage (lowest case count in the package against a multi-axis spec) and platform validation
input	9	yes	no	none	preview	Contract coverage and platform validation
list-item	12	yes	yes	listitem--selected-focus	beta	None identified beyond the universal gates - the only component with type test, snapshot, and an on-device case together
listbox-item	9	yes	no	listboxitem--default focus	preview	Contract coverage - no resolved-output record
menu-item	10	yes	no	menuitem--selected focus	preview	Contract coverage - no resolved-output record
progress-bar	6	yes	no	none	preview	Platform validation - no on-device case at all
radio	9	yes	no	radio--default focus	preview	Contract coverage - no resolved-output record
skeleton	4	yes	yes	none	preview	Platform validation - no on-device case at all
spinner	4	yes	no	none	preview	Contract coverage (4 cases against an eight-step size axis) and platform validation
switch	12	yes	no	switch--default focus	preview	Contract coverage - no resolved-output record
tab	10	yes	no	tab--selected focus	preview	Contract coverage - no resolved-output record
tag	9	yes	no	tag--default focus	preview	Contract coverage - no resolved-output record

Primitives

Observed columns; Inferred ceiling and limiting axis.

Primitive	Runtime cases	Type test	Story	On-device case	Ceiling once universal gates clear	Limiting axis at that ceiling
checkbox-indicator	1	yes	yes	none	experimental	Spec fidelity (no SPEC.md, no upstream catalog entry), contract coverage, platform validation
compound-item-layout	1	yes	yes	none	experimental	Spec fidelity, contract coverage, platform validation
focus-visual	2	yes	yes	none	experimental	Spec fidelity, contract coverage, platform validation - despite being the mechanism behind a shipped Windows Fabric crash fix
icon	5	yes	yes	icon--default render	experimental	Spec fidelity - no SPEC.md and no upstream catalog entry, so the axis cannot be evaluated at all
layout-stable-text	1	yes	yes	none	experimental	Spec fidelity, contract coverage, platform validation

What this assessment says

1. Observed. Nothing in the package is beta-ready today, and the reason is
   infrastructural rather than per-component: no spec provenance and no macOS on-device
   validation.
2. Inferred. Once those two gates clear, one component (list-item) reaches
   beta on existing evidence, sixteen reach preview, and button alone
   remains experimental - the canonical component, held back by the package's only
   missing type test and by a spec contract that has drifted from upstream.
3. Inferred. The distance from preview to beta for the sixteen is small and
   mechanical: a resolved-output record where the visual contract is state-dependent,
   and an on-device case for the seven components the Windows harness never selects
   (avatar, badge, divider, input, progress-bar, skeleton, spinner).
4. Resolved. The five primitives are assessed on local contract fidelity rather
   than upstream-spec fidelity. Their CONTRACT.md, public types, and renderer branches
   define the axes; no upstream counterpart is required.

Provisional status. This assessment is not a marker. It is the evidence-backed
starting point for the owner decision in the Scope section below; persisting the
markers, publishing them, and automating promotion remain this task's deliverables.

Scope

1. Ratify or revise the proposed ladder in
   Provisional level ladder
   (experimental -> preview -> beta -> stable, with deprecated terminal). A
   small ladder is preferable to a matrix.
2. For each level, state the required evidence on each axis above, phrased so it can be
   checked rather than asserted.
3. Decide where the marker lives. Options observed to be viable in this repository:
   a per-component field in SPEC.md front matter (which already carries structured
   front matter), a package-level manifest file, a TSDoc release tag on the exported
   symbol, or some combination.
4. Decide how it reaches consumers who never open the repository: a package README
   table, the generated type declarations, the docs site, or the Storybook story
   metadata.
5. Ratify or revise the provisional assessment above once the ladder is approved, and
   record the ratified result as the initial assessment across all 18 components and 5
   primitives, with the evidence for each level recorded, not just the verdict.
6. Define promotion and demotion: who decides, what evidence is required, and what
   happens when a component regresses or its spec drifts.
7. Decide whether readiness is computed from evidence or declared and then verified.

Out of scope

• Raising any component's readiness. This task measures and marks; raising is the work
  of component-test-strategy.md and the individual
  component tasks.
• Readiness for packages/components, packages/experimental, and packages/native.
• Versioning or release policy for the package as a whole.

Deliverables

1. A readiness model document defining the levels, the evidence per level, and the
   promotion and demotion rules.
2. A decision, with rationale, on where the marker is stored and how it is published.
3. The marker applied to all 18 components and 5 primitives.
4. A ratified initial assessment table, derived from the provisional one in this
   document, with a level and the supporting evidence per item, including the axis that
   limits each item's level.
5. A consumer-facing surface (at minimum a package README table) that shows the level
   per component.
6. A specification for the automated readiness check to be built in Stage 3, including
   which axes can be machine-verified and which require review.

Acceptance criteria

• The readiness model document exists and defines each level in terms of checkable
  evidence.
• Each of the 18 components and 5 primitives carries a readiness marker in the
  agreed location.
• The provisional assessment in this document is ratified or revised, and the
  ratified result records, per item, the level, the evidence, and the limiting
  axis.
• Any revision to the ladder is applied back to all 23 items rather than leaving
  the provisional verdicts stale.
• The primitives are addressed explicitly, including whether items without a
  SPEC.md can be marked at all.
• The button spec divergence is reflected in its assessment rather than ignored.
• A consumer can read the level for a component without cloning the repository.
• Promotion and demotion rules name a decision owner and the required evidence.
• The Stage 3 automated check is specified precisely enough to implement, with each
  axis marked machine-verifiable or review-only.
• No component is marked above the evidence that exists for it on the day of
  assessment.

Dependencies and ordering

• Depends on component-test-strategy.md for the
  coverage contract that the contract-coverage axis measures against.
• Depends on spec-ingestion-and-generation.md
  for the pinned upstream revision and the drift report that the spec-fidelity axis
  needs.
• Consumes focus-zone.md indirectly: components whose keyboard
  behavior depends on a focus container cannot reach the highest level until that
  behavior exists.
• Consumes the Infrastructure workstream's Storybook end-to-end pipeline
  (storybook-e2e.md) for the
  platform-validation axis.
• Feeds every task in missing-components/: each
  new component states the readiness level it is expected to reach.

Risks and open decisions

1. Marker location. SPEC.md front matter keeps readiness next to the contract but
   is invisible to a published consumer; a TSDoc release tag reaches the declaration
   files but is easy to leave stale. Open decision.
2. Declared versus computed. A computed level cannot be wrong but can only measure
   mechanical axes; a declared level can capture judgement but can be optimistic.
   Open decision: compute a ceiling and allow a declared level at or below it.
3. Level inflation at beta. If the beta bar is set where the library already is, the
   marker carries no information. Open decision: set the bar from the strongest
   component's evidence rather than the median.
4. Primitives. Resolved in
   #4250: retain the
   five public primitives under the ./primitives subpath and apply the normal readiness
   ladder using local contract fidelity in place of upstream-spec fidelity.
5. Composition-pipeline exports. The use*_unstable / render*_unstable surface is
   a separate public contract from the component itself and may warrant its own level.
   Open decision.
6. Assessment staleness. An assessment produced once is wrong within a release
   unless it is regenerated. Inferred: the assessment should be generated from
   evidence rather than hand-written, which argues for the computed option.

Evidence and references

• packages/agentic/components/package.json
  and CHANGELOG.md - version and
  change history.
• packages/agentic/components/src/index.ts
  • the full public surface being assessed.
• packages/agentic/components/src/components/button/SPEC.md
  • existing structured front matter, a candidate marker location.
• packages/agentic/components/specs -
  blockers.md precedent for recording a machine-readable status next to a spec.
• apps/storybook/windows-tests/storybook-smoke.test.cjs,
  apps/storybook/scripts/smoke-stories.json,
  and apps/storybook/jest.windows.config.cjs
  • the current extent of on-device validation, and its single-platform, unenforced
    shape.
• component-test-strategy.md - the measured coverage
  inventory behind the contract-coverage axis.
• spec-ingestion-and-generation.md - the drift
  report behind the spec-fidelity axis.

Sources retrieved 2026-08-20.