AI-Ready Component Description Template

What This Is

A simple template for writing component descriptions that both humans and AI tools can use. This is the format that makes it possible to write 554 component descriptions in a single session using AI assistance.

Why Descriptions Matter

• Figma descriptions are the first thing AI reads about your components
• Bad descriptions lead to wrong component selection and misuse
• Good descriptions eliminate “what is this for?” questions from both humans and AI

The Template

For each component, write a description following this structure:

[What it is]. [When to use it]. [Key constraint or behavior].

Examples

Good descriptions:

Component	Description
Button/Primary	Primary action trigger for forms and dialogs. Use for the single most important action on a page. Always pair with a secondary action for cancel/dismiss.
AlertBanner	System-level notification bar for page-wide messages. Use for errors, warnings, and success confirmations that affect the entire view. Dismissible unless the error requires action.
Card	Content container grouping related information as a scannable unit. Use in grids and lists for repeating content. Click target is the entire card surface.
Input/Text	Single-line text entry field. Use for short-form input (names, emails, search). Always pair with a visible label above the field.
Dialog/Destructive	Confirmation overlay for irreversible actions (delete, remove, revoke). Requires explicit user confirmation. Primary button uses danger variant.

Bad descriptions (don’t do this):

Component	Description	Problem
Button	A button	No context, no usage guidance
Card	Card component for the design system	Circular. Doesn’t explain when to use it.
Input	Text input field	Doesn’t distinguish from Textarea, Search, etc.

The Batch Prompt

Use this prompt to generate descriptions for multiple components at once:

I have a design system with the following components. Write a description for each one following this format: [What it is]. [When to use it]. [Key constraint or behavior].

Keep each description under 200 characters. Be specific about when to use vs when NOT to use. Mention accessibility requirements where relevant.

Components:
1. [Component name]
2. [Component name]
3. [Component name]
...

Tips

• Under 200 characters keeps descriptions scannable
• Start with what it IS, not what it does
• Include one “don’t” to prevent misuse
• Mention the key a11y requirement if there is one
• Be specific about context: “for forms” is better than “for user interaction”
• Run in batches of 20: AI quality drops with longer lists