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.mdnew file mode 100644index 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.