DESIGN REFERENCE

Behavior is part
of the design.

Flows, focus, states, transitions, and recovery rules. Runnable behavior is explicitly local; private product operations remain excluded.

Public evidence18 Sep 2026Observed sources. Explicit local contracts.

End-to-end patterns

Critical / /store · /store/category/:slug · /search · /:author/:extension

Discover an extension

Public homepage or Store navigation.

  1. 1

    Browse featured extensions or choose a category.

  2. 2

    Search by title, purpose or platform.

  3. 3

    Open the extension detail and inspect commands, author and screenshots.

  4. 4

    Follow the official Install extension link; native installation is an external boundary.

States and data

Loading, successful list, empty filtered, unavailable detail and failed search. Local search fixtures preserve the query across error and retry.

Extension.id, author.handle, title, description, platforms, commands, categories, updatedAt, canonicalUrl. Never use array index for identity.

Input and verification

Search via visible button or Cmd/Ctrl+K; Tab or Arrow keys through result links; Enter opens detail; Escape returns focus.

Search filters deterministically; empty state offers clear; stable deep link opens correct object; narrow layout becomes one column; no native install is silently executed.

Critical / /pricing · /pro · /teams

Compare plans

Visitor wants a feature or team entitlement.

  1. 1

    Choose annual or monthly billing.

  2. 2

    Select Pro, Plus or Max inside the relevant plan.

  3. 3

    Compare price cadence and feature eligibility.

  4. 4

    Continue through the official account entry; payment and account mutation remain outside this reference.

States and data

Annual/monthly, tier selected, unavailable price and enterprise custom pricing; source FAQ answers shown in expanded/closed states.

Plan.id, audience, tier, billingPeriod, amountMinor, currency, unit, entitlementIds, capturedAt. Local fixtures are versioned and not a current commercial offer.

Input and verification

Native radios support arrows; tier buttons support ArrowLeft/Right and Home/End; focus does not jump when the number changes.

Amount, cadence and entitlements update as one state; every amount names its unit; no subscription is created; archived capture date remains visible.

Critical / / · /windows · /ios

Reach the right download

Visitor selects a platform.

  1. 1

    Read platform/hardware compatibility.

  2. 2

    Choose direct download or inspect the package-manager command.

  3. 3

    Copy the visible command; recover with manual selection if clipboard access is denied.

  4. 4

    Follow first-party installer/app-store link deliberately.

States and data

Desktop/mobile platform, package-manager open/closed/copied/denied, email handoff empty/invalid/pending/local result.

Platform.id, installerUrl, packageCommand, requirements, legacyUrl. URLs restricted to recorded https first-party or official store destinations.

Input and verification

Button or link is reachable; Homebrew/Winget popover opens from Enter; Escape returns focus; command is selectable.

No automatic binary download on reference load; compatibility stays adjacent; mobile has useful navigation; commands remain literal and are never executed.

Important / /feedback

Prepare feedback

Visitor wants to report an issue or request a feature.

  1. 1

    Choose category, supply email/version and explain the issue.

  2. 2

    Optionally choose up to five files, each at most 20MB.

  3. 3

    Review local validation errors without losing the draft.

  4. 4

    Reference validates locally; original submission and email delivery are not exercised.

States and data

Empty, invalid email, missing message, file overflow, too-large file, pending, local success, simulated error/offline.

FeedbackDraft.category, email, version, message, attachment{name,size,type}. Runtime contains synthetic data only; no telemetry or persistent storage.

Input and verification

Visible labels, native select and file picker; first invalid field receives focus; status is announced; duplicate pending submission is ignored.

Wrong email focuses its field; filename is treated as text; error preserves all values; no fetch/email request leaves the page.

Important / /blog · /resources · /changelog · /customers · /community-stories

Read a release or story

Visitor follows an editorial collection or release link.

  1. 1

    Choose the relevant category/platform.

  2. 2

    Open a stable article/version route.

  3. 3

    Read headings, text, figures and supporting links.

  4. 4

    Return to the collection using breadcrumb or browser Back.

