skills.rest
razorpay
razorpayOFFICIAL
Explore all skills by this author →
Website𝕏@razorpayGitHub

write-api-decision

Writes API decision documents for new Blade design system components.

649|197|Updated Jan 28, 2020
Search Tags:#react components#component props#Documentation#API Design#typeScript#blade#Design system
One-click install
npx skills add https://github.com/razorpay/blade --skill write-api-decision
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: write-api-decision
Source: https://github.com/razorpay/blade/tree/main/.agents/skills/write-api-decision
Command: npx skills add https://github.com/razorpay/blade --skill write-api-decision

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Designing consistent, implementable component APIs for a design system requires studying existing patterns and documenting decisions in a strict format, which is slow and error-prone when done manually.

Core Features & Use Cases

  • Structured API Decisions: Generates decisions.md files following the exact Blade template with API structure, TypeScript prop types, examples, accessibility notes, and open questions.
  • Pattern Consistency: References existing component decisions (SideNav, Modal, Button, Typography, Badge) to enforce common prop naming like variant, size, isActive, and compound component structures.
  • Use Case: When adding a new component like a DatePicker to Blade, use this Skill to produce a complete _decisions/decisions.md document with realistic JSX usage, typed props, and accessibility requirements before implementation begins.

Quick Start

Write an API decision document for a new DatePicker component following the Blade design system conventions.

Frequently Asked Questions about write-api-decision

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an API decision for a new Blade component?▼

Create a decisions.md file under packages/blade/src/components/<ComponentName>/_decisions/ following the required structure: description, Figma design link, API usage example, TypeScript prop types, examples, accessibility, and open questions. Reference existing decisions like Modal or Button for consistent patterns.

What structure should a design system API decision document follow?▼

The Blade template requires a component description, design link, main API example in JSX, optional alternate APIs with pros and cons, TypeScript prop type definitions per component, usage examples, accessibility requirements, and open questions documenting trade-offs.

How are props named in Blade component APIs?▼

Blade uses consistent naming: variant for visual variations, size with small/medium/large values, boolean states prefixed with is (isActive, isDisabled, isOpen), event handlers like onDismiss and onChange, and accessibilityLabel for screen readers.

Should Figma props map directly to component props?▼

No. Cover all Figma scenarios but avoid one-to-one prop mapping. For example, a showLeading Figma prop is unnecessary because the leading prop alone determines whether the leading element renders.

When should alternate APIs be included in a decision document?▼

Include alternate APIs only when the main API is not obvious and a genuinely different approach exists. Each alternate needs JSX examples plus pros and cons. Skip the section entirely if the primary API is clear.

Related Skills

Explore More Software Engineering Skills→
codigodoleocodigodoleo
13

superpowers-sage:sage-design-system

Automate Sage design system token extraction and component scaffolding.

Official
Advanced
soham2008xyzsoham2008xyz

writing-react-native-storybook-stories

Write React Native Storybook stories using CSF with Meta and StoryObj.

Community
Intermediate
TheGoat395TheGoat395
117

react-accessible-components

Construct accessible React components with semantic HTML and ARIA attributes.

Community
Intermediate
johnatas-henriquejohnatas-henrique

reverse-document

Generate design, architecture, and concept documentation from existing code.

Community
Advanced