Editing Openai/695d28c7-94c8-8006-836b-96dbe559b5eb (section)

==== UI Library Compatibility Policy (Contract) ====

<syntaxhighlight lang="md"># UI Library Compatibility Policy (Contract)

Applies to: @org/ui (and any sibling packages like @org/ui-tokens)

Goal: Component teams can ship improvements without forcing full-product regression testing,
while consumer teams can upgrade on their schedule with predictable risk.

==== 1) What is Public API vs Private ====

===== Public API =====
Only these are considered supported and stable:
* Package entrypoints exported from:
* <code>@org/ui</code> (root)
'' <code>@org/ui/<subpath></code> ''only if explicitly listed in <code>package.json#exports</code>*
* Types re-exported from public entrypoints.
* CSS variables / design tokens explicitly documented in @org/ui-tokens.
* Storybook stories are the canonical behavioral + visual examples for public components.

===== Private API (NO consumer dependencies) =====
Consumers must NOT import:
* deep paths like <code>@org/ui/src/...</code> or <code>@org/ui/components/...</code>
* any file not reachable via <code>package.json#exports</code>
* internal DOM structure (e.g., <code>.kebab > div:nth-child(2)</code> selectors)
* internal class names (unless explicitly documented as stable)
* test ids unless explicitly documented as stable (prefer role/label-based selectors)

Breaking this rule means the consumer owns the breakage risk.

==== 2) Semantic Versioning Rules ====

We use SemVer for @org/ui:

===== Patch (x.y.Z) =====
* bug fixes that do not change intended behavior
* performance improvements
* internal refactors
* docs/story fixes
* a11y improvements that do not change visual layout materially

===== Minor (x.Y.z) =====
* new components
* new optional props with safe defaults
* new variants/slots that do not change existing default rendering
* additive token additions

===== Major (X.y.z) =====
Any change that can reasonably break consumers or change user-visible behavior by default:
* removing or renaming exports, components, props, events
* changing default prop values in a user-visible way
* changing DOM in a way that breaks common integration (e.g., removes an element
  frequently targeted by consumer CSS) unless explicitly declared private
* significant visual change outside defined tolerances
* token changes that alter appearance beyond tolerances

==== 3) Definition of “Breaking” (Practical) ====

A change is breaking if it causes any of these:
* TypeScript compile errors for consumers
* runtime errors for consumers
* layout/visual regressions outside approved tolerances
* behavioral regressions (click, focus, keyboard nav, validation)
* a11y regressions (color contrast, missing labels, keyboard trap, etc.)

If in doubt, treat as breaking (major) or provide a compatibility path.

==== 4) Compatibility Paths (Preferred over Majors) ====

Before a major, prefer:
* keep old prop, introduce new prop; deprecate old prop
* support both old and new values for a release window
* adapter/wrapper exports (temporary) to keep old behavior
* codemod + migration guide

==== 5) Deprecation Policy ====
* Deprecated APIs remain supported for at least:
* 2 minor releases OR 60 days (whichever is longer) within the same major.
* Deprecated APIs must include:
* JSDoc <code>@deprecated</code> with the replacement
* a migration note in CHANGELOG
* We support at most the last 2 majors at any time.
* Older majors receive only critical security/a11y fixes, then are removed on schedule.

==== 6) Consumer Upgrade Policy ====
* Consumers pin versions (no auto-floating to new majors).
* Upgrades happen via explicit dependency bump PRs.
* Any component library major upgrade requires consumer-side validation.
* Patch/minor upgrades should be safe by default; validation can be localized.

==== 7) Required Evidence for Changes ====

Every change to public components must include at least one:
* updated Storybook story (new/changed behavior)
* unit/integration test (Testing Library / Playwright component test)
* visual regression approval (if visuals changed)

==== 8) Ownership ====

Each component has an owner group responsible for:
* reviewing breaking changes
* maintaining deprecations/migrations
* ensuring test coverage is adequate

</syntaxhighlight>