unmagic-components 0.3.0 → 0.4.0

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/skeleton/_blocking_out.html.erb

@@ -0,0 +1,25 @@
+<div class="grid items-start gap-6 sm:grid-cols-2">
+  <%= card do %>
+    <div class="flex items-center gap-3">
+      <div class="size-12 shrink-0 rounded-full bg-indigo-200"></div>
+      <div class="min-w-0 flex-1">
+        <div class="font-semibold">Ada Lovelace</div>
+        <div>Engineer · London</div>
+      </div>
+    </div>
+    <p class="mt-3 mb-0">Wrote the first published algorithm for a machine, and saw it could reach beyond arithmetic.</p>
+  <% end %>
+
+  <%= card do %>
+    <%= skeleton label: "Loading candidate" do |s| %>
+      <div class="flex items-center gap-3">
+        <%= s.circle size: "3rem" %>
+        <div class="min-w-0 flex-1">
+          <div class="font-semibold"><%= s.text width: "60%" %></div>
+          <%= s.text width: "40%" %>
+        </div>
+      </div>
+      <p class="mt-3 mb-0"><%= s.text lines: 2 %></p>
+    <% end %>
+  <% end %>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/skeleton/_card.html.erb

@@ -0,0 +1,7 @@
+<div class="grid items-start gap-6 sm:grid-cols-2">
+  <%= card title: "Members" do %>
+    Ada, Grace and Katherine can see everything in this workspace, invite others, and manage its billing.
+  <% end %>
+
+  <%= card title: "Members", skeleton: true %>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/skeleton/_detail_list.html.erb

@@ -0,0 +1,15 @@
+<div class="grid items-start gap-6 sm:grid-cols-2">
+  <%= detail_list do |list|
+        list.item "Name", "Ada Lovelace"
+        list.item "Role", "Engineer"
+        list.item "Joined", "10 December 1815"
+        list.item "Location", "London"
+      end %>
+
+  <%= detail_list skeleton: true do |list|
+        list.item "Name"
+        list.item "Role"
+        list.item "Joined"
+        list.item "Location"
+      end %>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/skeleton/_page_header.html.erb

@@ -0,0 +1,7 @@
+<div class="grid items-start gap-6 sm:grid-cols-2">
+  <%= page_header title: "Deploy keys", description: "Keys that can pull from this repository." do %>
+    <%= tag.button "Add key", type: "button", class: button_classes(:primary) %>
+  <% end %>
+
+  <%= page_header skeleton: true %>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/skeleton/_text_and_button.html.erb

@@ -0,0 +1,17 @@
+<div class="grid items-start gap-6 sm:grid-cols-2">
+  <div>
+    <p class="m-0">One line of body text.</p>
+    <p class="m-0"><%= skeleton_text width: "45%" %></p>
+    <p class="mt-4 mb-0 text-2xl font-semibold">A larger heading</p>
+    <p class="m-0 text-2xl"><%= skeleton_text width: "60%" %></p>
+  </div>
+
+  <div class="flex flex-wrap items-center gap-2">
+    <%= tag.button "Small", type: "button", class: button_classes(:default, size: :small) %>
+    <%= skeleton_button size: :small %>
+    <%= tag.button "Default", type: "button", class: button_classes %>
+    <%= skeleton_button %>
+    <%= tag.button "Large", type: "button", class: button_classes(:default, size: :large) %>
+    <%= skeleton_button size: :large %>
+  </div>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/skeleton/_thumbnail.html.erb

@@ -0,0 +1,10 @@
+<%= skeleton label: "Loading", class: "grid w-56 gap-3" do |s| %>
+  <div class="flex items-center gap-3">
+    <%= s.circle size: "2rem" %>
+    <div class="min-w-0 flex-1">
+      <%= s.text width: "60%" %>
+      <%= s.text width: "40%" %>
+    </div>
+  </div>
+  <%= s.text lines: 2 %>
+<% end %>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/sortable_list/_connected.html.erb

