Describe the task and the observed limitation. Record the source revision, props, browser, and steps needed to reproduce it. Decide whether the behavior belongs to the component or to the consuming application. For example, a button can suppress activation while loading, but the application decides when a network operation has completed.

Read the component's specification, source, tests, and public stories. Compare installed behavior with upstream before treating an upstream change as available to consumers. Use Apple guidance for design intent and web semantics for the browser contract.

Write down the proposed props, defaults, callbacks, state ownership, keyboard behavior, and compatibility effect. Follow docs/api-conventions.md in the current library checkout. Keep private reference material out of public documentation.

Add a failing test that expresses the intended behavior before changing component code, following the repository's test-first policy. Update the implementation and the relevant stories, specification, and documentation together. Use the owning scripts for generated artifacts; do not hand-edit their output.

Use the component checklist to review semantics, state, presentation, and consumer integration. Run the checks listed in Contributing overview.

For visual changes, inspect actual components in both themes and the required browsers. A source test or successful build alone cannot establish that focus, clipping, and translucent surfaces work in the rendered interface.

Describe the user-visible result, changed contracts, source evidence, and verification. List unresolved issues and unavailable checks. Keep a compatibility note for changed exports, defaults, callback order, or rendered semantics.

A merged source change, a built artifact, a website update, and a public package release are separate events. Verify the consumer artifact before describing a new feature as installed or published.