LLMs.txt Format Reference

The LLMs.txt format is a standardized way to document components for AI systems. It's designed to be both human-readable and machine-parseable, making it ideal for inclusion in AI prompts and system contexts.

What is LLMs.txt?

LLMs.txt is a plain-text format that describes components in a way that's easy for AI systems to understand and use. It combines structured sections with plain English descriptions.

Benefits

Human Readable – Easy to include in prompts
Machine Parseable – AI can reliably extract information
Complete – Includes all information AI needs
Stable – Format doesn't change unexpectedly
No Dependencies – Just plain text, works everywhere

Format Structure

Document Header

# UI Lab Components

**Version:** 2.0.0
**Last Updated:** 2025-12-17
**Package:** ui-lab-components
**Repository:** https://github.com/your-org/ui-lab

This document describes all UI Lab components with their props,
variants, usage guidelines, and examples.

Component Section

Each component has this structure:

## ComponentName
**Category:** [category]
**Status:** [stable|experimental|deprecated]

[1-2 sentence description of what the component does]

### Import
import { ComponentName } from 'ui-lab-components'

### Props
- propName: type
  - description of the prop
  - valid values if applicable
  - default value if applicable

### Variants
- variantName: Description and when to use it

### Examples
[Code examples showing common usage]

### Accessibility
[Accessibility features and requirements]

### Composition
[How this component works with others]

Complete Example: Button Component

Here's a real example of how the Button component appears in LLMs.txt:

## Button
**Category:** action
**Status:** stable

Primary action component for user interactions. Use for buttons
that trigger actions, submit forms, or allow users to make choices.

### Import
import { Button } from 'ui-lab-components'

### Props
- variant: "primary" | "secondary" | "outline" | "ghost"
  - Visual style of the button
  - primary: Main call-to-action, use for recommended action
  - secondary: Alternative action, use for less important choices
  - outline: Secondary with less emphasis, use with secondary
  - ghost: Tertiary or subtle action, use for help or ancillary
  - default: "primary"

- size: "sm" | "md" | "lg"
  - Button size/padding
  - sm: Small button for compact layouts
  - md: Standard button size
  - lg: Large button for prominent placement
  - default: "md"

- disabled: boolean
  - Whether the button is disabled
  - Prevents user interaction
  - Shows disabled visual state
  - default: false

- onClick: (event: React.MouseEvent) => void
  - Callback function when button is clicked
  - Receives React mouse event
  - optional

- children: React.ReactNode
  - Button content (text, icons, etc.)
  - Can contain text, icons, or other elements
  - required

- className: string
  - Additional CSS classes
  - Use for responsive sizing: "w-full sm:w-auto"
  - optional

- type: "button" | "submit" | "reset"
  - HTML button type
  - Use "submit" for form submission
  - default: "button"

- aria-label: string
  - Accessible label for screen readers
  - Required if button only contains an icon
  - optional

- aria-busy: boolean
  - Indicates button is processing
  - Set to true while loading/submitting
  - optional

### Variants

- **primary** (default)
  Visual style: Full color, most prominent
  Usage: Main call-to-action, recommended action
  Example: <Button variant="primary">Save</Button>

- **secondary**
  Visual style: Lighter color, less prominent than primary
  Usage: Alternative actions, secondary choices
  Example: <Button variant="secondary">Cancel</Button>

- **outline**
  Visual style: Border with transparent background
  Usage: Secondary actions, multiple equal alternatives
  Example: <Button variant="outline">Download</Button>

- **ghost**
  Visual style: No background or border, text-only
  Usage: Tertiary actions, help, information
  Example: <Button variant="ghost">Help</Button>

### Examples

Basic button:
```jsx
<Button>Click me</Button>
```

Primary action:
```jsx
<Button variant="primary" onClick={handleSave}>
  Save Changes
</Button>
```

Loading state:
```jsx
<Button
  disabled
  aria-busy="true"
>
  <Spinner className="inline-block mr-sm" />
  Saving...
</Button>
```

Icon button (requires aria-label):
```jsx
<Button variant="ghost" aria-label="Close">
  ×
</Button>
```

Responsive sizing:
```jsx
<Button className="w-full sm:w-auto">
  Full width on mobile, auto on desktop
</Button>
```

Disabled button:
```jsx
<Button disabled>
  Not available
</Button>
```

### Accessibility

- All buttons have visible focus rings for keyboard navigation
- Keyboard support: Tab to focus, Space or Enter to activate
- Icon-only buttons must have aria-label attribute
- Disabled state is conveyed visually and programmatically
- Works with screen readers (NVDA, JAWS, VoiceOver)
- WCAG AA compliant

### Composition

Can contain: Icon, Spinner, or text
Can be contained by: Group, Card, Modal, Form
Related components: Link (for navigation), IconButton
Common patterns:
  - Button groups for related actions
  - Loading button with spinner inside
  - Icon button with aria-label
  - Form submission with disabled state during loading

### Design Tokens

**Primary variant uses:**
--accent-600 (background), --accent-50 (text)

**Secondary variant uses:**
--accent-100 (background), --accent-900 (text)

**Outline variant uses:**
--accent-300 (border), --accent-900 (text)

**Ghost variant uses:**
--transparent (background), --foreground-900 (text)

All variants support dark mode automatically.

Format Sections Explained

Component Header

## ComponentName
**Category:** category-name
**Status:** stable|experimental|deprecated

ComponentName: Exact export name from the package
Category: One of: action, input, layout, navigation, feedback, information, data
Status: Component maturity level

Description

One to two sentence description of what the component does
and when you should use it. Should be clear to someone
unfamiliar with UI Lab.

Import Section

### Import
import { ComponentName } from 'ui-lab-components'