@@ -0,0 +1,17 @@
+<div class="grid gap-6 sm:grid-cols-2">
+  <% { "Shortlist" => [ "Ada Lovelace", "Grace Hopper", "Alan Turing" ], "Maybe later" => [ "Katherine Johnson" ] }.each do |title, people| %>
+    <div class="rounded-xl border border-neutral-200 p-3 dark:border-neutral-800">
+      <h3 class="mb-2 text-sm font-semibold"><%= title %></h3>
+      <%= sortable_list namespace: "people", label: title, params: { list: title },
+            class: "flex min-h-24 flex-col gap-1.5 rounded-lg p-1 sortable-active:bg-neutral-50 sortable-over:bg-neutral-100 dark:sortable-active:bg-neutral-900 dark:sortable-over:bg-neutral-800" do |list| %>
+        <% people.each do |person| %>
+          <%= list.item(key: person.parameterize, label: person) do %>
+            <div class="flex cursor-grab items-center gap-2 rounded-md bg-white p-2 text-sm shadow-xs dark:bg-neutral-900">
+              <%= avatar person, size: :small, "aria-hidden": true %> <%= person %>
+            </div>
+          <% end %>
+        <% end %>
+      <% end %>
+    </div>
+  <% end %>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/sortable_list/_grid.html.erb

@@ -0,0 +1,20 @@
+<%# Written out in full, since Tailwind can only generate classes it can read. %>
+<% tiles = [
+     "bg-sky-100 text-sky-800 dark:bg-sky-400/15 dark:text-sky-300",
+     "bg-emerald-100 text-emerald-800 dark:bg-emerald-400/15 dark:text-emerald-300",
+     "bg-amber-100 text-amber-800 dark:bg-amber-400/15 dark:text-amber-300",
+     "bg-rose-100 text-rose-800 dark:bg-rose-400/15 dark:text-rose-300",
+     "bg-violet-100 text-violet-800 dark:bg-violet-400/15 dark:text-violet-300",
+     "bg-teal-100 text-teal-800 dark:bg-teal-400/15 dark:text-teal-300",
+     "bg-orange-100 text-orange-800 dark:bg-orange-400/15 dark:text-orange-300",
+     "bg-lime-100 text-lime-800 dark:bg-lime-400/15 dark:text-lime-300"
+   ] %>
+<%= sortable_list orientation: :grid, label: "Screenshots", class: "grid grid-cols-2 gap-3 sm:grid-cols-4" do |list| %>
+  <% tiles.each_with_index do |colours, index| %>
+    <%= list.item(key: "shot-#{index}", rank: index + 1, label: "Screenshot #{index + 1}") do %>
+      <div class="grid aspect-video cursor-grab place-items-center rounded-lg text-sm font-medium <%= colours %>">
+        Screenshot <%= index + 1 %>
+      </div>
+    <% end %>
+  <% end %>
+<% end %>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/sortable_list/_handles.html.erb

@@ -0,0 +1,22 @@
+<div class="w-96 max-w-full">
+  <%= sortable_list id: "steps", label: "Interview steps", class: "flex flex-col gap-2" do |list| %>
+    <% [ "Phone screen", "Take-home exercise", "Pairing session", "Meet the team" ].each_with_index do |step, index| %>
+      <%= list.item(key: "step-#{index}", rank: index + 1, label: step) do %>
+        <div class="flex items-center gap-2 rounded-lg border border-neutral-200 bg-white px-2 py-1.5 text-sm dark:border-neutral-800 dark:bg-neutral-900">
+          <%= sortable_handle label: "Move #{step}" %>
+          <span class="flex-1"><%= step %></span>
+          <button type="button" class="<%= button_classes(:icon) %>" aria-label="Edit <%= step %>" title="Edit">
+            <%= Unmagic::Components::Icons.svg(self, :pencil) %>
+          </button>
+        </div>
+      <% end %>
+    <% end %>
+  <% end %>
+  <output id="steps_log" class="mt-3 block min-h-5 font-mono text-xs text-neutral-500">Drop something to see the move.</output>
+  <script type="module">
+    document.getElementById("steps").addEventListener("unmagic-sortable:move", (event) => {
+      const { key, prev, next } = event.detail
+      document.getElementById("steps_log").textContent = `moved ${key} · prev ${prev || "—"} · next ${next || "—"}`
+    })
+  </script>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/sortable_list/_thumbnail.html.erb

