/component-api-validator

name: component-api-validator
description: "Audit component APIs for consistency, breaking changes, TypeScript coverage, and contract compliance across a component library. Trigger when someone says: component prop review, verify component types are exported, component API audit, check our component interfaces, are our props consistent, API consistency check, prop naming review, breaking change detection, or anything about checking whether component APIs are structurally sound and consistent across the library."
references:
  - ../../knowledge-notes/design-to-code-contract.md
  - ../../knowledge-notes/component-governance.md

Component API validator

A skill for auditing the public API surface of a component library — prop naming consistency, type coverage, default value patterns, breaking change detection, and alignment with the design-to-code contract. Treats the component API as infrastructure: the public contract that consuming teams depend on.

Context

A component library's most important output is not its visual rendering — it is its API. The props, types, defaults, and composition patterns form a contract with every consuming team. When that contract is inconsistent (some components use `variant`, others use `type`, others use `appearance` for the same concept), unclear (prop types are `any` or undocumented), or unstable (breaking changes ship without versioning), consuming teams lose trust. And when trust erodes, teams start wrapping system components in local abstractions, which is the beginning of drift.

API validation is not about enforcing a single naming convention. It is about detecting where the library's public surface is working against the teams consuming it. A library where every component follows the same patterns for sizing, variants, event handlers, and composition is a library that teams can learn once and apply everywhere. A library where each component invents its own conventions is a library that requires re-learning for every component.

This skill evaluates the API surface as a whole — not one component at a time, but the patterns that emerge across the library. Individual component reviews are useful but miss the cross-library inconsistencies that frustrate consumers most.

---

Configuration

Check for `.ds-ops-config.yml` in the project root. If present, load:

• `system.framework` — React, Vue, Web Components, Svelte, Angular, etc. (determines prop extraction method)
• `system.styling` — CSS Modules, Styled Components, Tailwind, Emotion, etc.
• `severity.api_*` — overrides for API finding severity
• `integrations.github` — if enabled, pull component source directly from the repo
• `integrations.storybook` — if enabled, extract prop metadata from Storybook's component analysis

Auto-pull integrations

**GitHub** (`integrations.github.enabled: true`):

• Pull component source files from the configured repository
• Identify the last change date and recent PRs for each component to assess API stability

**Storybook** (`integrations.storybook.enabled: true`):

• Extract argTypes metadata for structured prop information
• Cross-reference Storybook's prop documentation with source code types

**Figma** (`integrations.figma.enabled: true`):

• Pull component property definitions from Figma
• Cross-reference Figma properties against code props for design-to-code alignment

If an integration fails, log it and proceed with manual input.

---

Step 1: Gather component sources

Ask for or confirm:

1. **Component source path** — directory containing component files (e.g., `src/components/`) 2. **Framework** — React (TSX/JSX), Vue (SFC), Web Components, Svelte, Angular, or other 3. **TypeScript usage** — full TypeScript, JSDoc types, PropTypes, or untyped 4. **Current version** — the published version of the library (for breaking change context) 5. **Previous version source** (optional) — for breaking change comparison. Can be: a git tag, a previous release branch, or the npm-published version

Step 2: Extract API surface

For each component in the source path:

1. **Identify exported components** — components that are part of the public API (exported from index files or package entry points) 2. **Extract props/attributes**:

• **React:** TypeScript interfaces, PropTypes, or JSDoc annotations
• **Vue:** defineProps, props option, or TypeScript interfaces
• **Web Components:** observed attributes, properties, events, slots, CSS custom properties
• **Svelte:** exported let declarations, events, slots

3. **For each prop, capture:**

• Name
• Type (specific type or `any`/`unknown`/untyped)
• Required or optional
• Default value (if any)
• Description (from JSDoc, TSDoc, or inline comment)

4. **Identify composition patterns:**

• Does the component accept `children`/`slots`?
• Does it forward refs?
• Does it spread remaining props to a root element?
• Does it accept render props or scoped slots?

Step 3: Assess cross-library consistency

This is the core of the skill. Evaluate patterns across the entire library, not within individual components.

3a. Prop naming consistency

Look for the same concept implemented with different names across components:

| Concept | Consistent pattern | Inconsistent examples | |---------|-------------------|----------------------| | Visual variant | All use `variant` | Some use `variant`, others `type`, others `appearance`, others `kind` | | Size | All use `size` | Some use `size`, others `scale`, others `dimension` | | Disabled state | All use `disabled` | Some use `disabled`, others `isDisabled` | | Loading state | All use `loading` | Some use `loading`, others `isLoading`, others `pending` | | Event handlers | All use `onAction` | Some use `onChange`, others `handleChange`, others `onValueChange` | | Colour/intent | All use `intent` | Some use `intent`, others `color`, others `severity`, others `status` |

For each inconsistency, report:

• The concept
• Which convention is mo