@misoto22/kioku-ui 0.0.0 → 0.2.0

package/dist/theme/Theme.d.ts

@@ -1,24 +1,47 @@
 import { type ReactNode } from 'react';
 import { type ThemeDefinition } from '../tokens/contracts.js';
 export type Density = 'compact' | 'standard';
+/**
+ * Which appearance the theme resolves its `light-dark()` pairs against.
+ * `system` follows the reader's own setting.
+ */
+export type ColorMode = 'dark' | 'light' | 'system';
 export interface ThemePersistence {
     read(): string | undefined;
     write(themeId: string): void;
     readDensity?(): string | undefined;
     writeDensity?(density: Density): void;
+    readMode?(): string | undefined;
+    writeMode?(mode: ColorMode): void;
 }
 export interface ThemeProviderProps {
     readonly children: ReactNode;
     readonly defaultDensity?: Density;
+    readonly defaultMode?: ColorMode;
     readonly defaultThemeId: string;
     readonly persistence?: ThemePersistence;
     readonly themes: readonly ThemeDefinition[];
 }
 export interface ThemeContextValue {
     readonly density: Density;
+    readonly mode: ColorMode;
+    readonly setMode: (mode: ColorMode) => void;
+    /**
+     * The element the theme's custom properties are written to. A floating
+     * surface has to portal into this rather than into `document.body`: the
+     * tokens live here, not on the document, so a surface that escapes it
+     * resolves every `var()` to nothing and renders unpainted.
+     */
+    readonly root: HTMLElement | null;
     readonly setDensity: (density: Density) => void;
     readonly setThemeId: (themeId: string) => void;
     readonly theme: ThemeDefinition;
 }
-export declare function ThemeProvider({ children, defaultDensity, defaultThemeId, persistence, themes, }: ThemeProviderProps): import("react").JSX.Element;
+export declare function ThemeProvider({ children, defaultDensity, defaultMode, defaultThemeId, persistence, themes, }: ThemeProviderProps): import("react").JSX.Element;
+/**
+ * The theme, or `null` when there is no provider above. `useTheme` throws in
+ * that case, which is right for a component that cannot work unthemed; a
+ * portal boundary can, so it asks without insisting.
+ */
+export declare function useOptionalTheme(): ThemeContextValue | null;
 export declare function useTheme(): ThemeContextValue;

package/dist/theme/Theme.js

@@ -19,6 +19,12 @@ const grainMask = "url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000
 // StyleX emits semantic-token bridge variables for this generated scope. The
 // host theme values live on ThemeProvider, so the scope must live there too.
 const semanticTokenScopeClass = semanticTokens.__varGroupHash__;
+
+/**
+ * Which appearance the theme resolves its `light-dark()` pairs against.
+ * `system` follows the reader's own setting.
+ */
+
 const densities = ['compact', 'standard'];
 
 // A theme pack fulfills the token contract twice, once per density. Density is
