Skip to content

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

TypeScript

docs(core): record ProgressBar and Slider anatomy (#5760)

Cindy Zhang1d6d712bf6a1
diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
index b27c45e3b8..b4e2902f0b 100644
--- a/packages/core/src/ProgressBar/ProgressBar.doc.mjs
+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
@@ -1,12 +1,59 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Progress bar',
+ required: true,
+ description: 'Container arranging the label row and progress track.',
+ },
+ {
+ name: 'Label',
+ required: true,
+ description:
+ 'Text naming the operation, optionally hidden visually while remaining accessible.',
+ },
+ {
+ name: 'Value text',
+ required: false,
+ description:
+ 'Formatted determinate value shown beside the label when requested.',
+ },
+ {
+ name: 'Track',
+ required: true,
+ description:
+ 'Remaining-progress rail that carries the progressbar semantics.',
+ },
+ {
+ name: 'Fill',
+ required: true,
+ description:
+ 'Painted segment showing completed progress or indeterminate movement.',
+ },
+ {
+ name: 'Mark',
+ required: false,
+ description: 'Labeled target tick positioned on a determinate track.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
name: 'ProgressBar',
displayName: 'Progress Bar',
category: 'Feedback & Status',
- keywords: ["progressbar","progress","loader","loading","linear","determinate","indeterminate","meter"],
+ keywords: [
+ 'progressbar',
+ 'progress',
+ 'loader',
+ 'loading',
+ 'linear',
+ 'determinate',
+ 'indeterminate',
+ 'meter',
+ ],
props: [
{
name: 'label',
@@ -60,12 +107,13 @@ export const docs = {
name: 'marks',
type: 'ReadonlyArray<{value: number; label: string}>',
description:
- 'Fixed target marks drawn on the track at values in the same 0..max scale as value (e.g. a goal line). They stay visible whether progress is below or past them, and take their color from what they sit on: a mark inside the filled area uses the fill variant\'s on-color (on-accent, on-warning, on-error, and so on), a mark still out on the bare track uses the primary text color (the secondary one on a disabled bar, which dims everything it draws). Each mark requires a label: it is the mark\'s accessible name and the text revealed via a tooltip on hover/focus. Ignored when indeterminate.',
+ "Fixed target marks drawn on the track at values in the same 0..max scale as value (e.g. a goal line). They stay visible whether progress is below or past them, and take their color from what they sit on: a mark inside the filled area uses the fill variant's on-color (on-accent, on-warning, on-error, and so on), a mark still out on the bare track uses the primary text color (the secondary one on a disabled bar, which dims everything it draws). Each mark requires a label: it is the mark's accessible name and the text revealed via a tooltip on hover/focus. Ignored when indeterminate.",
},
{
name: 'isDisabled',
type: 'boolean',
- description: 'Visually disabled state: grays out the fill and text. Use for canceled or inactive operations.',
+ description:
+ 'Visually disabled state: grays out the fill and text. Use for canceled or inactive operations.',
default: 'false',
},
{
@@ -96,7 +144,10 @@ export const docs = {
visualProps: ['variant'],
deprecatedFor: 'progress-bar-fill',
},
- {className: 'astryx-progressbar-track', deprecatedFor: 'progress-bar-track'},
+ {
+ className: 'astryx-progressbar-track',
+ deprecatedFor: 'progress-bar-track',
+ },
{
className: 'astryx-progressbar-mark',
visualProps: ['variant', 'placement'],
@@ -104,24 +155,63 @@ export const docs = {
},
],
vars: [
- {name: '--_progressbar-mark-width', description: 'Target mark tick width', default: '2px', private: true},
- {name: '--_progressbar-mark-height', description: 'Target mark tick height', default: '8px', private: true},
+ {
+ name: '--_progressbar-mark-width',
+ description: 'Target mark tick width',
+ default: '2px',
+ private: true,
+ },
+ {
+ name: '--_progressbar-mark-height',
+ description: 'Target mark tick height',
+ default: '8px',
+ private: true,
+ },
],
derived: [
{property: 'width', vars: ['--_progressbar-mark-width'], replaces: true},
- {property: 'height', vars: ['--_progressbar-mark-height'], replaces: true},
+ {
+ property: 'height',
+ vars: ['--_progressbar-mark-height'],
+ replaces: true,
+ },
],
},
usage: {
+ anatomy,
description:
- 'A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can\'t be calculated. Supports semantic color variants, value labels, and custom formatting.',
+ "A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting.",
bestPractices: [
- { guidance: true, description: "Use a determinate bar when the total amount of work is known, and indeterminate when it's not." },
- { guidance: true, description: 'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.' },
- { guidance: true, description: "Always provide a label, even if hidden; screen readers need it to announce what's loading." },
- { guidance: false, description: 'Place icons or labels inside the bar; compose them alongside it using layout components.' },
- { guidance: false, description: "Use a progress bar for instant actions; it's meant for operations that take noticeable time." },
- { guidance: false, description: 'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.' },
+ {
+ guidance: true,
+ description:
+ "Use a determinate bar when the total amount of work is known, and indeterminate when it's not.",
+ },
+ {
+ guidance: true,
+ description:
+ 'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.',
+ },
+ {
+ guidance: true,
+ description:
+ "Always provide a label, even if hidden; screen readers need it to announce what's loading.",
+ },
+ {
+ guidance: false,
+ description:
+ 'Place icons or labels inside the bar; compose them alongside it using layout components.',
+ },
+ {
+ guidance: false,
+ description:
+ "Use a progress bar for instant actions; it's meant for operations that take noticeable time.",
+ },
+ {
+ guidance: false,
+ description:
+ 'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.',
+ },
],
},
};
@@ -164,8 +254,7 @@ export const docsZh = {
{
name: 'formatValueLabel',
type: '(value: number, max: number) => string',
- description:
- '自定义值标签格式化器;默认为百分比字符串。',
+ description: '自定义值标签格式化器;默认为百分比字符串。',
},
{
name: 'variant',
@@ -188,7 +277,8 @@ export const docsZh = {
{
name: 'isDisabled',
type: 'boolean',
- description: '视觉禁用状态——使填充条和文本变灰。用于已取消或不活跃的操作。',
+ description:
+ '视觉禁用状态——使填充条和文本变灰。用于已取消或不活跃的操作。',
default: 'false',
},
{
@@ -219,7 +309,10 @@ export const docsZh = {
visualProps: ['variant'],
deprecatedFor: 'progress-bar-fill',
},
- {className: 'astryx-progressbar-track', deprecatedFor: 'progress-bar-track'},
+ {
+ className: 'astryx-progressbar-track',
+ deprecatedFor: 'progress-bar-track',
+ },
{
className: 'astryx-progressbar-mark',
visualProps: ['variant', 'placement'],
@@ -227,24 +320,63 @@ export const docsZh = {
},
],
vars: [
- {name: '--_progressbar-mark-width', description: '目标标记刻度宽度', default: '2px', private: true},
- {name: '--_progressbar-mark-height', description: '目标标记刻度高度', default: '8px', private: true},
+ {
+ name: '--_progressbar-mark-width',
+ description: '目标标记刻度宽度',
+ default: '2px',
+ private: true,
+ },
+ {
+ name: '--_progressbar-mark-height',
+ description: '目标标记刻度高度',
+ default: '8px',
+ private: true,
+ },
],
derived: [
{property: 'width', vars: ['--_progressbar-mark-width'], replaces: true},
- {property: 'height', vars: ['--_progressbar-mark-height'], replaces: true},
+ {
+ property: 'height',
+ vars: ['--_progressbar-mark-height'],
+ replaces: true,
+ },
],
},
usage: {
+ anatomy,
description:
- 'A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can\'t be calculated. Supports semantic color variants, value labels, and custom formatting.',
+ "A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting.",
bestPractices: [
- { guidance: true, description: "Use a determinate bar when the total amount of work is known, and indeterminate when it's not." },
- { guidance: true, description: 'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.' },
- { guidance: true, description: "Always provide a label, even if hidden; screen readers need it to announce what's loading." },
- { guidance: false, description: 'Place icons or labels inside the bar; compose them alongside it using layout components.' },
- { guidance: false, description: "Use a progress bar for instant actions; it's meant for operations that take noticeable time." },
- { guidance: false, description: 'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.' },
+ {
+ guidance: true,
+ description:
+ "Use a determinate bar when the total amount of work is known, and indeterminate when it's not.",
+ },
+ {
+ guidance: true,
+ description:
+ 'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.',
+ },
+ {
+ guidance: true,
+ description:
+ "Always provide a label, even if hidden; screen readers need it to announce what's loading.",
+ },
+ {
+ guidance: false,
+ description:
+ 'Place icons or labels inside the bar; compose them alongside it using layout components.',
+ },
+ {
+ guidance: false,
+ description:
+ "Use a progress bar for instant actions; it's meant for operations that take noticeable time.",
+ },
+ {
+ guidance: false,
+ description:
+ 'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.',
+ },
],
},
};
@@ -254,15 +386,40 @@ export const docsDense = {
description:
'Progress bar for displaying determinate or indeterminate progress.',
usage: {
+ anatomy,
description:
- 'A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can\'t be calculated. Supports semantic color variants, value labels, and custom formatting.',
+ "A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting.",
bestPractices: [
- { guidance: true, description: "Use a determinate bar when the total amount of work is known, and indeterminate when it's not." },
- { guidance: true, description: 'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.' },
- { guidance: true, description: "Always provide a label, even if hidden; screen readers need it to announce what's loading." },
- { guidance: false, description: 'Place icons or labels inside the bar; compose them alongside it using layout components.' },
- { guidance: false, description: "Use a progress bar for instant actions; it's meant for operations that take noticeable time." },
- { guidance: false, description: 'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.' },
+ {
+ guidance: true,
+ description:
+ "Use a determinate bar when the total amount of work is known, and indeterminate when it's not.",
+ },
+ {
+ guidance: true,
+ description:
+ 'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.',
+ },
+ {
+ guidance: true,
+ description:
+ "Always provide a label, even if hidden; screen readers need it to announce what's loading.",
+ },
+ {
+ guidance: false,
+ description:
+ 'Place icons or labels inside the bar; compose them alongside it using layout components.',
+ },
+ {
+ guidance: false,
+ description:
+ "Use a progress bar for instant actions; it's meant for operations that take noticeable time.",
+ },
+ {
+ guidance: false,
+ description:
+ 'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.',
+ },
],
},
propDescriptions: {
@@ -271,11 +428,14 @@ export const docsDense = {
max: 'Maximum value.',
isLabelHidden: 'Visually hide label (remains accessible).',
hasValueLabel: 'Show formatted value text (ignored when indeterminate).',
- formatValueLabel: 'Custom value label formatter; defaults to percentage string.',
+ formatValueLabel:
+ 'Custom value label formatter; defaults to percentage string.',
variant: 'Semantic color variant.',
isIndeterminate: 'Animated loading indicator for unknown progress.',
- marks: 'Fixed target marks ({value, label?}) drawn on the track in the 0..max scale; stay visible past the fill. Marks inside the fill take the variant on-color; marks on the bare track take the primary text color (secondary when disabled). A label reveals a tooltip on hover/focus. Ignored when indeterminate.',
+ marks:
+ 'Fixed target marks ({value, label?}) drawn on the track in the 0..max scale; stay visible past the fill. Marks inside the fill take the variant on-color; marks on the bare track take the primary text color (secondary when disabled). A label reveals a tooltip on hover/focus. Ignored when indeterminate.',
isDisabled: 'Visually disabled: grays out fill and text.',
- xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
+ xstyle:
+ 'StyleX styles for layout customization. Must be stylex.create() value.',
},
};
diff --git a/packages/core/src/ProgressBar/ProgressBar.spec.md b/packages/core/src/ProgressBar/ProgressBar.spec.md
index ffd0a959da..c6eeacc5b8 100644
--- a/packages/core/src/ProgressBar/ProgressBar.spec.md
+++ b/packages/core/src/ProgressBar/ProgressBar.spec.md
@@ -1,6 +1,6 @@
---
schema_version: 1
-template_version: 1
+template_version: 3
kind: component
id: component:ProgressBar
authority: draft
@@ -10,7 +10,12 @@ approved_by: null
approved_at: null
owners: [cixzhang]
review_triggers: [public-api, behavior, theming, accessibility]
-verified_by: [packages/core/src/ProgressBar/ProgressBar.test.tsx]
+verified_by:
+ [
+ packages/core/src/ProgressBar/ProgressBar.test.tsx,
+ packages/core/src/theme/themingTargets.test.ts,
+ scripts/check-knowledge.mjs,
+ ]
families: []
design_specs: []
architecture:
@@ -34,14 +39,15 @@ 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.
+This draft now also records the current consumer anatomy and exact theming
+ownership. It still does not choose a visual treatment or change runtime
+behavior.
## 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.
+- Compatibility class: additive documentation only; no public API, DOM, style,
+ target, or alias is added, removed, or changed.
- Controlled/uncontrolled behavior: unchanged.
- Migration decision: `component:ProgressBar/DEC-1`.
@@ -55,11 +61,16 @@ Consumer migration instructions belong in consumer docs and release notes.
progress for every determinate presentation the component provides.
- Internal resolution of that visual treatment when the caller supplies ordinary
progress state.
+- The current progress-bar container, track, fill, and mark parts represented by
+ the `progress-bar`, `progress-bar-track`, `progress-bar-fill`, and
+ `progress-bar-mark` targets.
**Does not own / non-goals**
- External visible labels, values, or descriptions — owned by the product
callsite and supplementary to the bar.
+- A separate public target for the built-in label or value text; none currently
+ exists.
- 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
@@ -81,13 +92,14 @@ does not turn nearby external content into a ProgressBar concept.
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 |
+| 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 |
+| FR6 | The current container, track, fill, and mark carry their four current targets; label and value text carry no separate ProgressBar target. | Current source, public docs, and focused tests | Verified current behavior; no target change |
### Observed current behavior
@@ -97,8 +109,11 @@ 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.
+- `Progress bar`, `Track`, `Fill`, and `Mark` carry `progress-bar`,
+ `progress-bar-track`, `progress-bar-fill`, and `progress-bar-mark`
+ respectively. `Label` and `Value text` have no separate public target.
+- Variant state is reflected on the progress-bar, fill, and mark targets;
+ placement is also reflected on marks.
- 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
@@ -146,15 +161,45 @@ draft:
## 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 |
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ------------------------------------ | ------------------------------------------------------- | ------------------------------------- | -------------- | ------------------ |
+| Progress bar | Arranges the current label row and progress track. | Current source and public docs | Supporting | FR6 |
+| Label and value text | Name the operation and optionally supplement its value. | Current source and public docs | Supporting | FR2, AR2, FR6 |
+| Determinate fill and remaining track | Provide a sufficient standalone distinction. | Unsettled standalone visual treatment | Prominent | FR1, AR1 |
+| Mark | Presents an optional labeled target on the track. | Current source and public docs | Supporting | FR6 |
The component implements design requirements without copying their rationale.
The standalone visual remains a human design decision; this contract does not
invent its form.
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Progress bar": {"target": "progress-bar"},
+ "Label": {
+ "none": {
+ "reason": "unsettled: No current public ProgressBar target reaches this part; future target ownership is undecided."
+ }
+ },
+ "Value text": {
+ "none": {
+ "reason": "unsettled: No current public ProgressBar target reaches this part; future target ownership is undecided."
+ }
+ },
+ "Track": {"target": "progress-bar-track"},
+ "Fill": {"target": "progress-bar-fill"},
+ "Mark": {"target": "progress-bar-mark"}
+}
+```
+
+The `Label` and `Value text` gaps are current facts, not decisions that those
+parts should remain untargeted. Deprecated `progressbar*` aliases are
+compatibility metadata, not separate anatomy or current targets. This map does
+not select a standalone visual treatment or resolve OQ1.
+
## Family and system relationships
- `architecture:public-component-api` and `spec:AST-002/DEC-1` govern whether a
@@ -165,15 +210,22 @@ invent its form.
component capabilities without creating a second component contract.
- `architecture:theme-tokens` governs the semantic token vocabulary used by the
eventual treatment.
+- ProgressBar and Slider both render a track, a filled segment, positioned
+ indicators, and optional value presentation, while their current target
+ coverage differs. That evidence requires a future joint family/audit pass; it
+ does not declare a current family, require a new target, or authorize runtime
+ behavior changes.
## 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 |
+| 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 |
+| FR6 | `ProgressBar.test.tsx` and `themingTargets.test.ts` | Current and deprecated target classes | Source, metadata, or compatibility target placement drifts | `audit:ProgressBar/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and four current targets | Missing, extra, prefixed, stale, alias-backed, or unclaimed mappings fail | `audit:ProgressBar/theming` |
+| 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
diff --git a/packages/core/src/Slider/Slider.doc.mjs b/packages/core/src/Slider/Slider.doc.mjs
index 37f9be3eba..49349e2c5d 100644
--- a/packages/core/src/Slider/Slider.doc.mjs
+++ b/packages/core/src/Slider/Slider.doc.mjs
@@ -1,12 +1,86 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Label',
+ required: true,
+ description:
+ 'Text identifying the numeric setting controlled by the slider.',
+ },
+ {
+ name: 'Description',
+ required: false,
+ description: 'Helper text between the label and the slider control.',
+ },
+ {
+ name: 'Slider',
+ required: true,
+ description:
+ 'Control row containing the track, thumb or thumbs, and optional text value.',
+ },
+ {
+ name: 'Track',
+ required: true,
+ description: 'Background rail representing the available numeric range.',
+ },
+ {
+ name: 'Filled range',
+ required: true,
+ description:
+ 'Accent segment from the minimum to a single value, or between two range values.',
+ },
+ {
+ name: 'Tick mark',
+ required: false,
+ description: 'Position marker supplied through the marks collection.',
+ },
+ {
+ name: 'Mark label',
+ required: false,
+ description: 'Optional text displayed beside a tick mark.',
+ },
+ {
+ name: 'Thumb',
+ required: true,
+ description:
+ 'Draggable value indicator; range mode renders a minimum and maximum thumb.',
+ },
+ {
+ name: 'Value display',
+ required: false,
+ description:
+ 'Formatted current value shown beside the slider when valueDisplay is text.',
+ },
+ {
+ name: 'Value tooltip',
+ required: false,
+ description:
+ 'Formatted current value shown in a tooltip when valueDisplay is tooltip.',
+ },
+ {
+ name: 'Status message',
+ required: false,
+ description: 'Error, warning, or success message below the slider.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
name: 'Slider',
displayName: 'Slider',
category: 'Form Controls',
- keywords: ["slider","range","slidebar","trackbar","scrubber","knob","thumb","rangeslider"],
+ keywords: [
+ 'slider',
+ 'range',
+ 'slidebar',
+ 'trackbar',
+ 'scrubber',
+ 'knob',
+ 'thumb',
+ 'rangeslider',
+ ],
playground: {
defaults: {
label: 'Volume',
@@ -156,20 +230,49 @@ export const docs = {
],
theming: {
targets: [
- {className: 'astryx-slider', visualProps: ['orientation'], states: ['disabled']},
+ {
+ className: 'astryx-slider',
+ visualProps: ['orientation'],
+ states: ['disabled'],
+ },
{className: 'astryx-slider-track', visualProps: ['orientation']},
- {className: 'astryx-slider-thumb', visualProps: ['orientation'], states: ['disabled']},
+ {
+ className: 'astryx-slider-thumb',
+ visualProps: ['orientation'],
+ states: ['disabled'],
+ },
],
},
usage: {
+ anatomy,
description:
'A draggable control for selecting a numeric value or range within defined bounds. Supports single value and range selection, tick marks, custom value formatting, and vertical orientation. Use it when users need to explore a continuous range, such as volume, price, or percentage.',
bestPractices: [
- {guidance: true, description: 'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.'},
- {guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
- {guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
- {guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
- {guidance: false, description: 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
+ {
+ guidance: true,
+ description:
+ 'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use for precise numeric entry; pair with a text input or use NumberInput instead.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+ },
],
},
};
@@ -229,8 +332,7 @@ export const docsZh = {
{
name: 'formatValue',
type: '(value: number) => string',
- description:
- '自定义值格式化函数,用于显示和 `aria-valuetext`。',
+ description: '自定义值格式化函数,用于显示和 `aria-valuetext`。',
},
{
name: 'valueDisplay',
@@ -246,8 +348,7 @@ export const docsZh = {
{
name: 'minStepsBetweenThumbs',
type: 'number',
- description:
- '范围模式下滑块之间的最小步数;防止滑块重叠。',
+ description: '范围模式下滑块之间的最小步数;防止滑块重叠。',
default: '0',
},
{
@@ -259,7 +360,8 @@ export const docsZh = {
{
name: 'htmlName',
type: 'string',
- description: '用于表单提交的 HTML name 属性。渲染携带当前值的隐藏输入(范围模式下为两个条目)。',
+ description:
+ '用于表单提交的 HTML name 属性。渲染携带当前值的隐藏输入(范围模式下为两个条目)。',
},
{
name: 'disabledMessage',
@@ -293,8 +395,7 @@ export const docsZh = {
{
name: 'status',
type: "{type: 'warning' | 'error' | 'success', message?: string}",
- description:
- '验证反馈的状态指示器对象(`{ type, message }`)。',
+ description: '验证反馈的状态指示器对象(`{ type, message }`)。',
},
{
name: 'labelTooltip',
@@ -310,20 +411,49 @@ export const docsZh = {
],
theming: {
targets: [
- {className: 'astryx-slider', visualProps: ['orientation'], states: ['disabled']},
+ {
+ className: 'astryx-slider',
+ visualProps: ['orientation'],
+ states: ['disabled'],
+ },
{className: 'astryx-slider-track', visualProps: ['orientation']},
- {className: 'astryx-slider-thumb', visualProps: ['orientation'], states: ['disabled']},
+ {
+ className: 'astryx-slider-thumb',
+ visualProps: ['orientation'],
+ states: ['disabled'],
+ },
],
},
usage: {
+ anatomy,
description:
'A draggable control for selecting a numeric value or range within defined bounds. Supports single value and range selection, tick marks, custom value formatting, and vertical orientation. Use it when users need to explore a continuous range, such as volume, price, or percentage.',
bestPractices: [
- {guidance: true, description: 'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.'},
- {guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
- {guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
- {guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
- {guidance: false, description: 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
+ {
+ guidance: true,
+ description:
+ 'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use for precise numeric entry; pair with a text input or use NumberInput instead.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+ },
],
},
};
@@ -331,19 +461,41 @@ export const docsZh = {
/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
usage: {
+ anatomy,
description:
'A draggable control for selecting a numeric value or range within defined bounds. Supports single value and range selection, tick marks, custom value formatting, and vertical orientation. Use it when users need to explore a continuous range, such as volume, price, or percentage.',
bestPractices: [
- {guidance: true, description: 'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.'},
- {guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
- {guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
- {guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
- {guidance: false, description: 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
+ {
+ guidance: true,
+ description:
+ 'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use for precise numeric entry; pair with a text input or use NumberInput instead.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+ },
],
},
propDescriptions: {
label: 'Label text (always rendered for a11y).',
- value: 'Current value; number for single thumb, [number, number] for range.',
+ value:
+ 'Current value; number for single thumb, [number, number] for range.',
onChange: 'Fired on value change during drag.',
onChangeEnd: 'Fired when drag ends.',
min: 'Minimum value.',
@@ -353,9 +505,11 @@ export const docsDense = {
formatValue: 'Custom value formatting fn for display + aria-valuetext.',
valueDisplay: 'How current value is displayed.',
marks: 'Tick marks at specified positions w/ optional labels.',
- minStepsBetweenThumbs: 'Min steps between thumbs in range mode; prevents overlap.',
+ minStepsBetweenThumbs:
+ 'Min steps between thumbs in range mode; prevents overlap.',
isDisabled: 'Whether slider is disabled.',
- htmlName: 'HTML name attr; hidden inputs carry the value (two in range mode).',
+ htmlName:
+ 'HTML name attr; hidden inputs carry the value (two in range mode).',
isOptional: 'Whether field is optional.',
isRequired: 'Whether field is required.',
isLabelHidden: 'Visually hide label.',
diff --git a/packages/core/src/Slider/Slider.spec.md b/packages/core/src/Slider/Slider.spec.md
new file mode 100644
index 0000000000..b91a3b7abb
--- /dev/null
+++ b/packages/core/src/Slider/Slider.spec.md
@@ -0,0 +1,223 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Slider
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+ [
+ packages/core/src/Slider/Slider.test.tsx,
+ packages/core/src/theme/themingTargets.test.ts,
+ scripts/check-knowledge.mjs,
+ ]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# Slider component contract
+
+## Intent
+
+Slider presents a labeled control for selecting one numeric value or a bounded
+range. This draft records its current consumer anatomy and theming ownership
+without changing runtime behavior, styling, targets, or public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+ targets, and public API remain unchanged
+- Controlled/uncontrolled behavior: unchanged; Slider remains controlled
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The current slider row, background track, filled range, tick marks and labels,
+ thumbs, and adjacent text value presentation.
+- The existing `slider`, `slider-track`, and `slider-thumb` public targets.
+
+**Does not own / non-goals**
+
+- Label and validation-message presentation — owned by `component:Field` and
+ `component:FieldStatus`.
+- Value-tooltip presentation — owned by `component:Tooltip`.
+- New public targets for the filled range, tick marks, mark labels, description,
+ or adjacent text value display.
+- A decision that the current target asymmetry should be preserved or removed.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props, modes, states, and usage
+remain documented in `Slider.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
+| FR1 | The current render places a filled range, one or two thumbs, and optional tick marks over the background track. | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |
+| FR2 | `Slider`, `Track`, and `Thumb` carry the existing `slider`, `slider-track`, and `slider-thumb` targets respectively. | Current source and public docs | Verified current behavior; no target change |
+| FR3 | Filled range, tick marks, mark labels, and adjacent text value display are stable rendered parts without their own current Slider target. | Current source and public docs | Verified current asymmetry; not ratified as policy |
+| FR4 | Label and status presentation continue to use Field and FieldStatus; value tooltips continue to use Tooltip. | Current source and focused tests | Verified composition boundary |
+
+### Observed current target asymmetry
+
+ProgressBar currently exposes targets for its fill and marks, while Slider
+exposes targets for its root row, background track, and thumbs but not its
+filled range, tick marks, mark labels, or adjacent text value display. This is
+implementation evidence for a joint audit, not approval of either target shape.
+
+### Allowed variation
+
+- Orientation, single or range mode, disabled state, value-display mode, and the
+ number or labels of supplied marks remain current capabilities rather than
+ separate target names.
+- A description, status message, mark label, text value, or value tooltip may be
+ absent without changing the remaining anatomy.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ------------------------ | ----------------------------------------------------------------------- | -------------------------------------------------- |
+| Single value | One thumb and a filled range render over the track. | Orientation, value, disabled state, value display |
+| Range value | Two thumbs bound the filled range. | Values and minimum step separation |
+| With marks | Tick marks and optional mark labels align to the same range geometry. | Mark count, values, and label presence |
+| With shared field output | Field or Tooltip renders the requested label, feedback, or value layer. | Description, status, disabled reason, tooltip mode |
+
+### Transformation and precedence order
+
+- No new value, snapping, geometry, interaction, or styling precedence rule is
+ introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend Slider's existing accessible name, value,
+range-thumb naming, description/status association, keyboard behavior, disabled
+behavior, or value-tooltip behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ----------------------- | ------------------------------------------------------------- | ------------------------------- | -------------- | ------------------ |
+| Label and description | Identify and explain the numeric setting. | Current shared-component source | Supporting | FR4 |
+| Slider and track | Arrange the current interactive range control and rail. | Current source and public docs | Prominent | FR1, FR2 |
+| Filled range and thumbs | Show the selected value or interval over the available range. | Current source and public docs | Prominent | FR1, FR2, FR3 |
+| Tick marks and labels | Show optional supplied positions and their text. | Current source and public docs | Supporting | FR1, FR3 |
+| Value presentation | Shows the formatted value as text or a shared Tooltip. | Current source and public docs | Supporting | FR3, FR4 |
+| Status message | Presents shared validation feedback below the slider. | Current shared-component source | Supporting | FR4 |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Label": {
+ "delegatesTo": {"owner": "component:Field", "target": "field-label"}
+ },
+ "Description": {
+ "none": {
+ "reason": "unsettled: No current public target reaches this part; future target ownership is undecided."
+ }
+ },
+ "Slider": {"target": "slider"},
+ "Track": {"target": "slider-track"},
+ "Filled range": {
+ "none": {
+ "reason": "unsettled: No current public Slider target reaches this part; future target ownership is undecided."
+ }
+ },
+ "Tick mark": {
+ "none": {
+ "reason": "unsettled: No current public Slider target reaches this part; future target ownership is undecided."
+ }
+ },
+ "Mark label": {
+ "none": {
+ "reason": "unsettled: No current public Slider target reaches this part; future target ownership is undecided."
+ }
+ },
+ "Thumb": {"target": "slider-thumb"},
+ "Value display": {
+ "none": {
+ "reason": "unsettled: No current public Slider target reaches this part; future target ownership is undecided."
+ }
+ },
+ "Value tooltip": {
+ "delegatesTo": {"owner": "component:Tooltip", "target": "tooltip"}
+ },
+ "Status message": {
+ "delegatesTo": {
+ "owner": "component:FieldStatus",
+ "target": "field-status"
+ }
+ }
+}
+```
+
+`Filled range`, `Tick mark`, `Mark label`, and `Value display` remain stable
+consumer anatomy, but no current Slider target reaches them. The map records
+those gaps without making their absence intentional. `Value display` names the
+adjacent text mode; the separately listed value tooltip retains Tooltip's target.
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, factual
+ `none` dispositions, and composition-preserving target ownership.
+- Field, FieldStatus, and Tooltip retain their existing public target contracts
+ when composed by Slider.
+- Slider and ProgressBar both render a track, a filled segment, positioned
+ indicators, and optional value presentation, while their current target
+ coverage differs. That evidence requires a future joint family/audit pass; it
+ does not declare a current family, require a new target, or authorize runtime
+ behavior changes.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| FR1 | `Slider.test.tsx` structure, range, and marks suites | Single, range, horizontal, vertical, marks | Removing or misaligning stable parts breaks existing role, position, or mark assertions. | `audit:Slider/anatomy` |
+| FR2 | `themingTargets.test.ts` | Root, track, and thumb target call sites | Source and public target metadata drift fails the target guard. | `audit:Slider/theming` |
+| FR3 | Source and consumer-doc review | Filled range, marks, labels, adjacent text value | A missing target is inaccurately documented as present or intentionally permanent. | `audit:Slider/theming` |
+| FR4 | Source inspection; focused tests cover label, status, and disabled-reason Tooltip only | Label, status, value tooltip, disabled reason | Shared composition or its accessible association disappears; value-tooltip composition still lacks focused coverage. | `audit:Slider/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and three current local targets | Missing, extra, prefixed, stale, or unclaimed mappings fail repository validation. | `audit:Slider/theming` |
+
+The focused Slider suite does not separately assert the exact `slider`,
+`slider-track`, or `slider-thumb` class placement. The source/metadata target
+guard covers those declarations. It also covers only the disabled-reason
+Tooltip path, not the `valueDisplay="tooltip"` composition; that anatomy is
+source-inspected and remains missing focused test coverage.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+family, theming, or API decision.
+
+## Open questions
+
+- **OQ1 — After a joint ProgressBar and Slider family audit, should any shared
+ painted parts have aligned target coverage?** (`human-api`)
+
+This question records the audit need only. It does not presume that either
+component should add, remove, or rename a target.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, implementation
+steps, audit outcomes, or shared-component contracts. It links to their owners.