plutonium 0.34.1 → 0.35.0

data/docs/guides/theming.md

@@ -4,11 +4,224 @@ This guide covers customizing colors, styles, and branding.
 
 ## Overview
 
-Plutonium uses TailwindCSS 4 for styling. Customization happens through:
+Plutonium uses TailwindCSS 4 with a design token system for consistent styling. Customization happens through:
 
+- **Design Tokens** - CSS custom properties for colors, spacing, shadows
+- **Component Classes** - Pre-built `.pu-*` classes for buttons, inputs, tables
 - **Tailwind Configuration** - Extend colors and design tokens
 - **Component Themes** - Override form, table, and display styling
-- **Asset Configuration** - Custom CSS, JS, logo, and favicon
+
+## Design Token System
+
+Plutonium uses CSS custom properties (design tokens) for theming. These tokens automatically adapt to light and dark modes.
+
+### Available Tokens
+
+#### Surface Colors
+
+```css
+--pu-body            /* Page background */
+--pu-surface         /* Card/panel backgrounds */
+--pu-surface-alt     /* Alternate surface (headers, sidebars) */
+--pu-surface-raised  /* Elevated surfaces */
+--pu-surface-overlay /* Modal/dropdown overlays */
+```
+
+#### Border Colors
+
+```css
+--pu-border        /* Default borders */
+--pu-border-muted  /* Subtle borders */
+--pu-border-strong /* Emphasized borders */
+```
+
+#### Text Colors
+
+```css
+--pu-text        /* Primary text */
+--pu-text-muted  /* Secondary text */
+--pu-text-subtle /* Tertiary/placeholder text */
+```
+
+#### Table Tokens
+
+```css
+--pu-table-header-bg    /* Header background */
+--pu-table-header-text  /* Header text color */
+--pu-table-row-bg       /* Row background */
+--pu-table-row-hover    /* Row hover state */
+--pu-table-row-selected /* Selected row */
+--pu-table-border       /* Row borders */
+```
+
+#### Form Tokens
+
+```css
+--pu-input-bg          /* Input background */
+--pu-input-border      /* Input border */
+--pu-input-focus-ring  /* Focus ring color */
+--pu-input-placeholder /* Placeholder text */
+```
+
+#### Card Tokens
+
+```css
+--pu-card-bg     /* Card background */
+--pu-card-border /* Card border */
+```
+
+#### Shadow System
+
+```css
+--pu-shadow-sm  /* Subtle shadow */
+--pu-shadow-md  /* Medium shadow */
+--pu-shadow-lg  /* Large shadow */
+```
+
+#### Spacing Scale
+
+```css
+--pu-space-xs  /* 0.25rem */
+--pu-space-sm  /* 0.5rem */
+--pu-space-md  /* 1rem */
+--pu-space-lg  /* 1.5rem */
+--pu-space-xl  /* 2rem */
+```
+
+#### Border Radius
+
+```css
+--pu-radius-sm   /* 0.375rem */
+--pu-radius-md   /* 0.5rem */
+--pu-radius-lg   /* 0.75rem */
+--pu-radius-xl   /* 1rem */
+--pu-radius-full /* 9999px */
+```
+
+#### Transitions
+
+```css
+--pu-transition-fast   /* 150ms */
+--pu-transition-normal /* 200ms */
+--pu-transition-slow   /* 300ms */
+```
+
+### Overriding Tokens
+
+Override tokens in your CSS to customize the theme:
+
+```css
+/* app/assets/stylesheets/application.css */
+@import "tailwindcss";
+@import "gem:plutonium/src/css/plutonium.css";
+
+/* Light mode overrides */
+:root {
+  --pu-surface: #fafafa;
+  --pu-border: #d4d4d4;
+  --pu-input-focus-ring: #6366f1;
+}
+
+/* Dark mode overrides */
+.dark {
+  --pu-surface: #18181b;
+  --pu-border: #3f3f46;
+}
+```
+
+## Component Classes
+
+Plutonium provides pre-built component classes for common UI elements.
+
+### Buttons
+
+```html
+<!-- Sizes -->
+<button class="pu-btn pu-btn-md pu-btn-primary">Medium</button>
+<button class="pu-btn pu-btn-sm pu-btn-primary">Small</button>
+<button class="pu-btn pu-btn-xs pu-btn-primary">Extra Small</button>
+
+<!-- Solid variants -->
+<button class="pu-btn pu-btn-md pu-btn-primary">Primary</button>
+<button class="pu-btn pu-btn-md pu-btn-secondary">Secondary</button>
+<button class="pu-btn pu-btn-md pu-btn-success">Success</button>
+<button class="pu-btn pu-btn-md pu-btn-danger">Danger</button>
+<button class="pu-btn pu-btn-md pu-btn-warning">Warning</button>
+<button class="pu-btn pu-btn-md pu-btn-info">Info</button>
+<button class="pu-btn pu-btn-md pu-btn-accent">Accent</button>
+
+<!-- Soft variants (tinted backgrounds) -->
+<button class="pu-btn pu-btn-md pu-btn-soft-primary">Soft Primary</button>
+<button class="pu-btn pu-btn-md pu-btn-soft-secondary">Soft Secondary</button>
+<button class="pu-btn pu-btn-md pu-btn-soft-success">Soft Success</button>
+<button class="pu-btn pu-btn-md pu-btn-soft-danger">Soft Danger</button>
+<button class="pu-btn pu-btn-md pu-btn-soft-warning">Soft Warning</button>
+<button class="pu-btn pu-btn-md pu-btn-soft-info">Soft Info</button>
+<button class="pu-btn pu-btn-md pu-btn-soft-accent">Soft Accent</button>
+
+<!-- Other styles -->
+<button class="pu-btn pu-btn-md pu-btn-ghost">Ghost</button>
+<button class="pu-btn pu-btn-md pu-btn-outline">Outline</button>
+```
+
+### Form Inputs
+
+```html
+<label class="pu-label">Email</label>
+<input type="email" class="pu-input" placeholder="you@example.com">
+<p class="pu-hint">We'll never share your email.</p>
+
+<!-- Validation states -->
+<input type="text" class="pu-input pu-input-invalid">
+<p class="pu-error">This field is required.</p>
+
+<input type="text" class="pu-input pu-input-valid">
+```
+
+### Checkboxes
+
+```html
+<input type="checkbox" class="pu-checkbox">
+```
+
+### Cards
+
+```html
+<div class="pu-card">
+  <div class="pu-card-body">
+    Card content here
+  </div>
+</div>
+```
+
+### Tables
+
+```html
+<div class="pu-table-wrapper">
+  <table class="pu-table">
+    <thead class="pu-table-header">
+      <tr>
+        <th class="pu-table-header-cell">Name</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr class="pu-table-body-row">
+        <td class="pu-table-body-cell">John</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+```
+
+### Empty States
+
+```html
+<div class="pu-empty-state">
+  <svg class="pu-empty-state-icon">...</svg>
+  <h3 class="pu-empty-state-title">No items found</h3>
+  <p class="pu-empty-state-description">Get started by creating a new item.</p>
+</div>
+```
 
 ## Setup Custom Assets
 
