Design Knowledge Base
Community-maintained principles reviewed before publication and retrieved as Agent design constraints.
Translucent 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%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%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%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%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%