Proposal process

When to write a proposal

Change	Needed
New component	Proposal (RFC)
Breaking change to an existing component (removing or renaming a prop, changing behaviour)	Proposal (RFC)
New variant on an existing axis, used on at least two screens	Variant record: first use, screens, Figma link, approver (REUSE-03)
New token or token rename	Changeset; a migration note for a rename
Architecture, package boundary, dependency or rule change	Decision record (ADR)
Bug fix, docs fix	Not needed

A new file under packages/ui/src without a proposal is rejected in review (REUSE-08).

Steps

1. Search. Look for a similar component on the Components overview and in Storybook. Write the search words you used and the step of the decision flow you reached into the proposal (REUSE-06).
2. Check the name. The proposed name must not repeat the root of an existing component or carry one of the banned affixes; see Naming.
3. Write the proposal. Fill in the template below. The proposed interface is detailed enough for the person writing the code to start without asking further questions.
4. Review. A designer, a developer and the accessibility owner read the proposal. Questions are answered on the proposal.
5. Decision. The proposal closes as accepted, accepted with changes or rejected; the reason is written into it. No code is written before it is accepted.
6. Implementation. An accepted proposal is built in one change, following the Component checklist.

Proposal template (RFC)

rfc-0000-component-name.md

# RFC: <Component name>

- Status: draft | in review | accepted | rejected
- Author:
- Date:

## Problem
Which user needs what while doing which task? How is it solved today?

## Screens that will use it
At least two screens, with Figma links.

## Search and decision flow
Search words used, components reviewed, the step of the decision flow reached.

## Proposed interface
Props (name, type, default, description), parts (`data-part`), states and variants.

## Behaviour and motion
Interaction states, keyboard, motion presets to use, reduced-motion behaviour.

## Accessibility
Role, accessible name, keyboard table, focus management, screen reader output, related WCAG 2.2 criteria.

## Tokens
Semantic tokens to use; new component tokens if needed.

## Strings
The library's own strings (`ui.*`), in Turkish and English.

## Alternatives considered
At least two alternatives and why they were not chosen.

Decision record template (ADR)

Every decision that changes the architecture, package boundaries, dependencies or a rule is written down as a decision record. Records are kept in the repository under docs/adr/ and are not changed afterwards; if a decision changes, a new record supersedes the old one and links to it.

0000-decision-title.md

# ADR 0000: <Decision title>

- Status: proposed | accepted | superseded (ADR xxxx)
- Date:

## Context
The situation and constraints that call for a decision.

## Options
At least three options, with the criteria each is assessed against.

## Decision
The option chosen and why.

## Consequences
What becomes easier and harder, the way back, follow-up work.