@astryxdesign/core 0.5.2-canary.e4f7677 → 0.5.2-canary.e4f8e4e

package/dist/Carousel/Carousel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Carousel.d.ts","sourceRoot":"","sources":["../../src/Carousel/Carousel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,KAAK,SAAS,EAOf,MAAM,OAAO,CAAC;AAef,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAKhD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,UAAU,IAAI,IAAI,CAAC;IACnB;;;OAGG;IACH,UAAU,IAAI,IAAI,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,aAAa,IAAI,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACtC,kEAAkE;IAClE,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAyJD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,SAAS,EACT,QAAQ,EACR,GAAO,EACP,UAAiB,EACjB,WAAkB,EAClB,OAAe,EACf,OAAe,EACf,OAAO,EACP,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,SAAS,EACb,EAAE,aAAa,+BAgYf;yBAhZe,QAAQ"}
+{"version":3,"file":"Carousel.d.ts","sourceRoot":"","sources":["../../src/Carousel/Carousel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,KAAK,SAAS,EAOf,MAAM,OAAO,CAAC;AAef,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAKhD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,UAAU,IAAI,IAAI,CAAC;IACnB;;;OAGG;IACH,UAAU,IAAI,IAAI,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,aAAa,IAAI,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACtC,kEAAkE;IAClE,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA+JD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,SAAS,EACT,QAAQ,EACR,GAAO,EACP,UAAiB,EACjB,WAAkB,EAClB,OAAe,EACf,OAAe,EACf,OAAO,EACP,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,SAAS,EACb,EAAE,aAAa,+BAgYf;yBAhZe,QAAQ"}

package/dist/Carousel/Carousel.js

@@ -69,11 +69,11 @@ const styles = {
     $$css: true
   },
   fadeStart: {
-    kX1K2I: "x1ujl4f5",
+    kX1K2I: "x1ujl4f5 x17xqekc",
     $$css: true
   },
   fadeEnd: {
-    kX1K2I: "xtdd0ob",
+    kX1K2I: "xtdd0ob x8ulde1",
     $$css: true
   },
   fadeBoth: {

package/dist/astryx.css

@@ -1317,7 +1317,9 @@
   .x16khyan:is(:disabled,[aria-disabled="true"]):not(#\#):not(#\#):not(#\#){cursor:default}
   .x1y40yee:popover-open:not(#\#):not(#\#):not(#\#){display:flex}
   .x1sik18w:not(:first-child):not(#\#):not(#\#):not(#\#){margin-inline-start:var(--_avatar-group-overlap)}
+  .x17xqekc:is([dir="rtl"] *):not(#\#):not(#\#):not(#\#){mask-image:linear-gradient(to left,transparent 0%,rgba(0,0,0,.3) 2px,black var(--spacing-1))}
   .x1nwey30:is([dir="rtl"] *):not(#\#):not(#\#):not(#\#){mask-image:linear-gradient(to left,transparent var(--_tab-strip-bleed),black calc(var(--_tab-strip-bleed) + var(--spacing-8)))}
+  .x8ulde1:is([dir="rtl"] *):not(#\#):not(#\#):not(#\#){mask-image:linear-gradient(to right,transparent 0%,rgba(0,0,0,.3) 2px,black var(--spacing-1))}
   .x1rxa4r8:is([dir="rtl"] *):not(#\#):not(#\#):not(#\#){mask-image:linear-gradient(to right,transparent var(--_tab-strip-bleed),black calc(var(--_tab-strip-bleed) + var(--spacing-8)))}
   .x1euntei:focus-within:not(#\#):not(#\#):not(#\#){opacity:1}
   .x25t5g8:focus-visible:not(#\#):not(#\#):not(#\#){opacity:1}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.5.2-canary.e4f7677",
+  "version": "0.5.2-canary.e4f8e4e",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -661,7 +661,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/cli": "0.5.2-canary.e4f7677",
+    "@astryxdesign/cli": "0.5.2-canary.e4f8e4e",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",

package/src/Button/Button.doc.mjs

@@ -23,6 +23,62 @@ export const docs = {
       {guidance: false, description: 'Use the destructive variant without a confirmation step for irreversible actions like deleting data.'},
       {guidance: false, description: 'Use a button for navigation. If it only takes the user to another page, use a link instead. Buttons are for actions like saving, deleting, or submitting.'},
     ],
+    accessibility: [
+      {
+        name: 'Text label',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Hover', 'Pointer down'],
+        description:
+          'Button text must have at least 4.5:1 contrast with the button background in every state. For Hover and Pointer down, measure the final background after the overlay is applied.',
+      },
+      {
+        name: 'Essential icon or spinner arc',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Icon only', 'Loading'],
+        description:
+          'An icon used instead of text must have at least 3:1 contrast with the button background. The moving spinner arc must also meet 3:1. An icon beside a visible label does not need its own check.',
+      },
+      {
+        name: 'Badge text',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Hover', 'Pointer down'],
+        description:
+          'Badge text inside a button must have at least 4.5:1 contrast with the Badge background. Check all 14 built-in Badge colors in Rest, Hover, and Pointer down on page and surface backgrounds. This covers 336 pairs per mode. Check custom end content separately.',
+      },
+      {
+        name: 'Visible control boundary',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1 if needed',
+        states: ['Rest'],
+        description:
+          'The button edge needs 3:1 contrast only when users need it to see the control. A text-only button can rely on its label.',
+      },
+      {
+        name: 'Keyboard focus indicator',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Focus visible'],
+        description:
+          'The focus outline needs at least 3:1 contrast with the area around the button. Check every style. Destructive buttons use a red outline.',
+      },
+      {
+        name: 'Disabled appearance',
+        category: 'Color contrast',
+        criterion: '1.4.3 and 1.4.11 exceptions',
+        requirement: 'Not required',
+        states: ['Disabled'],
+        description:
+          'Disabled controls do not need to meet these contrast ratios.',
+      },
+    ],
     anatomy: [
       {name: 'Icon', required: false, description: 'A leading icon that reinforces the label, like a trash icon on a Delete button.'},
       {name: 'Label', required: true, description: 'The visible text describing the action. Also used as the accessible name.'},

package/src/ButtonGroup/ButtonGroup.doc.mjs

@@ -39,6 +39,53 @@ export const docs = {
   usage: {
     description:
       'ButtonGroup joins related actions into a single connected control. Use it when multiple buttons represent related choices or operations that belong together visually, like copy/cut/paste, or undo/redo.',
+    accessibility: [
+      {
+        name: 'Text label',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Hover', 'Pointer down'],
+        description:
+          'Text in each button must have at least 4.5:1 contrast with its background in every state. For Hover and Pointer down, measure the final background after the overlay is applied.',
+      },
+      {
+        name: 'Essential icon or spinner arc',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Icon only', 'Loading'],
+        description:
+          'An icon used instead of text must have at least 3:1 contrast with the button background. The moving spinner arc must also meet 3:1. An icon beside a visible label does not need its own check.',
+      },
+      {
+        name: 'Visible control boundary',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1 if needed',
+        states: ['Rest'],
+        description:
+          'Some groups need a divider or edge to show each button. That divider or edge must have at least 3:1 contrast.',
+      },
+      {
+        name: 'Keyboard focus indicator',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Focus visible'],
+        description:
+          'The focus outline must have at least 3:1 contrast with the area around it.',
+      },
+      {
+        name: 'Disabled appearance',
+        category: 'Color contrast',
+        criterion: '1.4.3 and 1.4.11 exceptions',
+        requirement: 'Not required',
+        states: ['Disabled'],
+        description:
+          'Disabled controls do not need to meet these contrast ratios.',
+      },
+    ],
     bestPractices: [
       {guidance: true, description: 'Group buttons that perform related actions on the same object, like copy, cut, paste on selected text.'},
       {guidance: true, description: 'Use the same variant for all buttons in a group so they look like a single connected unit.'},

package/src/Carousel/Carousel.test.tsx

@@ -850,4 +850,87 @@ describe('Carousel', () => {
       expect(scroller).not.toHaveAttribute('data-padding');
     });
   });
+
+  describe('edge fade', () => {
+    function getScroller() {
+      const region = screen.getByRole('region');
+      return region.firstElementChild as HTMLElement;
+    }
+
+    function makeOverflowing(el: HTMLElement, scrollLeft: number) {
+      Object.defineProperty(el, 'scrollWidth', {
+        value: 500,
+        configurable: true,
+      });
+      Object.defineProperty(el, 'clientWidth', {
+        value: 200,
+        configurable: true,
+      });
+      Object.defineProperty(el, 'scrollLeft', {
+        value: scrollLeft,
+        writable: true,
+        configurable: true,
+      });
+      fireEvent.scroll(el);
+    }
+
+    function injectedCss(): string {
+      let out = '';
+      for (const sheet of Array.from(document.styleSheets)) {
+        try {
+          for (const rule of Array.from(sheet.cssRules)) {
+            out += rule.cssText + '\n';
+          }
+        } catch {
+          // Ignore cross-origin sheets.
+        }
+      }
+      return out;
+    }
+
+    it('fades the physical left edge when only the start overflows (LTR)', () => {
+      render(
+        <Carousel aria-label="Fade">
+          <div>Item 1</div>
+          <div>Item 2</div>
+        </Carousel>,
+      );
+      const scroller = getScroller();
+      makeOverflowing(scroller, 300);
+      expect(getComputedStyle(scroller).maskImage).toContain(
+        'linear-gradient(to right',
+      );
+    });
+
+    it('fades the physical right edge when only the end overflows (LTR)', () => {
+      render(
+        <Carousel aria-label="Fade">
+          <div>Item 1</div>
+          <div>Item 2</div>
+        </Carousel>,
+      );
+      const scroller = getScroller();
+      makeOverflowing(scroller, 0);
+      expect(getComputedStyle(scroller).maskImage).toContain(
+        'linear-gradient(to left',
+      );
+    });
+
+    it('mirrors both single-edge fade gradients under RTL', () => {
+      render(
+        <Carousel aria-label="Fade">
+          <div>Item 1</div>
+          <div>Item 2</div>
+        </Carousel>,
+      );
+      const css = injectedCss();
+      expect(css).toMatch(
+        /:is\(\[dir="rtl"\][^)]*\)[^{]*\{\s*mask-image:\s*linear-gradient\(to left/,
+      );
+      expect(css).toMatch(
+        /:is\(\[dir="rtl"\][^)]*\)[^{]*\{\s*mask-image:\s*linear-gradient\(to right/,
+      );
+    });
+  });
+
 });

package/src/Carousel/Carousel.tsx

@@ -178,10 +178,16 @@ const styles = stylex.create({
     maskImage: 'none',
   },
   fadeStart: {
-    maskImage: `linear-gradient(to right, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+    maskImage: {
+      default: `linear-gradient(to right, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+      ':is([dir="rtl"] *)': `linear-gradient(to left, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+    },
   },
   fadeEnd: {
-    maskImage: `linear-gradient(to left, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+    maskImage: {
+      default: `linear-gradient(to left, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+      ':is([dir="rtl"] *)': `linear-gradient(to right, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+    },
   },
   fadeBoth: {
     maskImage: `linear-gradient(to right, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']}, black calc(100% - ${spacingVars['--spacing-1']}), rgba(0,0,0,0.3) calc(100% - 2px), transparent 100%)`,

package/src/IconButton/IconButton.doc.mjs

@@ -74,6 +74,44 @@ export const docs = {
 
   usage: {
     description: 'A button that shows only an icon with no visible text. Use IconButton in toolbars, table rows, and compact UI where space is tight and the icon is universally understood.',
+    accessibility: [
+      {
+        name: 'Essential icon or spinner arc',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Rest', 'Hover', 'Pointer down', 'Loading'],
+        description:
+          'IconButton has no visible label. Its icon must have at least 3:1 contrast with the button background in Rest, Hover, and Pointer down. The moving spinner arc must also meet 3:1 while loading.',
+      },
+      {
+        name: 'Visible control boundary',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1 if needed',
+        states: ['Rest'],
+        description:
+          'The button edge needs 3:1 contrast only when users need it to see the control.',
+      },
+      {
+        name: 'Keyboard focus indicator',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Focus visible'],
+        description:
+          'The focus outline must have at least 3:1 contrast with the area around the button. Check the red outline on destructive buttons too.',
+      },
+      {
+        name: 'Disabled appearance',
+        category: 'Color contrast',
+        criterion: '1.4.3 and 1.4.11 exceptions',
+        requirement: 'Not required',
+        states: ['Disabled'],
+        description:
+          'Disabled controls do not need to meet these contrast ratios.',
+      },
+    ],
     bestPractices: [
       { guidance: true, description: 'Make the aria-label specific: a trash icon labeled "Delete conversation" is clearer than just "Delete" for screen readers.' },
       { guidance: true, description: 'Add a tooltip: even a gear icon can mean Settings, Preferences, or Configure.' },

package/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.

package/src/SegmentedControl/SegmentedControl.doc.mjs

@@ -98,6 +98,62 @@ export const docs = {
   usage: {
     description:
       'A segmented button group that allows users to make a single selection from a small set of mutually exclusive options. Use SegmentedControl when all options should be visible at once and the selection controls a value or mode, not page navigation.',
+    accessibility: [
+      {
+        name: 'Text label',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Hover', 'Selected'],
+        description:
+          'Each label must have at least 4.5:1 contrast with its segment background. Check unselected, Hover, and selected colors as they appear on screen.',
+      },
+      {
+        name: 'Essential icon',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Icon only'],
+        description:
+          'When a segment has no visible label, its icon must have at least 3:1 contrast with the segment background. An icon beside a visible label does not need its own check.',
+      },
+      {
+        name: 'Selected state indicator',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1 if relied upon',
+        states: ['Selected'],
+        description:
+          'The selected background must reach 3:1 only when users need it to tell selected from unselected. Label color and weight also show selection.',
+      },
+      {
+        name: 'Visible control boundary',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1 if needed',
+        states: ['Rest'],
+        description:
+          'The control edge or segment borders need at least 3:1 contrast when users need them to see the choices.',
+      },
+      {
+        name: 'Keyboard focus indicator',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Focus visible'],
+        description:
+          'The focus outline must have at least 3:1 contrast with the area around the segment. Check it on the track and selected background.',
+      },
+      {
+        name: 'Disabled appearance',
+        category: 'Color contrast',
+        criterion: '1.4.3 and 1.4.11 exceptions',
+        requirement: 'Not required',
+        states: ['Disabled'],
+        description:
+          'Disabled controls do not need to meet these contrast ratios.',
+      },
+    ],
     bestPractices: [
       {guidance: true, description: 'Use for switching between 2–5 mutually exclusive views or modes where all options should be visible.'},
       {guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},

package/src/ToggleButton/ToggleButton.doc.mjs

@@ -122,6 +122,62 @@ export const docs = {
   usage: {
     description:
       'ToggleButton switches between selected and unselected states to represent a persistent on/off choice. Use it standalone for binary actions like bold, mute, or favorite, or inside a ToggleButtonGroup for single-select or multi-select toolbar controls.',
+    accessibility: [
+      {
+        name: 'Text label',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Unselected', 'Selected', 'Hover', 'Pointer down'],
+        description:
+          'The label must have at least 4.5:1 contrast with the button background when selected and unselected. For Hover and Pointer down, measure the final background after the overlay is applied.',
+      },
+      {
+        name: 'Essential icon or spinner arc',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Icon only', 'Loading'],
+        description:
+          'An icon-only ToggleButton must have at least 3:1 contrast between its icon and button background. The moving spinner arc must also meet 3:1. An icon beside a visible label does not need its own check.',
+      },
+      {
+        name: 'Selected state indicator',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1 if relied upon',
+        states: ['Selected'],
+        description:
+          'The selected background must reach 3:1 only when users need it to tell selected from unselected. Label weight or a changed icon can also show selection.',
+      },
+      {
+        name: 'Visible control boundary',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1 if needed',
+        states: ['Rest'],
+        description:
+          'The button edge needs 3:1 contrast only when users need it to see the control. A visible label or icon can show the control instead.',
+      },
+      {
+        name: 'Keyboard focus indicator',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Focus visible'],
+        description:
+          'The focus outline must have at least 3:1 contrast with the area around the button. Check both selected and unselected states.',
+      },
+      {
+        name: 'Disabled appearance',
+        category: 'Color contrast',
+        criterion: '1.4.3 and 1.4.11 exceptions',
+        requirement: 'Not required',
+        states: ['Disabled'],
+        description:
+          'Disabled controls do not need to meet these contrast ratios.',
+      },
+    ],
     bestPractices: [
       {guidance: true, description: 'Use a filled or colored icon for the pressed state so users can see the current state at a glance: an outline star vs a solid star, for example.'},
       {guidance: true, description: 'Keep the label identical between pressed and unpressed states. Let the visual treatment (icon, weight, background) communicate the change.'},

package/src/theme/themingTargets.test.ts

@@ -3,8 +3,10 @@
 /* eslint-disable @typescript-eslint/no-require-imports */
 /**
  * @file Guards `theming.targets` against the real `themeProps()` call sites (#3741).
- * @input Component sources (*.tsx/*.ts) and their `{Name}.doc.mjs` files.
- * @output Vitest failures naming each undocumented class / visual prop.
+ * @input Core/Lab component sources (*.tsx/*.ts), their `{Name}.doc.mjs`
+ *   files, and the Lab promotion-candidate manifest.
+ * @output Vitest failures naming each undocumented class / visual prop on the
+ *   stable Core surface or a capability-participating Lab component.
  * @position Sibling of derivedVarRegistry.test.ts, which already validates the
  *   OTHER fields of the same `theming` block (`vars`, `derived`). `targets` was
  *   the one field with no machine check, so it drifted — twice (#3652, #3680).
@@ -22,6 +24,11 @@
  * `visualProps` or `states`. Docs may list MORE than the source passes —
  * components forward props they don't themselves reflect (Timestamp passes
  * `{format}` but documents `type`/`color`/`format`), and that is intentional.
+ *
+ * Lab is capability-based: a component participates when it already declares
+ * `theming.targets` or enters the existing promotion-candidate manifest. Other
+ * Lab components remain free to iterate with runtime hooks that are not yet a
+ * documented public theming promise.
  */
 
 import {describe, it, expect} from 'vitest';
@@ -30,7 +37,23 @@ import {join, relative} from 'node:path';
 import ts from 'typescript';
 import {stableClassName} from '../naming';
 
-const SRC_DIR = join(__dirname, '..');
+const CORE_SRC_DIR = join(__dirname, '..');
+const LAB_SRC_DIR = join(__dirname, '../../../lab/src');
+const LAB_PROMOTION_MANIFEST = join(
+  __dirname,
+  '../../../../internal/lab-readiness/manifest.mjs',
+);
+
+interface LabPromotionCandidate {
+  sourceDir: string;
+}
+
+const {CANDIDATES: labPromotionCandidates} = require(
+  LAB_PROMOTION_MANIFEST,
+) as {CANDIDATES: LabPromotionCandidate[]};
+const LAB_PROMOTION_DIRS = new Set(
+  labPromotionCandidates.map(candidate => candidate.sourceDir),
+);
 
 // ---------------------------------------------------------------------------
 // Source scanning: find themeProps() call sites via the TypeScript AST
@@ -314,6 +337,7 @@ type DocBlock = {theming?: {targets?: DocTarget[]}};
 type ComponentDocModule = {docs?: DocBlock; docsZh?: DocBlock};
 
 interface ComponentInfo {
+  packageName: 'core' | 'lab';
   dir: string;
   sites: ThemeTargetSite[];
   /** The doc blocks that carry theming.targets, by the key they live under. */
@@ -328,7 +352,10 @@ interface ComponentInfo {
  * Reads the file as text rather than requiring it: this runs for directories
  * that have no doc of their own, so most candidates are misses.
  */
-function docFilesDocumenting(classNames: Set<string>): string[] {
+function docFilesDocumenting(
+  srcDir: string,
+  classNames: Set<string>,
+): string[] {
   const matches: string[] = [];
   const walk = (dir: string): void => {
     for (const entry of readdirSync(dir, {withFileTypes: true})) {
@@ -346,18 +373,22 @@ function docFilesDocumenting(classNames: Set<string>): string[] {
       }
     }
   };
-  walk(SRC_DIR);
+  walk(srcDir);
   return matches;
 }
 
-function discoverComponents(): ComponentInfo[] {
+function discoverComponents(
+  srcDir: string,
+  packageName: ComponentInfo['packageName'],
+  requiredDirs: ReadonlySet<string> = new Set(),
+): ComponentInfo[] {
   const results: ComponentInfo[] = [];
-  const dirs = readdirSync(SRC_DIR, {withFileTypes: true})
+  const dirs = readdirSync(srcDir, {withFileTypes: true})
     .filter(d => d.isDirectory())
     .map(d => d.name);
 
   for (const dir of dirs) {
-    const dirPath = join(SRC_DIR, dir);
+    const dirPath = join(srcDir, dir);
     const dirEntries = readdirSync(dirPath);
 
     const sourceFiles = dirEntries.filter(
@@ -389,10 +420,7 @@ function discoverComponents(): ComponentInfo[] {
     // doc file that CI never checks. (Same guard as derivedVarRegistry.test.ts.)
     const docFiles = dirEntries.includes(`${dir}.doc.mjs`)
       ? [join(dirPath, `${dir}.doc.mjs`)]
-      : docFilesDocumenting(new Set(sites.map(s => s.className)));
-    if (docFiles.length === 0) {
-      continue;
-    }
+      : docFilesDocumenting(srcDir, new Set(sites.map(s => s.className)));
 
     const docBlocks: ComponentInfo['docBlocks'] = [];
     for (const docFile of docFiles) {
@@ -404,18 +432,23 @@ function discoverComponents(): ComponentInfo[] {
       }
       for (const key of ['docs', 'docsZh'] as const) {
         const targets = mod[key]?.theming?.targets;
-        // Only blocks that already document a theming surface are held to it —
-        // a doc with no theming block at all is a separate (documentation) gap.
+        // A normal Core or Lab component enrolls by declaring a theming
+        // surface. Promotion candidates are also enrolled here so a missing
+        // block is a failure rather than a silently skipped readiness gap.
         if (targets != null) {
-          docBlocks.push({key, file: relative(SRC_DIR, docFile), targets});
+          docBlocks.push({key, file: relative(srcDir, docFile), targets});
         }
       }
     }
-    if (docBlocks.length === 0) {
+    const participates =
+      packageName === 'core'
+        ? docBlocks.length > 0
+        : requiredDirs.has(dir) || docBlocks.length > 0;
+    if (!participates) {
       continue;
     }
 
-    results.push({dir, sites, docBlocks});
+    results.push({packageName, dir, sites, docBlocks});
   }
   return results;
 }
@@ -425,24 +458,57 @@ function discoverComponents(): ComponentInfo[] {
 // ---------------------------------------------------------------------------
 
 describe('theming.targets matches the themeProps() call sites', () => {
-  const components = discoverComponents();
+  const components = [
+    ...discoverComponents(CORE_SRC_DIR, 'core'),
+    ...discoverComponents(LAB_SRC_DIR, 'lab', LAB_PROMOTION_DIRS),
+  ];
+
+  it('finds participating Core and Lab components', () => {
+    // A refactor that renames themeProps or drops the Lab package from this
+    // inventory must not silently disable either side of the guard.
+    expect(components.some(component => component.packageName === 'core')).toBe(
+      true,
+    );
+    expect(components.some(component => component.packageName === 'lab')).toBe(
+      true,
+    );
+  });
 
-  it('finds components to check', () => {
-    // A refactor that renames themeProps must not silently disable this file.
-    expect(components.length).toBeGreaterThan(0);
+  it('enrolls every Lab promotion candidate and explicit theming capability', () => {
+    const labDirs = new Set(
+      components
+        .filter(component => component.packageName === 'lab')
+        .map(component => component.dir),
+    );
+    expect([...LAB_PROMOTION_DIRS].filter(dir => !labDirs.has(dir))).toEqual(
+      [],
+    );
+    expect(LAB_PROMOTION_DIRS.has('CircularProgress')).toBe(false);
+    expect(labDirs.has('CircularProgress')).toBe(true);
+    expect(labDirs.has('Schedule')).toBe(false);
   });
 
-  for (const {dir, sites, docBlocks} of components) {
+  for (const {packageName, dir, sites, docBlocks} of components) {
+    const componentLabel = `${packageName}/${dir}`;
     const renderedClasses = [...new Set(sites.map(s => s.className))].sort();
 
+    it(`${componentLabel}: participating components declare theming metadata`, () => {
+      expect(
+        docBlocks,
+        `${componentLabel} participates in the public theming contract but has ` +
+          `no loadable .doc.mjs theming.targets. Lab components participate ` +
+          `when they declare theming.targets or enter the promotion manifest.`,
+      ).not.toHaveLength(0);
+    });
+
     for (const {key, file, targets} of docBlocks) {
       const documented = new Set(targets.map(t => t.className));
 
-      it(`${dir} (${file} ${key}): every rendered class is documented`, () => {
+      it(`${componentLabel} (${file} ${key}): every rendered class is documented`, () => {
         const undocumented = renderedClasses.filter(c => !documented.has(c));
         expect(
           undocumented,
-          `${dir} renders ${undocumented.length} astryx-* class(es) that ` +
+          `${componentLabel} renders ${undocumented.length} astryx-* class(es) that ` +
             `${file} ${key}.theming.targets does not document: ` +
             `${undocumented.join(', ')}. An undocumented class is an ` +
             `unthemeable element — theme authors and codegen read targets[] ` +
@@ -450,7 +516,7 @@ describe('theming.targets matches the themeProps() call sites', () => {
         ).toEqual([]);
       });
 
-      it(`${dir} (${file} ${key}): every visual prop passed to themeProps is documented`, () => {
+      it(`${componentLabel} (${file} ${key}): every visual prop passed to themeProps is documented`, () => {
         const missing: string[] = [];
         for (const site of sites) {
           const target = targets.find(t => t.className === site.className);