---
name: pluma
description: Customer.io's Pluma design system documentation. Use when building, reviewing, or migrating UI that uses Pluma components (React or Ember), design tokens, icons, or patterns, or when deciding how to compose a Customer.io interface.
---

# Pluma design system docs

Every Pluma doc is published as Markdown at https://pluma.customer.io. Fetch pages on demand; never guess a component API or layout convention from memory.

## Workflow

1. **Component work** (props, variants, usage of a specific component): fetch https://pluma.customer.io/components.json, find the component, then read its files in this order: AI Guidelines first when present, then only the code, design, accessibility, API, or test helper file the task actually needs.
2. **Page-level composition** (what a list page, wizard, or screen state should look like): read the Patterns pages, for example https://pluma.customer.io/patterns/states.md. The full list is under "Patterns" in llms.txt.
3. **Everything else** (tokens, icons, motion, principles, style utilities, provider setup, migrations): fetch https://pluma.customer.io/llms.txt and follow the relevant link.

## URL map

| Path | Content |
| --- | --- |
| `/llms.txt` | Table of contents for all docs |
| `/components.json` | Component manifest: status, per-file doc paths, source paths |
| `/components/<slug>.md` | Per-component index linking its focused files |
| `/ai-guidelines/<slug>.md` | Imperative rules for agents using the component |
| `/components/<slug>/api.md` | Full prop and API reference |
| `/patterns/*.md` | Page-level composition recipes |
| `/foundations/*.md` | Principles, tokens, icons, motion, style utilities |
| `/fly-migration/*.md` | Migrating legacy `fly-*` elements |
| `/llms.json` | Full manifest of every page (large; rarely needed) |

Relative links inside pages resolve against https://pluma.customer.io.

## Rules

- Read a component's AI Guidelines file first when it has one; it settles the layout and prop decisions the other docs leave open.
- Fetch only the files the task needs. Do not bulk-download llms.json or every tab of a component.
- For upgrades across breaking changes, read https://pluma.customer.io/overview/breaking-changes.md and run the `@customerio/pluma-cli upgrade` codemods.
- Docs describe the latest release. If the app pins an older `@customerio/pluma-components` major version, check the changelog before reaching for a new prop.