component-api-validator
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.
murphytrueman · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add murphytrueman/design-system-ops --skill 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 severityintegrations.github— if enabled, pull component source directly from the repointegrations.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:
- Component source path — directory containing component files (e.g.,
src/components/) - Framework — React (TSX/JSX), Vue (SFC), Web Components, Svelte, Angular, or other
- TypeScript usage — full TypeScript, JSDoc types, PropTypes, or untyped
- Current version — the published version of the library (for breaking change context)
- 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:
- Identify exported components — components that are part of the public API (exported from index files or package entry points)
- 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
- 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)
- 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?
- Does the component accept
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