# poetry docs

> The documentation site for Poetry, an AI-native, Rails-first component library: accessible, themeable ViewComponents on semantic design tokens. Every page below also serves a markdown mirror - append `.md` to its URL or send `Accept: text/markdown`.


## Guides

- [Installation](/installation): Install and upgrade: what poetry:install wires (idempotent, theme-sticky re-runs), the three ownership tiers, and the poetry:diff copy-in report — the install generator is the upgrade path, not a one-shot.
- [Theming](/theming): All nine upstream themes: install-time selection with --theme, the docs style switcher mechanism, and the lyra/sera font-pairing story.
- [Typography](/typography): Heading, paragraph, list, table, and inline-text recipes on Poetry tokens — class strings transcribed from upstream at the pin. Fonts ride the theme: the same markup goes mono under lyra, serif under sera.
- [Testing](/testing): Test Poetry UIs at the cheapest tier that can catch the bug: wiring asserts on rendered contracts, behavior through the Testing helpers (poetry_dialog, poetry_select, poetry_combobox, poetry_dropdown_menu, assert_poetry_controllers_registered), and the browser only for what needs a layout engine.
- [I18n](/i18n): Poetry's interface strings ride I18n keys under poetry.* - override the shipped en.yml per key, add locales with fallbacks, and keep visible copy in your own templates; form labels and errors localize through the model layer.
- [Stimulus](/stimulus): Compose your own Stimulus controllers with Poetry's: data: keywords merge onto any root or slot, forty-two controllers dispatch namespaced events, your markup drives Poetry's actions, use_stimulus declares wiring in a subclass, and a re-registered identifier extends a controller in JavaScript - poetry:check and the registration guard cover every rung.
- [Form Builder](/forms): The model-bound FormBuilder: form_with(builder:) + f.input for one-call fields - label, value, errors, aria, and validation attributes all derived from the object; type inference into Poetry's vocabulary, f.association, and the poetry_form -> simple_form i18n chain.
- [Pagination](/pagination): Pagination through the gem you already use: bin/rails g poetry:pagination installs a host-owned adapter for kaminari, pagy (v43+), or will_paginate - existing paginate / poetry_pagy_nav / will_paginate calls render Poetry's nav. This page's examples run live on all three gems.
- [Deferred Regions](/deferred): poetry_deferred(src:) — Turbo owns the loading physics (lazy fetches on visibility, so hidden Tabs panels and HoverCards defer for free); Poetry owns the states: a Skeleton placeholder and a retryable error card.
- [Optimistic Forms](/optimistic-forms): poetry_optimistic_form — the predicted result paints on submit as a server-authored Turbo Stream; the server corrects only on rejection (morph refresh). One vocabulary for prediction and truth, plus the 204/no-redirect server contract.
- [Recipes](/recipes): Multi-file payloads beyond components: skill bundles, the scaffold template set, and screen slices (controller + view + system test, blocks pulled as dependencies) - installable with bin/rails g poetry:add <name> or any shadcn-compatible registry client.
- [Page Agent](/page-agent): The operator-register demo: this site embeds page-agent (pinned, opt-in, bring-your-own key) configured with Poetry's operator register - watch a GUI agent operate the components, and see which tasks succeed through ARIA alone.
- [Agent Skills](/agent-skills): The installable skills catalog: what each skill teaches, served live with a discovery index (agentskills.io schema, sha256 digests) so npx skills, a curl one-liner, or bin/rails g poetry:skill drops the same SKILL.md set into any agent's skills directory.
- [Editors](/editors): bin/rails g poetry:editor wires Poetry's MCP server and registry-driven snippets into the editors a Rails team uses (VS Code, Cursor, Claude Code, Zed, RubyMine): safe MCP-config upserts, a per-editor matrix, a .herb.yml for the Herb toolchain, and the Figma / Paper design-tool token bridges.
- [API Reference](/api): The Ruby and JS surface, generated from the gems' source documentation: component options, slots, and style axes on each gallery page, plus per-gem pages for the base classes, DSLs, helpers, supporting gems, and the Stimulus controller suite.
- [Data Table](/data-table): The server-driven table: DataTable::State.from_params with a sortable: whitelist, URL-state sorting, filtering and pagination, row selection, and sticky headers - a full controller-to-view recipe.
- [Caching](/caching): Fragment-caching Poetry safely: the version-keyed cache recipe, and why unkeyed fragments go silently stale across component upgrades.
- [Stable IDs](/stable-ids): Poetry ids are unique per render by default - what that means for fragment caches, Turbo morph and ETags, and the id: token contract that pins them when identity matters.
- [Rails Engines](/engines): Reusable engines built on Poetry ship views as Ruby and ERB with zero CSS - the host's theme styles every mounted engine, so one retheme command restyles the whole application, engines included. The recipe: gemspec dependency, host layout, the tailwindcss-rails engines wiring, and the subclass pair for engine-owned component styling.
- [Accessibility](/accessibility): What Poetry guarantees by construction - required accessible names, Field-chain aria wiring, native form participation, overlay focus - and the keyboard and screen-reader checklist for verifying your app.
- [MCP Server](/mcp-server): The boot-free MCP server behind agent workflows: what each of the ten registry-backed tools does and when an agent reaches for it, and how it fits with llms.txt and the installable skills.
- [WebMCP](/webmcp): Your components' tools, registered with the user's own browser agent: opt a rendered Combobox, Dialog, or Tabs into WebMCP with one keyword, declare a form as a tool with no JavaScript, and try both live on this page.
- [AG-UI Relay](/ag-ui): Bring an AG-UI agent into your Rails app: run its endpoint, fold the event stream into a transcript, relay every change as a versioned Turbo Stream, let the page's components answer the agent's tool calls, and pause on interrupts - the full host recipe.
- [A2UI Surfaces](/a2ui): Render agent-generated UI with your own components: fold A2UI messages into surfaces, render them as forms, stream updates that keep their state, turn a submission into the spec's action, and run the catalog's functions and checks on the server and in the browser.

