Patterns

A component is a thing you can use. A pattern is how to use things together to solve a problem that keeps coming back: a form that validates without scolding people, an empty state that points somewhere, a page layout your whole product shares.

Tostada treats a pattern as a structured object rather than a page of prose, so the same pattern can be read by a person and followed by an AI.

What a pattern holds

The reasoning matters as much as the rules. "Never disable the submit button" is a rule; "a disabled button cannot be focused and gives no reason" is what lets someone apply it to a control the rule never mentioned.

Three levels: Foundations, Components, Patterns

The Library has three levels. Layout is no longer a level of its own: your shells and layouts appear under Patterns → Layout as layout patterns, each with its guidance, its arrangement and a live preview. The layout editor is at Patterns → Layout → Layout editor, and old links to it still work.

Three kinds of pattern

• Tostada's patterns — navigation hierarchy, accessibility, forms and validation, empty states, error and loading states, filtering and search, data table usage, and destructive actions.
• Layout patterns — one for each shell and layout in your library.
• Your own — patterns you write, under Patterns → Custom → Add a pattern. Your own patterns can have variants: a named alternative that changes only some sections and keeps the rest.

Making patterns your own

Every pattern page is editable. Open any pattern and choose Edit.

On Tostada's patterns and on layout patterns, only the sections you change are kept as yours. Every other section keeps following Tostada's version, so a correction we ship still reaches the parts you did not touch. Each section you changed is marked Edited, with Reset to Tostada's version beside it, and Reset all puts the whole page back. A layout's arrangement is changed in the layout editor, not here.

To start a separate pattern from one of Tostada's, choose Duplicate as a new pattern.

Images

Add images from the editor (PNG, JPEG, WebP or GIF, up to 2 MB). They appear at the top of the page, above the problem.

• In a local library, images stay in this browser, like the rest of the library. Opened on another computer, the page says the image is not available there.
• In a cloud library, images are stored privately for your organisation. Visitors to a share link see them through a link that expires after an hour.
• When you download the documentation site, images are copied into the folder, so it still works offline. The hosted documentation site and the command-line export name the image instead of showing it.
• If you restore an old version whose image has since been deleted, the page says so rather than showing a broken image.

Images are never sent to an AI: a model applying your system cannot look at a picture, so patterns.md and design-system.json leave them out.

Plans

Writing patterns, editing Tostada's and layout patterns, and adding images are part of Pro in cloud libraries. On Free you still read everything, including edits made while on Pro. Local libraries are never limited. See Plans.

Where the same patterns show up

One source, four readers, so none of them can disagree about what a pattern says — including your edits:

• The app — Library → Patterns.
• Your documentation site — one page per pattern, including in the offline folder you can open from disk. The accessibility page carries its guidance above the measured colour pairs.
• The design/ bundle — patterns.md holds every pattern with its rules and reasoning, and design-system.json holds a compact record of each, including a layout pattern's arrangement. AGENTS.md tells a coding agent to read the matching pattern before building a form, a table or an empty state.
• Spread — the in-app Spread reads the bundle, so the patterns shape the pages it rebuilds.

Leaving with your patterns

Patterns are part of the open format. Tostada's patterns are in @tostada-ui/format, and your own patterns and edits are in tostada.json, so regenerating your bundle or documentation on your own machine, without the app, carries the same guidance.