[P1][Landing vNext] Publish framework-neutral interaction contracts and accessibility test vectors

[BunsDev]

Outcome

Export the behavioral, semantic, and accessibility contracts from OpenCoven/ui in a framework-neutral form that static Astro surfaces such as coven-landing can implement without importing the React/Tailwind runtime.

Why

The landing currently reimplements buttons, menus, tabs, progress, status, copy controls, simulated windows, theme controls, and focus behavior privately. The UI repository already defines valuable laws—semantic color, one filled action per surface, shared radii/density, non-color state cues, and complete reduced-motion feedback—but downstream non-React surfaces need a consumable contract.

Scope

Define portable interaction specifications for at least:

• Button/action hierarchy;
• Disclosure and dropdown menu;
• Tabs;
• Tooltip/help text;
• Status badge/indicator;
• Progress where real progress exists;
• Code/command copy control;
• Download/artifact chooser;
• Theme control;
• Dialog only where a true modal surface is justified;
• Navigation menu and mobile navigation.

For each primitive document:

• semantic HTML baseline;
• roles/ARIA only where native semantics are insufficient;
• state model and canonical state names;
• keyboard map;
• focus-entry, containment, return, and visible-focus behavior;
• pointer/touch behavior and target-size guidance;
• disabled/busy/error/success behavior;
• reduced-motion behavior that preserves all information;
• high-contrast/forced-colors considerations;
• associated semantic tokens and dimensions;
• progressive-enhancement/no-JavaScript fallback;
• examples of misuse.

Shared test vectors

Provide framework-neutral fixtures or test cases covering:

• open/close and aria-expanded synchronization;
• aria-controls linkage;
• Escape and outside activation;
• arrow-key/tab behavior by primitive type;
• focus restoration;
• focused-nav visibility;
• no accidental focus trap for non-modal UI;
• target size;
• non-color state communication;
• reduced-motion completeness;
• keyboard-only completion;
• screen-reader names/descriptions;
• error/live-region behavior without excessive announcements.

The artifacts may be JSON, Markdown tables, HTML fixtures, Playwright helper packages, or another deterministic format, but must not require the specimen app to be running.

Landing-specific reference states

Include reference behavior for:

• global mobile navigation;
• Start locally selector;
• platform/artifact download chooser;
• maturity/status badge;
• three-state guided proof controls;
• command copy confirmation;
• theme toggle;
• any full-demo dialog/media viewer retained after the redesign.

Non-goals

• Rebuilding Astro components inside the UI repository.
• Forcing coven-landing to adopt React.
• Making every decorative panel interactive.
• Defining brand visual identity that belongs to OpenCoven/brand.

Acceptance criteria

• Portable contracts exist for every primitive required by landing vNext.
• State names, semantics, keyboard behavior, focus behavior, and reduced-motion behavior are explicit.
• Shared test vectors can run against both the UI specimens and Astro implementations.
• Every colored state has a text/icon/shape/weight counterpart.
• One-filled-action guidance is represented in examples and tests where practical.
• The contract can be versioned and consumed from an immutable revision/release.
• A landing consumer can pass the vectors without importing the React component implementation.

Verification

• Run vectors against current @opencoven/ui components.
• Add a consumer canary in OpenCoven/coven-landing.
• Axe/keyboard tests for supplied fixtures.
• Mutation tests for missing state synchronization, focus return, and reduced-motion feedback.

Dependency/handoff

The coven-landing vNext shell and control work should consume this issue together with OpenCoven/brand#2.