## Libraries

- [Core](/libraries/core): The engine gem: the component DSL, design tokens, and 53 Stimulus primitives poetry-ui is built on - the same public surface you use to build your own component library, styled with Tailwind utilities or a stable BEM class contract.
- [UI](/libraries/ui): The component catalog: 88 accessible components rendered server-side from Ruby helpers, with nine themes in the gem, copy-in ownership via poetry:add, testing helpers, and a full agent surface.
- [Charts](/libraries/charts): Nine chart families computed in Ruby and shipped as finished SVG in the initial HTML - valid in print, PDF, email, and without JavaScript, with live streaming and a frozen chart-spec for BYO engines.
- [Agent](/libraries/agent): The agent-interop gem: the boot-free poetry-agent MCP server for coding agents, and the WebMCP runtime that registers rendered components' declared tools with the user's browser agent.
- [Simple Form](/libraries/simple-form): The migration bridge from Simple Form: one initializer re-maps f.input onto Poetry fields, so existing forms restyle without a rewrite.
- [Extract](/libraries/extract): Domain-to-theme extraction: point it at a public site and it writes a DESIGN.md plus deterministic Poetry tokens, ready for the AA-gated importer.

## Icons

- [Lucide](/icons/lucide): The vendored icon set: 1,745 icons served from the gem, rendered through poetry_icon with literal-name validation.

## Components

