poetry-ui 0.0.2

data/lib/generators/poetry/agents_section.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Poetry
+  # Namespace for poetry's Rails generators and their shared step
+  # modules.
+  module Generators
+    # The host-facing AGENTS.md section: a short, registry-derived
+    # pointer layer for coding agents working in the host app - llms.txt
+    # stays the catalog, this is the front door to it. Marker-bounded so a
+    # re-run refreshes poetry's section without touching anything the host
+    # wrote around it.
+    #
+    # Shared by poetry:install and the standalone poetry:agents (which
+    # exists so hosts that must NOT re-run install - e.g. a docs app with a
+    # hand-scoped style registry - can still refresh the pointer). NOTE:
+    # Thor only registers methods added directly on the generator class as
+    # steps, so each generator declares its own public step and calls
+    # apply_agents_section.
+    #
+    # @api private
+    module AgentsSection
+      BEGIN_MARKER = "<!-- poetry:agents:begin -->"
+      END_MARKER = "<!-- poetry:agents:end -->"
+
+      # Writes or refreshes the marker-bounded poetry section in the
+      # host's AGENTS.md.
+      def apply_agents_section
+        path = File.join(destination_root, "AGENTS.md")
+        if File.exist?(path) && File.read(path).include?(BEGIN_MARKER)
+          gsub_file "AGENTS.md",
+                    /#{Regexp.escape(BEGIN_MARKER)}.*#{Regexp.escape(END_MARKER)}/mo,
+                    agents_section.chomp
+        elsif File.exist?(path)
+          append_to_file "AGENTS.md", "\n#{agents_section}"
+        else
+          create_file "AGENTS.md", agents_section
+        end
+      end
+
+      # The marker-bounded section text, registry-derived.
+      def agents_section
+        <<~MD
+          #{BEGIN_MARKER}
+          ## Building UI with poetry (#{agents_component_counts})
+
+          - FIRST MOVE on any UI brief: call the poetry MCP `compose` tool with the
+            task text, before writing any ERB. It routes to the matching vetted
+            block (source included, adapt in place - the winning path for screens)
+            or to the right components. No MCP? `bin/rails g poetry:block --list`
+            and start from the closest block. Composing a screen from scratch when
+            a block matched is the known losing path.
+          - Compose with the `poetry_*` helpers; never hand-write `cn-*` classes, raw
+            hex/oklch colors, or off-scale arbitrary values - tokens and variants carry
+            the design.
+          - Machine catalog: `/poetry/llms.txt` (index + blocks) and `/poetry/llms-full.txt`
+            (full contracts + Stimulus wiring: targets / values / actions / events).
+          - Check comes LAST: `bin/rails poetry:check` as the FINAL action, after
+            the last edit (unknown components/slots/variants/wiring, icon names,
+            enum values, typed-slot props, helper + setter arity, yield-less
+            blocks, setter keywords, required content blocks, required slots,
+            did-you-mean, `--json`; needs the `herb` gem in the Gemfile). An edit
+            made after your last check is unverified markup - re-run it.
+          - Faster: the `poetry` MCP server (`.mcp.json`: command `bundle`, args
+            `["exec", "poetry-agent"]`, the poetry-agent gem) serves ten tools from the live registry
+            with no app boot - `compose`, `build_page`, `list_components`,
+            `describe_component`, `check`, `list_blocks`, `describe_block`,
+            `list_recipes`, `get_skill`, and `guidance`. Prefer `compose` (or `build_page` for a
+            whole screen) to start, and its `check` tool when iterating. Wire it
+            into every editor at once with `bin/rails g poetry:editor` (MCP
+            configs for VS Code / Cursor / Claude Code / Zed / RubyMine plus
+            registry-driven snippets).
+          - Browser agents (WebMCP): opt a rendered component into the user's own
+            agent with `webmcp: "name"` on the helper call - Combobox, Dialog, Sheet,
+            Drawer, and Tabs declare tools (`describe_component` at `full` lists them);
+            declare a form as a tool with `poetry_webmcp_form(tool: { name:,
+            description: })` (autosubmit is GET-only). Needs the poetry-agent gem and
+            `registerPoetryAgent(application)`; `poetry:check` gates the opt-ins.
+          - One visual theme per app (chosen at install with `--theme`); components
+            read tokens, never restate them.
+          - Component identity: pass `key:` (a record, or a literal string) on any
+            poetry component inside a collection loop, a fragment-cache block, or
+            a broadcast partial - keyed ids follow the record across Turbo morph
+            reorders and stay stable inside cached fragments, where random ids
+            force replacement. `key: record` derives via dom_id (a host `to_key`
+            override propagates); explicit `id:` wins outright; repeated NEW
+            records need explicit keys. `poetry:check` warns on unkeyed
+            components in cache blocks and loops. Full story: the Stable IDs guide on the poetry docs site.
+          - Upgrading poetry gems: after `bundle update`, re-run
+            `bin/rails g poetry:install` - the vendored token/theme/safelist
+            files refresh (the installed theme sticks; `--theme` switches),
+            new wiring appends, this section and the skills regenerate. Then
+            rebuild CSS and run the suite. `bin/rails g poetry:diff` reports
+            where copied-in components drift from the installed gems.
+          - `bin/rails g poetry:scaffold_templates` retargets the STANDARD
+            `rails g scaffold` to emit poetry-composed views (DataTable index
+            with URL state, Field-composed forms) plus a matching controller -
+            prefer scaffolding over hand-writing CRUD views.
+          - Claude Code skills: `poetry` (component contracts by family),
+            `poetry-design` (theme / compose / audit / study / figma / paper -
+            the taste layer), and `poetry-component` (anatomy / documentation /
+            audit - the authoring layer) live under `.claude/skills/` - load
+            `poetry` whenever writing ERB, `poetry-design` whenever composing a
+            page or screen, BEFORE building (any page task is a design task,
+            not only ones that mention design), and `poetry-component` whenever
+            authoring or reviewing an app-owned component. Install/refresh:
+            `bin/rails g poetry:skill`.
+          - Design interop: `bin/rails poetry:design:export` writes this app's
+            DESIGN.md (tokens + treatment) for external design skills.
+          - Overriding the theme: token-level restyling goes through
+            `poetry:design:import` (design-overrides.css) - which also ingests a
+            Figma variables export (`bin/rails poetry:figma:import[export.json]`)
+            or a Paper "Copy theme" (`bin/rails poetry:paper:import[theme.css]`),
+            dropping any swatch that fails WCAG AA. Host CSS that targets
+            theme-owned `cn-*` classes is allowed ONLY as a declared
+            override - a dated, reasoned entry under `overrides:` in
+            config/poetry_components.yml (`bin/rails poetry:design:overrides`
+            reports drift and prints the paste-ready declaration). Declare
+            only after the user confirms intent; never declare to skip a fix.
+          #{END_MARKER}
+        MD
+      end
+
+      # The human count line (components + charts + blocks) for the
+      # section heading.
+      def agents_component_counts
+        parts = ["#{agents_registry_size(Poetry::Ui.root)} components"]
+        # Tolerant on charts: a stubbed/partial gem without a registry file
+        # (the install-test stub) just drops out of the count.
+        charts = defined?(Poetry::Charts::Engine) && agents_registry_size(Poetry::Charts.root)
+        parts << "#{charts} chart components" if charts
+        blocks = agents_registry_size(Poetry::Ui.root, section: "blocks")
+        parts << "#{blocks} blocks" if blocks&.positive?
+        parts.join(" + ")
+      end
+
+      # One section's entry count from a gem's committed registry (nil
+      # when the gem ships none).
+      def agents_registry_size(root, section: "components")
+        path = root.join("config/component_registry.yml")
+        return nil unless File.exist?(path)
+
+        (YAML.safe_load_file(path)[section] || {}).size
+      end
+    end
+  end
+end