Standard import statement for the component.

Props Section

### Props
- propName: type
  - Description
  - Additional details
  - Valid values if enum
  - default: value

Format Rules:

List each prop on its own line
Include the type (string, boolean, function, etc.)
Describe what the prop does
For enums, list each valid value with description
Note defaults
Mark as required or optional

Variants Section

### Variants
- **variantName**
  Description and purpose
  Usage guidelines
  Example code if helpful

Document each variant and its purpose. Explain semantic meaning.

Examples Section

### Examples

Brief description:
```jsx
<Component>example code</Component>
```

Show common usage patterns with brief descriptions.

What to Include:

Basic usage
All major variants
Common prop combinations
Loading/disabled states
Responsive examples
Icon/label examples

Accessibility Section

### Accessibility

- Feature 1: description
- Feature 2: description
- WCAG level: AA
- Tested with: screen readers, keyboard navigation

Document accessibility features and requirements.

Composition Section

### Composition

Can contain: ComponentA, ComponentB, ...
Can be contained by: ComponentX, ComponentY, ...
Related components: ComponentP, ComponentQ
Common patterns:
  - Pattern 1
  - Pattern 2

Explain how this component relates to others.

Design Tokens Section

### Design Tokens

**variant-name uses:**
--token-1, --token-2

All variants support dark mode automatically.

List semantic design tokens for each variant.

Complete File Template

# UI Lab Components

**Version:** 2.0.0
**Last Updated:** [date]
**Package:** ui-lab-components
**Documentation:** https://ui-lab.app

Complete reference for all UI Lab components.

---

## Button

[Full button documentation as shown above]

---

## Input

[Input component documentation]

---

## [Other components...]

Generating LLMs.txt

Command Line

Generate the LLMs.txt file for your project:

npx ui-lab llms > components.txt

Programmatically

import { generateLLMsText } from 'ui-lab-registry'

const llmsText = generateLLMsText()
console.log(llmsText)

In Your Documentation

Include LLMs.txt in your documentation:

# Option 1: Commit to repository
git add components.txt
git commit -m "docs: update component reference"

# Option 2: Auto-generate on build
npm run build:docs

Using LLMs.txt with Claude

In System Prompt

Include a reference to LLMs.txt in Claude's system instructions:

When generating React code, reference this component documentation:

[Include LLMs.txt content here]

Use these components with the provided props and variants.

In User Prompt

Reference specific components when asking Claude:

Using the Button component from the documentation provided,
create a form with Save and Cancel buttons.

Button variants:
- primary: for main CTA
- secondary: for alternative actions

With MCP Server

Use the MCP server to get real-time LLMs.txt:

const client = new MCPClient()
const llmsText = await client.getLLMsText()

// Use in prompt context
const prompt = `
Here are the available components:

${llmsText}

Generate a login form component.
`

Best Practices

For Component Authors

Keep Examples Simple – Show common patterns, not edge cases
Be Descriptive – Explain the 'why', not just the 'what'
Include All Props – Don't omit optional props
Document Accessibility – Make it clear what a11y features exist
Show Variants – Include all variants with examples
Update Regularly – Keep LLMs.txt in sync with code

For AI Prompts

Include Full LLMs.txt – Don't summarize, include the complete text
Reference Specific Components – "Use the Button component with variant='primary'"
Show Examples – Quote the examples from LLMs.txt
Be Explicit About Props – List the specific props you want used
Request Type Safety – Ask for TypeScript with types from LLMs.txt

Format Conventions

Use ## for component names
Use ### for major sections (Props, Examples, etc.)
Use #### for subsections if needed
Use backticks for code: propName, variant="primary"
Use bold for emphasis: important concept
Use ````jsx` for code blocks
Keep line length reasonable (max 80 characters for readability)

Common Components in LLMs.txt

Button

Primary, secondary, outline, ghost variants Size: sm, md, lg Disabled, loading states

Input

Type: text, email, password, number, etc. Error states Icon support Disabled state

Select

Options as children or array Single or multiple selection Searchable variant Grouped options

Flex/Grid

Responsive column/row configuration Alignment and justification Gap spacing Auto-fit/auto-fill

Form/FormField

Composition with Input, Select, etc. Error display Validation feedback

Modal/Dialog

Header, body, footer sections Backdrop dismiss Focus trapping Keyboard support (Escape to close)

Card

Header, body, footer sections Composable container Shadow and border styling

Validation

Checking LLMs.txt Format

Validate your LLMs.txt:

npx ui-lab llms:validate components.txt

Requirements

All exported components documented
All props listed
Examples provided
Accessibility section included
Proper formatting with markdown
No broken imports or references

Version History

The LLMs.txt format evolves over time:

v1.0 - Initial format, basic component documentation
v1.1 - Added design tokens section
v2.0 - Added composition guidelines
v2.1 - Enhanced examples section with more patterns

Check the version in your LLMs.txt:

**Version:** 2.0.0

Troubleshooting

Claude doesn't use the right component

Cause: LLMs.txt examples aren't clear enough Fix: Add more detailed examples showing common patterns

Generated code has wrong props

Cause: Props not clearly documented in LLMs.txt Fix: List all props with descriptions and defaults

Components missing from LLMs.txt

Cause: Component not exported from package Fix: Export component and regenerate LLMs.txt

Formatting issues in prompt

Cause: LLMs.txt formatting may be unclear Fix: Use cleaner formatting, clearly delineate sections

Next Steps

Generate Your LLMs.txt → npx ui-lab llms > components.txt
Use With Claude → Include in system prompts
Set Up MCP → Use MCP server for dynamic access
View Full Registry → Component Registry Reference

LLMs.txt: Reliable component documentation for AI systems.