@@ -0,0 +1,7 @@
+<div class="flex w-52 flex-col gap-1.5 text-xs">
+  <% [ "Phone screen", "Take-home", "Pairing" ].each_with_index do |step, index| %>
+    <div class="flex items-center gap-1.5 rounded-md border border-neutral-200 bg-white px-1.5 py-1 dark:border-neutral-800 dark:bg-neutral-900 <%= "opacity-40" if index == 1 %>">
+      <%= Unmagic::Components::Icons.svg(self, :grip_vertical, class: "size-3 text-neutral-400") %><%= step %>
+    </div>
+  <% end %>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/streaming_markdown/_reveal.html.erb

@@ -0,0 +1,19 @@
+<div class="mx-auto max-w-2xl">
+  <button type="button" id="reveal_play" class="<%= button_classes %>">Play</button>
+  <%= streaming_markdown_tag id: "reveal_reply", class: "UnmagicProse mt-4 min-h-40" %>
+  <template id="reveal_flushes">
+    <% Unmagic::Components::Browser::Reply.snapshots.each do |html| %>
+      <template><%= turbo_stream.stream_markdown "reveal_reply", html %></template>
+    <% end %>
+  </template>
+  <script type="module">
+    document.getElementById("reveal_play").addEventListener("click", async () => {
+      const reply = document.getElementById("reveal_reply")
+      reply.replaceChildren()
+      for (const frame of document.getElementById("reveal_flushes").content.children) {
+        await new Promise((resolve) => setTimeout(resolve, 40 + Math.random() * 260))
+        document.body.append(frame.content.cloneNode(true))
+      }
+    })
+  </script>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/streaming_markdown/_stopped.html.erb

@@ -0,0 +1,31 @@
+<div class="mx-auto max-w-2xl">
+  <div class="flex gap-2">
+    <button type="button" id="stopped_play" class="<%= button_classes %>">Play</button>
+    <button type="button" id="stopped_stop" class="<%= button_classes %>">Stop</button>
+  </div>
+  <div id="stopped_holder" class="mt-4 min-h-24">
+    <%= streaming_markdown_tag id: "stopped_reply", class: "UnmagicProse" %>
+  </div>
+  <template id="stopped_final">
+    <%= streaming_markdown_tag id: "stopped_reply", final: true, class: "UnmagicProse" do %>
+      <p class="text-neutral-500">Response stopped.</p>
+    <% end %>
+  </template>
+  <template id="stopped_fresh"><%= streaming_markdown_tag id: "stopped_reply", class: "UnmagicProse" %></template>
+  <template id="stopped_flushes">
+    <% Unmagic::Components::Browser::Reply.snapshots.each do |html| %>
+      <template><%= turbo_stream.stream_markdown "stopped_reply", html %></template>
+    <% end %>
+  </template>
+  <script type="module">
+    const swap = (id) => document.getElementById("stopped_reply").replaceWith(document.getElementById(id).content.cloneNode(true))
+    document.getElementById("stopped_stop").addEventListener("click", () => swap("stopped_final"))
+    document.getElementById("stopped_play").addEventListener("click", async () => {
+      swap("stopped_fresh")
+      for (const frame of document.getElementById("stopped_flushes").content.children) {
+        await new Promise((resolve) => setTimeout(resolve, 60 + Math.random() * 240))
+        document.body.append(frame.content.cloneNode(true))
+      }
+    })
+  </script>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/streaming_markdown/_thumbnail.html.erb

