# Pluma Design System

> Pluma is Customer.io's design system. It contains design tokens, icons, and UI components for React and Ember.

This file is a table of contents for the public Pluma docs. Page links point to Markdown or MDX sources. Pages with AI guidelines or multiple tabs open as a Markdown index for that page.
Recommended traversal: For component work, start with [components.json](/components.json) to choose a component and its focused files. Read AI Guidelines first when present, then only the code, design, accessibility, API, or test helper Markdown needed for the task.

## [Overview](/overview.md)

- [About](/overview/about.md): Learn about our design system, why it exists, and its goals.
- [Agent skill](/overview/agent-skill.md): Give coding agents Pluma docs through a lightweight skill that reads the Markdown published on this site.
- [MCP server](/overview/mcp-server.md): Connect AI tools to Pluma docs, component metadata, and migration guidance through the Pluma MCP server.
- [CLI](/overview/cli.md): Run codemods to migrate your app across Pluma breaking changes with the @customerio/pluma-cli command-line tool.
- [Getting started](/overview/getting-started.md): Install Pluma packages and wire the provider, theme, and icons into your app.
- [Contributing](/overview/contributing.md): Learn how to contribute, including general guidelines, running the project locally, publishing, and creating new components.
- [Breaking changes](/overview/breaking-changes.md): Breaking changes planned for the next major version of Pluma.
- [Migrating to v3](/overview/migrating-to-v3.md): How to migrate an app from Pluma v2 to v3 — every breaking change, its codemod, and the recommended order.
- [Changelog](/overview/changelog.md): Review release notes for Pluma components, icons, tokens, and the MCP package.

## [Foundations](/foundations.md)

- [Content](/foundations/content.md): Guidelines for writing copy across Customer.io interfaces.
- [Icons](/foundations/icons.md): Icons are used to visually communicate core actions and concepts in the product. They are used to enhance the user experience and provide visual cues to help users understand the product.
- [Motion](/foundations/motion.md): Guidelines for using motion purposefully, accessibly, and consistently across Customer.io interfaces.
- [Principles](/foundations/principles.md): Guiding ideas to building Customer.io interfaces.
- [Style utilities](/foundations/style-utilities.md): All Pluma components accept a set of utility props to aid with layout and styling.

### [Tokens](/foundations/tokens.md)

- [All Tokens](/foundations/tokens/all-tokens.md): Design tokens for colors, spacing, typography, and more
- [Color](/foundations/tokens/color.md): Palette primitives, semantic color, and backdrop tokens.
- [Spacing](/foundations/tokens/spacing.md): Space, border width, and border radius tokens.
- [Typography](/foundations/tokens/typography.md): Font family, size, and weight primitives plus composite text styles.
- [Elevation](/foundations/tokens/elevation.md): Box shadow and filter shadow tokens for depth and focus.
- [Motion](/foundations/tokens/motion.md): Duration and easing tokens, with live previews of each timing and curve.
- [AI](/foundations/tokens/ai.md): Fill and ring tokens for AI surfaces and affordances.

## [Components](/components.md)

- [Status](/components/status.md): Track component maturity across design, framework support, tests, docs, and test helpers.
- [Test helpers](/components/test-helpers.md): Pluma components have test helpers to aid with writing tests

### [Layout](/components/layout.md)

- [Accordion](/components/accordion.md): Accordion is a component that allows for the expansion and collapsing of content
- [AccordionGroup](/components/accordion-group.md): AccordionGroup is the wrapper component for Accordions. It allows for limiting open accordions and helps standardize styling.
- [AspectRatio](/components/aspect-ratio.md): A utility component for constraining content to a fixed width-to-height ratio.
- [Box](/components/box.md): Base component for all Pluma components. All components in Pluma are built using the Box component. This means Pluma components all accept the Box component's props.
- [Card](/components/card.md): Card is a component for grouping similar content in a container.
- [CenterBaseline](/components/center-baseline.md): Utility component for centering content vertically.
- [Divider](/components/divider.md): A horizontal line that separates content.
- [EmptyState](/components/empty-state.md): EmptyStates notify the user that the content area or page has no data.
- [Flex](/components/flex.md): A utility component for creating flex containers.
- [FormLayout](/components/form-layout.md): A flexible layout component for arranging form elements with customizable spacing.
- [Grid](/components/grid.md): A utility component for building CSS grid layouts.
- [InlineStack](/components/inline-stack.md): A utility component for creating horizontal flex containers.
- [Panel](/components/panel.md): A Panel wraps related content, sometimes separated by borders, within a minimally-styled container.
- [Scrollable](/components/scrollable.md): Scrollable is a utility component that provides a scrollable container with configurable overflow behavior and edge detection capabilities.
- [SplitView](/components/split-view.md): A layout component for splitting a space into resizable, nestable panes with draggable handles.
- [Stack](/components/stack.md): A utility component for creating vertical flex containers.

