# Component development workflow

Use this workflow when adding a component or updating an existing component in `@eleventheye/asui`. Read [AGENTS.md](../AGENTS.md) and the relevant component guides before implementation.

## Shared expectations

- Inspect comparable components, public types, styles, stories, and tests before choosing an implementation. Follow existing naming, file layout, formatting, arrow-function syntax, shared size constants, and public export patterns.
- Keep ASUI a reusable React/TypeScript UI library. Application business rules, project branding, routing decisions, and resource loading belong to consumers unless an established component contract says otherwise.
- Discuss proposed behavior with Andrey before implementing anything that does not fit ASUI's purpose, conflicts with established patterns, changes a public contract, or requires a broad refactor. Explain the mismatch and suggest an approach that fits. Present the plan before substantial component changes.
- Keep changes scoped and preserve unrelated work. Inspect the current branch and working tree before editing. Use `<ticket-number>-<branch-description>` for ticket branches, with a short lowercase, hyphen-separated description, such as `94-donut-theme-migration`. Confirm the intended ticket or branch when unclear; do not invent a ticket or switch branches underneath pending work.

## Adding a new component

1. Establish the component's responsibility, public API, defaults, state ownership, accessibility behavior, and consumer responsibilities. Check whether an existing component can already satisfy the need.
2. Use the closest established component as a structural reference. Implement source, prop types, styles, and any necessary helpers under `src/`; expose the intended public component and types through `src/index.ts` following nearby exports.
3. Integrate with ASUI's existing theme resolution and semantic slots. Follow the theme requirements below for any additions.
4. Add Storybook examples following neighboring stories, covering ordinary usage and meaningful states, sizes, accessibility, and theme customization. Add focused tests for behavior and contracts that need regression protection.
5. Create a consumer guide in `docs/` using the documentation requirements below, and link it from `README.md`.
6. Complete the relevant validation and review handoff below.

## Updating an existing component

1. Read its implementation, types, styles, consumer guide, stories, tests, and any applicable `.github/instructions/*.instructions.md` file. Trace shared helpers and affected consumers before changing their contracts.
2. Preserve existing public behavior and defaults unless a change is intentional and discussed. Pay particular attention to controlled/uncontrolled state, callbacks, refs, DOM semantics, keyboard interaction, theme precedence, and portal descendants where applicable.
3. Follow surrounding patterns and make the smallest coherent change. Update stories and regression coverage to demonstrate changed behavior and protect relevant existing behavior.
4. Update the component's existing guide in `docs/` in the same change. If none exists, create one; do not create a duplicate guide for each modification. Ensure `README.md` links to the guide. Update any affected prop JSDoc, theme reference, and component instructions.
5. Complete the relevant validation and review handoff below.

## Component documentation

Every new or modified component must have an up-to-date consumer guide in `docs/`, linked from `README.md`. Match the structure and level of detail of existing guides such as [ASChoiceBar](./choicebar.md) and [ASSwitch](./switch.md). Use readable Markdown, fenced TSX examples, and prop tables where useful.

Cover the following where applicable:

- Purpose, supported functionality, and responsibilities left to the consumer.
- A practical usage example using the public API.
- Relevant props, defaults, supported values, callbacks, and refs.
- State ownership, interactions, and important edge cases.
- Accessibility semantics, accessible naming, keyboard behavior, focus, and reduced motion.
- Theme customization, precedence, and a link to the component's section in the [theme property reference](./theme-reference.md).
- Public limitations and compatibility or migration guidance when behavior changes.

### README catalogue format

Keep each public component entry under `Available components` in README.md consistent:

1. A level-three heading with the public component name and a `Reference` link to its guide (or current source API reference when a guide is not yet available).
2. A horizontal rule, followed by a short description of purpose and supported modes.
3. An `Example` label and a concise TSX example using public imports and named application handlers.

Keep full prop definitions, defaults, and detailed behavior in the linked reference instead of copying interfaces into the README. Keep modes such as ASTextField multiline under their owning component. Give separate components separate entries; list factories under the utility section. When adding a component, add its catalogue entry and guide link in the same change.

Describe the current component API. Keep implementation progress, ticket checklists, and validation results in tickets and PR descriptions. Put deeper implementation rationale in a linked developer document when needed.

### Theme reference section format

Use the same structure for every component section in `docs/theme-reference.md`:

