baldur 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c30a02aad73679e5b6bb7d00222718c2d41404dc711304bc8c06e93b9263544
-  data.tar.gz: beaedad46ac4a8d0bf61b11812c0004675e8a9d707dee05fe54ae589f1ef1ff9
+  metadata.gz: 173fbb6ff876c4440db1b17b3edb60f7d9c9bee99fdf18d59a733c411897d5b1
+  data.tar.gz: 6a51c87730719ddb3155a7eb70d7c6ab6f257ce66b0fb0b23a94582434665beb
 SHA512:
-  metadata.gz: 75fe161cdcd9d876121c3ec9182ce70ce402b982a9b42628b2c19bd92286e695df48dc9252f59b11eb0a58406f690d7df50bb74eed56421b425377a6d1f85773
-  data.tar.gz: dd85ce27768bb4802ee67f2b27e11926dedf286a82d4dea893ac6463c47727a174017580ab62dbc08b7b6a9d1a7b269a82a392bbafc635ae73363fbb78b348e1
+  metadata.gz: c02cccdbe76f6e8b19a76dc70fe932b6ccb303a381de63dd9270f1414cd658ec310d5d965f8649c1d44a6fb1f62eeceacc92ab9a0af8a3b33b9ba051836d43b0
+  data.tar.gz: fe5a8cbd70bbe930a4f738de6ab52b15ce793ef2c60e1117026d22c6388910c1774e5c879581f28a825651e201b11fc6bb1d5819a8f77355cb120af0ca0ee67b

data/README.md

@@ -72,12 +72,22 @@ Render a sidebar with navigation and a main content area:
 - [Styling](docs/styling.md)
 - [Sidebar](docs/sidebar.md)
 - [Auth](docs/auth.md)
+- [Forms](docs/forms.md)
 - [Modals and Panels](docs/modals-and-panels.md)
 - [Alerts and Snackbars](docs/alerts-and-snackbars.md)
+- [Tabs and Segmented Controls](docs/tabs-and-segmented-controls.md)
 - [Tables](docs/tables.md)
 - [Marketing](docs/marketing.md)
 - [Security](docs/security.md)
 
+## LLM / Context7 Docs
+
+- [llms.txt](llms.txt) for agent-friendly doc discovery and page summaries.
+- [llms-full.txt](llms-full.txt) for a denser, one-file integration guide.
+- [context7.json](context7.json) scopes Context7 parsing to Baldur's primary docs and agent rules.
+
+These files are intended for Context7 and other doc-ingestion tools that look for machine-readable documentation entrypoints.
+
 ## Security
 
 See [docs/security.md](docs/security.md) for artifact verification, MFA requirements, and vulnerability reporting.

data/TODO.md

@@ -1,7 +1,5 @@
 # Baldur TODO
 
-- [ ] Consider `pagy` gem for tables component
-
 ## Install and Verification
 - [ ] Harden `baldur:install` so host assumptions are reduced
 - [ ] Audit generated controller shims against all shipped components
@@ -9,11 +7,11 @@
 - [ ] Add end-to-end install verification in dummy app
 
 ## Showcase App and Docs
-- [ ] Add agent-friendly docs, fetchable by Context7
 - [ ] Add a dedicated dummy app in the extracted gem repo for visual smoke checks
 - [ ] Add a component inventory/showcase page in that dummy app
 - [ ] Add interaction showcase pages for modal, sidebar, menu select, snackbar, and `panel_secondary`
 - [ ] Add copy-paste examples for core surfaces from the showcase app back into docs
+- [ ] Add a dummy-app example showing segmented tabs inside a form with hidden tab state
 
 ## Starter Templates
 - [ ] Add dedicated password reset templates
@@ -29,6 +27,31 @@
 - [ ] Bind labels, hints, errors, and invalid states automatically
 - [ ] Document model-bound form usage
 
