Design Knowledge Base
Community-maintained principles reviewed before publication and retrieved as Agent design constraints.
Scroll Container Ownership Contract
Long pages, libraries, and workbenches must define one primary scroll owner; declare scroll ownership before combining nested `height: 100vh`, `overflow: hidden/auto`, and sticky panels.
Scrolling is not incidental browser behavior; it is a layout contract. Decide who owns page scroll, who owns local scroll, which panels are sticky, and how mobile reflows before implementation.97%Frontend Implementationmaterial / glassTranslucent Material Readability Contract
Glass, acrylic, mica, smoke, and backdrop blur are not just style filters. They need explicit surface role, backdrop variability, hierarchy, contrast, user preferences, forced-colors behavior, and fallback.
The value of translucent material is connecting interface hierarchy with background context. If it weakens reading, state recognition, keyboard focus, or accessibility preferences, it should fall back to an opaque surface.96%Frontend Implementationaria / componentsARIA Component Contract
Before styling a custom interactive component, define its native-first decision, name/role/value, ARIA/DOM states, keyboard matrix, focus path, visual states, and test assertions.
ARIA is not a magic semantic layer for divs; a component is implementable only when native semantics, keyboard behavior, accessible name, state attributes, and visual state agree.96%Interaction Responsive Motionoverlay / dialogOverlay 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%Frontend Implementationupload / dropzoneFile Upload State and Validation Contract
An uploader is not a dashed box. It is a state machine from selection, validation, upload, pause, failure, retry, and final file record; drag-and-drop is enhancement, not a replacement for accessible file selection and server validation.
File upload spans interaction, network, privacy, security, and accessibility. A healthy uploader defines file purpose, restrictions, API, states, and recovery before choosing react-dropzone, Uppy, FilePond, tus-js-client, or native input.96%Frontend Implementationcomponents / statesComponent State Matrix Contract
Before generating or adopting a component, define the state matrix, triggers, ARIA/DOM expression, visual tokens, and test path instead of only shipping the static default state.
Component quality is not the default-state screenshot. Every reachable state must remain understandable, recoverable, and testable across mouse, keyboard, touch, screen readers, loading, errors, and permission limits.95%Frontend Implementationcopy-in / motionCopy-in Motion Component Localization and Accessibility
After copying an external motion component, Lottie/Rive player, Motion/GSAP example, or registry block, localize copy, states, direction, duration, reduced motion, pause/stop/hide behavior, keyboard paths, and license source.
Once a motion component is copied into the repository, it is no longer a demo fragment. It becomes a local interaction asset that must satisfy brand voice, language direction, accessible fallbacks, performance budget, and source licensing.95%Frontend Implementationaria / apgARIA APG Widget Pattern Contract
Before hand-rolling complex widgets, extract roles, states, properties, keyboard tables, focus strategy, and test assertions from WAI-ARIA APG; prefer native controls or mature primitives when they fit.
ARIA is a semantic and interaction contract, not magic attributes for divs. Custom comboboxes, dialogs, tabs, treegrids, menus, listboxes, and similar widgets must prove their keyboard, focus, and assistive-technology model first.95%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%Design Systems Page Patternspublic-service / trustPublic-Service Trust Rails and Recovery
Public-service interfaces must make official identity, responsible organization, legal links, task title, form semantics, error summaries, and recovery paths into verifiable page structure instead of merely applying blue-white civic styling.
Trust in public services comes from an inspectable responsibility chain and recoverable task flow: users need to know whether the service is official, who is responsible, whether the connection is safe, why information is needed, how to fix mistakes, and where privacy/accessibility/oversight information lives.95%Frontend Implementationtables / responsiveResponsive Data Table Disclosure Contract
Complex data tables should not simply shrink text or force horizontal scrolling on mobile; define primary key, column priority, alternate presentation, header relationships, and batch/row action boundaries.
A data table is a comparison structure. Responsive treatment must preserve comparison relationships and accessible semantics, not only the desktop visual appearance.95%Design Systems Page Patternsinformation-architecture / navigationInformation Scent and Link Label Contract
Navigation, card links, and inline links must help users judge destination, value, and effort before clicking; vague labels such as read more weaken findability and accessibility.
Information scent comes from link text, surrounding context, and users' prior knowledge. A design system should treat link labels as information architecture, not as late-stage button filler.95%Data Visualizationmap / poiMap POI Icon Attribution Boundaries
POI icon sets such as Maki solve map symbols, not map data, tiles, style, basemap providers, place labels, or interaction attribution.
Map symbols are one layer of visual encoding. Agents must govern icon set, sprite, map style, geodata, tile provider, legend, and accessible labels separately instead of treating icon license as map license.95%Data Visualizationmaps / geospatialMap Data Attribution and Alternatives
Map interfaces must separately record runtime library, tiles, styles, glyphs, sprites, geodata, and provider attribution, while providing list/table alternatives and keyboard-reachable paths.
A map is not a background image. It combines complex data visualization, interactive controls, and licensed materials; users must understand location, scope, selected object, data source, update time, and alternate access paths.95%Data Visualizationaccessibility / chartsAccessible Chart Alternatives
Charts need takeaway titles, text summaries, redundant encodings, and data-table alternatives; Canvas or SVG alone is not automatically accessible.
Data visualization is non-text and often interactive content. It must give equivalent conclusions and data paths to people who cannot see the chart, distinguish colors, use a mouse, or read it at default size.95%Resource Licensingavatar / placeholderDeterministic Avatar Placeholder Governance
Avatar generators such as Boring Avatars and DiceBear work well for identity placeholders, but seed, style, license, private inputs, and accessible names must be recorded; generated avatars are not real likenesses or brand assets.
The value of a deterministic avatar is stable object recognition, not real identity. It combines visual distinction, privacy, licensing, accessible labeling, and cross-project reuse boundaries.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%Resource Licensingbrand-logo / trademarkBrand Logo Use Boundaries
Brand logos should be used only for real brand references, integrations, payment methods, customer or partner proof, or authorized collaboration. Confirm trademark and brand guidelines, avoid implied endorsement, do not alter shape or color casually, and provide accessible names.
A brand logo is not an ordinary icon. The code license of an open-source project, aggregator, or SVG package usually does not replace trademark, brand-guideline, endorsement-context, and usage-scope judgment.95%Resource Licensingicons / licenseIcon Set License, Trademark, and Accessibility Governance
Icons are not arbitrary decoration; primary icon sets, aggregated icons, brand logos, and icon-only controls need separate license, trademark, import, and accessibility rules.
Icon governance keeps symbols visually consistent, legally reusable, screen-reader understandable, tree-shakable, and prevents brand logos from becoming free decoration or implied endorsement.95%Resource Licensingvideo / motionStock Video Hero and Background Governance
Free stock video can make heroes feel more real, but each use must confirm item license, likeness/trademark/property rights, attribution, poster, pause control, reduced motion, and mobile performance.
Background video is not moving wallpaper. It belongs in production only when it serves first-viewport signal, brand tone, or story evidence without weakening readability, accessibility, licensing, or performance.95%Resource Licensingillustration / empty-stateFriendly Asset Governance for Empty States
Illustrations, emoji, and Lottie can make empty states friendlier, but they must first serve reason, next action, license record, alt text, and reduced-motion.
Friendly assets are not the main actor in an empty state. They reinforce tone, reduce anxiety, or aid understanding; the real interface value is clear reason, next action, and legally reusable asset metadata.95%Typography Color Accessibilitycharts / accessibilityChart Accessibility Encoding
Chart Accessibility Encoding turns a frequent interface judgment into an executable constraint before generation.
An accessible chart is not a graphic with one alt sentence; its visual encodings, text summary, interaction states, and data alternative all carry the same evidence.94%Typography Color Accessibilitybackground / textureDecorative Background Readability
Textures, patterns, gradients, noise, and media backgrounds must serve text, controls, semantics, and performance instead of turning content into atmosphere.
A background is a support layer for hierarchy and mood; once it carries meaning, affects reading, or moves, it needs semantic alternatives, contrast evidence, motion fallback, and license records.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%Frontend Implementationbackground-texture / cssBackground Texture CSS and Accessible Fallbacks
Background texture should enter as a secondary layer through tokens, CSS/SVG output, and fallback strategy while preserving readable UI in forced colors, print, mobile, and low-data conditions.
Background texture adds surface depth, brand tone, or redundant encoding; it should not steal information hierarchy. Production implementation must treat texture as a disable-able, compressible, replaceable surface layer.94%Frontend Implementationcomponents / radixPrimitive Component Selection
When an interaction involves focus, keyboard behavior, overlays, arrow keys, or screen-reader semantics, start from a mature primitive and apply local visuals.
The risk in complex interactive components is usually not styling. It is focus management, keyboard paths, ARIA semantics, portals, collision positioning, and mobile scroll locking. Primitives stabilize that behavior first.92%Typography Color Accessibilitycolor / contrastContrast-Generated Color Tokens
Generating color scales from target contrast ratios can improve theme accessibility, but the output must still map to semantic tokens and state roles.
Accessible color systems should not audit contrast only after design. Contrast targets should shape color-scale generation and token naming from the start.92%Frontend Implementationloading / skeletonLoading Skeleton Progress Contract
Loading states should choose skeletons, inline loading, spinners, progress bars, or stage feedback based on duration, scope, and measurability, backed by a frontend state machine for accessibility, stability, and recovery.
The goal of loading feedback is not to decorate waiting; it tells users whether the system responded, what region is changing, whether they can still act, whether wait time is knowable, and how recovery works after failure. Different wait scenarios require different feedback modes.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 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 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%Typography Color Accessibilitymotion / reduced-motionReduced Motion Accessibility
Reduced Motion Accessibility turns a frequent interface judgment into an executable constraint before generation.
Animation and transitions need to respect reduced-motion preferences and provide non-motion information paths.86%Typography Color Accessibilityforms / labelsPersistent Form Labels
Persistent Form Labels turns a frequent interface judgment into an executable constraint before generation.
Form labels should remain visible before and after input so users can confirm meaning and context.86%Typography Color Accessibilityauthentication / accessibilityAccessible Authentication Flow
Accessible Authentication Flow turns a frequent interface judgment into an executable constraint before generation.
Secure flows still need low cognitive load, helping users complete rather than testing them.86%Typography Color Accessibilityforms / errorsError Summary Pattern
Error Summary Pattern turns a frequent interface judgment into an executable constraint before generation.
Users need to know how many errors exist, where they are, and how to fix them without hunting for red text.86%Typography Color Accessibilitytarget-size / touchTarget Size and Spacing
Target Size and Spacing turns a frequent interface judgment into an executable constraint before generation.
Interactive targets need enough size and spacing, especially on mobile, toolbars, and dense lists.86%Typography Color Accessibilitylinks / contrastLink Contrast and Affordance
Link Contrast and Affordance turns a frequent interface judgment into an executable constraint before generation.
Links are navigation promises; users must quickly recognize clickable text in reading flows.85%Typography Color Accessibilitycognitive-load / copyCognitive Load Copy
Cognitive Load Copy turns a frequent interface judgment into an executable constraint before generation.
Users should not need to remember system state, previous-screen information, or hidden rules to complete a task.84%Typography Color Accessibilitycontent / plain-languagePlain Language
Plain Language turns a frequent interface judgment into an executable constraint before generation.
Understandability is part of accessibility; complex copy increases cognitive load for everyone.84%Typography Color Accessibilityicons / ariaIcon Accessible Names
Icon Accessible Names turns a frequent interface judgment into an executable constraint before generation.
Icon-only buttons and statuses need accessible names, while decorative icons should be hidden from assistive technology.84%Typography Color Accessibilitytypography / spacingText Spacing Resilience
Text Spacing Resilience turns a frequent interface judgment into an executable constraint before generation.
Interfaces should tolerate adjusted line height, letter spacing, font size, or browser zoom without hiding content.84%Typography Color Accessibilityforms / redundant-entryRedundant Entry Reduction
Redundant Entry Reduction turns a frequent interface judgment into an executable constraint before generation.
Redundant entry increases cognitive load, errors, and abandonment, especially for assistive technology users.84%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%Typography Color Accessibilitytouch-target / mobileAccessible Interactive Targets
Buttons, links, menu items, and icon buttons need sufficient hit area, especially on mobile.
A visually small control does not need a tiny hit area; targets require stable size and clear feedback.82%Typography Color Accessibilityaccessibility / colorColor Must Not Stand Alone
State, risk, category, and selection cannot rely on color alone; text, icon, shape, or position must help.
Color semantics weaken under color blindness, low vision, printing, and poor lighting.82%Typography Color Accessibilityfocus / keyboardVisible Focus States
Keyboard and assistive technology users need to know where focus is; focus states must not be reset away.
Focus state is part of the interaction path, not a browser default flaw.82%Typography Color Accessibilityforms / accessibilityAccessible Form Feedback
Form feedback should sit near fields, explain why, and remain understandable before and after submission.
Error messages are not punishment; they guide users toward completion.82%Typography Color Accessibilitycontrast / accessibilityLegibility Contrast
Text contrast must serve reading first, especially for small text, disabled states, notes, and button labels.
Low contrast turns polish into unusability, especially on mobile and in difficult lighting.82%