@@ -125,7 +338,7 @@ Plutonium includes these semantic colors:
 @import "tailwindcss";
 @config '../../../tailwind.config.js';
 
-/* Your custom styles */
+/* Your custom styles and token overrides */
 ```
 
 ## Component Themes
@@ -140,14 +353,14 @@ class PostDefinition < ResourceDefinition
     class Theme < Plutonium::UI::Form::Theme
       def self.theme
         super.merge({
-          base: "bg-white dark:bg-gray-800 shadow-md rounded-lg p-6",
+          base: "pu-card my-4 p-8 space-y-8",
           fields_wrapper: "grid grid-cols-2 gap-6",
           actions_wrapper: "flex justify-end mt-6 space-x-2",
-          label: "block mb-2 text-base font-bold",
-          input: "w-full p-2 border rounded-md shadow-sm",
-          hint: "mt-2 text-sm text-gray-500",
-          error: "mt-2 text-sm text-red-600",
-          button: "px-4 py-2 bg-primary-600 text-white rounded-md hover:bg-primary-700",
+          label: "pu-label",
+          input: "pu-input",
+          hint: "pu-hint",
+          error: "pu-error",
+          button: "pu-btn pu-btn-md pu-btn-primary",
         })
       end
     end
@@ -164,8 +377,8 @@ class PostDefinition < ResourceDefinition
       def self.theme
         super.merge({
           fields_wrapper: "grid grid-cols-3 gap-8",
-          label: "text-sm font-bold text-gray-500 mb-1",
-          string: "text-lg text-gray-900 dark:text-white",
+          label: "text-sm font-bold text-[var(--pu-text-muted)] mb-1",
+          string: "text-lg text-[var(--pu-text)]",
           link: "text-primary-600 hover:underline",
         })
       end
@@ -182,12 +395,12 @@ class PostDefinition < ResourceDefinition
     class Theme < Plutonium::UI::Table::Theme
       def self.theme
         super.merge({
-          wrapper: "overflow-x-auto shadow-md rounded-lg",
-          base: "w-full text-sm text-gray-500",
-          header: "text-xs uppercase bg-gray-100 dark:bg-gray-700",
-          header_cell: "px-6 py-3",
-          body_row: "bg-white border-b dark:bg-gray-800",
-          body_cell: "px-6 py-4",
+          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
@@ -253,6 +466,8 @@ document.documentElement.classList.toggle('dark');
 
 Plutonium includes a color mode selector component that handles this automatically.
 
+Design tokens automatically adapt to dark mode - override the `.dark` selector in your CSS to customize dark mode colors.
+
 ## Stimulus Controllers
 
 Register Plutonium's Stimulus controllers in your application:
@@ -296,25 +511,6 @@ import CustomController from "./custom_controller"
 application.register("custom", CustomController)
 ```
 
