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.mdnew file mode 100644index 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`.++@cixzhangdiff --git a/packages/cli/test/core-prop-docs.known-drift.json b/packages/cli/test/core-prop-docs.known-drift.jsonindex 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.mjsindex 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.tsxindex 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.tsnew file mode 100644index 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([]);+});