@astryxdesign/core 0.5.1 → 0.5.2-canary.00477a5

package/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.',
   },
 };

package/src/ProgressBar/ProgressBar.spec.md

@@ -0,0 +1,260 @@
+---
+schema_version: 1
+template_version: 3
+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,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+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 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: 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`.
+
+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.
+- 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
+  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                      |
+| 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
+
+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.
+- `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
+  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 |
+| ------------------------------------ | ------------------------------------------------------- | ------------------------------------- | -------------- | ------------------ |
+| 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
+  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.
+- 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 |
+| 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
+
+### 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.

package/src/RadioList/RadioList.doc.mjs

@@ -6,7 +6,7 @@ export const docs = {
   name: 'RadioList',
   displayName: 'Radio List',
   group: 'Radio',
-  category: 'Data Input',
+  category: 'Form Controls',
   keywords: ["radiolist","radio","radiogroup","radiobutton","optionlist","singlechoice","choicelist"],
   theming: {
     targets: [