data/lib/generators/poetry/block/block_generator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "yaml"
+
+module Poetry
+  # `rails g poetry:block <name>` - copies a vetted composed
+  # screen into the app as source the app OWNS. Blocks are starting points
+  # an agent (or a person) edits, not components it configures: the file
+  # lands under app/views/blocks/ as a partial, the sample content is meant
+  # to be replaced in place, and `poetry check` keeps validating the result
+  # like any other template. `--list` (or no argument) prints the catalog
+  # from the registry's blocks section.
+  #
+  # @example
+  #   bin/rails g poetry:block login-form
+  class BlockGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    argument :block_name, type: :string, required: false,
+                          banner: "block-name", desc: "the block to copy in (see --list)"
+    class_option :list, type: :boolean, default: false, desc: "list the available blocks"
+
+    desc "Copy a vetted poetry block (a composed screen) into app/views/blocks/ as app-owned source"
+
+    # The header stamped on every copied block: names the generating
+    # command and hands ownership to the app.
+    OWNERSHIP_HEADER = "<%%# generated by `bin/rails g poetry:block %<name>s` - this file is yours: " \
+                       "rename, move, and edit freely (sample content is meant to be replaced). " \
+                       "Catalog: /poetry/llms.txt; verify edits with poetry check. %%>"
+
+    # Step: copies the named block (or prints the catalog with --list).
+    # @api private
+    def copy_block
+      return print_catalog if options[:list] || block_name.nil?
+
+      name = block_name.tr("_", "-")
+      entry = catalog[name]
+      unless entry
+        say_status :error, "unknown block #{name.inspect}", :red
+        print_catalog
+        raise Thor::Error, "unknown block #{name.inspect}"
+      end
+
+      source = Poetry::Ui.root.join(entry.fetch("template")).read
+      body = source.sub(/\A<%#\s*poetry:block[^%]*%>\n?/, "")
+      header = format(OWNERSHIP_HEADER, name: name)
+      create_file "app/views/blocks/_#{name.tr("-", "_")}.html.erb", "#{header}\n#{body}"
+      say_status :render, "<%= render \"blocks/#{name.tr("-", "_")}\" %>", :blue
+    end
+
+    private
+
+    def catalog
+      @catalog ||= YAML.safe_load_file(
+        Poetry::Ui.root.join(Poetry::Core::Registry::RELATIVE_PATH)
+      )["blocks"] || {}
+    end
+
+    def print_catalog
+      say "poetry blocks (bin/rails g poetry:block <name>):"
+      catalog.each do |name, entry|
+        say "  #{name.ljust(18)} #{entry["title"]} - #{entry["description"]}"
+      end
+    end
+  end
+end

data/lib/generators/poetry/block/templates/action_bar.html.erb

@@ -0,0 +1,45 @@
+<%# poetry:block title="Action bar" description="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." keywords="bulk, selection, batch, actions, action bar, selected, archive, delete rows, multi-select, table actions" %>
+<%# ActionBar is a BLOCK, not a component: the bar
+    is plain markup wired to two small engines - the data_table's
+    selectable: engine dispatches selection-change, and the bar's
+    controller shows/hides on it, retains the last non-zero count while
+    animating out, announces "Actions available." once per appearance,
+    and Escape anywhere inside clears the selection. The wrapper div
+    PAIRS them positionally (shared parent) - no id contract. Swap the
+    sample actions for your bulk endpoints: the checkboxes are real form
+    values (selected_ids[]), so a wrapping form_with posts them as-is. %>
+<% invoice = Struct.new(:id, :number, :customer, :amount) %>
+<% rows = local_assigns[:rows] || [
+     invoice.new(1, "INV-001", "Acme", "$250.00"),
+     invoice.new(2, "INV-002", "Globex", "$1,150.00"),
+     invoice.new(3, "INV-003", "Initech", "$420.00")
+   ] %>
+<% state = Poetry::Ui::DataTable::State.from_params(params, sortable: %w[number customer]) %>
+<div class="relative mx-auto max-w-3xl pb-16">
+  <%= poetry_data_table(rows: rows, state: state, path: ->(p) { "?#{p.to_query}" },
+                        caption: "Recent invoices.",
+                        selectable: ->(row) { row.id }) do |table| %>
+    <% table.with_column("Invoice", key: :number, sortable: true) { |row| row.number } %>
+    <% table.with_column("Customer", key: :customer, sortable: true) { |row| row.customer } %>
+    <% table.with_column("Amount", classes: "text-right") { |row| row.amount } %>
+  <% end %>
+  <div hidden
+       data-controller="poetry--core--action-bar"
+       data-poetry--core--action-bar-label-value="%{count} selected"
+       data-available-label="Actions available."
+       data-action="keydown->poetry--core--action-bar#keydown"
+       data-slot="action-bar"
+       class="absolute inset-x-8 bottom-2 z-10 mx-auto flex max-w-xl items-center gap-3 rounded-lg border bg-popover px-4 py-2 text-popover-foreground shadow-lg transition-[opacity,translate] data-open:translate-y-0 data-open:opacity-100 not-data-open:translate-y-2 not-data-open:opacity-0">
+    <span data-slot="action-bar-count" class="text-sm font-medium tabular-nums"
+          data-poetry--core--action-bar-target="count"></span>
+    <span class="ms-auto flex items-center gap-2" data-slot="action-bar-actions" aria-label="Actions">
+      <%= poetry_button(variant: :outline, size: :sm) { "Export" } %>
+      <%= poetry_button(variant: :destructive, size: :sm) { "Archive" } %>
+    </span>
+    <%= poetry_button(variant: :ghost, size: :"icon-sm", label: "Clear selection",
+                      "data-slot": "action-bar-clear",
+                      data: { action: "click->poetry--core--action-bar#clear" }) do %>
+      <%= poetry_icon(name: :x) %>
+    <% end %>
+  </div>
+</div>

data/lib/generators/poetry/block/templates/app_shell.html.erb

@@ -0,0 +1,139 @@
+<%# poetry:block title="App shell" description="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." keywords="dashboard, shell, layout, sidebar, workspace, admin, console, overview, stats, chrome" %>
+<%= poetry_sidebar(collapsible: :icon) do |shell| %>
+  <% shell.with_nav do %>
+    <%= poetry_sidebar_header do %>
+      <%# The collapse-aware header shape (a menu button, never a bare
+          div): at icon width the button shrinks to the tile and the
+          truncating spans disappear with it. %>
+      <%= poetry_sidebar_menu do %>
+        <%= poetry_sidebar_menu_item do %>
+          <%= poetry_sidebar_menu_button(size: :lg) do %>
+            <div class="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+              <%= poetry_icon(name: :"audio-waveform", class: "size-4") %>
+            </div>
+            <div class="grid flex-1 text-left text-sm leading-tight">
+              <span class="truncate font-semibold">Meridian</span>
+              <span class="truncate text-xs">Operations</span>
+            </div>
+          <% end %>
+        <% end %>
+      <% end %>
+    <% end %>
+    <%= poetry_sidebar_content do %>
+      <%= poetry_sidebar_group do %>
+        <%= poetry_sidebar_group_label { "Platform" } %>
+        <%= poetry_sidebar_menu do %>
+          <%= poetry_sidebar_menu_item do %>
+            <%= poetry_sidebar_menu_button(href: "/dashboard", active: true) do %>
+              <%= poetry_icon(name: :"layout-dashboard") %><span>Dashboard</span>
+            <% end %>
+          <% end %>
+          <%= poetry_sidebar_menu_item do %>
+            <%= poetry_sidebar_menu_button(href: "/orders") do %>
+              <%= poetry_icon(name: :package) %><span>Orders</span>
+            <% end %>
+            <%= poetry_sidebar_menu_badge do %>12<% end %>
+          <% end %>
+          <%= poetry_sidebar_menu_item do %>
+            <%= poetry_sidebar_menu_button(href: "/customers") do %>
+              <%= poetry_icon(name: :users) %><span>Customers</span>
+            <% end %>
+          <% end %>
+        <% end %>
+      <% end %>
+      <%= poetry_sidebar_group do %>
+        <%= poetry_sidebar_group_label { "Resources" } %>
+        <%= poetry_sidebar_menu do %>
+          <%= poetry_sidebar_menu_item do %>
+            <%= poetry_sidebar_menu_button(href: "/docs") do %>
+              <%= poetry_icon(name: :"book-open") %><span>Documentation</span>
+            <% end %>
+          <% end %>
+          <%= poetry_sidebar_menu_item do %>
+            <%= poetry_sidebar_menu_button(href: "/support") do %>
+              <%= poetry_icon(name: :"life-buoy") %><span>Support</span>
+            <% end %>
+          <% end %>
+        <% end %>
+      <% end %>
+    <% end %>
+    <%= poetry_sidebar_footer do %>
+      <%# The footer rides the same collapse-aware shape as the header: at
+          icon width the menu button shrinks to the avatar tile and the
+          truncating spans clip with it instead of spilling into the inset. %>
+      <%= poetry_sidebar_menu do %>
+        <%= poetry_sidebar_menu_item do %>
+          <% profile = "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA2NCA2NCI+PGRlZnM+PGxpbmVhckdyYWRpZW50IGlkPSJnIiB4MT0iMCIgeTE9IjAiIHgyPSIxIiB5Mj0iMSI+PHN0b3Agb2Zmc2V0PSIwIiBzdG9wLWNvbG9yPSIjNjM2NmYxIi8+PHN0b3Agb2Zmc2V0PSIuNTUiIHN0b3AtY29sb3I9IiM4YjVjZjYiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNlYzQ4OTkiLz48L2xpbmVhckdyYWRpZW50PjwvZGVmcz48cmVjdCB3aWR0aD0iNjQiIGhlaWdodD0iNjQiIGZpbGw9InVybCgjZykiLz48Y2lyY2xlIGN4PSIzMiIgY3k9IjI1IiByPSIxMCIgZmlsbD0iI2ZmZiIgb3BhY2l0eT0iLjkiLz48cGF0aCBkPSJNMTIgNjRjMi0xMyAxMC0xOSAyMC0xOXMxOCA2IDIwIDE5eiIgZmlsbD0iI2ZmZiIgb3BhY2l0eT0iLjkiLz48L3N2Zz4=" %>
+          <%= poetry_sidebar_menu_button(size: :lg) do %>
+            <%= poetry_avatar(src: profile, label: "Matt Solt", class: "size-8 rounded-lg") { "MS" } %>
+            <div class="grid flex-1 text-left text-sm leading-tight">
+              <span class="truncate font-semibold">Matt Solt</span>
+              <span class="truncate text-xs">matt@roboruby.com</span>
+            </div>
+          <% end %>
+        <% end %>
+      <% end %>
+    <% end %>
+    <%= poetry_sidebar_rail %>
+  <% end %>
+  <% shell.with_inset do %>
+    <header class="flex h-14 shrink-0 items-center gap-2 border-b px-4 transition-[height] group-has-data-[collapsible=icon]/sidebar-wrapper:h-12">
+      <%= poetry_sidebar_trigger %>
+      <%= poetry_separator(orientation: :vertical, class: "h-4") %>
+      <%= poetry_breadcrumb do |crumb| %>
+        <% crumb.with_item("Meridian", href: "/") %>
+        <% crumb.with_item("Dashboard") %>
+      <% end %>
+    </header>
+    <div class="flex flex-col gap-6 p-6">
+      <div class="flex flex-wrap items-end justify-between gap-4">
+        <div class="space-y-1">
+          <h1 class="text-2xl font-semibold tracking-tight">Dashboard</h1>
+          <p class="text-sm text-muted-foreground">Today across the Meridian workspace.</p>
+        </div>
+        <%= poetry_button(variant: :outline) do |button| %>
+          <% button.with_leading { poetry_icon(name: :download) } %>
+          Export
+        <% end %>
+      </div>
+      <div class="grid gap-4 md:grid-cols-3">
+        <%= poetry_card(title_tag: :h2) do |card| %>
+          <% card.with_title { "Revenue" } %>
+          <% card.with_description { "Last 30 days" } %>
+          <div class="text-2xl font-semibold tabular-nums">$48,210</div>
+          <p class="text-xs text-muted-foreground">+12.4% from the previous period</p>
+        <% end %>
+        <%= poetry_card(title_tag: :h2) do |card| %>
+          <% card.with_title { "Open orders" } %>
+          <% card.with_description { "Awaiting fulfillment" } %>
+          <div class="text-2xl font-semibold tabular-nums">42</div>
+          <p class="text-xs text-muted-foreground">12 due before Friday</p>
+        <% end %>
+        <%= poetry_card(title_tag: :h2) do |card| %>
+          <% card.with_title { "On-time rate" } %>
+          <% card.with_description { "Trailing quarter" } %>
+          <div class="text-2xl font-semibold tabular-nums">98.2%</div>
+          <p class="text-xs text-muted-foreground">Target is 97.5%</p>
+        <% end %>
+      </div>
+      <%= poetry_card(title_tag: :h2) do |card| %>
+        <% card.with_title { "Recent activity" } %>
+        <% card.with_description { "The latest changes across orders and customers." } %>
+        <ul class="space-y-3 text-sm">
+          <li class="flex items-center justify-between gap-4">
+            <span>ORD-1042 marked fulfilled by Matt</span>
+            <span class="text-xs text-muted-foreground tabular-nums">2m ago</span>
+          </li>
+          <li class="flex items-center justify-between gap-4">
+            <span>Northwind Traders added a shipping address</span>
+            <span class="text-xs text-muted-foreground tabular-nums">18m ago</span>
+          </li>
+          <li class="flex items-center justify-between gap-4">
+            <span>Refund approved for ORD-1040</span>
+            <span class="text-xs text-muted-foreground tabular-nums">1h ago</span>
+          </li>
+        </ul>
+      <% end %>
+    </div>
+  <% end %>
+<% end %>

