docs: add responsive and interaction readiness rubric

[rubyycheung]

Latest refinement

Popover review exposed two reusable gaps, now added without expanding the rubric:

• anchored/layered surfaces must test explicit, trigger-derived, intrinsic, and consumer-overridden sizing on both axes, including both outcomes: oversized content scrolls and fitting content remains unclipped;
• responsive stories must use the real Storybook viewport/container and preserve normal trigger, outside-dismiss, keyboard-dismiss, and focus behavior. Stories may auto-open through interaction code rather than being permanently controlled open; simulator/device evidence remains separate.

Summary

• narrow the rubric scope around Pass/Fail/Blocked/N/A status semantics, applicable scenario evidence, conditional adaptive/transient appendices, and interaction-affecting motion while moving generic hardening guidance out of scope.
• address reviewer feedback in docs: add responsive and interaction readiness rubric #5351 by adding a platform/browser evidence layer: Storybook and Playwright cannot prove iOS Safari/shell behavior, iOS touch/WebKit claims need Simulator/device evidence, unavailable platform evidence is Blocked rather than N/A, and diagnostics remain development-only.
• add a reusable astryx docs responsive-interaction-readiness rubric for reviewing new or changed components across viewport space, pointer precision, hover availability, gestures, transient and queued UI, mobile viewport constraints, and existing interaction contracts
• add an Adaptive presentation decision gate so authors decide from task semantics/product intent before using width or input capability as implementation signals
• add conditional Transient and queued UI checks covering queue/stack policy, timing, announcement semantics, gesture alternatives, and viewport obstruction evidence for toasts, snackbars, notifications, transient banners, and similar surfaces
• add generalized viewport obstruction and placement guidance for fixed overlays, transient feedback, floating actions, and other viewport-anchored surfaces
• wire Responsive and Interaction Readiness into lab readiness as a new evidenced human-review check so component reviews can record Pass/Fail/N/A plus linked evidence instead of relying on an isolated checklist
• add a copyable component-PR reporting template with compact Check | Result | Evidence subsections that preserve the four viewport/input independence scenarios
• link the rubric from principles and layout guidance so authors can discover it while authoring responsive or input-sensitive behavior

Why

Responsive component work was mixing viewport width with touch capability. This rubric keeps those axes separate, preserves the four reference scenarios that prove width independence and input independence, and organizes review outcomes into four scannable categories: responsive layout; touch, pointer, and hover; accessibility and interaction contracts; and mobile viewport constraints.

The adaptive presentation gate captures the Dialog vs BottomSheet lesson generally: responsive pressure usually means reflow/resize, while presentation changes must be explicit, opt-in, documented, and backed by evidence for changed placement, motion, dismissal, focus, scrolling, gesture, or announcement contracts.

The transient UI guidance captures the Toast lessons generally: queued or auto-dismissing surfaces need explicit stack/queue/timing/announcement/gesture evidence, and unrelated components can mark those checks N/A.

The viewport obstruction guidance keeps placement decisions tied to actual obstructions and content priority, not touch/coarse-pointer inference; safe-area support alone is not treated as keyboard or app-chrome avoidance.

WCAG AA boundary

The rubric is scoped to WCAG 2.2 Level AA. For target size, it uses Success Criterion 2.5.8: at least 24x24 CSS px or a permitted exception.

Validation

• pnpm exec prettier --write .changeset/responsive-interaction-readiness.md internal/lab-readiness/catalog.mjs internal/lab-readiness/audit.test.mjs packages/cli/assets/docs/responsive-interaction-readiness.doc.mjs packages/cli/foundation/discovery/docs-discovery.test.mjs
• pnpm exec prettier --check .changeset/responsive-interaction-readiness.md internal/lab-readiness/catalog.mjs internal/lab-readiness/audit.test.mjs packages/cli/assets/docs/responsive-interaction-readiness.doc.mjs packages/cli/foundation/discovery/docs-discovery.test.mjs
• pnpm exec vitest run internal/lab-readiness/audit.test.mjs packages/cli/foundation/discovery/docs-discovery.test.mjs packages/cli/api/docs/integrationDocs.test.mjs
• pnpm -F @astryxdesign/cli astryx docs responsive-interaction-readiness --dense
• pnpm check:changesets
• pnpm check:repo
• pnpm lab:readiness:check

Relationship to #5343

This is intentionally separate from the AlertDialog implementation PR #5343. AlertDialog is only used as a concise worked example of the rubric; this branch is based on current main and is not stacked on #5343.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview	Aug 24, 2026 2:52am

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

No new or modified components detected.

Bundle Size Summary

No component packages changed.

Accessibility Audit

Status: No accessibility violations detected.

---

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}

[light-merlin-dark]

A field note from adopting this rubric's spirit downstream, offered because it cost us a real debugging session this week:

The mobile-readiness rubric marks "Touch, pointer, and hover: Pass" on evidence from Storybook and Playwright. Both are structurally blind to WebKit-on-iOS: Playwright's WebKit is macOS WebKit with no iOS shell and no top-layer <dialog> behaviour to match. A component can pass every current check and still behave differently on a real iPhone.

Recommend adding an iOS Simulator verification step to the rubric for touch-interaction claims. A cheap technique that works without a console: render an on-page, pointer-events: none forensics overlay behind a query flag, so one screenshot reads the whole event/dispatch story. One React-specific trap worth documenting for anyone instrumenting this: React freezes props in development, so any handler probe must survive commits (intercept the props property and return a wrapped copy) — mutating the props object silently no-ops and makes a working dispatch look broken.

For what it's worth, we ran exactly this suspicion against @astryxdesign/core@0.4.0's Dialog on an iOS 26.5 simulator with real touch injection: dispatch is clean, top-layer propagation is clean. The rubric gap is about what the current instruments can't see, not about a defect they missed.

By Merlin (rbeckner.com) and his AI agent (Claude Code, Opus 5 (1M context), thinking on: high).

[rubyycheung]

@light-merlin-dark Thanks so much for your feedback! Will definitely include, let me know if you have any other thoughts on the rubric. 🙂