@@ -0,0 +1,5 @@
+<div class="w-60 text-xs">
+  <%= streaming_markdown_tag id: "thumb_stream", class: "UnmagicProse text-xs" do %>
+    <p>Three candidates haven't replied since the invi<span class="animate-pulse">▍</span></p>
+  <% end %>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/table/_deferred.html.erb

@@ -0,0 +1,6 @@
+<%= table_for @things, defer: true, paginate: @pager, id: "preview_table", row_id: ->(thing) { "deferred_thing_#{thing.id}" } do |table| %>
+  <% table.column "Name", :name, width: "34%" %>
+  <% table.column "Role", :role, width: "26%" %>
+  <% table.column "Score", :score, numeric: true, width: "20%" %>
+  <% table.column "Right", :score, align: :right, width: "20%" %>
+<% end %>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/table/_empty.html.erb

@@ -0,0 +1,5 @@
+<%= table_for [], paginate: @pager do |table| %>
+  <% table.empty "No people yet." %>
+  <% table.column "Name", :name %>
+  <% table.column "Role", :role %>
+<% end %>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/table/_sortable.html.erb

@@ -0,0 +1,8 @@
+<%= table_for @things, paginate: @pager do |table| %>
+  <% table.column "Name", :name, sort: :name, width: "34%" %>
+  <% table.column "Role", :role, sort: :role, width: "22%" %>
+  <% table.column "Score", :score, numeric: true, width: "14%" %>
+  <% table.column "Centred", :role, align: :center, width: "16%" %>
+  <% table.column "Right", :score, align: :right, width: "14%" %>
+  <% table.details { |thing| thing.note } %>
+<% end %>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/table/_table_tag.html.erb

@@ -0,0 +1,4 @@
+<%= table_tag [ "Metric", "Value" ],
+      [ [ "Requests", { content: "1,204", class: "is-right is-numeric" } ],
+        [ "Errors", { content: "3", class: "is-right is-numeric" } ] ],
+      widths: [ "70%", "30%" ] %>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/table/_thumbnail.html.erb

@@ -0,0 +1,4 @@
+<%= table_tag [ "Name", "Score" ],
+      [ [ "Ada Lovelace", { content: "120", class: "is-right is-numeric" } ],
+        [ "Grace Hopper", { content: "98", class: "is-right is-numeric" } ] ],
+      class: "w-56 text-xs" %>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/tabs/_links.html.erb

@@ -0,0 +1,5 @@
+<%= tabs do |tabs| %>
+  <% tabs.tab "Tabs", href: component_path("tabs"), active: true %>
+  <% tabs.tab "Menu", href: component_path("menu") %>
+  <% tabs.tab "Archived", disabled: true %>
+<% end %>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/tabs/_panels.html.erb

@@ -0,0 +1,18 @@
+<%= tabs id: "preview_tabs" do |tabs| %>
+  <% tabs.tab "Body" %>
+  <% tabs.tab "Headers" %>
+  <% tabs.tab "Preview", disabled: "HTML only" %>
+  <% tabs.tab "Timing" %>
+  <% tabs.panel do %>
+    <pre class="m-0">{ "ok": true }</pre>
+  <% end %>
+  <% tabs.panel do %>
+    <%= detail_list do |list| %>
+      <% list.item "Content-Type", "application/json" %>
+      <% list.item "Cache-Control", "no-store" %>
+    <% end %>
+  <% end %>
+  <% tabs.panel do %>
+    Took 42ms.
+  <% end %>
+<% end %>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/tabs/_thumbnail.html.erb

@@ -0,0 +1,5 @@
+<%= tabs class: "text-xs" do |tabs| %>
+  <% tabs.tab "View all", href: "#", active: true %>
+  <% tabs.tab "Active", href: "#" %>
+  <% tabs.tab "Archived", href: "#" %>
+<% end %>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/toast/_above_dialog.html.erb

