Marigold v17.2.0

Spring is just around the corner, and Marigold v17.2.0 brings a fresh batch of features and improvements.

Let's take a look at what's new!

Components

Sidebar (beta)

A new <Sidebar> component for persistent app-level navigation. It features a compound component API, drill-down sub-navigation with animated transitions, collapse/expand via keyboard shortcut (Cmd+B / Ctrl+B) with localStorage persistence, a mobile-responsive sheet overlay, and full accessibility and i18n support.

<Sidebar.Provider>
  <div className="flex h-screen">
    <Sidebar>
      <Sidebar.Header>
        <Text weight="bold">Acme Inc.</Text>
      </Sidebar.Header>
      <Sidebar.Nav>
        <Sidebar.Item href="/overview">Overview</Sidebar.Item>
        <Sidebar.Item href="/analytics">Analytics</Sidebar.Item>
        <Sidebar.Separator />
        <Sidebar.Item id="management" textValue="Management">
          Management
          <Sidebar.Item href="/users">Users</Sidebar.Item>
          <Sidebar.Item href="/teams">Teams</Sidebar.Item>
        </Sidebar.Item>
      </Sidebar.Nav>
      <Sidebar.Footer>
        <Text fontSize="xs">Footer content</Text>
      </Sidebar.Footer>
    </Sidebar>
    <main className="flex-1">
      <Sidebar.Toggle />
      {/* Page content */}
    </main>
  </div>
</Sidebar.Provider>

TopNavigation (beta)

A new <TopNavigation> component with a three-slot grid layout using the compound component pattern. It uses semantic HTML with <header> and <nav> landmarks, is sticky by default, and includes i18n ARIA labels.

<TopNavigation>
  <TopNavigation.Start>
    <Button variant="icon">
      <MenuIcon />
    </Button>
  </TopNavigation.Start>
  <TopNavigation.Middle>
    <SearchField placeholder="Search..." />
  </TopNavigation.Middle>
  <TopNavigation.End>
    <UserMenu />
  </TopNavigation.End>
</TopNavigation>

ActionBar (alpha)

The <ActionBar> has been significantly enhanced with enter/exit animations, keyboard support (press Escape to clear selection), and built-in <Table> integration.

The <Table> component does the heavy lifting: its new actionBar render prop automatically wires up selection state and positions the ActionBar relative to the table. Selecting rows reveals bulk actions, and the selection count updates automatically.

<Table
  aria-label="Users"
  selectionMode="multiple"
  actionBar={() => (
    <ActionBar>
      <ActionBar.Button onPress={() => alert('Edit')}>
        <Pencil />
        Edit
      </ActionBar.Button>
      <ActionBar.Button onPress={() => alert('Delete')}>
        <Trash2 />
        Delete
      </ActionBar.Button>
    </ActionBar>
  )}
>
  <Table.Header>
    <Table.Column>Name</Table.Column>
    <Table.Column>Email</Table.Column>
  </Table.Header>
  <Table.Body>
    {users.map(user => (
      <Table.Row key={user.id} id={user.id}>
        <Table.Cell>{user.name}</Table.Cell>
        <Table.Cell>{user.email}</Table.Cell>
      </Table.Row>
    ))}
  </Table.Body>
</Table>

Try the interactive demo in Storybook.

The <ActionBar> also received updated styling with a ui-surface-contrast utility for adaptive theming on dark surfaces and a dedicated button slot in the theme.

Breadcrumbs

The <Breadcrumbs> component now supports auto-collapse behavior. The maxVisibleItems prop defaults to 'auto', which uses a ResizeObserver to progressively show or hide breadcrumb items based on the available container width.

Tabs

The active tab underline now slides smoothly between items with an animated transition. This works automatically and requires no code changes. See the Tabs documentation for details.

System

CVA Migration (Custom/Extended Themes Only)

If you maintain a custom theme, note that the cva function re-exported from @marigold/system has been upgraded to cva v1 (beta). The new API uses a single object config with base, variants, compoundVariants, and defaultVariants keys instead of positional arguments. It also includes built-in Tailwind merge support, so you no longer need to handle class conflicts manually.

// Before
import { cva } from '@marigold/system';

const button = cva(['base-classes'], {
  variants: {
    variant: {
      primary: 'bg-brand text-white',
    },
  },
});