### [Typography](/components/typography.md)

- [Code](/components/code.md): Code visually marks technical text in a monospace font family, alternate colors, and responsive font size.
- [DescriptionList](/components/description-list.md): Organize and explain a group of terms and their descriptions.
- [Emphasis](/components/emphasis.md): Marks text that has stress emphasis.
- [Heading](/components/heading.md): A styled, semantic heading element. The Heading component builds on top of Text and supports all Text props.
- [List](/components/list.md): List a group of text-only content.
- [Paragraph](/components/paragraph.md): Paragraph, meant to represent the paragraph element, is a typography component built on top of Text.
- [Strong](/components/strong.md): Strong renders bold text for visual weight and importance.
- [Text](/components/text.md): Text is a foundational component used to apply typographic styles.
- [TextLabel](/components/text-label.md): TextLabel captions form controls or definitions with contextual information.
- [Truncated](/components/truncated.md): A component that handles text truncation with an accessible tooltip that appears only when the text is actually truncated.

### [Content](/components/content.md)

- [Avatar](/components/avatar.md): A component that displays a user's avatar, supporting images, Gravatar, and initials.
- [CodeBlock](/components/code-block.md): Displays a block of code with syntax highlighting.
- [Coin](/components/coin.md): A shaped container (circle or rounded square) of fixed size that frames an Icon, Image, or short text content.
- [Icon](/components/icon.md): Icons are scalable graphics used to visually enhance a user interface.
- [Image](/components/image.md): Images are used to display graphics and custom icons.

### [Navigation](/components/navigation.md)

- [Breadcrumbs](/components/breadcrumbs.md): Breadcrumbs provide information about a user's current location within the application's page hierarchy.
- [Link](/components/link.md): Links are used to navigate to a new location, open or download an asset, or serve as an inline action.
- [NavItem](/components/nav-item.md): A component to display a navigation button in a sidebar.
- [Page](/components/page.md): Page is the outermost layout for a route, setting where the title and page-level actions sit and how wide the content column is.
- [Pagination](/components/pagination.md): A navigation component for moving through paginated content.
- [PlainLink](/components/plain-link.md): The PlainLink is a foundational component with minimal styling used to build other link components in Pluma.
- [SetupFlow](/components/setup-flow.md): An ordered set of steps that collapse into editable summaries as they are completed, ending in one explicit commit.
- [SideNav](/components/side-nav.md): A component to display a navigation sidebar.
- [Stepper](/components/stepper.md): Communicates progress through the ordered steps of a wizard or multi-step flow.
- [Tabs](/components/tabs.md): A component to switch between different views within the same context.
- [TabNav](/components/tab-nav.md): A navigation component to move between different views within the same page hierarchy.

### [Buttons](/components/buttons.md)

- [Button](/components/button.md): Buttons are interactive elements that allow the user to perform an action on the page or serve as a prominent hyperlink.
- [ButtonGroup](/components/button-group.md): The ButtonGroup component renders a group of related buttons next to each other.
- [CloseButton](/components/close-button.md): CloseButton provides a standard close/dismiss button with an X icon for use in dialogs, modals, and other dismissible UI elements.
- [DropdownMenu](/components/dropdown-menu.md): A set of actions in a popover.
- [PlainButton](/components/plain-button.md): The PlainButton is a foundational component with minimal styling used to build other button components in Pluma.

### [Forms](/components/forms.md)

