Design Knowledge Base
Community-maintained principles reviewed before publication and retrieved as Agent design constraints.
Overlay Focus and Scroll Lock Contract
An overlay is not just a scrim; it is a contract across modality, initial focus, focus containment, dismissal, inert background, scroll locking, portal stacking, and mobile safe areas.
Whenever an overlay changes the interactive scope, keyboard, screen reader, pointer, scroll, and mobile behavior must be governed together; a visually covered but semantically reachable background is the most dangerous fake modal.96%Interaction Responsive Motionscroll / horizontalHorizontal Scroll Portfolio Boundary
Horizontal scrolling works for bounded portfolios, galleries, and project sequences, but not for long prose, documentation, or core task flows.
Horizontal scroll must be an explicit content format: users can see the next item, operate it with keyboard and touch, reflow on narrow screens, and read core text without hunting on the horizontal axis.95%Interaction Responsive Motionmotion / scrollScroll Story Chapter Contract
The basic unit of scrollytelling is not an animation frame but a readable chapter: each chapter needs a question, text anchor, visual state, static fallback, and verifiable scroll behavior.
Scroll storytelling should break complex mechanisms into evidence chapters users can pause on, skip, and return to; motion connects chapters and states but should not become the only content layer.95%Interaction Responsive Motionmotion / reduced-motionMotion Accessibility and Performance Triage
Before shipping motion, classify purpose, trigger, disable path, performance properties, and verification evidence instead of accepting it because it looks smooth.
Good motion explains change; bad motion adds burden. Triage turns every animation into an explainable, reducible, testable, cleanup-safe interface behavior.95%Interaction Responsive Motionbulk-actions / tablesBatch Action Preview and Diff
Batch actions need selection scope, action object, affected count, failure branches, and undo/audit paths; dangerous bulk changes must show a diff before submission.
Batch actions increase efficiency and amplify mistakes. The interface must make current selection, action scope, invalid items, dangerous consequences, async progress, and recovery path explicit.95%Interaction Responsive Motionforms / validationForm Error State Contract
A form error state contract puts labels, helper text, validation timing, inline errors, error summaries, submit states, server failures, mobile keyboards, and ARIA wiring into one implementable model.
Form errors are not one red component; they combine field contracts, state machines, and recovery paths, and should route to narrower guidance for summaries, accessible feedback, persistent labels, and transactional recovery.95%Interaction Responsive Motion3d / storytellingImmersive 3D Storytelling Gates
WebGL, Three.js, and 3D motion should be split into understandable story gates: each stage answers one question and provides static, reduced-motion, and skippable paths.
Immersive 3D is valuable when it turns abstract concepts into a pausable, understandable, continuable chain of evidence instead of trapping users inside a scene.94%Interaction Responsive Motionforms / errorsTransactional Form Error Recovery
Error handling in high-trust forms is not about telling users they are wrong. It returns them to a recoverable state where they can continue without re-entering information.
Transactional service error recovery must handle visual placement, screen readers, focus, original input, error copy, and next action together.94%Interaction Responsive Motionmotion / scrollAward Site Scroll Story Motion
Scroll motion should help users understand product state and narrative progress, not hide information inside uncontrolled spectacle.
Scroll motion in narrative pages must serve causality, hierarchy, and pacing: each motion segment should explain a state change or value proof.92%Interaction Responsive Motionportfolio / motionQuiet Motion in Portfolios
Portfolio motion should clarify selection, entry, comparison, and memory instead of making every element perform.
The interaction value of a portfolio is helping users judge craft: project selection, visual detail, case navigation, and contextual transitions matter more than decorative animation.90%Interaction Responsive Motionempty-state / recoveryEmpty State Recovery Contract
Empty states should explain system status and cause before offering an action that resolves that cause, instead of filling silence with illustration.
An empty state is completed system feedback: users need to know why content is absent, whether the request has finished, what they can do, and whether access, configuration, retry, or waiting is required.90%Interaction Responsive Motionmodal / focusModal Focus Management
Modal Focus Management turns a frequent interface judgment into an executable constraint before generation.
Dialogs change interaction context and must manage focus, background reachability, and close paths.87%Interaction Responsive Motiongesture / mobileTouch Gesture Alternatives
Touch Gesture Alternatives turns a frequent interface judgment into an executable constraint before generation.
Swipe, pinch, and long press cannot be the only way to complete a task.86%Interaction Responsive Motionloading / skeletonSkeleton Loading Hierarchy
Skeleton Loading Hierarchy turns a frequent interface judgment into an executable constraint before generation.
Skeletons should preview real content structure instead of adding extra visual noise.86%Interaction Responsive Motiontables / bulk-actionsTable Bulk Action Model
Table Bulk Action Model turns a frequent interface judgment into an executable constraint before generation.
Bulk actions need to express selected count, scope, risk, and completion feedback clearly.86%Interaction Responsive Motiondrag-drop / accessibilityDrag and Drop Alternatives
Drag and Drop Alternatives turns a frequent interface judgment into an executable constraint before generation.
Drag and drop is useful direct manipulation, but sorting, moving, and upload need non-drag alternatives.86%Interaction Responsive Motiondanger / confirmationDestructive Action Confirmation
Destructive Action Confirmation turns a frequent interface judgment into an executable constraint before generation.
Confirmation should protect irreversible or high-impact actions and explain object plus consequence.86%Interaction Responsive Motionkeyboard / navigationKeyboard First Navigation
Keyboard First Navigation turns a frequent interface judgment into an executable constraint before generation.
An interface that works from the keyboard is usually clearer because focus order reveals the real task structure.86%Interaction Responsive Motionmobile / actionsMobile Bottom Action Bar
Mobile Bottom Action Bar turns a frequent interface judgment into an executable constraint before generation.
Critical mobile actions should be thumb-reachable without covering content, errors, or system navigation.85%Interaction Responsive Motionfeedback / toastToast vs Inline Feedback
Toast vs Inline Feedback turns a frequent interface judgment into an executable constraint before generation.
Feedback placement should match the object; toast fits short global status, while inline feedback fits fields and local fixes.85%Interaction Responsive Motionwizard / progressWizard Stepper Progress
Wizard Stepper Progress turns a frequent interface judgment into an executable constraint before generation.
Wizards need to show current position, remaining work, reversibility, and save state.85%Interaction Responsive Motionfilters / stateFilter Query State Preservation
Filter Query State Preservation turns a frequent interface judgment into an executable constraint before generation.
Filter results are user-built work context and should persist across refresh, back navigation, and sharing.85%Interaction Responsive Motionresponsive / navigationResponsive Navigation Collapse
Responsive Navigation Collapse turns a frequent interface judgment into an executable constraint before generation.
Collapsing navigation is not hiding every entry; it reorders by task frequency and current location.85%Interaction Responsive Motionundo / editingUndo Redo Reversibility
Undo Redo Reversibility turns a frequent interface judgment into an executable constraint before generation.
Reversible actions let users explore with fewer confirmation interruptions.85%Interaction Responsive Motionlatency / microinteractionReduced Latency Microinteraction
Reduced Latency Microinteraction turns a frequent interface judgment into an executable constraint before generation.
Microinteractions should confirm input and state change, not make the interface feel busy.84%Interaction Responsive Motionpagination / scrollInfinite Scroll vs Pagination
Infinite Scroll vs Pagination turns a frequent interface judgment into an executable constraint before generation.
Browse lists can scroll continuously; task lists usually need position, selection, return, and count awareness.84%Interaction Responsive Motionrealtime / collaborationRealtime Collaboration Presence
Realtime Collaboration Presence turns a frequent interface judgment into an executable constraint before generation.
Collaborative interfaces need to show who is present, who is editing, and how conflicts resolve.84%Interaction Responsive Motionfeedback / latencyOptimistic Update Feedback
Optimistic Update Feedback turns a frequent interface judgment into an executable constraint before generation.
Optimistic updates make interfaces feel fast while failure and rollback remain understandable.84%Interaction Responsive Motioncommand / shortcutsCommand Palette Safety
Command Palette Safety turns a frequent interface judgment into an executable constraint before generation.
Command palettes are useful for speed, but scope, risk, and outcome must be explicit.84%Interaction Responsive Motioninputs / controlsInput Mode and Control Matching
Controls should match decision shape: toggles for binary, segmented controls for modes, menus for option sets, sliders for continuous values.
The wrong control adds cognitive cost and makes reversibility unclear.82%Interaction Responsive Motiontables / responsiveResponsive Tables and Comparison
Tables support comparison, so responsive behavior must preserve columns, sorting, and key actions.
Turning tables into cards indiscriminately can destroy comparison; choose the pattern by data task.82%Interaction Responsive Motionloading / performancePerceived Performance and Loading Structure
Loading states should preserve layout skeletons so users know what will appear, instead of showing only a spinner.
Stable skeletons reduce waiting anxiety and avoid layout shift when content appears.82%Interaction Responsive Motionmotion / animationRestrained Motion With Purpose
Motion should explain state change, spatial relationship, or feedback instead of adding noise.
Excessive motion interrupts tasks, especially in dense tools.82%Interaction Responsive Motionbreakpoints / responsiveBreakpoint Recomposition, Not Scaling
Responsive design should recombine layout relationships at breakpoints instead of scaling everything by viewport.
Scaling type and containers causes unpredictable overflow; recomposition is more stable.82%Interaction Responsive Motionmobile / responsiveMobile Priority Stack Layout
Mobile is not a smaller desktop; content and actions should restack by task priority.
Small screens need important information, controls, and feedback early without overlap.82%Interaction Responsive Motionprogressive-disclosure / complexityProgressive Disclosure by Task Risk
Low-frequency, risky, or advanced settings should be deferred while common tasks remain reachable.
Progressive disclosure does not hide functionality; it places complexity at the right decision moment.82%Interaction Responsive Motionfeedback / statesFeedback States for System Continuity
Loading, saving, generating, review, and failure all need visible states so users know the system is responding.
Missing feedback causes repeated clicks or fear that data was lost.82%Interaction Responsive Motioncards / panelsCard and Panel Density Affordance
Cards represent objects, panels represent tools or context; they need different density and affordance.
Clickable objects must be recognizable, while informational containers should not masquerade as buttons.82%Interaction Responsive Motionbuttons / actionsButton Priority and Action Separation
Primary, secondary, destructive, and navigation actions need clear differences to avoid mistakes.
Button styling expresses decision cost and risk, not just visual preference.82%Interaction Responsive Motionforms / workflowForm Flow and Validation
Forms should follow the user's mental order and provide recoverable feedback at key moments.
Good forms split complex tasks into completeable steps rather than dumping every field at once.82%Interaction Responsive Motionnavigation / wayfindingNavigation Landmarks and Current State
Users need to know where they are, where they can go, and what scope the current page belongs to.
Navigation is not a pile of links; it continuously communicates structure and current location.82%