+## Buttons
+- [x] `ui_button` should support `formaction` and `formmethod` attributes so host apps can use it as a form-action button (e.g. Turbo-frame-aware submit that posts to a different endpoint)
+  - Currently host apps fall back to raw `<button>` or `button_tag` because `ui_button` only forwards `type`, `data`, `aria`, `disabled`, and `form`.
+  - Add passthrough for `formaction` and `formmethod` in both `ui_button` helper signature and `baldur/components/button` partial.
+  - Accept `value:` and `name:` too so it can double as a named submit button.
+  - Verify with a dummy-app example that submits within a Turbo Frame to a custom formaction.
+  - Why: keeps host code free of custom HTML button wiring and lets `ui_button` act as a full submit/FAB replacement.
+- [ ] Document interplay between `ui_button`, hidden state fields, and segmented tabs for multi-panel forms
+  - avoid host apps inventing ad hoc flow-state patterns just to support review/commit loops
+
+## Tabs and Segmented Controls
+- [x] Add a first-class `ui_tabs` primitive or documented tabs pattern built on `ui_segmented_buttons`
+  - selected tab trigger
+  - tab panels
+  - ARIA wiring
+  - keyboard behavior
+  - hidden / inactive panel handling
+- [x] Provide a small Stimulus controller for segmented-button tabs so host apps do not hand-roll `show/hide` logic
+- [x] Support syncing selected tab into a hidden input for form-backed workflows
+- [x] Document when tabs should be:
+  - instant client-side state
+  - Turbo GET navigation
+  - preserved across POST / redirect / render flows
+- [ ] Consider adding a higher-level `ui_tabs` helper on top of the documented segmented-buttons pattern once host usage stabilizes
+
 ## Tables and Resource Screens
 - [ ] Add a higher-level resource index pattern on top of existing table primitives
 - [ ] Support search, filters, row actions, bulk select, and empty states
@@ -37,13 +60,10 @@
 
 ## Theming
 - [ ] Add a small set of starter theme presets
-- [ ] Add first-class `ui_theme_toggle` helper/component so hosts do not need to copy Mimir toggle partial
-- [ ] Improve dark-mode/theme controller documentation
-  - [ ] Theme toggle on auth page templates need top rail 
-  - [ ] Document brand-token customization more clearly
 
 ## Accessibility
 - [ ] Audit keyboard and focus behavior across interactive components
+- [ ] ADA WCAG 2.1 AA compliance
 - [ ] Add accessibility-focused tests for core surfaces
 - [ ] Document a11y guarantees and known gaps
 

data/app/assets/javascripts/baldur/controllers/segmented_tabs_controller.js

