DEV Community: Rails Designer

Choosing colors (for developers)

Rails Designer — Fri, 14 Aug 2026 07:30:00 +0000

The eleven-shade color scale from Tailwind CSS is one of those ideas I keep stealing. You know the one: 50 through 950 gives you enough stops for backgrounds, borders, hover states, text, everything. I use it even when I’m not using Tailwind.

But I almost never use the defaults (your site/app ends up looking like every other site built by LLMs).

The fix is not complicated. You don’t need a color theory degree or a five-color palette generator (you know the ones 🥹). You only need two or three color scales, and you can derive them all from a single value.

How to choose your brand hue

Rule of thumb: pick a color that fits the problem, not your personal taste (I like pink but not use it all the time).

Finance, B2B and enterprise sites use blues (hue 200-250).
Trust, stability, conservative. Health and wellness lean green or teal (120-200). Calm, natural.
Creative and entertainment go purple, pink, orange (270-360). Energy, fun.
Food and hospitality use reds, oranges, warm yellows (0-60). Appetite, warmth.

These are guidelines, not rules. A creative agency can use blue. A bank can use orange. But the defaults exist for a reason. They match user expectations.

Still stuck? Steal from a site you like. Find an app or landing page whose color feels right for your domain. Open DevTools, grab the hue from any OKLCH color on the page. That is your starting point. Adjust from there.

If you have an image (hero photo, logo, brand asset), sample a prominent color from it. Drop it into a color picker, get the OKLCH hue. Images that already look good together contain colors that already work together.

You do not need to nail it on the first try. Pick something reasonable, build the palette, see it on a real page. If it feels wrong, shift the hue by 30 and check again. Five minutes of tweaking beats an hour of analysis. 💪

Pick a neutral, name it `--gray`

First, a naming trick. Whatever neutral you settle on, alias it to --gray-*. This way your templates reference --gray-500 regardless of which tone you picked.

:root {
  --gray-50: #f8fafc;
  --gray-100: #f1f5f9;
  --gray-200: #e2e8f0;
  /* … */
}

The point is the name --gray stays the same. Want a warmer tone next month? Change the values, not every template.

If I use Tailwind, I use the same trick (but map them with the --color- prefix so bg-gray-500 works):

@theme {
  --color-gray-50: var(--gray-50);
  --color-gray-100: var(--gray-100);
}

One hue to rule them

OKLCH makes this easy. Instead of hardcoding eleven hex values for your brand, derive them from a single hue variable.

I covered the technique before in Building user-customizable themes with Tailwind CSS. The idea: OKLCH separates color into lightness, chroma and hue. Keep lightness and chroma constant per shade level, vary only the hue.

:root {
  --brand-hue: 250;

  --brand-50: oklch(.99 .01 var(--brand-hue));
  --brand-100: oklch(.98 .02 var(--brand-hue));
  --brand-200: oklch(.94 .04 var(--brand-hue));
  --brand-300: oklch(.86 .08 var(--brand-hue));
  --brand-400: oklch(.74 .14 var(--brand-hue));
  --brand-500: oklch(.6 .18 var(--brand-hue));
  --brand-600: oklch(.52 .16 var(--brand-hue));
  --brand-700: oklch(.44 .14 var(--brand-hue));
  --brand-800: oklch(.36 .12 var(--brand-hue));
  --brand-900: oklch(.26 .08 var(--brand-hue));
  --brand-950: oklch(.16 .04 var(--brand-hue));
}

Change --brand-hue from 250 to 10 and every shade updates. The palette stays harmonious because lightness and chroma never shift.

One thing to watch: OKLCH math gets you 90% of the way there. Different hues at the same lightness and chroma can feel slightly different to the eye — a purple at .6 .18 reads differently than a yellow at .6 .18. You might need to bump a stop or two for balance. That is normal. Tweak and move on.

Gray from your brand tint

Create a neutral palette the same way. Drop the chroma near zero:

:root {
  --gray-50: oklch(.99 .005 var(--brand-hue));
  --gray-100: oklch(.97 .005 var(--brand-hue));
  --gray-200: oklch(.93 .005 var(--brand-hue));
  --gray-300: oklch(.86 .008 var(--brand-hue));
  --gray-400: oklch(.76 .01 var(--brand-hue));
  --gray-500: oklch(.64 .01 var(--brand-hue));
  --gray-600: oklch(.54 .01 var(--brand-hue));
  --gray-700: oklch(.44 .01 var(--brand-hue));
  --gray-800: oklch(.34 .008 var(--brand-hue));
  --gray-900: oklch(.24 .005 var(--brand-hue));
  --gray-950: oklch(.14 .005 var(--brand-hue));
}

These read as neutral grays. But they carry a faint undertone of your brand color. The result is cohesive without being matchy-matchy.

Color theory with math

Complementary colors sit opposite each other on the color wheel. In OKLCH that is + 180 degrees.

:root {
  --accent-50: oklch(.99 .01 calc(var(--brand-hue) + 180));
  --accent-100: oklch(.98 .02 calc(var(--brand-hue) + 180));
  --accent-200: oklch(.94 .04 calc(var(--brand-hue) + 180));
  --accent-300: oklch(.86 .08 calc(var(--brand-hue) + 180));
  --accent-400: oklch(.74 .14 calc(var(--brand-hue) + 180));
  --accent-500: oklch(.6 .18 calc(var(--brand-hue) + 180));
  --accent-600: oklch(.52 .16 calc(var(--brand-hue) + 180));
  --accent-700: oklch(.44 .14 calc(var(--brand-hue) + 180));
  --accent-800: oklch(.36 .12 calc(var(--brand-hue) + 180));
  --accent-900: oklch(.26 .08 calc(var(--brand-hue) + 180));
  --accent-950: oklch(.16 .04 calc(var(--brand-hue) + 180));
}

That is the simplest color scheme: complementary. High contrast, punches hard.

But you have more options. Here is how color schemes translate to OKLCH math:

