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 Implementationai-ui / citationsAI Response Citation and Evidence Surface Contract
Citations in AI/RAG answers are not footer decoration. They are an evidence surface joining claims, sources, snippets, permissions, streaming state, copy/share behavior, and auditability.
Trustworthy AI interfaces let users see which claims have sources, whether sources are accessible, when evidence was generated, how to open or copy it, and how missing, stale, or low-confidence evidence is handled.96%Frontend Implementationapi-reference / openapiAPI Reference Endpoint Page Contract
An API endpoint page should combine method/path, auth, parameters, request body, response/error matrix, examples, try-it safety, and mobile schema reading into one executable documentation contract.
An API reference is not complete just because an OpenAPI schema is rendered. It is an operating surface for developers and must support discovery, first calls, auth setup, error recovery, copied examples, try-it safety, and version trust.96%Frontend Implementationdeveloper-docs / code-blockDeveloper Docs Code Example and Copy Contract
Code blocks in developer docs must do more than look highlighted: they explain the task, copy safely, provide clear feedback, keep tabs keyboard-operable, and avoid breaking mobile page scrolling.
A code example is a product operation surface. It carries teaching, configuration, API calls, trust, and execution cost, so syntax highlighting, copy, placeholders, tabs, playgrounds, responsiveness, and accessible feedback need one component contract.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 Implementationscroll / motionScroll-linked Motion Implementation Boundaries
Scroll motion must distinguish CSS scroll timelines, GSAP ScrollTrigger, Lenis smooth scroll, and native scrolling; immersion must not break reading, anchors, keyboard behavior, or mobile feel.
Scroll is user-controlled reading rhythm, not the animator's timeline. Implementation should preserve native scroll semantics first, then bind lightweight motion to sections where it adds value.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 Implementationcontainer-query / responsiveContainer Query Component Contract
Responsive components should not only follow the viewport; cards, sidebars, charts, and resource cards should adapt density, hierarchy, and actions to their own container width.
Container queries move responsive decisions from page-level breakpoints into component context, letting the same component work inside grids, sidebars, drawers, modals, and dashboard slots.95%Frontend Implementation3d / three.jsWeb 3D Asset Runtime Pipeline
A Three.js page is not just a canvas; 3D assets need source licensing, glTF optimization, texture compression, loading states, interaction goals, fallbacks, and verification evidence.
Web 3D combines design, assets, runtime, and performance budgets. Agents can safely generate 3D experiences only after governing model source, geometry complexity, texture format, fallback path, and accessible explanation.95%Frontend Implementationview-transition / navigationView Transition Route Continuity
The View Transition API can make route, filter, and detail changes feel continuous, but it must preserve URL, focus, scroll, reduced-motion, and progressive enhancement boundaries.
Page transitions are not spectacle; they help users understand continuity of the same object across lists, details, filters, and state changes.94%Frontend Implementationa11y-testing / axe-coreAutomated Accessibility Tool Triage
axe-core, Storybook a11y, Pa11y, Lighthouse, Accessibility Insights, and WAVE should be layered: automation catches common issues first, then humans verify task flows.
Automated accessibility testing is an early warning system, not complete compliance proof. A healthy process converts tool output into reproducible, fixable, retestable product-task defects.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 Implementationcss-color / oklchCSS Color Spaces and Gamut Fallbacks
Modern CSS supports OKLCH, P3, and relative colors, but production tokens still need to handle sRGB, older tooling, screenshot tests, and third-party renderers.
Frontend color implementation must separate design source, modern CSS output, and compatibility fallback; browser support does not mean every toolchain supports the same syntax.93%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 Implementationshadcn / component-governanceCopy-in Component Governance
Copy-in components such as shadcn/ui become local assets once added, so they need token mapping, a state matrix, upgrade policy, and license records.
The advantage of copied source components is control and adaptability. The cost is that the project owns consistency, upgrades, license notices, and design-system adaptation.91%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%