-## Portal-Specific Themes
-
-Different portals can have different themes by overriding definitions per-portal:
-
-```ruby
-# packages/admin_portal/app/definitions/admin_portal/post_definition.rb
-class AdminPortal::PostDefinition < ::PostDefinition
-  class Form < Form
-    class Theme < Plutonium::UI::Form::Theme
-      def self.theme
-        super.merge({
-          base: "bg-blue-50 p-8",  # Admin-specific styling
-        })
-      end
-    end
-  end
-end
-```
-
 ## Related
 
 - [Custom Actions](./custom-actions)

data/docs/index.md

@@ -2,81 +2,227 @@
 layout: home
 hero:
   name: Plutonium
-  text: Rapid Application Development for Rails
-  tagline: Build production-ready Rails applications in minutes, not months. Convention-driven, fully customizable.
+  text: Ship Rails Apps 10x Faster
+  tagline: Build production-ready Rails applications in minutes, not days. Convention-driven, fully customizable. Built for the AI era.
+  image:
+    src: /plutonium.png
+    alt: Plutonium
   actions:
     - theme: brand
-      text: Get Started
+      text: Get Started →
       link: /getting-started/
     - theme: alt
-      text: View on GitHub
+      text: GitHub
       link: https://github.com/radioactive-labs/plutonium-core
-
-features:
-  - icon: 🚀
-    title: Zero to Production Fast
-    details: Generate complete CRUD interfaces with a single command. Authentication, authorization, and UI included out of the box.
-  - icon: 🧩
-    title: Modular Architecture
-    details: Organize your app into Feature Packages and Portals. Each module is isolated, testable, and reusable.
-  - icon: 🎨
-    title: Fully Customizable
-    details: Every layer is overridable. Customize fields, forms, tables, pages, and styles without fighting the framework.
-  - icon: 🔐
-    title: Built-in Authorization
-    details: Policy-based authorization at every level - actions, attributes, and collection scoping. Multi-tenancy ready.
-  - icon: 📦
-    title: Convention over Configuration
-    details: Smart defaults detect your models, associations, and validations. Only configure what you need to change.
-  - icon: 🛠️
-    title: Rails Native
-    details: Built on Rails conventions. Uses Phlex for views, Rodauth for auth, and standard Rails patterns throughout.
 ---
 
-## Why Plutonium?
-
-Building admin panels, dashboards, and internal tools in Rails often means:
-- Writing repetitive CRUD code
-- Building authorization from scratch
-- Creating forms and tables manually
-- Handling multi-tenancy yourself
-
-**Plutonium eliminates this boilerplate** while remaining fully customizable.
+<div class="landing-content">
+
+<section class="before-after">
+  <h2>The Old Way vs The Plutonium Way</h2>
+  <div class="comparison">
+    <div class="before">
+      <h3>Without Plutonium</h3>
+      <div class="file-tree">
+        <div class="file">app/controllers/posts_controller.rb</div>
+        <div class="file">app/controllers/comments_controller.rb</div>
+        <div class="file">app/views/posts/index.html.erb</div>
+        <div class="file">app/views/posts/show.html.erb</div>
+        <div class="file">app/views/posts/new.html.erb</div>
+        <div class="file">app/views/posts/edit.html.erb</div>
+        <div class="file">app/views/posts/_form.html.erb</div>
+        <div class="file dim">...12 more files</div>
+      </div>
+      <div class="stats">
+        <span>~200 lines</span>
+        <span>30+ minutes</span>
+        <span>No auth yet</span>
+      </div>
+    </div>
+    <div class="arrow">→</div>
+    <div class="after">
+      <h3>With Plutonium</h3>
 
 ```bash
-# Create a new Plutonium app
-rails new myapp -a propshaft -j esbuild -c tailwind \
-  -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
+rails g pu:res:scaffold Post \
+  title:string body:text
 
-# Generate a resource
-rails g pu:res:scaffold Post title:string body:text published:boolean
-
-# Connect it to a portal
-rails g pu:res:conn Post --dest=admin_portal
+rails g pu:res:conn Post \
+  --dest=admin_portal
+```
 