Analogous — hues next to your brand (± 30). Low contrast, harmonious. Good for backgrounds and subtle variety.
Complementary — opposite hue (+ 180). High contrast, pops. Good for CTAs and accents.
Split complementary — the two hues on either side of the complement (+ 150 and - 150). Same contrast as complementary but safer. Less jarring.
Triadic — three hues evenly spaced (+ 120 and + 240). Balanced. Gives you a third color for free.

--analogous-light: calc(var(--brand-hue) + 30);
--analogous-dark: calc(var(--brand-hue) - 30);
--split-a: calc(var(--brand-hue) + 150);
--split-b: calc(var(--brand-hue) - 150);
--triad-a: calc(var(--brand-hue) + 120);
--triad-b: calc(var(--brand-hue) + 240);

Pick one scheme and stick with it. The math guarantees the relationship. You just pick the starting hue.

All together now

:root {
  --brand-hue: 250;

  /* Gray (low chroma, brand undertone) */
  --gray-50: oklch(.99 .005 var(--brand-hue));
  --gray-100: oklch(.97 .005 var(--brand-hue));
  --gray-200: oklch(.93 .005 var(--brand-hue));
  --gray-300: oklch(.86 .008 var(--brand-hue));
  --gray-400: oklch(.76 .01 var(--brand-hue));
  --gray-500: oklch(.64 .01 var(--brand-hue));
  --gray-600: oklch(.54 .01 var(--brand-hue));
  --gray-700: oklch(.44 .01 var(--brand-hue));
  --gray-800: oklch(.34 .008 var(--brand-hue));
  --gray-900: oklch(.24 .005 var(--brand-hue));
  --gray-950: oklch(.14 .005 var(--brand-hue));

  /* Brand */
  --brand-50: oklch(.99 .01 var(--brand-hue));
  --brand-100: oklch(.98 .02 var(--brand-hue));
  --brand-200: oklch(.94 .04 var(--brand-hue));
  --brand-300: oklch(.86 .08 var(--brand-hue));
  --brand-400: oklch(.74 .14 var(--brand-hue));
  --brand-500: oklch(.6 .18 var(--brand-hue));
  --brand-600: oklch(.52 .16 var(--brand-hue));
  --brand-700: oklch(.44 .14 var(--brand-hue));
  --brand-800: oklch(.36 .12 var(--brand-hue));
  --brand-900: oklch(.26 .08 var(--brand-hue));
  --brand-950: oklch(.16 .04 var(--brand-hue));

  /* Accent (complementary) */
  --accent-50: oklch(.99 .01 calc(var(--brand-hue) + 180));
  --accent-100: oklch(.98 .02 calc(var(--brand-hue) + 180));
  --accent-200: oklch(.94 .04 calc(var(--brand-hue) + 180));
  --accent-300: oklch(.86 .08 calc(var(--brand-hue) + 180));
  --accent-400: oklch(.74 .14 calc(var(--brand-hue) + 180));
  --accent-500: oklch(.6 .18 calc(var(--brand-hue) + 180));
  --accent-600: oklch(.52 .16 calc(var(--brand-hue) + 180));
  --accent-700: oklch(.44 .14 calc(var(--brand-hue) + 180));
  --accent-800: oklch(.36 .12 calc(var(--brand-hue) + 180));
  --accent-900: oklch(.26 .08 calc(var(--brand-hue) + 180));
  --accent-950: oklch(.16 .04 calc(var(--brand-hue) + 180));
}

Use them anywhere:

.btn--primary {
  background: var(--brand-500);

  &:hover {
    background: var(--brand-600);
  }
}

.card {
  background: var(--gray-50);
  border: 1px solid var(--gray-100);
}

.badge--new {
  color: var(--accent-700);
  background: var(--accent-100);
}

Three palettes. One variable to change them all. No hex codes to manage. Winning! 🏆

Above :root{} content is easily copied from one app or site to your next one. Making sure you can return building quickly.

Recreating Stimulus: targets, actions and reactive values

Rails Designer — Thu, 13 Aug 2026 07:30:00 +0000

This is part 2 of a two-part series. Part 1 covered controllers and lifecycle.

Controllers connect and disconnect. That is not useful on its own. The value comes from three things: referencing elements inside the controller, handling events without inline JavaScript and reacting to data changes. Stimulus calls these targets, actions and values.

Each maps to a distinct JavaScript feature. And none of them repeat the tricks from part 1.

Here is the code. See the full commit on GitHub.

Targets: dynamic getters

A target is a named element inside a controller’s scope. Declare it in the class and get a getter for free:

class HelloController extends Controller {
  static targets = ["name", "output"]
}

The getter this.nameTarget returns the first element with data-hello-target="name" inside the controller element. The plural this.nameTargets returns all of them. The existence this.hasNameTarget returns true or false.

These getters do not exist at compile time. They are created dynamically using Object.defineProperty:

export function wireTargets(controller, identifier) {
  for (const name of controller.constructor.targets) {
    Object.defineProperty(controller, `${camelize(name)}Target`, {
      get() {
        return this.element.querySelector(`[data-${identifier}-target="${name}"]`)
      }
    })

    Object.defineProperty(controller, `${camelize(name)}Targets`, {
      get() {
        return this.element.querySelectorAll(`[data-${identifier}-target="${name}"]`)
      }
    })
  }
}

Object.defineProperty defines a property on an existing object with configurable behavior (in Ruby, you’d use define_method or attr_accessor with a custom getter to achieve similar dynamic property behavior). The getter runs every time the property is accessed, so the query is always live. If the DOM changes, the getter returns the updated result. No manual refresh needed.

This is different from a regular property assignment. With controller.nameTarget = value you set a static value. With Object.defineProperty you control every aspect: get, set, enumerable and configurable (in Ruby, this level of control over property access would be achieved using method_missing or define_method with custom logic to intercept and control all aspects of property access).

Actions: event delegation

Actions wire DOM events to controller methods. In HTML you write:

<button data-action="click->hello#greet">Greet</button>

No addEventListener in sight. The framework handles it with a single document-level listener per event type. This is event delegation, and it works like this:

export function energize(lookup) {
  controllerLookup = lookup

  for (const eventType of ["click", "submit", "change", "input", "keydown", "keyup"]) {
    document.addEventListener(eventType, spark)
  }
}

function spark(event) {
  const actionElement = event.target.closest("[data-action]")
  if (!actionElement) return

  const raw = actionElement.getAttribute("data-action")
  const descriptors = raw.split(" ").map(part => part.trim()).filter(Boolean)

  for (const descriptor of descriptors) {
    const route = deconstruct(descriptor, event.type)
    if (!route) continue

    const controllerElement = actionElement.closest(`[data-controller~="${route.identifier}"]`)
    if (!controllerElement) continue

    const controller = controllerLookup(controllerElement)
    if (!controller) continue

    if (typeof controller[route.methodName] === "function") {
      controller[route.methodName](event)
    }
  }
}

One listener per event type on document. No matter how many action-annotated elements are on the page. When a click fires, event.target.closest("[data-action]") walks up the DOM tree to find the nearest element with an action attribute. If it finds one, the descriptor is parsed and the right method is called.

The parsing is straightforward string work with split and trim:

function deconstruct(descriptor, eventType) {
  const parts = descriptor.split("->")

  if (parts.length === 2) {
    if (parts[0].trim() !== eventType) return null

    const rest = parts[1].split("#")

    return { identifier: rest[0].trim(), methodName: rest[1].trim() }
  }

  return null
}

This is the old-school JavaScript that never goes out of style. No regex, no framework. Just split, trim and a conditional. 🧓

Values: reactive data

Values bring reactivity. Declare them with a type and get getter, setter and change callback:

class HelloController extends Controller {
  static values = { count: Number }

  countValueChanged(current, previous) {
    console.log(`Count went from ${previous} to ${current}`)
  }
}

Setting this.countValue = this.countValue + 1 updates the attribute data-hello-count-value on the DOM element and fires countValueChanged with the old and new values.

The implementation uses Object.defineProperty again, this time with both a getter and a setter:

Object.defineProperty(controller, propertyName, {
  get() {
    return stored
  },

  set(value) {
    const previous = stored
    if (value === previous) return

    stored = value
    controller.element.setAttribute(attributeName, serialize(value, type))

    const changedCallback = `${camelize(name)}ValueChanged`
    if (typeof controller[changedCallback] === "function") {
      controller[changedCallback](value, previous)
    }
  }
})

The getter returns a cached value. The setter stores the new value, syncs it to the DOM attribute and calls the change callback if it exists. The if (value === previous) return guard prevents unnecessary updates.

Type coercion happens through a helper that maps JavaScript constructors to coercion logic:

function read(raw, type) {
  if (type === Number) return raw === "" || raw === null ? null : Number(raw)
  if (type === Boolean) return raw === "true" || raw === "1"
  if (type === Array || type === Object) {
    try { return JSON.parse(raw) } catch { return raw }
  }
  return raw
}

Number("42") returns 42. JSON.parse("[1,2,3]") returns an actual array. "false" as Boolean returns… well, Boolean("false") would return true (non-empty string is truthy). So we check the string value directly. These are the small traps that make framework development interesting. 😬

Three features, three JavaScript concepts. Object.defineProperty for dynamic accessors. Event delegation via closest(). Static class fields for declarative configuration. Plus a dash of JSON.parse and Number for type coercion.

All code from this article (and the previous one) is in the recreate-stimulus repo.

Courrier: a gem to send emails without SMTP

Rails Designer — Mon, 10 Aug 2026 07:30:00 +0000

Every transactional email provider ships a Ruby SDK. Each one has its own client class, its own conventions, its own way of doing the same thing. I got tired of learning yet another API for every project. So I built Courrier.

About 14 months and 73 commits later, Courrier 1.0 is here. It covers 13 email providers and 7 newsletter platforms. There’s a companion gem for Rails apps that adds generators, ActiveJob support, browser-based inbox previews and more.

Star it on GitHub ✨

13 providers, one API

Courrier.configure do |config|
  config.email = {
    provider: :postmark,
    api_key: "your_postmark_api_key"
  }

  config.from = "devs@railsdesigner.com"
end

# courrier/emails/order_email.rb
class OrderEmail < Courrier::Email
  def subject = "Your order is ready!"

  def text
    <<~TEXT
      Thanks for ordering, #{name}!

      Your order ##{order_id} is on its way.
    TEXT
  end

  def html
    <<~HTML
      <h1>Thanks for ordering!</h1>

      <p>Your order ##{order_id} is on its way.</p>
    HTML
  end
end

OrderEmail.deliver to: "customer@railsdesigner.com", name: "Cam", order_id: 42

That’s it. That’s the whole thing. One class, one deliver call, works with any supported provider.

Courrier has three levels of configuration that build on each other. Set defaults globally, override per email class or per delivery. Need to use Mailpace for transactional emails and Postmark for marketing? Easy. Need a provider not on the list? Subclass Courrier::Email::Providers::Base and add it yourself.

Content your way

The example above uses text and html methods. That’s the simplest path and works for most cases.

Prefer markdown? Define a markdown method instead. Courrier detects your markdown engine (kramdown, redcarpet or commonmarker) automatically and renders it to HTML.

Want the same structure as ViewComponent gives you (an ERB template alongside your email class):

courrier/emails/order_email.rb
courrier/emails/order_email.html.erb

Method definitions take precedence over template files, so you can mix approaches. Plain text via a method, HTML via a template. Or both via templates. Whatever fits your mental model.

Layouts wrap your email content the same way Rails layouts wrap views. Define one inline, in a method or in a separate class. And if you only write HTML, Courrier can auto generate the plain text version. 🤖

But wait, there is more

The Result object tells you if delivery succeeded, with access to the raw response data and any errors. Test helpers give you assert_emails_delivered and friends, so you can verify delivery without hitting a real API. before_deliver and after_deliver callbacks let you hook into the lifecycle. Custom HTTP headers (like List-Unsubscribe) go straight into each email class.

There’s also a a newsletter subscription system: Courrier::Subscriber.create and .destroy work with Beehiiv, Buttondown, Kit, Loops, Mailchimp, MailerLite and Brevo.

