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.