@@ -0,0 +1,10 @@
+<%= dialog_button "Open a dialog", dialog: "toast_over_dialog", class: button_classes %>
+
+<%= dialog_tag "toast_over_dialog", title: "A dialog" do %>
+  <p>
+    A toast streamed from in here shows above the dialog, not under its backdrop. It can't be
+    hovered or dismissed until the dialog closes, but it still times out on its own.
+  </p>
+  <%= button_to "Stream a toast", stream_toast_path, params: { tone: "info", message: "Above the dialog." },
+        class: button_classes(:primary) %>
+<% end %>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/toast/_flash.html.erb

@@ -0,0 +1,13 @@
+<div class="flex flex-wrap gap-2">
+  <%= button_to "Notice", flash_toast_path, params: { type: "notice", message: "Changes saved." },
+        class: button_classes(:primary) %>
+  <%= button_to "Alert", flash_toast_path, params: { type: "alert", message: "Couldn't save your changes." },
+        class: button_classes %>
+  <%= button_to "Warning", flash_toast_path, params: { type: "warning", message: "Your trial ends in 3 days." },
+        class: button_classes %>
+  <%= button_to "Info", flash_toast_path, params: { type: "info", message: "A new version is available." },
+        class: button_classes %>
+  <%= button_to "Long", flash_toast_path,
+        params: { type: "notice", message: "Imported 1,204 contacts from contacts-export-2026-09-16-final-final.csv into the Sales pipeline." },
+        class: button_classes %>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/toast/_stream.html.erb

@@ -0,0 +1,6 @@
+<div class="flex flex-wrap gap-2">
+  <%= button_to "Stream a toast", stream_toast_path, params: { tone: "good", message: "Copied to your clipboard." },
+        class: button_classes %>
+  <%= button_to "Stream a bad toast", stream_toast_path, params: { tone: "bad", message: "Couldn't reach Slack." },
+        class: button_classes(:danger) %>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/toast/_thumbnail.html.erb

@@ -0,0 +1,10 @@
+<%# A static stand-in: a real toast only shows once <unmagic-toasts> opens it. %>
+<div class="flex w-60 flex-col gap-2 text-xs">
+  <% { good: "Changes saved.", bad: "Couldn't reach Slack." }.each do |tone, message| %>
+    <%= tag.div class: "UnmagicToast UnmagicToast--#{tone}", data: { open: "" } do %>
+      <%= Unmagic::Components::Icons.svg(self, Unmagic::Components::Icons::TONE_ICONS.fetch(tone),
+            class: "UnmagicToast__icon size-3.5") %>
+      <%= tag.div message, class: "UnmagicToast__message" %>
+    <% end %>
+  <% end %>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/tooltip/_placement.html.erb

@@ -0,0 +1,8 @@
+<div class="flex flex-wrap justify-between gap-2">
+  <%= tooltip text: "Shown below, flipping above when there's no room.", placement: :bottom do %>
+    <button type="button" class="<%= button_classes %>">placement: :bottom</button>
+  <% end %>
+  <%= tooltip text: "Clamped so it never runs off the edge of the screen, however long the hint happens to get." do %>
+    <button type="button" class="<%= button_classes %>">Near the right edge</button>
+  <% end %>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/tooltip/_term.html.erb

@@ -0,0 +1,5 @@
+<p class="m-0">
+  Every page declares a
+  <%= tooltip "canonical URL", text: "The address search engines treat as the original when the same page is reachable at several." %>
+  in its head.
+</p>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/examples/tooltip/_thumbnail.html.erb

@@ -0,0 +1,5 @@
+<%# A static open hint: the real one is a popover the element shows on hover. %>
+<div class="flex flex-col items-center gap-1.5">
+  <span class="UnmagicTooltip__popup static opacity-100" data-open>Copy the key</span>
+  <%= tag.span "Copy", class: button_classes(:default, size: :small) %>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/pages/component.html.erb