@@ -42,6 +48,10 @@ function validateThemes(themes) {
 function requiredDensity(density, fallback) {
   return densities.includes(density) ? density : fallback;
 }
+const colorModes = ['dark', 'light', 'system'];
+function requiredMode(mode, fallback) {
+  return colorModes.includes(mode) ? mode : fallback;
+}
 function requiredTheme(themes, themeId) {
   const theme = themes.find(({
     id
@@ -57,6 +67,7 @@ function themeStyle(theme) {
 export function ThemeProvider({
   children,
   defaultDensity = 'compact',
+  defaultMode = 'system',
   defaultThemeId,
   persistence,
   themes
@@ -75,12 +86,22 @@ export function ThemeProvider({
     persistence?.writeDensity?.(resolved);
     setCurrentDensity(resolved);
   }, [defaultDensity, persistence]);
+  const [mode, setCurrentMode] = useState(() => requiredMode(persistence?.readMode?.(), defaultMode));
+  const setMode = useCallback(nextMode => {
+    const resolved = requiredMode(nextMode, defaultMode);
+    persistence?.writeMode?.(resolved);
+    setCurrentMode(resolved);
+  }, [defaultMode, persistence]);
+  const [root, setRoot] = useState(null);
   const value = useMemo(() => ({
     density,
+    mode,
+    root,
     setDensity,
+    setMode,
     setThemeId,
     theme
-  }), [density, setDensity, setThemeId, theme]);
+  }), [density, mode, root, setDensity, setMode, setThemeId, theme]);
   const {
     className,
     style
@@ -92,15 +113,38 @@ export function ThemeProvider({
     children: /*#__PURE__*/_jsx("div", {
       className: [semanticTokenScopeClass, className].filter(Boolean).join(' '),
       "data-density": density,
+      "data-mode": mode,
       "data-theme": theme.id,
+      ref: setRoot
+      /*
+       * `color-scheme` is stamped on this element and no other. It is the
+       * element that carries the tokens, and `light-dark()` resolves against
+       * the used color-scheme of the element the value lands on — so a host
+       * that sets the scheme on a div *inside* the provider changes nothing,
+       * which is exactly the bug this replaced. `system` omits the property
+       * so the stylesheet's own `light dark` stands and the reader's setting
+       * decides.
+       */,
       style: {
         ...style,
-        ...themeStyle(theme)
+        ...themeStyle(theme),
+        ...(mode === 'system' ? {} : {
+          colorScheme: mode
+        })
       },
       children: children
     })
   });
 }
+
+/**
+ * The theme, or `null` when there is no provider above. `useTheme` throws in
+ * that case, which is right for a component that cannot work unthemed; a
+ * portal boundary can, so it asks without insisting.
+ */
+export function useOptionalTheme() {
+  return useContext(ThemeContext) ?? null;
+}
 export function useTheme() {
   const theme = useContext(ThemeContext);
   if (!theme) {

package/dist/theme/index.d.ts

@@ -1,2 +1,2 @@
-export { ThemeProvider, useTheme, type Density, type ThemeContextValue, type ThemePersistence, type ThemeProviderProps, } from './Theme.js';
+export { ThemeProvider, useTheme, type ColorMode, type Density, type ThemeContextValue, type ThemePersistence, type ThemeProviderProps, } from './Theme.js';
 export type { ThemeDefinition } from '../tokens/contracts.js';

package/dist/tokens/contracts.d.ts

@@ -1,11 +1,11 @@
 type Roles<Group extends string, Role extends string> = Readonly<{
     [Name in Role]: `${Group}.${Name}`;
 }>;
-type ColorRole = 'canvas' | 'surface' | 'surfaceRaised' | 'surfaceMuted' | 'text' | 'textSecondary' | 'textMuted' | 'textOnAccent' | 'accent' | 'accentHover' | 'accentActive' | 'overlayHover' | 'overlayActive' | 'disabledSurface' | 'disabledText' | 'focus';
+type ColorRole = 'canvas' | 'surface' | 'surfaceRaised' | 'surfaceMuted' | 'text' | 'textSecondary' | 'textMuted' | 'textOnAccent' | 'accent' | 'accentHover' | 'accentActive' | 'overlayHover' | 'overlayActive' | 'disabledSurface' | 'disabledText' | 'focus' | 'scrim';
 type BorderRole = 'default' | 'strong' | 'interactive' | 'disabled' | 'width' | 'style';
 type StatusRole = 'infoSurface' | 'infoText' | 'successSurface' | 'successText' | 'warningSurface' | 'warningText' | 'dangerSurface' | 'dangerText';
 type FocusRole = 'width' | 'offset';
-type TypographyRole = 'fontFamilyBody' | 'fontFamilyHeading' | 'fontFamilyDisplay' | 'fontFamilyMono' | 'fontFeatureSettings' | 'fontSizeXs' | 'fontSizeSm' | 'fontSizeMd' | 'fontSizeLg' | 'fontSizeXl' | 'fontSize2xl' | 'fontWeightRegular' | 'fontWeightMedium' | 'fontWeightStrong' | 'lineHeightBody' | 'lineHeightHeading';
+type TypographyRole = 'fontFamilyBody' | 'fontFamilyHeading' | 'fontFamilyDisplay' | 'fontFamilyMono' | 'fontFeatureSettings' | 'fontSizeXs' | 'fontSizeSm' | 'fontSizeMd' | 'fontSizeLg' | 'fontSizeXl' | 'fontSize2xl' | 'fontWeightRegular' | 'fontWeightMedium' | 'fontWeightStrong' | 'lineHeightBody' | 'lineHeightHeading' | 'letterSpacingTitle' | 'letterSpacingHeading' | 'letterSpacingBody' | 'letterSpacingLabel' | 'letterSpacingEyebrow' | 'letterSpacingMono';
 type SpacingRole = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
 type RadiusRole = 'inner' | 'element' | 'container' | 'page' | 'full';
 type SizeRole = 'controlSm' | 'controlMd' | 'controlLg' | 'hitTarget';
@@ -43,6 +43,7 @@ export declare const tokenContract: {
         readonly disabledSurface: "color.disabledSurface";
         readonly disabledText: "color.disabledText";
         readonly focus: "color.focus";
+        readonly scrim: "color.scrim";
     };
     readonly border: {
         readonly default: "border.default";
@@ -83,6 +84,12 @@ export declare const tokenContract: {
         readonly fontWeightStrong: "typography.fontWeightStrong";
         readonly lineHeightBody: "typography.lineHeightBody";
         readonly lineHeightHeading: "typography.lineHeightHeading";
+        readonly letterSpacingTitle: "typography.letterSpacingTitle";
+        readonly letterSpacingHeading: "typography.letterSpacingHeading";
+        readonly letterSpacingBody: "typography.letterSpacingBody";
+        readonly letterSpacingLabel: "typography.letterSpacingLabel";
+        readonly letterSpacingEyebrow: "typography.letterSpacingEyebrow";
+        readonly letterSpacingMono: "typography.letterSpacingMono";
     };
     readonly spacing: {
         readonly xs: "spacing.xs";

package/dist/tokens/contracts.js

@@ -16,7 +16,8 @@ export const tokenContract = {
     overlayActive: 'color.overlayActive',
     disabledSurface: 'color.disabledSurface',
     disabledText: 'color.disabledText',
-    focus: 'color.focus'
+    focus: 'color.focus',
+    scrim: 'color.scrim'
   },
   border: {
     default: 'border.default',
@@ -56,7 +57,13 @@ export const tokenContract = {
     fontWeightMedium: 'typography.fontWeightMedium',
     fontWeightStrong: 'typography.fontWeightStrong',
     lineHeightBody: 'typography.lineHeightBody',
-    lineHeightHeading: 'typography.lineHeightHeading'
+    lineHeightHeading: 'typography.lineHeightHeading',
+    letterSpacingTitle: 'typography.letterSpacingTitle',
+    letterSpacingHeading: 'typography.letterSpacingHeading',
+    letterSpacingBody: 'typography.letterSpacingBody',
+    letterSpacingLabel: 'typography.letterSpacingLabel',
+    letterSpacingEyebrow: 'typography.letterSpacingEyebrow',
+    letterSpacingMono: 'typography.letterSpacingMono'
   },
   spacing: {
     xs: 'spacing.xs',

package/dist/utils/clamp.d.ts

@@ -0,0 +1,2 @@
+/** Holds a number inside an inclusive range. */
+export declare function clamp(value: number, min: number, max: number): number;

package/dist/utils/clamp.js

@@ -0,0 +1,5 @@
+import "../styles/stylex.css";
+/** Holds a number inside an inclusive range. */
+export function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,3 @@
+export { clamp } from './clamp.js';
+export { mergeIds } from './mergeIds.js';
+export { resolveInvalid } from './resolveInvalid.js';

package/dist/utils/index.js

@@ -0,0 +1,4 @@
+import "../styles/stylex.css";
+export { clamp } from './clamp.js';
+export { mergeIds } from './mergeIds.js';
+export { resolveInvalid } from './resolveInvalid.js';

package/dist/utils/mergeIds.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Joins ids for an ARIA relationship attribute, dropping empty ones. Returns
+ * `undefined` rather than an empty string, because `aria-describedby=""`
+ * points at nothing and confuses some screen readers.
+ */
+export declare function mergeIds(...ids: readonly (string | undefined | false | null)[]): string | undefined;

package/dist/utils/mergeIds.js

@@ -0,0 +1,10 @@
+import "../styles/stylex.css";
+/**
+ * Joins ids for an ARIA relationship attribute, dropping empty ones. Returns
+ * `undefined` rather than an empty string, because `aria-describedby=""`
+ * points at nothing and confuses some screen readers.
+ */
+export function mergeIds(...ids) {
+  const joined = ids.filter(Boolean).join(' ');
+  return joined === '' ? undefined : joined;
+}

package/dist/utils/resolveInvalid.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reads an `aria-invalid` value as a boolean. The attribute accepts strings,
+ * and the string `"false"` means valid — a plain truthiness check would read
+ * it as invalid.
+ */
+export declare function resolveInvalid(value: boolean | 'false' | 'true' | 'grammar' | 'spelling' | undefined): boolean;

package/dist/utils/resolveInvalid.js

@@ -0,0 +1,9 @@
+import "../styles/stylex.css";
+/**
+ * Reads an `aria-invalid` value as a boolean. The attribute accepts strings,
+ * and the string `"false"` means valid — a plain truthiness check would read
+ * it as invalid.
+ */
+export function resolveInvalid(value) {
+  return value !== undefined && value !== false && value !== 'false';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misoto22/kioku-ui",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "description": "Product-neutral React design system foundations.",
   "license": "MIT",
   "repository": {

package/src/Alert/Alert.tsx

@@ -13,6 +13,7 @@ const styles = stylex.create({
     display: 'flex',
     fontFamily: semanticTokens.fontFamilyBody,
     fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingBody,
     gap: semanticTokens.spacingMd,
     lineHeight: semanticTokens.lineHeightBody,
     padding: semanticTokens.spacingMd,

package/src/AlertDialog/AlertDialog.doc.ts

@@ -0,0 +1,22 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const alertDialogDoc = {
+  name: 'AlertDialog',
+  description: 'Asks for a decision that cannot be dismissed by the scrim.',
+  props: [
+    {name: 'children', description: 'Supplies the dialog body.'},
+    {name: 'description', description: 'Adds a described-by summary line.'},
+    {name: 'footer', description: 'Places the decision actions.'},
+    {name: 'onDismiss', description: 'Runs on Escape.'},
+    {name: 'open', description: 'Controls whether the dialog renders.'},
+    {name: 'size', description: 'Selects the maximum surface width.'},
+    {
+      name: 'title',
+      description: 'Names the decision for assistive technology.',
+    },
+  ],
+  inheritedProps: ['DialogProps except dismissOnOutsideClick'],
+  example:
+    '<AlertDialog onDismiss={cancel} open={open} title="Discard draft?">...</AlertDialog>',
+  storyId: 'core-alert-dialog--default',
+} satisfies ComponentDoc;

package/src/AlertDialog/AlertDialog.tsx

@@ -0,0 +1,18 @@
+import {DialogSurface, type DialogProps} from '../Dialog/index.js';
+
+/** Props for a decision the reader must resolve before continuing. */
+export type AlertDialogProps = Omit<DialogProps, 'dismissOnOutsideClick'>;
+
+/**
+ * Asks for a decision that cannot be deferred. Unlike Dialog, a click on the
+ * scrim does not dismiss it — the reader must choose one of the actions.
+ */
+export function AlertDialog(props: AlertDialogProps) {
+  return (
+    <DialogSurface
+      {...props}
+      dismissOnOutsideClick={false}
+      role="alertdialog"
+    />
+  );
+}

package/src/AlertDialog/index.ts

@@ -0,0 +1 @@
+export {AlertDialog, type AlertDialogProps} from './AlertDialog.js';

package/src/AppShell/AppShell.doc.ts

@@ -0,0 +1,30 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const appShellDoc = {
+  name: 'AppShell',
+  description: 'Wraps Layout with a skip link into the main region.',
+  props: [
+    {name: 'aside', description: 'Places a secondary rail after the content.'},
+    {name: 'children', description: 'Supplies the main region content.'},
+    {
+      name: 'contentPadding',
+      description:
+        'Drops the main region gutter when the page supplies its own.',
+    },
+    {name: 'footer', description: 'Places content below the body.'},
+    {name: 'header', description: 'Places the banner above the body.'},
+    {
+      name: 'pageHead',
+      description: 'Opens the main region with a chapter head.',
+    },
+    {
+      name: 'pageIndex',
+      description: 'Hangs a numeral in the margin beside the page head.',
+    },
+    {name: 'sidebar', description: 'Places a primary rail before the content.'},
+    {name: 'skipLinkLabel', description: 'Names the skip link.'},
+  ],
+  inheritedProps: ['None; AppShell composes Layout and owns its skip link'],
+  example: '<AppShell header={<TopNav />}>{page}</AppShell>',
+  storyId: 'core-app-shell--default',
+} satisfies ComponentDoc;

package/src/AppShell/AppShell.tsx

@@ -0,0 +1,93 @@
+import * as stylex from '@stylexjs/stylex';
+import {useId, type ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {useInternationalization} from '../i18n/index.js';
+import {Layout} from '../Layout/index.js';
+
+const styles = stylex.create({
+  // A floating surface, so it carries elevation and no border. It rests above
+  // the banner until a keyboard reader asks for it, then slides into view.
+  skipLink: {
+    backgroundColor: semanticTokens.colorSurfaceRaised,
+    borderRadius: semanticTokens.radiusElement,
+    borderStyle: 'none',
+    boxShadow: semanticTokens.elevationMedium,
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    fontWeight: semanticTokens.fontWeightMedium,
+    insetBlockStart: semanticTokens.spacingSm,
+    insetInlineStart: semanticTokens.spacingSm,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingSm,
+    position: 'fixed',
+    textDecorationLine: 'none',
+    transform: 'translateY(-200%)',
+    transitionDuration: semanticTokens.durationModerate,
+    transitionProperty: 'transform',
+    transitionTimingFunction: semanticTokens.easingEmphasized,
+    zIndex: 1,
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+      transform: 'translateY(0)',
+    },
+  },
+});
+
+/** Props for the application frame. */
+export interface AppShellProps {
+  readonly aside?: ReactNode;
+  readonly children: ReactNode;
+  readonly contentPadding?: boolean;
+  readonly footer?: ReactNode;
+  readonly header?: ReactNode;
+  readonly pageHead?: ReactNode;
+  readonly pageIndex?: ReactNode;
+  readonly sidebar?: ReactNode;
+  readonly skipLinkLabel?: string;
+}
+
+/**
+ * Wraps `Layout` with the one thing every application needs and most forget:
+ * a skip link that jumps a keyboard reader past the banner and rails straight
+ * into the main region.
+ */
+export function AppShell({
+  aside,
+  children,
+  contentPadding = true,
+  footer,
+  header,
+  pageHead,
+  pageIndex,
+  sidebar,
+  skipLinkLabel,
+}: AppShellProps) {
+  const {messages} = useInternationalization();
+  const mainId = useId();
+
+  return (
+    <>
+      <a href={`#${mainId}`} {...stylex.props(styles.skipLink)}>
+        {skipLinkLabel ?? messages.skipToContent}
+      </a>
+      <Layout
+        {...(aside === undefined ? {} : {aside})}
+        contentPadding={contentPadding}
+        {...(footer === undefined ? {} : {footer})}
+        {...(header === undefined ? {} : {header})}
+        mainId={mainId}
+        {...(pageHead === undefined ? {} : {pageHead})}
+        {...(pageIndex === undefined ? {} : {pageIndex})}
+        {...(sidebar === undefined ? {} : {sidebar})}
+      >
+        {children}
+      </Layout>
+    </>
+  );
+}

package/src/AppShell/index.ts

@@ -0,0 +1 @@
+export {AppShell, type AppShellProps} from './AppShell.js';

package/src/AspectRatio/AspectRatio.doc.ts

@@ -0,0 +1,15 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const aspectRatioDoc = {
+  name: 'AspectRatio',
+  description: 'Reserves space at a fixed width-to-height ratio.',
+  props: [
+    {name: 'children', description: 'Supplies the content to frame.'},
+    {name: 'ratio', description: 'Sets the width divided by the height.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children, className, and style',
+  ],
+  example: '<AspectRatio ratio={4 / 3}><img alt="" src={src} /></AspectRatio>',
+  storyId: 'core-aspect-ratio--default',
+} satisfies ComponentDoc;

package/src/AspectRatio/AspectRatio.tsx

@@ -0,0 +1,47 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes, ReactNode} from 'react';
+
+const styles = stylex.create({
+  frame: {
+    display: 'block',
+    overflow: 'hidden',
+    position: 'relative',
+    width: '100%',
+  },
+  content: {
+    blockSize: '100%',
+    insetBlockStart: 0,
+    insetInlineStart: 0,
+    inlineSize: '100%',
+    position: 'absolute',
+  },
+});
+
+/** Props for a box that holds a fixed width-to-height ratio. */
+export interface AspectRatioProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className' | 'style'
+> {
+  readonly children: ReactNode;
+  readonly ratio?: number;
+}
+
+/**
+ * Reserves space at a fixed ratio before its content loads, so a page does
+ * not jump once an image or embed arrives.
+ */
+export function AspectRatio({
+  children,
+  ratio = 16 / 9,
+  ...props
+}: AspectRatioProps) {
+  return (
+    <div
+      {...props}
+      {...stylex.props(styles.frame)}
+      style={{aspectRatio: String(ratio)}}
+    >
+      <div {...stylex.props(styles.content)}>{children}</div>
+    </div>
+  );
+}

package/src/AspectRatio/index.ts

@@ -0,0 +1 @@
+export {AspectRatio, type AspectRatioProps} from './AspectRatio.js';

package/src/AsyncState/AsyncState.tsx

@@ -1,9 +1,43 @@
+import * as stylex from '@stylexjs/stylex';
 import type {ReactNode} from 'react';
 
 import {Alert} from '../Alert/index.js';
+import {semanticTokens} from '../authoring.stylex.js';
 import {EmptyStateContent} from '../EmptyState/index.js';
 import {SpinnerVisual} from '../Spinner/index.js';
 
+const styles = stylex.create({
+  // Loading and empty are the same block at two moments, so they are the same
+  // plate: `EmptyState`'s. Waiting used to be a bare 14px ring on nothing at
+  // all, which meant the region collapsed to the height of a ring and sprang
+  // back the instant the data landed — the reader watched the page move twice
+  // for something whose size never changed.
+  plate: {
+    alignItems: 'center',
+    backgroundColor: semanticTokens.colorSurface,
+    borderRadius: semanticTokens.radiusContainer,
+    boxShadow: semanticTokens.elevationMedium,
+    color: semanticTokens.colorText,
+    display: 'flex',
+    flexDirection: 'column',
+    fontFamily: semanticTokens.fontFamilyBody,
+    gap: semanticTokens.spacingSm,
+    paddingBlockEnd: semanticTokens.spacingXl,
+    paddingBlockStart: semanticTokens.spacing2xl,
+    paddingInline: semanticTokens.spacing2xl,
+    textAlign: 'center',
+  },
+  // What is being waited for, said once. The live region already carries the
+  // same words as its accessible name, so this copy is for the eye only.
+  label: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+  },
+});
+
 export type AsyncStateValue<T> =
   | {readonly kind: 'loading'; readonly label?: string}
   | {
@@ -41,7 +75,14 @@ export function AsyncState<T>({children, state}: AsyncStateProps<T>) {
     state.kind === 'loading' ? (state.label ?? 'Loading') : undefined;
   const statusContent =
     state.kind === 'loading' ? (
-      <SpinnerVisual />
+      <div {...stylex.props(styles.plate)}>
+        <SpinnerVisual />
+        {state.label === undefined ? null : (
+          <span aria-hidden="true" {...stylex.props(styles.label)}>
+            {state.label}
+          </span>
+        )}
+      </div>
     ) : state.kind === 'empty' ? (
       <EmptyStateContent
         action={state.action}

package/src/Avatar/Avatar.doc.ts

@@ -0,0 +1,16 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const avatarDoc = {
+  name: 'Avatar',
+  description: 'Shows one person or entity, falling back to initials.',
+  props: [
+    {name: 'name', description: 'Names the person and supplies the initials.'},
+    {name: 'size', description: 'Selects the square size.'},
+    {name: 'src', description: 'Points at the likeness to show.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLSpanElement> except children and className',
+  ],
+  example: '<Avatar name="Ada Lovelace" src="/ada.jpg" />',
+  storyId: 'core-avatar--default',
+} satisfies ComponentDoc;