- [Checkbox](/components/checkbox.md): Checkboxes allow users to select one or more items from a group of options.
- [CheckboxGroup](/components/checkbox-group.md): The CheckboxGroup component is used for displaying a list of related options, in the form of Checkbox inputs, where multiple choices may be selected.
- [ColorPicker](/components/color-picker.md): An HEX value color picker.
- [Combobox](/components/combobox.md): A text input with a dropdown list of options.
- [DatePicker](/components/date-picker.md): An input component that allows selecting a date from a popup calendar.
- [FileField](/components/file-field.md): FileField lets people choose files from their device, either through a button or a drag-and-drop area.
- [Form](/components/form.md): A component to handle submitting forms.
- [JsonField](/components/json-field.md): A textarea component for JSON input
- [NumberField](/components/number-field.md): A numeric input field with increment/decrement controls, value clamping, and keyboard support.
- [OptionCard](/components/option-card.md): OptionCards present the functionality of a radio or checkbox in a more visually prominent card format with an increased click area.
- [OptionCardGroup](/components/option-card-group.md): A wrapper for OptionCard components.
- [Radio](/components/radio.md): The Radio form control allows for selection of one option from a group.
- [RadioGroup](/components/radio-group.md): The RadioGroup component is used for displaying a list of related options, in the form of Radio inputs, where only one choice can be selected.
- [Search](/components/search.md): The PlumaSearch component builds upon the TextField component, providing additional functionality tailored for search use cases.
- [SegmentedControl](/components/segmented-control.md): Toggle from a set of two or more options. SegmentedControl is essentially a styled wrapper around a group of radio inputs.
- [Select](/components/select.md): Selecting a value from a dropdown list of options.
- [SelectPalette](/components/select-palette.md): The dropdown surface a Select renders, with an optional header, categories rail, detail pane and footer.
- [Slider](/components/slider.md): Choose a number value within a range.
- [TextArea](/components/text-area.md): A textarea component for user input.
- [TextField](/components/text-field.md): A styled text input field.
- [Toggle](/components/toggle.md): The Toggle component renders a switch to toggle between enabled or disabled states.

### [Data display](/components/data-display.md)

- [Badge](/components/badge.md): Badges are read-only indicators used to communicate a category, metadata, a numeric quantity, or a process's current state.
- [ConditionViewer](/components/condition-viewer.md): The ConditionViewer components render a read-only summary of a set of rules — one boxed sentence per rule, nested under the operator that combines them.
- [DataTable](/components/data-table.md): DataTable enables users to act upon complex datasets with a variety of features including filtering and sorting.
- [Filters](/components/filters.md): The Filters component is a versatile component that can be used to filter data based on user-defined criteria.
- [FormattedDateTime](/components/formatted-date-time.md): Displays a date/time formatted in one of a number of predefined formats.
- [FormattedRelativeTime](/components/formatted-relative-time.md): Displays a date/time in a human-readable format, relative to the current time.
- [KeyboardShortcut](/components/keyboard-shortcut.md): Displays keyboard shortcuts with platform-aware formatting.
- [ProgressBar](/components/progress-bar.md): A progress bar component that can be used to show the progress of a task.
- [ProgressCircle](/components/progress-circle.md): A circular progress indicator that visually represents the completion of a task or process.
- [StatusIndicator](/components/status-indicator.md): A small colored circle used to indicate status or state.
- [Table](/components/table.md): Tables display a set of data in an organized tabular format.
- [Tag](/components/tag.md): Tags represent user-generated, interactive categorization — items a person can add, apply, and remove, like filter criteria or audience attributes.
- [Timeline](/components/timeline.md): Presents ordered events, milestones, or state transitions with a connected vertical rail.

### [Feedback](/components/feedback.md)

- [Banner](/components/banner.md): Banners prominently communicate contextual information.
- [PageLoader](/components/page-loader.md): PageLoader communicates that a process is currently running on a page-level context.
- [SkeletonShape](/components/skeleton-shape.md): A placeholder component that mimics the shape of various UI elements while data is loading.
- [SkeletonText](/components/skeleton-text.md): A placeholder component that mimics the shape of text content while data is loading.
- [Snackbar](/components/snackbar.md): A non-disruptive message that appears at the bottom of the interface to provide quick, at-a-glance feedback on the outcome of an action. Snackbars communicate messages that are minimally interruptive.
- [Spinner](/components/spinner.md): Spinners are animated icons used to indicate a content area's loading state.

### [Overlays](/components/overlays.md)

- [Blanket](/components/blanket.md): An overlay component that centers content, with an optional semi-transparent background.
- [ConfirmationModal](/components/confirmation-modal.md): Confirmation with confirm/cancel actions.
- [Drawer](/components/drawer.md): Control interaction flow with simple, extensible drawers.
- [Drawer manager](/components/drawer-manager.md): Programmatic control of drawers
- [Modal](/components/modal.md): Modals are dialogs displayed over inert content that allow users to complete a singular, focused task without leaving the page.
- [Modal manager](/components/modal-manager.md): Programmatic control of modals
- [Popover](/components/popover.md): Popovers are floating overlays that contain additional information or interactive content.
- [Tooltip](/components/tooltip.md): A floating label to explain additional context in the UI. They're triggered by interaction events like hover, focus, tap, or click.

### [Misc](/components/misc.md)

- [VisuallyHidden](/components/visually-hidden.md): A utility component that visually hides its children while keeping them accessible to screen readers.

## [Data visualization](/data-visualization.md)

