Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: draft ProgressBar component contract (#5727)

Cindy Zhang17f22f474753
diff --git a/packages/core/src/ProgressBar/ProgressBar.spec.md b/packages/core/src/ProgressBar/ProgressBar.spec.md
new file mode 100644
index 0000000000..ffd0a959da
--- /dev/null
+++ b/packages/core/src/ProgressBar/ProgressBar.spec.md
@@ -0,0 +1,208 @@
+---
+schema_version: 1
+template_version: 1
+kind: component
+id: component:ProgressBar
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, theming, accessibility]
+verified_by: [packages/core/src/ProgressBar/ProgressBar.test.tsx]
+families: []
+design_specs: []
+architecture:
+ [
+ architecture:public-component-api,
+ architecture:component-theming-surface,
+ architecture:theme-authoring-contract,
+ architecture:theme-tokens,
+ ]
+contributing: []
+system_specs: [spec:AST-002/DEC-1, spec:AST-002/DEC-2]
+---
+
+# ProgressBar component contract
+
+## Intent
+
+ProgressBar communicates the progress of an operation. A determinate bar must be
+a sufficient standalone visual: people must be able to distinguish completed
+from remaining progress without depending on visible text rendered elsewhere.
+External text may supplement the bar, but it is not a prerequisite for the bar
+to be correct.
+
+This draft is intentionally limited to that visual-completeness requirement and
+the resulting public-API boundary. It does not choose a visual treatment.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; this draft changes no runtime behavior.
+- Compatibility class: documentation-only draft; no public API is added, removed,
+ or changed.
+- Controlled/uncontrolled behavior: unchanged.
+- Migration decision: `component:ProgressBar/DEC-1`.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- A sufficient standalone visual distinction between completed and remaining
+ progress for every determinate presentation the component provides.
+- Internal resolution of that visual treatment when the caller supplies ordinary
+ progress state.
+
+**Does not own / non-goals**
+
+- External visible labels, values, or descriptions — owned by the product
+ callsite and supplementary to the bar.
+- The exact standalone contrast treatment — still a human design decision.
+- Theme token definitions — owned by `architecture:theme-tokens`.
+- Public API that makes visual correctness depend on caller-declared external
+ content — governed by `architecture:public-component-api` and `spec:AST-002`.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ------------------- | ---------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------- | ------------------------------- | ----------------------- | ------------------ | ------------------------------ |
+| Progress mode | `determinate`, `indeterminate` | Whether completed progress is known | All variants | Determinate | `component:ProgressBar` | Stable current API | Existing prop handling applies |
+| Built-in value text | Shown or hidden | Optional visible text supplement generated by ProgressBar | Determinate only | Hidden | `component:ProgressBar` | Stable current API | Ignored when indeterminate |
+| Visual treatment | One sufficient standalone treatment; exact form unresolved | How the graphic distinguishes completed from remaining progress | Determinate progress | Sufficient standalone treatment | `component:ProgressBar` | Draft decision | No incomplete public mode |
+
+The current public props remain documented in `ProgressBar.doc.mjs`. This draft
+does not turn nearby external content into a ProgressBar concept.
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision.
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ---------------------- |
+| FR1 | Every determinate presentation ProgressBar provides MUST be a sufficient standalone visual for distinguishing completed from remaining progress. | `component:ProgressBar/DEC-1`; existing non-text contrast standard | Settled |
+| FR2 | External visible text MAY supplement the bar but MUST NOT be required for the bar's visual correctness. | `component:ProgressBar/DEC-1` | Settled |
+| FR3 | ProgressBar MUST NOT make visual correctness depend on caller-declared external content that it cannot verify or associate. | `component:ProgressBar/DEC-1`; `spec:AST-002` | Settled |
+| FR4 | Supplementary text or graphics MUST NOT substitute for a sufficient distinction between completed and remaining progress. | `component:ProgressBar/DEC-1` | Settled |
+| FR5 | Public API MAY be considered only after the component has a correct base behavior and a stable caller-owned distinction still remains. | `component:ProgressBar/DEC-1`; `spec:AST-002` | Settled admission gate |
+
+### Observed current behavior
+
+These observations describe `main`; they are not design approval from this
+draft:
+
+- Determinate progress renders a semantic-color fill over a muted track.
+- `hasValueLabel` optionally renders formatted value text in the component.
+- Callers may compose other visible text outside the component.
+- The current public theming surface exposes root, fill, track, and mark targets;
+ variant state is reflected on the root, fill, and mark targets.
+- Current unit tests cover value semantics, labels, variants, determinate and
+ indeterminate modes, disabled rendering, marks, and public target names. They
+ do not establish a sufficient standalone completed-versus-remaining visual
+ across shipped themes.
+
+### Allowed variation
+
+- **AV1 — Exact visual treatment.** Shape, token choice, and other rendering
+ details may vary if every resulting presentation satisfies FR1.
+- **AV2 — Themes.** Themes may express their visual language through the current
+ theming system while preserving the standalone distinction.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| -------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Determinate, partial progress | Completed and remaining progress are distinguishable from the graphic alone | Exact visual treatment and semantic variant |
+| Determinate with built-in value text | The graphic still satisfies FR1; value text supplements it | Value formatting |
+| Determinate with external visible text | The graphic still satisfies FR1 without relying on that text | Callsite composition |
+| Indeterminate | Communicates ongoing activity without claiming a completed amount | Existing animation and theme variation; completed-versus-remaining distinction does not apply |
+
+### Transformation and precedence order
+
+- **ORD1 — Progress state before presentation.** Resolve determinate or
+ indeterminate behavior from component state, then render a treatment valid for
+ that mode. External content does not weaken the determinate visual requirement.
+
+### Performance and resources
+
+- **PR1 — No external-content inspection.** ProgressBar MUST NOT add DOM
+ observation, measurement, or relationship discovery to decide whether nearby
+ visible text makes a weaker bar acceptable.
+
+## Accessibility contract
+
+- **AR1 — Standalone non-text distinction.** A determinate bar MUST satisfy the
+ applicable non-text contrast requirement without relying on external visible
+ text.
+- **AR2 — Programmatic semantics remain present.** The current required
+ accessible name and determinate value semantics remain independent of the
+ visible treatment.
+- **AR3 — Supplementary text is not inferred.** ProgressBar MUST NOT claim that
+ external text is present, visible, equivalent, or correctly associated when it
+ cannot encode or verify those facts.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ------------------------------------ | ------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Determinate fill and remaining track | Sufficient standalone distinction | Unsettled | Prominent | FR1, AR1 |
+| Built-in or external visible value | Supplements rather than enables correctness | Prescribed | Supporting | FR2, AR3 |
+
+The component implements design requirements without copying their rationale.
+The standalone visual remains a human design decision; this contract does not
+invent its form.
+
+## Family and system relationships
+
+- `architecture:public-component-api` and `spec:AST-002/DEC-1` govern whether a
+ caller-owned distinction justifies a public prop.
+- `architecture:component-theming-surface` governs which stable visible parts and
+ states become public theme capabilities.
+- `architecture:theme-authoring-contract` governs how themes override those
+ component capabilities without creating a second component contract.
+- `architecture:theme-tokens` governs the semantic token vocabulary used by the
+ eventual treatment.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------- |
+| FR1, AR1 | Real-browser visual and contrast evidence across shipped themes and color modes | Partial determinate progress for each semantic variant | A completed or remaining segment becomes indistinguishable without text | Future ProgressBar visual audit |
+| FR2, FR3, AR3 | Public type and consumer-doc review | No value text, built-in value text, external composed text | A caller signal is credited with correctness the component cannot verify | Future ProgressBar API tests |
+| AR2 | `ProgressBar.test.tsx` | Determinate, indeterminate, hidden label, custom value text | Accessible name or value semantics disappear when visuals change | Future ProgressBar accessibility audit |
+| Theming | Theme-target metadata checks plus browser evidence | Shipped themes, light and dark modes | A theme override bypasses the standalone distinction | Future ProgressBar theming audit |
+
+## Decision log
+
+### DEC-1 — ProgressBar owns a sufficient standalone visual
+
+**Reference:** `component:ProgressBar/DEC-1`
+**Decider:** `cixzhang`, `2026-08-30`
+
+ProgressBar must provide a sufficient standalone visual. Visible text inside or
+outside the component may improve understanding, but the bar remains responsible
+for communicating completed versus remaining progress without it.
+
+Public API must not make that correctness depend on external content the
+component cannot carry, associate, or verify. Solve the component behavior first.
+Consider new API only when a stable caller-owned distinction still remains after
+the base behavior is correct.
+
+Rejected: weakening the bar based on a caller claim about nearby content. That
+would move component correctness into an external condition the component cannot
+verify.
+
+## Open questions
+
+- **OQ1 — What exact visual treatment gives every determinate presentation a
+ sufficient standalone completed-versus-remaining distinction across supported
+ variants, themes, and color modes?** (`human-design`)
+
+## Content boundary
+
+This file does not duplicate consumer prop tables or examples, current audit
+results, implementation steps, exact visual values, or system theming rules. It
+links to their owners.