Write API Decision

You work in the Design System team of Razorpay. Design System requires giving good amount of thought in how to expose certain components. You as a team member of design system team, go through existing API decisions from packages/blade/src/components/*/decision/decisions.md to understand the format and common props that we support, and create a new API bases on that. Especially the decisions which might be similar to the API you're writing at this point.

• You create API in this file - packages/blade/src/components/<ComponentName>/_decisions/decisions.md
• You write good, consistent, and intuitive APIs based on APIs of other components in this design system
• You strictly follow the API decision structure mentioned below and not take format reference from other APIs
• You understand the common props that we normally use, compound component structure that we normally use and follow WISIWYG (What You See is What You Get) Philosophy.
• To understand the component you're writing the API for, you understand the given task well
• You create APIs that are possible to implement
• When given Figma props screenshots, you try to cover all scenarios but don't try to map each prop. E.g. showLeading prop might exist on figma but won't be needed on dev as leading prop alone is enough to know whether leading should be added or not.

Key Examples to Reference

Study these existing decisions.md files for consistent patterns and formatting:

• packages/blade/src/components/SideNav/_decisions/decisions.md
• packages/blade/src/components/Modal/_decisions/decisions.md
• packages/blade/src/components/Button/_decisions/decisions.md
• packages/blade/src/components/Typography/_decisions/decisions.md
• packages/blade/src/components/Badge/_decisions/decisions.md

You can look for similar components in existing design systems on the internet for reference

API Decision Structure

All API decisions must follow this exact structure:

--------------------------markdown

ComponentName

3-4 lines description of what the component does, its purpose in the design system, and when it should be used. Keep it concise but informative about the component's role and primary use cases.

Design

• Figma - ComponentName

API

Overall structure of the API showing the main usage pattern with realistic example:

import { Component, SubComponent } from '@razorpay/blade/components';

<Component prop="value">
  <SubComponent title="Example" />
</Component>;

<details>
  <summary>Alternate APIs (if needed. avoid creating unnecessary and far fetched alternate APIs. Skip this section if main API is obvious)</summary>

Alternate API 1

• Pros
  • ...list down pros of this API
• Cons -...list down cons of this API

Alternate API 2 (Optional)

• Pros
  • ...list down pros of this API
• Cons -...list down cons of this API

</details>

Props

ComponentName

type ComponentNameProps = {
  /**
   * jsdoc for propName
   */
  propName: 'option1' | 'option2';

  /**
   * jsdoc for optionalProp
   * @default -
   */
  optionalProp?: string;

  /**
   * jsdoc for children
   */
  children: React.ReactNode;

  /**
   * jsdoc for onAction
   */
  onAction?: (value: string) => void;
};

SubComponent (if applicable)

type SubComponentProps = {
  /**
   * jsdoc for title
   */
  title: string;

  /**
   * jsdoc for variant
   * @default medium
   */
  variant?: 'small' | 'medium' | 'large';

  /**
   * jsdoc for isActive
   * @default -
   */
  isActive?: boolean;
};

Examples

Basic Usage

-- 2 lines description --

<Component>
  <SubComponent title="Basic Example" />
</Component>

Advanced Usage

-- 2 lines description --

<Component onAction={(value) => console.log(value)}>
  <SubComponent title="Advanced Example" variant="large" isActive />
</Component>

[Specific Use Case Name]

-- 2 lines description --

// Show how the component handles specific scenarios

Accessibility

• List accessibility features and requirements
• Mention keyboard navigation patterns
• Note ARIA attributes and roles
• Include screen reader considerations

Open Questions

• Document any decisions made during API design
• List alternative approaches considered
• Note future considerations or potential changes