Patterns · composition guide

App shell pattern

How an AhaSlides product SCREEN is assembled from DS components — the left nav rail (real brand mark + nav items + one primary CTA), the top bar (context left, actions/avatar right), the content region, and where relevant a canvas/stage — spaced by --aha-* tokens, with a real brand identity and no dead placeholders. Closes the composition gap that turns a component-correct screen into generic-admin-template slop.

◆ generated from guidelines/app-shell.json — do not edit by hand

The DS ships no shell/nav/rail leaf, so a consumer hand-rolls the screen scaffold — and hand-rolled scaffold is where slop enters: a placeholder letter-tile logo, a 'Loading…' block shipped as final, evenly-spaced equal-weight cards. This pattern ships NO new component; it documents how to compose the shell from existing DS components and binds each rule to a binary criterion the consumer self-judges.

Based on

The rationale, worked examples, and the full assertion set live in the design skill — this pattern distils the enforceable subset and links each rule back to it.

build ahaslides-design:app-shell judge ahaslides-design:app-shell

Composed of

What a compliant app shell surface reuses from this design system — the pattern's link into the component graph.

Reuses	Kind	For	In DS?
`button`	component	the primary CTA in the nav rail (e.g. New presentation), top-bar actions, and per-row actions — one primary per region, sized via the size prop, never inline height/padding/radius	available
`icon`	component	the brand mark glyph, every nav-item glyph, and top-bar action glyphs — an <aha-icon name> from the library, never an inline <svg> or a foreign icon set	available
`avatar`	component	the top-bar account avatar and any per-row user avatar	available
`badge`	component	the 'New' marker on a nav item or menu row	available
`divider`	component	top-bar and rail section separators	available
`--aha-motion-mid`	token	the active/selected nav-item transition duration — toggled on a persistent node, never a bare literal	available
`--aha-borderRadius`	token	the radius on rail/top-bar/content surfaces — from the 4/6/8/12/16 scale	available

Rules

The shippable checklist — each rule traces to an assertion in ahaslides-design:app-shell.

Rule	Skill assertion
Use the real AhaSlides brand mark + wordmark at the top of the nav rail — the shipped logo / an <aha-icon> brand glyph — never a coloured letter-tile or initials square standing in for a logo.	C1
Never ship a placeholder as a final state: a QR/thumbnail/region renders a real asset or an explicit, styled empty state — never a permanent 'Loading QR…' label, spinner, or grey box.	C2
Give each region one primary action and a scannable type hierarchy from the scale; do not render uniform grey-on-white equal-weight cards with evenly-spaced everything (the admin-template tell).	C3
Fill every shell slot with a DS component (aha-button, aha-icon, aha-avatar, aha-badge, DataTable) and take all spacing/radius/colour from --aha-* tokens — never a hand-rolled <button>/<div> with inline hex/px, never a raw <table>.	C4
Animate the active/selected nav state by toggling an attribute/class on a persistent node via the motion tokens (--aha-motion-* + --aha-ease-*); never snap, never a bare duration literal, never rebuild the subtree on selection.	C5

Composition code

Doc-only — this pattern ships no wrapper from this repo. Doc-only pattern — the DS ships no shell wrapper leaf. The composition lives in the consuming app; this pattern is the conventions + the binary criteria (anti-slop/criteria.json → surfaces.app-shell) a consumer self-judges against.