data/lib/generators/poetry/block/templates/data_index.html.erb

@@ -0,0 +1,85 @@
+<%# poetry:block title="Data index" description="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." keywords="index, list, listing, table, records, directory, filter, pagination, management, browse, catalog" %>
+<section class="space-y-4">
+  <div class="flex flex-wrap items-end justify-between gap-4">
+    <div class="space-y-1">
+      <h2 class="text-lg font-semibold tracking-tight">Orders</h2>
+      <p class="text-sm text-muted-foreground">Fulfillment status across every open order.</p>
+    </div>
+    <%= poetry_button do |button| %>
+      <% button.with_leading { poetry_icon(name: :plus) } %>
+      New order
+    <% end %>
+  </div>
+  <div class="flex flex-wrap items-center gap-3">
+    <%= poetry_label(for_id: "orders-search", class: "sr-only") { "Search orders" } %>
+    <%= poetry_input_group(class: "max-w-xs") do %>
+      <%= poetry_input_group_addon do %>
+        <%= poetry_icon(name: :search) %>
+      <% end %>
+      <%= poetry_input_group_input(id: "orders-search", name: "q", placeholder: "Search orders…") %>
+    <% end %>
+    <%= poetry_label(for_id: "orders-status", class: "sr-only") { "Filter by status" } %>
+    <%= poetry_native_select(name: "status", id: "orders-status",
+                             options: [["All statuses", "all"], ["Fulfilled", "fulfilled"],
+                                       ["Processing", "processing"], ["Refunded", "refunded"]]) %>
+    <%= poetry_button_group("aria-label": "Layout", class: "ml-auto") do %>
+      <%= poetry_button(variant: :outline, size: :sm, "aria-pressed": "true") { "List" } %>
+      <%= poetry_button(variant: :outline, size: :sm, "aria-pressed": "false") { "Board" } %>
+    <% end %>
+  </div>
+  <div class="overflow-hidden rounded-lg border">
+    <%= poetry_table do %>
+      <%= poetry_table_caption(class: "sr-only") { "Open orders with customer, status, and total." } %>
+      <%= poetry_table_header do %>
+        <%= poetry_table_row do %>
+          <%= poetry_table_head { "Order" } %>
+          <%= poetry_table_head { "Customer" } %>
+          <%= poetry_table_head { "Status" } %>
+          <%= poetry_table_head(class: "text-right") { "Total" } %>
+        <% end %>
+      <% end %>
+      <%= poetry_table_body do %>
+        <%= poetry_table_row do %>
+          <%= poetry_table_cell(class: "font-medium") { "ORD-1042" } %>
+          <%= poetry_table_cell { "Northwind Traders" } %>
+          <%= poetry_table_cell { poetry_badge(variant: :success) { "Fulfilled" } } %>
+          <%= poetry_table_cell(class: "text-right tabular-nums") { "$1,250.00" } %>
+        <% end %>
+        <%= poetry_table_row do %>
+          <%= poetry_table_cell(class: "font-medium") { "ORD-1041" } %>
+          <%= poetry_table_cell { "Lumen Labs" } %>
+          <%= poetry_table_cell { poetry_badge(variant: :warning) { "Processing" } } %>
+          <%= poetry_table_cell(class: "text-right tabular-nums") { "$482.50" } %>
+        <% end %>
+        <%= poetry_table_row do %>
+          <%= poetry_table_cell(class: "font-medium") { "ORD-1040" } %>
+          <%= poetry_table_cell { "Aperture Optics" } %>
+          <%= poetry_table_cell { poetry_badge(variant: :outline) { "Refunded" } } %>
+          <%= poetry_table_cell(class: "text-right tabular-nums") { "$96.00" } %>
+        <% end %>
+        <%= poetry_table_row do %>
+          <%= poetry_table_cell(class: "font-medium") { "ORD-1039" } %>
+          <%= poetry_table_cell { "Gable & Sons" } %>
+          <%= poetry_table_cell { poetry_badge(variant: :warning) { "Processing" } } %>
+          <%= poetry_table_cell(class: "text-right tabular-nums") { "$2,040.00" } %>
+        <% end %>
+        <%= poetry_table_row do %>
+          <%= poetry_table_cell(class: "font-medium") { "ORD-1038" } %>
+          <%= poetry_table_cell { "Fern & Field" } %>
+          <%= poetry_table_cell { poetry_badge(variant: :success) { "Fulfilled" } } %>
+          <%= poetry_table_cell(class: "text-right tabular-nums") { "$318.75" } %>
+        <% end %>
+      <% end %>
+      <%= poetry_table_footer do %>
+        <%= poetry_table_row do %>
+          <%= poetry_table_cell(colspan: 3) { "Total" } %>
+          <%= poetry_table_cell(class: "text-right tabular-nums") { "$4,187.25" } %>
+        <% end %>
+      <% end %>
+    <% end %>
+  </div>
+  <div class="flex flex-wrap items-center justify-between gap-4">
+    <p class="text-sm text-muted-foreground">Showing 5 of 42 orders</p>
+    <%= poetry_pagination(current: 3, total: 9, current_variant: :filled, path: ->(page) { "?page=#{page}" }) %>
+  </div>
+</section>