States and data

Long title, missing image, long article, version string, source link unavailable and narrow screen.

Article.slug, title, section, author, publishedAt, bodyBlocks, media, canonicalUrl. Dates have ISO machine values and readable display.

Input and verification

Native article links; semantic headings; skip to main; caption/source remains near media; print is readable.

One h1; heading levels do not skip; readable width 746px; no clipped long code or links; image failure retains caption and destination.

Critical / /users/sign_in

Understand the account boundary

A public action requires an account.

  1. 1

    Choose a first-party identity provider or email entry.

  2. 2

    Switch between magic-link and password modes if needed.

  3. 3

    Read the associated terms and privacy links.

  4. 4

    Stop the reference at the submission boundary; use the official site for real authentication.

States and data

Email/password mode, invalid input and native/browser validation; authenticated success, MFA and session errors remain unobserved.

Local draft only. Identity-provider endpoints, session cookies, permissions and real recovery are excluded private contracts.

Input and verification

All provider entries are named controls; mode switches label and input type together; no password is persisted or logged.

No real credential input is requested in fixtures; reference mode change is visible; author clearly identifies what was and was not observed.

Important / /keyboard

Inspect the keyboard

Visitor opens the physical-product announcement.

  1. 1

    Inspect product photos and specification groups.

  2. 2

    Play the sound sample only after explicit input.

  3. 3

    Read availability; sold-out action remains unavailable.

  4. 4

    Follow official page for any future purchase.

States and data

Media idle/playing/paused/failure, sold out, long specification and mobile layout.

ProductModel, specification groups, publicAudioUrl, availability, canonicalUrl. Stock and checkout backends are outside scope.

Input and verification

Native audio controls; specs have labeled terms; disabled purchase explains availability; static alternative for 3D media.

No autoplay sound; dimensions keep units; photograph is not used to infer specs; availability is dated; no cart or purchase mutation.

Nine distinct collection states

Loading

Keep the shell and query; announce once. Skeleton geometry matches the expected content.

local contract

Populated

Stable object IDs, source order, visible count and clear detail action.

local contract

Empty source

Explain the absence of records and show a useful browse/create boundary.

local contract

No matching results

Keep search and category; offer Clear search.

local contract

Partial data

Render valid rows; disclose omitted records. Do not treat it as a complete zero.

local contract

Recoverable error

Preserve the draft/query and expose a named retry.

local contract

Offline

Keep the last readable state; distinguish connectivity from permission.

local contract

Stale snapshot

Show capture/update time; never imply current price, stock or compatibility.

local contract

Permission boundary

Explain the official account entry; do not invent a role or locked private screen.

local contract

Keyboard, pointer and touch

ComponentKeyboard contractFocus ownership
NavigationTab reaches all links; mobile button opens; Escape closes.Trigger retains focus; open menu remains in logical DOM order.
Search dialogCmd/Ctrl+K and visible trigger; arrows navigate results; Enter opens; Escape closes.Native modal traps focus; opener restored on close.
Tabs / tiersArrow keys, Home/End; selection updates; Tab exits the group.Roving tabIndex; exactly one selected item.
DisclosureEnter/Space on native summary; no custom key interception.Focus remains on summary; expanded content enters reading order.
FormsTab follows fields; native select/file picker; invalid submit focuses first invalid field.Error linked by describedby; recovery keeps field values.
Copy / transient messageNative button; clipboard promise determines success.No focus theft; status announced; manual copy fallback.

Responsive and content transformations

