feat: build the semantic component catalog, theme contract, and Theme Lab

Outcome

Deliver a finite AOS semantic component catalog, theme-pack contract, and interactive Theme Lab covering every supported primitive and state.

Scope and ownership

Unicity AOS owns presentation. This issue owns stable component ids, semantic props, theme token names, and catalog/theme validation. #91 stores references only. #92 resolves them into interaction. #94 persists theme id plus semantic tokens on the recipe. Astrid remains UI, language, theme, and shell-blind.

Covered families: layout, content, input, data, navigation, feedback, permission, media, canvas, terminal, and native-portal primitives; semantic tokens; typography; spacing; material; elevation; motion; density; breakpoints; named icons; sound and haptics descriptors; accessibility and interaction states.

Accepted contract

Catalog identity is aos.catalog/1. Theme identity is aos.theme/1. Neither document is an A2UI catalog, CSS stylesheet, screenshot, or permission grant.

v1 primitive ids (62)

Layout (12): Region, Stack, Grid, Split, Sidebar, ActionBar, Card, Group, Collapse, Repeater, ScrollRegion, Divider.

Content (8): Heading, Text, InlineContent, CodeBlock, Badge, KeyFigure, EmptyState, Icon.

Input (10): Button, TextField, TextArea, NumberField, Select, MultiSelect, Switch, Checkbox, Slider, DateTimeField.

Data (6): Table, RecordSummary, DatasetChart, Timeline, Difference, Progress.

Navigation (5): Tabs, Breadcrumb, Menu, Pager, Link.

Feedback (7): Alert, Toast, InlineMessage, Skeleton, Spinner, StatusDot, Dialog.

Permission (4): CapabilityCard, ConsentForm, SecurePrompt, FilePicker.

Media (5): ImageView, AudioPlayer, VideoPlayer, FileDetails, MediaEmbed.

Canvas (3): CanvasStage, DiagramView, AnnotationLayer.

Terminal (1): TerminalView.

Native portal (1): NativePortal.

Each primitive has one record: semantic role, allowed children or slots, required accessibility label strategy, state set, density behavior, phone and desktop adaptation, native mapping, focus and keyboard contract, motion contract, and fallback rendering. Semantic props use roles, ratios, and units, not pixel snapshots.

Explicit v1 exclusions

These are not v1 catalog primitives:

• IconButton folds into Button with an icon slot.
• CommandLauncher belongs to the #92 detached shell, not generated activity trees.
• SystemActivityTile is shell chrome over activity identity, not a widget.
• EmbeddedWebView is a NativePortal with a web portal contract, never agent-authored HTML or CSS.
• MapView and Scene3DView are namespaced extensions or native portals until a real AOS renderer exists.

Unknown namespaced components preserve the declared identifier and legally accepted action references, then render a neutral unsupported-component fallback. Unknown children must not execute.

Non-authority

Permission, media, terminal, and native-portal primitives visualize or request. They do not mint capabilities, open files, spawn processes, or store secrets. FilePicker and SecurePrompt declare intent; policy and consent grant. TerminalView presents a bound session; it is not capsule-shell command execution. NativePortal frames a native or web portal node from #91; live native control remains #97. MediaEmbed is a typed principal-scoped media reference, not an iframe.

Theme pack

aos.theme/1 is renderer-owned. Required environment: light, dark, high-contrast light, high-contrast dark; densities compact, cozy, spacious; pointer and keyboard; text scaling; reduced motion; safe-area handling.

Token layers:

1. Renderer or base values: private implementation, not author API.
2. Environment tokens: platform material, input modality, system palette, display scale, safe areas.
3. Semantic tokens: background, surface, text, border, focus, accent, success, warning, danger, information, neutral, disabled, selected, overlay, elevation, spacing, radius, typography, icon, motion, sound, and haptic roles.
4. Component tokens: stable per-primitive slots derived from semantic tokens.
5. User or workspace preferences: mode, contrast, density, accent choice, motion reduction, sound and haptic preference.

Recipes store theme id plus semantic token references only, per #91. Custom themes may alias semantic tokens and choose from bounded scales. They must not inject selectors, scripts, raw fonts, infinite values, component internals, fake permissions, or executable media. Missing tokens fall back through exact theme version, compatible latest minor, built-in contrast, then fail-closed neutral styling.

A2UI import maps Row/Column to Stack, List to Repeater or Stack, ChoicePicker to Select or MultiSelect, Modal to Dialog, Image to ImageView, and Text usage hints to Heading or Text. That mapping is declared-loss and lives in #91.

Theme Lab

The Lab is a verification surface, not a second UI authority. It instantiates every v1 primitive across documented states, densities, breakpoints, color modes, keyboard and focus conditions, reduced-motion, and high-contrast. It loads two complete themes and proves workspace recipes are unchanged while presentation changes.

Dependencies

• Consumes the #91 Mapped document split: theme attachment is on the recipe, not on an ephemeral surface tree.
• Supplies frozen component ids and theme token names to #91, #92, and #94.
• NativePortal presentation only; live native integration remains #97.
• A2UI remains an interoperability input through the #91 adapter, not a catalog authority.
• Does not depend on #90, #95, or #96 for the catalog or theme contract.

Exit gate

Every v1 primitive renders in all documented states, densities, breakpoints, color modes, keyboard and focus modes, and reduced-motion or high-contrast variants. A second complete theme changes presentation without changing workspace recipes. Unknown components use an explicit safe fallback. Visual permission, terminal, and portal affordances never grant capability.

Claim boundary

The catalog is finite and extensible through versioned ids and namespaced extensions. It does not encode every application-specific widget, grant authority through visual affordances, replace the Surface Model, persist recipes, or prove native-app compatibility.

Verification

Interactive Theme Lab, visual regression suite, accessibility audit, theme conformance validator, responsive phone and desktop corpus, hostile token and value tests, unknown-component fixtures, A2UI declared-loss mapping fixtures, and a recipe or theme independence check.

Candidate paths

AOS CE capsule layout: capsules/capsule-surface-catalog/ for catalog records, theme packs, and validators. Theme Lab runs as a verification mode of apps/adaptive-shell/. Do not reuse capsule-shell or capsule-react. Do not place this under crates/ or collide with the Rhai or Surface Model writers.