data/lib/generators/poetry/block/templates/destructive_panel.html.erb

@@ -0,0 +1,26 @@
+<%# poetry:block title="Destructive panel" description="A guarded destructive action: heading and consequences in plain language, a severity-tinted alert with the blast radius, and a cancel/confirm action pair." keywords="deletion, deactivate, irreversible, permanently" %>
+<%# Page framing: the panel keeps its container + breathing room when it
+    is the page's subject (a judged-run lesson); drop the outer wrapper
+    when composing into an already-padded frame. %>
+<div class="mx-auto max-w-xl p-6">
+  <section class="space-y-4 rounded-lg border border-destructive/50 p-6" aria-labelledby="destructive-panel-title">
+    <div class="space-y-1">
+      <h2 id="destructive-panel-title" class="text-base font-semibold">Revoke deploy token</h2>
+      <p class="text-sm text-muted-foreground">The token stops working immediately. Three services signed their last deploy with it — their next runs will fail until a replacement is configured.</p>
+    </div>
+    <%# Icon + title only: an alert DESCRIPTION rides the destructive tint,
+        which sits at 4.49:1 on white (the standing token-retune ledger) -
+        the blast radius lives in the AA-clean muted copy above instead. %>
+    <%= poetry_alert(variant: :destructive) do |alert| %>
+      <% alert.with_icon(name: "triangle-alert") %>
+      <% alert.with_title { "This cannot be undone" } %>
+    <% end %>
+    <div class="flex items-center justify-end gap-2">
+      <%= poetry_button(variant: :outline) { "Cancel" } %>
+      <%= poetry_button(variant: :destructive) do |button| %>
+        <% button.with_leading { poetry_icon(name: :trash) } %>
+        Revoke token
+      <% end %>
+    </div>
+  </section>
+</div>

