/component-api-validator

name: component-api-validator
description: "Audit prop APIs across a component library: naming consistency, boolean/default patterns, type coverage, exported types, breaking changes between versions. Trigger: component API audit, are our props consistent, prop naming review. For semver calls use version-bump-advisor."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(find:*), Bash(head:*), Bash(ls:*), Bash(sort:*), Bash(tail:*), Bash(wc:*), Bash(npm pack:*), Bash(npx react-docgen-typescript:*), Bash(npx custom-elements-manifest:*), Bash(npx vue-component-meta:*)
references:
  - ../../knowledge-notes/design-to-code-contract.md
  - ../../knowledge-notes/component-governance.md
  - ../../knowledge-notes/output-discipline.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.

Before you begin: verify references

Confirm that every path in this skill's frontmatter `references:` exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example `npx skills install`) dropped the repo-root `knowledge-notes/` directory. Tell the user to reinstall by a method in `1-INSTALL.md` and run `verify-install.sh` from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

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.

**Do NOT use this skill for:** deciding the semver bump for a release (use version-bump-advisor) or checking one component against its design spec (use design-to-code-check).

---

Configuration

If `.ds-ops-config.yml` exists, follow the configuration-and-recurring knowledge note (`../../knowledge-notes/configuration-and-recurring.md`) for loading, integration fallbacks and recurring runs. This skill reads:

• `system.framework` — determines the prop extraction method
• `system.styling` — styling approach
• `severity.api_*` — overrides for API finding severity
• `integrations.github` — component source (see below)
• `integrations.storybook` — prop metadata (see below)

Auto-pull integrations

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

• Pull component source files from the configured repository if there's no local checkout

**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

---

Step 1: Gather component sources

Read before asking. `package.json` gives the package name, `version`, `exports`, `main` and `types`; the entry point gives the public component list; `tsconfig.json` or the presence of `.d.ts`, PropTypes or JSDoc gives the typing approach; the framework shows in the dependencies. Confirm what you found in one line and ask only for:

1. **Previous version source** (optional) — for breaking change comparison. Prefer the published type declarations of the previous release (`npm pack <pkg>@<prev>` and read its `.d.ts` files, or an api-extractor report); a git tag or release branch works if nothing was published 2. **Deliberate exceptions** — legacy names kept for compatibility, so they're reported as accepted rather than as deviations

If no component source is in reach (no path, no checkout, no package to unpack), stop and ask for one; an API audit of described components produces guesses.

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 with the tool that fits, and hand-parse only when none does.** Tool output is complete and consistent; a hand read of forty interfaces is neither.

• **React with TypeScript:** `react-docgen-typescript` (`npx react-docgen-typescript` or its API) gives name, type, required, default and description per prop from the interfaces. Storybook `argTypes` (from `integrations.storybook`) are the same data if the docs addon is set up.
• **Vue:** `vue-component-meta` for `<script setup>` and `defineProps`; fall back to reading `defineProps` by hand.
• **Web Components:** the Custom Elements Manifest (`npx custom-elements-manifest analyze`, or an existing