Skip to content

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

TypeScript

[Component Audit] IconButton: every prop is documented, and square targets are proven in a browser (#9757)

Cindy Zhang89255718a0a2
diff --git a/.changeset/icon-button-audit-docs.md b/.changeset/icon-button-audit-docs.md
new file mode 100644
index 0000000000..e65e2e25ae
--- /dev/null
+++ b/.changeset/icon-button-audit-docs.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] IconButton: document `isInterruptible`, `width`, the form props (`type`, `name`, `value`, `form`), and the link props (`href`, `as`, `target`, `rel`), and say that a disabled IconButton with a tooltip stays focusable through `aria-disabled`.
+
+@cixzhang
diff --git a/packages/cli/test/core-prop-docs.known-drift.json b/packages/cli/test/core-prop-docs.known-drift.json
index 165ecdea95..ecf5fff2c0 100644
--- a/packages/cli/test/core-prop-docs.known-drift.json
+++ b/packages/cli/test/core-prop-docs.known-drift.json
@@ -22,16 +22,6 @@
"src/FieldStatus/FieldStatus.doc.mjs FieldStatus.variant type_mismatch",
"src/HoverCard/HoverCard.doc.mjs HoverCard.children required_mismatch",
"src/Icon/Icon.doc.mjs Icon.color type_mismatch",
- "src/IconButton/IconButton.doc.mjs IconButton.as not_in_doc",
- "src/IconButton/IconButton.doc.mjs IconButton.form not_in_doc",
- "src/IconButton/IconButton.doc.mjs IconButton.href not_in_doc",
- "src/IconButton/IconButton.doc.mjs IconButton.isInterruptible not_in_doc",
- "src/IconButton/IconButton.doc.mjs IconButton.name not_in_doc",
- "src/IconButton/IconButton.doc.mjs IconButton.rel not_in_doc",
- "src/IconButton/IconButton.doc.mjs IconButton.target not_in_doc",
- "src/IconButton/IconButton.doc.mjs IconButton.type not_in_doc",
- "src/IconButton/IconButton.doc.mjs IconButton.value not_in_doc",
- "src/IconButton/IconButton.doc.mjs IconButton.width not_in_doc",
"src/Layout/Layout.doc.mjs Layout.children not_in_doc",
"src/Layout/LayoutFooter.doc.mjs LayoutFooter.padding not_in_doc",
"src/Layout/LayoutHeader.doc.mjs LayoutHeader.padding not_in_doc",
diff --git a/packages/core/src/IconButton/IconButton.doc.mjs b/packages/core/src/IconButton/IconButton.doc.mjs
index 17f684a78e..9ca1e2060d 100644
--- a/packages/core/src/IconButton/IconButton.doc.mjs
+++ b/packages/core/src/IconButton/IconButton.doc.mjs
@@ -20,7 +20,8 @@ export const docs = {
{
name: 'icon',
type: 'ReactNode',
- description: 'Icon element rendered inside the button. An Astryx Icon with no explicit size defaults to sm for sm/md buttons and md for lg buttons.',
+ description:
+ 'Icon element rendered inside the button. An Astryx Icon with no explicit size defaults to sm for sm/md buttons and md for lg buttons.',
required: true,
slotElements: [{__element: 'Icon', props: {icon: 'check'}}],
},
@@ -46,19 +47,22 @@ export const docs = {
{
name: 'isLoading',
type: 'boolean',
- description: 'Shows a loading spinner and blocks re-activation while staying focusable (aria-busy + aria-disabled, not native disabled).',
+ description:
+ 'Shows a loading spinner and blocks re-activation while staying focusable (aria-busy + aria-disabled, not native disabled).',
default: 'false',
},
{
name: 'isDisabled',
type: 'boolean',
- description: 'Disables the button.',
+ description:
+ 'Disables the button. When a tooltip is present, uses aria-disabled instead of native disabled so the button stays focusable.',
default: 'false',
},
{
name: 'tooltip',
type: 'string',
- description: 'Tooltip text shown on hover.',
+ description:
+ "Tooltip text shown on hover and keyboard focus. It also describes the button, unless it repeats the button's accessible name.",
},
{
name: 'onClick',
@@ -70,10 +74,69 @@ export const docs = {
type: '(e: MouseEvent) => void | Promise<void>',
description: 'Async click handler with automatic loading state.',
},
+ {
+ name: 'isInterruptible',
+ type: 'boolean',
+ description:
+ 'Keep the button clickable while a clickAction is pending: the spinner and aria-busy still show, but the button is not disabled and the action is not deduped, so a re-click lands and interrupts the in-flight action with a fresh one. Use it for interruptible actions, not fire-once actions (submit, save, pay).',
+ default: 'false',
+ },
+ {
+ name: 'width',
+ type: 'SizeValue',
+ description:
+ 'Width of the button. Numbers are treated as pixels, strings are used as-is. Without it the button keeps its icon-only aspect, square by default; with it the button takes that width.',
+ },
+ {
+ name: 'type',
+ type: "'button' | 'submit' | 'reset'",
+ description: 'HTML button type attribute.',
+ default: "'button'",
+ },
+ {
+ name: 'name',
+ type: 'string',
+ description: 'HTML name attribute for form submission.',
+ },
+ {
+ name: 'value',
+ type: 'string | number | readonly string[]',
+ description: 'HTML value attribute for form submission.',
+ },
+ {
+ name: 'form',
+ type: 'string',
+ description: 'Associates the button with a form element by ID.',
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description:
+ 'When provided, renders the button as a link element (<a> or custom link component). A disabled IconButton still renders a <button>.',
+ },
+ {
+ name: 'as',
+ type: 'ComponentType',
+ description:
+ 'Custom link component to use when href is provided (e.g. Next.js Link).',
+ },
+ {
+ name: 'target',
+ type: 'string',
+ description:
+ 'HTML target attribute when rendered as a link (e.g. "_blank").',
+ },
+ {
+ name: 'rel',
+ type: 'string',
+ description:
+ 'HTML rel attribute when rendered as a link (e.g. "noopener noreferrer").',
+ },
],
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.',
+ 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',
@@ -113,26 +176,68 @@ export const docs = {
},
],
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.' },
- { guidance: true, description: 'Use ghost in toolbars and dense areas to reduce visual clutter.' },
- { guidance: false, description: 'Use IconButton if the action isn\'t obvious from the icon alone; use Button with text.' },
- { guidance: false, description: 'Skip the tooltip; label only reaches screen readers, sighted users need the hover hint.' },
+ {
+ 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.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use ghost in toolbars and dense areas to reduce visual clutter.',
+ },
+ {
+ guidance: false,
+ description:
+ "Use IconButton if the action isn't obvious from the icon alone; use Button with text.",
+ },
+ {
+ guidance: false,
+ description:
+ 'Skip the tooltip; label only reaches screen readers, sighted users need the hover hint.',
+ },
],
},
};
/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
- description: 'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
+ description:
+ 'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
usage: {
- description: 'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
+ description:
+ 'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
bestPractices: [
- { guidance: true, description: 'Make aria-label specific: trash icon labeled "Delete conversation" > just "Delete" for screen readers.' },
- { guidance: true, description: 'Add tooltip: even gear icon can mean Settings/Preferences/Configure.' },
- { guidance: true, description: 'Use ghost in toolbars + dense areas to reduce visual clutter.' },
- { guidance: false, description: "Use IconButton if action isn't obvious from icon alone; use Button w/ text instead." },
- { guidance: false, description: 'Skip tooltip: label only reaches screen readers; sighted users need hover hint.' },
+ {
+ guidance: true,
+ description:
+ 'Make aria-label specific: trash icon labeled "Delete conversation" > just "Delete" for screen readers.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Add tooltip: even gear icon can mean Settings/Preferences/Configure.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use ghost in toolbars + dense areas to reduce visual clutter.',
+ },
+ {
+ guidance: false,
+ description:
+ "Use IconButton if action isn't obvious from icon alone; use Button w/ text instead.",
+ },
+ {
+ guidance: false,
+ description:
+ 'Skip tooltip: label only reaches screen readers; sighted users need hover hint.',
+ },
],
},
propDescriptions: {
@@ -140,11 +245,26 @@ export const docsDense = {
icon: 'icon element rendered inside button; unsized Astryx Icon defaults to sm for sm/md buttons and md for lg',
variant: 'visual style variant',
size: 'size variant',
- elevation: 'resting shadow depth: none|low|med|high; raise for a floating action button (FAB)',
- isLoading: 'shows loading spinner, blocks re-activation but stays focusable (aria-disabled, not native disabled)',
- isDisabled: 'disables button',
- tooltip: 'tooltip text shown on hover',
+ elevation:
+ 'resting shadow depth: none|low|med|high; raise for a floating action button (FAB)',
+ isLoading:
+ 'shows loading spinner, blocks re-activation but stays focusable (aria-disabled, not native disabled)',
+ isDisabled: 'disables button; uses aria-disabled when tooltip present',
+ tooltip:
+ 'tooltip on hover + keyboard focus; also describes the button unless it repeats the accessible name',
onClick: 'standard click handler',
clickAction: 'async click handler w/ automatic loading state',
+ isInterruptible:
+ 'keeps button clickable while clickAction pending; a re-click interrupts it. Not for fire-once actions (submit/save/pay)',
+ width:
+ 'button width; numbers=pixels, strings=as-is; without it keeps the icon-only aspect (square by default)',
+ type: 'HTML button type; defaults to "button"',
+ name: 'HTML name for form submission',
+ value: 'HTML value for form submission',
+ form: 'associates button with form element by ID',
+ href: 'renders as a link; a disabled IconButton stays a <button>',
+ as: 'custom link component used with href',
+ target: 'HTML target when rendered as a link',
+ rel: 'HTML rel when rendered as a link',
},
};
diff --git a/packages/core/src/IconButton/IconButton.test.tsx b/packages/core/src/IconButton/IconButton.test.tsx
index 04f9420e60..b1f054739b 100644
--- a/packages/core/src/IconButton/IconButton.test.tsx
+++ b/packages/core/src/IconButton/IconButton.test.tsx
@@ -42,16 +42,56 @@ describe('IconButton', () => {
expect(visibleText).not.toContain('Settings');
});
- it('forwards variant prop', () => {
- render(
- <IconButton label="Delete" icon={<span>πŸ—‘</span>} variant="destructive" />,
- );
- expect(screen.getByRole('button', {name: 'Delete'})).toBeInTheDocument();
+ it('reflects each variant on the button target', () => {
+ for (const variant of [
+ 'primary',
+ 'secondary',
+ 'ghost',
+ 'destructive',
+ ] as const) {
+ const {unmount} = render(
+ <IconButton label="Delete" icon={<span>πŸ—‘</span>} variant={variant} />,
+ );
+ expect(screen.getByRole('button', {name: 'Delete'})).toHaveAttribute(
+ 'data-variant',
+ variant,
+ );
+ unmount();
+ }
+ });
+
+ it('reflects each size on the button target', () => {
+ for (const size of ['sm', 'md', 'lg'] as const) {
+ const {unmount} = render(
+ <IconButton label="Add" icon={<span>+</span>} size={size} />,
+ );
+ expect(screen.getByRole('button', {name: 'Add'})).toHaveAttribute(
+ 'data-size',
+ size,
+ );
+ unmount();
+ }
+ });
+
+ it('stays icon-only when a caller passes isIconOnly anyway', () => {
+ // The type rejects this prop; an untyped caller can still pass it.
+ const untyped = {isIconOnly: false} as Record<string, unknown>;
+ render(<IconButton label="Settings" icon={<span>βš™</span>} {...untyped} />);
+ const button = screen.getByRole('button', {name: 'Settings'});
+ expect(button).toHaveAttribute('aria-label', 'Settings');
+ expect(button.textContent).not.toContain('Settings');
});
- it('forwards size prop', () => {
- render(<IconButton label="Add" icon={<span>+</span>} size="sm" />);
- expect(screen.getByRole('button', {name: 'Add'})).toBeInTheDocument();
+ it('describes the button with its tooltip, keeping label as the name', () => {
+ render(
+ <IconButton
+ label="Notifications"
+ icon={<span>πŸ””</span>}
+ tooltip="View notifications"
+ />,
+ );
+ const button = screen.getByRole('button', {name: 'Notifications'});
+ expect(button).toHaveAccessibleDescription('View notifications');
});
it.each([
diff --git a/packages/core/src/IconButton/__tests__/IconButtonAudit.a11y.chromium.spec.ts b/packages/core/src/IconButton/__tests__/IconButtonAudit.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..540899809a
--- /dev/null
+++ b/packages/core/src/IconButton/__tests__/IconButtonAudit.a11y.chromium.spec.ts
@@ -0,0 +1,565 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y audit IconButton
+
+/**
+ * @file IconButtonAudit.a11y.chromium.spec.ts
+ * @input Exact-head Core/IconButton stories across sizes, variants, states, themes, and modes
+ * @output Screenshots and fail-closed sensor receipts for the IconButton whole-component audit
+ * @position Component-owned Night Watch browser evidence; CI runs it only for an IconButton audit pull request
+ */
+
+import {createHash} from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {expect, test, type Page} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const OUTPUT = path.resolve('icon-button-audit-evidence');
+const VIEWPORT = {width: 480, height: 320};
+
+type Mode = 'light' | 'dark';
+type Theme = 'neutral' | 'butter';
+type Story =
+ | 'default'
+ | 'ghost'
+ | 'primary'
+ | 'destructive'
+ | 'small'
+ | 'large'
+ | 'with-tooltip'
+ | 'loading'
+ | 'disabled'
+ | 'emoji-icon';
+
+type AuditCase = {
+ key: string;
+ story: Story;
+ mode: Mode;
+ theme: Theme;
+ // Reach the button by keyboard, or hover or press it, before the capture.
+ interaction: 'none' | 'focus' | 'hover' | 'press';
+ // Story args set through the Storybook channel before the capture.
+ args?: Record<string, unknown>;
+ // Adds a key suffix that names a case's story args.
+ suffix?: string;
+};
+
+type AuditReceipt = {
+ passed: boolean;
+ expected: Record<string, unknown>;
+ failures: string[];
+};
+
+// What each story renders, as its args set it.
+const STORY: Record<
+ Story,
+ {label: string; variant: string; size: string; state?: string}
+> = {
+ default: {label: 'Settings', variant: 'secondary', size: 'md'},
+ ghost: {label: 'Settings', variant: 'ghost', size: 'md'},
+ primary: {label: 'Add item', variant: 'primary', size: 'md'},
+ destructive: {label: 'Delete', variant: 'destructive', size: 'md'},
+ small: {label: 'Close', variant: 'ghost', size: 'sm'},
+ large: {label: 'Edit', variant: 'secondary', size: 'lg'},
+ 'with-tooltip': {
+ label: 'Notifications',
+ variant: 'ghost',
+ size: 'md',
+ state: 'tooltip',
+ },
+ loading: {label: 'Saving', variant: 'primary', size: 'md', state: 'loading'},
+ disabled: {
+ label: 'Edit',
+ variant: 'secondary',
+ size: 'md',
+ state: 'disabled',
+ },
+ 'emoji-icon': {label: 'React with rocket', variant: 'ghost', size: 'sm'},
+};
+
+const cases: AuditCase[] = [];
+function add(
+ story: Story,
+ options: {
+ theme?: Theme;
+ interaction?: AuditCase['interaction'];
+ modes?: Mode[];
+ args?: Record<string, unknown>;
+ suffix?: string;
+ } = {},
+) {
+ const theme = options.theme ?? 'neutral';
+ const interaction = options.interaction ?? 'none';
+ for (const mode of options.modes ?? ['light', 'dark']) {
+ const parts = [story, options.suffix, theme];
+ if (interaction !== 'none') {
+ parts.push(interaction);
+ }
+ cases.push({
+ key: `${parts.filter(Boolean).join('-')}-${mode}`,
+ story,
+ mode,
+ theme,
+ interaction,
+ args: options.args,
+ suffix: options.suffix,
+ });
+ }
+}
+
+add('small');
+add('default');
+add('large');
+add('small', {theme: 'butter'});
+add('default', {theme: 'butter'});
+add('large', {theme: 'butter'});
+add('ghost');
+add('primary');
+add('destructive');
+add('default', {interaction: 'focus'});
+add('destructive', {interaction: 'focus', modes: ['light']});
+add('with-tooltip', {interaction: 'focus'});
+add('default', {interaction: 'hover', modes: ['light']});
+add('primary', {interaction: 'press', modes: ['light']});
+add('default', {suffix: 'elevated', args: {elevation: 'med'}});
+add('loading');
+add('disabled');
+add('emoji-icon', {modes: ['light']});
+
+test.describe.configure({retries: 0});
+let server: StaticServer;
+let checkoutSha: string;
+let storybookSha: string;
+
+function storyUrl(item: AuditCase) {
+ return `${server.origin}/iframe.html?id=core-iconbutton--${item.story}&viewMode=story&globals=colorMode:${item.mode};astryxTheme:${item.theme}`;
+}
+
+async function settle(page: Page) {
+ await holdMotionStill(page);
+ await page.evaluate(async () => document.fonts.ready);
+ await page.evaluate(
+ async () =>
+ new Promise<void>(resolve =>
+ requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+ ),
+ );
+ await page.waitForTimeout(40);
+}
+
+async function observe(page: Page) {
+ return page.evaluate(() => {
+ const round = (value: number) => Math.round(value * 10) / 10;
+ function box(element: Element | Range) {
+ const rect = element.getBoundingClientRect();
+ return {
+ left: round(rect.left),
+ top: round(rect.top),
+ width: round(rect.width),
+ height: round(rect.height),
+ };
+ }
+ const root = document.querySelector('#storybook-root') ?? document.body;
+ const button = root.querySelector('.astryx-button');
+ const style = button ? getComputedStyle(button) : null;
+ // An SVG icon, or else the text of a text icon such as an emoji.
+ let glyph: ReturnType<typeof box> | null = null;
+ const svg = button?.querySelector('svg');
+ if (svg) {
+ glyph = box(svg);
+ } else if (button) {
+ const walker = document.createTreeWalker(button, NodeFilter.SHOW_TEXT);
+ let node = walker.nextNode();
+ while (node && !(node.textContent ?? '').trim()) {
+ node = walker.nextNode();
+ }
+ if (node) {
+ const range = document.createRange();
+ range.selectNodeContents(node);
+ glyph = box(range);
+ }
+ }
+ const describedBy = button?.getAttribute('aria-describedby') ?? '';
+ const description = describedBy
+ .split(/\s+/)
+ .filter(Boolean)
+ .map(id => document.getElementById(id)?.textContent?.trim() ?? '')
+ .join(' ');
+ const tooltip = Array.from(
+ document.querySelectorAll<HTMLElement>('[role="tooltip"]'),
+ ).find(element => element.checkVisibility());
+ return {
+ theme: document
+ .querySelector('[data-astryx-theme]')
+ ?.getAttribute('data-astryx-theme'),
+ mode: document.documentElement.getAttribute('data-theme'),
+ viewport: {width: innerWidth, height: innerHeight},
+ dpr: devicePixelRatio,
+ reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+ fonts: document.fonts.status,
+ storybookError:
+ document.querySelector('.sb-show-errordisplay') != null ||
+ document.body.classList.contains('sb-show-errordisplay'),
+ buttonCount: root.querySelectorAll('.astryx-button').length,
+ button: button
+ ? {
+ tagName: button.tagName,
+ ariaLabel: button.getAttribute('aria-label'),
+ textContent: button.textContent ?? '',
+ dataVariant: button.getAttribute('data-variant'),
+ dataSize: button.getAttribute('data-size'),
+ disabled: (button as HTMLButtonElement).disabled,
+ ariaDisabled: button.getAttribute('aria-disabled'),
+ ariaBusy: button.getAttribute('aria-busy'),
+ focused: document.activeElement === button,
+ hovered: button.matches(':hover'),
+ pressed:
+ button.matches(':active') ||
+ button.getAttribute('data-astryx-press') === 'on',
+ dataElevation: button.getAttribute('data-elevation'),
+ boxShadow: style?.boxShadow,
+ transform: style?.transform,
+ backgroundColor: style?.backgroundColor,
+ backgroundImage: style?.backgroundImage,
+ focusVisible: button.matches(':focus-visible'),
+ outlineStyle: style?.outlineStyle,
+ outlineWidth: style?.outlineWidth,
+ paddingInline: `${style?.paddingInlineStart} ${style?.paddingInlineEnd}`,
+ paddingBlock: `${style?.paddingBlockStart} ${style?.paddingBlockEnd}`,
+ box: box(button),
+ }
+ : null,
+ glyph,
+ description,
+ tooltip: tooltip ? (tooltip.textContent ?? '').trim() : null,
+ };
+ });
+}
+
+test.beforeAll(async () => {
+ fs.mkdirSync(OUTPUT, {recursive: true});
+ checkoutSha = execFileSync('git', ['rev-parse', 'HEAD'], {
+ encoding: 'utf8',
+ }).trim();
+ const expected = process.env.ASTRYX_HEAD_SHA;
+ if (expected && expected !== checkoutSha) {
+ throw new Error(
+ `checkout ${checkoutSha} does not match expected head ${expected}`,
+ );
+ }
+ server = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+ const response = await fetch(`${server.origin}/astryx-build-sha.txt`);
+ if (!response.ok) {
+ throw new Error(`Storybook build has no SHA stamp (${response.status})`);
+ }
+ storybookSha = (await response.text()).trim();
+ if (storybookSha !== checkoutSha) {
+ throw new Error(
+ `Storybook ${storybookSha} does not match checkout ${checkoutSha}`,
+ );
+ }
+});
+
+test.afterAll(async () => {
+ await server?.close();
+});
+
+for (const item of cases) {
+ test(item.key, async ({browser}) => {
+ const context = await browser.newContext({
+ viewport: VIEWPORT,
+ deviceScaleFactor: 2,
+ colorScheme: item.mode,
+ reducedMotion: 'reduce',
+ });
+ const page = await context.newPage();
+ const pageErrors: string[] = [];
+ page.on('pageerror', error => pageErrors.push(String(error)));
+ await page.goto(storyUrl(item), {waitUntil: 'load'});
+ await page.locator('#storybook-root .astryx-button').first().waitFor();
+ await settle(page);
+ if (item.args) {
+ await page.evaluate(async args => {
+ const channel = (
+ window as unknown as {
+ __STORYBOOK_ADDONS_CHANNEL__: {
+ emit: (event: string, payload: unknown) => void;
+ once: (event: string, listener: () => void) => void;
+ };
+ }
+ ).__STORYBOOK_ADDONS_CHANNEL__;
+ const storyId = new URLSearchParams(location.search).get('id');
+ await new Promise<void>(resolve => {
+ channel.once('storyRendered', () => resolve());
+ channel.emit('updateStoryArgs', {storyId, updatedArgs: args});
+ });
+ }, item.args);
+ await settle(page);
+ }
+ const target = page.locator('#storybook-root .astryx-button').first();
+ if (item.interaction === 'hover') {
+ await target.hover();
+ await settle(page);
+ }
+ if (item.interaction === 'press') {
+ await target.hover();
+ await page.mouse.down();
+ await settle(page);
+ }
+ if (item.interaction === 'focus') {
+ await page.keyboard.press('Tab');
+ if (item.story === 'with-tooltip') {
+ await page
+ .locator('[role="tooltip"]')
+ .first()
+ .waitFor({state: 'visible'});
+ }
+ await settle(page);
+ }
+ const first = await observe(page);
+ await page.waitForTimeout(100);
+ await settle(page);
+ const observed = await observe(page);
+ const geometryStable =
+ JSON.stringify(first.button?.box) ===
+ JSON.stringify(observed.button?.box);
+
+ const failures: string[] = [];
+ const check = (condition: boolean, message: string) => {
+ if (!condition) {
+ failures.push(message);
+ }
+ };
+ const near = (actual: number, expected: number, tolerance = 1) =>
+ Math.abs(actual - expected) <= tolerance;
+ const spec = STORY[item.story];
+ // Text glyph boxes follow font metrics, so they get a wider tolerance.
+ const centerTolerance = item.story === 'emoji-icon' ? 2 : 1;
+
+ check(storybookSha === checkoutSha, 'storybook build mismatch');
+ check(pageErrors.length === 0, `page errors: ${pageErrors.join(' | ')}`);
+ check(!observed.storybookError, 'storybook error display');
+ check(observed.theme === item.theme, `theme ${observed.theme}`);
+ check(observed.mode === item.mode, `mode ${observed.mode}`);
+ check(
+ observed.viewport.width === VIEWPORT.width &&
+ observed.viewport.height === VIEWPORT.height,
+ 'viewport mismatch',
+ );
+ check(observed.dpr === 2, `dpr ${observed.dpr}`);
+ check(observed.reducedMotion, 'reduced motion not applied');
+ check(observed.fonts === 'loaded', `fonts ${observed.fonts}`);
+ check(geometryStable, 'geometry changed between samples');
+ check(observed.buttonCount === 1, `${observed.buttonCount} buttons`);
+
+ const button = observed.button;
+ if (button == null) {
+ check(false, 'no button');
+ } else {
+ check(button.tagName === 'BUTTON', `renders ${button.tagName}`);
+ check(button.ariaLabel === spec.label, `aria-label ${button.ariaLabel}`);
+ check(
+ !button.textContent.includes(spec.label),
+ 'label text is rendered visibly',
+ );
+ check(
+ button.dataVariant === spec.variant,
+ `variant ${button.dataVariant}`,
+ );
+ check(button.dataSize === spec.size, `size ${button.dataSize}`);
+ check(
+ near(button.box.width, button.box.height),
+ `not square: ${button.box.width}x${button.box.height}`,
+ );
+ check(
+ button.box.width >= 24 && button.box.height >= 24,
+ `target under 24px: ${button.box.width}x${button.box.height}`,
+ );
+ if (item.theme === 'neutral' && spec.size === 'sm') {
+ check(
+ button.box.width >= 28 && button.box.height >= 28,
+ `sm target under 28px: ${button.box.width}x${button.box.height}`,
+ );
+ }
+ // A theme may pad the button target; the box must stay square with the
+ // icon centered, which the checks around this one prove in every theme.
+ if (item.theme === 'neutral') {
+ check(
+ button.paddingInline === '0px 0px' &&
+ button.paddingBlock === '0px 0px',
+ `padding ${button.paddingInline} / ${button.paddingBlock}`,
+ );
+ }
+ if (spec.state !== 'loading' && observed.glyph) {
+ const glyph = observed.glyph;
+ check(
+ near(
+ glyph.left + glyph.width / 2,
+ button.box.left + button.box.width / 2,
+ centerTolerance,
+ ) &&
+ near(
+ glyph.top + glyph.height / 2,
+ button.box.top + button.box.height / 2,
+ centerTolerance,
+ ),
+ 'icon is not centered',
+ );
+ } else if (spec.state !== 'loading') {
+ check(false, 'no icon');
+ }
+ // An Astryx-sized SVG icon follows the button size: sm in sm and md
+ // buttons, md in lg buttons (16px and 20px at the neutral theme).
+ if (
+ item.theme === 'neutral' &&
+ item.story !== 'emoji-icon' &&
+ spec.state !== 'loading' &&
+ observed.glyph
+ ) {
+ const expected = spec.size === 'lg' ? 20 : 16;
+ check(
+ near(observed.glyph.width, expected) &&
+ near(observed.glyph.height, expected),
+ `icon ${observed.glyph.width}x${observed.glyph.height}, expected ${expected}`,
+ );
+ }
+ if (spec.state === 'loading') {
+ check(button.ariaBusy === 'true', `aria-busy ${button.ariaBusy}`);
+ check(button.ariaDisabled === 'true', 'loading is not aria-disabled');
+ check(!button.disabled, 'loading uses native disabled');
+ }
+ if (spec.state === 'disabled') {
+ check(
+ button.disabled || button.ariaDisabled === 'true',
+ 'disabled button is still available',
+ );
+ }
+ if (item.interaction === 'hover') {
+ check(button.hovered, 'not hovered');
+ }
+ if (item.interaction === 'press') {
+ check(button.pressed, 'not pressed');
+ }
+ if (item.args?.elevation) {
+ check(
+ button.dataElevation === item.args.elevation,
+ `elevation ${button.dataElevation}`,
+ );
+ check(
+ button.boxShadow != null && button.boxShadow !== 'none',
+ `no shadow: ${button.boxShadow}`,
+ );
+ }
+ if (item.interaction === 'focus') {
+ check(button.focused && button.focusVisible, 'not keyboard focused');
+ check(
+ button.outlineStyle !== 'none' && button.outlineWidth !== '0px',
+ `no focus outline: ${button.outlineStyle} ${button.outlineWidth}`,
+ );
+ }
+ if (spec.state === 'tooltip') {
+ check(
+ observed.description === 'View notifications',
+ `description ${observed.description}`,
+ );
+ check(
+ observed.tooltip === 'View notifications',
+ `visible tooltip ${observed.tooltip}`,
+ );
+ }
+ }
+
+ const png = await page.screenshot({animations: 'disabled'});
+ check(png.length > 1000, 'screenshot is empty');
+ const image = `${item.key}.png`;
+ const receipt = {
+ schemaVersion: 1,
+ expected: {
+ build: checkoutSha,
+ storyId: `core-iconbutton--${item.story}`,
+ mode: item.mode,
+ theme: item.theme,
+ viewport: VIEWPORT,
+ interaction: item.interaction,
+ args: item.args ?? null,
+ ...spec,
+ anatomy:
+ 'one native button named by aria-label with no visible label text, carrying the button target with data-variant and data-size, square with a centered icon and, at the neutral theme, zero padding',
+ target:
+ 'at least 24 by 24 CSS px; at least 28 by 28 for sm at the neutral theme',
+ state:
+ 'loading: aria-busy and aria-disabled, not native disabled; disabled: unavailable (native disabled or aria-disabled); focus: keyboard focus-visible with an outline; hover and press: the button matches the state (the press transform is recorded, not asserted); elevation: data-elevation and a shadow; tooltip: described by and showing the tooltip text',
+ },
+ observed: {
+ build: storybookSha,
+ ...observed,
+ geometryStable,
+ pageErrors,
+ },
+ image: {
+ file: image,
+ sha256: createHash('sha256').update(png).digest('hex'),
+ width: png.readUInt32BE(16),
+ height: png.readUInt32BE(20),
+ },
+ failures,
+ passed: failures.length === 0,
+ };
+ fs.writeFileSync(path.join(OUTPUT, image), png);
+ fs.writeFileSync(
+ path.join(OUTPUT, `${item.key}.sensors.json`),
+ `${JSON.stringify(receipt, null, 2)}\n`,
+ );
+ await context.close();
+ expect(failures).toEqual([]);
+ });
+}
+
+test('manifest is complete', async () => {
+ const receiptFiles = fs
+ .readdirSync(OUTPUT)
+ .filter(file => file.endsWith('.sensors.json'));
+ const receipts = receiptFiles.map(
+ (file): AuditReceipt =>
+ JSON.parse(
+ fs.readFileSync(path.join(OUTPUT, file), 'utf8'),
+ ) as AuditReceipt,
+ );
+ fs.writeFileSync(
+ path.join(OUTPUT, 'manifest.json'),
+ `${JSON.stringify(
+ {
+ schemaVersion: 1,
+ component: 'core/IconButton',
+ build: checkoutSha,
+ frames: cases.map(item => ({
+ key: item.key,
+ image: `${item.key}.png`,
+ receipt: `${item.key}.sensors.json`,
+ })),
+ },
+ null,
+ 2,
+ )}\n`,
+ );
+ expect(receiptFiles).toHaveLength(cases.length);
+ // A receipt left by an earlier build does not count.
+ expect(
+ receipts
+ .filter(receipt => receipt.expected.build !== checkoutSha)
+ .map(receipt => receipt.expected),
+ ).toEqual([]);
+ expect(
+ receipts
+ .filter(receipt => !receipt.passed)
+ .map(receipt => ({frame: receipt.expected, failures: receipt.failures})),
+ ).toEqual([]);
+});