data/lib/generators/poetry/block/templates/page_header.html.erb

@@ -0,0 +1,25 @@
+<%# poetry:block title="Page header" description="The furniture a screen opens with: breadcrumb trail, page title with supporting description, and a right-aligned action group over a grounding rule." keywords="header, breadcrumb" %>
+<header class="flex flex-col gap-4">
+  <%= poetry_breadcrumb do |crumb| %>
+    <% crumb.with_item("Home", href: "/") %>
+    <% crumb.with_item("Projects", href: "/projects") %>
+    <% crumb.with_item("Atlas") %>
+  <% end %>
+  <div class="flex flex-wrap items-end justify-between gap-4">
+    <div class="space-y-1">
+      <h1 class="text-2xl font-semibold tracking-tight">Atlas</h1>
+      <p class="text-sm text-muted-foreground">Shipping schedules, owners, and release health for the Atlas program.</p>
+    </div>
+    <div class="flex items-center gap-2">
+      <%= poetry_button(variant: :outline) do |button| %>
+        <% button.with_leading { poetry_icon(name: :download) } %>
+        Export
+      <% end %>
+      <%= poetry_button do |button| %>
+        <% button.with_leading { poetry_icon(name: :plus) } %>
+        New project
+      <% end %>
+    </div>
+  </div>
+  <%= poetry_separator %>
+</header>