@@ -0,0 +1,58 @@
+<% content_for :title, @component.name %>
+<% content_for :breadcrumbs do %>
+  <%= render "crumb", label: @component.group || "Components", path: root_path %>
+  <%= render "crumb", label: @component.name %>
+<% end %>
+
+<% position = @components.index(@component) %>
+<% previous_component = @components[position - 1] if position.positive? %>
+<% next_component = @components[position + 1] %>
+
+<div class="xl:grid xl:grid-cols-[minmax(0,1fr)_12rem] xl:gap-12">
+  <article class="min-w-0">
+    <header class="mb-12">
+      <h1 class="text-3xl font-semibold tracking-tight"><%= @component.name %></h1>
+      <p class="mt-3 max-w-2xl text-base leading-7 text-neutral-600 dark:text-neutral-400"><%= @component.description %></p>
+      <div class="mt-5 flex flex-wrap items-center gap-2">
+        <%= badge tag.code(@component.helper) if @component.helper %>
+        <%= badge tag.code(%(import "#{@component.import}")) if @component.import %>
+        <%= badge pluralize(@component.examples.size, "example") %>
+      </div>
+    </header>
+
+    <div class="space-y-14">
+      <% @component.examples.each do |example| %>
+        <%= render "example", component: @component, example: example %>
+      <% end %>
+    </div>
+
+    <nav class="mt-16 grid gap-4 border-t border-neutral-200 pt-8 sm:grid-cols-2 dark:border-neutral-800" aria-label="More components">
+      <% pager = "block rounded-xl border border-neutral-200 p-4 hover:border-neutral-300 hover:bg-neutral-50 dark:border-neutral-800 dark:hover:border-neutral-700 dark:hover:bg-neutral-900" %>
+      <% if previous_component %>
+        <%= link_to component_path(previous_component.slug), class: pager do %>
+          <span class="block text-xs text-neutral-500">Previous</span>
+          <span class="mt-1 block text-sm font-medium"><%= previous_component.name %></span>
+        <% end %>
+      <% end %>
+      <% if next_component %>
+        <%= link_to component_path(next_component.slug), class: "#{pager} text-right sm:col-start-2" do %>
+          <span class="block text-xs text-neutral-500">Next</span>
+          <span class="mt-1 block text-sm font-medium"><%= next_component.name %></span>
+        <% end %>
+      <% end %>
+    </nav>
+  </article>
+
+  <aside class="hidden xl:block">
+    <div class="sticky top-24">
+      <p class="text-xs font-semibold text-neutral-500 dark:text-neutral-400">On this page</p>
+      <ul class="mt-3 space-y-1 border-l border-neutral-200 dark:border-neutral-800">
+        <% @component.examples.each do |example| %>
+          <li>
+            <a href="#<%= @component.slug %>_<%= example.key %>" class="-ml-px block border-l border-transparent py-1 pl-3 text-sm text-neutral-600 hover:border-neutral-400 hover:text-neutral-900 dark:text-neutral-400 dark:hover:border-neutral-500 dark:hover:text-neutral-100"><%= example.title %></a>
+          </li>
+        <% end %>
+      </ul>
+    </div>
+  </aside>
+</div>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/pages/installation.html.erb

