Component API Validator

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 custom-elements.json) lists attributes, properties, events, slots and CSS custom properties; it is the standard, so read it rather than re-deriving it.
   • Svelte: exported let declarations, events, slots (read by hand; note that in the Scope block).
   • Untyped or PropTypes-only React: read PropTypes and JSDoc; record every prop with no type as untyped.
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:

For each inconsistency, report:

• The concept
• Which convention is most common (the likely "correct" one)
• Which components deviate
• Suggested normalisation

3b. Boolean prop patterns

Boolean props are a common source of API inconsistency:

1. Prefix convention — does the library use isDisabled or disabled? Pick one, flag deviations.
2. Negative booleans — the working convention is that a boolean prop defaults to false, so the common case needs no prop. hideLabel is the right shape when labels usually show; showLabel defaulting to true forces showLabel={false} at every call site that hides one. Flag a boolean whose default is true, and flag a library that uses both forms for the same concept (hideLabel on one component, showLabel on another). Don't flag a negative name on its own.
3. Boolean vs. enum — a prop that started as boolean (compact) but should be an enum (density: 'compact' | 'default' | 'comfortable'). Flag booleans that limit future extensibility.