ui

Maquina UI Standards

Build production-quality Rails UIs with maquina_components — ERB partials styled with Tailwind CSS 4 and data attributes, inspired by shadcn/ui.

Verified against maquina-components 0.7.0. Upgrading an app from 0.5.x? Read upgrading-0.6.md first — 0.6.0 changed behavior silently. 0.7.0 broke nothing, but it deprecated collapse_after on responsive_breadcrumbs and fixed focus-ring timing; never transition outline-color in a component of your own.

Official documentation: https://maquina.app/documentation/components/

Core Rules

1. Composition first — build screens from component partials and helpers; wrap repeated compositions into app-specific partials that encode your conventions.
2. Data-attribute styling — components style through data-component / data-*-part attributes; the engine CSS handles appearance. Reach for a variant or a role token first, and use Tailwind utilities for layout — grids, spacing, placement.
3. The layered engine — every engine rule lives in @layer components flattened to specificity 0,1,0, so a utility passed as css_classes: applies. That makes rule 2 a convention you keep, not a mechanism that keeps itself: an unintended utility silently reshapes the component.
4. Semantic variants — map meaning to variants (:success, :warning, :destructive), one mapping per status domain. The danger variant is :destructive everywhere; sizes are :sm / :default / :lg (badge's middle size is :md; both accept the other's name as an alias). This vocabulary is canonical — the catalog defers to it.
5. Helpers for interactive components — dropdown_menu, combobox, toggle_group, simple_table, pagination_nav (Pagy), empty_state, toast_flash_messages, breadcrumbs. Use _simple variants for data-driven one-liners, block builders for custom content, partials for structural components (Card, Alert, Badge, Sidebar, Drawer).
6. Inline errors — field errors render next to their input (data-form-part="error"), with a brief flash summary. Complete inputs: every field carries type, required, maxlength, autocomplete, and inputmode where they apply.
7. Handle the zero state — every list renders an empty_state (or empty_search_state / empty_list_state) when the collection is empty.
8. Icons via icon_for — one icon system, delegating to the app's main_icon_svg_for override with built-in SVG fallbacks. Under strict_icons (on by default in development and test) an unresolvable name raises MaquinaComponents::UnknownIconError, so use a name from the roster in installation-guide.md.
9. Tokens carry the design — color, shape, elevation, focus and weight are all CSS variables. Use role tokens (--surface-radius, --elevation-overlay, --focus-ring-width) to restyle a whole class of component, and a per-component escape hatch (--card-radius, --toast-shadow) to pin exactly one. A theme changes values, not selectors. One accent color moment per screen; neutrals elsewhere.