# Component Usage Guidelines

> Turn a component's code and docs into a contract that says what it's for, what it isn't for and what it promises.

- Drop: Prompt (rare)
- Season 1 – The AI-ready Design System
- Status: Tested (used on real work)
- Published: 2026-10-09
- URL: https://www.mlynarz.com/grist/component-usage-guidelines
- Curated by: Dawid Młynarz

**Hint:** For documenting components that agents will use. Each one gets a short contract in markdown.

## Why

Every component page in my design system opens with a short description, and agents are the ones reading it.

Props tell an agent what a component accepts. They don't tell it when to use one, so the description has to. The line that does the most work is what the component isn't for. For a button, that's "Don't use it to go to another page. Use a link."

## How to use it

1. Paste the component's code, props and any docs.
2. Fix the "don't use for" section; it's the most valuable line and the tool's weakest guess.
3. Save it next to the component.

## The drop

````markdown
Write a contract for this component, under 200 words:

- Purpose: one sentence
- Use when: two or three situations
- Don't use for: two or three common misuses, each with the component to use instead
- Props that matter: only the ones that change behaviour
- States: every state it supports
- Easily confused with: the components an agent might pick instead, and how to tell them apart
- Limits: content limits (max items, max characters) and accessibility promises

Mark anything you inferred rather than read as [CHECK].

Component:
[paste code and docs]
````