Rails Courrier

Courrier works with any Ruby app. But if you’re using Rails, there’s a companion gem that adds Rails-specific features.

Generators scaffold everything for you. Run rails generate courrier:install to create the initializer. Pass --provider to pre-fill provider-specific config. Run rails generate courrier:email Order to create an email class.

ActiveJob support means you can send emails in the background with a single method change. Call deliver_later instead of deliver.

Inbox gives you browser-based email previews, like (good ol’) Letter Opener but built into the gem. Mount the engine in your routes and every sent email opens in your browser.

I18n is scoped under courrier.email.<class_name>, so your translations stay organised. The t helper works in email classes and ERB templates.

Instrumentation publishes delivery.courrier and delivery_failed.courrier events through ActiveSupport::Notifications.

I have a few ideas for what is next. Auto redundancy: if your primary provider goes down, Courrier falls back to a backup provider. Baked-in layouts to make your emails a bit fancier (without asking a LLM). Dedicated real email testing tools that go beyond the test helpers. And more delivery methods beyond email (SMS, push notifications). 🤯

A huge thank you to delynn, benedikt, faheemKamboh and JSap0914 for their contributions. ❤️

Give Courrier a try. Star the repo on GitHub. For Rails apps, use rails_courrier. Would love to see what you build with it. 🚀🤘

Recreating Stimulus: how data-controller works under the hood

Rails Designer — Mon, 27 Jul 2026 07:30:00 +0000

This is part 1 of a two-part series. Part 2, coming soon, will cover targets, actions and reactive values.

Yep, that text is programmatically added using a recreated Stimulus framework and a hello_world_controller.js

Stimulus is a modest JavaScript framework to sprinkle bits of interactivity. At its core it watches the DOM for elements with a data-controller attribute and connects them to JavaScript classes. When an element appears, a controller instance is created. When it disappears, the instance is cleaned up. That’s it. That’s the entire foundation.

I want to walk through how you can recreate Stimulus yourself to learn a few modern JavaScript features to have in your magic hat, you can tell your LLM agent to use instead.

To recreate it you need a few things: a registry to store controllers, a watcher for DOM changes and a base class for controllers to extend. Each of these maps to a modern JavaScript feature.

Here is the code. See the full commit on GitHub.

The registry

The Engine class holds a private map of registered controllers:

class Engine {
  #controllers = new Map()
  #connections = new WeakMap()
  #observer = null

  register(name, controllerClass) {
    this.#controllers.set(name, controllerClass)
  }
}

#controllers is a Map, not a plain object. Why? Maps have a get, set and has API. They accept any key type, not just strings. They are iterable with for...of. And they have a clear .size property. For a registry, Maps are more “honest” than objects.

The private # prefix is real ES2022 encapsulation (if you been around these parts of the internet, you have seen them many times before 🤓). No private access modifier like in Ruby. If you try to access engine.#controllers from outside the class, JavaScript throws an error (even when you inherit from the class with the private method; unlike with Ruby!).

Watching the DOM

Controllers need to connect when elements appear and disconnect when they disappear. The tool for that is MutationObserver:

start() {
  this.#observer = new MutationObserver(mutations => {
    for (const { addedNodes, removedNodes } of mutations) {
      for (const node of addedNodes) {
        if (node.nodeType === Node.ELEMENT_NODE) this.#wireUp(node)
      }
      for (const node of removedNodes) {
        if (node.nodeType === Node.ELEMENT_NODE) this.#wireDown(node)
      }
    }
  })

  this.#observer.observe(document.body, { childList: true, subtree: true })
  this.#wireUp(document.body)
}

MutationObserver fires a callback when the DOM changes. You pass it { childList: true, subtree: true } to observe all additions and removals anywhere in the body. When nodes come in, it scans for [data-controller] elements and connect them. When nodes leave, they are cleaned up.

The Node.ELEMENT_NODE check is a small detail that matters. MutationObserver also reports text nodes and comments. Those you do not want, so these are filtered.

The initial this.#wireUp(document.body) handles existing elements on page load. MutationObserver only fires on future changes.

Tracking instances

When a controller is created, it needs to remember which element it belongs to. Later, when that element leaves the DOM, the instance is found and disconnect() is called.

A WeakMap is the right tool:

#wire(element) {
  if (this.#connections.has(element)) return

  const name = element.getAttribute("data-controller")
  const ControllerClass = this.#controllers.get(name)

  if (!ControllerClass) return

  const controller = new ControllerClass(element)
  this.#connections.set(element, controller)

  controller.connect()
}

#unwire(element) {
  const controller = this.#connections.get(element)
  if (!controller) return

  controller.disconnect()

  this.#connections.delete(element)
}

WeakMap uses the DOM element as its key. When the element is garbage collected, the entry disappears automatically. No manual cleanup needed. No risk of memory leaks.

A regular Map would hold a strong reference to the element and prevent garbage collection (GC; the automatic process of freeing up memory from unused objects). WeakMap does not hold such strong references, allowing objects to be garbage collected even if they’re stored in it. It is one of those JavaScript features you do not need often, but when you do, it is the only tool for the job. 🤘

The controller

The base class is intentionally minimal:

class Controller {
  #element

  constructor(element) {
    this.#element = element

    this.initialize()
  }

  get element() {
    return this.#element
  }

  initialize() {}
  connect() {}
  disconnect() {}
}

The #element private field stores the DOM element. A getter exposes it read-only. Subclasses can access this.element but cannot reassign it.

The real Stimulus calls initialize() once and connect() when the element enters the DOM. This recreation does the same. Subclasses override these methods to add behavior.

All code from this article is in the recreate-stimulus repo.

In a next article: targets, actions and reactive values. Stay tuned. 🤙

Add newsletter subscriptions to Rails 8 signups

Rails Designer — Fri, 17 Jul 2026 09:30:00 +0000

Users are creating accounts on your new Saas. Yay (and not just family and friends or bots). Yay! Now comes the next step from every marketing handbook: capturing newsletter subscriptions.

This article builds on Add Sign Up to Rails 8’ Authentication.

