Skip to content

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

TypeScript

docs(spec): Skeleton radius is callsite geometry and is not reflected (#10221)

Cindy Zhangf36e57c50806
diff --git a/docs/specs/components/Skeleton/Skeleton.spec.md b/docs/specs/components/Skeleton/Skeleton.spec.md
index 18ffaccadd..f3c7aa8503 100644
--- a/docs/specs/components/Skeleton/Skeleton.spec.md
+++ b/docs/specs/components/Skeleton/Skeleton.spec.md
@@ -38,7 +38,7 @@ system_specs: [spec:AST-009]
| Builder impact | None; the record describes shipped behavior. |
| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. No implementation gap is recorded. |
| Review checks | Reject an exposed-by-default placeholder, a `steps()` timing function, a pulse under reduced motion, or a block that disappears under forced colors. |
-| Governing rules | `architecture:component-theming-surface/INV2`; `architecture:public-component-api/INV5,INV6,INV8`. |
+| Governing rules | `architecture:component-theming-surface/INV2,INV6`; `architecture:public-component-api/INV5,INV6,INV8`. |
This table is a review projection; the body below is authoritative.
@@ -87,7 +87,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| ID | Invariant | Basis |
| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| FR1 | Skeleton renders one childless `div` carrying the `skeleton` target, sized by `width` and `height` (numbers in pixels, strings as CSS), default `100%` each. | Current source and tests |
-| FR2 | `radius` maps `none` to no radius, `0` to `--radius-none`, `1` to `--radius-inner`, `2` to `--radius-element`, `3` and `4` to `--radius-container`, and `rounded` to `--radius-full`; the default is `3`. | Current source |
+| FR2 | `radius` maps `none` to no radius, `0` to `--radius-none`, `1` to `--radius-inner`, `2` to `--radius-element`, `3` and `4` to `--radius-container`, and `rounded` to `--radius-full`; the default is `3`. `radius` is callsite geometry (AV2), like `width` and `height`, and is not reflected through themeProps (`architecture:component-theming-surface` INV6). | Current source |
| FR3 | The block paints `--color-skeleton` at opacity 0.25. Under `prefers-contrast: more` it paints that color mixed 30% toward primary text. Under `forced-colors: active` it paints `GrayText`, which wins over the contrast rule, at full opacity while no pulse runs; with motion allowed the FR4 pulse still varies its opacity. | Current source and tests |
| FR4 | The block pulses its opacity from 0.25 to 0.925 in ten equal held steps and back, alternating indefinitely, each climb and each fall taking `--duration-medium-max` as the theme sets it before `tempo` scales it (`spec:AST-108` FR4), with a linear timing function and no `steps()`. The pulse starts after 1000 ms plus 100 ms times `index`. Under `prefers-reduced-motion: reduce` there is no pulse. | Current source and tests |
| FR5 | `ref` reaches the block. Supported DOM, ARIA, data, and event props, including `data-testid`, reach the block after the default `aria-hidden`; `xstyle`, `className`, and `style` merge in that order after component styles. | Current source and tests |
diff --git a/packages/core/src/theme/themingTargets.test.ts b/packages/core/src/theme/themingTargets.test.ts
index 9074aca7f8..e29602a3ec 100644
--- a/packages/core/src/theme/themingTargets.test.ts
+++ b/packages/core/src/theme/themingTargets.test.ts
@@ -1002,9 +1002,10 @@ describe('theming.targets matches the themeProps() call sites', () => {
});
/**
- * Painted axes that do not reach themeProps() yet. Each key is
- * `Component.prop`; each value says why. Remove the entry when the axis
- * reaches themeProps(). A stale entry fails the guard.
+ * Painted axes that do not reach themeProps(). Each key is `Component.prop`.
+ * Each value says why: the record claim that keeps the axis unreflected, or
+ * the gap that blocks a target. Remove a gap entry when the axis reaches
+ * themeProps(). A stale entry fails the guard.
*/
const UNREFLECTED_STYLE_AXIS_EXCEPTIONS: ReadonlyMap<string, string> = new Map([
[
@@ -1019,8 +1020,8 @@ const UNREFLECTED_STYLE_AXIS_EXCEPTIONS: ReadonlyMap<string, string> = new Map([
],
[
'Skeleton.radius',
- 'The skeleton target paints the radius. Adding the prop to its ' +
- 'themeProps() call is a product change that ships separately.',
+ 'component:Skeleton FR2: radius is callsite geometry, like width and ' +
+ 'height, and is not reflected.',
],
]);
@@ -1049,9 +1050,9 @@ describe('every painted prop axis reaches themeProps()', () => {
`with \`${finding.styleMap}[${finding.prop}]\`, but no themeProps() ` +
`call passes \`${finding.prop}\`. A theme cannot select the ` +
`\`${finding.prop}\` values. Add \`${finding.prop}\` to the ` +
- `themeProps() call on the target that paints it. If no target ` +
- `paints it, add an UNREFLECTED_STYLE_AXIS_EXCEPTIONS entry that ` +
- `says why.`,
+ `themeProps() call on the target that paints it. If a record ` +
+ `keeps the axis unreflected, or no target paints it, add an ` +
+ `UNREFLECTED_STYLE_AXIS_EXCEPTIONS entry that says why.`,
);
expect(unexplained).toEqual([]);
});