# Poetry for Rails

> poetry is an AI-native, Rails-first component library: accessible,
> themeable ViewComponents on semantic design tokens. Agents compose
> from the approved catalog below instead of writing raw markup.

Preference hierarchy: tokens > utilities; components > raw markup;
variants > one-off classes; slots > custom HTML. Render components
with their `poetry_<name>` helpers.

Verify your markup with `poetry check` (rake poetry:check) before it
renders - it validates components, options, variants, and Stimulus
wiring against these contracts. Testing doctrine: the Testing guide on the poetry docs site.

## Components

- accordion: `poetry_accordion` - A vertically stacked set of interactive headings that each reveal a section of content.
- alert: `poetry_alert` - A callout that highlights an important inline message. (variant: default|destructive)
- alert_dialog: `poetry_alert_dialog` - A modal dialog that interrupts the user and expects a response. (size: default|sm)
- aspect_ratio: `poetry_aspect_ratio` - Locks its content to a fixed width-to-height ratio.
- attachment: `poetry_attachment` - A file or image chip showing its name, type, and size. (orientation: horizontal|vertical; size: default|sm|xs)
- autocomplete: `poetry_autocomplete` - An input that suggests options as you type - the text itself is the value.
- avatar: `poetry_avatar` - A user's image with an initials fallback.
- badge: `poetry_badge` - A small count or status descriptor. (variant: default|secondary|destructive|outline|ghost|link|success|warning|info)
- breadcrumb: `poetry_breadcrumb` - Shows the path to the current page as a trail of links.
- bubble: `poetry_bubble` - A chat message bubble aligned to its sender. (variant: default|secondary|muted|tinted|outline|ghost|destructive)
- button: `poetry_button` - Triggers an action or event, such as submitting a form or opening a dialog. (size: default|xs|sm|lg|icon|icon-xs|icon-sm|icon-lg; variant: default|destructive|outline|secondary|ghost|link)
- button_group: `poetry_button_group` - Visually joins adjacent buttons and controls into one group. (orientation: horizontal|vertical)
- calendar: `poetry_calendar` - A month grid for selecting single dates or ranges.
- card: `poetry_card` - A container that groups related content and actions.
- carousel: `poetry_carousel` - A slideshow for cycling through content, built on native scroll-snap.
- checkbox: `poetry_checkbox` - A control for toggling a single value on or off.
- clipboard_text: `poetry_clipboard_text` - A read-only value with a button to copy it to the clipboard.
- code_block: `poetry_code_block` - A syntax-highlighted code panel with a copy button and optional line numbers.
- collapsible: `poetry_collapsible` - An interactive element that expands and collapses a section of content.
- combobox: `poetry_combobox` - A text input with an autocomplete popover for picking from a list.
- command: `poetry_command` - A command palette for fast, keyboard-driven search and actions.
- command_dialog: `poetry_command_dialog` - The command palette in a modal dialog, summonable from anywhere.
- context_menu: `poetry_context_menu` - A menu of actions revealed by right-clicking an element.
- data_table: `poetry_data_table` - A table with sorting, row selection, and sticky headers.
- date_field: `poetry_date_field` - A segmented input for typing a date one part at a time.
- date_picker: `poetry_date_picker` - A date field that opens a calendar popover for selection.
- date_time_field: `poetry_date_time_field` - A segmented input for typing a date and a time one part at a time.
- deferred: `poetry_deferred` - A region that lazily loads its content on visibility, with skeleton and error states.
- dialog: `poetry_dialog` - A window overlaid on the page for content that requires attention.
- drawer: `poetry_drawer` - A gesture-driven panel that slides in from a screen edge. (direction: down|up|left|right)
- dropdown_menu: `poetry_dropdown_menu` - A menu of actions or options triggered by a button.
- empty: `poetry_empty` - An empty-state placeholder with an icon, message, and actions.
- field: `poetry_field` - Wraps a form control with its label, hint, and validation message. (orientation: vertical|horizontal|setting|responsive)
- field_group: `poetry_field_group` - variant: default|choices
- field_separator: `poetry_field_separator` - no style attributes
- fieldset: `poetry_fieldset` - no style attributes
- file_input: `poetry_file_input` - A control for selecting, previewing, and removing files to upload. (variant: input|dropzone)
- hover_card: `poetry_hover_card` - A card that reveals preview content when its trigger is hovered.
- icon: `poetry_icon` - Renders an inline SVG icon from the icon set.
- input: `poetry_input` - A form control for entering a single line of text.
- input_group: `poetry_input_group` - One bordered surface combining an input with buttons, icons, or add-ons.
- input_otp: `poetry_input_otp` - A fixed-length, segmented input for one-time passcodes.
- item: `poetry_item` - A generic list row with media, content, and actions. (size: default|sm|xs; variant: default|outline|muted)
- kbd: `poetry_kbd` - Displays a keyboard key or shortcut.
- label: `poetry_label` - An accessible caption bound to a form control.
- link: `poetry_link` - A styled navigational hyperlink. (underline: hover|always|none)
- marker: `poetry_marker` - A transcript divider or inline status marker for chat UIs. (variant: default|separator|border)
- menubar: `poetry_menubar` - A horizontal bar of menus, like a desktop application menu.
- message: `poetry_message` - A chat row pairing an author and avatar with message content.
- message_scroller: `poetry_message_scroller` - A streaming-aware transcript that keeps the latest message in view.
- metadata_list: `poetry_metadata_list` - A key-value list for labeled attributes on detail pages. (columns: one|two|three; orientation: vertical|horizontal)
- meter: `poetry_meter` - A gauge that shows a quantity within a known range.
- native_select: `poetry_native_select` - A styled wrapper around the real native select control.
- navigation_menu: `poetry_navigation_menu` - A site-navigation bar with links and optional dropdown panels.
- number_field: `poetry_number_field` - A numeric input with increment and decrement steppers.
- pagination: `poetry_pagination` - Navigation for moving between pages of content.
- popover: `poetry_popover` - Rich floating content anchored to a trigger.
- progress: `poetry_progress` - A determinate progress bar toward task completion.
- questionnaire: `poetry_questionnaire` - A one-question-at-a-time survey flow with choices, free answers, and validation.
- radio_group: `poetry_radio_group` - A set of options where only one can be selected at a time.
- resizable: `poetry_resizable` - Panels with draggable handles for resizing adjacent regions.
- scroll_area: `poetry_scroll_area` - A bounded, keyboard-reachable scroll region with styled scrollbars.
- search_field: `poetry_search_field` - A search input with clear and search affordances.
- select: `poetry_select` - A dropdown for choosing one option from a list.
- sensitive_input: `poetry_sensitive_input` - A masked secret field with a reveal toggle and a copy button.
- separator: `poetry_separator` - A thin divider between content, decorative or semantic.
- sheet: `poetry_sheet` - A dialog that slides in from a screen edge. (side: top|right|bottom|left)
- sidebar: `poetry_sidebar` - A collapsible app-shell navigation column.
- skeleton: `poetry_skeleton` - A pulsing placeholder shown while content loads.
- slider: `poetry_slider` - An input for selecting a value or range along a track.
- spinner: `poetry_spinner` - An indeterminate loading indicator that announces itself.
- stat: `poetry_stat` - A single KPI: a muted label over a large metric value.
- switch: `poetry_switch` - A toggle for turning a setting on or off. (size: default|sm)
- table: `poetry_table` - A semantic table for rows and columns of data.
- tabs: `poetry_tabs` - A tablist of triggers that switch between content panels.
- tag_group: `poetry_tag_group` - A set of removable chips or tokens.
- textarea: `poetry_textarea` - A form control for entering multiple lines of text.
- time_field: `poetry_time_field` - A segmented input for typing a time one part at a time.
- timeline: `poetry_timeline` - A sequence of dated events as an ordered list. (orientation: vertical|horizontal)
- toast: `poetry_toast` - A brief, auto-dismissing notification message. (variant: default|success|info|warning|destructive|loading)
- toast_trigger: `poetry_toast_trigger` - no style attributes
- toaster: `poetry_toaster` - The region that stacks and manages toast notifications. (position: top-left|top-center|top-right|bottom-left|bottom-center|bottom-right)
- toggle: `poetry_toggle` - A two-state button that can be pressed on or off. (size: default|sm|lg; variant: default|outline)
- toggle_group: `poetry_toggle_group` - A set of toggle buttons for single or multiple selection. (size: default|sm|lg; variant: default|outline)
- toolbar: `poetry_toolbar` - A horizontal group of controls that acts as one keyboard tab stop - Tab passes over the group, Arrow keys move between its controls. (orientation: horizontal|vertical)
- tooltip: `poetry_tooltip` - A floating label describing an element on hover or focus.
- tree: `poetry_tree` - A hierarchical list of expandable, selectable nodes.
- typeset: `poetry_typeset` - Prose styling for long-form and rendered-markdown content.

