lostcoords-ui 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b432f8fc71804447fa32cf3290c7db2556243ef42c6f6849fa7604ed5081870
-  data.tar.gz: 5cf53096cc4479889f98f4764d6dac7391e787b0a3fe4bb2c21f23e5201d2918
+  metadata.gz: be63d4a81a906b754a7dda9d321d5e0d79b45ac4ca18b39dc3e542d8b10a9822
+  data.tar.gz: 2073ae1b254f4f6aa61c4665bf1d3e4123d756b0bcfdb345ee1f5182452f6c14
 SHA512:
-  metadata.gz: aa29b884d7e07cc1204088de38ace739805f0b5d7ff853bdd2196f9787c65ad71c80005e653180840c877e880d21b66159b8c660fcab0846dc9a34715236d8b4
-  data.tar.gz: 4da2f287536853733eac9ee133fd16b2627d0f54e4c2cfc2bdd2d254588b4ab51f9631191b1558f35ca52b6fbb85ec2caade6674d1987c8eb51cc4ebc07989ec
+  metadata.gz: 7c00c795e03e402e554532c542b4d6ac748b9efb61dad9e057b5698a99a70ac9f49671f211ce7fd467d5b2d12693d63d2243583f6bd94bd454da2cd24b77ba13
+  data.tar.gz: 9333e9c1cdf9a7e7a35ca00ad411be173578203af5c82deedd1f432e812361a9b01f22e74f5234aae75351a1e115e57cb1675b3b76239c6eae770a89106144d7

data/README.md

@@ -21,7 +21,7 @@ its gem version, so publishing a library update does not upgrade consumers.
 ## Install
 
 ```ruby
-gem "lostcoords-ui", "~> 0.4.0"
+gem "lostcoords-ui", "~> 0.6.0"
 ```
 
 The engine adds its rendering helpers to host views, its JavaScript to the asset paths and its pins to
@@ -49,29 +49,52 @@ Standalone applications compile Tailwind and register Stimulus controllers throu
 pipeline. `Lostcoords::Ui.root` locates the gem's source assets. Rails applications receive automatic
 registration; use `require "lostcoords/ui/rails"` explicitly if Rails loads after the components.
 
-### Stylesheet
+### Standalone assets
 
-Tailwind CSS v4 is required. Use `tailwindcss-rails` 4.4 or later to compile the component styles and
-your app's utilities. Add the gem's entry to `app/assets/tailwind/application.css`:
+Import `app/assets/tailwind/lostcoords/ui/components.css` from the Bundler-resolved gem root
+into your Tailwind build. This entry includes component rules, default tokens and source scanning.
+It does not set body styles, heading defaults, global inline-code styles or document corner radii.
+Map the library's tokens to your app's theme and keep your Tailwind theme declarations after the import.
+The full `ui.css` entry includes those document defaults and remains the Rails default.
+
+Tailwind always ships component rules, used or not, and generates every utility the scanned helpers
+mention. For a smaller build, import `core.css` and the opt-in components you render instead of
+everything. Each entry carries the rules and scans the sources of its own component only. In Rails,
+every Tailwind build writes stable paths for them next to the engine's own import:
 
 ```css
-@layer theme, base, layout, components, modules, utilities;
+/* app/assets/tailwind/application.css, instead of ../builds/tailwind/lostcoords_ui.css */
+@import "../builds/tailwind/lostcoords_ui/base.css";
+@import "../builds/tailwind/lostcoords_ui/core.css";
+@import "../builds/tailwind/lostcoords_ui/components/dialog.css";
+@import "../builds/tailwind/lostcoords_ui/components/menu.css";
+```
 
-@import "tailwindcss/theme.css" layer(theme);
-@import "tailwindcss/preflight.css" layer(base);
-@import "tailwindcss/utilities.css" layer(utilities);
+Outside Rails, import the same files from `app/assets/tailwind/lostcoords/ui/` in the gem.
+`base.css` holds the document defaults that `ui.css` adds; skip it when the host owns its base styles.
+`core.css` holds the tokens, buttons, badges, avatars, cards, alerts, form controls, choices,
+toggles, layout, typography and navigation. The opt-in entries are `dialog` (with the phone sheet),
+`menu` (menus and popovers), `toast`, `tooltip`, `collapsible`, `code-block`,
+`emoji-picker`, `table` and `prose`. A component whose entry is missing renders unstyled.
 
-@plugin "@tailwindcss/typography";
+Start one Stimulus application in the host, then register the controllers you use:
 
-@import "../builds/tailwind/lostcoords_ui.css";
+```javascript
+import { Application } from "@hotwired/stimulus"
+import { registerControllers } from "lostcoords/ui"
+
+const application = Application.start()
+registerControllers(application, { only: ["lc-copy", "lc-collapsible"] })
 ```
 