-# Done. Full CRUD with auth, policies, and UI.
+  <div class="stats success">
+    <span>2 commands</span>
+    <span>30 seconds</span>
+    <span>Auth included</span>
+  </div>
+    </div>
+  </div>
+</section>
+
+<section class="ai-section">
+  <h2>Built for the AI Era</h2>
+  <p class="ai-intro">Plutonium is the first Rails framework designed from the ground up for AI-assisted development. Every pattern, every convention, every file structure is optimized for AI comprehension.</p>
+
+  <div class="ai-features">
+    <div class="ai-feature">
+      <div class="ai-icon">🧠</div>
+      <h3>Claude Code Skills</h3>
+      <p>20+ built-in skills teach AI assistants your app's patterns. Resources, policies, definitions, interactions - Claude understands them all.</p>
+    </div>
+    <div class="ai-feature">
+      <div class="ai-icon">⚡</div>
+      <h3>Predictable Patterns</h3>
+      <p>Convention-heavy architecture means AI can accurately predict file locations, naming, and relationships. Less hallucination, more precision.</p>
+    </div>
+    <div class="ai-feature">
+      <div class="ai-icon">🔄</div>
+      <h3>Generate & Iterate</h3>
+      <p>Tell Claude what you need. It generates the scaffold, policy, and definition. You refine. Ship in minutes what used to take hours.</p>
+    </div>
+  </div>
+
+  <div class="ai-example">
+    <div class="ai-prompt">
+      <span class="prompt-label">You say:</span>
+      <p>"Add a blog with posts and comments. Posts belong to users. Only authors can edit their posts. Add a publish action."</p>
+    </div>
+    <div class="ai-result">
+      <span class="result-label">Claude generates:</span>
+      <p>Model, migration, policy, definition, interaction, and connects it to your portal. Ready to customize.</p>
+    </div>
+  </div>
+</section>
+
+<section class="features-detailed">
+  <h2>Everything You Need, Nothing You Don't</h2>
+
+  <div class="feature-row">
+    <div class="feature-text">
+      <h3>Resources Are Your Foundation</h3>
+      <p>Just ActiveRecord. Associations, scopes, validations you already know. No new ORM to learn.</p>
+    </div>
+    <div class="feature-code">
+
+```ruby
+class Post < ApplicationRecord
+  include Plutonium::Resource::Record
+
+  belongs_to :author, class_name: "User"
+  has_many :comments
+
+  scope :published, -> { where.not(published_at: nil) }
+  scope :drafts, -> { where(published_at: nil) }
+end
 ```
 
-## How It Works
+  </div>
+  </div>
 
-Plutonium follows a layered architecture where each layer has a single responsibility:
+  <div class="feature-row reverse">
+    <div class="feature-text">
+      <h3>Definitions Control UI</h3>
+      <p>Declare how fields render. Add search, filters, scopes. Custom actions. All in one place.</p>
+    </div>
+    <div class="feature-code">
 
-| Layer | Purpose | File |
-|-------|---------|------|
-| **Model** | Data structure and validations | `app/models/post.rb` |
-| **Definition** | How the resource renders (fields, actions) | `app/definitions/post_definition.rb` |
-| **Policy** | Who can do what | `app/policies/post_policy.rb` |
-| **Controller** | HTTP handling and customization | `app/controllers/posts_controller.rb` |
+```ruby
+class PostDefinition < ResourceDefinition
+  input :body, as: :markdown
 
-Each layer auto-detects sensible defaults. You only write code when you need to customize.
+  search do |scope, query|
+    scope.where("title ILIKE ?", "%#{query}%")
+  end
 
-## Quick Links
+  scope :published
+  scope :drafts
 
-<div class="quick-links">
+  action :publish, interaction: PublishPost
+end
+```
+
+  </div>
+  </div>
+
+  <div class="feature-row">
+    <div class="feature-text">
+      <h3>Interactions Encapsulate Logic</h3>
+      <p>Complex actions become simple classes. Validated inputs. Clear outcomes. Easy to test.</p>
+    </div>
+    <div class="feature-code">
+
+```ruby
+class PublishPost < ResourceInteraction
+  attribute :resource
+  attribute :publish_at, :datetime
+
+  def execute
+    resource.published_at = publish_at
+    if resource.save
+      succeed(resource).with_message("Published!")
+    else
+      failed(resource.errors)
+    end
+  end
+end
+```
+
+  </div>
+  </div>
+
+  <div class="feature-row reverse">
+    <div class="feature-text">
+      <h3>Policies Control Access</h3>
+      <p>Define who can do what. Attribute-level permissions. Automatic scoping. No more <code>if current_user.admin?</code> scattered everywhere.</p>
+    </div>
+    <div class="feature-code">
+
+```ruby
+class PostPolicy < ResourcePolicy
+  def update?
+    record.author == user || user.admin?
+  end
+
+  def permitted_attributes_for_create
+    %i[title body]
+  end
+end
+```
 
