@arbor-education/design-system.components 0.25.3 → 0.25.5

package/src/components/skeleton/Skeleton.stories.tsx

@@ -0,0 +1,748 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { useState } from 'react';
+import { Skeleton } from './Skeleton.js';
+import { Avatar } from 'Components/avatar/Avatar.js';
+import { Button } from 'Components/button/Button.js';
+import { Card } from 'Components/card/Card.js';
+import { Heading } from 'Components/heading/Heading.js';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'Skeleton is an animated pulsing placeholder that communicates to users that content is loading.',
+  'Wrap your real content as `children` — the skeleton matches its dimensions automatically.',
+  'When data arrives, flip `loading` to `false` and the real content appears.',
+].join(' ');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **While fetching data** for a named region of the UI — a student profile, a report table, a list of events',
+  '- **Wrapping real content** — pass `children` and toggle `loading`; the skeleton sizes itself to match the wrapped element automatically',
+  '- **Multiple independent placeholders** in the same region — compose separate Skeleton instances, one per content element',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Measurable async operation (file upload, multi-step wizard) | [`Progress`](?path=/docs/components-progress--docs) |',
+  '| Unknown-duration background process | Spinner (Icon `name="loader"` with CSS rotation animation) |',
+  '| Content that loads instantly from cache | Nothing — a flash of skeleton is jarring |',
+  '| Content that is purely dynamic in size (infinite scroll, variable-length tables) | Nothing — a mismatched skeleton causes layout shift |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**Wrap the real content as children** — the skeleton sizes itself to match automatically:',
+  '',
+  '```tsx',
+  '<Skeleton loading={isLoading}>',
+  '  <span>{student.name}</span>',
+  '</Skeleton>',
+  '```',
+  '',
+  '**`width` and `height` are escape hatches** for cases where you cannot wrap the real element',
+  '(e.g. approximating the width of a text line whose content is unknown):',
+  '',
+  '```tsx',
+  '<Skeleton loading={isLoading} width="160px" height="20px" />',
+  '```',
+  '',
+  '**`loading={false}` with no children renders an empty fragment** — nothing in the DOM at all.',
+  'This is intentional and useful for conditional rendering; the component unmounts cleanly.',
+  '',
+  '**Circle shapes** require `style={{ borderRadius: \'50%\' }}` — there is no `shape` prop.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '`aria-hidden="true"` is hardcoded on the pulsing placeholder span — screen readers skip it entirely. This is correct behaviour.',
+  'This attribute is set explicitly after the `{...props}` spread, so consumers **cannot** override it.',
+  '',
+  'When `loading` flips to `false` and meaningful content appears, screen readers will not announce the change automatically.',
+  'If that announcement matters, wrap the containing region in `aria-live="polite"`:',
+  '',
+  '```tsx',
+  '<section aria-live="polite" aria-busy={isLoading}>',
+  '  <Skeleton loading={isLoading}>',
+  '    <span>{student.name}</span>',
+  '  </Skeleton>',
+  '</section>',
+  '```',
+  '',
+  '**Design tokens:**',
+  '',
+  '| Token | Value | Used for |',
+  '|---|---|---|',
+  '| `--color-grey-200` | `#dfdfdf` | Resting background colour |',
+  '| `--color-grey-100` | `#efefef` | Animation pulse peak (lighter) |',
+  '| `--border-radius-xsmall` | `4px` | Corner radius |',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { Skeleton } from '@arbor-education/design-system.components';",
+  '',
+  'function MyComponent(props: Skeleton.Props) { ... }',
+  '```',
+  '',
+  '| Type | Description |',
+  '|---|---|',
+  '| `Skeleton.Props` | Full props interface |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Progress](?path=/docs/components-progress--docs) · [Avatar](?path=/docs/components-avatar--docs) · [Card](?path=/docs/components-card--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
+
+function SkeletonDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta = {
+  title: 'Components/Skeleton',
+  component: Skeleton,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: SkeletonDocsPage,
+    },
+  },
+  argTypes: {
+    loading: {
+      control: 'boolean',
+      description: [
+        'Controls whether the pulsing placeholder is shown.',
+        '`true` (default) renders the animated `<span>`. `false` renders `children` directly — or an empty fragment if no children are provided.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'true' },
+      },
+    },
+    width: {
+      control: 'text',
+      description: [
+        'Override the skeleton width. Accepts any CSS value (`"200px"`, `"100%"`, `"12rem"`) or a number (converted to pixels).',
+        'Only needed when you cannot wrap the real element as `children` — the skeleton normally sizes itself to its children.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string | number' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    height: {
+      control: 'text',
+      description: [
+        'Override the skeleton height. Same rules as `width`.',
+        'Only needed when you cannot wrap the real element as `children`.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string | number' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    style: {
+      control: false,
+      description: [
+        'Additional inline styles applied to the skeleton span.',
+        'Primary use case: `style={{ borderRadius: \'50%\' }}` for a circular placeholder.',
+        '⚠️ Spreads LAST in the internal style object (`{ width, height, ...style }`),',
+        'so it overrides `width`/`height` props for the same CSS property. Avoid setting width or height in both places.',
+      ].join(' '),
+      table: {
+        type: { summary: 'React.CSSProperties' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    className: {
+      control: false,
+      description: 'Additional CSS class names merged with `ds-skeleton`. Only applied when `loading={true}`.',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    children: {
+      control: false,
+      description: [
+        'The real content the skeleton is standing in for.',
+        'While `loading={true}` the children are rendered but hidden — they determine the skeleton\'s size.',
+        'When `loading={false}` the skeleton disappears and children render normally.',
+        'When no children are provided and `loading={false}`, the component returns an empty React fragment.',
+      ].join(' '),
+      table: {
+        type: { summary: 'React.ReactNode' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+  },
+} satisfies Meta<typeof Skeleton>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Template components for stateful and composed stories.
+// ---------------------------------------------------------------------------
+
+const MultipleLinesTmpl = () => (
+  <div
+    style={{
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 'var(--spacing-xsmall)',
+      width: '360px',
+    }}
+  >
+    <Skeleton width="100%" height="1em" />
+    <Skeleton width="85%" height="1em" />
+    <Skeleton width="60%" height="1em" />
+  </div>
+);
+
+const LoadingToLoadedTmpl = () => {
+  const [loading, setLoading] = useState(true);
+  return (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+        alignItems: 'flex-start',
+      }}
+    >
+      <Button onClick={() => setLoading(prev => !prev)}>
+        {loading ? 'Show content' : 'Show skeleton'}
+      </Button>
+      <Skeleton loading={loading}>
+        <span className="ds-text">Maya Patel — Year 9</span>
+      </Skeleton>
+    </div>
+  );
+};
+
+const CircleShapeTmpl = () => (
+  <div style={{ display: 'flex', gap: 'var(--spacing-large)', alignItems: 'center' }}>
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)', alignItems: 'center' }}>
+      <Skeleton style={{ borderRadius: '50%' }}>
+        <Avatar size="medium" initials="JC" alt="Joe Carter" />
+      </Skeleton>
+      <span className="ds-text" style={{ color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }}>medium</span>
+    </div>
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)', alignItems: 'center' }}>
+      <Skeleton style={{ borderRadius: '50%' }}>
+        <Avatar size="large" initials="JC" alt="Joe Carter" />
+      </Skeleton>
+      <span className="ds-text" style={{ color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }}>large</span>
+    </div>
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)', alignItems: 'center' }}>
+      <Skeleton style={{ borderRadius: '50%' }}>
+        <Avatar size="extra-large" initials="JC" alt="Joe Carter" />
+      </Skeleton>
+      <span className="ds-text" style={{ color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }}>extra-large</span>
+    </div>
+  </div>
+);
+
+const FullWidthTmpl = () => (
+  <div style={{ width: '360px' }}>
+    <Skeleton width="100%" height="20px" />
+  </div>
+);
+
+const AvatarCircleTmpl = () => {
+  const [loading, setLoading] = useState(true);
+  return (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+        alignItems: 'flex-start',
+      }}
+    >
+      <Button onClick={() => setLoading(prev => !prev)}>
+        {loading ? 'Show content' : 'Show skeleton'}
+      </Button>
+      <Skeleton loading={loading} style={{ borderRadius: '50%' }}>
+        <Avatar size="large" initials="JC" alt="Joe Carter" />
+      </Skeleton>
+    </div>
+  );
+};
+
+const CardLayoutTmpl = () => {
+  const [loading, setLoading] = useState(true);
+  return (
+    <div
+      style={{
+        width: '360px',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <Button onClick={() => setLoading(prev => !prev)}>
+        {loading ? 'Show content' : 'Show skeleton'}
+      </Button>
+      <Card>
+        <div style={{ display: 'flex', gap: 'var(--spacing-large)', alignItems: 'flex-start' }}>
+          <Skeleton loading={loading} style={{ borderRadius: '50%' }}>
+            <Avatar size="large" initials="JC" alt="Joe Carter" />
+          </Skeleton>
+          <div
+            style={{
+              display: 'flex',
+              flexDirection: 'column',
+              gap: 'var(--spacing-xsmall)',
+              flex: 1,
+            }}
+          >
+            <Skeleton loading={loading}>
+              <Heading level={2}>Joe Carter</Heading>
+            </Skeleton>
+            <Skeleton loading={loading}>
+              <Heading level={4}>Form 10B</Heading>
+            </Skeleton>
+          </div>
+        </div>
+      </Card>
+    </div>
+  );
+};
+
+const ExplicitDimensionsTmpl = () => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+    <div>
+      <p className="ds-text" style={{ margin: '0 0 var(--spacing-xsmall)' }}>
+        Approximate text line (unknown content, known approximate width)
+      </p>
+      <Skeleton width="200px" height="1em" />
+    </div>
+    <div>
+      <p className="ds-text" style={{ margin: '0 0 var(--spacing-xsmall)' }}>
+        Approximate paragraph block (multiple lines, varying width)
+      </p>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+        <Skeleton width="100%" height="1em" />
+        <Skeleton width="85%" height="1em" />
+        <Skeleton width="60%" height="1em" />
+      </div>
+    </div>
+    <div>
+      <p className="ds-text" style={{ margin: '0 0 var(--spacing-xsmall)' }}>
+        Full-width block (e.g. a banner or table row)
+      </p>
+      <Skeleton width="100%" height="48px" />
+    </div>
+  </div>
+);
+
+const AccessibilityPatternTmpl = () => {
+  const [loading, setLoading] = useState(true);
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', alignItems: 'flex-start' }}>
+      <Button onClick={() => setLoading(prev => !prev)}>
+        {loading ? 'Reveal content' : 'Reset to loading'}
+      </Button>
+      <section aria-live="polite" aria-busy={loading}>
+        <Heading level={3} style={{ marginBottom: 'var(--spacing-xsmall)' }}>Student profile</Heading>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+          <Skeleton loading={loading} width="180px" height="16px">
+            <span className="ds-text">Maya Patel — Year 10</span>
+          </Skeleton>
+          <Skeleton loading={loading} width="140px" height="16px">
+            <span className="ds-text">Form: 10B/Tu</span>
+          </Skeleton>
+        </div>
+      </section>
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      loading: true,
+    },
+    render: args => (
+      <Skeleton {...args}>
+        <span className="ds-text">Joe Carter — Year 9</span>
+      </Skeleton>
+    ),
+  },
+  [
+    'Toggle `loading` in the Controls panel to see the skeleton replaced by the real content.',
+    'No `width` or `height` is set — the skeleton sizes itself to match the wrapped `<span>`.',
+  ].join(' '),
+);
+
+export const CircleShape: Story = withDescription(
+  {
+    render: CircleShapeTmpl,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Avatar, Skeleton } from '@arbor-education/design-system.components';
+
+function AvatarSkeletonExample() {
+  return (
+    // Wrap the Avatar — the skeleton sizes itself automatically.
+    // style={{ borderRadius: '50%' }} rounds the skeleton to match the Avatar's shape.
+    <Skeleton style={{ borderRadius: '50%' }}>
+      <Avatar size="large" initials="JC" alt="Joe Carter" />
+    </Skeleton>
+  );
+}
+export default AvatarSkeletonExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Wrap the real Avatar and add `style={{ borderRadius: \'50%\' }}` — the skeleton matches the Avatar\'s dimensions automatically.',
+    'There is no `shape` prop; `style` is the escape hatch for corner radius.',
+  ].join(' '),
+);
+
+export const FullWidth: Story = withDescription(
+  {
+    render: FullWidthTmpl,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Skeleton } from '@arbor-education/design-system.components';
+
+function FullWidthSkeletonExample() {
+  return (
+    // width="100%" fills the parent container.
+    // Control the actual rendered size by sizing the wrapper.
+    <div style={{ width: '360px' }}>
+      <Skeleton width="100%" height="20px" />
+    </div>
+  );
+}
+export default FullWidthSkeletonExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Percentage widths work — `width="100%"` fills the parent container.',
+    'Use this for full-bleed block placeholders like a report title, a section header, or a table cell.',
+    'Control the actual rendered width by sizing the wrapper element.',
+  ].join(' '),
+);
+
+export const MultipleLines: Story = withDescription(
+  {
+    render: MultipleLinesTmpl,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Skeleton } from '@arbor-education/design-system.components';
+
+function MultipleLinesExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)', width: '360px' }}>
+      <Skeleton width="100%" height="1em" />
+      <Skeleton width="85%" height="1em" />
+      <Skeleton width="60%" height="1em" />
+    </div>
+  );
+}
+export default MultipleLinesExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'When you are loading a block of text whose content is unknown, use explicit `width` and `height` to approximate the paragraph shape.',
+    'Use `height="1em"` to match the line height and vary widths to mimic natural text breaks.',
+    'Prefer wrapping real content as `children` when the content is known.',
+  ].join(' '),
+);
+
+export const LoadingToLoaded: Story = withDescription(
+  {
+    render: LoadingToLoadedTmpl,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Button, Skeleton } from '@arbor-education/design-system.components';
+
+function LoadingToLoadedExample() {
+  const [loading, setLoading] = useState(true);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', alignItems: 'flex-start' }}>
+      <Button onClick={() => setLoading(prev => !prev)}>
+        {loading ? 'Show content' : 'Show skeleton'}
+      </Button>
+      <Skeleton loading={loading}>
+        <span>Maya Patel — Year 9</span>
+      </Skeleton>
+    </div>
+  );
+}
+export default LoadingToLoadedExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'The canonical wrap-and-reveal pattern: pass the real content as `children` and drive `loading` from your async state.',
+    'When the data arrives, set `loading={false}` — the pulsing placeholder disappears and the children appear in its place with no additional wrappers or state.',
+  ].join(' '),
+);
+
+export const AvatarCircle: Story = withDescription(
+  {
+    name: 'Avatar circle',
+    render: AvatarCircleTmpl,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Avatar, Button, Skeleton } from '@arbor-education/design-system.components';
+
+function AvatarRevealExample() {
+  const [loading, setLoading] = useState(true);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)', alignItems: 'flex-start' }}>
+      <Button onClick={() => setLoading(prev => !prev)}>
+        {loading ? 'Show content' : 'Show skeleton'}
+      </Button>
+      <Skeleton loading={loading} style={{ borderRadius: '50%' }}>
+        <Avatar size="large" initials="JC" alt="Joe Carter" />
+      </Skeleton>
+    </div>
+  );
+}
+export default AvatarRevealExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'A circular Skeleton wrapping an Avatar — no explicit `width` or `height` needed.',
+    'The skeleton auto-sizes to the wrapped Avatar\'s dimensions.',
+    'Add `style={{ borderRadius: \'50%\' }}` to match the Avatar\'s circular shape.',
+    'When `loading` flips to `false`, the Avatar appears in place of the circle.',
+  ].join(' '),
+);
+
+export const CardLayout: Story = withDescription(
+  {
+    name: 'Card layout',
+    render: CardLayoutTmpl,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Avatar, Button, Card, Heading, Skeleton } from '@arbor-education/design-system.components';
+
+function StudentCardSkeleton() {
+  const [loading, setLoading] = useState(true);
+
+  return (
+    <div style={{ width: '360px', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <Button onClick={() => setLoading(prev => !prev)}>
+        {loading ? 'Show content' : 'Show skeleton'}
+      </Button>
+      <Card>
+        <div style={{ display: 'flex', gap: 'var(--spacing-large)', alignItems: 'flex-start' }}>
+          <Skeleton loading={loading} style={{ borderRadius: '50%' }}>
+            <Avatar size="large" initials="JC" alt="Joe Carter" />
+          </Skeleton>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)', flex: 1 }}>
+            <Skeleton loading={loading}>
+              <Heading level={2}>Joe Carter</Heading>
+            </Skeleton>
+            <Skeleton loading={loading}>
+              <Heading level={4}>Form 10B</Heading>
+            </Skeleton>
+          </div>
+        </div>
+      </Card>
+    </div>
+  );
+}
+export default StudentCardSkeleton;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'A composed Card layout with a circular Avatar skeleton alongside stacked Heading skeletons —',
+    'mirroring the shape and position of the real content.',
+    'All Skeleton instances share a single `loading` state and reveal their children together when the data arrives.',
+  ].join(' '),
+);
+
+export const ExplicitDimensions: Story = withDescription(
+  {
+    name: 'Explicit dimensions',
+    render: ExplicitDimensionsTmpl,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Skeleton } from '@arbor-education/design-system.components';
+
+// Use explicit width/height when you cannot wrap the real element —
+// for example, when approximating text whose content is unknown at load time.
+function TextLineSkeleton() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+      <Skeleton width="100%" height="1em" />
+      <Skeleton width="85%" height="1em" />
+      <Skeleton width="60%" height="1em" />
+    </div>
+  );
+}
+export default TextLineSkeleton;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'When you cannot wrap the real element — for example, when loading a paragraph whose text is unknown — use `width` and `height` to approximate the shape.',
+    'Pass `height="1em"` to match the current line height, and vary widths to suggest natural text breaks.',
+  ].join(' '),
+);
+
+export const AccessibilityPattern: Story = withDescription(
+  {
+    name: 'Accessibility pattern',
+    render: AccessibilityPatternTmpl,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Skeleton } from '@arbor-education/design-system.components';
+
+function StudentProfileSection({ isLoading }: { isLoading: boolean }) {
+  return (
+    <section aria-live="polite" aria-busy={isLoading}>
+      <h3>Student profile</h3>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+        <Skeleton loading={isLoading} width="180px" height="16px">
+          <span>Maya Patel — Year 10</span>
+        </Skeleton>
+        <Skeleton loading={isLoading} width="140px" height="16px">
+          <span>Form: 10B/Tu</span>
+        </Skeleton>
+      </div>
+    </section>
+  );
+}
+export default StudentProfileSection;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Screen readers do not announce when `loading` flips to `false` — the pulsing placeholder is `aria-hidden="true"` and unmounts silently.',
+    'Wrap the region in `aria-live="polite"` with `aria-busy` so assistive technology announces when content becomes available.',
+    'Click the button to see the loading-to-loaded transition.',
+  ].join(' '),
+);