跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
法律与合规

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

ConceptConsistent patternInconsistent examples
Visual variantAll use variantSome use variant, others type, others appearance, others kind
SizeAll use sizeSome use size, others scale, others dimension
Disabled stateAll use disabledSome use disabled, others isDisabled
Loading stateAll use loadingSome use loading, others isLoading, others pending
Event handlersAll use onActionSome use onChange, others handleChange, others onValueChange
Colour/intentAll use intentSome use intent, others color, others severity, others status

For each inconsistency, report:

  • The concept
  • Which convention is mo
阅读完整来源 ↗