- [Colors](/data-visualization/colors.md): Categorical, sequential, semantic, and diverging chart color palettes
- [Chart](/data-visualization/chart.md): Chart draws data as composable marks — lines, bars, areas and radial arcs — on shared, automatically laid out axes.
  - [Marks](/data-visualization/chart/marks.md): A mark is one visual layer of a chart — a line, a set of bars, a ring of arcs — built by a factory function and layered onto shared axes.
    - [Line and area](/data-visualization/chart/marks/line-and-area.md): The two continuous marks — a line traced through the rows, and the fill beneath it — plus the curve and the labels that go with them.
    - [Bar](/data-visualization/chart/marks/bar.md): A bar per row, or a bar group per series — upright by default, and on its side where the category names or the ranking ask for it.
    - [Sparkline](/data-visualization/chart/marks/sparkline.md): A chart with everything but the shape taken away, small enough to sit in a table cell beside the number it qualifies.
    - [Dot](/data-visualization/chart/marks/dot.md): A dot per row, for points a reader is meant to notice — and `decorative`, which keeps an annotation out of the tooltip.
    - [Arc](/data-visualization/chart/marks/arc.md): A ring of slices, each one's angle proportional to its value — the pie, the donut and the gauge are one mark at different settings.
    - [Sankey](/data-visualization/chart/marks/sankey.md): Ribbons through a set of stages, showing how a quantity splits, drops off and recombines on its way.
    - [Reference line](/data-visualization/chart/marks/reference-line.md): A rule across the whole plot at one value — today, a target, the week a definition changed — with a caption beside it and a note the tooltip reads.
  - [Axes](/data-visualization/chart/axes.md): What Pluma infers about scales, ticks and margins, and the three things worth saying yourself — a second value axis, a domain, a time granularity.
  - [Series and legend](/data-visualization/chart/series-and-legend.md): Splitting a mark into one line or bar group per value, naming those series in a legend, and coloring them.
  - [Interaction](/data-visualization/chart/interaction.md): What the chart does under a pointer or a keyboard — the crosshair, the focused column, and the tooltip that follows it.
  - [Animation](/data-visualization/chart/animation.md): Drawing the chart in rather than showing it finished, and moving it between shapes when the data changes.
  - [Exporting](/data-visualization/chart/exporting.md): The download menu a chart can offer — the picture as a PNG or a PDF, and the numbers behind it as a CSV.

## [Patterns](/patterns.md)

- [Density](/patterns/density.md): Guidelines for applying density and spacing across Customer.io interfaces.
- [List page](/patterns/list-page.md): An index page built from a Page and a DataTable that owns its own search, filters, and pagination.
- [Menu keyboard shortcuts](/patterns/menu-keyboard-shortcuts.md): How to show keyboard shortcuts alongside menu actions so people can discover and learn them.
- [Setup flow with a preview](/patterns/setup-flow-with-a-preview.md): A SetupFlow beside live preview content, in a page-width Drawer.
- [States](/patterns/states.md): Guidelines for every state a screen can be across Customer.io interfaces.
- [Wizard layout](/patterns/wizard-layout.md): A multi-step flow built from a Page, a Stepper, and a stack of PageSections.

## [Advanced](/core.md)

- [Ember Floating UI](/core/ember-floating-ui.md): Position Ember overlays with Pluma's Floating UI helpers and interaction plugins.
- [Ember prop spreading](/core/ember-prop-spreading.md): Pass sets of props through Ember components with Pluma's unsafeprops and sprinkle utilities.
- [PlainModal](/core/plain-modal.md): PlainModal is a low-level component that provides the basic structure for a modal.
- [PlainPopover](/core/plain-popover.md): A primitive for building popovers. Used only within other Pluma components.
- [PlumaProvider](/core/pluma-provider.md): Configure the provider that supplies themes, icons, routing, and app-level Pluma behavior.
- [Portal](/core/portal.md): Render overlay content outside the current DOM hierarchy.
- [React yield](/core/react-yield.md): Pass structured values to React children using Pluma's yield helper.

## [Fly Migration](/fly-migration.md)

- [fly-alert](/fly-migration/fly-alert.md): Migrating fly-alert
- [fly-btn](/fly-migration/fly-btn.md): Migrating fly-btn
- [fly-close](/fly-migration/fly-close.md): Migrating fly-close
- [fly-label](/fly-migration/fly-label.md): Migrating fly-label
- [fly-panel](/fly-migration/fly-panel.md): Migrating fly-panel
- [fly-range](/fly-migration/fly-range.md): Migrating fly-range
- [Forms](/fly-migration/forms.md): Migrating form elements
- [Lists](/fly-migration/lists.md): Migrating lists
- [Tailwind](/fly-migration/tailwind.md): Migrating Tailwind classes