DESIGN.md · git:20260819.88f979a · 2026-08-19 · sha256 46061a3914be412d
DESIGN.md git:20260819.88f979aA
Immutable. This exact content never changes and is served at /api/v1/blob/46061a3914be412d.
# Motion Lexicon V6 Product Design ## Experience model Motion Lexicon V6 is a Components-first React library. The website lets a builder judge a complete static frame, interact with a real product state, inspect the source, and install the same implementation through the Registry. ```text Components: Browse → Judge → Interact → Inspect → Install Page Blocks: Browse → Preview by viewport → Inspect → Install Primitives: Browse → Tune → Inspect → Install Skill: Understand product job → Select Components → Compose → Review ``` The shell stays quiet and legible. The components carry visual character through Product Mono, Editorial Warm, and Spatial Dark scenes. ## Information architecture Primary routes: - `/:locale/` — component-led showcase and discovery. - `/:locale/components/` — all 100 Components across 11 categories. - `/:locale/components/:componentId/` — live preview, source, install command, related Primitives, and visual contract. - `/:locale/blocks/` — ten complete Page Blocks. - `/:locale/blocks/:blockId/` — responsive Block preview, source, and install command. - `/:locale/primitives/` — 44 canonical motion Primitives. - `/:locale/primitives/:primitiveId/` — live preview, props, source, install, and related Components. Resource routes include `/:locale/guides/`, `/:locale/skill/`, `/:locale/method/`, and `/:locale/vocabulary/`. The domain root opens the Chinese landing page. ## Navigation and discovery - Components occupy the first navigation position and the primary directory entry. - Page Blocks have their own directory and show complete product compositions. - Category filtering exposes Agent UI, Actions, Overlays & Surfaces, Forms & Input, Navigation, Data & Commerce, Feedback, Cards & Media, Visual & Ambient, Hero & Story, and Text & Type. - Primitives remain accessible as stable motion vocabulary: 44 canonical entries preserve 91 source terms through mappings and redirects. - Global search opens with `Cmd/Ctrl + K`; language, theme, and GitHub remain compact top-level actions. - Desktop and mobile navigation preserve the same hierarchy. ## Directory and workbench Each Component card renders a lazy real demo with an intentional primary frame. The directory supports scanning by category, scene family, runtime cost, and search. Narrow layouts place the active work ahead of the full directory. A Component workbench provides identity, a concise product job, the live preview, source from the rendered implementation, install command, dependencies, and relevant motion foundations. Page Block workbenches add desktop, tablet, mobile, and fullscreen previews. ## Scene families | Family | Visual direction | Typical use | | --- | --- | --- | | Product Mono | quiet neutrals, crisp boundaries, compact mono metadata, exact state color | forms, tools, data, navigation, feedback | | Editorial Warm | paper and material warmth, expressive type, image-led pacing | media, cards, stories, cultural products | | Spatial Dark | dark depth, controlled light, dimensional context | technical worlds, visual systems, spatial product stories | The primary static frame must remain informative without autoplay. Dynamic behavior starts from intent or a meaningful state transition. ## Material, type, and interaction - The website shell uses chroma-zero light and dark neutrals, thin boundaries, compact radii, black primary actions, restrained blue focus/selection, and semantic status colors. - Components may expand into their scene family while keeping core content, controls, focus visibility, and contrast legible. - Platform system typography and compact mono metadata keep dense implementation details scannable; Editorial Warm scenes may use larger display rhythm. - Motion relies on transform and opacity where possible, preserves final geometry, supports interruption, and respects fine-pointer media queries. - Reduced motion preserves state, focus, content, and the resulting action. ## Registry contract Component and Block source files are the source of truth for: 1. direct-import live demos; 2. directory and workbench previews; 3. source views; 4. `/r/:id.json`; 5. the public machine-readable catalog and root `registry.json`. ```text components/:id.tsx → demos/:id-demo.tsx → directory and Component workbench → source view → /r/:id.json blocks/:id.tsx → block-demos/:id-demo.tsx → Block directory and responsive workbench → source view → /r/:id.json ``` Registry items declare runtime dependencies. The release workflow generates the official shadcn schema and verifies fresh representative installs. ## Accessibility, responsiveness, and performance - Native semantics, labels, focus restoration, keyboard paths, live regions, touch targets, and visible focus remain part of the implementation. - Primary interactive targets use a 44px baseline. - Components and Blocks hold at 320, 390, 768, and 1440px without page-level horizontal overflow. - Heavy canvas, WebGL, and Three.js scenes initialize only when useful, pause when offscreen, respond to resize, dispose resources on unmount, and render a meaningful static/reduced-motion frame. - Each scene supports light and dark context where its product job needs it. ## Static delivery and release `npm run build` prerenders localized canonical routes and produces the sitemap, robots file, structured metadata, public catalog, social assets, and shadcn Registry output. V6 release acceptance verifies those generated assets after the 100-Component and 10-Block catalog passes source, visual, accessibility, installation, and browser review.