They are all baseline ready (e.g. supported by core browsers for at least 30 months), so there is no fallback excuse left. Let’s get into it.

Logical properties: think in axes (x and y)

A few of these units only make sense when you drop the ideas of “width” and “height” and think in axes instead. CSS now measures along the inline axis (the direction your text flows, left to right in, for example, English) and the block axis (the direction blocks stack, top to bottom). Once that makes sense, units like vi, vb and cqi will be less weird. 💡

Full screen height: dvh

100vh includes the space behind the browser’s address bar, so a full height hero can get clipped the moment the bar shows up. The dynamic viewport unit fixes this.

.hero {
  min-height: 100dvh;
}

1dvh is one percent of the dynamic viewport, the size that shrinks and grows as the browser chrome moves. Its stable siblings svh (small, chrome shown) and lvh (large, chrome hidden) are there when you want a value that never moves.

Scroll offsets: vi and vb

vi is one percent of the viewport’s inline axis (again: the direction the text flows), vb the block axis (how blocks are stacked). Because they are axis based, a change in writing-mode (the direction text flows) survives.

A common use case for me, is giving anchored jumps some room to breath:

[id] {
  scroll-margin-top: 10vb;
}

Upon a page click, or when scroll-into-view fires, the heading lands 20vb below the top instead of jammed against the edge. Try doing that cleanly with vh and you are already guessing at orientations.

Container aware type: cqi

Viewport units can’t tell a card in a 300px sidebar from the same card in a 700px main column. They both see the whole window. Container query units measure the nearest container instead, which is what you actually want for reusable components.

.cards {
  container-type: inline-size;
}

.card {
  font-size: clamp(1rem, 4cqi, 1.5rem);
  padding: 3cqi;
}

1cqi is one percent of the container’s inline size. The card now scales to wherever it lives, with zero media queries. The unit reads the nearest ancestor with container-type, never the element itself. And if you need cqb (block axis) you must set container-type: size and give the container a height.

[AD] Spinal CMS: Git-based CMS for static site generators

Line perfect spacing: lh

1lh is exactly one line height of the current font’s size. That sounds small, but it lets you tie any spacing to your actual text rhythm instead of eyeballing em values.

.field {
  line-height: 1.5;
}

textarea {
  height: 3lh;
}

p {
  margin-block: 1lh;
}

The textarea trick is one I use all the time now. No more rows guessing or JavaScript needed. rlh is the root version, the same idea as rem versus em. Both landed Baseline in November 2023.

Text matched icons: cap

Ever tried to size an inline icon next to a label and end up nudging 1em, then 1.2em, then 0.9em? The cap unit ends the guessing. It equals the cap height of the font, the height of its capital letters.

.icon {
  width: 1cap; height: 1cap;
  vertical-align: baseline;
}

Now the icon lines up with the capitals in your text, in any font, at any size. Satisfying!

Reading measure: ch and ic

1ch is the advance width of the 0 glyph in the element’s own font. Because it is relative to that font’s size, 60ch means roughly sixty characters wide whether the text is 14px or 32px. The measure stays constant in character count, which is exactly what comfortable reading wants.

.prose {
  max-width: 60ch;
}

.input {
  width: 20ch;
}

Note that ch is built on the 0 glyph, so it is an approximation of average character width, not a precise count. And for wide or CJK scripts (graphemes), reach for ic instead, which measures a full width ideograph.

Edge fitting squares: vmin and vmax

vmin is one percent of the smaller viewport edge, vmax the larger. That makes them perfect for elements that must behave in any orientation without a media query.

.avatar {
  width: min(50vmin, 200px);
  aspect-ratio: 1;
}

The avatar is half the smaller screen edge, capped at 200px, and never overflows when you rotate the phone. Same trick works for full bleed overlays with vmax.

It is why I extracted the core features (pulling SVGs from remote repository, transforming filenames, etc.) of Rails Icons into a Ruby gem, called Icons, so other frameworks can have all the icons in their apps as well.

Hanami Icons is the next wrapper of the Icons gem for… drumroll… Hanami! It gives you the same interface as Rails Icons too, whether that is Heroicons, Lucide, Tabler or even a folder of your own SVGs.

<%== icon "check", class: "text-gray-500" %>

<%== icon "apple", library: "simple_icons", class: "text-black" %>

if you have seen Rails icons, you know Hanami Icons.

One interface, all the libraries

The work is done in Icons. If you do not know it: it syncs SVGs from their source repositories, normalizes names, handles variants and builds sprite markup. Hanami Icons just adds the Hanami-specific parts: a provider, view helpers and CLI generators.

Hanami Icons supports twelve first-party libraries: from good-old Feather to Heroicons to Lucide and Phosphor. That ranges from 49 icons in SidekickIcons to more than 9,000 in Phosphor. You can also add your own library (more on that below).

Install and generate

Hanami loads CLI extensions from the :cli Bundler group, while the view helpers need the gem at runtime. Add it to both:

gem "hanami_icons", group: [:default, :cli]

Then run:

bundle install
hanami generate icons --library=lucide

The generator writes config/providers/icons.rb, registers the icons provider, adds the helpers to app/views/helpers.rb and syncs the library. You can pick several libraries or only the variants you need:

hanami generate icons --libraries=heroicons lucide
hanami generate icons --library=heroicons --variants solid outline

The Hanami configuration can be used to set a default library and variant there:

HanamiIcons.configure do |config|
  config.default_library = "heroicons"
  config.default_variant = "outline"
end

Icons and sprites

The main helper takes the icon name and any attributes you want on the SVG:

icon "check"
icon "check", variant: "solid"
icon "check", library: "heroicons"
icon "check", class: "icon icon-small"
icon "check", aria: { label: "Save" }
icon "check", stroke_width: 2

