plutonium 0.50.0 → 0.51.0

data/docs/reference/testing/index.md

@@ -0,0 +1,287 @@
+# Testing Reference
+
+`Plutonium::Testing` provides scaffolded integration tests that assert a resource × portal pairing — CRUD, policy matrix, definition smoke tests, model concerns (associated_with, SGID, has_cents), nested-resource scope boundaries, cross-portal access, and interaction outcomes. All optional, all opt-in.
+
+## 🚨 Critical
+
+- **Use the generators.** `pu:test:install` once per app, then `pu:test:scaffold ResourceClass --portals=...` per resource × portal. Hand-written test files drift from conventions.
+- **Tests are opt-in.** `Plutonium::Testing` is only loaded when `require "plutonium/testing"` runs — it's never autoloaded, never present in production.
+- **One file per (resource × portal).** Same model in admin and org portals = two test files. Each portal has different auth, scoping, and allowed actions.
+- **Stub methods are required.** Concerns ship with `NotImplementedError` stubs — your test class supplies the test data via `create_resource!`, `valid_create_params`, `policy_roles`, etc.
+
+## Quick start
+
+```bash
+# Once per app
+rails g pu:test:install
+
+# Per resource × portal pairing
+rails g pu:test:scaffold Blogging::Post --portals=admin,org
+
+# Run
+bin/rails test
+```
+
+`pu:test:install` adds `require "plutonium/testing"` to `test/test_helper.rb` and creates `test/support/plutonium_testing.rb` (a stub for non-Rodauth auth overrides).
+
+## The DSL
+
+Every concern uses the same class-level DSL:
+
+```ruby
+resource_tests_for ResourceClass,
+  portal:           :admin,                              # required
+  path_prefix:      "/admin",                            # optional override
+  parent:           :organization,                       # for nested resources
+  actions:          %i[index show new create edit update destroy],
+  skip:             %i[destroy],
+  associated_with:  :organization,                       # ResourceModel only
+  sgid_routing:     true,                                # ResourceModel only
+  has_cents:        %i[price]                            # ResourceModel only
+```
+
+The **portal symbol** drives:
+
+| Derived | `:admin` example | `:org` example |
+|---|---|---|
+| `path_prefix` | `/admin` | `/org` |
+| Default sign-in helper | admin Rodauth | user Rodauth |
+| Allowed action set | from definition | from definition |
+
+`path_prefix` is auto-resolved from the mounted portal engine. For mounts inside `constraints` (typical Plutonium setup), the resolver walks the route tree and finds the engine.
+
+## Concerns
+
+Each concern is `include`d separately. Pick the ones you need.
+
+### `Plutonium::Testing::ResourceCrud`
+
+Generates index / show / new / create / edit / update / destroy integration tests against the portal-mounted resource.
+
+**Stubs:**
+
+- `create_resource!` → persisted record
+- `valid_create_params` → Hash for POST
+- `valid_update_params` → Hash for PATCH
+
+```ruby
+class AdminPortal::BloggingPostsTest < ActionDispatch::IntegrationTest
+  include IntegrationTestHelper
+  include Plutonium::Testing::ResourceCrud
+
+  resource_tests_for Blogging::Post, portal: :admin
+
+  setup do
+    @admin = create_admin!
+    @user  = create_user!
+    @org   = create_organization!
+    login_as(@admin)
+  end
+
+  def create_resource! = create_post!(user: @user, organization: @org)
+
+  def valid_create_params
+    {title: "x", body: "y", status: :draft, user: @user.to_sgid.to_s, organization: @org.to_sgid.to_s}
+  end
+
+  def valid_update_params = {title: "Updated"}
+end
+```
+
+### `Plutonium::Testing::ResourcePolicy`
+
+Asserts the `permit?` matrix across action × role and verifies `relation_scope` returns an `ActiveRecord::Relation`.
+
+**Stubs:**
+
+- `policy_roles` → `{role_sym => -> { account }}`
+- `policy_record` → persisted record under test
+- `policy_matrix` → `{action_sym => [allowed_role_syms]}`
+- `policy_context` (optional) → extra kwargs (defaults to `{entity_scope: nil}`)
+
+```ruby
+def policy_roles
+  {admin: -> { @admin }, member: -> { @user }}
+end
+
+def policy_record
+  create_post!(user: @user, organization: @org)
+end
+
+def policy_matrix
+  {
+    index:   %i[admin member],
+    show:    %i[admin member],
+    create:  %i[admin],
+    update:  %i[admin],
+    destroy: %i[admin]
+  }
+end
+```
+
+### `Plutonium::Testing::ResourceDefinition`
+
+Smoke-tests the resource definition: the class is constantize-able, every defineable prop dictionary (fields/inputs/displays/columns/scopes/filters/sorts/actions) is queryable, and declared fields exist on the model.
+
+**No stubs required** for the happy path.
+
+### `Plutonium::Testing::ResourceInteraction`
+
+Outcome-assertion helpers for `Plutonium::Resource::Interaction` subclasses.
+
+**Helpers:**
+
+- `assert_interaction_success(klass, **input)` → returns the success outcome
+- `assert_interaction_failure(klass, **input)` → returns the failure outcome
+- `interaction_view_context` (overridable) → defaults to a mock view context
+
+```ruby
+test "RebuildSearchInteraction succeeds" do
+  outcome = assert_interaction_success(RebuildSearchInteraction, since: 1.day.ago)
+  assert_equal 42, outcome.value[:rebuilt_count]
+end
+```
+
+### `Plutonium::Testing::ResourceModel`
+
+Tests `associated_with` scope, SGID routing, and `has_cents` accessors — gated by DSL flags.
+
+**Stubs:**
+
+- `model_test_record` → persisted record
+
+```ruby
+resource_tests_for Catalog::Product, portal: :admin,
+  associated_with: :organization,
+  sgid_routing:    true,
+  has_cents:       %i[price]
+
+def model_test_record = create_product!(user: @user, organization: @org)
+```
+
+Only the flagged features generate tests.
+
+### `Plutonium::Testing::NestedResource`
+
+Asserts CRUD under a parent + scope-boundary tests (sibling tenants invisible).
+
+**Stubs:**
+
+- `parent_record!` → current tenant
+- `other_parent_record!` → sibling tenant
+- `create_resource!(parent:)` → persisted record under given parent
+
+### `Plutonium::Testing::PortalAccess`
+
+Cross-portal access boundaries. Uses its own DSL — NOT `resource_tests_for`.
+
+```ruby
+class PortalAccessTest < ActionDispatch::IntegrationTest
+  include IntegrationTestHelper
+  include Plutonium::Testing::PortalAccess
+
+  portal_access_for portals: %i[admin org],
+    matrix: {admin: %i[admin], member: %i[org]}
+
+  setup do
+    @admin = create_admin!
+    @user  = create_user!
+    @org   = create_organization!
+    create_membership!(organization: @org, user: @user)
+  end
+
+  def login_as_role(role)
+    case role
+    when :admin  then login_as(@admin, portal: :admin)
+    when :member then login_as(@user, portal: :user)
+    end
+  end
+
+  def portal_root_path(portal)
+    case portal
+    when :admin then "/admin"
+    when :org   then "/org/#{@org.id}"
+    end
+  end
+end
+```
+
+Generates one test per (role × portal). Allowed = `200 | 302`; blocked = `302 | 401 | 403 | 404`.
+
+## Auth helpers
+
+`Plutonium::Testing::AuthHelpers` is included transitively by every concern.
+
+```ruby
+login_as(account)                       # uses portal from the DSL
+login_as(account, portal: :admin)       # explicit override
+sign_out                                # uses portal from the DSL
+sign_out(portal: :admin)
+current_account                         # uses portal from the DSL
+current_account(portal: :admin)
+with_portal(:org) { ... }              # scoped portal switch
+```
+
+### Override hook for non-Rodauth apps
+
+Define `sign_in_for_tests(account, portal:)` in your test class (or in `test/support/plutonium_testing.rb` for project-wide use). `AuthHelpers` will defer to it.
+
+```ruby
+def sign_in_for_tests(account, portal:)
+  # your custom auth flow here
+end
+```
+
+## Generators
+
+### `pu:test:install`
+
+```bash
+rails g pu:test:install
+```
+
+- Adds `require "plutonium/testing"` to `test/test_helper.rb` (idempotent)
+- Creates `test/support/plutonium_testing.rb` with override stub
+
+### `pu:test:scaffold`
+
+```bash
+rails g pu:test:scaffold Blogging::Post --portals=admin,org
+rails g pu:test:scaffold Blogging::Post --portals=admin --concerns=crud,policy,definition
+rails g pu:test:scaffold Blogging::Post --portals=org --parent=organization --dest=blogging
+```
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--portals=admin,org` | required | Emit one file per portal |
+| `--concerns=...` | `crud,policy,definition` | Concerns to include (`crud`, `policy`, `definition`, `nested`, `model`, `interaction`, `portal_access`) |
+| `--parent=organization` | | Wires `NestedResource` parent |
+| `--dest=main_app\|<package>` | `main_app` | Output destination |
+
+Output path: `test/integration/<portal>_portal/<resource_underscored>_test.rb`.
+
+## Customization & escape hatches
+
+- **Skip individual tests:** `resource_tests_for Klass, portal: :admin, skip: %i[destroy]`
+- **Restrict action set:** `resource_tests_for Klass, portal: :admin, actions: %i[index show]`
+- **Custom assertions:** add regular `test "..."` blocks alongside the generated matrix — they coexist.
+- **Non-Rodauth auth:** override `sign_in_for_tests`. See [AuthHelpers](#auth-helpers).
+- **Custom path prefix:** `path_prefix: "/v2/admin"` overrides portal resolution.
+
+## Common pitfalls
+
+- **Forgotten stubs raise `NotImplementedError`** with the stub name. Look for the missing method in your test class.
+- **Portal mismatch:** `:admin` portal expects `AdminPortal::Engine` constant. If your portal is named differently, pass `path_prefix:` explicitly.
+- **Tenant leakage in stubs:** `create_resource!` for an org portal must return a record bound to the test's `@org`. Otherwise scope filtering tests pass for the wrong reason.
+- **`policy_record` for tenant-scoped resources** must belong to a tenant the role has access to — otherwise even allowed roles will see `false`.
+- **Nested resources need `parent: :foo`** in the DSL AND a real parent record from `parent_record!`. Without both, path interpolation fails.
+- **`PortalAccess` doesn't use `resource_tests_for`** — use `portal_access_for` instead. Mixing them on the same class is undefined behavior.
+
+## Related
+
+- [Behavior › Policy](/reference/behavior/policies) — the policy methods `ResourcePolicy` verifies
+- [Behavior › Interaction](/reference/behavior/interactions) — interaction outcomes asserted by `ResourceInteraction`
+- [Resource › Definition](/reference/resource/definition) — definition props the smoke test introspects
+- [Tenancy](/reference/tenancy/) — parent scoping (`NestedResource`), entity strategies (drive auth/scoping)
+- [Auth](/reference/auth/) — Rodauth setup behind the default `sign_in_for_tests`
+- [Guides › Testing](/guides/testing) — task-oriented walkthrough

data/docs/reference/ui/assets.md

@@ -0,0 +1,400 @@
+# Assets
+
+TailwindCSS 4 + Stimulus toolchain. CSS design tokens for theming, `.pu-*` component classes for consistent styling, and a Phlexi theme system for component-level overrides.
+
+## 🚨 Critical
+
+- **Always register Stimulus controllers** — `registerControllers(application)` is required. Without it, Plutonium's controllers (color-mode, form, slim-select, flatpickr, easymde, etc.) are dead.
+- **Use `plutoniumTailwindConfig.merge`** when overriding the theme — plain object spread drops Plutonium's defaults.
+- **Tokens are CSS variables**, not Tailwind keys — `bg-[var(--pu-surface)]`, NOT `bg-pu-surface`.
+- **Dark mode uses `selector`** strategy — toggle `dark` on `<html>`. The bundled `color-mode` controller does this.
+- **Prefer `.pu-*` classes and `var(--pu-*)` tokens** over hardcoded `gray-X/dark:gray-Y` pairs — they switch with dark mode automatically.
+
+## Asset configuration
+
+```ruby
+# config/initializers/plutonium.rb
+Plutonium.configure do |config|
+  config.load_defaults 1.0
+
+  config.assets.stylesheet = "application"     # your CSS file
+  config.assets.script     = "application"     # your JS file
+  config.assets.logo       = "my_logo.png"
+  config.assets.favicon    = "my_favicon.ico"
+end
+```
+
+## Generator
+
+```bash
+rails generate pu:core:assets
+```
+
+This:
+
+1. Installs npm packages (`@radioactive-labs/plutonium`, TailwindCSS plugins).
+2. Creates `tailwind.config.js` extending Plutonium's config.
+3. Imports Plutonium CSS into `application.tailwind.css`.
+4. Registers Plutonium's Stimulus controllers.
+5. Updates Plutonium config to point at your asset files.
+
+## Tailwind config
+
+Generated `tailwind.config.js`:
+
+```javascript
+const { execSync } = require('child_process');
+const plutoniumGemPath = execSync("bundle show plutonium").toString().trim();
+const plutoniumTailwindConfig = require(`${plutoniumGemPath}/tailwind.options.js`);
+
+module.exports = {
+  darkMode: plutoniumTailwindConfig.darkMode,                       // 'selector'
+  plugins:  [].concat(plutoniumTailwindConfig.plugins),
+  theme:    plutoniumTailwindConfig.merge(
+              plutoniumTailwindConfig.theme,
+              { /* your overrides */ },
+            ),
+  content: [
+    `${__dirname}/app/**/*.{erb,haml,html,slim,rb}`,
+    `${__dirname}/app/javascript/**/*.js`,
+    `${__dirname}/packages/**/app/**/*.{erb,haml,html,slim,rb}`,
+  ].concat(plutoniumTailwindConfig.content),
+};
+```
+
+::: danger Use `plutoniumTailwindConfig.merge`
+A plain spread (`...plutoniumTailwindConfig.theme`) drops the merge logic and you lose Plutonium's defaults. Always use `merge(...)`.
+:::
+
+### Customizing colors
+
+```javascript
+theme: plutoniumTailwindConfig.merge(plutoniumTailwindConfig.theme, {
+  extend: {
+    colors: {
+      primary: { 50: '#eff6ff', 500: '#3b82f6', 900: '#1e3a8a' },
+    },
+  },
+})
+```
+
+### Default color palette
+
+| Color | Usage |
+|---|---|
+| `primary` | Brand primary (turquoise default) |
+| `secondary` | Brand secondary (navy default) |
+| `success` | Success states (green) |
+| `info` | Informational (blue) |
+| `warning` | Warning (amber) |
+| `danger` | Error (red) |
+| `accent` | Highlight (coral pink) |
+
+## CSS imports
+
+```css
+/* app/assets/stylesheets/application.tailwind.css */
+@import "gem:plutonium/src/css/plutonium.css";
+
+@import "tailwindcss";
+@config '../../../tailwind.config.js';
+
+/* your styles */
+```
+
+Plutonium CSS includes core utility classes, EasyMDE (markdown editor), Slim Select, intl-tel-input, Flatpickr (date picker).
+
+## Stimulus
+
+```javascript
+// app/javascript/controllers/index.js
+import { application } from "./application"
+import { registerControllers } from "@radioactive-labs/plutonium"
+
+registerControllers(application)
+
+// Your custom controllers...
+import CustomController from "./custom_controller"
+application.register("custom", CustomController)
+```
+
+### Bundled controllers
+
+- `color-mode` — dark/light mode toggle
+- `form` — form handling (pre-submit, etc.)
+- `nested-resource-form-fields` — nested form management
+- `slim-select` — enhanced select boxes
+- `flatpickr` — date/time pickers
+- `easymde` — markdown editor
+- Various internal UI controllers
+
+### Custom Stimulus controller — standard pattern
+
+```javascript
+// app/javascript/controllers/custom_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  connect() {
+    console.log("Custom controller connected")
+  }
+}
+```
+
+```javascript
+// Register
+application.register("custom", CustomController)
+```
+
+## Design tokens
+
+Plutonium uses a comprehensive CSS custom-property system for consistent, themeable UI components. Tokens auto-switch with dark mode. Source: `src/css/tokens.css`.
+
+### Surface & backgrounds
+
+```css
+/* Light */
+--pu-body:             #f8fafc;
+--pu-surface:          #ffffff;
+--pu-surface-alt:      #f1f5f9;
+--pu-surface-raised:   #ffffff;
+--pu-surface-overlay:  rgba(255, 255, 255, 0.95);
+
+/* Dark (.dark class) */
+--pu-body:             #0f172a;
+--pu-surface:          #1e293b;
+--pu-surface-alt:      #0f172a;
+--pu-surface-raised:   #334155;
+--pu-surface-overlay:  rgba(30, 41, 59, 0.95);
+```
+
+### Text
+
+```css
+/* Light */
+--pu-text:         #0f172a;
+--pu-text-muted:   #64748b;
+--pu-text-subtle:  #94a3b8;
+
+/* Dark */
+--pu-text:         #f8fafc;
+--pu-text-muted:   #94a3b8;
+--pu-text-subtle:  #64748b;
+```
+
+### Borders, forms, cards
+
+```css
+--pu-border:         #e2e8f0;
+--pu-border-muted:   #f1f5f9;
+--pu-border-strong:  #cbd5e1;
+
+--pu-input-bg:           #ffffff;
+--pu-input-border:       #e2e8f0;
+--pu-input-focus-ring:   theme(colors.primary.500);
+--pu-input-placeholder:  #94a3b8;
+
+--pu-card-bg:      #ffffff;
+--pu-card-border:  #e2e8f0;
+```
+
+### Shadows, radii, spacing, transitions
+
+```css
+--pu-shadow-sm:  0 1px 2px 0 rgb(0 0 0 / 0.03), 0 1px 3px 0 rgb(0 0 0 / 0.05);
+--pu-shadow-md:  0 2px 4px -1px rgb(0 0 0 / 0.04), 0 4px 6px -1px rgb(0 0 0 / 0.06);
+--pu-shadow-lg:  0 4px 6px -2px rgb(0 0 0 / 0.03), 0 10px 15px -3px rgb(0 0 0 / 0.08);
+
+--pu-radius-sm:    0.375rem;
+--pu-radius-md:    0.5rem;
+--pu-radius-lg:    0.75rem;
+--pu-radius-xl:    1rem;
+--pu-radius-full:  9999px;
+
+--pu-space-xs:  0.25rem;
+--pu-space-sm:  0.5rem;
+--pu-space-md:  1rem;
+--pu-space-lg:  1.5rem;
+--pu-space-xl:  2rem;
+
+--pu-transition-fast:    150ms cubic-bezier(0.4, 0, 0.2, 1);
+--pu-transition-normal:  200ms cubic-bezier(0.4, 0, 0.2, 1);
+--pu-transition-slow:    300ms cubic-bezier(0.4, 0, 0.2, 1);
+```
+
+### Customizing tokens
+
+```css
+/* app/assets/stylesheets/application.tailwind.css */
+@import "gem:plutonium/src/css/plutonium.css";
+@import "tailwindcss";
+
+:root {
+  --pu-surface: #fafafa;
+  --pu-border:  #d1d5db;
+}
+
+.dark {
+  --pu-surface: #111827;
+  --pu-border:  #374151;
+}
+```
+
+### Using tokens in templates
+
+```erb
+<h1 class="text-[var(--pu-text)]">Title</h1>
+<p class="text-[var(--pu-text-muted)]">Description</p>
+
+<div class="bg-[var(--pu-surface)] border border-[var(--pu-border)] rounded-[var(--pu-radius-lg)]">
+  Content
+</div>
+```
+
+```ruby
+class MyComponent < Plutonium::UI::Component::Base
+  def view_template
+    div(
+      class: "bg-[var(--pu-surface)] border border-[var(--pu-border)] rounded-[var(--pu-radius-lg)]",
+      style: "box-shadow: var(--pu-shadow-md)"
+    ) do
+      h2(class: "text-lg font-semibold text-[var(--pu-text)]") { "Title" }
+      p(class: "text-[var(--pu-text-muted)]") { "Description" }
+    end
+  end
+end
+```
+
+## Component classes (`.pu-*`)
+
+Ready-to-use styled components in `src/css/components.css`. **Prefer these over hardcoded `gray-X/dark:gray-Y` pairs** — they auto-switch with dark mode.
+
+### Buttons
+
+```
+.pu-btn                            (base)
+.pu-btn-md / -sm / -xs             (size)
+.pu-btn-primary / -secondary / -danger / -success / -warning / -info / -accent
+.pu-btn-ghost / -outline
+.pu-btn-soft-primary / -soft-danger / ...
+```
+
+```erb
+<%= form.submit "Save", class: "pu-btn pu-btn-md pu-btn-primary" %>
+```
+
+### Inputs, labels, hints, errors
+
+```
+.pu-input / -invalid / -valid
+.pu-label / -required
+.pu-hint / .pu-error
+.pu-checkbox
+```
+
+### Cards, panels, tables, toolbars, empty states
+
+```
+.pu-card / .pu-card-body
+.pu-panel-header / -title / -description
+.pu-table-wrapper / .pu-table / -header / -header-cell / -body-row / -body-row-selected / -body-cell / .pu-selection-cell
+.pu-toolbar / -text / -actions
+.pu-empty-state / -icon / -title / -description
+```
+
+### Ruby constants
+
+`Plutonium::UI::ComponentClasses` (in `lib/plutonium/ui/component_classes.rb`):
+
+```ruby
+ComponentClasses::Button.classes(variant: :primary, size: :default, soft: false)
+# => "pu-btn pu-btn-md pu-btn-primary"
+
+ComponentClasses::Form::INPUT       # "pu-input"
+ComponentClasses::Form::LABEL       # "pu-label"
+ComponentClasses::Table::WRAPPER    # "pu-table-wrapper"
+ComponentClasses::Card::BASE        # "pu-card"
+```
+
+## Migration from hardcoded classes
+
+| Old | New |
+|---|---|
+| `text-gray-900 dark:text-white` | `text-[var(--pu-text)]` |
+| `text-gray-500 dark:text-gray-400` | `text-[var(--pu-text-muted)]` |
+| `bg-gray-50 dark:bg-gray-700` | `bg-[var(--pu-surface)]` |
+| `border-gray-300 dark:border-gray-600` | `border-[var(--pu-border)]` |
+| Long input class chain | `pu-input` |
+| `block mb-2 text-sm font-semibold ...` | `pu-label` |
+| `text-red-600 dark:text-red-400` | `pu-error` |
+| Long button class chain | `pu-btn pu-btn-md pu-btn-primary` |
+
+## Phlexi component themes
+
+Plutonium components use a Phlexi-based theme system for customizing Form, Display, and Table components. Each has a theme class with named style tokens.
+
+### Form theme
+
+See [Forms › Theming](./forms#theming) for the full Form theme surface.
+
+### Display theme
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Display < Display
+    class Theme < Plutonium::UI::Display::Theme
+      def self.theme
+        super.merge(
+          fields_wrapper: "grid grid-cols-3 gap-8",
+          label:          "text-sm font-bold text-[var(--pu-text-muted)] mb-1",
+          string:         "text-lg text-[var(--pu-text)]",
+          markdown:       "prose dark:prose-invert max-w-none"
+        )
+      end
+    end
+  end
+end
+```
+
+**Theme keys:** `fields_wrapper`, `label`, `description`, `string`, `text`, `link`, `email`, `phone`, `markdown`, `json`.
+
+### Table theme
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Table < Table
+    class Theme < Plutonium::UI::Table::Theme
+      def self.theme
+        super.merge(
+          wrapper:      "pu-table-wrapper",
+          base:         "pu-table",
+          header:       "pu-table-header",
+          header_cell:  "pu-table-header-cell",
+          body_row:     "pu-table-body-row",
+          body_cell:    "pu-table-body-cell"
+        )
+      end
+    end
+  end
+end
+```
+
+**Theme keys:** `wrapper`, `base`, `header`, `header_cell`, `body_row`, `body_cell`, `sort_icon`.
+
+::: warning Always `super.merge(...)`
+Don't replace the theme wholesale. Plutonium's defaults handle invalid states, focus rings, and dark mode — `super.merge` keeps them.
+:::
+
+## Gotchas
+
+- **Stimulus controllers register silently fails.** If `registerControllers(application)` isn't called, the entire UI's interactive layer is dead (color-mode toggle, slim-select, flatpickr, easymde, pre-submit). No error — just no behavior.
+- **`plutoniumTailwindConfig.merge` is mandatory.** Plain spread drops defaults silently.
+- **Tokens are CSS variables, not Tailwind keys.** Use `bg-[var(--pu-surface)]`, not `bg-pu-surface`.
+- **Dark mode is `selector`, not `class`.** Toggle via `document.documentElement.classList.toggle('dark')`.
+- **`.pu-*` classes auto-switch with dark mode.** Hardcoded `gray-X/dark:gray-Y` pairs don't get auto-updated when tokens change.
+
+## Related
+
+- [Forms › Theming](./forms#theming) — Form theme keys + override pattern
+- [Components](./components) — `tokens` and `classes` helpers for conditional class composition
+- [Layouts](./layouts) — fonts, dark-mode toggle, body attributes