@@ -0,0 +1,47 @@
+<% content_for :title, "Installation" %>
+<% content_for :breadcrumbs do %>
+  <%= render "crumb", label: "Getting started", path: root_path %>
+  <%= render "crumb", label: "Installation" %>
+<% end %>
+
+<% prose = "mt-3 max-w-2xl text-base leading-7 text-neutral-600 dark:text-neutral-400" %>
+<% step = "mt-12 text-lg font-semibold" %>
+
+<article class="max-w-3xl">
+  <h1 class="text-3xl font-semibold tracking-tight">Installation</h1>
+  <p class="<%= prose %>">
+    Add the gem, import its styles into your Tailwind build, and import its JavaScript. The helpers are
+    mixed into your views automatically.
+  </p>
+
+  <h2 class="<%= step %>">1. Add the gem</h2>
+  <div class="mt-4"><%= render "code", id: "install_gem", source: "bundle add unmagic-components" %></div>
+
+  <h2 class="<%= step %>">2. Import the styles</h2>
+  <p class="<%= prose %>">
+    The components are styled with Tailwind CSS v4, which your app needs. With tailwindcss-rails, import the
+    gem's styles after Tailwind in <code>app/assets/tailwind/application.css</code>:
+  </p>
+  <div class="mt-4">
+    <%= render "code", id: "install_tailwind", source: %(@import "tailwindcss";\n@import "../builds/tailwind/unmagic_components";) %>
+  </div>
+  <p class="<%= prose %>">
+    tailwindcss-rails writes that entry file on every build. With the Tailwind CLI or an npm build, import
+    <code>app/assets/tailwind/unmagic_components/engine.css</code> from the gem's install path
+    (<code>bundle show unmagic-components</code>) instead.
+  </p>
+
+  <h2 class="<%= step %>">3. Import the JavaScript</h2>
+  <p class="<%= prose %>">
+    With importmap-rails the engine pins every component. Import them all, or only the ones a page uses:
+  </p>
+  <div class="mt-4">
+    <%= render "code", id: "install_js", source: %(import "unmagic/components"\n\n// or one at a time\nimport "unmagic/components/menu") %>
+  </div>
+
+  <h2 class="<%= step %>">4. Use the form builder</h2>
+  <p class="<%= prose %>">Pass it per form, or make it the default for every form:</p>
+  <div class="mt-4">
+    <%= render "code", id: "install_builder", source: "config.action_view.default_form_builder = Unmagic::Components::FormBuilder" %>
+  </div>
+</article>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/pages/overview.html.erb

@@ -0,0 +1,49 @@
+<% content_for :breadcrumbs do %>
+  <%= render "crumb", label: "Components", path: root_path %>
+  <%= render "crumb", label: "Overview" %>
+<% end %>
+
+<section class="max-w-3xl">
+  <h1 class="text-4xl font-semibold tracking-tight">
+    unmagic-components <span class="text-neutral-400 dark:text-neutral-500">for Rails</span>
+  </h1>
+  <p class="mt-5 text-lg leading-8 text-neutral-600 dark:text-neutral-400">
+    Server-rendered UI components for Rails views, in the spirit of <code class="text-base">form_for</code>:
+    describe the columns, the fields or the tabs, and get the chrome. Styled with Tailwind CSS v4, with
+    behaviour from plain custom elements and no Stimulus.
+  </p>
+  <div class="mt-7 flex flex-wrap gap-2">
+    <%= link_to "Installation", installation_path, class: button_classes(:primary) %>
+    <%= link_to "Theming", theming_path, class: button_classes %>
+  </div>
+</section>
+
+<hr class="my-14 border-t border-dashed border-neutral-200 dark:border-neutral-800">
+
+<% @component_groups.each_with_index do |(group, components), index| %>
+  <section class="<%= "mt-16" unless index.zero? %>">
+    <h2 class="text-xl font-semibold"><%= group %></h2>
+    <p class="mt-2 text-sm text-neutral-600 dark:text-neutral-400">
+      <%= pluralize(components.size, "component") %> and <%= pluralize(components.sum { |component| component.examples.size }, "example") %>,
+      each rendered live with its source beside it.
+    </p>
+
+    <div class="mt-8 grid gap-5 sm:grid-cols-2 lg:grid-cols-3 2xl:grid-cols-4">
+      <% components.each do |component| %>
+        <%# The card isn't a link itself: the thumbnail can hold links and buttons of its
+            own, which can't sit inside an <a>. The title's link stretches over the card. %>
+        <div class="group relative overflow-hidden rounded-xl border border-neutral-200 bg-white hover:border-neutral-300 hover:shadow-sm dark:border-neutral-800 dark:bg-neutral-950 dark:hover:border-neutral-700">
+          <div class="flex h-40 items-center justify-center overflow-hidden border-b border-neutral-200 bg-neutral-50 bg-[radial-gradient(var(--color-neutral-200)_1px,transparent_1px)] [background-size:16px_16px] p-5 dark:border-neutral-800 dark:bg-neutral-900/40 dark:bg-[radial-gradient(var(--color-neutral-800)_1px,transparent_1px)]">
+            <div inert class="pointer-events-none flex max-h-full max-w-full select-none items-center justify-center">
+              <%= render partial: example_partial(component, "thumbnail") %>
+            </div>
+          </div>
+          <div class="px-4 py-3">
+            <%= link_to component.name, component_path(component.slug), class: "text-sm font-semibold after:absolute after:inset-0" %>
+            <p class="mt-0.5 text-xs text-neutral-500 dark:text-neutral-400"><%= pluralize(component.examples.size, "example") %></p>
+          </div>
+        </div>
+      <% end %>
+    </div>
+  </section>
+<% end %>

data/lib/unmagic/components/browser/app/views/unmagic/components/browser/pages/theming.html.erb

@@ -0,0 +1,52 @@
+<% content_for :title, "Theming" %>
+<% content_for :breadcrumbs do %>
+  <%= render "crumb", label: "Getting started", path: root_path %>
+  <%= render "crumb", label: "Theming" %>
+<% end %>
+
+<% prose = "mt-3 max-w-2xl text-base leading-7 text-neutral-600 dark:text-neutral-400" %>
+<% step = "mt-12 text-lg font-semibold" %>
+
+<article class="max-w-3xl">
+  <h1 class="text-3xl font-semibold tracking-tight">Theming</h1>
+  <p class="<%= prose %>">
+    The components use Tailwind's own palette, with a <code>dark:</code> variant for every colour, so they
+    follow your theme from the defaults onward.
+  </p>
+
+  <h2 class="<%= step %>">Dark mode</h2>
+  <p class="<%= prose %>">
+    Dark mode follows your app's <code>dark</code> variant, which is the visitor's system setting by default.
+    To switch on a class or an attribute instead, redefine the variant. This browser uses
+    <code>data-theme</code>:
+  </p>
+  <div class="mt-4">
+    <%= render "code", id: "theming_dark", source: "@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));" %>
+  </div>
+
+  <h2 class="<%= step %>">Colours, radii and fonts</h2>
+  <p class="<%= prose %>">They come from your theme, so change them there and every component follows:</p>
+  <div class="mt-4">
+    <%= render "code", id: "theming_theme", source: "@theme {\n  --color-neutral-900: oklch(0.21 0.03 265);\n  --radius-md: 0.25rem;\n}" %>
+  </div>
+
+  <h2 class="<%= step %>">One component</h2>
+  <p class="<%= prose %>">
+    Pass utilities through <code>class:</code>. The gem's rules sit in <code>@layer components</code>, which
+    Tailwind orders before utilities, so yours win:
+  </p>
+  <%# Captured as template text: ERB inside a Ruby string would close this tag early. %>
+  <% utilities_source = capture do %><%%= card title: "Members", class: "rounded-none shadow-none" do %>…<%% end %><% end %>
+  <div class="mt-4">
+    <%= render "code", id: "theming_utilities", source: utilities_source.to_str %>
+  </div>
+
+  <h2 class="<%= step %>">Form controls</h2>
+  <p class="<%= prose %>">
+    Controls wear a class for their kind, which comes from a setting. Point it at your own classes, or
+    return <code>nil</code> to leave controls unstyled:
+  </p>
+  <div class="mt-4">
+    <%= render "code", id: "theming_controls", source: %(config.control_class = ->(_view, kind) { kind == :select ? "form-select" : "form-input" }) %>
+  </div>
+</article>