## Blocks

Blocks are the DEFAULT starting point, not a fallback: route every
brief through the MCP `compose` tool first - it returns the
matching block's source ready to adapt, or the component path when
nothing matches. Without MCP: `bin/rails g poetry:block <name>`
copies a block into app/views/blocks/ as source the app owns
(--list to browse). Blocks carry the composed patterns -
containment, status color-coding, page furniture, realistic
content - so a screen starts composed, not blank. Page framing
counts: a section that IS the page's subject keeps its container +
breathing room (the section blocks demonstrate the wrapper) - a
bare component at the viewport origin reads cramped.

- Action bar (`action-bar`): Bulk actions over a selectable table: a selection-driven floating bar with the live count, the actions, and clear - shown while rows are selected, Escape clears, focus never steals. [composes: button, data_table, icon]
- App shell (`app-shell`): The frame every screen composes into: an icon-collapsible sidebar with grouped nav, badges and a user footer, plus a topbar with breadcrumb that answers the collapsed state, and a stat-card content grid. [composes: avatar, breadcrumb, button, card, icon, separator, sidebar]
- Data index (`data-index`): A contained records screen: title bar with primary action, search-and-filter toolbar, status-badged table with a totals footer, and a result count paired with pagination. [composes: badge, button, button_group, icon, input_group, label, native_select, pagination, table]
- Destructive panel (`destructive-panel`): A guarded destructive action: heading and consequences in plain language, a severity-tinted alert with the blast radius, and a cancel/confirm action pair. [composes: alert, button, icon]
- Page header (`page-header`): The furniture a screen opens with: breadcrumb trail, page title with supporting description, and a right-aligned action group over a grounding rule. [composes: breadcrumb, button, icon, separator]
- Section card (`section-card`): A contained content section: header row with title, supporting description and a status badge, body copy with a feature list, and a footer pairing meta text with a call-to-action. [composes: badge, card, icon, link]
- Stepper (`stepper`): A multi-step flow header: numbered step indicators with connectors and completed/current/upcoming states over the current step's panel with back/continue actions. [composes: button, card, icon]
- Top nav (`top-nav`): A site navigation bar: brand mark, a products dropdown of rich title-and-description links, direct destinations, and the log-in / sign-up action pair. [composes: button, icon, link, navigation_menu]