-Tailwind resolves `@import` by path, and Bundler decides where the gem lives. tailwindcss-rails' `tailwindcss:engines`
-task, which runs before every `tailwindcss:build` and `tailwindcss:watch` (and so before `assets:precompile`), writes
-`app/assets/builds/tailwind/lostcoords_ui.css` with the absolute path to the gem's
-`app/assets/tailwind/lostcoords_ui/engine.css`. `app/assets/builds` is already ignored by a Rails app's `.gitignore`
-and `.dockerignore`, so there is nothing to commit. The file does not exist until the first Tailwind build, so a lint
-that checks imports should skip it.
+Resolve `lostcoords/ui/*` to the gem's `app/javascript/lostcoords/ui/*` and `@hotwired/stimulus` to
+the host's installed package. `registerControllers` imports every controller, so a bundle carries
+them all; to bundle only some, import them directly:
+`import Dialog from "lostcoords/ui/controllers/lc_dialog_controller"` and
+`application.register("lc-dialog", Dialog)`. Build configuration belongs to the host. The entry does not start
+Stimulus or register anything on import. Omit `only` to register all library controllers. Register
+defaults before application overrides. Repeated calls on the same application preserve later
+overrides; unknown controller identifiers raise before registration.
 
 The gem's stylesheets write into the `components` and `modules` layers, so the host declares that layer order.
 The theme defines the `dark:` variant with `html[data-theme="dark"]`. `ui.css` carries its own `@source` lines, so Tailwind
@@ -79,36 +102,94 @@ scans the gem's helpers, views and JavaScript wherever the gem is installed.
 
 ### Theming
 