Add a simple checkbox to let users opt in to product updates during signup. Store their preference using Rails Vault and manage the subscription with Rails Courrier.

First, add Rails Vault and Rails Courrier to your Gemfile:

gem "rails_vault"
gem "rails_courrier"

Rails Vault adds simple and easy settings, preferences and so on to any ActiveRecord model (I recently pushed 1.0.0). Courrier is API-powered email delivery for Ruby apps with support for Mailgun, Postmark, Resend and more. Rails Courrier is the Rails “wrapper” for Courrier. These two gems work really nicely together for this feature.

Run bundle install and generate the Rails Vault migration:

rails generate rails_vault:install
rails db:migrate

It creates a new file app/models/user/subscriptions.rb:

class User::Subscriptions < Vault
  vault_attribute :product_emails_subscribed_at, :datetime

  # Add more subscription types as needed:
  # vault_attribute :marketing_emails_subscribed_at, :datetime
  # vault_attribute :weekly_digest_subscribed_at, :datetime
end

And updates your User model to use this vault:

# app/models/user.rb
class User < ApplicationRecord
+ vault :subscriptions

  has_secure_password
  has_many :sessions, dependent: :destroy
end

This keeps subscription data organized without cluttering your User table. More subscription types can be added later without database migrations.

Now the plumbing is done, add a checkbox to your signup form in app/views/signups/new.html.erb:

<%= form.check_box :product_emails %>
<%= form.label :product_emails, "Subscribe to product updates" %>

Update the Signup model to accept this parameter:

# app/models/signup.rb
class Signup
  include ActiveModel::Model
  include ActiveModel::Attributes

  attribute :email_address, :string
  attribute :password, :string
  attribute :terms, :boolean, default: false
+ attribute :product_emails, :boolean, default: false

  # …existing validations

  def save
    if valid?
      User.create!(email_address: email_address, password: password).tap do |user|
        create_workspace_for user
+       subscribe_to_product_emails user

        send_welcome_email_to user
      end
    end
  end

  private

+ def subscribe_to_product_emails(user)
+   return if !product_emails
+
+   user.create_subscriptions(product_emails_subscribed_at: Time.current)
+
+   Courrier::Subscriber.create email_address
+ end
end


  def signup_params
    # NOTE: new syntax, see PR: https://github.com/rails/rails/pull/51674
- params.expect(signup: [:email_address, :password, :terms])
+ params.expect(signup: [:email_address, :password, :terms, :product_emails])
  end

Create config/initializers/courrier.rb:

Courrier.configure do |config|
  # …

  config.subscriber = {
    provider: "buttondown",
    api_key: Rails.application.credentials.dig(:buttondown, :api_key)
  }
end

Replace "buttondown" with your preferred newsletter provider. Courrier has support for many providers.

Time to test it! Create a new user through the signup form with the product emails checkbox enabled. The subscription gets stored in the Rails Vault and the subscriber gets created in your newsletter service.

All code from this article is available in the Rails 8 Authentication repository.

Questions about subscriptions or newsletter management? Let me know below in the comments.

Permission UI the Rails way

Rails Designer — Fri, 10 Jul 2026 14:30:00 +0000

I’ve built many a SaaS. And most have pricing tiers: the higher the plans the more widgets you can create or features are allowed. Typically there are two ways to approach this:

hide the feature if the customer does not have access;
show all features, to all customers, but guard them with some, optional, upsell.

I have succesfully implementated the latter approach with a helper that quacks like Rails itself.

The helper lets you wrap content and decide what happens when access is denied. Hide it, redirect to a link, render content or render a partial. It’s small but flexible. This is how it looks (added a toggle allowed/denied states):

As always view on GitHub for a ready-to-copy code.

The API is elegant. Let’s look at some examples:

<%= allowed? Current.user.premium? do %>
  <%= link_to "Create project", projects_path %>
<% end %>

When Current.user.premium? is true, the link renders. When false, nothing shows. That’s the default behavior.

But you can do more. Redirect to a link instead:

<%= allowed? Current.user.premium?, redirect_to: upgrade_path do %>
  <%= link_to "Advanced analytics", analytics_path %>
<% end %>

The content becomes a clickable link pointing to your upgrade page.

Show plain text as a fallback:

<%= allowed? Current.user.premium?, render: { plain: "Upgrade to unlock this." } do %>
  <%= button_to "Delete project", project_path, method: :delete %>
<% end %>

Or render HTML:

<%= allowed? Current.user.premium?, render: { html: "Upgrade to the <strong>Pro plan</strong>." } do %>
  <%= button_to "Delete project", project_path, method: :delete %>
<% end %>

And render a partial for complex fallbacks:

<%= allowed? Current.user.premium?, render: "upsell" do %>
  <%= button_to "Advanced settings", settings_path %>
<% end %>

The helper

Here’s the full helper in app/helpers/allowed_helper.rb:

module AllowedHelper
  def allowed?(condition, options = {})
    return yield if condition

    if options[:redirect_to]
      content = capture { yield }

      link_to strip_tags(content), options[:redirect_to]
    elsif options.key?(:render)
      render_options = options[:render]

      if render_options.is_a?(Hash) && render_options.key?(:html)
        render_options[:html].html_safe
      elsif render_options.is_a?(Hash) && render_options.key?(:plain)
        render_options[:plain]
      else
        render({ partial: render_options.to_s }) if render_options.is_a?(String) || render_options.is_a?(Symbol)
      end
    end
  end
end

The logic is straightforward. If the condition is true, render the block. If false, check your options and handle it accordingly.

When you pass redirect_to, it captures the block content, strips HTML tags and wraps it in a link. When you pass render, it supports three formats: plain text, raw HTML or a partial name as a string or symbol.

This helper did, ~10 years ago, not start like this. Over the years, after working on many dozens Rails-based SaaS apps, my aim became to make helpers “quack” more like Rails methods. You’re familiar with render plain:, render html: and partial rendering. This helper just extends that familiar syntax to conditional rendering.

I like it. What do you think of this?

Build a changelog widget (with Perron)