ContextTransformationRequired check
Narrow320–390pxSingle-column cards and contracts; nav becomes58px menu; long titles wrap.No page-level horizontal scroll; dialog stays within viewport.
Medium 768pxTwo-column catalogs where readable; mobile navigation.Controls remain reachable; label/helper relationship retained.
Desktop1440px1204px max container; side-by-side source/specimen;64px hero.Compare geometry with recorded source viewport.
Wide1920pxFixed maximum reading widths with flexible outer margins.No stretched screenshots or excessive line length.
Text zoom / expanded copyLayout grows naturally; vertical scroll allowed; essential text not clipped.At200% zoom and 30% longer labels, all actions remain readable.
RTL / mixed scriptLogical DOM order and content direction; code stays LTR.Local fixture only; product localization unverified.
Reduced motion / forced colorsStatic loading treatment; explicit borders and focus.No animation-dependent information or color-only meaning.

Motion ownership and interruption

These are executable local contracts. Source animations retain their own captured evidence and uncertainty; the decorative homepage animation is explicitly frozen.
Owner / triggerStart → endTiming / interruption
.button
Pointer press / release
scale(1) → scale(.98)100 ms · ease-in-out · delay 0 ms
Release or drag away reverses from the current interpolated value. Disabled controls have no transform.
.button, .nav-link, .input-wrap
Hover, keyboard focus or focus-within
Declared resting paint → Declared hover/focus paint200 ms · ease; button shadow uses ease-in-out · delay 0 ms
The next state replaces the target. No queued animation or delayed action.
.panel-link, .extension-card
Pointer enters / leaves
translateY(0) → Panel link: translateY(-3px); extension card: translateY(-2px)200 ms · ease · delay 0 ms
Reverse on pointer leave. Reduced motion keeps the transform at none.
.toggle input::before
Native checked state
translateX(0) → translateX(12px)200 ms · ease · delay 0 ms
A new checked value replaces the target. Checked state, label and accessibility tree update immediately.
.tooltip
Hover or focus; Escape dismisses
opacity 0 / hidden → opacity 1 / visible100 ms · ease · delay 0 ms
Escape hides the tooltip until focus or pointer enters again. It owns no focus.
.button .spinner
Visible pending specimen
rotate(0) → rotate(1turn)800 ms per loop · linear · delay 0 ms
A disabled pending control prevents repeat activation. Reduced motion replaces rotation with a static complete ring and visible status text.
.skeleton
Collection loading state
background-position 0% 0% → background-position -200% 01800 ms per loop · ease-in-out · delay 0 ms
State replacement removes the loading DOM. Reduced motion uses a static fill; the Loading status remains readable.
Native dialog; assets/reference.js
Named trigger, Escape, close button or backdrop
Closed → Open modal, then closed0 ms; no entrance choreography · None · delay 0 ms
Repeated open is ignored. Escape closes once and returns focus to the actual connected opener. Dismissal does not clear the search query.
[data-local-form]
Valid submit
Editable draft → Checking, then success / error / offline450 ms local simulation · None; semantic state change · delay 0 ms
A pending guard ignores repeat submissions. All controls restore their previous disabled state; failed drafts remain intact.
Native links and collection focus handlers
Follow a reference link or change page
Current document or collection page → Target document or next page of itemsNative navigation; no fabricated transition duration · None · delay No artificial delay
The browser owns load cancellation and history. A collection page change focuses its first result; filtering resets its page index.
assets/media-lifecycle.mjs
Document hidden or pagehide
Optional user-started audio/video → PausedSynchronous event handler · None · delay 0 ms
Preserve current time while the document exists. Visibility restoration does not restart playback. Native controls own explicit resume and seeking.
.hero-backdrop; RAY-002 exception
Page load
Frozen captured frame → Same frameStatic local reconstruction · None · delay None
Original WebGL animation is not reproduced. The WebP derivative is pixel-identical to the retained PNG; no motion-dependent information is removed.

Download the motion and interruption contracts

Reference hover and focus transitions belong to individual controls; opening and closing a dialog belongs to the overlay. Requests are local simulations with a450ms pending state. Repeated submit is ignored while pending. A new search supersedes the previous filter immediately, with no out-of-order network response. A failed clipboard request never produces a false success toast.

State and event contracts

About this specimen

This is a local reconstruction of a public Raycast pattern. It demonstrates the interface contract; real accounts, installs and payments remain on the official product.

Icon contract