# API Stability — TVU Design System

> **Status**: v0.6.0 published; this document defines what becomes part of the **v1.0 stable surface** and what is explicitly excluded.
>
> Once **v1.0.0** is tagged, the surfaces below are covered by a stability promise: removals or breaking changes require a deprecation cycle of **≥ 1 minor** (e.g. v1.x.0 deprecates → v2.0.0 removes).
>
> Pre-v1.0 (0.x.y) does **not** carry this promise — minor bumps may include breaking changes per `0.x` semver convention.

## Public API surface (v1-stable)

### 1. npm package barrel (`@nancyzeng0210/tvu-design-system`)

All named exports from the top-level barrel are public. Current barrel exports the canonical components only — `src/canonical/*` shapes are the contract:

- `Button` (8-axis canonical API: `canonicalStyle` / `canonicalColor` / `canonicalRadius` / `canonicalFixedWidth` / `canonicalStatus` / `canonicalIcon` / `canonicalSize` / `canonicalTheme`)
- `Input` / `InputBoxLine` / `InputBoxFilled` / `InputNumber`
- `Select` / `SelectBoxLine` / `SelectBoxFilled`
- `Checkbox` / `Radio` / `Switch`
- `FormItem`
- `Notification` / `PromptMessage` / `Tooltip` / `PopupBox`
- `Pagination` / `Table`
- `Chart` (4 types: pie / donut / line / bar)
- `Progress` / `Slider` / `Rating`
- `Tabs` / `Steps` / `Breadcrumb`
- `Icon` (and icon registry)
- `Badge`

### 2. Subpath exports

- `./style.css` — global stylesheet
- `./icons/manifest.json` — icon registry catalog
- `./icons/esm` + `./icons/esm/*` — icon ESM components
- `./icons/svg/*` — raw SVG assets
- `./eslint-plugin` + `./eslint-plugin/*` — ESLint 9 flat-config plugin (4 rules: `no-hardcoded-color` / `no-inline-svg` / `icon-from-dist` / `no-base-component-import`)

### 3. Design tokens (`./style.css` injects)

All `--*` CSS custom properties listed in `src/tokens/variables.css` are v1-stable. New tokens may be added in any minor; renames or deletions require deprecation cycle.

### 4. Type exports

All TypeScript types exported alongside their components — including `CanonicalColor`, `CanonicalStyle`, `CanonicalSize`, etc. for Button — are v1-stable.

## Internal / not v1-stable

These exist in the source tree but are **not** part of the v1.0 contract:

- `src/components/*` (base implementation layer) — **internal only**. Consumers MUST use the top-level barrel, not deep paths into `src/components/*` or `dist/components/*`. (AGENTS.md 硬规则 #6 + `eslint-plugin/rules/no-base-component-import`.)
- `figma-sync/*` scripts — development tooling, not shipped to consumers.
- `scripts/*.mjs` audit scripts (`audit-mockup-*`, `audit-product-code`, `audit-status-consistency`, `audit-scripts-stdlib-stability`) — these run via `pnpm` scripts inside this repo; not exposed as a consumer API.
- `playground/*` — internal docs site for this repo only.
- Anything marked `@internal` in JSDoc.

## Promise scope

The v1.0 stability promise covers:

1. **Component prop names + types** — adding optional props is OK; removing or renaming requires deprecation cycle.
2. **Component slot names + scope** — adding optional named slots is OK; removing or renaming requires deprecation cycle.
3. **Component emit signatures** — additions OK; signature changes require deprecation cycle.
4. **CSS custom property names** — additions OK; removals/renames require deprecation cycle.
5. **Public class names** documented in component CSS (e.g. `.btn`, `.tvu-input`, `.switch`) — additions OK; removals/renames require deprecation cycle.
6. **Icon registry keys** — additions OK; removals require deprecation cycle.
7. **Subpath exports** — additions OK; removals require deprecation cycle.

The v1.0 stability promise does **not** cover:

- Internal implementation details: which Vue version, which Chart.js version, which build tool, etc.
- Pixel-level visual rendering (covered separately by visual regression baselines).
- Internal CSS variable values (only the names are stable; values may shift to fix a11y / contrast issues without major version bump).
- Pre-release / experimental components flagged `@experimental` (none in v0.6.0; reserve right to add in future minors).

## Deprecation protocol post-v1.0

When a v1-stable API needs removal:

1. Mark `@deprecated since X.Y.0` in source + emit dev-mode warning if feasible.
2. Document the migration path in CHANGELOG.md.
3. Wait at least 1 minor version before removal.
4. Removal requires **major** version bump (v2.0.0).

Pre-v1.0 path retained for 0.x: minor (0.x.0) may include breaking changes (currently used to evolve API rapidly).

---

## Current deprecations awaiting cleanup

None as of v0.6.0. Button legacy props (variant/size/disabled/loading) deprecated v0.5.0, removed v0.6.0.