Rails Designer — Mon, 06 Jul 2026 20:30:00 +0000

Changelog widgets, like those from Headway and Beamer, are still a popular way to tell your users about updates to your product. What if you could build one yourself?

Perron, the Rails-based SSG, has a library of production-ready custom elements. One of them, the Embed Content component is perfect for this exact use case. It fetches JSON data, renders it as a list, tracks read state and handles all the UI interactions. You just provide the data.

The result will look like this:

Pretty smooth, right?

Most changelog services lock you into their platform. You pay per seat, deal with their branding and accept their feature set. If you want something simpler or more tailored to your product, you’re stuck building it from scratch.

But here’s the thing: a changelog widget isn’t complicated. It needs to fetch some data, display it nicely, track which items users have read and maybe show a badge with unread counts. That’s it. The Embed Content component is a custom element that fetches JSON from any endpoint, renders items with a template you control, tracks unread state based on a last-read-at timestamp, shows an unread badge automatically and handles open/close toggle states.

You drop it into your HTML, point it at your changelog endpoint and it works. You write the changelog entries in your Perron site (where they are also published. Win-win! 🏆).

Getting Started

First, add the Embed Content component to your project. The setup instructions are straightforward: run the template in your app and the custom element is ready to use.

Next, you’ll need a JSON feed. Perron makes this easy: check out the Perron docs to see how to create a custom template that outputs your changelog items as JSON.

Once your feed is live, drop the Embed Content component into your view:

<embed-content id="changelog-widget" src="https://example.com/changelog.json" limit="5" last-read-at="2026-03-20T00:00:00Z">
  <button aria-label="Toggle changelog">
    <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
      <path d="M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9"/>
      <path d="M10.3 21a1.94 1.94 0 0 0 3.4 0"/>
    </svg>

    <span badge></span>
  </button>

  <div panel>
    <div header>
      <h2>What's new</h2>
    </div>

    <ul items></ul>
  </div>
</embed-content>

The component reads the src attribute, fetches your JSON and renders each item. The limit attribute controls how many items show. The last-read-at attribute tracks which items are new: anything published after that timestamp gets marked as unread and counted in the badge.

Your feed doesn’t have to come from Perron. The component just needs JSON with title, body, url and published_at fields. You could use a custom Rails endpoint, a headless CMS or any JSON API. The pattern is the same.

The component uses semantic HTML and CSS custom properties, so styling is straightforward. You control the colors, spacing and layout. This pattern works for any feed-like feature: product announcements, status updates, notification centers or feature releases. The Embed Content component handles the hard parts. You focus on your content. ✨

Check out the example repository for the complete example including CSS.

Beam Up: CLI to deploy static sites

Rails Designer — Tue, 30 Jun 2026 07:30:00 +0000

Beam Up is a command-line tool I wanted for some time. Its goal is to make deployments of static sites across various providers simpler from your machine: run one command: beam_up ./output/. ❤️

If you feel generous, head over to the GitHub repo and give it a star! 🌟

Installation and configuration

To install Beam Up, run:

gem install beam_up

Then initialize a configuration file for your chosen provider with:

beam_up init # to start an interactive process, or:
# beam_up init hetzner

This creates a .beam_up.yml file:

provider: netlify
netlify:
  api_token: your_token_here
  project_id: your_project_id

Ready to beam ⚡

Now you can deploy your static site using the super fun beam_up command:

beam_up ./output

Beam Up supports multiple providers including AWS S3, Seal Static, Hetzner, Netlify and Statichost. Oh, and it even works with SFTP (remember those days?!).

Usage from Ruby

Beam Up can also be used within Ruby scripts:

require "beam_up"

BeamUp.deploy! "./output"

Integration with Perron

While Beam Up is designed to work with any SSG (Jekyll, Middleman or Bridgetown), I built it for Perron. With the latest version, you can now simply run bin/rails perron:deploy, it will build your site (bin/rails perron:build) and deploy it: your site will be live in no time. Without any config, it will default to deploy to Seal Static (where an account is created for you on first deploy). Cool, right? 😎

Beam Up is a small, new OSS project made with ❤️ from Rails Designer HQ. If you like it, do star it on GitHub and give it a try on your (next) SSG project.

Build a reusable before/after image slider with Stimulus

Rails Designer — Mon, 29 Jun 2026 07:30:00 +0000

Before and after (image) sliders are great for product showcases, before/after transformations, renovation projects or photo editing results. They’re engaging, interactive, and honestly just fun to use.

Ever thought of building one from scratch? Not complicated at all! In this article, I want to show how to build a simple, reusable Stimulus controller that does just all that. This is how the end result will look like:

As always, the code can be found on GitHub.

It is simple, really

The beauty of this controller is its simplicity. You need three things:

a wrapper element;
two images (before and after), and;
a slider.

That’s it. Here’s it in HTML:

<div data-controller="compare">
  <img data-compare-target="before" src="before.jpg">
  <img data-compare-target="after" src="after.jpg">

  <div data-compare-target="slider"></div>
</div>

The two images are positioned absolutely and the slider sits on top as a draggable handle. The “after” image gets clipped dynamically as you drag.

Here’s that interesting part. It uses clip-path to reveal or hide the after image:

set #position(value) {
  this.positionValue = value
  this.sliderTarget.style.left = `${value * 100}%`
  this.afterTarget.style.clipPath = `inset(0 0 0 ${value * 100}%)`
}

When you drag the slider, it calculates the position relative to the container’s width, then updates both the slider’s left position and the clip-path of the after image. Most of that is done with:

