write-ui-examples

# Write UI Examples Help readers discover UI features, feel their behavior and copy appropriate patterns. Every public feature needs documentation. Features without a visual motivation usually need prose, a wiring snippet and an API reference rather than another live demo. The docs also help maintainers evaluate an evolving library. Preserve observable differences and unsupported capabilities so readers can compare APIs and interactions without reading their implementations. ## Documentation architecture - Keep TSX documentation pages under `docs/ui/app/pages/` and runnable `.example.tsx` modules under `docs/ui/app/examples/`, grouped by feature. Use the existing page helpers, explicit source loading and normal Remix hydration rather than bundler-specific snippet machinery. Keep documentation authoring files out of published package output. - Treat UI as a standalone, currently unstable library. Put installation, package status and shared styling or composition concepts in Getting Started. Organize existing features under Patterns and Animation. Do not introduce a speculative system layer. - Name the library Remix UI rather than using UI as a standalone product name in prose. Once identified within a passage, use the library, the package or a pronoun where clear instead of repeating Remix UI. Generic terms such as UI patterns and the shared UI navigation label are still appropriate. - Cover useful supported compositions as well as dedicated library options. Compare related library examples, established UI libraries and the relevant WAI-ARIA Authoring Practices patterns for gaps such as named option groups, visible labels and descriptions. Verify the composed markup and interaction against the implementation; a standard HTML or ARIA feature can deserve an example even without a dedicated Remix UI API. Add a live demo when the composition reveals a distinct interaction, and concise guidance beside an existing demo when markup alone supplies the lesson. Give supported compositions such as grouped options or menu items named feature sections so readers can discover them without reading example source. Show the consumer-authored semantics, labeling and keyboard entry points needed by the composition, including focusable text-only tab panels. Associate useful existing help text with its control, and keep the accessible name distinct from its description. Add instructions only when the interaction benefits from them; do not expand every demo into a form or settings group merely to show standard markup. - Preserve shared docs branding, navigation positions and theme behavior. A UI-focused preview layout can differ without redesigning the rest of the docs site. ## Choose the interaction first Before coding, read the public API and implementation, and the current or similar examples. For an unfamiliar pattern, compare the relevant Base UI or Radix example and earlier repo demos. Verify historical authorship before attributing an example. Borrow interaction conventions rather than framework-specific code or unsupported capabilities. For each proposed example, decide what the reader should observe, which familiar interaction fits it and whether a live example is needed. Write down three plausible interaction patterns and prefer the one where the documented feature does useful, observable work in a familiar task with the least context. Judge both product UX and implementation fit. The smallest composition is not the best example if it removes the reason to use the feature. Explain why its trigger, surface and outcome belong together. Reject a scenario before implementation if it needs unrelated controls or explanatory copy to make sense. - Treat realism as pattern fit and believable content, not the amount of application detail. A realistic example is a small, familiar interaction whose controls and labels naturally belong together. It does not need a surrounding app, a backstory or a complete workflow. A labeled switch or populated action menu can be a complete example. - Choose the scenario and content together. A compact set of familiar statuses can make a filter list self-explanatory. Arbitrary departments or invented project details can require more context than the feature warrants. Use familiar, purposeful content. Avoid fictional project summaries, activity feeds, dates and decorative cards unless the feature needs that context. Avoid meaningless numbered items and lorem ipsum when labels help evaluate the pattern. Include specific details only when they help readers recognize or evaluate the interaction. Prefer neutral wording over incidental brand names. - Review content as a set. Labels, descriptions, actions and states must belong to the same recognizable context and level of abstraction. Match action labels to the specific meaning of their icons. A bookmark icon should say Bookmark rather than a broader action such as Save that could imply persisting edits or downloading a file. Plausible individual labels can still make an incoherent group. Check why these particular items would appear together in one product. - Put enough content inside the primitive to exercise it. Search needs a useful collection. A submenu needs sibling actions that justify nesting. Radio and checkbox menus need meaningful choices. - A menu example can demonstrate activation and dismissal without implementing an editor or file system behind its commands. Preserve the primitive's complete interaction without inventing surrounding state just to prove a callback ran. - Match the primitive to the task. Searchable selection from a substantial collection suits Combobox. A few fixed choices usually suit Select. Actions suit Menu. Do not accidentally teach a different primitive's job. - A floating surface needs a reason to float. Compact settings, filters and editing forms are established patterns. A button revealing an isolated sentence is not automatically a useful popover just because its content is brief. Choose placement that reinforces the relationship to its trigger. - Review overlapping primitives together, not only each page in isolation. Imagine one application using both APIs for good reasons and identify the distinct responsibility of each. Choose examples that make that choice understandable. If sibling pages show the same interaction, either explain the composition tradeoff explicitly or find scenarios that better reveal their different purposes. A plausible standalone example can still blur which API consumers should choose. Also compare it with a simpler native or CSS implementation. Distinguishing two library APIs is not enough if the example manufactures extra structure just to use either one. - Identify the abstraction level before choosing a demo. A behavior primitive, positioning utility and composition recipe need different framing. For a lower-level utility, explain what it contributes, what supplies the rest of the interaction and when consumers would use it directly instead of a higher-level primitive. A working example can still teach the wrong default if its scenario is better served by another public API. - Low-level geometry utilities can lead with focused positioning illustrations when geometry is the lesson. Make placement, alignment, viewport fit or tracking observable without inventing an app interaction. Neutral labels are appropriate in a technical illustration. Keep product interactions complete when showing a composition, and attribute opening, dismissal, focus and semantics to the native features or primitives that actually supply them. Verify native accessibility behavior before presenting it as a reason to require a higher-level primitive. Reusing a scenario across layers can support an explicit comparison, but do not present duplicate recipes as interchangeable defaults. Prefer a wiring snippet over inventing an incomplete application for an option. - Keep one main behavior per example. Do not add unrelated disabled, loading or error states merely to cover another API option. Across variations, retain the canonical content and change only what the feature requires so readers can compare behavior directly. A layout animation should not also switch display modes, reverse order and expose configuration flags. - Availability states need a credible cause within the scenario, such as an unmet prerequisite, eligibility rule or workflow state. Establish why an unavailable choice should remain visible instead of being omitted. Retain it when it helps users compare capabilities, understand eligibility or discover how to make it available. A plausible status such as archived is insufficient if that item would normally disappear from the task. Do not add explanatory UI for familiar states whose meaning is already clear, such as an unavailable Undo action. When availability depends on less obvious context, make the reason visible and accessible without activating the unavailable control or opening its panel. Place it where visual grouping clearly attributes it to that control, such as beside its label. Give the control label and supporting reason a clear typographic hierarchy through weight, color and spacing while keeping the reason readable. Keep equivalent labels styled consistently across siblings. Establish hierarchy between labels and supporting text without accidentally emphasizing only one peer. Do not mute them together until their roles become indistinguishable. An aria-describedby relationship alone does not fix a visually detached explanation. Do not put the reason in another control’s content region. For unavailable tabs, distinguish an unsupported capability from an empty panel that should remain accessible with an empty state. Check that blocking this particular action makes product sense. An unavailable action does not justify hiding information the user still needs. Prefer a code example if no convincing interaction fits, and avoid inventing a surrounding workflow just to explain the state. - For controlled state, first look for a familiar interaction where application state naturally coordinates the control with another element. A Show password switch and password input share one boolean that drives both checked state and input type. This explains why the state belongs to the application without duplicate controls or invented feedback. Compare this with a native form reset before proposing Clear all or Reset. Do not require controlled state to be the only possible implementation, but make it a natural architectural choice. Use a snippet when no compact, useful visual interaction fits. Add external actions only when they have an independent product purpose. ## Reduce the composition before polishing A plausible scenario can still be overdesigned for an example. Compare the proposed composition with a simpler version before styling it. - Find the fewest control types and decisions that preserve a credible interaction and expose the documented feature. For a filter popover, a small checkbox list can be enough. A select, a second filter category and an Apply workflow each need an independent reason to be present. - Prefer a coherent set of choices over a mixture of controls when both communicate the feature equally well. Keep extra controls when the documented feature actually depends on them. - Do not invent draft state, commit buttons, reset actions, badges or result summaries merely to make a demo feel functional. Immediate changes can be the more natural interaction. Preserve the behavior that the chosen pattern does require. - Assess visual and source density together. Remove machinery that competes with the API being taught, then refine hierarchy, spacing, alignment and hit areas. Simplicity should still feel deliberately designed. ## Adversarial product UX review Every UI example must pass a product UX review before it is presented as finished. This is a distinct pass from checking that the code works. Review it as if the interaction and content were being shipped in an app or presented in a product design review meeting. - Would a product designer choose this interaction for this content without knowing which API the example must demonstrate? Why does the user open it, and why is this preferable to showing the content inline or using another primitive? - Do the items belong together, including their descriptions and availability? Does each variation preserve that context while isolating the feature being taught? - Does each action have the expected result? Does the example imply a workflow it does not actually implement? - Check the expectations created by the visible content, not only the API path the example was built to demonstrate. Try likely searches and actions using the labels and supporting text a user sees. Searchable options should include meaningful visible names and descriptions in their search data, rather than finding hidden aliases while omitting prominent text. Verify the actual matching behavior; owning the markup does not imply owning filtering. If the API cannot deliver a credible interaction for the scenario, revise the scenario or report the API concern separately instead of explaining away the mismatch in demo copy. - Does the example reveal why a consumer would use the documented feature, rather than merely include it in source? Would a simpler native mechanism fit better? Before falling back to code alone, have you considered a familiar interaction where the feature has a direct purpose? - Is the primary interaction obvious without instructions inside the preview? - Is this the simplest convincing version of the interaction? Can an entire control type, workflow step or content group be removed without making the example less useful or less natural? - Does the apparent interactive boundary match the actual hit area? Test the label, whitespace and control itself across equivalent host variants. A rounded standalone control can imply that the entire surface activates it. Use native labeling where possible and keep one keyboard focus target. - Do hover, pressed and focus states reinforce the interaction implied by the visual design? Apply feedback to the actionable surface, not indiscriminately to enclosing cards or form groups. Unavailable and read-only controls must not advertise activation. - Does each indicator describe an available action or actual state? Avoid collapse affordances on locked-open panels and controls that duplicate existing controls. - Can readers infer why each unavailable control is unavailable from the visible UI? Would a product designer disable this action, leave its information readable or use another treatment? - Do focus, dismissal, selected state and disabled state behave coherently across the whole interaction? - Does the example still make sense with keyboard and touch input, repeated actions and rapid changes? When it fails, return to scenario selection and compare alternatives. Shortening copy, renaming a button or adding polish does not fix an interaction that has no credible purpose. Change the scenario or remove the demo. Treat subsequent user feedback as evidence of a missing decision criterion. Update this skill with the reusable principle that would have caught the failure, then reassess earlier examples affected by that principle. Keep this review in working notes or the completion report rather than adding review machinery to the example UI. ## Preserve the library's actual contract - Document each component's actual props, state ownership, event payloads, attributes and defaults. Do not smooth over differences to make the API appear consistent. For a coverage audit, compare each public export and option with its implementation and tests, including defaults, matching rules, event timing, keyboard handling and form behavior. A symbol appearing in a reference is not proof that its contract is explained. Reproduce contradictions before choosing wording and record library bugs separately from documentation gaps. - Report confirmed bugs, workarounds and accidental API migration leftovers separately to the user rather than turning the docs into a bug inventory. Document supported contracts and intentional API differences. Do not claim broken behavior works, but do not add warnings or recommend avoiding specific values solely to describe an implementation defect. - Do not frame the absence of an unpromised capability as a documentation caveat. Explain supported behavior without comparisons to hypothetical support, such as right-to-left layouts, unless the public contract or the task makes that capability relevant. - Review the complete diff for usefulness and tone after a coverage audit. Added detail should help consumers choose, compose or use the API. Remove inventories of missing capabilities and speculative warnings. Keep constraints that directly govern supported usage, accessibility responsibilities and observable timing, placing edge rules in the reference rather than repeating them throughout the page. - Match state-section headings to the supported ownership model. Use Controlled state when contrasting externally managed state with an uncontrolled mode. If the API only supports externally managed state, prefer Managing state and explain which values the consumer must supply and update. Verify support in the implementation rather than inferring it from neighboring primitives. - Cover selection flashes, close motion and label timing in ordinary working examples and source when those examples already expose the behavior. A dedicated preview should demonstrate a distinct supported configuration or interaction, not repeat the same fixed feedback with different colors. Keep event ordering in prose or the reference when it affects what readers see or when state commits. Style brief selection feedback as a restrained variation of the settled selection color, preserving its hue and text treatment rather than switching between unrelated palettes. For action menus without a persistent selection, use the existing highlight palette. Keep feedback perceptible without an abrupt bright fill or unnecessary text-color inversion. - Distinguish fixed internal timing from public timing options. CSS can style feedback without controlling its lifetime. Preserve fixed library timing and explain the limitation rather than simulating a longer sequence, delaying dismissal artificially or changing primitive behavior. Do not invent configuration or normalize differing event sequences. - Ordinary change events generally need wiring and payload documentation. Analytics, persistence and state updates do not justify a separate mock product UI. Retain a visual event example only when its resulting interaction independently earns its place. - Make snippets support the surrounding claim. Generic anatomy does not demonstrate draft-versus-committed input behavior. Separate visible input text, submitted value and commit rules when explaining forms. - Explain distinct pieces of state before describing transitions between them. Name what each represents, why the distinction matters and how it maps to public APIs or form fields. Ground abstract terms such as draft or committed in one concrete value-and-label example. Separate the conceptual model from edge rules such as blur and Escape, and verify each rule independently. - Describe the feature in prose. Let examples demonstrate a usage. When an example also uses another public pattern or utility, briefly name its contribution and link to its documentation near the example or its explanation. Distinguish the demonstrated pattern’s own behavior from the supporting API without repeating the supporting guide or annotating every framework helper. Avoid narrating the mock application or repeating cross-cutting concepts on every page. - Introduce public touch points before relying on them. The reference should specify accepted values, defaults, provided state, decorated attributes and event detail for each provider or mixin in turn. Use tables for comparable options and exported types rather than walls of text. - Explain the styling and motion contract before discussing one technique. Examples can use a particular transition, but prose should not imply that technique is required unless the implementation requires it. ## Code and presentation - In live examples and displayed snippets, lead imports with the pattern or API being taught. Put supporting UI APIs next, then framework helpers, styling and types. Import order should introduce the subject before its wiring; do not lead a Listbox example with `css`. - In `mix` arrays, lead with the Remix UI APIs being documented, then supporting behavior such as `on()` and `ref()`, and put all styling last, including `styles.*` entries and inline `css()`. Apply this to live examples and displayed snippets so behavior is visible before presentation. Preserve relative order within each group and verify interactions after reordering, since mixins compose element props in sequence. - Lead behavior primitives with a canonical live example, followed immediately by code-only Anatomy, then focused variations, accessibility and a reference organized by public part. Keep exploratory alternatives and secondary recipes after anatomy once a hero is chosen. Utilities can lead with a focused technical illustration or minimal wiring when that better explains their contract. Put behavioral explanations and supporting API links in the intro or the relevant feature section, outside Anatomy. Keep short anatomy and wiring snippets visible. Show a small faded preview of complete live-example source with an accessible Show code control below it. Match the preview and code backgrounds so the text fades into the same surface in light and dark themes. Expand source into normal document flow rather than a nested vertical scroller. Preserve code indentation and line breaks, allowing horizontal scrolling for long lines instead of wrapping, including on narrow screens. While expanded, keep Hide code available at the viewport bottom and constrain it to the source block. Collapsing source should preserve keyboard focus and position Show code just below the sticky navigation, with the code preview above the visible content so readers can continue to the next section. Keep the demo available without opening its source. - Put standalone disabled and read-only sections after the main behavior variations, state management and forms, before accessibility and the API reference. Keep availability details beside another feature when they are necessary to explain it. - Let the page description frame the hero without another redundant title or explanation. Use a short intro for cross-cutting behavior readers need to understand the canonical example; put feature-specific explanations beside the relevant example. Style the intro as ordinary body copy so it stays secondary to the page description. Do not invent a separate demo for ordinary core behavior. Reserve Anatomy for a skimmable, code-only structural API map after the hero: no introductory paragraphs, behavior explanations or captions. Show providers, mixins, required relationships and state styling hooks in the code itself. Put empty selector rules in an inline `css()` mixin beside the behavior they style, rather than introducing a `styles` object or imposing a visual structure. Verify each selector against the actual host element and distinguish native pseudo-classes from library attributes. Utilities need only the wiring relevant to their API; do not invent styling hooks. - Use descriptive placeholders in Anatomy, such as Trigger text, Option text and Panel content, with representative identifiers such as `option-value`. Match API labels to visible text. Show one representative repeated part and omit datasets, mapping loops and application backstories. Preserve required semantics and relationships. Keep Anatomy expanded; reduce incidental setup before hiding essential structure. Anatomy must exhaustively surface distinct supported styling states across public parts and host or feature variants, not every attribute emitted by the implementation. Use additional anatomy snippets for variants such as custom hosts, checked items and submenus rather than omitting their hooks. Shared variants can share a map when the code makes that relationship clear. Before finishing, compare each mixin with its implementation, following composed mixins and helpers as well as direct attribute assignments. Verify the receiving element, exact attribute or native pseudo-class, emitted values and conditions, including transient selection and dismissal states. For each distinct styling state, show the intended hook and its supported values, using the shortest selector that correctly identifies the state. Prefer the library’s higher-level state hook over native or ARIA attributes that mirror it on the same element: show Accordion’s `[data-state]`, not redundant `[aria-expanded]`, `[aria-hidden]` or `[inert]` rules; likewise omit Toggle’s `:checked` and `[aria-checked]` when `[data-state]` already covers selection. Keep native or ARIA hooks when no higher-level styling hook represents that state on that element, including distinct disabled, read-only and required states. Do not infer redundancy from similar names alone: Accordion’s trigger `aria-disabled` represents locked-open behavior, distinct from native `:disabled`. Keep accessibility attributes documented in the reference without presenting every one as a styling recommendation. For boolean flags that the implementation adds only when true and removes otherwise, prefer presence selectors such as `[data-menu-flash]`; do not repeat `="true"`. Keep explicit value checks when both true and false are emitted, as with Listbox’s `data-highlighted`, and for meaningful named states such as `[data-submenu-state="dismissing"]`. Verify these distinctions per primitive and host rather than applying a global replacement: identical attribute names can have different emission rules. Absent attributes and ordinary base styles need not have redundant selectors. Keep identity and accessibility relationship attributes in the API reference rather than adding empty CSS hooks for them. Check consumer-authored native and ARIA states separately from attributes supplied by the library. Match selectors to the host actually shown: do not add unused ARIA fallbacks to input-only styles or duplicate a custom host’s library-supplied ARIA state with native hooks merely to cover a hypothetical consumer prop. An exhaustive API table or passing live-example test does not establish anatomy completeness. - Do not give every implementation technique its own preview or every explanation its own section. Place conceptual framing beside the first example that needs it and detailed edge rules with the relevant API. - Keep prose comprehensive through precision. Remove redundant headings, introductory filler, repeated code narration and statements true of every primitive. Preserve useful accessibility and keyboard guidance without reteaching the basic setup. - Use `remix/component`, the owning UI package's public imports and the `css()` mixin. Keep live example source self-contained and readable. Typecheck and format interactive examples as real source files, with focused browser tests for the behavior they demonstrate. - Short explanatory snippets may remain inline fragments when surrounding context is already clear. Format them as code using the repository rules before highlighting. Formatting failures must preserve the original snippet and warn without breaking the page. These fragments are not typechecked, so review them alongside API changes. Do not introduce source-region extraction or artificial setup solely to make every fragment independently executable. - Name default-exported live components for their subject, such as `ExampleAccordion` or `ExampleCombobox`, so copied source retains its context. Order full examples for readers: main component, local styles, helper components and SVG icons, then supporting datasets last. Separate top-level declarations and functions with blank lines, including around nested helper functions. Keep SVG markup out of the main interaction, including conditional and repeated markup. - In full live examples, group named CSS mixins in a local `styles` object, such as `styles.root` and `styles.option`. Define meaningful repeated styling values as CSS custom properties on the example’s root style and reference them with `var()`. This keeps styling within one `styles` object without introducing a separate JavaScript token abstraction. Keep one-off values inline, preserve inheritance to floating surfaces, and retain ordinary JavaScript constants when the behavior itself needs them. Keep styles self-contained rather than introducing a shared demo styling system or naming every literal. - Expand populated CSS objects across multiple lines throughout UI documentation: live examples, Anatomy and short inline wiring or motion snippets. Give selectors, media queries, `@starting-style` and other nested rules their own visibly indented blocks, even for one declaration. Put a newline after each populated CSS object’s opening brace so formatting preserves the structure, and inspect the highlighted output too. Empty Anatomy rules can remain `{}`. - Prefer multiline object literals inside JSX expressions, including mixin options, inline style values and objects passed from JSX callbacks. Put each property on its own line, even for a single-property object, so `mix` props and nested calls read vertically. Apply this to live examples and inline documentation snippets. Empty objects may remain `{}`. Pass an existing object directly when it already satisfies the API; avoid spread-only wrappers such as `{ ...spring('snappy') }` unless a copy is needed. Keep spreads when combining or overriding options. If a spread-only copy is necessary, keep it inline rather than expanding it. - Make live-example styling self-contained. Supply the resets and inherited typography the example needs rather than relying on docs-site styles. Remove redundant, contradictory and unused declarations, and preserve native hiding when adding display rules. Use inline styles for continuously changing geometry rather than generating CSS for every animation frame. - Capture owned DOM nodes with refs instead of document queries or tree traversal. Scope IDs and native radio-group names to the component instance, and clean up animation frames and observers when the instance is removed. - Keep authored snippets syntactically valid even when they omit surrounding setup. Group adjacent JSX elements in a fragment and separate statements from JSX unambiguously. Formatting fallback is for unexpected failures, not normal rendering. Fix warning-producing snippets rather than suppressing warnings across tests or builds. - Use descriptive callback names. Reserve names such as `nextValue` for state changes. Name an API ref for the API it receives. - Use US English and concise feature-focused prose. Prefer short, focused sentences. Avoid using semicolons, colons or em dashes to cram additional clauses into documentation prose and demo copy. Split overloaded sentences rather than substituting punctuation. This is a sentence construction preference, not a ban on punctuation in ranges such as 2–4 business days, compound words, code or technical notation. Avoid redundant example subheadings. - Organize references by public part. Use the shared reference component across pattern and animation pages so presentation improvements apply consistently. An initial pilot should be followed by an audit of every relevant page, including older table helpers. APIs without options, fields or decorated attributes can use concise prose. Use compact expandable rows for dense props, options and exported types, keeping names, types, defaults and required status scannable. Reveal full signatures, precise descriptions and type definitions on expansion. Keep links inside the expanded content rather than nesting navigation within disclosure controls. Make type links reveal their target even when it is collapsed, and keep keyboard operation available without client JavaScript when native elements suffice. Apply the same expandable reference treatment to attributes and parameters as to props, options and state, including parts that take no options but decorate elements. Lay out expanded descriptions, full types, defaults and definitions in a borderless table with labels on the left and details on the right. Use a restrained color or weight difference to distinguish labels from values, and spacing rather than internal rules. Review the longest API names and signatures at desktop and narrow widths. Keep identifiers intact where possible, wrap full signatures and use bounded horizontal scrolling only when table columns cannot remain readable. Give expanded content its own padding below the interactive row so a hover or pressed background does not crowd the description. - Keep page navigation derived from the authored section and API-part headings rather than a second manual list. Offer stable links to individual API entries without filling the outline with every field. Direct links must reveal collapsed targets and leave the relevant heading or disclosure control below sticky navigation. Check fresh navigation, reloads and mobile outline dismissal as separate interactions. - Treat related examples as a visual family. Keep equivalent controls consistent in typography, spacing, shape, colors and interaction feedback unless a variation is explicitly demonstrating a different treatment. After changing a shared visual pattern in one demo, review the hero and sibling examples together and propagate the decision where it applies. Preserve intentional state distinctions and the hierarchy of supporting text. Review related states together in the same composition when they can coexist. A disabled-tabs example should retain an enabled inactive tab alongside the active and disabled tabs so their appearance and behavior can be compared directly. Check disabled controls against enabled but inactive peers. Verify the rendered colors and interaction feedback after styling refactors; a disabled selector in source can still be overridden by a reset or another rule. They should look unavailable at a glance, not merely unselected. Mute the unavailable control label without dimming its explanation into unreadability; visual consistency does not mean identical treatment across different states. - Use a restrained monochrome palette for demos, including Toggle. For switches, keep thumb geometry and treatment stable across states, using thumb position and a restrained change in track tone to distinguish on and off. Check thumb contrast on both tracks in light and dark themes; avoid unnecessary color inversion that makes the transition feel harsher or changes the thumb’s apparent size. Distinguish selection, keyboard highlight, hover, focus, disabled state and transient feedback through sufficient tonal contrast, indicators and outlines rather than hue alone. Align headings, group labels and item text to a deliberate shared edge; account for the padding inside interactive rows instead of aligning only their outer boxes. Check both themes and selected-plus-highlighted states. - Match the shared docs theme. Polish spacing, typography, focus indicators, motion and touch targets without adding a miniature app shell. Keep surface contrast restrained and use a clear primary selection treatment; stacking contrasting headers, active fills and indicators can create unnecessary bands instead of a cohesive control. Preserve readable distinctions between active, inactive and disabled states. Keep documentation prose selectors from reaching into live examples. Compare equivalent markup in the hero and later sections, where ancestor selectors can otherwise override the example’s own spacing, typography or colors. - Balance space around the visible interaction and within its surfaces. Use consistent preview padding and let content determine height. Fixed minimum heights can add uneven amounts of space across examples even when their padding matches. Avoid arbitrary panel heights that leave excess space on one side, and reserve space within an example only when its interaction needs it for stability. Integrate structural controls with the surface they govern, such as tabs forming a panel’s header, rather than nesting floating controls inside another padded card. Check initial and changed states at wide and narrow widths across sibling examples. - Keep toolbars stable while content expands. Review both endpoints and the transition for unintended changes in control size, icon position, text wrapping and surrounding layout. Changing labels can move an animated icon even when the button width stays fixed. Prefer stable labels and state indicators, or reserve space for variable content when the changing label is useful. Keep hit areas and animation anchors stable unless their layout change is the documented feature. Make first and repeated interactions animate correctly, avoid content distortion and respect reduced motion. - Check floating examples against the surrounding site's navigation and overlays, including mobile navigation while the example is visible. Choose ordinary stacking or the browser's top layer deliberately. Decorative readouts should not cover unrelated navigation just because a native popover makes positioning convenient. - Show supported motion in the canonical example where it improves the interaction. Look for familiar motion that explains continuity, state changes or spatial relationships, such as a moving tab indicator or a restrained floating-surface entrance. Weigh that benefit against the extra example code; keep text, keyboard highlights and pointer tracking immediate when motion would reduce clarity or precision. Prefer short, interruptible movement without decorative bounce, and preserve reduced-motion behavior. Apply equivalent motion consistently across sibling examples. Give animation examples one clear focal point, with minimal framing and an obvious trigger. Avoid separate Animate and Reset controls when one repeatable action makes sense. - Disable browser autocomplete on editable demo fields, including text, search, email, password and textarea controls, so repeated experimentation does not accumulate unrelated suggestions. Use `autocomplete="off"` on fields or their form, and verify defaults supplied by primitive mixins before adding redundant options. Keep intended library suggestions such as Combobox filtering enabled. Form examples should also opt out at the form level. - Decorative previews must be inert and hidden from assistive technology. Interactive examples must remain accessible. Do not rely on right-click-only triggers. - Match cursor treatment to the control's established interaction conventions. Keep the ordinary arrow cursor for menu items, including disabled items; muted styling and blocked activation convey their availability. Where disabled controls use `cursor: 'not-allowed'`, apply it consistently to their associated clickable label area. Preserve distinct read-only styling rather than treating read-only controls as disabled. ## Verify the result Review complete interaction sequences, not only isolated actions. Selection should still be valid after closing, blurring and submitting. Check that aliases or custom labels remain compatible with later validation, and distinguish internal state, visible text and submitted values. Verify native behaviors such as form reset instead of assuming that using a native input integrates the primitive with them. Keep live-example tests focused on the behavior each example teaches. For each test, identify a plausible regression and temporarily introduce it to verify that the test fails for the expected reason, then restore the source. A companion filename or successful render is not enough. Assert the intended visible outcome as well as relevant state, focus or form behavior. Programmatic clicks can activate hidden elements, and unrelated transitions can satisfy broad animation checks. Keep assertions specific to the element and behavior being taught. Use a small docs-site smoke test for shared hydration and real browser interaction rather than duplicating every example as an end-to-end test. Keep exhaustive primitive coverage in the library tests. Update affected tests whenever making changes, including assertions about removed content, links and changed layout behavior. Search existing tests for the old contract before treating a small presentation change as complete. Run the full UI docs test suite, typecheck and formatting checks as part of completing the changes. If anything changes after validation, rerun the affected checks. Do not rely on a successful run from an earlier iteration. Use the browser to inspect changed interactions, including their first use, keyboard access, dismissal, repeated use and a narrow viewport. Check light and dark presentation when styling changes. Review both the preview and displayed source. Report API differences or implementation bugs separately from example design problems. Do not silently change primitive behavior while documenting it. Flag remaining questionable examples with a concrete recommendation, rather than treating an attractive preview or passing checks as proof of good UX.