-- [Installation Guide](/getting-started/installation) - Set up Plutonium in a new or existing Rails app
-- [Tutorial](/getting-started/tutorial/) - Build a complete blog application step by step
-- [Architecture Overview](/concepts/architecture) - Understand how the pieces fit together
-- [Reference Documentation](/reference/model/) - Detailed API documentation
+  </div>
+  </div>
+</section>
+
+<section class="feature-grid">
+  <div class="grid-item">
+    <div class="icon">📦</div>
+    <h3>Modular Packages</h3>
+    <p>Split your app into Feature Packages and Portals. Each isolated, testable, and reusable.</p>
+  </div>
+  <div class="grid-item">
+    <div class="icon">🔐</div>
+    <h3>Auth Built In</h3>
+    <p>Rodauth integration with login, registration, 2FA, and password reset. Ready in one command.</p>
+  </div>
+  <div class="grid-item">
+    <div class="icon">🏢</div>
+    <h3>Multi-Tenancy</h3>
+    <p>Entity scoping works out of the box. Path-based or custom strategies. Data isolation guaranteed.</p>
+  </div>
+  <div class="grid-item">
+    <div class="icon">🎨</div>
+    <h3>Fully Customizable</h3>
+    <p>Override any layer. Custom views with Phlex. Your CSS. No black boxes.</p>
+  </div>
+</section>
+
+<section class="cta-section">
+  <h2>Ready to Build Faster?</h2>
+  <p>Get a complete admin interface running in under 5 minutes.</p>
+  <div class="cta-buttons">
+    <a href="./getting-started/" class="cta-primary">Get Started</a>
+    <a href="./getting-started/tutorial/" class="cta-secondary">Follow the Tutorial</a>
+  </div>
+</section>
 
 </div>

data/docs/reference/controller/index.md

@@ -20,24 +20,19 @@ class PostsController < ::ResourceController
 end
 ```
 
-For portals:
+For portals, controllers inherit from the feature package's controller and include the portal's concern:
 
 ```ruby
-# packages/admin_portal/app/controllers/admin_portal/resource_controller.rb
-module AdminPortal
-  class ResourceController < ::ResourceController
-    include AdminPortal::Concerns::Controller
-  end
-end
-
 # packages/admin_portal/app/controllers/admin_portal/posts_controller.rb
-module AdminPortal
-  class PostsController < ResourceController
-    # Portal-specific customizations
-  end
+class AdminPortal::PostsController < ::PostsController
+  include AdminPortal::Concerns::Controller
+
+  # Portal-specific customizations
 end
 ```
 
+Controllers are auto-created if not defined. When accessing a portal resource controller, Plutonium dynamically creates it by inheriting from the feature package's controller.
+
 ## Built-in Actions
 
 | Action | HTTP Method | Path | Purpose |
@@ -67,10 +62,13 @@ current_parent          # Parent record for nested routes
 ### Authorization
 
 ```ruby
-authorize_current!(record, to: :action?)  # Check permission
-current_policy                            # Policy for current resource
-permitted_attributes                      # Allowed attributes for action
-current_authorized_scope                  # Scoped records user can access
+authorize_current!(record, to: :action?)   # Check permission
+current_policy                             # Policy for current resource
+permitted_attributes                       # Allowed attributes for action
+current_authorized_scope                   # Scoped records user can access
+authorized_resource_scope(Post)            # Authorized scope for a different resource
+policy_for(record)                         # Get policy for any record
+allowed_to?(:edit?, record)                # Check if action is allowed
 ```
 
 ### Definition Access