1. A level-two heading naming the public component and its style interface, explicitly marked `@interface`. Link the interface name to its source declaration. Use the actual declaration name, even when it differs from the component name.
2. A configuration sentence naming the exact `components.*` path and the APIs that accept it.
3. A brief description of the styled surface and relevant precedence or shared behavior.
4. A property table with `Property`, `Description`, `Classic default`, and `Neutral default` columns. Keep meanings separate from values; cover supported size/state variants and verify defaults against recipes.
5. Relevant exceptions and links to the component's consumer guide.

```markdown
## ASChartDonut — @interface [`ASChartDonutStyles`](../src/astheme/ASTheme.types.ts#L628)

Configure these properties under `components.chartdonut` in
`createASTheme`, `extendASTheme`, or `themeOverrides`.

ASChartDonut shares these styles across its one to four rings.

| Property | Description | Classic default | Neutral default |
| --- | --- | --- | --- |
```

Verify the source line when adding or moving an interface; the example's line number is illustrative. Shared style interfaces name all public components they configure, such as `ASChartHBar and ASChartVBar — @interface ASChartBarStyles`. For tokens, use `Theme tokens — @interface ASThemeTokens` and the configuration path `tokens`.

Preserve existing section anchors when renaming headings, or update their inbound links. Place complete-theme compatibility notes after all component sections and `Maintaining this reference` at the end. Source types, current consumer guides, and the theme reference must describe the same API.

## Theme additions and changes

Read [Applying an ASUI theme](./theme-provider.md), [Project themes](./phase2-contract.md), and the [theme update strategy](./theme-update-strategy.md) before changing theme APIs.

- Reuse existing semantic tokens and component slots where they express the right meaning. Discuss additions that would couple ASUI to a specific application or visual implementation.
- Follow the existing theme types, factory recipes, preset defaults, resolver, and compatibility patterns. Preserve provider inheritance, explicit theme precedence, and the default ASUI appearance unless an intentional change is agreed.
- Give every new theme property source JSDoc matching neighboring properties. Explain what it controls, its value type or CSS meaning, and relevant state, size, fallback, or precedence behavior. Do not leave new properties undocumented.
- Add every new property to `docs/theme-reference.md` using its existing format: meaning, actual classic and neutral defaults, and all supported size/state variants where applicable. Verify values against the implementation rather than guessing.
- Update the component guide with the customization behavior and an example. Keep public types, source comments, theme reference, and Storybook descriptions consistent; update shared theme contract docs if the contract changes.
- Verify relevant preset, inheritance, override, and legacy compatibility paths. Theme changes must work beyond a single custom example.

## Validation and review handoff

- Run `npm run typescript:check` after TypeScript or TSX changes.
- Run focused existing tests for affected behavior; use `npm run test:theme` for theme changes. Add regression coverage when it meaningfully protects a changed contract.
- Check relevant rendering and interactions in Storybook for visual or behavioral changes. For story typing when useful, run `npx tsc -p src/stories/tsconfig.json --noEmit --pretty false`. Keep Storybook outside the production build boundary.
- Check documentation links and run `git diff --check`. Documentation-only changes do not need a production build or new tests.
- Report what changed, validation performed, and any remaining limitations. Do not claim checks or visual review that were not performed.

## Commits, pull requests, and tracking tickets

Follow [Commit syntax and release workflow](./commit-syntax.md).

- Wait until Andrey finishes reviewing and explicitly indicates readiness before the initial commit. A request to implement work or discuss the workflow is not approval to commit it.
- Before committing, verify the target branch, stage the intended files explicitly, and inspect the staged diff. Use `<type>: <ticket number> <description>` for the subject.
- Write the initial commit body in Markdown suitable for reuse as the PR description. Explain the concrete problem and resulting behavior, relevant API/theme/documentation changes, validation actually performed, and any compatibility limitations. Scale detail to the change; do not include conversational history.
- Report the commit hash and a short summary. Leave pushing, PR creation, review requests, merging, and publishing to Andrey unless explicitly delegated. Never push without an explicit request.
- If an overarching ticket tracks the implementation, update that ticket with completed work and keep its checklist current. Link each completed item to its actual PR. Mark an item resolved only once the PR is merged or its completion is otherwise confirmed; distinguish implemented, awaiting review, and resolved work. Do not close the overarching ticket while tracked work remains.
- When the completed PR is not yet available, include the remaining ticket-update step in the handoff. Once the completed PR is available, verify its scope and update the matching items with the PR link. If ticket access is unavailable, provide the exact proposed update and explain the blocker. Never invent a PR link or mark pending work resolved.