DESIGN REFERENCE
Keep the reference
honest and useful.
Versions, ownership, exceptions, budgets and recovery rules tied to the retained evidence.
Public evidence18 Sep 2026Observed sources. Explicit local contracts.
A dated, reproducible snapshot
Initial public evidence was captured 18 September 2026, with separately dated source recovery on 19 September. The guide is a local reconstruction. Native and authenticated product behavior remains outside the verified boundary.
| Identity | Record |
|---|---|
| Reference version | 1.1.0 · reconstructed families, complete content contracts and expanded verification |
| Research repository | Base commit c1a28dcf6438e6062255f62fd10448147f1e04f0; branch t3code/raycast-design-research-1. This is not Raycast’s source repository. |
| Website revision | Private source commit unavailable. Retained source URLs, capture times, response hashes and authored CSS identify the inspected build. |
| Packages and fonts | @raycast/icons 0.4.7; native @raycast/api 2.4.1 is ecosystem evidence only. Inter 4.001, Geist Mono 1.400, JetBrains Mono 2.211, Instrument Serif 1.000, VT323 2.000. |
| Execution environment | Node 24.13.1 · Playwright 1.62.1 · Chromium 152.0.7977.42. |
| Freshness rule | Recheck within 30 days or when public drift is observed. Preserve old evidence alongside new captures. A changed date does not renew evidence. |
| Final assessment identity | The local .benchmark-score.json and exhaustive SHA-256 manifests bind the final package and deployment. The visible assessment identifies the retained review status. Changes after a freeze require a new full independent review. |
Sources of truth and change ownership
| Concern | Owner | Change protocol |
|---|---|---|
| Public denominator | Independent inventory researcher | Discover routes, families, states and assets before counting completed specimens. Reconcile additions against occurrence pointers. |
| Tokens and CSS | Reference maintainer | Change the named role, inspect every consuming control and full surface, rerun geometry and modes. |
| Data and interactions | Contract maintainer | Version schema/API changes; update realistic and malformed fixtures before running tests. |
| Assets and rights | Asset maintainer | Retain original bytes and licenses; label derivatives with transform, dimensions and hashes. |
| Accessibility | Accessibility reviewer | Inspect names, keyboard/focus, zoom, contrast, motion, coarse targets and recorded human-test boundaries. |
| Release | Release operator and independent judges | Freeze after tests, evaluate with two fresh isolated judges, publish only site/, verify all reachable deployed bytes. |
Token, mode and alias checks
| Contract | Rule |
|---|---|
| Inheritance | 62 shared tokens at :root; --text → --grey-50, --muted → --grey-200, --surface → --grey-700. Components inherit unless their local contract declares an override. |
| Per-instance values | --swatch is a validated color for swatches; --height is the synthetic bar value; --icon is a local asset mask; --role-size is a declared typography role. They are component inputs, not unresolved global tokens. |
| Modes | Dark is the documented website baseline. Forced colors delegates text/control/focus to system colors. Print removes chrome and restores paper-friendly prose. Reduced motion removes nonessential animation. Reduced transparency uses opaque shared chrome and dialog surfaces. |
| Unsupported modes | Light, tenant, custom density and authenticated platform themes were not observed; do not infer a complete theme API from the dark site. |
| Deprecation | No deprecated local tokens in v1.1. Preserve a renamed token or anchor for one documented minor release, with explicit mapping, before major-version removal. |
| Automated checks | Resolve variable references and aliases; detect cycles; calculate eight allowed text/focus/status pairings; compare 14 rendered type roles at four widths. |
Deliberate local exceptions
| ID / need | Scope and consequence | Owner / review / exit |
|---|---|---|
| RAY-001 Use named native controls and stronger focus/contrast where the captured DOM was weaker. | Local guide controls Some semantics and state colors intentionally differ from the captured product. | Reference maintainer and accessibility reviewer · 2026-10-18 Retire only when a new source capture verifies an equivalent accessible contract. |
| RAY-002 Represent the original moving WebGL backdrop in a static reference. | Homepage decorative background Time-varying animation and performance are not reproduced. | Reference maintainer · 2026-10-18 Reintroduce motion only with a lawful implementation, preference handling and measured budgets. |
| RAY-003 Retain five font families within the 150 KiB runtime budget. | Derived Geist Mono Latin and technical glyph subset The Latin source subset omits broader scripts. The guide adds labeled local Japanese and Devanagari fallback subsets, then system fallback; the full original remains available. | Asset maintainer · 2026-10-18 Choose the original file when broader language coverage is required, then remeasure the budget. |
| RAY-004 Fit reference-specific navigation labels in the captured shell. | Local 880–1199 px navigation Compact local labels use 12 px; original primary navigation uses 14 px. | Reference maintainer · 2026-10-18 Recheck after information architecture changes; preserve 1204×76 desktop shell. |
| RAY-005 Show executable schema, failure recovery and charts without private services. | Synthetic fixtures, local form modes and diagram examples Examples cannot establish real permissions, prices, model results or backend guarantees. | Contract maintainer · 2026-10-18 Replace only with authorized, versioned first-party contracts and original-runtime verification. |
Failure, privacy and operational boundaries
| Area | Acceptance rule |
|---|---|
| Data safety | Strict schemas, safe official URLs, textContent/escaping, bounded rows/blocks/files and explicit permission states. Local forms cannot transmit data. |
| Persistence | No user-data storage, account, analytics SDK, cookies, service worker or background synchronization is installed. Drafts live in document memory. |
| Observability | Tests record request method/origin, errors, timings and counts. Never log email, message, query, copied content, filename or private identifier. |
| Network loss | Loaded static content remains readable; an uncached offline first visit can fail at the browser boundary. Retain drafts, distinguish stale data, provide explicit retry. |
| Budgets | Shared CSS ≤100 KiB, JS ≤50 KiB, five Latin source-font files ≤150 KiB; language fallback subsets load on demand and are reported separately; first-viewport images ≤1500 KiB; cold local LCP ≤2500 ms and CLS ≤0.1 in three runs at two widths; 500-row filter p95 ≤100 ms and worst ≤200 ms. |
| Degraded network and memory | Acceptance uses 150 ms latency, 250,000 B/s download, 125,000 B/s upload and 4× Chromium CPU slowdown at 390 and 1440 px. Cold readiness ≤8 s, LCP ≤6 s, CLS ≤0.1. Sixty filter cycles over 500 rows retain at most 30 visible rows and ≤8 MiB additional collected heap. These are local emulation budgets, not real-user or physical-device claims. |
| Media lifecycle | Native controls own optional sound. Playback pauses when the document becomes hidden or receives pagehide. Time is retained while the document exists; returning never starts sound automatically. The user resumes explicitly. Source videos have text walkthroughs and official-source links. |
| Search recovery | The complete index uses byte-identical gzip. Loading, failed, empty and matching states stay distinct; a failed request exposes Retry search and preserves the query. Already loaded results work offline. |
| Evidence downloads | Large JSON ledgers use lossless gzip. The source browsers decompress them locally; downloads can be opened with gzip -d. Every decoded byte is checked against its source during the build. No record or precision is removed. |
| Compatibility | Chromium, Firefox and Playwright WebKit execute on this Linux host; the linked reports name the actual versions, tested pages and failures. Playwright WebKit is not branded Safari. Physical devices, human assistive-technology sessions and representative-user research remain unexecuted. |
| Rollout | Publish static files as one artifact. No remote experiment assignment. A faulty entry point can be removed or the last verified artifact republished under the same private name. |
| Rollback | Restore site, contracts, fixtures and matching assessment together; rerun links/navigation, record rollback, and invalidate the superseded evaluation. No Raycast account is changed. |
Inspect the actual results
| Suite | Recorded execution | Download |
|---|---|---|
| Data contracts | 119 of 119 completed checks | JSON evidence |
| Browser behavior | 603 of 603; 0 automated accessibility violations | JSON evidence |
| Typography, tokens and budgets | 92 of 92 checks | JSON evidence |
| Catalog and source browsers | 6 of 6 checks | JSON evidence |
| Geometry and provenance | 17 of 17 checks | JSON evidence |
| HTML structure | 83 of 83 checks | JSON evidence |
| Handoff integration | 7 of 7 commands; independent handoff retained separately | JSON evidence |
| chromium page, reflow and behavior verification | 603 of 603 checks | JSON evidence |
| firefox page, reflow and behavior verification | 603 of 603 checks | JSON evidence |
| webkit page, reflow and behavior verification | 603 of 603 checks | JSON evidence |
| Network, memory, search recovery and media lifecycle | 21 of 21 checks | JSON evidence |
| Named recipes and family variants | 38 of 38 checks | JSON evidence |
| Expanded text and bidirectional reflow | 249 of 249 checks | JSON evidence |
| Exact rendered type roles | 364 of 364 checks | JSON evidence |
| Family interactions and object flows | 330 of 330 checks | JSON evidence |
| Family data and relationship contracts | 76 of 76 checks | JSON evidence |
| Family composition anatomy | 18 of 18 checks | JSON evidence |
node designs/raycast/evidence/verification/data-contract-tests.mjs
.agents/skills/design-research/scripts/run-playwright.sh \
designs/raycast/evidence/verification/verify-site.cjs
.agents/skills/design-research/scripts/run-playwright.sh \
designs/raycast/evidence/verification/check-system.cjsThese downloads preserve dated executions and their original input hashes. They are historical snapshots, not proof that every recorded input still matches a later build. The full local package retains subsequent verification and the final independent assessment alongside the reproduction scripts.