write-ui-module-readme

name	write-ui-module-readme
description	Write concise module README files for `packages/ui/src/lib/*` primitives. Use when drafting or revising README docs for UI package modules like popover, press, or other first-party UI helpers, especially when the main goal is agent-friendly usage guidance and a short explanation of each exported value.

Write UI Module Readme

Overview

Write module README files for packages/ui/src/lib/* as practical usage guides for agents and developers.

Optimize for fast, correct adoption:

• show the canonical usage first
• explain each exported module.* value briefly
• document the important behavior guarantees
• avoid implementation-history dumps and internal type walkthroughs

These are module docs for UI primitives, not package-level READMEs.

Workflow

1. Read the module source first.

• Identify the actual public exports and their roles.
• Confirm the behavior from code, not memory.

2. Read nearby tests and demos.

• Pull behavior notes from tests.
• Reuse the most realistic example shape from a demo when available.

3. Document the module as it exists today.

• Do not describe planned APIs.
• Do not document internal coordinators, private state, or workaround history unless they are part of the public contract.

4. Keep the README short and scannable.

• Prefer short paragraphs and flat bullets.
• Use one strong canonical example instead of multiple weak snippets.

Recommended Structure

Use this structure unless the module needs something more specific:

1. # ModuleName
2. One or two sentences: what it is, what it is for, and what it is not for
3. ## Usage
4. ## \module.*`` or equivalent export reference
5. ## Behavior Notes
6. ## When To Use Something Else when the primitive sits below higher-level widgets

Usage Section

Lead with a copy-pasteable example that shows the real shape of usage.

• Prefer production-shaped UI over toy snippets.
• Use the actual exported API names.
• Show the minimum surrounding structure needed to use the primitive correctly.
• If the module composes with other first-party UI helpers, show that composition.

For popup-style primitives, the example should usually show:

• trigger
• surface/root
• one or two meaningful controls inside
• dismissal or completion path

Export Reference

After the example, explain the role of each important exported value in a few lines each.

For example:

• module.context: what shared coordination it provides
• module.button(...): what it registers or activates
• module.surface(): what it turns the host into
• module.dismiss(): how it closes or finalizes
• module.change: what event it emits and the useful event fields

Keep this section focused on:

• what it does
• where to apply it
• key arguments or options
• observable behavior

Do not turn this into a full API dump.

Behavior Notes

Document the behaviors that matter when composing with the primitive:

• focus movement
• dismissal rules
• anchoring rules
• keyboard behavior
• multi-trigger behavior
• any important guarantees tested in the module suite

This section should save a reader from opening the implementation just to answer “what happens when...?”

Scope Rules

• Treat the primary audience as an agent or developer trying to use the primitive correctly.
• Prefer usage guidance over architecture explanation.
• Name public events and useful event fields, but avoid deep event-class internals unless necessary.
• Do not document private classes, internal coordinators, or helper mixins unless the README is specifically for that helper.
• Do not pad the README with generic accessibility or popover theory the agent already knows.

Good Patterns

• “Use popover directly for custom floating panels like filters or view options.”
• “Wrap triggers and the surface in popover.context.”
• “The opener that started the current session controls anchoring and focus return.”
• “Do not use this as the final consumer-facing primitive for menus or comboboxes.”

Checklist

• Did you read the module source first?
• Did you confirm behavior from tests or demos?
• Does the README start with a realistic usage example?
• Does it explain each important exported value briefly?
• Does it include behavior notes that matter in practice?
• Does it avoid internal implementation detail and historical debugging context?
• Would an agent know how to use the primitive correctly without opening the source?