data/lib/generators/poetry/block/templates/section_card.html.erb

@@ -0,0 +1,42 @@
+<%# poetry:block title="Section card" description="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." keywords="settings, section, panel, account, detail, summary, form" %>
+<%# Page framing: a section keeps its container + breathing room when it is
+    the page's subject - a bare card at the viewport origin reads cramped
+    (a judged-run lesson). Drop the wrapper only when composing into an
+    already-padded frame like the app-shell content area. %>
+<div class="mx-auto max-w-md p-6">
+  <%= poetry_card do |card| %>
+    <% card.with_title { "Usage-based billing" } %>
+    <% card.with_description { "Meter API calls and storage, invoiced monthly." } %>
+    <% card.with_action do %>
+      <%= poetry_badge(variant: :secondary) { "Beta" } %>
+    <% end %>
+    <% card.with_footer do %>
+      <div class="flex w-full items-center justify-between gap-4">
+        <span class="text-xs text-muted-foreground">Updated 2 days ago</span>
+        <%# The CTA reads as interactive (v1.1): always-underlined with a
+            trailing arrow - the affordance the judged card pairs kept
+            rewarding. %>
+        <%= poetry_link(href: "/docs/billing", underline: :always, class: "inline-flex items-center gap-1") do %>
+          Learn more <%= poetry_icon(name: :"arrow-right", class: "size-3.5") %>
+        <% end %>
+      </div>
+    <% end %>
+    <div class="space-y-3 text-sm">
+      <p>Pay for what the workspace actually uses. Metering runs hourly and the invoice line items match the usage dashboard.</p>
+      <ul class="space-y-2">
+        <li class="flex items-center gap-2">
+          <%= poetry_icon(name: :check, class: "size-4 text-muted-foreground") %>
+          <span>Per-request API metering</span>
+        </li>
+        <li class="flex items-center gap-2">
+          <%= poetry_icon(name: :check, class: "size-4 text-muted-foreground") %>
+          <span>Storage billed by the gigabyte-hour</span>
+        </li>
+        <li class="flex items-center gap-2">
+          <%= poetry_icon(name: :check, class: "size-4 text-muted-foreground") %>
+          <span>Spend alerts before every threshold</span>
+        </li>
+      </ul>
+    </div>
+  <% end %>
+</div>