#pointerDown = (event) => {
  if (event.target !== this.sliderTarget) return

  event.preventDefault()

  document.addEventListener("pointermove", this.#pointerMove)
  document.addEventListener("pointerup", this.#pointerUp)
}

Stimulus controllers are meant to be reusable

This controller is a wrapper element plus two images. That’s it. Use cases then are limitless (they generally work great on marketing blogs as well!):

product photography ; show different angles or colors of the same product
photo editing results ; before/after with filters, adjustments, or retouching
UI redesigns ; old interface vs. new interface

You could (should) extend this in several directions. Add keyboard support for accessibility. Include labels (“Before” / “After”) that move with the slider. Add touch support with haptic feedback on mobile.

It is the kind of controller you copy and paste into your projects. Just as it should be.

Building a quiz with Stimulus

Rails Designer — Sat, 13 Jun 2026 07:30:00 +0000

Quizzes are a fun! Well… I do think they are. Always up to learn new things. So how can you create one in with your favorite frameworks? In this article, I want to show how you can build a quiz witg Stimulus. It can be a good starting point for learn about a new customer in your SaaS or as a smart, little marketing tool (keep readers engaged/on your page). 💡

The quiz loads questions from a Rails endpoint, tracks answers in real-time, calculates results and submits them to your server. As always, the code can be found on GitHub.

This will be the result. Time to dust off that good ol’ computer science knowledge… 🤓

Building the data class

Here’s the QuizData class that handles the quiz logic. For this example it lives inside the Stimulus controller, but you can organise it however you want.

class QuizData {
  constructor(questions) {
    this.questions = questions
    this.answers = {}
  }

  answer(questionIndex, selectedOption) {
    this.answers[questionIndex] = selectedOption
  }

  getAnswer(questionIndex) {
    return this.answers[questionIndex]
  }

  correctCount() {
    return this.questions.filter((question, questionIndex) => {
      const answer = this.answers[questionIndex]
      return answer !== undefined && answer === question.correct
    }).length
  }

  result() {
    return this.questions.reduce((accumulate, question, questionIndex) => {
      const answer = this.answers[questionIndex]

      return accumulate + ((answer === question.correct) ? Math.pow(2, this.questions.length - 1 - questionIndex) : 0)
    }, 0)
  }

  get totalQuestions() {
    return this.questions.length
  }

  get isComplete() {
    return Object.keys(this.answers).length === this.totalQuestions
  }

  static default() {
    return new QuizData([
      {
        question: "What is \"Hi\" in binary?",
        options: ["01001000 01101001", "01000111 01101001", "01001000 01110011", "01000001 01101001"],
        correct: 0
      },

      // more questions…
    ])
  }
}

This class provides methods to record answers, checks if all questions are answered and calculate the score and encode results. The result() method is a little bit clever, it encodes which questions were answered correctly as a binary number, making it easy to store and analyze results server-side.

The static default() method provides quiz data if you do not have a remote endpoint so you can use it also outside of a Rails app (in a static site, for example).

The Rails endpoint

Your quiz questions need to come from somewhere. Create a QuizzesController with an index action that returns questions as JSON:

class QuizzesController < ApplicationController
  def index
    render json: {
      questions: [
        {
          question: "What is \"Hi\" in binary?",
          options: ["01001000 01101001", "01000111 01101001", ...],
          correct: 0
        },

        # etc…
      ]
    }
  end

  def create
    Rails.logger.info "Quiz submission: #{params.permit!.to_h}"

    head :ok
  end
end

The index action returns an array of questions with their options and the index of the correct answer. The create action receives the submitted answers, you can process them here however you want (send along, store in DB, etc.).

The Stimulus controller

Now the Stimulus where it all happens 🛏️✨. This controller fetches questions from your endpoint, renders them and handles user interactions. It uses the @rails/request.js library to make clean HTTP requests.

When the controller connects, it fetches the questions:

async connect() {
  this.quiz = await this.#getQuestions()

  this.#render()
}

async #getQuestions() {
  if (this.hasQuestionsEndpointValue) {
    try {
      const response = await get(this.questionsEndpointValue, { responseKind: "json" })

      if (response?.questions?.length > 0) return new QuizData(response.questions)
    } catch (error) {
      console.warn("Failed to load questions from endpoint, using defaults:", error)
    }
  }

  return QuizData.default()
}

This check this.hasQuestionsEndpointValue is added so I can use this controller also outside of a Rails app.

When a user selects an answer, the controller records it and enables the submit button (when all questions are answered):

selectAnswer(event) {
  const optionsContainer = event.target.closest("[data-quiz-question-index]")
  const questionIndex = parseInt(optionsContainer.dataset.quizQuestionIndex, 10)
  const selectedOption = parseInt(event.target.value, 10)

  this.quiz.answer(questionIndex, selectedOption)
  this.submitTarget.disabled = !this.quiz.isComplete
}

When the user submits the quiz, the controller sends the answers and result to your Rails endpoint. For details on how @rails/request.js works and how to make GET and POST requests from a Stimulus controller, check out this article 😊. What is happening is that you’re sending structured data (answers and a calculated result) to your server:

async submit() {
  const payload = {
    answers: this.quiz.answers,
    result: this.quiz.result()
  }

  if (this.hasAnswersEndpointValue) {
    await post(this.answersEndpointValue, {
      body: JSON.stringify(payload)
    })
  }

  this.#showResults()
}

After submission, the controller displays the results and hides the quiz:

#showResults() {
  const correct = this.quiz.correctCount()
  const total = this.quiz.totalQuestions

  const fieldsets = this.element.querySelectorAll("fieldset")
  fieldsets.forEach(fieldset => fieldset.remove())

  this.resultsTarget.innerHTML = `<div>${correct} out of ${total} correct</div>`
  this.submitTarget.hidden = true
}

The HTML view is minimal:

<article data-controller="quiz" data-quiz-questions-endpoint-value="<%= quizzes_path %>" data-quiz-answers-endpoint-value="<%= quizzes_path %>">
  <output data-quiz-target="results"></output>

  <button type="button" data-quiz-target="submit" data-action="quiz#submit" disabled>Submit Quiz</button>
</article>

The controller renders each question as a fieldset with radio buttons. The styling uses modern CSS (oklch color space; see this article, CSS Grid) to create a clean, accessible interface. The CSS isn’t included here, but it handles the layout, hover states and checked states for the radio buttons.

This quiz is a good starting point. You could add pagination to show only a few questions at a time, add a countdown timer that auto-submits when time runs out, send detailed results to an analytics service to track which questions trip up your users, allow retakes so users can compare scores over time or fetch different question sets based on difficulty level.