[AD] Spinal CMS: Git-based CMS for static site generators

A page with many icons repeats the same paths over and over. Sprites fix that. Generate one:

hanami generate icons:sprite

Then reference symbols instead of inlining every path:

<%== sprite_icon "check" %>
<%== sprite_icon "search", class: "icon icon-small fill-blue-500" %>

Point config.default_sprite_location at the generated file or at a CDN. Set it to nil to inline the sprite in your layout with icons_sprite. Check the README for more details on sprites. They give you the best of customisability and rendering optimisation.

Custom libraries and syncing

Any directory under app/assets/svg/icons is a “library”. Add a SVG and use it:

app/assets/svg/icons/simple_icons/apple.svg

icon "apple", library: "simple_icons"

Libraries with variants use a variant directory, like heroicons/outline/check.svg. If you want a starting point, hanami generate icons --library=simple_icons creates the folder and adds config.custom_library :simple_icons to the provider.

You can also sync a library from a git repository:

HanamiIcons.configure do |config|
  config.custom_library :my_icons, source: {
    url: "https://github.com/user/icons.git",
    variants: { default: "." }
  }
end

The icons:sync command runs before the app boots, so it does not load providers. It only sees the first-party libraries. Sync a custom library inside the app context instead:

bundle exec hanami run 'Icons::Sync.new(:my_icons).now'

For first-party libraries, syncing is a single command:

hanami generate icons:sync
hanami generate icons:sync --library=heroicons
hanami generate icons:sync --libraries=heroicons lucide

Run it whenever an upstream library adds icons you want. No bundle update hanami_icons needed.

Hanami Icons is at 0.6.0. It is still early. The generators and helpers have tests, but I want to hear from people using it in real apps before calling it 1.0. If something feels awkward, open an issue or send a pull request.

If Hanami Icons saves you an afternoon, a star helps other Hanami developers find it. ⭐

Look at those text effects: wow would you build them?

My first answer, somewhere in the 2000s, would have been Flash. A timeline, some easing curves, spooky rippling text for every band MySpace page. 🤘 After Flash came many other options: jQuery plugins, canvas pixel picking, shaders in a giant WebGL library for one ripple of text.

Luckily today all you need fits in two SVG primitives and one line of CSS.

For a while now, you can apply SVG filters to regular HTML:

filter: url(#my-filter)

The browser then renders your element through that filter. And SVG filters can do wild things. The wildest of all: feDisplacementMap.

How feDisplacementMap works

Here’s how feDisplacementMap works. It takes two images. The first one is your content (SourceGraphic, in filter-speak). The second one is a map. For every pixel of your content, the filter reads the color at that position in the map, converts one of its channels to a number between 0 and 1, and shifts the pixel sideways by:

scale * (channelValue - 0.5)

So a red channel value of 0.5 (neutral gray) means “don’t move this pixel”. A value of 1.0 pushes it scale pixels to the right (if you used Photoshop’s distort effect this might be familiar). A value of 0 pulls it back the other way.

This means the real work goes into the map, and you can build that map from anything. The workhorse for organic distortion is feTurbulence: it generates Perlin-style noise, a soft cloud of grays and colors, and that becomes your map. Chain the two primitives and you get distortion for free.

Your first distortion

Enough theory. This is the full setup (and below, real examples!):

<svg width="0" height="0" style="position: absolute">
  <defs>
    <filter id="fd-wavy">
      <feTurbulence type="turbulence" baseFrequency="0.02" numOctaves="2" result="map"/>

      <feDisplacementMap in="SourceGraphic" in2="map" scale="20"/>
    </filter>
  </defs>
</svg>

Look at that! No JavaScript, no canvas, but real text you can select. 🤯 The result="map" names the turbulence output, and in2="map" pipes it into the displacement (you’ll also see xChannelSelector and yChannelSelector on feDisplacementMap; more on those in a second).

Turn the dials

[AD] Spinal CMS: Git-based CMS for static site generators

Two attributes control almost everything: baseFrequency on the turbulence and scale on the displacement.

baseFrequency picks the size of the noise blobs. Low values give you big, slow waves. High values give you fine, nervous grain:

scale picks how far pixels travel. Keep it small for a subtle wobble, crank it up and your text melts:

A few more dials worth knowing:

• numOctaves layers noise on top of noise. More octaves, more detail.
• seed produces a different noise pattern. Great when you want variants that look related (but differ).
• xChannelSelector / yChannelSelector set which color channel drives horizontal and vertical shifts. The defaults are R and G. Point yChannelSelector at A and the vertical shift follows the noise’s alpha channel instead. This is how you design maps where X and Y move independently.

Move it

A static distortion is nice, but you can use SVG’s own <animate> to, for example, wobble the turbulence’s baseFrequency over time:

<feTurbulence type="turbulence" baseFrequency="0.02" numOctaves="2" result="map">
  <animate attributeName="baseFrequency"
           dur="6s" repeatCount="indefinite"
           values="0.02;0.04;0.02"/>
</feTurbulence>

Animating scale instead gives you a pulse. Animate both baseFrequency and scale and you get heat shimmer off a summer road.

Any image can be a map

My favorite part? The map is just an image. So swap feTurbulence for feImage and feed in any picture. A smooth radial gradient, for example, gives you a lens. One catch: feImage inside filters applied to plain HTML behaves unreliably across browsers, so I render the word inside an inline <svg> instead. Works everywhere:

<svg width="240" height="100">
  <defs>
    <filter id="fd-lens" filterUnits="userSpaceOnUse" x="0" y="0" width="240" height="100">
      <feImage href="data:image/svg+xml,…" x="0" y="0" width="240" height="100" result="m"/>
      <feDisplacementMap in="SourceGraphic" in2="m" scale="40"/>
    </filter>
  </defs>
  <text x="120" y="64" text-anchor="middle" filter="url(#fd-lens)">lens</text>
</svg>

(Grayscale in the middle, white at the edges: pixels near the center stay put, pixels near the edge get pushed outward.)

And once you accept “the map is an image”, you are only limited to your imagination. Feed in a photo, a QR-looking pattern (instant glitch) or a feColorMatrix on top of turbulence. The displacement filter does exactly what the map tells it to. Design the map, design the distortion.

Try it yourself

I’ve wrapped these ideas in a tiny custom element, <displacement-svg>, with seven presets (wavy, glitch, water, heat, lens, liquid, sketch) and attributes to override every dial. As always, the code can be found on GitHub.

Combine feDisplacementMap with feBlend for water-on-glass (to get that iOS’ liquid glass effect 💡). The MDN docs for feDisplacementMap are another great resource.

I will use them whenever I need a small, reusable UI behavior. The latest one I used (in my main product) is a tooltip and it’s a good example of why this approach is so clean. 🧼

The usage will show you my point:

<tool-tip label="Search">
  <%= icon "magnifying-glass", aria: {label: "View search"} %>
</tool-tip>

You just wrap any element with tool-tip. That’s it. The label becomes the tooltip text. No Stimulus controller to wire up, no data attributes to memorize or no data-controller noise. Just a tag around the thing you already had.

An important detail (and it actually deserves a separate post!): the element adds display: contents to itself. Why does that matter? Because display: contents removes the custom element from the box tree while keeping its child elements in the normal DOM flow. The extra wrapper will not break your layout, your flexbox or your grid. The <svg> behaves exactly as if the tool-tip weren’t there.

[AD] Spinal CMS: Git-based CMS for static site generators

Under the hood, the element leans on the Popover API for the tooltip box. It creates a div, sets popover="hint" and positions it with getBoundingClientRect. The positioning logic is small: it finds the trigger’s rect, centers vertically, places the tooltip to the right and flips left if there’s no room:

let left = triggerRect.right + VIEWPORT_MARGIN
if (left + tooltipRect.width > window.innerWidth - VIEWPORT_MARGIN) {
  left = triggerRect.left - VIEWPORT_MARGIN - tooltipRect.width
}

It also degrades gracefully. If the browser doesn’t support popover, it falls back to the native title attribute.

Now, CSS Anchor Positioning would massively simplify this element. The complete #position method, the scroll listeners, the resize recalculation: it could all collapse into a few lines of CSS if the browser support were there. I skipped it on purpose. Anchor positioning is still too thin on support to rely on (~64% of the level 2 API as of this writing), so the JS stays as-is. When coverage improves, that positioning block is the first thing I’ll delete.

As always, the code can be found on GitHub. It’s a tiny file, and reading it end to end takes less time than this paragraph (okay, maybe not this one, but certainly the previous one…).

Next time you reach for a tooltip gem or package, you could use this custom element instead. Wrap, label, done. 🏁 And keep an eye on anchor positioning, because the day it becomes “baseline wide available” I am going to replace a lot of code. 🧹

The whole thing is paused-gif. Drop it in your markup and it renders a still frame with a button to play the animation:

<paused-gif src="/celebration.gif" alt="A confetti cannon going off at a launch party"></paused-gif>

That’s it. Let me walk through why each accessibility decision in there matters, because that’s the interesting bit.

Pause by default

The “poster frame” (the initial image) is captured the moment the element mounts, so nothing animates until someone clicks “play”. This is the most important a11y win.

Why does it matter? Animated content triggers vertigo and balance disorders for a real chunk of people. WCAG 2.3.3 says anything that moves for more than five seconds needs a pause control. By showing a still image first, I’m compliant before the user even clicks. I also grab the first frame onto a canvas so there’s no flash of a half-loaded GIF:

canvas.getContext("2d").drawImage(frame, 0, 0);

this.#posterUrl = canvas.toDataURL("image/png");

If the canvas read fails (cross-origin issue, mostly), I fall back to the source URL. The poster still shows, the animation stays paused.

A real button, not a div with a click handler (yes, I have seen this)

The toggle is a <button type="button">. This matters more than it looks:

this.#button = document.createElement("button");
this.#button.type = "button";

this.#button.addEventListener("click", () => this.toggle());

[AD] Spinal CMS: Git-based CMS for static site generators

Setting type="button" stops it from accidentally submitting a form it happens to live inside. Because it’s a native button, keyboard users get Tab, Enter and Space for free. If you use any other element (e.g. <div>), you’ve just created a problem that already has a solution.

State that screen readers can hear

A play/pause button is a toggle, so it needs aria-pressed. The render method keeps it in sync with the actual state:

this.#button.setAttribute("aria-pressed", String(this.#playing));
this.#button.setAttribute("aria-label", `${this.#playing ? "Pause" : "Play"} animation: ${this.alt}`);

this.#button.textContent = this.#playing ? "Pause" : "Play";

Two things are happening. aria-pressed tells assistive tech this is a toggle and whether it’s on. The dynamic aria-label does something cool: it bakes the image’s alt text right into the control. A screen reader user hears “Play animation: a confetti cannon going off at a launch party” instead of a bare “Play”. The visible text says “Play” or “Pause” for sighted users, while the label carries the context.

And the alt isn’t an afterthought. It flows straight through to the underlying <img>:

this.#img.alt = this.alt;

If you forget the alt attribute, it becomes an empty string, which is the correct signal that the image is decorative (the button label already describes it).

decoding = "async" on the image keeps the poster from blocking the main thread. And because src, poster, alt and button-class are all observed attributes, the element re-renders correctly when any of them change after mount.

I keep coming back to web components/elements: the platform already solved accessibility for buttons, images and toggles. Build the control out of native elements, mirror state into ARIA and pause the motion by default. Everything else is detail.

As always, the code can be found on GitHub. If you ship it somewhere, I’d love to see how you theme the button. ❤️

I put together a small demo repo to show a handful of these in action. Lets go over them and maybe you find a way to refactor and simplify one of your Stimulus controllers.

First a few you probably have used before. A <textarea> fires input on every keystroke. The character-counter controller subtracts the current length from maxLength and updates a live counter.

<textarea data-controller="character-counter" data-action="input->character-counter#update" maxlength="200">

Note the difference. input fires on every change. change fires only on blur. For real-time feedback, input is what you want.

A range slider works the same way. The range-display controller grabs event.target.value and writes it into an <output> element. As the user drags, the displayed number updates instantly.

<input type="range" data-action="input->range-display#update">
<output data-range-display-target="value">42</output>

A checkbox fires change when its checked state toggles. The checkbox-reveal controller inspects event.target.checked and toggles a hidden class on a content section.

<input type="checkbox" data-action="change->checkbox-reveal#toggle">
<div data-checkbox-reveal-target="content" class="hidden">…</div>

A <details> element fires toggle every time it opens or closes. The accordion controller uses this to persist state to localStorage.

<details data-controller="accordion" data-action="toggle->accordion#persist">

The controller reads event.target.open to know whether the element was opened or closed and saves a boolean. On connect, it restores the saved state. Native event, no wrapper library.

A code block fires copy when the user selects text and presses Cmd+C. The clipboard controller shows a “Copied!” tooltip for 1.5 seconds, then hides it.

<pre data-controller="clipboard" data-action="copy->clipboard#showTooltip">
  <code>$ rails g controller pages show</code>

  <span data-clipboard-target="tooltip" class="clipboard-tooltip">Copied!</span>
</pre>

The copy event fires before the clipboard is populated, so there is time to show feedback.

A <dialog> fires two distinct events. close fires when the dialog closes via a form submission or button click. cancel fires when the user dismisses it with the Esc key. The modal controller tracks both to display the correct status.

[AD] Spinal CMS: Git-based CMS for static site generators

<dialog data-action="close->modal#close cancel->modal#cancel" data-modal-target="dialog">

When Esc is pressed, cancel fires first. The controller sets a flag so close (which fires right after) can distinguish between “closed via button” and “cancelled via Esc”.

A form fires submit as a default event (similar to the Turbo events for form submissions). The form controller shows the :prevent action option to stop the browser from reloading.

<form data-controller="form" data-action="submit->form#validating:prevent">

Stimulus uses @ to scope the event listener to a different element. The full descriptor is event@target->controller#method. Leave off @target and it listens on the controller’s element. Set it to @document or @window and it listens globally.

<section data-controller="visibility" data-action="visibilitychange@document->visibility#toggle">

The visibility controller toggles document.title depending on whether the tab is hidden or visible. The @document suffix is the only way to make this work since visibilitychange fires on the document, not on the controller’s element.

This is also how you hook into Turbo events:

<turbo-frame id="comments" data-action="turbo:frame-render@document->comments#highlight">

And how you listen to custom dispatched events from anywhere. A Stimulus controller, a Turbo Stream response, a WebSocket handler. Call dispatchEvent and bind with the exact same syntax.

element.dispatchEvent(new CustomEvent("cart:updated", { detail: { count: 5 } }))

<span data-controller="cart" data-action="cart:updated@document->cart#updateBadge"></span>

Custom events are just DOM events with a custom name. Stimulus treats them identically to native ones.

One more thing. You can go further with custom action options. I wrote about them here. They let you gate whether an action fires based on custom logic. For example, you could register an open option so the accordion’s persist action only runs when the <details> element opens, not when it closes. All declarative in the HTML, no conditionals in the controller.

The seven default events are convenient, but every DOM event works the same way in Stimulus. Knowing this allows you to write more advanced controllers, simpler. 😊

• Attractive.js 1.0.0: interactive HTML without one line of JavaScript
• Custom Actions in Attractive.js: one interface, from small to big

In this last article I want to highlight how Attractive can be a nice addition and in some cases a complete replacement for Hotwire.

I created a simple message board in Rails. No Stimulus anywhere, nor Turbo Streams. Check it out!

Most of the features of the is build one Attractive extension I intentionaly left out last week; Attract. It serves two purposes:

• intercept form request and send fetch instead (we know that technique!), and:
• work with attract JSON responses to render HTML based off of template elements

One partial, three uses

The whole thing uses one single partial for a message:

<%# locals: (message:) %>
<li class="message" id="message-<%= message.id %>">
  <small class="author" attract-field="author"><%= message.author %></small>

  <p class="body" attract-field="body"><%= message.body %></p>
</li>

This one partial renders the initial page, drives the optimistic UI and powers the lazy load. Say what?! 🤯 The attract-field attributes tell Attractive’s Attract where to slot data when it renders the template.

Client and server validation

The message body validates on the client with the native Constraint Validation API, via the @validate extensions (mentioned last week). Just required and minlength attributes, plus one attribute on the form:

<form @validate @attract …>
  <input id="author" name="author" type="text" placeholder="Your name">

  <textarea name="body" required minlength="3"></textarea>
</form>

The name field, by contrast, is deliberately left without a client rule. Its validation comes from the server. When Rails rejects it, the errors come back as JSON and get wired into the same native validation UI. Client and server errors render identically.

Optimistic UI

The form has @attract, so submitting it sends a fetch instead of a page reload. A cached <template> renders an optimistic preview instantly, from that same partial, while the server processes the request:

<p><strong @text="message_count">41</strong> messages</p>

<form
  id="new-message"
  @attract
  data-attract-template="message"
  data-attract-target="messages"
  data-attract-position="prepend"
></form>

<ul id="messages">
  <%= render @messages %>
</ul>

<template id="message">
  <%= render "messages/message", message: Message.new %>
</template>

In the example app, the create request sleeps for a second so you can actually see the optimistic message appear before the real response. When it comes back, it holds the actions:

{
  "actions": [
    { "action": "setStore#message_count=42" },
    { "action": "reset", "target": "new-message" }
  ]
}

Multiple actions in one response once the message is saved: set the message count using Reactive’s store and a (bundled) action to reset the form.

Attract brings 6 more actions to the table. They almost all clone a cached template (like #message above):

• append to append to target
• prepend to prepend to target
• replace to replace target element
• before to insert before target
• after to clone template, insert after target

And the odd one:

• remove to remove target element(s)

The nice thing is, you can use these actions solo without attract as well, like I do for my flash (toast) messages:

<%# locals: (message:, icon: :check, icon_css: …, css: …) %>
<li @action="remove:mounted" data-delay="7500" class="…">
  <%= tag.p safe_join([icon(icon, class: icon_css), message]), aria: {live: :polite}, class: css %>
</li>

The message gets removed from the DOM after a delay of 7500ms.

Lazy loading messages

The message list loads five at a time. At the bottom, a simple form GET request that is triggered when in view (using the bundled whenInView trigger):

<form
  method="get"
  action="/messages?offset=5"
  @action="submit:whenInView"
  @attract
></form>

The server replies with a sequence of actions: append the next batch, when there are more, swap in a fresh “lazy load action” and point it at the next offset or remove it when the list runs out.

render json: {
  actions: [
    { action: "append", target: "messages", template: "message", data: batch },
    { action: "replace", target: "load-more", template: "load-more", data: {} },
    { action: "setAttribute#action=/messages?offset=10", target: "load-more" }
  ]
}

Three actions, one request.

Keyboard shortcuts

The Attractive Element scopes the filter and the keyboard extension wires the shortcuts. @hotkey.meta+k focuses the filter, @keydown.escape clears it, @keydown.meta+enter submits the form.

And that is how Attractive can work alongside Hotwire or replace it; depending on your needs. I am quite excited how this all turned out. It has been multiple months in the making (excluding the time noodling it over in my brain).

I would love for you to give it a try, just the bundled actions for your (Perron-powered 💡) site, along-side Hotwire or even replacing it. Let met know how it goes.

Things I am thinking about adding is support for SSE so you can “broadcast” actions to many and also an attractivejs-rails gem (to remove some of the ceremony you see in the Rails demo app).

Get started with the quickstart and give the repo a star or fix a bug you find! ✨😊

Next to that I will also highlight some extra goodies and the bundled extensions that can now be (optionally) added.

Start with a one-liner

The quickest custom action is the js: prefix. It evaluates a JavaScript expression on the element, so you can do things too small for a full action:

<button @click="js:this.textContent=1">0 (I will become 1)</button>

Use it for one-liners only. It goes through the full action pipeline (so all events works as well as data-debounce and data-delay). It runs new Function() under the hood (which needs unsafe-eval in your CSP).

A custom action as a function

The step up from js: is a plain function. Register it with addActions on activate():

import Attractive from "attractivejs";

const sharePage = (element, { dataset }) => {
  const title = dataset.shareTitle || document.title;
  const url = dataset.shareUrl || window.location.href;

  if (navigator.share) {
    navigator.share({ title, url });
  } else {
    // write to clipboard or however you want to handle this
  }
};

Attractive.activate({
  addActions: { sharePage }
});

<button @action="sharePage" data-share-title="Check this out">Share</button>

The function receives the element and a context object with value, target, targets, event and dataset. In a Rails app you’d put this in app/javascript/application.js and you’re done. The markup stays identical to a built-in action.

A custom action as a class

When an action grows beyond a reasonable size, it becomes a class. Any class with a run() method works:

class Reorder {
  run() {
    this.element;  // the element with @action
    this.options;  // { value, target, targets, event, dataset, … }
  }
}

Register it the same way as the function:

Attractive.activate({
  addActions: { reorder: Reorder }
});

There’s an optional Action base class that gives you value, dataset and a dispatchEvent helper:

import { Action } from "attractivejs";

export default class Reorder extends Action {
  run() {
    this.value;  // the string after # in @action="reorder#…"
    this.dataset;

    this.dispatchEvent("reorder:done", { ids: [1, 2, 3] });
  }
}

Notice what didn’t change: registration is the same as the function version. You started with a one-liner, then a function, then a class and the interface stayed the same the whole way. Pretty cool, right?

Organizing actions

When you have a handful of actions, keep each in its own file and collect them in a barrel (same as how Stimulus is organized):

app/javascript/
  actions/
    reorder.js
    syntax_highlighting.js
    index.js

Each file exports a single function or class as default. The barrel collects them:

// app/javascript/actions/index.js
import syntax_highlighting from "./syntax_highlighting.js";
import reorder from "./reorder.js";

export default { syntax_highlighting, reorder };

Then your application file imports the barrel and activates:

import Attractive from "attractivejs";
import actions from "./actions/index.js";

Attractive.activate({ addActions: actions });

Hooks and error handling

Hooks let you run code around every action and handle errors in one place.

beforeAction runs before each action, return false to cancel it. afterAction runs after a success. onError handles a thrown action:

attractive.onError(({ name, element, options, event, error }) => {
  console.warn(`Action ${name} failed:`, error.message);
});

There are no unhandled rejections, the rest of a chained action still runs. There’s a global Attractive.onError fallback too, handy for wiring up a monitoring service.

The extensions

Attractive ships a few optional extensions you opt into with extendWith.

Keyboard

The keyboard extension gives you @keydown.enter, combos like @keydown.ctrl+k and global @hotkey shortcuts:

import { keyboard } from "attractivejs/keyboard";

Attractive.activate({ extendWith: [keyboard] });

<input @keydown.mod+enter="submit" @target="form">

<a href="/" aria-hidden="true" @hotkey.g.h="/">Homepage</a>

Validate

The validate extension brings client-side form validation using the browser’s native Constraint Validation API. Just add @validate to a form and style the invalid state:

import { validate } from "attractivejs/validate";

Attractive.activate({ extendWith: [validate] });

input:user-invalid {
  border-color: red;
}

Reactive

The reactive extension adds a shared JSON store with @text bindings and a setStore:

<input @input="setStore#name" />

<p>Hello, <span @text="name"></span></p>

Attractive Element

Attractive Element is the last piece I want to highlight today: a custom element base class. It scopes Attractive to a component, so actions and targets work inside it without a connectedCallback, a querySelector or manual teardown.

import { AttractiveElement } from "attractivejs/element";

class Counter extends AttractiveElement {
  connect() {
    this.count = 0;
  }

  increment() {
    this.target("count").textContent = ++this.count;
  }
}

customElements.define("ui-counter", Counter);

<ui-counter>
  <button @click="increment">+</button>

  <output id="count">0</output>
</ui-counter>

connect() and disconnect() replace the lifecycle callbacks. Methods in the HTML become actions. this.target("id") and this.targets(".selector") query within the component, so each component resolves its own targets even when the same id appears twice. It works alongside a document-wide activation without actions firing twice.

One interface for everything, from a one-liner to a function to a class to a custom element. That’s why I am so excited about Attractive: it works neatly alongside your bigger frameworks but can also stand on its own feet.

Everything you need is in the docs and the repo is always open for a star and improvement and bugfixes. ☺️

Next week, it comes all together: all of this inside a real Rails app (optimistic UI included 🤫).

I had the idea for Attractive for quite some time, based on the following thought: why do I reach for a framework to toggle a class, add an attribute or copy a bit of text?

So I made Attractive.js: a humble set of declarative HTML actions. You put the behavior on the element itself. No virtual DOM, no state management, no component lifecycle to learn or more of things like that. Reading the markup tells you what the page does. In that regard it is much like Stimulus, but with less ceremony/setup (and Attractive gives you actions out of the gate).

This is an overview of what 1.0.0 looks like (currently available as pre-release).

In a nutshell:

• complete new syntax
• extensibility (create your own custom actions)
• addons like keyboard, reactive, validate and attract (to make Attractive.js a worthy competitor for Hotwire!)
• A base class to write custom elements, named Attractive Element

This week I cover the basics of Attractive.js, next week I go over how to write custom actions and the week following it all comes together in a real Rails app where I show how it can replace Hotwire. But first…

What’s new in 1.0.0

The biggest change is the syntax. Actions used to live in data-action and data-target. Now they’re just @action and @target.

<button @action="toggleClass#active" @target="panel">Toggle</button>

<div id="panel">Content</div>

That’s the whole interaction: an attribute that says what happens and one that says where.

For existing users, it is just a rename:

-<button data-action="mouseenter->addClass#hovered">
+<button @mouseenter="addClass#hovered">

The event-type attributes read like sentences, they’re easier to find in a grep and the old -> bulky syntax is gone. The @ shorthand means the same as @action. And simple setups now work from a single script tag with the activate attribute, no manual Attractive.activate() call:

<script src="//unpkg.com/attractivejs" type="module" activate></script>

The actions

Everyday interactions are covered out of the box. Class and attribute actions (toggleClass, addClass, removeClass, cycleClass, the same for attributes and data attributes), style actions, copy to clipboard, confirm, dialogs, focus, form submit and reset, scroll to and more.

There’s also a js: prefix for the occasional one-liner:

<button @action="js:this.textContent=1">0</button>

Handy when a custom action is a bit too much. For anything bigger, you can write your own action (which is next week’s post).

Triggers and gates

Beyond actions, you can control when they run with triggers and gates, appended to the value with a colon.

Triggers run an action without user input. :mounted runs immediately when the element appears. :whenVisible fires when it scrolls into view:

<img
  @action="addClass#loaded:whenVisible"
  data-src="/image.jpg"
  loading="lazy"
/>

Gates guard an action. :once runs it a single time. :preventDefault calls event.preventDefault(). :whenOutside only fires when the click target is outside the element, which is how the dropdown example from below closes itself:

<button @action="toggleClass#open:once">Click once</button>

<div @action="removeClass#open:whenOutside" @target="menu">…</div>

You can register your own triggers and gates too, with addTriggers and addGates.

What you can build with zero JavaScript

To show what this means in practice, here are a few components you can write without a line of your own JavaScript.

A copy button is one attribute pointing at the target to copy an API key , code example and so on:

<button @action="copy" @target="card-example">Copy</button>

<code id="card-example">…</code>

A dialog (with a newsletter sign up) opens at a certain point within your article:

<div @action="openModal:whenInView" @target="newsletter"></div>

<dialog id="newletter">…</dialog>

Auto-save form data with a debounce:

<form action="POST" id="post">
  <textarea name="body" @action="submit" @target="post" data-debounce="400"></textarea>
</form>

Tabs and accordions are toggleAttribute against the right target. Toasts remove themselves with a :mounted trigger and a data-delay=8000. Even a carousel is just cycleClass on a custom property.

The default event per element type means a button just works with @action alone.

You can see all actions in action in the docs.

How small is it?

The full build is about ~7 KB gzipped (no external dependencies). If you’re feeling fancy, the core engine is less than 5 KB and you can import only the actions you use. That only applies to a bundler setup, though. With importmap, you pin one minified file and you’re done. Either way, it’s a fraction of what you’d drag in for a framework.

Where I’d use this

Attractive.js works great on static sites for those small bits of interactivity, but above examples also show how it works great for server-rendered apps or to replace those bulky toggle_class_controller.js 😅

The core has been solid for a while. Try it with the script tag from the quickstart and if you want to make me happy (besides giving Attractive a try), star the repo. 🌟

Next week: writing your own actions. After that: putting all of it to work in a Rails app.

It worked well. But every YAML file needed manual wiring: <%= ENV.fetch("BOT_API_KEY", Rails.application.credentials.dig(:bot, :api_key)) %>. For every key. Across every file. Ugh!

So I rebuilt it. Same clean Config::Namespace.key API, but now it chains through all three sources automatically.

Before (old module’s YAML):

# config/bot.yml
shared:
  api_key: <%= ENV.fetch("BOT_API_KEY", Rails.application.credentials.dig(:bot, :api_key)) %>
  user_agent: "MyAwesomeBot/1.0"
  timeout: 10

After (new module’s YAML):

# config/bot.yml
shared:
  # Config::Bot.api_key is still available and will check environment variables and then check credentials
  user_agent: "MyAwesomeBot/1.0"
  timeout: 10

One API. Three sources. No more guessing where a value lives.

You can find the full code on GitHub. What follows are the parts I find most interesting.

Lazy namespaces with const_missing

The old version scanned a directory at boot and called const_set for every YAML file. That works, but it means every namespace is loaded whether you use it or not.

This version uses const_missing instead. Reference Config::Bot for the first time and a Namespace object is created lazily:

def self.const_missing(name)
  MUTEX.synchronize do
    @namespaces ||= {}
    @namespaces[name] ||= Namespace.new(name)
  end
end

The Mutex isn’t there by accident. In threaded environments (Puma, Solid Queue), two threads could hit const_missing simultaneously. Mutex makes sure only one namespace object gets created.

The three source chain

Each Namespace uses method_missing to resolve a key:

def method_missing(method, ...)
  key = method.to_s.delete_suffix("!")
  bang = method.to_s.end_with?("!")

  environment_key = "#{@prefix}_#{key.upcase}"
  return @environment_cache[environment_key] if @environment_cache.key?(environment_key)

  value = Rails.application.credentials.dig(@credentials_key.to_sym, key.to_sym)
  return value unless value.nil?

  value = from_yaml(key)
  return value unless value.nil?

  raise(NotFoundError, "Config::#{@name}.#{key} not found") if bang

  nil
end

ENV is checked first. It caches a snapshot at boot via ENV.to_h, so there’s no hash lookup penalty on every access. Then credentials. Then the YAML file via Rails.application.config_for. Bang methods raise instead of returning nil.

The convention for ENV keys follows the namespace: Config::Bot.timeout checks ENV["BOT_TIMEOUT"]. Config::Stripe.api_key checks ENV["STRIPE_API_KEY"]. Predictable and consistent (change to your likings though).

Bang methods and discovery

I added two small quality of life features. Config::Bot.api_key! raises if nothing is found (useful in initializers where a missing secret should fail fast). And Config::Bot.keys lists everything available for that namespace, merging credential keys and YAML keys:

def keys
  credential_keys = Rails.application.credentials.dig(@credentials_key.to_sym)

  [credential_keys, yaml_config].compact.flat_map { it.keys }.uniq
end

There’s also a reload method that clears the ENV cache and YAML cache (for when you’re changing values in the console during development).

What about Rails 8.2’s creds?

Rails 8.2 (currently on main) is introducing Rails.app.creds, which provides Rails.app.creds.require(:stripe, :api_key) and Rails.app.creds.option(:stripe, :api_key). It checks ENV first, then encrypted credentials. Same layered idea, same bang and regular pattern.

The difference is scope. Rails.app.creds focuses on secrets (things that belong in encrypted credentials or ENV). My Config module adds YAML as a third tier, which is where I keep public configuration like URLs, timeouts, API versions and feature flags.

Both solve the same fundamental problem: stop guessing where a value lives and let a unified lookup handle it. Rails.app.creds is the Rails core answer (less setup, more opinionated). My Config module is the DIY answer (flexible, more tiers, yours to tweak).

I’ve been using this version of the Config module in production for some time now. The bang methods alone have caught two misconfigured deployments before they reached customers (the app refuses to boot if a required key is missing). The triple lookup means I can move a value from YAML to credentials to ENV without touching application code. Each tier handles what it’s best at.

The code is on GitHub if you want to drop it into your own app or adapt it.

By default, Rails Icons renders each icon as a full <svg> element. Fine for a handful of icons. But at scale, it adds up.

I built a simple benchmark to measure exactly how much (feel free to fork and improve ❤️). Two pages, identical layout, 1,000 icons each. One uses inline SVGs you use and love. The other uses an SVG sprite you will surely start to love after reading this. 😬

The benchmark is on GitHub.

How SVG sprites work

A SVG sprite is a single file (but can also be embedded) with multiple icon definitions wrapped in <symbol> tags:

<svg xmlns="http://www.w3.org/2000/svg">
  <symbol id="user" viewBox="0 0 24 24">
    <!-- path -->
  </symbol>
  <symbol id="pencil" viewBox="0 0 24 24">
    <!-- path -->
  </symbol>
</svg>

To render an icon, reference it with <use>:

<svg class="icon"><use href="/sprite.svg#user"/></svg>

The browser downloads the sprite file once and caches it. Every <use> is a lightweight DOM reference, not a full SVG subtree. Compare that to inline SVGs where every single icon is a complete <svg> element with all its paths. 1,000 icons means 1,000 unique SVG subtrees parsed, styled and laid out by the browser.

Why not font icons or image tags?

Before SVGs became the standard, font icons were the go-to (if you been around for some time, you surely have used them; I thought they were really cool!). They have problems: limited to one color (unless you stack multiple fonts), inconsistent rendering across browsers and operating systems and poor accessibility. And you’re loading an entire font file for a handful of icons.

Image tags (<img src="icon.svg">) solve the accessibility issue but you lose all styling control. You can’t change the color, stroke width or size via CSS. Every variant needs a separate file. Ouch!

SVG sprites give you the best of both. The <use>-element inherits CSS from the parent <svg>, so you can control color, size and stroke width the same way you do with inline SVGs.

Fully configurable, single HTTP request, accessible by default.

The benchmark

Two pages, identical layout, 1,000 icons each:

• 200 users in a table, 5 icons per row
• Same ERB template, same CSS, same layout
• Only difference: one page uses icon, the other uses sprite_icon (both helper methods from Rails Icons)

Inline:

<%= icon "user" %>
<%= icon "pencil" %>
<%= icon "arrow-path" %>
<%= icon "lock-closed" %>
<%= icon "trash" %>

Sprite:

<%= sprite_icon "user" %>
<%= sprite_icon "pencil" %>
<%= sprite_icon "arrow-path" %>
<%= sprite_icon "lock-closed" %>
<%= sprite_icon "trash" %>

The numbers

The sprite page loads faster, transfers less data and creates a simpler DOM tree.

Using sprites with Rails Icons

Rails Icons 1.9+ ships with built-in sprite support. Configure which icons to include in your initializer:

# config/initializers/rails_icons.rb
RailsIcons.configure do |config|
  config.default_library = "heroicons"

  config.sprite = {
    heroicons: {
      outline: %w[user pencil arrow-path lock-closed trash]
    }
  }
end

Then use sprite_icon in your views:

<%= sprite_icon "user" %>
<%= sprite_icon "pencil" %>

That’s it. The sprite file is served at /rails_icons/sprite.svg. This means you can:

• Cache it; it changes only when you add or remove icons
• Put it behind a CDN; it’s a static asset

When to reach for sprites

Inline SVGs are fine when you have a couple dozen of icons per page. Landing pages, simple forms, blog posts. The extra bytes don’t matter.

Sprites are a good choice when icons multiply. Like with data tables, kanban boards and activity feeds.

The trade-off is one extra HTTP request for the sprite file. On an icon-heavy page, that request pays for itself many times over. 💪

SVG sprites are available in Rails Icons 1.9. Add them to your next icon-heavy view and see the difference.

Yes, just around 100 LoC 🤯

I built one using CSS Anchor Positioning and a Stimulus controller. The approach uses two techniques worth talking about: a clip-path spotlight effect (useful in all sorts of contexts) and CSS anchor positioning for the dialog (still very new as of mid-2026).

The full code, as always, is on GitHub.

The clip-path trick

The overlay covers the viewport with a semi-transparent background. But instead of sitting on top of everything, it uses clip-path: polygon() to cut a hole around the target element, creating a spotlight effect.

#clipPath(target) {
  const { top, right, bottom, left } = target.getBoundingClientRect()
  const gap = 8

  this.#overlay.style.clipPath =
    `polygon(0% 0%, 100% 0%, 100% 100%, 0% 100%, ` +
    `0% ${top - gap}px, ${left - gap}px ${top - gap}px, ` +
    `${left - gap}px ${bottom + gap}px, ${right + gap}px ${bottom + gap}px, ` +
    `${right + gap}px ${top - gap}px, 0% ${top - gap}px)`
}

The polygon traces the full viewport boundary, then cuts inward around the target’s bounding box with an 8px gap. A requestAnimationFrame loop keeps the hole positioned correctly during scroll and resize.

This technique works for any overlay-with-a-hole scenario: tooltips, walkthroughs, masking, focus modes.

Anchoring the dialog

The dialog card attaches itself to the target element using CSS Anchor Positioning. No JS position calculation, no ResizeObserver.

[data-controller="onboarding"] > .card {
  position: fixed;
  position-anchor: --onboarding-target;
  left: anchor(--onboarding-target right);
  top: anchor(--onboarding-target top);
  position-try-fallbacks: flip-inline, flip-block, flip-start;
}

The JS sets anchor-name: --onboarding-target on whichever element the current step targets. The card’s CSS declares position-anchor: --onboarding-target, and anchor() functions read the target’s position. The card places itself at the target’s right edge, top-aligned.

If there isn’t room to the right, position-try-fallbacks lets the browser try alternatives: flip to the left, flip above, flip both axes. Each fallback is tested in order until one fits the viewport. No media queries, no JS overflow detection.

As of mid-2026, Anchor Positioning ships in most browsers. Without support, the card renders without anchoring (the anchor() values fall back to auto). The tour still works, the spotlight still works, the dialog just won’t track the target’s position. That’s a reasonable degradation for an enhancement like this.

[!TIP]
Read this article for a great primer on anchor positioning

One small Stimulus controller

One Stimulus controller to get it all together. On connect it creates the overlay and card elements. Each step is a JSON object with an element selector, title, description, and optional image. Moving through steps updates the anchor-name target, repopulates the dialog content, and the requestAnimationFrame loop keeps the clip-path in sync.

It is the kind of Stimulus controller you can drop into any project, update the step data and you have a working tour. The kind of Stimulus controller I like.

The two techniques are independently useful. The clip-path polygon approach works for any spotlight or masking use case. Anchor positioning removes an entire category of JS positioning code. Combined, they make a feature that usually requires a library into about 100 lines of Stimulus.

position-try-fallbacks is a CSS property that I love to see available! ❤️ Overflow handling has always been a JS problem. Now the browser handles it natively. Look for opportunities to use it anywhere you’re positioning elements! 🛝

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.

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.

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. 🚀🤘

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. 🤙

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.

• 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?

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.

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.

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.

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.

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. ⭐❤️

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>