- [Accordion](/components/accordion): A vertically stacked set of interactive headings that each reveal a section of content.
- [Alert](/components/alert): A callout that highlights an important inline message.
- [Alert Dialog](/components/alert-dialog): A modal dialog that interrupts the user and expects a response.
- [Aspect Ratio](/components/aspect-ratio): Locks its content to a fixed width-to-height ratio.
- [Attachment](/components/attachment): A file or image chip showing its name, type, and size.
- [Autocomplete](/components/autocomplete): An input that suggests options as you type - the text itself is the value.
- [Avatar](/components/avatar): A user's image with an initials fallback.
- [Badge](/components/badge): A small count or status descriptor.
- [Breadcrumb](/components/breadcrumb): Shows the path to the current page as a trail of links.
- [Bubble](/components/bubble): A chat message bubble aligned to its sender.
- [Button](/components/button): Triggers an action or event, such as submitting a form or opening a dialog.
- [Button Group](/components/button-group): Visually joins adjacent buttons and controls into one group.
- [Calendar](/components/calendar): A month grid for selecting single dates or ranges.
- [Card](/components/card): A container that groups related content and actions.
- [Carousel](/components/carousel): A slideshow for cycling through content, built on native scroll-snap.
- [Checkbox](/components/checkbox): A control for toggling a single value on or off.
- [Clipboard Text](/components/clipboard-text): A read-only value with a button to copy it to the clipboard.
- [Code Block](/components/code-block): A syntax-highlighted code panel with a copy button and optional line numbers.
- [Collapsible](/components/collapsible): An interactive element that expands and collapses a section of content.
- [Combobox](/components/combobox): A text input with an autocomplete popover for picking from a list.
- [Command](/components/command): A command palette for fast, keyboard-driven search and actions.
- [Command Dialog](/components/command-dialog): The command palette in a modal dialog, summonable from anywhere.
- [Context Menu](/components/context-menu): A menu of actions revealed by right-clicking an element.
- [Data Table](/components/data-table): A table with sorting, row selection, and sticky headers.
- [Date Field](/components/date-field): A segmented input for typing a date one part at a time.
- [Date Picker](/components/date-picker): A date field that opens a calendar popover for selection.
- [Date Time Field](/components/date-time-field): A segmented input for typing a date and a time one part at a time.
- [Deferred](/components/deferred): A region that lazily loads its content on visibility, with skeleton and error states.
- [Dialog](/components/dialog): A window overlaid on the page for content that requires attention.
- [Drawer](/components/drawer): A gesture-driven panel that slides in from a screen edge.
- [Dropdown Menu](/components/dropdown-menu): A menu of actions or options triggered by a button.
- [Empty](/components/empty): An empty-state placeholder with an icon, message, and actions.
- [Field](/components/field): Wraps a form control with its label, hint, and validation message.
- [Field Group](/components/field-group): 
- [Field Separator](/components/field-separator): 
- [Fieldset](/components/fieldset): 
- [File Input](/components/file-input): A control for selecting, previewing, and removing files to upload.
- [Hover Card](/components/hover-card): A card that reveals preview content when its trigger is hovered.
- [Icon](/components/icon): Renders an inline SVG icon from the icon set.
- [Input](/components/input): A form control for entering a single line of text.
- [Input Group](/components/input-group): One bordered surface combining an input with buttons, icons, or add-ons.
- [Input Otp](/components/input-otp): A fixed-length, segmented input for one-time passcodes.
- [Item](/components/item): A generic list row with media, content, and actions.
- [Kbd](/components/kbd): Displays a keyboard key or shortcut.
- [Label](/components/label): An accessible caption bound to a form control.
- [Link](/components/link): A styled navigational hyperlink.
- [Marker](/components/marker): A transcript divider or inline status marker for chat UIs.
- [Menubar](/components/menubar): A horizontal bar of menus, like a desktop application menu.
- [Message](/components/message): A chat row pairing an author and avatar with message content.
- [Message Scroller](/components/message-scroller): A streaming-aware transcript that keeps the latest message in view.
- [Metadata List](/components/metadata-list): A key-value list for labeled attributes on detail pages.
- [Meter](/components/meter): A gauge that shows a quantity within a known range.
- [Native Select](/components/native-select): A styled wrapper around the real native select control.
- [Navigation Menu](/components/navigation-menu): A site-navigation bar with links and optional dropdown panels.
- [Number Field](/components/number-field): A numeric input with increment and decrement steppers.
- [Pagination](/components/pagination): Navigation for moving between pages of content.
- [Popover](/components/popover): Rich floating content anchored to a trigger.
- [Progress](/components/progress): A determinate progress bar toward task completion.
- [Questionnaire](/components/questionnaire): A one-question-at-a-time survey flow with choices, free answers, and validation.
- [Radio Group](/components/radio-group): A set of options where only one can be selected at a time.
- [Resizable](/components/resizable): Panels with draggable handles for resizing adjacent regions.
- [Scroll Area](/components/scroll-area): A bounded, keyboard-reachable scroll region with styled scrollbars.
- [Search Field](/components/search-field): A search input with clear and search affordances.
- [Select](/components/select): A dropdown for choosing one option from a list.
- [Sensitive Input](/components/sensitive-input): A masked secret field with a reveal toggle and a copy button.
- [Separator](/components/separator): A thin divider between content, decorative or semantic.
- [Sheet](/components/sheet): A dialog that slides in from a screen edge.
- [Sidebar](/components/sidebar): A collapsible app-shell navigation column.
- [Skeleton](/components/skeleton): A pulsing placeholder shown while content loads.
- [Slider](/components/slider): An input for selecting a value or range along a track.
- [Spinner](/components/spinner): An indeterminate loading indicator that announces itself.
- [Stat](/components/stat): A single KPI: a muted label over a large metric value.
- [Switch](/components/switch): A toggle for turning a setting on or off.
- [Table](/components/table): A semantic table for rows and columns of data.
- [Tabs](/components/tabs): A tablist of triggers that switch between content panels.
- [Tag Group](/components/tag-group): A set of removable chips or tokens.
- [Textarea](/components/textarea): A form control for entering multiple lines of text.
- [Time Field](/components/time-field): A segmented input for typing a time one part at a time.
- [Timeline](/components/timeline): A sequence of dated events as an ordered list.
- [Toast](/components/toast): A brief, auto-dismissing notification message.
- [Toast Trigger](/components/toast-trigger): 
- [Toaster](/components/toaster): The region that stacks and manages toast notifications.
- [Toggle](/components/toggle): A two-state button that can be pressed on or off.
- [Toggle Group](/components/toggle-group): A set of toggle buttons for single or multiple selection.
- [Toolbar](/components/toolbar): A horizontal group of controls that acts as one keyboard tab stop - Tab passes over the group, Arrow keys move between its controls.
- [Tooltip](/components/tooltip): A floating label describing an element on hover or focus.
- [Tree](/components/tree): A hierarchical list of expandable, selectable nodes.
- [Typeset](/components/typeset): Prose styling for long-form and rendered-markdown content.

