Document the Popover semantic contract

[cixzhang]

Why

Popover has one painted surface, but the original draft described popover and popover-surface as equal anatomy owners. Cindy’s final decision makes popover the canonical broad baseline while preserving existing themes through a documented compatibility window.

What

• Accept the Popover contract as current, approved by cixzhang on 2026-08-31.
• Map the real Popover surface to canonical popover; remove the invented shared-hook anatomy part.
• Define optional component-owned surfaceTarget values as refinements on the same surface, and mark popover-surface as a deprecated compatibility alias.
• Keep runtime migration and named-AT evidence as explicit follow-up rather than blockers to the accepted semantic contract.
• Add an inventory regression proving the alias remains enumerable but is excluded from active ownership. The existing validator already understands deprecatedFor, so no schema or validator change is needed.

Risk

Documentation and inventory-test only. Runtime behavior and emitted classes are unchanged; existing popover-surface themes keep working. Automatic hook-wide popover emission and any later alias removal require separate implementation, release notes, and review. The PR remains draft for final parent review/merge. No Changeset.

Testing

• 8 focused Popover, theming-target, knowledge, and docs suites (164 tests)
• pnpm check:knowledge
• pnpm check:repo
• Prettier on all changed files

[vercel]

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

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 1, 2026 1:54pm UTC

[github-actions]

PR Analysis Report

Preview availability: Storybook and Sandbox were not published for this CI run.

Modified Components

Popover _{(@astryxdesign/core)}

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	809	-
Complexity	N/A	Very High (90)	-

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.8KB	1.2KB

Accessibility Audit

Status: No accessibility violations detected.

---

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

[cixzhang]

/approve-spec 9b8ec1b

[cixzhang]

/approve-spec 9b8ec1b