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