# Marigold Design System

> Documentation for Marigold, Reservix' design system: React components built on react-aria and Tailwind CSS.

Every page is linked below as Markdown. Those `.md` files are generated from
the docs source with component demos inlined as source code and props tables
expanded, so they carry more than the rendered page shows. Append `.md` to any
docs URL to get the same for a page that is not listed here.

- Page index as JSON: https://www.marigold-ui.io/manifest.json
- Release notes: https://www.marigold-ui.io/releases/release-notes

## Getting Started

- [Marigold CLI](https://www.marigold-ui.io/getting-started/cli.md): (updated) Component docs, discovery, and project setup, straight from the terminal.
- [Adapting examples for agents](https://www.marigold-ui.io/getting-started/examples-for-agents.md): (new) How to take a Marigold application example and make it run in your own app, whatever framework you use.
- [Get in touch](https://www.marigold-ui.io/getting-started/get-in-touch.md): How to reach us when you need help with Marigold.
- [How to Contribute](https://www.marigold-ui.io/getting-started/how-to-contribute.md): How to bring your ideas, feedback, and work into Marigold.
- [Installation](https://www.marigold-ui.io/getting-started/installation.md): How to setup and get started with Marigold.
- [Recommended Third-party Libraries](https://www.marigold-ui.io/getting-started/recommended-libraries.md): Third-party libraries we recommend pairing with Marigold.
- [Release Phases](https://www.marigold-ui.io/getting-started/release-phases.md): Understand the phases that drive component stability, from Alpha to Stable
- [Usage with AI](https://www.marigold-ui.io/getting-started/usage-with-ai.md): (updated) Connect AI coding assistants to the Marigold documentation.

## Foundations

- [Accessibility](https://www.marigold-ui.io/foundations/accessibility.md): (updated) A guide to accessibility best practices for making your product usable for all.
- [Component Principles](https://www.marigold-ui.io/foundations/component-principles.md): The core ideas behind how Marigold components are designed, styled, and composed.
- [Elevation](https://www.marigold-ui.io/foundations/elevation.md): (updated) How surfaces and shadows work together to create visual depth and hierarchy
- [Form Fields](https://www.marigold-ui.io/foundations/form-fields.md): Comprehensive guide for working with form fields
- [Iconography](https://www.marigold-ui.io/foundations/iconography.md): (new) How icons work in Marigold and the catalog of available icons.
- [Layouts](https://www.marigold-ui.io/foundations/layouts.md): (updated) How layout and composition are handled.
- [Responsive Design](https://www.marigold-ui.io/foundations/responsive.md): (new) How Marigold handles breakpoints, responsive values, and the minimum supported screen width.
- [Spacing](https://www.marigold-ui.io/foundations/spacing.md): (alpha) How spacing is applied and used.
- [Token Overview](https://www.marigold-ui.io/foundations/token-overview.md): (new) The complete reference for the Marigold design token system
- [Typography](https://www.marigold-ui.io/foundations/typography.md): (alpha) Where the heading and body scales live today, and where they're heading.

## Components

- [Form](https://www.marigold-ui.io/components/form.md): Wrap your fields to submit user data and enable input validation.

## Components / Application

- [MarigoldProvider](https://www.marigold-ui.io/components/application/provider.md): Container for apps using Marigold.
- [RouterProvider](https://www.marigold-ui.io/components/application/routerprovider.md): Provider for easier handling routing.

## Components / Layout

- [AppShell](https://www.marigold-ui.io/components/layout/app-shell.md): (beta) The layout frame of an application with sidebar navigation, a top bar, and the page content.
- [Aside](https://www.marigold-ui.io/components/layout/aside.md): Component to separate content from the main content.
- [Aspect](https://www.marigold-ui.io/components/layout/aspect.md): Keep media elements at a certain apsect ratio.
- [Center](https://www.marigold-ui.io/components/layout/center.md): Component to center its children horizontally.
- [Columns](https://www.marigold-ui.io/components/layout/columns.md): Position content in one row.
- [Container](https://www.marigold-ui.io/components/layout/container.md): Keep content at an optimal reading width.
- [Grid](https://www.marigold-ui.io/components/layout/grid.md): Arrange elements in a grid structure.
- [Inline](https://www.marigold-ui.io/components/layout/inline.md): Display children horizontally in a row.
- [Inset](https://www.marigold-ui.io/components/layout/inset.md): Adds space around its children.
- [OverflowRegion](https://www.marigold-ui.io/components/layout/overflow-region.md): (beta) Hide trailing items instead of wrapping when space runs out.
- [Page](https://www.marigold-ui.io/components/layout/page.md): (beta) The main content area of a screen, with its title, description, primary action, and the sections beneath them.
- [Panel](https://www.marigold-ui.io/components/layout/panel.md): (beta) Organize page content into labeled regions.
- [Scrollable](https://www.marigold-ui.io/components/layout/scrollable.md): Lets the content scroll.
- [Split](https://www.marigold-ui.io/components/layout/split.md): Component that creates spacing between two flex elements.
- [Stack](https://www.marigold-ui.io/components/layout/stack.md): Display children vertically with giving space between.
- [Tiles](https://www.marigold-ui.io/components/layout/tiles.md): Organize the content in tiles of equal width.

## Components / Actions

- [Button](https://www.marigold-ui.io/components/actions/button.md): (updated) Buttons allow users to trigger actions.
- [ButtonGroup](https://www.marigold-ui.io/components/actions/button-group.md): (beta) Toolbar wrapper around a related cluster of buttons.
- [Link](https://www.marigold-ui.io/components/actions/link.md): Interactive component to help users navigate to new pages.
- [LinkButton](https://www.marigold-ui.io/components/actions/link-button.md): Interactive component that resembels a button to help users navigate to new pages.
- [ToggleButton](https://www.marigold-ui.io/components/actions/toggle-button.md): (beta) An action button that retains an active state.

## Components / Form

- [Autocomplete](https://www.marigold-ui.io/components/form/autocomplete.md): A searchfield that displays a dynamic list of suggestions.
- [Calendar](https://www.marigold-ui.io/components/form/calendar.md): A date selection interface for choosing dates from a calendar view.
- [Checkbox](https://www.marigold-ui.io/components/form/checkbox.md): Component to select one or more options.
- [ComboBox](https://www.marigold-ui.io/components/form/combobox.md): A text-field that allows the user to select values from a provided items array.
- [DateField](https://www.marigold-ui.io/components/form/datefield.md): Component for entering date in forms.
- [DatePicker](https://www.marigold-ui.io/components/form/datepicker.md): Component used to pick date value.
- [DateRangePicker](https://www.marigold-ui.io/components/form/daterangepicker.md): (beta) Pick a start and end date through a single field.
- [FileField](https://www.marigold-ui.io/components/form/file-field.md): A form component for uploading files with drag and drop support.
- [NumberField](https://www.marigold-ui.io/components/form/number-field.md): Component for entering numbers.
- [Radio](https://www.marigold-ui.io/components/form/radio.md): Component which allows to select only one option from a list.
- [RangeCalendar](https://www.marigold-ui.io/components/form/rangecalendar.md): (alpha) Used to select a contiguous date range
- [SearchField](https://www.marigold-ui.io/components/form/search-field.md): Component which allows user to enter and clear a search query.
- [SegmentedControl](https://www.marigold-ui.io/components/form/segmented-control.md): (beta) A compact control for switching between a few options that are all visible at once.
- [Select](https://www.marigold-ui.io/components/form/select.md): Dropdown for selecting an option among different options.
- [SelectList](https://www.marigold-ui.io/components/form/selectlist.md): (updated) Pick one or many items from a fully visible list of rich options.
- [Slider](https://www.marigold-ui.io/components/form/slider.md): Allows to make selections from a range of values.
- [Switch](https://www.marigold-ui.io/components/form/switch.md): (updated) Component that switches between two states.
- [TagField](https://www.marigold-ui.io/components/form/tag-field.md): (beta) A multi-select field that displays selected items as removable tags with a searchable dropdown.
- [TextArea](https://www.marigold-ui.io/components/form/textarea.md): Component for entering multiline text input.
- [TextField](https://www.marigold-ui.io/components/form/textfield.md): Component for input forms.
- [TimeField](https://www.marigold-ui.io/components/form/timefield.md): Component for entering time in forms.

## Components / Collection

- [ActionBar](https://www.marigold-ui.io/components/collection/actionbar.md): (alpha) Floating toolbar of bulk actions for the current selection in a collection
- [Card](https://www.marigold-ui.io/components/collection/card.md): (updated) Represents one item in a collection.
- [ListView](https://www.marigold-ui.io/components/collection/listview.md): (beta) Show a collection of items as a list, with optional per-row controls.
- [Table](https://www.marigold-ui.io/components/collection/table.md): Display and interact with structured data in rows and columns.
- [Tag](https://www.marigold-ui.io/components/collection/tag.md): Used to manage related options.

## Components / Navigation

- [Accordion](https://www.marigold-ui.io/components/navigation/accordion.md): Component to show and hide related content from the main page.
- [Breadcrumbs](https://www.marigold-ui.io/components/navigation/breadcrumbs.md): A component for displaying hierarchical navigation with separators.
- [Pagination](https://www.marigold-ui.io/components/navigation/pagination.md): Component that divides up large datasets into manageable chunks.
- [Sidebar](https://www.marigold-ui.io/components/navigation/sidebar.md): (beta) Persistent navigation panel for organizing app-level navigation.
- [Tabs](https://www.marigold-ui.io/components/navigation/tabs.md): Component for building tabs.
- [TopNavigation](https://www.marigold-ui.io/components/navigation/topnavigation.md): (beta) A component for building a persistent top navigation bar with flexible slot-based layout.

## Components / Overlay

- [ActionMenu](https://www.marigold-ui.io/components/overlay/action-menu.md): (alpha) Quick contextual actions for an item, row, or surface.
- [ContextualHelp](https://www.marigold-ui.io/components/overlay/contextual-help.md): Displays contextual help via popover on button click
- [Dialog](https://www.marigold-ui.io/components/overlay/dialog.md): Component for displaying dialogs.
- [Drawer](https://www.marigold-ui.io/components/overlay/drawer.md): Component for showing additional content alongside the main page.
- [Menu](https://www.marigold-ui.io/components/overlay/menu.md): (updated) A trigger that opens a list of commands a user can act on.
- [Toast](https://www.marigold-ui.io/components/overlay/toast.md): (beta) Toasts are used to display brief messages or notifications that appear temporarily on the screen.
- [Tooltip](https://www.marigold-ui.io/components/overlay/tooltip.md): Component for displaying short information.

## Components / Content

- [Badge](https://www.marigold-ui.io/components/content/badge.md): Component for short notes with one color as status messages
- [Description](https://www.marigold-ui.io/components/content/description.md): (alpha) Help text or supporting content paired with a title or label.
- [Divider](https://www.marigold-ui.io/components/content/divider.md): Component to separate content.
- [EmptyState](https://www.marigold-ui.io/components/content/empty-state.md): Inform users when there is no content to display.
- [ErrorState](https://www.marigold-ui.io/components/content/error-state.md): (beta) Inform users when a page or region failed to load.
- [Headline](https://www.marigold-ui.io/components/content/headline.md): The title of a content section
- [Keyboard](https://www.marigold-ui.io/components/content/keyboard.md): (beta) A hint that shows the keyboard shortcut for an action.
- [List](https://www.marigold-ui.io/components/content/list.md): Used to display an unordered or ordered list.
- [Loader](https://www.marigold-ui.io/components/content/loader.md): Used to indicate the progress of the task.
- [SectionMessage](https://www.marigold-ui.io/components/content/section-message.md): Display important information in a section of a screen.
- [SVG](https://www.marigold-ui.io/components/content/svg.md): Wrapper for SVG elements
- [Text](https://www.marigold-ui.io/components/content/text.md): Component for displaying text paragraphs
- [TextValue](https://www.marigold-ui.io/components/content/text-value.md): (alpha) Inline label primitive for selection items.
- [Title](https://www.marigold-ui.io/components/content/title.md): (alpha) Heading primitive that participates in container slot context.

## Components / Formatters

- [DateFormat](https://www.marigold-ui.io/components/formatters/dateformat.md): Helper component for formatting date values based on the current language and locale-specific conventions.
- [NumericFormat](https://www.marigold-ui.io/components/formatters/numericformat.md): Helper component for formatting numeric based on the current language and locale-specific conventions.

## Components / Hooks and Utils

- [cn](https://www.marigold-ui.io/components/hooks-and-utils/cn.md): Helper that combines classnames together.
- [cva](https://www.marigold-ui.io/components/hooks-and-utils/cva.md): Helper to write styles for an element.
- [extendTheme](https://www.marigold-ui.io/components/hooks-and-utils/extendTheme.md): Function used to customize theme components styles.
- [parseFormData](https://www.marigold-ui.io/components/hooks-and-utils/parseFormData.md): Parse form data into objects
- [useAsyncList](https://www.marigold-ui.io/components/hooks-and-utils/useAsyncList.md): Hook that returns async data
- [useLandmark](https://www.marigold-ui.io/components/hooks-and-utils/useLandmark.md): Register a region as an ARIA landmark and enable F6 navigation between landmarks.
- [useListData](https://www.marigold-ui.io/components/hooks-and-utils/useListData.md): Manages state for an immutable list data structure, and provides convenience methods to update the data over time.
- [useTheme](https://www.marigold-ui.io/components/hooks-and-utils/useTheme.md): Hook that applies a theme
- [VisuallyHidden](https://www.marigold-ui.io/components/hooks-and-utils/visually-hidden.md): Hide children but keep content accessible

## Patterns / Layout

- [Admin- and Mastermark](https://www.marigold-ui.io/patterns/layout/admin-master-mark.md): (beta) Marking internal-only features.
- [App Frame](https://www.marigold-ui.io/patterns/layout/app-frame.md): (alpha) A composition pattern for building the application frame with persistent sidebar navigation, a top bar, and scrollable content.

## Patterns / User Input

- [Bulk Actions](https://www.marigold-ui.io/patterns/user-input/bulk-actions.md): (beta) Let users select many records and act on all of them at once.
- [Filter](https://www.marigold-ui.io/patterns/user-input/filter.md): (beta) Understand methods to refine data.
- [Forms](https://www.marigold-ui.io/patterns/user-input/forms.md): (beta) Guidelines for building accessible, consistent forms covering layout, validation, and submission
- [Multiple Selection](https://www.marigold-ui.io/patterns/user-input/multiple-selection.md): Learn about how & when to use multiple selection
- [Pick](https://www.marigold-ui.io/patterns/user-input/pick.md): (alpha) Find and collect records from a collection, then commit them as a set.
- [Table Records](https://www.marigold-ui.io/patterns/user-input/table-record-management.md): (alpha) Help users create, correct, and maintain records in data heavy tables without losing their context.

## Patterns / Feedback

- [Async Data Loading](https://www.marigold-ui.io/patterns/feedback/async-data-loading.md): Learn how to implement async data loading patterns in interactive components.
- [Destructive Actions](https://www.marigold-ui.io/patterns/feedback/destructive-actions.md): (alpha) Decide whether a destructive action needs a confirmation or an undo, and build the one it needs.
- [Error Boundaries](https://www.marigold-ui.io/patterns/feedback/error-boundaries.md): (beta) How a failed page or region presents itself, recovers, and stays accessible.
- [Feedback Messages](https://www.marigold-ui.io/patterns/feedback/feedback-messages.md): Learn when to use which message.
- [Loading States](https://www.marigold-ui.io/patterns/feedback/loading-states.md): Learn when to use which loading state.

## Patterns / Data

- [Fetching and Mutations](https://www.marigold-ui.io/patterns/data/fetching-and-mutations.md): (alpha) Patterns for fetching, mutating and giving feedback with React Query and Marigold.