Meet Mata: live reload for Rack Apps

Rails Designer — Thu, 04 Jun 2026 19:30:00 +0000

I build quite a few sites. For my own products or I help others. Since I released Perron that is my go-to static site generator now. But it was missing one feature for a speedy development cycle: live reload. Not just a page refresh, but more like hot reloading.

Most live reload solutions either require ActionCable (overkill when using Perron) or just do full-page reloads (annoying/too minimal). I wanted something in between.

Meet Mata : a lightweight live reload solution for Rack apps. It uses Server-Sent Events (SSE) and idiomorph.

You can install Mata simply by running bundle add mata --group=development. Then configure the middleware with watch and skip paths. That’s it. No JavaScript bundling. No ActionCable. No WebSockets. Just smart live reloading! ✨

But Mata isn’t just for Perron. It works with any Rack-based framework, like Rails: Sinatra, Hanami or Roda. 🚀 See the GitHub README for set up examples.

Look, mom, no hands:

So why the name? It’s named after the legendary double agent: Mata Hari. 🕵️💃🤓

(oh, I learned while in Indonesia, in Bahasa Indonesia, mata means eye. A fun coincidence, for something that watches your files. 😅)

Already using Mata (you do if you use Perron!)? Give Mata a star on GitHub. ⭐❤️

Building user-customizable themes with Tailwind CSS

Rails Designer — Thu, 28 May 2026 15:30:00 +0000

A little while ago I was asked to to build a “white-label” feature into an existing app. Their customers can now customize the app to match their brand without touching code.

It will look a little something like this:

This article walks through how I build a custom theme system using Tailwind CSS and the OKLCH color space. The basics for this feature I extracted and is available on GitHub.

The approach I took generates an entire color palette from a single value, instead of managing eleven different color stops manually. Sounds complicated? It really is quite simple. Let me show you.

Tailwind allows defining custom colors using the @theme directive (these can then be used normally, e.g. text-brand-500 and bg-brand-50/60). Rather than hardcoding hex values, use CSS variables that change at runtime.

Here is the setup in app/assets/tailwind/application.css:

@import "tailwindcss";

@theme {
  --color-brand-50: oklch(0.99 0.01 var(--color-value));
  --color-brand-100: oklch(0.98 0.02 var(--color-value));
  --color-brand-200: oklch(0.94 0.04 var(--color-value));
  --color-brand-300: oklch(0.86 0.08 var(--color-value));
  --color-brand-400: oklch(0.74 0.14 var(--color-value));
  --color-brand-500: oklch(0.60 0.18 var(--color-value));
  --color-brand-600: oklch(0.52 0.16 var(--color-value));
  --color-brand-700: oklch(0.44 0.14 var(--color-value));
  --color-brand-800: oklch(0.36 0.12 var(--color-value));
  --color-brand-900: oklch(0.26 0.08 var(--color-value));
  --color-brand-950: oklch(0.16 0.04 var(--color-value));
}

Notice the same --color-value variable? By changing this one variable, all eleven shades update automatically. The lightness and chroma values stay consistent (for a harmonious palette). 🌈

Use these colors in your templates like any other Tailwind color:

<nav class="bg-brand-50 border-brand-100">
  <span class="text-brand-600">Custom Theme</span>
</nav>

OKLCH?

But wait… OKLCH? What is that? OKLCH is a modern color space that separates color into three components: lightness, chroma and hue. This makes it a perfect choice for generating color palettes (Tailwind CSS changed to OKLCH internally as well since v4, iirc).

Take the brand-500 color from the example above:

oklch(0.60 0.18 var(--color-value))

So:

0.60 is the lightness. A value of 0 is black, 1 is white. This color is medium brightness.
0.18 is the chroma (or color saturation). Higher values are more vibrant.
var(--color-value) is the hue angle in degrees (0-360). This is what changes when you update the theme and defined initially in the style-element.

The beauty of OKLCH is that lightness and chroma remain constant across the palette. Only the hue changes. This means your brand color can shift from red to blue to green while maintaining the same visual weight and saturation at each shade level.

Setting up the HTML

In your layout, add a style tag with the default theme value:

<head>
  <style data-theme>
    :root { --color-value: 60; }
  </style>
  <%= stylesheet_link_tag "tailwind", "data-turbo-track": "reload" %>
  <%= javascript_importmap_tags %>
</head>

The default value of 60 is a sorta yellow-green hue. You can change it however you want.

Wiring up the theme controller

I just added this Stimulus controller for this demo (the client’s app worked a bit different).

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["value"]

  initialize() {
    this.style = document.querySelector('style[data-theme]')
  }

  update(event) {
    const value = event.target.value

    this.style.textContent = `:root { --color-value: ${value}; }`
    this.valueTarget.textContent = value
  }
}

The controller finds the existing style tag marked with data-theme and updates its content. This triggers a cascade: the CSS variable changes, all the brand colors are recalculated and the entire app recolors instantly. ✨

The demo interface

The example includes a simple slider to demonstrate the feature:

<div class="flex items-center gap-4 px-6 py-4 border-b border-brand-200" data-controller="theme">
  <span class="text-sm text-brand-700">Theme</span>
  <input type="range" min="0" max="360" value="60" data-action="theme#update" class="w-32 accent-brand-600">
  <span data-theme-target="value" class="text-sm text-brand-500">60</span>
</div>

<p class="mt-2 p-6 text-brand-900">Move the slider above to change the theme color.</p>

<ul class="flex gap-4 p-6">
  <li class="size-16 rounded-lg bg-brand-50 border border-brand-200"></li>
  <li class="size-16 rounded-lg bg-brand-100 border border-brand-200"></li>
  <li class="size-16 rounded-lg bg-brand-200 border border-brand-200"></li>
  <!-- … all the way to brand-950 -->
</ul>

User-selected themes

While this approach was built for a white-label app, it works equally well for user-customizable themes.

The technique is flexible. You could extend it to store multiple theme variables: primary color, secondary color, accent color. Each would be a separate CSS variable that users can customize independently.

Pretty cool, right?