// After
import { cva } from '@marigold/system';

const button = cva({
  base: 'base-classes',
  variants: {
    variant: {
      primary: 'bg-brand text-white',
    },
  },
  defaultVariants: {
    variant: 'primary',
  },
});

Spacing Tokens (alpha)

The semantic spacing scale (introduced as alpha in v17.0.0) has been simplified from seven tokens down to five. The guiding principle stays the same -- tighter space signals a stronger relationship -- but the scale is now easier to reason about and covers real-world usage more effectively.

The previous extremes, joined (1px) and context (128px), have been dropped. In practice, joined was rarely needed and context overlapped too much with section. Removing them reduces decision fatigue without losing meaningful control.

peer has been renamed to regular, which better communicates that this is the default, baseline rhythm of the interface. The name also aligns with the inset scale, which uses regular in the same way.

Scale values have been increased across the board for improved readability and stronger visual hierarchy:

The form patterns have been updated to use the new tokens, showing how section, group, regular, and related work together to create clear visual hierarchy in real forms -- from major section breaks down to paired fields like postal code and city.

For the full token reference and usage examples, see the Spacing guide.

Design

• Improved color contrast ratios to meet WCAG AA standards. muted-foreground and placeholder bumped from stone-500 to stone-600 (7.55:1 ratio), disabled-foreground from stone-400 to stone-500 (4.71:1 ratio). Opacity modifiers on text colors have been removed across Calendar, ComboBox, Select, DatePicker, Input, Accordion, and Menu.
• Ghost button hover now uses currentColor at 10% opacity (hover:bg-current/10) instead of a fixed background color. This makes the hover state adapt automatically to any container, whether light or dark.
• Refined elevation shadow tokens for more subtle and consistent depth.
• New shared CSS utilities (ui-interactive, ui-press, ui-panel-header, ui-panel-actions) reduce repeated style patterns across theme files.
• <ListBoxItem> and <MenuItem> now have a minimum height of 44px on mobile screens, meeting WCAG 2.1 touch target guidelines.

Infrastructure

• The theme package now exports a typed appearances object via @marigold/theme-rui/appearances, providing a single source of truth for available variant/size keys per component.
• Added explicit types condition to package exports across @marigold/system, @marigold/icons, @marigold/theme-rui, and @marigold/theme-docs for reliable type resolution.
• Removed tailwindcss-animate dependency and standardized overlay animations across all components.
• Updated React Aria to v1.16.0.

Raw Markdown Endpoint for AI and External Tools

Every documentation page is now available as clean, semantic Markdown via a new /mcp/[...slug] API route. This makes it easy for AI assistants, LLMs, and external tools to read and understand Marigold's documentation programmatically.

The endpoint converts MDX pages through a processing pipeline that resolves interactive demos into TSX code blocks, generates prop tables from TypeScript source, and transforms custom JSX components (like <SectionMessage>, <Do>/<Dont>, <Callout>) into their Markdown equivalents. The result is a portable, readable document that retains the full content of each page without requiring a browser.

GET /mcp/components/actions/button.md
Content-Type: text/markdown; charset=utf-8

Pages are statically generated at build time, so responses are fast and cacheable. The docs UI also includes a "Copy as Markdown" button and a "View as Markdown" link on every page, making it simple to grab content for use in prompts, wikis, or other documentation systems.

Bug Fixes

• Components with hardcoded English strings (Toast, Drawer, Pagination, SectionMessage, ProgressCircle, ActionBar, TagField, SearchInput) now use useLocalizedStringFormatter for proper i18n support. ARIA labels are automatically translated when the locale changes.
• Fixed <Tooltip> positioning when using the controlled open prop.
• Fixed <NumberField> group appearing disabled when the stepper hits a min/max boundary.
• Added z-50 to the non-modal (desktop) <Drawer> overlay so it renders above sticky table headers and other positioned content.
• Set explicit py-0 on table column headers to prevent external systems from overriding vertical padding.
• Added card shadows to master and admin mark variants of <Card>.
• Reinforced floating <Drawer> panel boundary with a darker border and spread shadow.
• Aligned <Menu> button styles with <Button> by reusing buttonBase for consistent sizing, hover, and disabled states.

This release brings stronger navigation primitives, better accessibility, and a more polished visual foundation. As always, we welcome your feedback!