## Charts

- [Adapter Chart](/charts/adapter): The bring-your-own-engine path: a themed mount and chart-spec JSON for a client library (Chart.js, etc.) to draw, instead of poetry's server-side SVG.
- [Area Chart](/charts/area): An area chart for volume or cumulative totals over a continuous axis.
- [Bar Chart](/charts/bar): A bar chart for comparing values across categories.
- [Composed Chart](/charts/composed): A composed chart layering bars, lines, and areas on shared axes.
- [Line Chart](/charts/line): A line chart for trends over a continuous axis.
- [Pie Chart](/charts/pie): A pie chart for showing parts of a whole.
- [Radar Chart](/charts/radar): A radar chart for comparing several variables on radial axes.
- [Radial Bar Chart](/charts/radial-bar): A radial bar chart with bars wrapped around a circular axis.
- [Scatter Chart](/charts/scatter): A scatter chart for the relationship between two variables.

## Blocks

- [Action bar](/blocks/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.
- [App shell](/blocks/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.
- [Data index](/blocks/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.
- [Destructive panel](/blocks/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.
- [Page header](/blocks/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.
- [Section card](/blocks/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.
- [Stepper](/blocks/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.
- [Top nav](/blocks/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.

## Demos

- [Chat Replay](/demos/chat-replay): A scripted AI conversation replayed through the REAL streaming pipeline - Poetry::Ui::Chat's deterministic frames arriving as versioned Turbo Stream morphs into MessageScroller: token-paced text, a tool call flipping loading to done, and a human-in-the-loop approval where the pause is a form and the continuation is the stream after your decision. No model, no key, same bytes every run.
- [AG-UI Relay](/demos/agui-relay): A scripted AG-UI agent's event stream - text deltas, reasoning, a backend tool call, shared state, a frontend tool call, an interrupt - relayed by poetry-agent as versioned Turbo Streams into MessageScroller. The tabs component on the page executes the agent's tool call through the registrar and reports back; the interrupt is answered as a URL decision. No model, no key, same bytes every run.
- [A2UI Surface](/demos/a2ui-surface): A2UI surfaces rendered by poetry-agent: the spec's basic catalog and Poetry's own catalog rendered on the server as forms, and a third streamed progressively - the surface, its components, its data - as versioned Turbo Streams. Submit a surface and read the action message the agent receives, then watch the scripted agent's reply stream into place. No model, no key, same bytes every run.
- [Interactive Filter](/demos/interactive): Upstream's interactive blocks are useState filters. Here the filter is a real form: submitting re-renders the chart on the server and Turbo swaps it in. Switch the traffic dataset and the chart morphs between renders; switch the period and the entrance replays instead.
- [Live Streaming](/demos/live): The server renders the first frame complete; a ticker then streams a sliding window through the payload-script channel and the client kernel redraws — zero further server round trips. Hover while it runs: the tooltip keeps serving fresh values.
- [Synced Tooltips](/demos/sync): Two charts share one sync group. Hover or arrow-key either chart and both tooltips follow the same index — recharts' syncId, without a client chart library.
- [Brush & Zoom](/demos/window): A year of data behind the window mechanism: drag the brush handles (or the window body) to slice it, drag a range on the plot to zoom in, double-click to reset. Everything recomputes client-side.

## API

- [poetry-core](/api/poetry-core): The engine: the Component base class, the option / style / part / use_stimulus DSLs, the style dictionary, tokens, icons, and the registry.
- [@poetry/controllers](/api/poetry-controllers): The JavaScript surface: the 53 Stimulus controllers and the DOM helper modules, one source over two channels (the engine's importmap pins and the npm package) - generated from the source JSDoc and the controllers manifest.
- [poetry-ui](/api/poetry-ui): The component suite's Ruby surface beyond the gallery: the poetry_* view helpers, the model-bound FormBuilder, the Testing helpers, and the chat replay DSL.
- [poetry-charts](/api/poetry-charts): The charts gem's Ruby surface: the chart helpers, the shared chart chassis, and the geometry layer (scales, curves, ticks, paths).
- [@poetry/charts](/api/poetry-charts-controllers): The charts JavaScript surface: the five Stimulus chrome controllers (tooltip, motion, live, window, adapter), the BYO-engine adapter seam, and the motion/live modules - generated from the source JSDoc and the controllers manifest.
- [poetry-agent](/api/poetry-agent): The agent-interop gem: the MCP server (stdio exe and the Rack HTTP transport), its bundled assembly, the WebMCP runtime's Ruby side, and the origin-trial middleware.
- [poetry-simple_form](/api/poetry-simple_form): The simple_form adapter: activate! plus the input classes that map simple_form types onto poetry fields.
- [poetry-extract](/api/poetry-extract): Domain-to-theme extraction: fetch a site's design signals and compose a DESIGN.md + token set from them.

## Machine-readable resources

- [Component catalog for agents](/poetry/llms.txt) and [full contracts + Stimulus wiring](/poetry/llms-full.txt)
- [Registry index](/r/registry.json) - shadcn-schema items; install with `bin/rails g poetry:add <name>` or `npx shadcn add`
- [Agent skills inventory](/.well-known/skills/index.json) with per-file serving, and the [discovery index](/.well-known/agent-skills/index.json) (agentskills.io schema 0.2.0, sha256 digests) - `npx skills add <origin>/agent-skills` installs from it
- [Agent install instructions](/installation.md)
- [OpenAPI description](/openapi.json) and [API catalog](/.well-known/api-catalog)