-The engine includes a complete light and dark theme, system fonts, shadows, glass effects and motion
-settings. Components work without an app-owned token file. To activate dark mode, set
-`data-theme="dark"` on `<html>`. Your app controls the switch and saved preference.
-
-To customize the theme, add CSS variable overrides after the engine import:
+Colors use [shadcn/ui](https://ui.shadcn.com/docs/theming) names, so a shadcn or tweakcn theme drops in.
+Set `data-theme="dark"` on `<html>` for dark mode; your app owns the switch and saved preference.
+Override any of these after the engine import:
 
 ```css
 :root {
-  --sky: oklch(52% 0.14 155);
-  --sky-deep: oklch(46% 0.14 155);
-  --sky-soft: oklch(96% 0.02 155);
+  --primary: oklch(46% 0.14 155);
+  --radius: 0.625rem;      /* every corner scales from this */
+  --lc-density: 0.875;     /* semantic spacing and control heights */
 }
 
 html[data-theme="dark"] {
-  --sky: oklch(75% 0.14 155);
-  --sky-deep: oklch(70% 0.14 155);
-  --sky-soft: color-mix(in oklab, var(--sky) 18%, var(--paper));
+  --primary: oklch(75% 0.14 155);
 }
 ```
 
-Override only the values you need. The [theming guide](https://ui.lostcoords.com/theming.html) covers
-colors, fonts, corners, shadows and advanced variables. Defaults live in
-`app/assets/tailwind/lostcoords/ui/theme.css`. `Lostcoords::Ui::TOKENS` lists the variables in that file
-for reference; apps do not have to define them.
+| Setting | Default | Drives |
+| --- | --- | --- |
+| `--background` `--foreground` | white, near black | page and body text |
+| `--card` `--card-foreground` | light gray | cards |
+| `--popover` `--popover-foreground` | page background | menus, popovers, dialogs |
+| `--primary` `--primary-foreground` | near black, white | primary actions, links, selection, focus |
+| `--secondary` `--secondary-foreground` | gray | secondary buttons |
+| `--muted` `--muted-foreground` | light gray, mid gray | subtle fills; secondary text, hints, placeholders |
+| `--accent` `--accent-foreground` | gray | hovered rows and menu items, inline code |
+| `--destructive` `--success` `--warning` | | status; soft fills such as `bg-success-soft` are generated |
+| `--border` `--input` `--ring` | | dividers, input fills, focus ring |
+| `--radius` | `0.5rem` | `rounded-sm` to `rounded-3xl` and `rounded-pill`; the default keeps Tailwind's own sizes |
+| `--lc-density` | `1` | the semantic spacing and control heights below |
+| `--lc-inset` | `1.25rem` | padding of cards, dialogs and popovers |
+| `--font-sans` `--font-display` `--font-mono` | system | font families |
+
+Defaults live in `app/assets/tailwind/lostcoords/ui/theme.css`. `Lostcoords::Ui::TOKENS` lists the
+public colors and fonts. Library-internal settings use the `--lc-` prefix.
+
+### Foundations
+
+Components never set outer margin. Layout helpers own the space between things, and components pad
+themselves from `--lc-inset`. Every token is a Tailwind utility:
+
+| Spacing | Default | Use |
+| --- | --- | --- |
+| `tight` | 4px | icon and label |
+| `related` | 8px | label and control, button groups |
+| `heading` | 12px | a heading and its content |
+| `content` | 16px | blocks and fields |
+| `inset` | `--lc-inset` | container padding and the gaps between its blocks |
+| `section` | 32px | sections on a page |
+
+Use them as `gap-related`, `p-inset`, `py-section` and so on. Setting `--lc-inset` on an element
+changes the padding of every card or dialog inside it.
+
+| Type role | Size / line height | Use |
+| --- | --- | --- |
+| `text-display` | 36 / 40px, bold | hero |
+| `text-title` | 30 / 36px, bold | page title |
+| `text-heading` | 20 / 28px, bold | section title |
+| `text-subheading` | 18 / 24px, semibold | card and dialog titles |
+| `text-body` | 16 / 24px | text |
+| `text-small` | 14 / 20px | hints and secondary text |
+| `text-label` | 14 / 20px, medium | labels, buttons, menu items |
+| `text-caption` | 12 / 16px | metadata, table headers |
+
+Each role sets size, line height, tracking and weight together. `lc-trim` trims the space above the
+capital letters and below the baseline where the browser supports `text-box`.
+
+Buttons, inputs, selects, toggles and icon buttons share heights: `h-control-sm` (32px),
+`h-control-md` (40px) and `h-control-lg` (48px). On touch screens the small and medium sizes grow to
+at least 40 and 44px. Containers use `max-w-page`, `max-w-reading` and `max-w-form`, and the page
+container pads with `px-gutter`.
 
 ### Importmap
 
-The engine pins its modules under the host's own keys, `controllers/*` and `helpers/*`, so
-`eagerLoadControllersFrom("controllers", application)` registers the gem's controllers with no extra wiring.
-A host file with the same name, such as `app/javascript/controllers/sheet_controller.js`, shadows the gem's.
+The engine pins its modules under `lostcoords/ui/*`. Controllers are also pinned under the host's
+`controllers/*` key with an `lc_` prefix, so Rails' controller loading registers them as `lc-dialog`,
+`lc-menu`, `lc-copy` and so on. Load them lazily, so a page downloads only the controllers it uses,
+the first time their `data-controller` appears:
+
+```javascript
+// app/javascript/controllers/index.js
+import { lazyLoadControllersFrom } from "@hotwired/stimulus-loading"
+import { application } from "controllers/application"
+
+lazyLoadControllersFrom("controllers", application)
+```
+
+`eagerLoadControllersFrom` also works and downloads all of them on every page. A host file with the
+same name, such as `app/javascript/controllers/lc_dialog_controller.js`, replaces the gem's.
 
 ## Components
 
@@ -117,7 +198,17 @@ in its code panel. The API reference reads signatures from the helper definition
 [API JSON](https://ui.lostcoords.com/api.json) and [llms.txt](https://ui.lostcoords.com/llms.txt)
 include those signatures and the runnable examples.
 
-Buttons use `primary`, `secondary`, `ghost` or `destructive`, with `sm`, `base` or `lg` sizes.
+Buttons use `primary`, `secondary`, `outline`, `ghost`, `glass` or `destructive`, with `sm`, `md` or `lg` sizes.
+Primary, secondary and destructive buttons have visible filled surfaces. Ghost buttons and the
+`lc_icon_button` toolbar action are transparent at rest and show their full shape on hover.
+Primary, secondary and destructive buttons are flat. Secondary buttons use a soft neutral fill distinct from page and card backgrounds.
+Outline buttons have a transparent fill and a visible edge. Glass buttons use the shared translucent material, rim and shadow for floating controls.
+The default light theme uses white pages and softly shaded cards, with no visible card borders or resting shadows.
+Popover triggers accept `trigger_variant` using the same button variants.
+Button hover and press fills mix 94% of the base background with 6% of its foreground in OKLab.
+Ghost and icon buttons stay transparent at rest and use the secondary base for that calculation.
+Apps can override `--secondary` for the neutral base, or `--lc-button-bg` and `--lc-button-ink` on individual buttons.
+Inputs use `--input` and `--lc-input-hover`.
 `lc_button_to` preserves Rails' form, HTTP method and CSRF behavior. Block helpers capture ERB content.
 Use `icon: "plus"` for a leading Heroicon or `icon_position: :end` for a trailing one. Custom icons and
 spinners use `data-icon="inline-start"` or `data-icon="inline-end"`; buttons adjust that edge's padding.
@@ -137,6 +228,188 @@ theme tokens to restyle the library. `lc_field` yields the input's `id` and vali
 labels, hints and errors stay connected. Linked cards use `lc_card(href: ...)`; cards containing
 buttons or fields remain ordinary containers.
 
+`lc_table` renders a native table with a shaded header and subtle row dividers. Supply the caption, header cells and body in its block.
+Wrap wide tables in an app-owned horizontal scroll region with an accessible name and keyboard focus.
+Use `lc_table_class` when an existing table renderer owns the markup.
+
+Cards share one API: `lc_card(padding: :md)`, with `:sm` and `:none` for tighter or custom spacing. Padding sizes set `--lc-inset`, so content inside follows the card.
+Inputs keep their `--input` fill inside cards; set `--lc-field-bg` to change it in one context. Cards provide avatar cutouts and a validation border when they contain errors. Fills that are muted on the page switch so they stay visible on the card: choice tiles, alerts, neutral badges and skeletons take the page background (`--lc-tile-bg`), and toggle group and tab tracks take the accent fill (`--lc-track-bg`). Set either variable to apply the same context to your own muted surface.
+Add `class: "@container"` when a card owns its width and its children use container queries.
+Use `--lc-card-bg`, `--lc-card-border`, `--lc-card-radius` and `--lc-card-shadow` for local appearance overrides.
+
+`lc_badge` handles labels, counts and status. Use `class: "rounded-full"` for a rounded status label.
+`lc_icon_badge` handles decorative icon containers, with `shape: :square` or `:circle` and `sm`, `md`, `lg` or `xl` sizes.
+Badge, icon badge, Alert and Toast share `neutral`, `primary`, `success`, `warning` and `destructive` tones.
+
+`lc_toggle` renders a pressed button. Use `lc_toggle_group` with `lc_toggle_group_item` for mutually exclusive
+choices and a native submitted value. Navigation uses `lc_button_link_to` and `aria-current`, so links keep their native behavior.
+`lc_collapsible` expands content through a native `<details>` element. `lc_alert` renders persistent inline feedback;
+`lc_toast` adds timed dismissal.
+
+### Parts and slots
+
+Compound components yield a builder, so their parts are scoped and discoverable. A card stacks its
+parts with the same gap it pads with:
+
+```erb
+<%= lc_card do |card| %>
+  <%= card.header title: "Members", description: "People in this workspace" do %>
+    <%= lc_button "Invite", size: :sm %>
+  <% end %>
+  <%= card.content do %>…<% end %>
+  <%= card.footer do %><%= lc_button "Save" %><% end %>
+<% end %>
+
+<%= lc_alert "Your card was declined.", title: "Payment failed" do |alert| %>
+  <%= alert.actions do %><%= lc_button "Update payment", size: :sm %><% end %>
+<% end %>
+
+<%= lc_dialog id: "new-project", title: "Create project", description: "Projects group pages." do |dialog| %>
+  …
+  <%= dialog.footer do %><%= dialog.close %><%= lc_button "Create" %><% end %>
+<% end %>
+```
+
+Every component root and part carries `data-slot`, plus `data-variant`, `data-size` or `data-tone`
+where they apply, so a context can restyle parts without matching utility classes:
+`[data-slot=card-footer] { justify-content: start }`.
+
+### Forms
+
+`lc_form_with` is `form_with` with `Lostcoords::Ui::FormBuilder`. Standard helpers keep their Rails
+signatures and render library controls; `field` adds the label, hint and the attribute's errors, and
+sets `aria-invalid` on the control. Rails' `field_with_errors` wrapper does not affect the layout.
+
+```erb
+<%= lc_form_with model: @project, class: "flex flex-col gap-content" do |form| %>
+  <%= form.field :name, hint: "Shown to members" %>
+  <%= form.field :email, as: :email_field %>
+  <%= form.switch :public %>
+  <%= form.submit "Save project" %>
+<% end %>
+```
+
+A symbol `size:` such as `size: :sm` picks the control height; an integer still sets the HTML
+attribute. Pass `builder: Lostcoords::Ui::FormBuilder` to `form_with` directly, or call `lc_field`
+with `error: record.errors.full_messages_for(:name)` when you keep your own builder.
+
+`lc_checkbox`, `lc_radio` and `lc_switch` render native inputs with a label and optional hint.
+Checkboxes and switches submit an unchecked value like Rails' `check_box`; pass `unchecked_value: nil`
+to omit it. `lc_choice_group` groups them in a fieldset with a legend, hint and error.
+
+### Navigation and overlays
+
+```erb
+<%= lc_breadcrumb [ [ "Projects", projects_path ], @project.name ] %>
+
+<%= lc_tabs id: "project-tabs", label: "Project" do |tabs| %>
+  <% tabs.panel "Overview" do %>…<% end %>
+  <% tabs.panel "Activity", value: :activity do %>…<% end %>
+<% end %>
+
+<%= lc_tooltip "Copy a link", id: "copy-tip" do |tip| %>
+  <%= lc_icon_button "Copy link", icon: "link", **tip %>
+<% end %>
+
+<%= lc_description_list do |list| %>
+  <%= list.item "Owner", @project.owner.name %>
+  <%= list.item("Plan") { lc_badge @project.plan } %>
+<% end %>
+```
+
+Tabs follow the ARIA tabs pattern with arrow key, Home and End navigation, and dispatch
+`lc-tabs:change`. `orientation: :vertical` stacks the tabs beside their panels and moves with Arrow Up
+and Down; `activation: :manual` moves focus with the arrows and selects with Enter or Space. Tooltips show on hover and keyboard focus, Escape hides them, and they describe
+their trigger, in the top layer; keep essential information visible. Description lists stack on phones and use two
+columns from `sm`.
+
+```erb
+<%= lc_skip_link %>
+
+<%= lc_nav_list label: "Settings" do |nav| %>
+  <%= nav.group "Workspace" do %>
+    <%= nav.link "General", settings_path, current: current_page?(settings_path) %>
+    <%= nav.link "Members", members_path %>
+  <% end %>
+<% end %>
+
+<%= lc_pager previous: [ "Install", install_path ], next: [ "Theming", theming_path ] %>
+
+Read the <%= lc_link "guide", guide_path %>.
+```
+
+`lc_nav_list` marks the current link with `aria-current="page"`; `compact: true` is the quieter
+style for an "On this page" list, and `indent: true` nests a link. `lc_pager` takes `[title, url]`
+for each side and `compact: true` for icon buttons. `lc_link` has `inherit`, `muted` and `primary`
+tones; `lc_link_class` styles links you render yourself. `lc_skip_link` targets `#main` by default.
+Pass `card: true` to `lc_radio` or `lc_checkbox` for selectable tiles; a block adds content, such as a
+preview, under the label.
+
+This documentation site is built with these components and two copyable blocks: the application
+header and the documentation layout.
+
+`lc_dialog` handles modal content and the mobile sheet layout. Set `detents: "medium large"` or `"large"`
+to choose mobile height stops; the default is `"fit"`. Icon buttons, avatar groups, motion and mobile dialogs
+appear with their parent component examples.
+
+### Keyboard
+
+Every interactive component works from the keyboard without extra code:
+
+| Component | Keys |
+|---|---|
+| Menu | Arrow Down or Up on the button opens on the first or last item. Arrows move and wrap, Home and End jump, a letter jumps to the next item that starts with it, Enter or Space activates, Escape closes and returns focus. |
+| Tabs | Arrows along the tab list's orientation, Home and End. Automatic tabs select on focus; manual tabs on Enter or Space. |
+| Toggle group | One Tab stop. All four arrows move and select, wrapping; Left and Right follow the text direction. |
+| Emoji picker | Arrow Down from the search enters the grid, arrows move through it by row, Arrow Up from the top row returns to the search, and Enter in the search picks the best match. The grid is one Tab stop. |
+| Dialogs, sheets, popovers, menus, tooltips | Escape closes the topmost one and returns focus to what opened it; an open tooltip closes before the menu or dialog around it. Escape in a search field with text clears it first. |
+
+Page-wide shortcuts focus a field or press a button. Merge `lc_shortcut_data` into the element's data and
+show the keys with `lc_kbd`:
+
+```erb
+<%= lc_input type: :search, name: "q", aria: { label: "Search" }, data: lc_shortcut_data("mod+k") %>
+<%= lc_button data: lc_shortcut_data("n", action: "projects#new") do %>
+  New project <%= lc_kbd "n", aria: { hidden: true } %>
+<% end %>
+```
+
+Keys are joined with `+`: `mod` is ⌘ on Apple platforms and Ctrl elsewhere, and `ctrl`, `alt`, `shift`
+and `meta` name the others. Separate alternatives with spaces. The element announces its keys through
+`aria-keyshortcuts`. Shortcuts without `mod`, `ctrl` or `alt` don't fire while typing in a field, only
+shortcuts inside an open modal dialog respond, and when two visible elements share keys the first wins
+and the console warns. `lc_kbd` renders the Ctrl form and switches to Apple symbols once JavaScript runs.
+
+Custom widgets can use the same navigation: `navigate(event, items, { orientation, wrap, typeahead })`
+from `lostcoords/ui/helpers/roving_focus` handles vertical, horizontal and grid layouts, right-to-left
+text, Home and End, and typeahead; `rove(items, current)` keeps a single Tab stop.
+
+### Layers
+
+Overlays never need a z-index. Dialogs and sheets open as modal `<dialog>` elements; menus,
+popovers, pickers and tooltips move into the browser's top layer while they are open; toasts go in
+`lc_toast_region`, which does the same. The top layer paints above every z-index, `overflow` clip
+and stacking context on the page, so a sticky header, a `transform` or a glass `backdrop-filter`
+can't cover them. A modal dialog makes the rest of the page inert, so while one is open the toast
+region moves inside it and back when it closes. The region is the live region that announces its
+toasts; destructive toasts are alerts. Where the Popover API is missing overlays stay in place,
+ordered by `--lc-z-popover`, `--lc-z-overlay` and `--lc-z-toast`.
+
+```erb
+<%# In the layout, once %>
+<%= lc_toast_region id: "toasts" do %>
+  <% flash.each do |type, message| %><%= lc_toast message, tone: type == "alert" ? :destructive : :success %><% end %>
+<% end %>
+
+<%# From a controller or job %>
+<%= turbo_stream.append "toasts" do %><%= lc_toast "Project saved." %><% end %>
+```
+
+Two in-page layers remain: `z-sticky` keeps app chrome such as a sticky header above content, and
+`z-raised` lifts an element over its neighbours. Put `isolate` on the main content area, so any z-index
+inside it stays below the chrome. Tailwind drops a `z-*` class it can't resolve without a warning, so
+use these two names, a number or `z-(--a-defined-variable)`.
+
 ## Copy feedback and motion
 
 ```erb
@@ -157,17 +430,31 @@ Default labels are translated in English, Japanese and Spanish. Use `label` (the
 `copied_label:` and `error_label:` to customize visible text, and `aria: { label: ... }` for a contextual name.
 Normal button variants, sizes, classes, disabled state and attributes are supported.
 
-The component emits bubbling `ui-copy:copied` (`detail.text`) and `ui-copy:error` (`detail.error`) events
-from its wrapper. Listen on an ancestor to connect application behavior. The documentation uses the error
-event to reveal clipped source code for manual copying.
+The component emits bubbling `lc-copy:copied` (`detail.text`) and `lc-copy:error` (`detail.error`) events
+from its wrapper. Listen on an ancestor to connect application behavior.
+
+```erb
+<%= lc_code_block "puts 'Hello'", id: "ruby-example", language: :ruby %>
+<%= lc_code_block source, id: "file-example", language: :ruby, title: "app/helpers/greeting_helper.rb" %>
+<%= lc_code_block source, id: "long-example", language: :ruby, max_lines: 5 %>
+```
 
-Buttons include hover and press feedback. Override `--ui-motion-quick` (140ms), `--ui-motion-control` (180ms),
-`--ui-motion-feedback` (160ms), `--ui-press-scale` (0.96) and `--ease-out` in your theme or on a container.
+Code blocks escape plain source, preserve whitespace, and include a floating icon-only copy button.
+The copy control appears on hover or keyboard focus and stays visible on touch devices and during copy feedback.
+Snippets have no header by default; use `title:` for a compact filename or heading. `language:` sets code metadata
+without adding a visible label. Snippets longer
+than `max_lines:` (10 by default) can expand and collapse; use `max_lines: nil` to show all lines.
+Copy failures expand clipped source for manual selection. Labels are translated in English, Japanese and Spanish.
+An optional block receives the raw source and can return highlighted markup from the app's syntax highlighter.
+For selective JavaScript registration, include both `lc-code-block` and `lc-copy`.
+
+Buttons include hover and press feedback. Override `--lc-motion-quick` (140ms), `--lc-motion-control` (180ms),
+`--lc-motion-feedback` (160ms), `--lc-press-scale` (0.96) and `--lc-ease-out` in your theme or on a container.
 Reduced motion removes control movement and makes copy feedback immediate. Your application owns the
 pending, success and failure states of network actions such as saving a form.
 
 [Try the copy button](https://ui.lostcoords.com/components/copy_button.html) ·
-[Motion reference](https://ui.lostcoords.com/components/motion.html)
+[Motion reference](https://ui.lostcoords.com/components/foundations.html#motion)
 
 ### Icons
 
@@ -185,18 +472,17 @@ Pass SVG attributes through `options:` and existing path attributes through `pat
 
 ### Typography and layout
 
-The engine stylesheet includes shared text styles and layout defaults. Heading level controls document
-structure independently of its visual size. Layout parents own the spacing between children, including fields.
-Inline `<code>` elements get a shared monospace style with a theme-aware background. `<pre><code>`
-blocks keep their block styling.
+Heading level controls document structure independently of its visual size. Layout parents own the
+spacing between children, including fields. Inline `<code>` elements get a shared monospace style;
+`<pre><code>` blocks keep their block styling.
 
 ```erb
 <%= lc_stack gap: :section do %>
-  <%= lc_heading "Workspace", level: 1, size: :page %>
+  <%= lc_heading "Workspace", level: 1, size: :title %>
   <%= lc_section title: "Members" do %>
     <%= lc_card do %>
       <%= lc_stack gap: :related do %>
-        <%= lc_heading "Design team", level: 3, size: :card %>
+        <%= lc_heading "Design team", level: 3, size: :subheading %>
         <%= lc_text "Three people share this workspace.", tone: :muted %>
       <% end %>
     <% end %>
@@ -204,16 +490,12 @@ blocks keep their block styling.
 <% end %>
 ```
 
-Heading sizes are `page`, `section` and `card`. Text sizes are `body`, `small` and `caption`,
-with `default`, `muted` and `subtle` tones. Stacks and inline groups accept `tight` (4px), `related`
-(8px), `heading` (12px), `content` (16px), `inset` (20px) and `section` (32px) gaps at the default
-browser font size. `lc_section` leaves 12px below its heading and 16px between content blocks.
-`lc_container` provides `page`, `reading` and `form` widths. Only the page container adds gutters.
-
-Fonts and colours come from the shared theme and your app's overrides. Optional custom properties override the shared defaults:
-`--ui-space-section`, `--ui-heading-page-size`, `--ui-heading-page-line-height`, `--ui-page-max`,
-`--ui-gutter` and `--ui-reading-measure`. Set them in the host theme or on a container. Japanese headings
-inherit `lang="ja"` and use natural letter spacing.
+Heading sizes are `display`, `title`, `heading` and `subheading`. Text sizes are `body`, `small`,
+`label` and `caption`, with `default` and `muted` tones. Pass `trim: true` to trim the text box.
+Stacks and inline groups take the spacing names from [Foundations](#foundations). `lc_section` leaves
+`heading` below its title and `content` between blocks. `lc_container` provides `page`, `reading` and
+`form` widths; only the page container adds gutters. Japanese headings inherit `lang="ja"` and use
+natural letter spacing.
 
 [Browse the foundations examples](https://ui.lostcoords.com/components/foundations.html).
 
@@ -237,7 +519,7 @@ Rails' normal escaping rules; sanitise rendered user content before marking it s
 <% end %>
 ```
 
-Override `--ui-reading-size`, `--ui-reading-leading`, `--ui-reading-flow` and `--ui-reading-measure`
+Override `--lc-reading-size`, `--lc-reading-leading`, `--lc-reading-flow` and `--lc-reading-measure`
 to tune a reading context. Use `not-prose` for embedded components.
 
 ### Class helpers
@@ -254,23 +536,20 @@ Class helpers remain available for custom markup. The application owns its seman
 Generated by `bin/rails lostcoords:ui:builders`; `bin/lint` checks this list against the style helpers.
 
 <!-- builders -->
-- `lc_icon_badge_class(size: :base, extra: nil)` (BadgeHelper)
-- `lc_icon_medallion_class(size: :sm, tone: :accent, extra: nil)` (BadgeHelper)
-- `lc_avatar_class(size: :base, ink: false, linked: false, extra: nil)` (BadgeHelper)
+- `lc_icon_badge_class(size: :md, shape: :square, tone: :neutral, extra: nil)` (BadgeHelper)
+- `lc_avatar_class(size: :md, ink: false, linked: false, extra: nil)` (BadgeHelper)
 - `lc_avatar_stack_class(compact: false, extra: nil)` (BadgeHelper)
 - `lc_avatar_stack_row_class(extra: nil)` (BadgeHelper)
-- `lc_eyebrow_class(extra: nil)` (BadgeHelper)
 - `lc_badge_class(tone: :neutral, extra: nil)` (BadgeHelper)
-- `lc_status_pill_class(tone: :accent, extra: nil)` (BadgeHelper)
-- `lc_pill_class(active: false, ghost: false, size: :base, extra: nil)` (BadgeHelper)
-- `lc_pill_row_class(extra: nil)` (BadgeHelper)
-- `lc_button_class(variant: :default, size: :base, block: false, extra: nil)` (ButtonHelper)
-- `lc_icon_button_class(shape: :square, size: :base, extra: nil)` (ButtonHelper)
-- `lc_card_class(interactive: false, dense: false, extra: nil)` (CardHelper)
-- `lc_card_surface_class(extra: nil)` (CardHelper)
-- `lc_form_card_class(padding: :default, extra: nil)` (CardHelper)
+- `lc_toggle_class(active: false, ghost: false, size: :md, extra: nil)` (BadgeHelper)
+- `lc_button_class(variant: :primary, size: :md, block: false, extra: nil)` (ButtonHelper)
+- `lc_icon_button_class(shape: :square, size: :md, extra: nil)` (ButtonHelper)
+- `lc_card_class(interactive: false, padding: :md, extra: nil)` (CardHelper)
+- `lc_choice_label_class(card: false, extra: nil)` (ChoiceHelper)
+- `lc_checkbox_class(extra: nil)` (ChoiceHelper)
+- `lc_radio_class(extra: nil)` (ChoiceHelper)
+- `lc_switch_class(extra: nil)` (ChoiceHelper)
 - `lc_dialog_class(kind = :modal, extra: nil)` (DialogHelper)
-- `lc_dialog_surface_class(extra: nil)` (DialogHelper)
 - `lc_emoji_picker_groups` (EmojiPickerHelper)
 - `lc_emoji_picker_count` (EmojiPickerHelper)
 - `lc_emoji_picker_version` (EmojiPickerHelper)
@@ -278,20 +557,18 @@ Generated by `bin/rails lostcoords:ui:builders`; `bin/lint` checks this list aga
 - `lc_emoji_picker_search_name(emoji)` (EmojiPickerHelper)
 - `lc_emoji_picker_search_labels(emoji)` (EmojiPickerHelper)
 - `lc_emoji_picker_toneable?(emoji)` (EmojiPickerHelper)
-- `lc_spinner_class(size: :base, extra: nil)` (FeedbackHelper)
+- `lc_alert_class(extra: nil)` (FeedbackHelper)
+- `lc_alert_icon(tone: :destructive)` (FeedbackHelper)
+- `lc_spinner_class(size: :md, extra: nil)` (FeedbackHelper)
 - `lc_skeleton_class(extra: nil)` (FeedbackHelper)
 - `lc_empty_state_class(extra: nil)` (FeedbackHelper)
-- `lc_segmented_class(extra: nil)` (FormHelper)
-- `lc_segmented_tab_class(active: false, extra: nil)` (FormHelper)
-- `lc_input_class(size: :base, extra: nil)` (FormHelper)
-- `lc_dropdown_trigger_class(size: :base, extra: nil)` (FormHelper)
-- `lc_select_class(size: :base, extra: nil)` (FormHelper)
+- `lc_toggle_group_class(extra: nil)` (FormHelper)
+- `lc_toggle_group_item_class(active: false, extra: nil)` (FormHelper)
+- `lc_input_class(size: :md, extra: nil)` (FormHelper)
+- `lc_select_class(size: :md, extra: nil)` (FormHelper)
 - `lc_textarea_class(extra: nil)` (FormHelper)
 - `lc_field_class(extra: nil)` (FormHelper)
 - `lc_field_label_class(extra: nil)` (FormHelper)
-- `lc_form_actions_class(extra: nil)` (FormHelper)
-- `lc_form_alert_class(extra: nil)` (FormHelper)
-- `lc_form_alert_icon(tone: :error)` (FormHelper)
 - `lc_glass_class(shape: :bar, thick: false, extra: nil)` (GlassHelper)
 - `lc_stack_class(gap: :content, extra: nil)` (LayoutHelper)
 - `lc_inline_class(gap: :related, extra: nil)` (LayoutHelper)
@@ -300,16 +577,16 @@ Generated by `bin/rails lostcoords:ui:builders`; `bin/lint` checks this list aga
 - `lc_popover_class(align: :end, extra: nil)` (MenuHelper)
 - `lc_menu_popover_class(align: :end, extra: nil)` (MenuHelper)
 - `lc_menu_option_class(tone: :default, extra: nil)` (MenuHelper)
+- `lc_link_class(tone: :inherit, extra: nil)` (NavigationHelper)
+- `lc_nav_link_class(compact: false, extra: nil)` (NavigationHelper)
 - `lc_prose_class(extra: nil)` (ReadingHelper)
 - `lc_sheet_data(data = {}, detents: "fit")` (SheetHelper)
-- `lc_sheet_row_class(extra: nil)` (SheetHelper)
-- `lc_sheet_row_label_class(extra: nil)` (SheetHelper)
-- `lc_sheet_chip_class(active: false, member: false, extra: nil)` (SheetHelper)
-- `lc_sheet_datetime_input_class(extra: nil)` (SheetHelper)
-- `lc_sheet_text_input_class(extra: nil)` (SheetHelper)
+- `lc_table_class(extra: nil)` (TableHelper)
 - `lc_tw(*classes)` (TailwindHelper)
-- `lc_heading_class(size: :section, extra: nil)` (TypographyHelper)
-- `lc_text_class(size: :body, tone: :default, extra: nil)` (TypographyHelper)
+- `lc_heading_class(size: :heading, trim: false, extra: nil)` (TypographyHelper)
+- `lc_text_class(size: :body, tone: :default, trim: false, extra: nil)` (TypographyHelper)
+- `lc_kbd_class(extra: nil)` (TypographyHelper)
+- `lc_shortcut_data(keys, data = {})` (TypographyHelper)
 <!-- /builders -->
 
 ## Blocks
@@ -339,14 +616,5 @@ bin/test
 bin/lint
 ```
 
-The helper migration tool updates Ruby calls, ERB code, and Ruby/ERB Markdown examples to the `lc_`
-namespace. Run it in a consumer checkout to preview changes, then add `--write` to apply them.
-Review dynamic method names stored in strings separately.
-
-```sh
-ruby "$(bundle show lostcoords-ui)/script/migrate_helpers.rb" .
-ruby "$(bundle show lostcoords-ui)/script/migrate_helpers.rb" . --write
-```
-
 The icon catalog and its MIT license live in `vendor/heroicons`. Regenerate them from the pinned
 upstream archive with `ruby bin/update-icons`.

data/app/assets/tailwind/lostcoords/ui/avatar.css

@@ -1,11 +1,11 @@
 /* A linked avatar's ring draws inside its own footprint, so it takes exactly the space of an
    unlinked one: the outline sits on the edge, over any cutout border, and the inset shadow
    paints the gap in the surface colour. Contexts that already cut the avatar out with a
-   border set --avatar-ring-inset (or --avatar-ring-gap) so the gap doesn't double up. */
-@utility avatar-ring {
-  --avatar-ring: clamp(1.5px, calc(var(--avatar-size, var(--avatar-size-default, --spacing(8))) * 0.06), 3px);
+   border set --lc-avatar-ring-inset (or --lc-avatar-ring-gap) so the gap doesn't double up. */
+@utility lc-avatar-ring {
+  --lc-avatar-ring: clamp(1.5px, calc(var(--lc-avatar-size, var(--lc-avatar-size-default, --spacing(8))) * 0.06), 3px);
 
-  outline: var(--avatar-ring) solid color-mix(in oklab, var(--sky) 74%, var(--paper));
-  outline-offset: calc(var(--avatar-ring) * -1);
-  box-shadow: inset 0 0 0 var(--avatar-ring-inset, calc(var(--avatar-ring) * var(--avatar-ring-gap, 2))) var(--avatar-cutout, var(--paper));
+  outline: var(--lc-avatar-ring) solid color-mix(in oklab, var(--primary) 74%, var(--background));
+  outline-offset: calc(var(--lc-avatar-ring) * -1);
+  box-shadow: inset 0 0 0 var(--lc-avatar-ring-inset, calc(var(--lc-avatar-ring) * var(--lc-avatar-ring-gap, 2))) var(--lc-avatar-cutout, var(--background));
 }