@@ -1,9 +1,11 @@
 import { Controller } from '@hotwired/stimulus'
 
 export default class extends Controller {
-  static targets = ['tab', 'panel']
+  static targets = ['hiddenInput', 'tab', 'panel']
   static values = { active: String }
 
+  static TAB_KEYS = ['ArrowLeft', 'ArrowRight', 'Home', 'End']
+
   connect() {
     const initial = this.activeValue || this.tabTargets[0]?.dataset.tabValue
     if (initial) {
@@ -19,20 +21,69 @@ export default class extends Controller {
     }
   }
 
+  handleKeydown(event) {
+    if (!this.constructor.TAB_KEYS.includes(event.key) || this.tabTargets.length === 0) return
+
+    event.preventDefault()
+
+    const currentIndex = this.tabTargets.indexOf(event.currentTarget)
+    if (currentIndex === -1) return
+
+    let nextIndex = currentIndex
+
+    if (event.key === 'Home') {
+      nextIndex = this.nextEnabledIndex(0, 1)
+    } else if (event.key === 'End') {
+      nextIndex = this.nextEnabledIndex(this.tabTargets.length - 1, -1)
+    } else if (event.key === 'ArrowRight') {
+      nextIndex = this.nextEnabledIndex((currentIndex + 1) % this.tabTargets.length, 1)
+    } else if (event.key === 'ArrowLeft') {
+      nextIndex = this.nextEnabledIndex((currentIndex - 1 + this.tabTargets.length) % this.tabTargets.length, -1)
+    }
+
+    const nextTab = this.tabTargets[nextIndex]
+    if (!nextTab) return
+
+    this.show(nextTab.dataset.tabValue)
+    nextTab.focus()
+  }
+
   show(value) {
     this.tabTargets.forEach((tab) => {
       const selected = tab.dataset.tabValue === value
       tab.classList.toggle('is-selected', selected)
-      tab.setAttribute('aria-selected', selected)
+      tab.setAttribute('aria-selected', selected ? 'true' : 'false')
       tab.tabIndex = selected ? 0 : -1
     })
 
     this.panelTargets.forEach((panel) => {
       const selected = panel.dataset.tabValue === value
       panel.classList.toggle('hidden', !selected)
+      panel.hidden = !selected
       panel.setAttribute('aria-hidden', (!selected).toString())
     })
 
+    if (this.hasHiddenInputTarget) {
+      this.hiddenInputTarget.value = value
+    }
+
     this.activeValue = value
   }
+
+  nextEnabledIndex(startIndex, direction) {
+    let index = startIndex
+
+    for (let count = 0; count < this.tabTargets.length; count += 1) {
+      const tab = this.tabTargets[index]
+      if (tab && !this.isDisabled(tab)) return index
+
+      index = (index + direction + this.tabTargets.length) % this.tabTargets.length
+    }
+
+    return startIndex
+  }
+
+  isDisabled(tab) {
+    return tab.getAttribute('aria-disabled') === 'true' || tab.disabled
+  }
 }

data/app/assets/javascripts/baldur/controllers/theme_controller.js

@@ -27,12 +27,13 @@ export default class ThemeController extends Controller {
   }
 
   getCurrentTheme() {
-    // 1. Check localStorage
     const stored = getFromStorage(this.storageKeyValue);
     if (stored && this.themesValue.includes(stored)) return stored;
 
-    // 2. Default to light when user has not chosen a theme.
-    return "light";
+    const systemTheme = getSystemPreference("color-scheme", this.themesValue);
+    if (systemTheme && this.themesValue.includes(systemTheme)) return systemTheme;
+
+    return this.themesValue[0] || "light";
   }
 
   handleToggleChange(toggle) {

data/app/assets/stylesheets/baldur/application/components/auth-page.css

@@ -4,13 +4,12 @@
     min-height: 100vh;
     align-items: center;
     justify-content: center;
-    padding: var(--space-6);
-    background: var(--color-surface-low);
+    padding: var(--space-6, 1.5rem);
+    background: var(--color-surface-low, var(--color-surface, #f8fafc));
   }
 
   .auth-page__container {
-    width: 32rem;
-    max-width: 100%;
+    width: min(32rem, 100%);
     margin-inline: auto;
   }
 
@@ -18,12 +17,12 @@
     display: flex;
     align-items: center;
     justify-content: flex-end;
-    margin-bottom: var(--space-4);
+    margin-bottom: var(--space-4, 1rem);
   }
 
   .auth-page__brand {
     display: flex;
     justify-content: center;
-    margin-bottom: var(--space-6);
+    margin-bottom: var(--space-6, 1.5rem);
   }
 }

data/app/assets/stylesheets/baldur/application/components/table.css

@@ -25,7 +25,7 @@
   .table-card__header {
     display: flex;
     flex-wrap: wrap;
-    align-items: center;
+    align-items: flex-start;
     justify-content: space-between;
     gap: var(--space-3);
     padding: var(--space-5) var(--space-6);
@@ -35,7 +35,7 @@
 
   .table-card__header-main {
     min-width: 0;
-    flex: 1 1 20rem;
+    flex: 1 1 auto;
   }
 
   .table-card__header-title-row {
@@ -52,7 +52,8 @@
 
   .table-card__header-side {
     min-width: 0;
-    flex: 1 1 20rem;
+    flex: 0 0 auto;
+    align-self: flex-start;
     display: flex;
     flex-wrap: wrap;
     justify-content: flex-end;
@@ -216,13 +217,22 @@
     background-color: color-mix(in srgb, var(--color-primary) 8%, var(--color-surface-highest));
   }
 
-  .table tbody td:first-child,
-  .table tbody td:last-child {
+  .table tbody td:first-child {
+    font-weight: 600;
+  }
+
+  /*
+   * Opt-in modifier for tables where the last column should be visually
+   * emphasized (e.g. a total or primary action column). Default tables leave
+   * the last body cell at normal weight so numeric columns are not
+   * unexpectedly bold.
+   */
+  .table--emphasize-last-column tbody td:last-child {
     font-weight: 600;
   }
 
-  .table thead th:last-child,
-  .table tbody td:last-child {
+  .table th.text-right,
+  .table td.text-right {
     text-align: right;
   }
 

data/app/helpers/baldur/ui_helper.rb

@@ -19,6 +19,10 @@ module Baldur
       baldur_render 'baldur/components/button', **options
     end
 
+    def ui_hidden_field_tag(name, value = nil, options = {})
+      hidden_field_tag(name, value, options)
+    end
+
     def ui_action_row(primary_button:, secondary_button: nil, extra_buttons: [], classes: nil)
       buttons = []
       buttons << secondary_button if secondary_button.present?
@@ -214,8 +218,13 @@ module Baldur
                     action: action
     end
 
-    def ui_segmented_buttons(items:, aria_label: 'Tabs', classes: nil)
-      baldur_render 'baldur/components/segmented_buttons', items: items, aria_label: aria_label, classes: classes
+    def ui_segmented_buttons(items:, aria_label: 'Tabs', classes: nil, id: nil, data: nil)
+      baldur_render 'baldur/components/segmented_buttons',
+                    items: items,
+                    aria_label: aria_label,
+                    classes: classes,
+                    id: id,
+                    data: data
     end
 
     def ui_tooltip(text:, content:, show_icon: true, icon: 'circle-help', variant: :link, wrapper_class: nil,

data/app/helpers/baldur/ui_helper_feedback.rb

@@ -19,8 +19,21 @@ module Baldur
                     class_name: class_name
     end
 
-    def ui_snackbar_stack(snackbars: [])
-      baldur_render 'baldur/components/snackbar_stack', snackbars: normalize_snackbars(snackbars)
+    def ui_snackbar_stack(snackbars: [], id: nil, class_name: nil, data: nil)
+      baldur_render 'baldur/components/snackbar_stack',
+                    snackbars: normalize_snackbars(snackbars),
+                    id: id,
+                    class_name: class_name,
+                    data: data
+    end
+
+    def ui_snackbar_turbo_stream(flash, target: 'snackbar-stack', **stack_options)
+      raise_missing_turbo_stream_helper! unless respond_to?(:turbo_stream)
+
+      turbo_stream.update(
+        target,
+        html: ui_snackbar_stack(snackbars: snackbar_flash_payloads(flash), id: target, **stack_options)
+      )
     end
 
     FLASH_SNACKBAR_VARIANTS = { success: :success, notice: :notice, alert: :error, warning: :warning }.freeze
@@ -115,5 +128,9 @@ module Baldur
     rescue NoMethodError
       false
     end
+
+    def raise_missing_turbo_stream_helper!
+      raise ArgumentError, "ui_snackbar_turbo_stream requires turbo-rails and a Turbo Stream view context"
+    end
   end
 end

data/app/views/baldur/components/_button.html.erb

@@ -75,6 +75,10 @@
                  data: local_assigns[:data],
                  aria: local_assigns[:aria],
                  form: local_assigns[:form],
+                 formaction: local_assigns[:formaction],
+                 formmethod: local_assigns[:formmethod],
+                 value: local_assigns[:value],
+                 name: local_assigns[:name],
                  disabled: disabled do %>
     <%= content %>
   <% end %>

data/app/views/baldur/components/_segmented_buttons.html.erb

@@ -1,9 +1,16 @@
 <%
   segments = Array(items)
   return if segments.empty?
+  wrapper_classes = ['segmented', classes].compact.join(' ')
+  wrapper_data = (local_assigns[:data] || {}).stringify_keys
 %>
-<div class="segmented <%= classes %>" role="tablist" aria-label="<%= aria_label %>">
+<%= tag.div class: wrapper_classes,
+            id: local_assigns[:id],
+            data: wrapper_data,
+            role: 'tablist',
+            aria: { label: aria_label } do %>
   <% segments.each do |segment| %>
+    <% segment = segment.respond_to?(:symbolize_keys) ? segment.symbolize_keys : segment %>
     <% label = segment[:label].to_s %>
     <% badge_label = segment[:badge_label].to_s.presence %>
     <% icon = segment[:icon].presence %>
@@ -11,7 +18,9 @@
     <% disabled = !!segment[:disabled] %>
     <% value = segment[:value].presence || label.parameterize %>
     <% icon_only = icon.present? && label.blank? %>
-    <% data_attributes = (segment[:data] || {}).merge(value: value) %>
+    <% data_attributes = (segment[:data] || {}).stringify_keys.merge('value' => value) %>
+    <% button_aria = (segment[:aria] || {}).symbolize_keys %>
+    <% button_aria = button_aria.reverse_merge(selected: selected, disabled: disabled) %>
     <% button_classes = [
       "segmented__button",
       ("is-selected" if selected),
@@ -22,11 +31,9 @@
     <% button_options = {
       type: "button",
       class: button_classes,
+      id: segment[:id],
       role: "tab",
-      aria: {
-        selected: selected,
-        disabled: disabled
-      },
+      aria: button_aria,
       tabindex: selected ? 0 : -1,
       data: data_attributes
     } %>
@@ -48,4 +55,4 @@
       <% end %>
     <% end %>
   <% end %>
-</div>
+<% end %>

data/app/views/baldur/components/_snackbar_stack.html.erb

@@ -1,8 +1,12 @@
-<div class="snackbar-stack"
-     data-baldur-snackbar-stack
-     role="status"
-     aria-live="polite"
-     aria-atomic="true">
+<%
+  stack_classes = ["snackbar-stack", local_assigns[:class_name]].compact.join(" ")
+  stack_data = { "baldur-snackbar-stack" => true }.merge((local_assigns[:data] || {}).stringify_keys)
+%>
+<%= tag.div class: stack_classes,
+            id: local_assigns[:id],
+            data: stack_data,
+            role: "status",
+            aria: { live: "polite", atomic: "true" } do %>
   <% Array(snackbars).each do |snackbar| %>
     <%= render "baldur/components/snackbar", **snackbar %>
   <% end %>
@@ -10,4 +14,4 @@
   <template data-baldur-snackbar-template>
     <%= render "baldur/components/snackbar", template: true %>
   </template>
-</div>
+<% end %>

data/app/views/baldur/components/_table.html.erb

@@ -14,16 +14,18 @@
   sort_key = sort_config[:key].to_s
   sort_direction = sort_config[:direction].to_s.downcase == "asc" ? "asc" : "desc"
   sort_path_builder = local_assigns[:sort_path_builder]
-  header_classes = "px-6 py-4 text-left text-xs font-semibold uppercase tracking-wide text-[color:var(--color-on-surface-variant)]"
+  header_classes = "px-6 py-4 text-xs font-semibold uppercase tracking-wide text-[color:var(--color-on-surface-variant)]"
   cell_classes = "px-6 py-4 text-sm text-[color:var(--color-on-surface)]"
-  table_classes = ["table", local_assigns[:table_class], local_assigns[:class]].compact.join(" ")
+  emphasize_last_column = local_assigns[:emphasize_last_column].present?
+  table_modifier_class = emphasize_last_column ? "table--emphasize-last-column" : nil
+  table_classes = ["table", table_modifier_class, local_assigns[:table_class], local_assigns[:class]].compact.join(" ")
 %>
 <div class="table-card__scroll">
   <table class="<%= table_classes %>">
     <thead>
       <tr>
         <% normalized_columns.each do |column| %>
-          <% column_header_class = [header_classes, column[:header_class]].compact.join(" ") %>
+          <% column_header_class = [header_classes, ("text-right" if column[:numeric]), column[:header_class]].compact.join(" ") %>
           <% column_sort_key = (column[:sort_key] || column[:key]).to_s %>
           <% sortable = !!column[:sortable] && sort_path_builder.respond_to?(:call) && column_sort_key.present? %>
           <% sorted = sortable && sort_key == column_sort_key %>
@@ -106,7 +108,7 @@
         %>
           <%= tag.tr(**attributes) do %>
             <% cells.each_with_index do |cell, index| %>
-              <% column_cell_class = [cell_classes, normalized_columns[index]&.fetch(:cell_class, nil)].compact.join(" ") %>
+              <% column_cell_class = [cell_classes, ("text-right" if normalized_columns[index]&.fetch(:numeric, nil)), normalized_columns[index]&.fetch(:cell_class, nil)].compact.join(" ") %>
               <td class="<%= column_cell_class %>"><%= cell %></td>
             <% end %>
           <% end %>

data/app/views/baldur/optional/_auth_page.html.erb

@@ -4,8 +4,8 @@
   auth_card_class = local_assigns[:card_class]
 %>
 
-<div class="<%= auth_shell_classes %>">
-  <div class="auth-page__container">
+<div class="<%= auth_shell_classes %> min-h-screen flex items-center justify-center p-6 bg-base-200">
+  <div class="auth-page__container w-full max-w-lg mx-auto">
     <% if local_assigns[:top_rail].present? %>
       <div class="auth-page__top-rail">
         <%= local_assigns[:top_rail] %>

data/baldur.gemspec

@@ -17,8 +17,11 @@ Gem::Specification.new do |spec|
 
   spec.files = Dir.chdir(__dir__) do
     Dir[
-      '{app,config,lib,script,test}/**/*',
+      '{app,config,docs,lib,script,test}/**/*',
       'README.md',
+      'llms.txt',
+      'llms-full.txt',
+      'context7.json',
       'TODO.md',
       'LICENSE',
       'SECURITY.md',

data/context7.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://context7.com/schema/context7.json",
+  "projectTitle": "Baldur",
+  "description": "Opinionated Rails UI engine for Propshaft, importmap-rails, stimulus-rails, and tailwindcss-rails host apps.",
+  "folders": [
+    "docs"
+  ],
+  "excludeFiles": [
+    "TODO.md"
+  ],
+  "rules": [
+    "Target Rails host apps using Propshaft, importmap-rails, stimulus-rails, and tailwindcss-rails.",
+    "Prefer Baldur ui_* helpers over ad hoc duplicated component markup when a helper exists.",
+    "Treat optional surfaces as generator-backed and verify install requirements before suggesting their use.",
+    "Turbo support is opt-in. ui_snackbar_turbo_stream requires turbo-rails in the host app."
+  ]
+}

data/docs/alerts-and-snackbars.md

@@ -0,0 +1,72 @@
+# Alerts and Snackbars
+
+## Alerts
+
+Use `ui_alert` for inline status surfaces. Alerts support optional inline actions and opt-in collapsed state:
+
+```erb
+<%= ui_alert(
+  variant: :warning,
+  title: "Data freshness warning",
+  actions: ui_button(label: "Upload Latest Data", href: new_ecommerce_import_path, variant: :primary, size: :sm),
+  collapsible: true,
+  collapse_key: "tenant-#{current_tenant.id}-executive-pulse-stale-data"
+) do %>
+  <p>Latest available data is 10 days old.</p>
+<% end %>
+```
+
+Collapsed alerts stay inline and can be re-expanded with the built-in `More` summary action.
+
+## Snackbars
+
+Use semantic snackbar tones:
+
+- `:success` for green success states
+- `:notice` for blue notice/info states
+- `:warning` for amber warning states
+- `:error` for red error states
+
+Host apps should map `flash[:notice]` to `:notice` and `flash[:alert]` to `:error` unless they have a stronger semantic signal available.
+
+### Snackbar stack layout
+
+Give the global stack an `id` so it can be targeted from the server:
+
+```erb
+<%= ui_snackbar_stack(
+  snackbars: snackbar_flash_payloads(flash),
+  id: "snackbar-stack"
+) %>
+```
+
+Use `class_name:` and `data:` to extend the wrapper. Baldur always keeps the base class `snackbar-stack` and the `data-baldur-snackbar-stack` hook.
+
+### Turbo Stream updates
+
+For Hotwire apps, call `ui_snackbar_turbo_stream` from a Turbo Stream view to refresh the stack in place:
+
+```erb
+<%# app/views/users/create.turbo_stream.erb %>
+<%= ui_snackbar_turbo_stream(flash) %>
+```
+
+This is the same as:
+
+```erb
+<%= turbo_stream.update(
+  "snackbar-stack",
+  html: ui_snackbar_stack(
+    snackbars: snackbar_flash_payloads(flash),
+    id: "snackbar-stack"
+  )
+) %>
+```
+
+Change the target with `target:`:
+
+```erb
+<%= ui_snackbar_turbo_stream(flash, target: "frame-snackbar-stack") %>
+```
+
+`ui_snackbar_turbo_stream` is opt-in. If the host app does not use `turbo-rails`, calling it raises a clear `ArgumentError` at runtime. Non-Turbo apps can continue using `ui_snackbar_stack` with flash payloads the normal way.

data/docs/auth.md

@@ -0,0 +1,66 @@
+# Auth
+
+## When to Use
+
+Use `ui_auth_page` for sign-in, sign-up, and password-reset layouts. It is available after base install.
+
+## Quick Example
+
+```erb
+<%= ui_auth_page(title: "Sign in", description: nil, brand_path: root_path) do %>
+  <%= yield %>
+<% end %>
+```
+
+## Flash Messages
+
+Auth flash messaging can be rendered inside the card by passing `notice:` / `alert:`:
+
+```erb
+<%= ui_auth_page(title: "Sign in", description: nil, brand_path: root_path, notice: notice, alert: alert) do %>
+  <%= yield %>
+<% end %>
+```
+
+## Top Rail
+
+Pass `top_rail:` to add an action bar above the brand lockup. The most common use is a theme toggle:
+
+```erb
+<%= ui_auth_page(
+      title: "Sign in",
+      description: nil,
+      brand_path: root_path,
+      top_rail: ui_theme_toggle,
+      notice: notice,
+      alert: alert
+    ) do %>
+  <%= yield %>
+<% end %>
+```
+
+The `top_rail` slot accepts any rendered content, so it works for other controls too:
+
+```erb
+<%= ui_auth_page(
+      title: "Sign in",
+      description: nil,
+      brand_path: root_path,
+      top_rail: "<span class='text-sm text-base-content/60'>v2.1.0</span>".html_safe
+    ) do %>
+  <%= yield %>
+<% end %>
+```
+
+The host must mount `data-controller="theme"` on a parent element (typically `<body>`) for the theme toggle to function. See `docs/theme.md` for full controller documentation.
+
+## Theme Toggle
+
+`ui_theme_toggle` renders a light/dark switch wired to the Baldur theme controller:
+
+```erb
+<%= ui_theme_toggle %>
+<%= ui_theme_toggle(aria_label: "Switch appearance", classes: "my-extra-class") %>
+```
+
+Requires `data-controller="theme"` on a parent element. See `docs/theme.md` for setup.