Fractaled Mind

Writing Tailwind-compatible Semantic CSS

2026-01-02T00:00:00+00:00

Building HTML UI forced me to figure out how to write reusable CSS classes that play nice with Tailwind. Along the way, I looked at how other libraries tackle this. Spoiler: most of them get it wrong.

Let me show you two approaches I found, then I’ll show you what I landed on.

Here’s how Basecoat defines a badge:

@layer components {
  .badge,
  .badge-primary,
  .badge-secondary,
  .badge-destructive,
  .badge-outline {
    @apply inline-flex items-center justify-center rounded-full border px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 [&>svg]:size-3 gap-1 [&>svg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden;
  }
}

One line. Every variant lumped together. State styles crammed in with bracket notation.

DaisyUI does something kinda similar but also notably different:

.badge {
  @layer daisyui.l1.l2.l3 {
    @apply rounded-selector inline-flex items-center justify-center gap-2 align-middle;
    color: var(--badge-fg);
    border: var(--border) solid var(--badge-color, var(--color-base-200));
    font-size: 0.875rem;
    width: fit-content;
    background-size: auto, calc(var(--noise) * 100%);
    background-image: none, var(--fx-noise);
    background-color: var(--badge-bg);
    --badge-bg: var(--badge-color, var(--color-base-100));
    --badge-fg: var(--color-base-content);
    --size: calc(var(--size-selector, 0.25rem) * 6);
    height: var(--size);
    padding-inline: calc(var(--size) / 2 - var(--border));
  }
}

Mixes @apply with raw CSS. Custom properties everywhere. Nested inside a layer with a bizarre naming scheme.

What’s Wrong

Both approaches share three problems:

Problem	Why It Hurts
No tree-shaking	`@layer` ships everything, used or not. Define 20 classes, ship 20 classes.
No autocomplete	Tailwind’s IntelliSense doesn’t know these classes exist. Developers can’t discover them.
Unreadable states	All those `focus-visible:` and `dark:aria-invalid:` prefixes become a wall of noise.

My Approach

Here’s how I write my badge class in HTML UI:

@utility ui-badge {
  :where(&) {
    @apply inline-flex items-center justify-center rounded-full border px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 gap-1 transition-[color,box-shadow] overflow-hidden border-transparent bg-primary text-primary-foreground;

    & > svg {
      @apply size-3 pointer-events-none;
    }

    @variant hover {
      @apply bg-primary/90;
    }

    @variant focus-visible {
      @apply border-ring ring-ring/50 ring-[3px];
    }

    @variant aria-invalid {
      @apply ring-destructive/20 border-destructive;
    }
  }

  @variant dark {
    :where(&) {
      @variant aria-invalid {
        @apply ring-destructive/40;
      }
    }
  }
}

Same basic visual result. Completely different structure. Let me break down why this is better.

`@utility` gives you tree-shaking and autocomplete

Classes defined with @utility only ship if they’re used in your markup. Define twenty, use three, ship three. That’s the essential Tailwind contract, and @layer breaks it.

@utility also registers with IntelliSense. Type your prefix in your editor and see every affordance. Discoverability matters. If developers can’t find your class, they’ll reinvent it inline.

A prefix like `ui-` makes affordances obvious

When you see .btn in a codebase, you have no idea what you’re dealing with. Is it Bootstrap? Some old semantic class with unpredictable specificity? A utility?

A prefix solves this. ui-button signals intent: this is a zero-specificity visual pattern designed to compose with utilities. It’s not last decade’s semantic CSS.

The prefix also makes autocomplete useful. Type ui- and you see every affordance in the system. Pick whatever convention works for your team—af-, look-, whatever—but having a convention communicates that these classes play by different rules.

`:where()` gives you zero specificity

Utilities in @utility live in Tailwind’s utilities layer—highest priority. That’s normally what you want. But affordance classes should be overridable by utilities.

:where() contributes zero specificity. So :where(.ui-badge) has specificity 0,0,0, while bg-red-500 has 0,1,0. The utility always wins:

<span class="ui-badge bg-red-500">Error</span>

No !important. No cascade conflicts. The affordance provides defaults; utilities customize.

`@variant` gives you readable state styles

Compare the Basecoat approach:

@apply focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40;

To this:

@variant focus-visible {
  @apply border-ring ring-ring/50 ring-[3px];
}

@variant aria-invalid {
  @apply ring-destructive/20 border-destructive;
}

@variant dark {
  :where(&) {
    @variant aria-invalid {
      @apply ring-destructive/40;
    }
  }
}

Each state gets its own block. You can see at a glance what changes on focus, what changes when invalid, what changes in dark mode. The structure matches how you think about states.

There’s also a practical reason: @apply hover:bg-red-500 can break in Svelte/Vue <style> blocks because the colon gets parsed as CSS syntax before Tailwind processes it. @variant sidesteps this entirely.

`@apply` makes compatibility a non-issue

You might wonder why I use @apply instead of raw CSS. The answer is compatibility.

When you write @apply bg-primary text-sm px-2, you’re referencing the user’s Tailwind theme. Their colors. Their spacing scale. Their typography. If they’ve customized primary to be orange instead of indigo, your affordance automatically uses orange. If they use a non-standard spacing scale, px-2 resolves to whatever they defined.

DaisyUI’s approach—defining its own custom properties like --badge-fg and --color-base-200—creates a parallel design system. Users have to map their tokens to DaisyUI’s tokens. That’s friction.

@apply eliminates that friction. Your affordances speak the same language as the user’s utilities because they are the user’s utilities, just composed.

Tailwind v4’s @utility, @apply, and @variant directives aren’t just new syntax. Combined with :where(), they let you write semantic CSS classes that are discoverable, tree-shakeable, readable, and composable with utilities.

That’s the approach. Now go build something.

2025 in review

2025-12-31T00:00:00+00:00

On September 23rd, 2025, in a Berlin hospital room, I became a dad. Emma Elanor Margheim entered the world and promptly rearranged every priority I thought I had.

She’s currently asleep, so let me tell you about the rest of the year.

Becoming a Family

The year began with a milestone: on January 13th, Geniya became a German citizen. After oodles of paperwork and appointments and waiting, she walked out of the Ausländerbehörde as a dual citizen. We celebrated with sushi.

By spring, we knew Emma was on the way. In June, we escaped to Südtirol for a babymoon—a last hurrah of lazy mornings and mountain views before our family of 2 become a family of 3. We hiked (more like walking, but in nature), ate too much, and tried to imagine what life would look like in a few months.

Then September 23rd arrived, and we began to find out.

What I didn’t fully appreciate until living it: Germany’s support system for new parents is remarkable, coming from someone raised in the States and just simply unaware of what the whole process could look like. A midwife—a Hebamme as they are called here—visited our apartment every single day for the first week after Emma was born. Then weekly for the next two months. She checked on Emma, checked on Geniya, answered our endless questions, and made those early weeks survivable. No bills. No insurance negotiations. Just care.

Looking ahead, knowing that universal childcare exists here—that Emma will have a spot in a Kita—takes an enormous weight off our planning. Starting a family in Germany has meant never once worrying about medical debt. That peace of mind is hard to overstate.

In November, my parents flew over from the States to meet their grand-daughter. A week of them holding Emma, of showing them our Berlin neighborhood, of watching my dad figure out the U-Bahn. It was the first time they’d seen our new life here up close; it was cozy and fun.

The Career Arc

2025 marked my second job change in just over two years. I’d joined Test IO when I moved to Berlin in 2019 and spent five years there—as a senior engineer, then team lead, then engineering manager, and eventually director leading 40+ engineers across five teams. Near the end of 2024, I moved to Prevail.ai as a Senior Engineer; I wanted to get back into writing code daily. Smaller team, different challenges, back to building.

Then in November this year, another shift: Principal Engineer at Impruvon Health. Healthcare tech, Ruby and Rails on the backend, real problems affecting real patients. The onboarding was dense—calls about integrations, architecture discussions, first tasks shipping within weeks. I’m still ramping up, but I’m contributing. Feels good.

The through-line across all of it: I keep finding my way back to Rails, to Ruby, to teams trying to build something that matters.

High Leverage Rails

The biggest project I shipped this year wasn’t code—it was a course.

In February, I launched High Leverage Rails with Aaron Francis and Try Hard Studios. It’s a comprehensive course on building production-ready Rails applications with SQLite—the database I’ve been advocating for years.

The thesis: learn the fundamentals deeply, and you can build anything quickly. The age of the starter kit is ending. Responsibility requires understanding.

Working with Aaron was a highlight. He’s built an incredible media operation, and collaborating on something at that scale pushed me in new directions. Hatchbox and Honeybadger came on as sponsors. The launch went well. And now there are developers out there building real applications with Rails and SQLite because of something I made. Wild.

Open Source

My open source work this year centered on a few key projects:

Acidic Job continued to evolve—durable execution workflows for Active Job. The idea is simple: background jobs should be resilient to failures, restarts, and chaos. The implementation is… less simple. But it’s getting there, with RC releases throughout the year.

Chaotic Job emerged as a companion gem for testing job resilience. It lets you simulate failures, timeouts, and all the ways jobs can go wrong—so you can prove your workflows handle them correctly. I talked about it at Tropical on Rails and ChicagoRuby.

Solid Errors hit v0.7.0 in June—a database-backed exception tracker for Rails. This release was special because it was almost entirely community-driven. PRs from contributors, issues identified by users, a release that felt collaborative.

Litestream Ruby got similar treatment—v0.13.0 shipped with all community contributions. The SQLite ecosystem keeps growing.

And then there’s Plume, my SQL parser for SQLite’s dialect. I spent months on this—learning parser patterns, hitting 37,000+ passing tests, creating syntax diagrams. It became my RubyKaigi talk and remains one of the most technically challenging things I’ve built.

My Ruby Triathlon

In April, I gave three talks on three continents in three consecutive weeks:

Tropical on Rails in São Paulo — “Resilient Jobs and Chaotic Tests”
wroclove.rb in Wrocław — “On the tasteful journey to Yippee” (a project Joel Drapper and I are slowly working on)
RubyKaigi in Matsuyama — “Parsing and generating SQLite’s SQL dialect with Ruby”

I called it my #RubyTriathlon. Geniya called it “that thing where you’re gone for most of April.”

The highlight was RubyKaigi and getting to hang out with the Ruby community in Japan, watching Matz talk about the future of Ruby, eating incredible food, and wandering Matsuyama. The lowlight was the 12-hour-33-minute flight from Warsaw to Tokyo, my longest ever.

Later: SQLite Office Hours at RailsConf with Mike Dalessio, a talk at ChicagoRuby. Five speaking engagements. Four continents. One very tired me.

Staying Connected

Beyond conferences, the Ruby community showed up in smaller ways all year.

In January and February alone, I had 19+ “Chat with Stephen” calls—video chats with developers from around the world. Some wanted to talk SQLite. Some wanted career advice. Some just wanted to connect. One of those calls was with Taylor Otwell, creator of Laravel. I basically begged him to consider expanding the Laravel services to the Rails ecosystem. Maybe one day; a man can dream.

I appeared on podcasts: Remote Ruby, a few episodes of In Dialog, others I’m probably forgetting. I gave a virtual talk to Ruby Turkey. I kept the Naming Things Discord running—it’s invite-only, but it remains one of my favorite corners of the internet. Like a virtual hallway track at a Ruby conference.

In December, after years of meaning to, I finally launched a newsletter. Added a signup form to the blog, sent my first issue. It felt like a missing piece clicking into place.

Writing

I published 6 blog posts this year, but the bigger development was launching a Tips section in December. Short, focused techniques—one concept per post.

The theme across all my writing: platform-native web development. Every month, browsers ship features that used to require JavaScript. I became obsessed with documenting what’s possible. Turns out: a lot.

I will be doing a lot more in this space in 2026 for sure.

Life in Berlin

Some snapshots from the year:

The movie pass. Early in the year, we got a UCI Luxe subscription—unlimited movies for a flat monthly fee. We saw everything: Nosferatu, Anora, A Real Pain, Emilia Perez, Mickey 17, Sinners, Final Destination 6, Ballerina. That last one, Demon Slayer, Geniya let me watch on my own while she was 37 weeks pregnant; she’s a champion. Once Emma arrived, the movie pass got canceled. Priorities shift. 🤷🏻

The studio. In July, I decided I needed a proper space for recording and calls. So I built one. Framed up a corner of our apartment, wired fans, hung insulation and acoustic panels. By August it was done—not perfect, but mine. As Aaron Francis says, you can just build things.

The opera. Swan Lake at Deutsche Oper Berlin in March. Ein Sommernachtstraum earlier that month. A Sicilian cooking class in January. Ballet. These felt like the “before times” in retrospect—the last stretch of being able to do things spontaneously.

The license. After years in Germany, I finally got my driver’s license in July. Test drove a BYD. Still thinking about it.

Sports. The Eagles won the Super Bowl in February (Fly Eagles Fly). LSU won the College World Series in June (Geaux Tigers). I watched both from Berlin, at inconvenient hours, and regret nothing.

By the Numbers

Travel

Flights	21
Miles	43,142
Time in the air	98 hours
Countries visited	9

I flew 1.7x around the Earth. Berlin appeared in 10 of my 21 flights. I never flew on a Friday—not once, for reasons I can’t explain.

Writing

6 blog posts
14 tips
1 newsletter launched

Speaking

5 events
4 continents
3 conference talks, 1 workshop, 1 meetup

Open Source

15+ active repositories
Major releases: Acidic Job, Chaotic Job, Solid Errors, Litestream Ruby, Plume

What I Learned

A few things became clear:

You can just build things. Studios. Parsers. Courses. The barrier is usually deciding to start.

The platform is getting really good. We need less than we think we do to build excellent web apps in 2026.

Community matters more than content. The best moments weren’t the talks. They were the conversations with old and new friends.

Support systems matter. Having a midwife visit daily, never worrying about medical bills, knowing childcare exists—these aren’t luxuries. They’re what let you focus on what matters.

Looking Ahead

As I write this, Emma is just over three months old. She’s has been smiling on purpose for a month or so now. She likes being held upright so she can look around.

For 2026, I’m keeping it simple:

Keep writing. The Tips format works.
Keep speaking. I’m already scheduled to speak at RubyConf Thailand, and I’m on the program committee for RubyConf Austria.
Keep shipping open source. I have some awesome stuff brewing that I can’t wait to share.
Be present. Emma’s first year only happens once.

To everyone who read a post, attended a talk, joined a call, or sent a kind message this year: thank you. The Ruby community remains one of the best places on the internet.

Here’s to 2026. May it be slightly less chaotic and equally wonderful.

— Stephen

Dialog Animation Gotchas

2025-12-19T00:00:00+00:00

I spent way too long getting the animations right for my dialog post. Chrome’s documentation on entry/exit animations made it look simple—define your open state, your starting state, your closed state. Three blocks of CSS. Done.

The entry animation worked immediately. The exit was a disaster. The dialog snapped to full width mid-animation, jumped around, then vanished. The backdrop lingered after close, or disappeared instantly while the dialog was still fading. Nothing synced up.

I want to walk through each problem I hit and how I fixed it, partly as documentation for my future self, partly because I suspect these same issues will bite anyone trying to animate native dialogs.

My first mistake was putting @starting-style in the wrong place. Chrome’s docs show it as a separate block, but I tried nesting it inside the base dialog selector:

dialog {
  opacity: 1;
  scale: 1;
  transition: /* ... */

  @starting-style {
    opacity: 0;
    scale: 0.95;
  }
}

Nothing. No animation.

The issue is that @starting-style defines where to animate from when an element enters a particular state. If you put it inside the base selector, it doesn’t know what state you’re entering. It needs to live inside dialog[open]:

dialog[open] {
  opacity: 1;
  scale: 1;

  @starting-style {
    opacity: 0;
    scale: 0.95;
  }
}

dialog {
  transition: /* ... */
  opacity: 0;
  scale: 0.95;
}

The naming trips you up. “Starting style” sounds like “where this element starts”—the base state. But it means “where this element starts when entering this specific state.”

Now the entry animation worked, but exit was still broken…

When the dialog closed, it snapped to full viewport width before animating out. I stared at this for a while before I thought to slow down the transition. Multiply your timings by 10x and you can actually see what’s happening frame by frame.

The problem was obvious once I could watch it in slow motion. I had my layout styles on dialog[open]:

dialog[open] {
  @apply flex w-full flex-col;
  @apply max-w-[calc(100vw-32px)];
  
  @variant sm {
    @apply max-w-md;
  }
}

The moment [open] gets removed, those constraints vanish. Mid-animation. The dialog loses max-w-md and expands while still fading out.

The fix is to put layout properties in the base selector. Only animation properties should differ between states:

dialog {
  @apply flex w-full flex-col;
  @apply max-w-[calc(100vw-32px)];
  
  @variant sm {
    @apply max-w-md;
  }
  
  /* animation properties here */
}

This is the kind of thing that’s obvious once you internalize it, but easy to miss when you’re thinking about open vs. closed as entirely separate visual states. The dialog needs to maintain its structure throughout its entire lifecycle—including while it’s animating away.

Next problem: the backdrop. It would fade in nicely, then stick around after the dialog closed. Or vanish instantly while the dialog was still animating.

The issue is that the backdrop’s overlay and display durations need to match the dialog’s. The color fade can be different, but the visibility timing has to stay in sync:

dialog::backdrop {
  background-color: rgb(0 0 0 / 0);
  transition:
    background-color 0.05s ease-in-out,
    overlay 0.1s ease-in-out allow-discrete,
    display 0.1s ease-in-out allow-discrete;
}

dialog[open]::backdrop {
  background-color: rgb(0 0 0 / 0.2);
  transition:
    background-color 0.15s ease-in-out,
    overlay 0.2s ease-in-out allow-discrete,
    display 0.2s ease-in-out allow-discrete;

  @starting-style {
    background-color: rgb(0 0 0 / 0);
  }
}

Here the backdrop fades out quickly (0.05s) but stays visible for 0.1s while the dialog finishes its exit. The color and the visibility are decoupled, which gives you flexibility in how the animation feels without breaking the synchronization.

At this point I had working animations, but they mirrored each other—slide up on entry, slide down on exit. I wanted asymmetry: slide up on entry, scale down in place on exit. Sliding down on exit felt wrong to me; it implies the dialog is going somewhere, but it’s not. It’s disappearing. Scale-and-fade says “dismissed” without the false movement.

I tried different transform values for each state:

dialog {
  transform: translateY(0) scale(0.95); /* Exit: just scale */
}

dialog[open] {
  transform: translateY(0) scale(1);
  
  @starting-style {
    transform: translateY(20px) scale(0.98); /* Entry: slide up */
  }
}

Both animations ended up as just scales. CSS transitions animate the shortest path—the exit always reverses from dialog[open] back to dialog. You can’t get different paths with transitions alone.

Keyframes solve this by letting you define completely independent animations:

@keyframes dialog-slide-up-scale-fade {
  from {
    opacity: 0;
    transform: translateY(20px) scale(0.98);
  }
  to {
    opacity: 1;
    transform: translateY(0) scale(1);
  }
}

@keyframes dialog-scale-down-fade {
  from {
    opacity: 1;
    transform: translateY(0) scale(1);
  }
  to {
    opacity: 0;
    transform: translateY(0) scale(0.95);
  }
}

dialog {
  animation: dialog-scale-down-fade 0.1s cubic-bezier(0.16, 1, 0.3, 1) forwards;
  transition:
    overlay 0.1s cubic-bezier(0.16, 1, 0.3, 1) allow-discrete,
    display 0.1s cubic-bezier(0.16, 1, 0.3, 1) allow-discrete;
}

dialog[open] {
  animation: dialog-slide-up-scale-fade 0.2s cubic-bezier(0.16, 1, 0.3, 1) forwards;
  transition:
    overlay 0.2s cubic-bezier(0.16, 1, 0.3, 1) allow-discrete,
    display 0.2s cubic-bezier(0.16, 1, 0.3, 1) allow-discrete;

  @starting-style {
    animation: none;
  }
}

Entry and exit are now independent. Transitions still handle overlay and display (they need allow-discrete because they’re discrete properties). The @starting-style { animation: none; } prevents the exit animation from firing on page load—without it, the dialog animates closed the moment the page renders.

One more issue: using display: flex on the base dialog meant it rendered briefly on page load. A flash of the styled dialog before it settled into its hidden state.

pointer-events: none fixed interaction but not the visual flash. The actual fix is to hide it properly:

dialog {
  visibility: hidden;
  pointer-events: none;
}

dialog[open] {
  visibility: visible;
  pointer-events: auto;
}

Here’s where I landed. Timing lives in CSS variables so changing entry duration cascades everywhere:

dialog {
  --dialog-entry-duration: 0.2s;
  --dialog-exit-duration: calc(var(--dialog-entry-duration) / 2);
  --backdrop-entry-duration: calc(var(--dialog-entry-duration) * 0.75);
  --backdrop-exit-duration: calc(var(--dialog-exit-duration) / 2);
  --dialog-easing: cubic-bezier(0.16, 1, 0.3, 1);
  --backdrop-easing: ease-in-out;

  /* Layout stays constant throughout lifecycle */
  @apply flex w-full flex-col max-w-[calc(100vw-32px)];
  @variant sm { @apply max-w-md; }

  visibility: hidden;
  pointer-events: none;

  animation: dialog-scale-down-fade var(--dialog-exit-duration) var(--dialog-easing) forwards;
  transition:
    overlay var(--dialog-exit-duration) var(--dialog-easing) allow-discrete,
    display var(--dialog-exit-duration) var(--dialog-easing) allow-discrete;
}

dialog[open] {
  visibility: visible;
  pointer-events: auto;

  animation: dialog-slide-up-scale-fade var(--dialog-entry-duration) var(--dialog-easing) forwards;
  transition:
    overlay var(--dialog-entry-duration) var(--dialog-easing) allow-discrete,
    display var(--dialog-entry-duration) var(--dialog-easing) allow-discrete;

  @starting-style {
    animation: none;
  }
}

dialog::backdrop {
  background-color: rgb(0 0 0 / 0);
  transition:
    background-color var(--backdrop-exit-duration) var(--backdrop-easing),
    overlay var(--dialog-exit-duration) var(--backdrop-easing) allow-discrete,
    display var(--dialog-exit-duration) var(--backdrop-easing) allow-discrete;
}

dialog[open]::backdrop {
  background-color: rgb(0 0 0 / 0.2);
  transition:
    background-color var(--backdrop-entry-duration) var(--backdrop-easing),
    overlay var(--dialog-entry-duration) var(--backdrop-easing) allow-discrete,
    display var(--dialog-entry-duration) var(--backdrop-easing) allow-discrete;

  @starting-style {
    background-color: rgb(0 0 0 / 0);
  }
}

Exit runs at half speed (entrances should feel intentional; exits get out of the way). Backdrop color fades faster than dialog content. Backdrop visibility stays synced with dialog.

None of this is complicated once you understand it. But it took me hours to get here, mostly because the failure modes are so disorienting—things jumping, flickering, desynchronizing in ways that don’t immediately point to the cause. The 10x slowdown trick was the breakthrough. Once I could see each frame, the fixes became obvious.

If you want to dig deeper into the CSS features at play here, MDN has solid documentation on @starting-style, the overlay property, and allow-discrete. But honestly, the best way to learn this stuff is to break it, slow it down, and watch what happens.

Stylish <dialog>s

2025-12-18T00:00:00+00:00

Campsite has some of my favorite UI styling on the web. Naturally, I cracked open their source hoping to learn something. What I found: React components rendering <div>s inside <div>s, with piles of JavaScript doing what <dialog> does for free.

So I borrowed their visual design and rebuilt it with semantic HTML and CSS using affordance classes. I want to walk you through all of the choices I’ve made and how it all comes together.

The HTML

Here’s the markup structure I use for a full-featured dialog:

<dialog id="example-dialog" class="ui/dialog" 
        aria-labelledby="example-dialog-title" 
        aria-describedby="example-dialog-desc" 
        closedby="any">
  <header>
    <hgroup>
      <h2 id="example-dialog-title">Basic Dialog</h2>
      <p id="example-dialog-desc">This is a basic dialog with header, content, and footer sections.</p>
    </hgroup>
    <button type="button" class="ui/button/plain aspect-square" 
            commandfor="example-dialog" command="close" 
            aria-label="Close dialog">&times;</button>
  </header>
  <form method="POST" action="#">
    <article>
      <p>
        Dialog content goes here. This area can contain forms, text, images, 
        or any other content. The native <code>&lt;dialog&gt;</code> element 
        handles focus management and accessibility automatically.
      </p>
    </article>
    <footer>
      <button class="ui/button/flat" type="submit" 
              formmethod="dialog" formnovalidate value="cancel">Cancel</button>
      <button class="ui/button/primary" type="submit" autofocus>Confirm</button>
    </footer>
  </form>
</dialog>

Semantic Elements

Yes, I’m a semantic HTML nerd. <header>, <article>, <footer> instead of <div>s everywhere. The structure is obvious when you revisit the code six months later, and you can target these elements directly in CSS without inventing class names.

The Form Wrapper

The body and footer are wrapped in a <form>. This might seem odd at first, but it unlocks key functionality. Dialogs often need to do something—create a resource, update settings, submit data. Wrapping in a form means your dialog is ready for that from the start. And for simple confirmations, method=dialog on the form (or formmethod=dialog on a button) closes the dialog without any network request.

Two Close Mechanisms

The header’s × button uses command=close because it’s outside the form. The footer’s Cancel button uses formmethod=dialog because it’s inside—a submit that closes without hitting the network.

Focus Handling

The confirm button has autofocus. When the dialog opens, focus moves there immediately—keyboard users land on the primary action, one Enter key away.

Light Dismiss

The closedby=any attribute enables “light dismiss”—clicking the backdrop closes the dialog. Combined with the browser’s built-in Escape key handling, users have multiple intuitive ways to close. No JavaScript event listeners required.

Accessibility

The aria-labelledby and aria-describedby attributes connect the dialog to its heading and description. Screen readers announce both immediately when the dialog opens, giving users full context before they need to act.

For confirmation dialogs specifically, add role=alertdialog. This signals that the dialog communicates an important message requiring a user response—distinct from a generic dialog that might just display information or offer a form. The browser and assistive technologies treat alert dialogs with appropriate urgency.

<dialog id="confirm-delete" 
        role="alertdialog"
        aria-labelledby="confirm-title" 
        aria-describedby="confirm-desc">
  <!-- ... -->
</dialog>

The CSS Architecture

The styles use Tailwind v4’s @utility directive to create tree-shakeable, autocomplete-friendly utility classes. Here’s the structure:

@import "tailwindcss";

@theme {
  --shadow-dialog: 0px 0px 3.5px rgba(0, 0, 0, 0.04), 
    0px 0px 10px rgba(0, 0, 0, 0.04),
    0px 0px 24px rgba(0, 0, 0, 0.05), 
    0px 0px 80px rgba(0, 0, 0, 0.08);
  --shadow-dialog-dark: inset 0 0.5px 0 rgb(255 255 255 / 0.08),
    inset 0 0 1px rgb(255 255 255 / 0.24), 
    0 0 0 0.5px rgb(0 0 0 / 1),
    0px 0px 4px rgba(0, 0, 0, 0.08), 
    0px 0px 10px rgba(0, 0, 0, 0.12),
    0px 0px 24px rgba(0, 0, 0, 0.16), 
    0px 0px 80px rgba(0, 0, 0, 0.2);
}

I borrowed these layered shadows directly from Campsite. The multiple shadows at different blur radii create a more natural, ambient lighting effect—the kind that makes people think you hired a designer. In dark mode, inset shadows add an inner glow that gives the panel depth.

The Base Dialog Utility

@utility ui/dialog {
  :where(&) {
    @apply rounded-lg border-none bg-white p-0 text-zinc-900 shadow-dialog;
    @apply isolate flex w-full flex-col;
    @apply max-w-[calc(100vw-32px)] min-w-sm;
    @apply pointer-events-none invisible;
  
    @apply m-auto;
    @apply max-h-[calc(100dvh-env(safe-area-inset-bottom,0)-env(safe-area-inset-top,0)-32px)];
  
    @variant sm {
      @apply max-w-md;
    }
  
    @variant focus {
      @apply outline-0;
    }
  
    @variant open {
      @apply pointer-events-auto visible;
    }
  
    @variant dark {
      @apply bg-zinc-900 text-zinc-50 shadow-dialog-dark;
    }
  }
}

The Visibility Problem

A <dialog> with display: flex stays visible even when closed—the browser’s default display: none gets overridden. The fix: pointer-events-none and invisible. The dialog stays in the DOM but users can’t see or interact with it. When [open] applies, we flip both back. This also prevents a flash of dialog content on page load.

Sizing Constraints

The max-w-[calc(100vw-32px)] ensures the dialog never touches the screen edges—always 16px of breathing room on each side. The min-w-sm (24rem) prevents the dialog from becoming uncomfortably narrow on larger screens.

For height, max-h-[calc(100dvh-env(safe-area-inset-bottom,0)-env(safe-area-inset-top,0)-32px)] does more work. The dvh unit (dynamic viewport height) accounts for mobile browser chrome that appears and disappears. The env(safe-area-inset-*) functions respect the notch and home indicator on modern phones. Together, they ensure the dialog fits the actual available space, not just the theoretical viewport.

Stacking Context

The isolate class creates a new stacking context. Any z-index values inside the dialog stay contained—dropdowns or tooltips won’t escape and interfere with elements outside.

Why `focus` Instead of `focus-visible`

The focus variant removes the outline entirely. You might expect :focus-visible here, but autofocus on dialog buttons triggers :focus, not :focus-visible. If you only style focus-visible, autofocused elements remain unstyled.

Slot Classes and Semantic Selectors

Now for a part I’m quite pleased with. We define independent “slot” utilities that can apply to any element:

@utility dialog/header {
  :where(&) {
    @apply relative flex-none rounded-t-lg p-4 text-sm;

    &:has(> button[command="close"]) {
      @apply pr-12;
    }
  }
}

@utility dialog/title {
  :where(&) {
    @apply m-0 flex-1 font-semibold;
  }
}

@utility dialog/description {
  :where(&) {
    @apply m-0 mt-0.5 text-zinc-600;

    @variant dark {
      @apply text-zinc-300;
    }
  }
}

@utility dialog/content {
  :where(&) {
    @apply flex flex-1 flex-col overflow-y-auto p-4 pt-0 text-sm;
  }
}

@utility dialog/footer {
  :where(&) {
    @apply flex items-center rounded-b-lg border-t border-black/10 p-3;

    @variant dark {
      @apply border-white/12;
    }
  }
}

Then the parent ui/dialog utility applies these to semantic elements automatically:

@utility ui/dialog {
  /* ... base styles ... */

  :where(& > header) {
    @apply dialog/header;
  }

  :where(& header hgroup :is(h1, h2, h3, h4, h5, h6)) {
    @apply dialog/title;
  }

  :where(& header hgroup p) {
    @apply dialog/description;
  }

  :where(& form > article) {
    @apply dialog/content;
  }

  :where(& form > footer) {
    @apply dialog/footer;
  }
}

Write semantic HTML, get automatic styling. Or apply dialog/content directly to a <div> when your framework generates custom markup.

The :where() wrapper keeps specificity at zero. Without it, these nested selectors would have higher specificity than single utility classes, and you’d be fighting your own styles every time you needed to customize something.

Animations

Most dialog implementations just fade in and out. That’s fine, but we can do better.

@keyframes dialog-slide-up-scale-fade {
  from {
    opacity: 0;
    transform: translateY(20px) scale(0.98);
  }
  to {
    opacity: 1;
    transform: translateY(0) scale(1);
  }
}

@keyframes dialog-scale-down-fade {
  from {
    opacity: 1;
    transform: translateY(0) scale(1);
  }
  to {
    opacity: 0;
    transform: translateY(0) scale(0.95);
  }
}

Asymmetric Motion

Entry slides up and scales in. Exit just scales down and fades. Sliding down on exit felt wrong—it implies the dialog is going somewhere, but it’s not. It’s disappearing. Scale-down-and-fade says “dismissed” without false movement.

Timing Differences

@utility ui/dialog {
  --dialog-entry-duration: 0.2s;
  --dialog-exit-duration: calc(var(--dialog-entry-duration) * 0.75);
  --backdrop-entry-duration: calc(var(--dialog-entry-duration) * 0.2);
  --backdrop-exit-duration: calc(var(--dialog-exit-duration) * 0.75);
}

Exit animations run at 75% the duration of entry. Entrances should feel intentional; exits should get out of the way.

The backdrop animates even faster. On entry, it appears almost instantly (20% of dialog duration), then the dialog follows—the dialog emerges from the dimmed background rather than appearing on top of it. On exit, the backdrop fades before the dialog finishes so you never see the dialog floating against a fully-bright background.

The Technical Details

@utility ui/dialog {
  animation: dialog-scale-down-fade var(--dialog-exit-duration) var(--dialog-easing) forwards;
  transition:
    overlay var(--dialog-exit-duration) var(--dialog-easing) allow-discrete,
    display var(--dialog-exit-duration) var(--dialog-easing) allow-discrete;

  @variant open {
    animation: dialog-slide-up-scale-fade var(--dialog-entry-duration) var(--dialog-easing) forwards;

    @starting-style {
      animation: none;
    }
  }
}

The allow-discrete keyword on display and overlay is essential. These are discrete properties—they can’t interpolate between values. The keyword tells the browser to keep the element visible during the exit animation, only flipping to display: none after the animation completes. Without it, your exit animation just… doesn’t happen. The dialog vanishes instantly.

The @starting-style rule defines where the animation begins. Without it, the browser renders the dialog immediately in its final state. Same problem, opposite direction—no entry animation.

Button Styles

The demo includes button styles, but those deserve their own post. Coming soon.

Browser Support

Feature	Chrome	Safari	Firefox
`command`/`commandfor`	135+	26.2+	144+
`@starting-style`	117+	17.5+	129+
`closedby`	134+	Not yet	141+
`allow-discrete`	117+	17.4+	129+

For production today, you can use polyfills if needed:

invokers-polyfill for command/commandfor
dialog-closedby-polyfill for closedby

Interactive Demo

Here’s a working demo. Try opening it, then close it different ways: click the × button, click Cancel, click Confirm, press Escape, or click the backdrop.

Event Log

Want to experiment? Explore the full demo on Tailwind Play where you can tweak the styles and see how everything fits together.

What’s Next

Dialogs are just one piece. I’m building out a full set of affordance classes—buttons, forms, menus, popovers, tabs, tables. Designer-quality styling, browser-native behavior. The kind of UI that makes people ask who you hired. So be on the lookout for more like this 👀.

Confirmation dialogs with zero JavaScript

2025-12-16T00:00:00+00:00

Turbo’s data-turbo-confirm attribute is convenient for quick confirmation dialogs, but the native confirm() prompt it triggers looks dated and out of place. If you want a styled confirmation dialog that matches your app’s design, the traditional approach recommends a lot of JavaScript—a Stimulus controller to open and close the dialog, event listeners for keyboard handling, and coordination between the trigger and the modal.

But, recent browser updates have changed the game. Invoker Commands landed in Chrome 131 and Safari 18.4, giving us declarative dialog control. Combined with @starting-style for animations, we can now build beautiful, animated confirmation dialogs without writing any JavaScript.

Feature	How
Open dialog	`command="show-modal"` on a button
Close dialog	`command="close"` on cancel button
Escape key	Built-in browser behavior
Light dismiss	`closedby="any"` attribute
Enter animation	`@starting-style` CSS rule
Exit animation	`allow-discrete` on `display` transition

Let’s imagine we wanted a confirmation dialog for when a user decides to delete an item in our app. Here is how we could build such a dialog today using modern browser features with zero JavaScript:

<button type="button" commandfor="delete-item-dialog" command="show-modal">
  Delete this item
</button>

<dialog id="delete-item-dialog" closedby="any" role="alertdialog"
        aria-labelledby="dialog-title" aria-describedby="dialog-desc">
  <header>
    <hgroup>
      <h3 id="dialog-title">Delete this item?</h3>
      <p id="dialog-desc">Are you sure you want to permanently delete this item?</p>
    </hgroup>
  </header>
  
  <footer>
    <button type="button" commandfor="delete-item-dialog" command="close">
      Cancel
    </button>
    <%= button_to item_path(item), method: :delete do %>
      Delete item
    <% end %>
  </footer>
</dialog>

The command attribute tells the browser what action to perform, and commandfor specifies the target element by id. With command="show-modal", clicking the button calls showModal() on the target dialog. The cancel button uses command="close" to call the dialog’s close() method. Note the cancel button is type="button", not type="submit"—we don’t want it participating in any form submission.

Modal dialogs opened with showModal() automatically close on Escape. The browser handles it. Adding closedby="any" enables “light dismiss”—clicking the backdrop closes the dialog too.

The aria-labelledby and aria-describedby attributes connect the dialog to its heading and description. Screen reader users hear both the title and explanatory text announced immediately, giving them full context before making a decision. And role="alertdialog" signals the dialog is a confirmation window communicating an important message that requires a user response.

So much functionality with nothing but declarative HTML! I love it.

Adding Animations with `@starting-style`

For a polished feel, add smooth enter/exit transitions. With @starting-style and allow-discrete, we can animate dialogs purely in CSS.

The @starting-style rule defines the initial state when an element first appears. Without it, the browser renders the dialog immediately in its final state. With it, the browser starts from opacity: 0; scale: 0.95 and transitions to opacity: 1; scale: 1, for example.

For exit animations, we need transition-behavior: allow-discrete on display and overlay. Most CSS properties are continuous—opacity can be 0.5, colors can blend. But display is discrete: it’s either none or block, with no intermediate values. Historically, this meant display changes couldn’t animate.

The allow-discrete keyword tells the browser to apply transition timing even for discrete properties. For closing animations, the browser keeps the element visible, runs the exit transition, then flips to display: none only after the transition completes. The overlay property works similarly—it controls whether the dialog stays in the top layer during the transition.

Example CSS

dialog {
  opacity: 1;
  scale: 1;
  
  transition: 
    opacity 0.2s ease-out,
    scale 0.2s ease-out,
    overlay 0.2s ease-out allow-discrete,
    display 0.2s ease-out allow-discrete;
  
  @starting-style {
    opacity: 0;
    scale: 0.95;
  }
}

dialog:not([open]) {
  opacity: 0;
  scale: 0.95;
}

dialog::backdrop {
  background-color: rgb(0 0 0 / 0.5);
  transition: 
    background-color 0.2s ease-out,
    overlay 0.2s ease-out allow-discrete,
    display 0.2s ease-out allow-discrete;
  
  @starting-style {
    background-color: rgb(0 0 0 / 0);
  }
}

dialog:not([open])::backdrop {
  background-color: rgb(0 0 0 / 0);
}

Browser Support

Feature	Chrome	Safari	Firefox	Can I Use
`command`	135+	26.2+	144+	link
`commandfor`	135+	26.2+	144+	link
`@starting-style`	117+	17.5+	129+	link
`closedby`	134+	Not yet	141+	link

Safari support for closedby is still pending. For production use today, add a polyfill: dialog-closedby-polyfill

If you need invoker command support for older browsers, there is also a polyfill for that: invokers-polyfill

Both polyfills are small and only run when native support is missing.

Integrating with Turbo’s Confirm System

Now, what if you want to keep using Turbo’s data-turbo-confirm attribute while getting a styled native dialog?

Turbo provides Turbo.config.forms.confirm for exactly this. Mikael Henriksson has an excellent writeup on this approach and Chris Oliver has a GoRails video as well.

First, add a dialog template to your layout, which you can of course style however you’d like using whatever CSS tooling you have in your app:

<%# app/views/layouts/application.html.erb %>
<dialog id="turbo-confirm-dialog" closedby="any"
        aria-labelledby="turbo-confirm-title" aria-describedby="turbo-confirm-message">
  <header>
    <hgroup>
      <h3 id="turbo-confirm-title">Confirm</h3>
      <p id="turbo-confirm-message"></p>
    </hgroup>
  </header>
  
  <footer>
    <button type="button" commandfor="turbo-confirm-dialog" command="close">
      Cancel
    </button>
    <form method="dialog">
      <button type="submit" value="confirm">
        Confirm
      </button>
    </form>
  </footer>
</dialog>

The Confirm button is type="submit" inside a <form method="dialog">. When submitted, the browser closes the dialog and sets returnValue to the button’s value attribute. This is how we detect which button was pressed—no JavaScript event coordination needed.

Then configure Turbo:

const dialog = document.getElementById("turbo-confirm-dialog")
const messageElement = document.getElementById("turbo-confirm-message")
const confirmButton = dialog?.querySelector("button[value='confirm']")

Turbo.config.forms.confirm = (message, element, submitter) => {
  // Fall back to native confirm if dialog isn't in the DOM
  if (!dialog) return Promise.resolve(confirm(message))

  messageElement.textContent = message
  
  // Allow custom button text via data-turbo-confirm-button
  const buttonText = submitter?.dataset.turboConfirmButton || "Confirm"
  confirmButton.textContent = buttonText
  
  dialog.showModal()

  return new Promise((resolve) => {
    dialog.addEventListener("close", () => {
      resolve(dialog.returnValue === "confirm")
    }, { once: true })
  })
}

The JavaScript does only three things:

set the message text,
customize the button text if provided, and
open the dialog.

Everything else—closing on button click, closing on Escape, closing on backdrop click, determining which button was pressed—is handled by the platform.

The fallback to native confirm() ensures your app still works if the dialog element is missing (e.g., on a different layout or error page).

Turbo.config.forms.confirm expects a function returning a Promise that resolves to true (proceed) or false (cancel). The function receives three arguments: the confirmation message, the element with the data-turbo-confirm attribute, and the submitter element. We listen for the close event and check returnValue. Write this handler once, add one dialog to your layout, and every data-turbo-confirm in your app uses it.

You can customize the confirm button text per-trigger using data-turbo-confirm-button:

<%= button_to item_path(item), 
              method: :delete,
              data: { 
                turbo_confirm: "Are you sure you want to delete this item?",
                turbo_confirm_button: "Delete item"
              } do %>
  Delete
<% end %>

This produces a more contextual confirmation dialog with “Delete item” instead of a generic “Confirm” button—better UX that makes the action clear.

Addendum: Preventing Background Scroll

One common modal requirement is preventing page scroll while the dialog is open:

body:has(dialog:modal) {
  overflow: hidden;
}

The :modal pseudo-class matches dialogs opened with showModal(). Combined with :has(), this selector targets the body only when a modal dialog is open. When the dialog opens, scrolling stops. When it closes, scrolling resumes. The browser handles the coordination.

Appendix: Interactive Demo

Here’s a working demo showing how different close mechanisms work. Try clicking “Delete Item”, then close it different ways: click Cancel, click Delete, press Escape, or click the backdrop. Notice how returnValue is only "confirm" when you click the Delete button.

Event Log

Affordances: The Missing Layer in Frontend Architecture

2025-12-01T00:00:00+00:00

I was building a form with a file input. Nothing fancy—just a place for users to upload a document. I wanted the trigger to look like the other buttons on the page: the same subtle shadows, the same hover effects, the same spacing. I was using Catalyst, the component kit from Tailwind Labs, so I had a <Button> component with all those styles baked in.

But I couldn’t use it.

A file input needs a <label> as its clickable element—that’s how you style file inputs without fighting the browser’s native UI. But Catalyst’s <Button> component only renders as a <button> element or a <Link>. There’s no way to apply those styles to a <label>.

Some component libraries offer escape hatches—props like asChild or render that let you swap out the underlying element. But these props don’t just pass through styles; they pass through the component’s behavior too. That’s fine when you want both. But when you just need the look—when you need an element to appear clickable while retaining its own native semantics—components leave you stuck.

This isn’t a bug in Catalyst. It’s a structural limitation of components as an abstraction. Components are poor vehicles for purely visual styles. And once you see this, you start seeing it everywhere.

Three Things, One Name

Consider the word “button.” In frontend development, it actually refers to three genuinely distinct things:

The <button> element — native HTML semantics and behavior
The Button component — your library’s encapsulation of structure, behavior, and possibly styles
The button visual pattern — rounded corners, padding, solid background, hover states; what makes something look clickable

When you need to make a <label> look like a <button>, you can’t reach for an element or a component.

The same is true for text inputs. There’s the element, the component, and the visual pattern—the border, the focus ring, the placeholder styling—that makes something look like a place to type. You might need that pattern on a <textarea>, a <select>, or a custom autocomplete built on a different element entirely.

These visual patterns have a name in design theory: affordances—visual signals that communicate how an element can be interacted with. The term comes from Don Norman’s The Design of Everyday Things, where he described how the shape of a door handle tells you whether to push or pull. In interfaces, affordances are what make a button look pressable, an input look typeable, a link look clickable.

The standard frontend architecture today needs to add this as the fourth conceptual layer:

Layer	What It Is	Example
Tokens	Atomic design values	`--color-indigo-600`, `--spacing-4`
Utilities	Single-purpose classes	`p-4`, `text-red-500`
Affordances	Element-independent visual patterns	`.ui-button`, `.ui-input`, `.ui-card`
Components	Encapsulated structure + behavior	`<Button>`, `<Dialog>`

Most libraries today bury affordances inside components. That’s the friction I hit with that file input—and I suspect you’ve hit it too. Isolating and naming the affordance layer restores the needed flexibility.

Unnecessary Pain

I love utility classes. I advocate for Tailwind in every team I work with. But when you don’t have an affordance layer and your team enforces a utility-only approach, every element that needs to look interactive gets its own pile of the same classes:

<label class="inline-flex items-center rounded-md bg-blue-600 px-4 py-2 text-sm font-semibold text-white shadow-sm hover:bg-blue-500 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600">
  Upload file
</label>

And every other element that needs that same treatment—an <a> styled as a button, a <summary>, a <div role="button">—gets its own copy of those same fourteen classes.

This creates three concrete problems. First, there’s no single source of truth. When the design changes—when blue-600 becomes indigo-600, or the border radius shifts from rounded-md to rounded-lg—you’re hunting through your codebase for every instance. Find-and-replace helps, but only if the classes appear in the same order, with the same formatting, across every file. They won’t.

Second, the abstraction leaks into component APIs. Without an affordance layer, you end up passing styling props through components or accepting arbitrary className strings that get merged in unpredictable ways. The component boundary, which should encapsulate complexity, becomes a surface for styling conflicts.

Third, consistency degrades over time. One developer uses hover:bg-indigo-500. Another uses hover:bg-indigo-600. A third forgets the focus styles entirely. No single element is wrong, but the product slowly becomes a patchwork. There’s no abstraction enforcing that “things which afford clicking should look like this.”

Beyond the pain of such a utility-only approach, we also feel the need to isolate purely presentational styles from purely behavioral components. That’s why headless libraries—Base UI, Headless UI, Radix UI—have swept through the frontend community like wildfire. We know behavior and styling need to be decoupled.

Headless libraries solved half the problem. They gave us components that handle accessibility, keyboard navigation, focus management—all the behavioral complexity—without dictating appearance.

But they left the styling half unsolved. Without a clear concept for that layer, most developers just inline utilities everywhere. And that brings us right back to the problems above: no single source of truth, leaky component APIs, consistency drift.

Affordances solve this other half.

“We Tried That. It Didn’t Work.”

I hear the objection already: “Isn’t this just… semantic CSS classes? We tried that.”

You’re right that we tried it. But “it didn’t work” deserves unpacking.

The problem with traditional semantic classes like .btn wasn’t the concept—it was the execution. In a utility-first world, semantic classes create specificity conflicts. If you write .btn { background: blue; }, that rule has a specificity of 0,1,0. When you try to customize with a utility like bg-red-500, the utility also has specificity 0,1,0. Order-dependent chaos ensues. You end up fighting the cascade instead of working with it.

Many developers who were burned by Bootstrap’s specificity nightmares found Tailwind and subsequently internalized “never write semantic classes” as a hard rule. That lesson may have been correct at the time, but the platform has evolved.

CSS now has cascade layers—a feature designed precisely for this problem. Layers let you define explicit priority ordering for groups of styles, independent of specificity or source order. Styles in later layers always beat styles in earlier layers, regardless of selector specificity.

This means you can put affordances in a layer that sits below utilities:

@layer affordances, utilities;

@layer affordances {
  .ui-button {
    display: inline-flex;
    align-items: center;
    padding: var(--spacing-2) var(--spacing-4);
    border-radius: var(--rounded-md);
    background-color: var(--color-indigo-600);
    color: var(--color-white);
    font-size: var(--text-sm);
    font-weight: var(--font-semibold);
    box-shadow: var(--shadow-sm);

    &:hover {
      background-color: var(--color-indigo-500);
    }

    &:focus-visible {
      outline: 2px solid var(--color-indigo-600);
      outline-offset: 2px;
    }
  }
}

Now any utility in the utilities layer will override .ui-button, no matter how specific the affordance selector is. Tailwind v4 already uses layers internally, so your utilities will naturally win.

For extra safety—or if you’re working with CSS that doesn’t use layers—you can also wrap selectors in :where() pseudo-class, which contributes zero specificity:

@layer affordances {
  :where(.ui-button) {
    /* ... */
  }
}

Now .ui-button has zero specificity and lives in a lower layer. Belt and suspenders.

<button class="ui-button bg-red-600 hover:bg-red-500">Delete</button>

The bg-red-600 utility wins. No !important, no specificity wars, no awkward workarounds. The affordance provides sensible defaults; utilities customize as needed.

NOTE: I use the ui- prefix to distinguish affordance classes from old-school semantic classes. When you see .btn, you might reasonably wonder if it’s a Bootstrap remnant with unpredictable specificity. When you see .ui-button, the prefix signals intent: this is a low-specificity visual pattern designed to compose with utilities. Pick whatever convention works for your team: af-, look-, or just go unprefixed if you’re starting fresh—but having a convention helps communicate that these aren’t last decade’s semantic classes.

This isn’t a return to 2015. It’s a genuinely new capability. Cascade layers and :where() achieved broad browser support in 2022, and we’re only now catching up to what they enable. The tooling is ready. It’s time for our concepts, terminology, and best practices to follow.

In Practice

Remember that file input from the opening? Here’s how it looks with an affordance layer:

<label for="document-upload" class="ui-button">
  Choose file
</label>
<input type="file" id="document-upload" class="sr-only" />

That’s it. The <label> gets the button affordance. The <input> is visually hidden but remains accessible. The <label> retains its native behavior—clicking it still triggers the file picker. No component gymnastics, no escape hatches, no fighting the framework.

If Catalyst shipped a .ui-button affordance class alongside its <Button> component, I never would have been stuck. The component could still encapsulate behavior for the common case. But when I needed just the look—for a <label>, a <summary>, an <a>, whatever—I’d have a clean path forward.

“What about primary, secondary, and destructive button variants?” I hear you ask. You have two options.

The first is to define variant affordance classes:

@layer affordances {
  :where(.ui-button-secondary) {
    background-color: var(--color-gray-100);
    color: var(--color-gray-900);
    &:hover { background-color: var(--color-gray-200); }
  }

  :where(.ui-button-danger) {
    background-color: var(--color-red-600);
    &:hover { background-color: var(--color-red-500); }
  }
}

The second is to use a base affordance and compose with utilities:

<button class="ui-button bg-red-600 hover:bg-red-500">Delete</button>

I prefer the composition approach for one-offs and the variant classes for patterns that repeat across your codebase. The zero-specificity foundation makes both work seamlessly.

A Call to Library Authors

If you maintain a component library, consider this: ship affordances alongside your components.

Your <Button> component is valuable. It handles click events, loading states, disabled styling, maybe even analytics. Keep all of that.

But also ship a .ui-button class (or whatever naming convention you prefer) that carries just the visual treatment. Let developers apply that class to any element they need. Use @layer and :where() to ensure it composes cleanly with utilities.

The same goes for inputs, cards, badges, and every other visual pattern in your system. The component is the opinionated, full-featured path. The affordance is the escape hatch—the flexibility that lets developers solve problems you didn’t anticipate.

This is the shift I’m advocating for: stop treating visual patterns as implementation details of components. Expose them as first-class primitives. Use :where() to make them composable with utilities. Let developers apply them to any element, for any reason, without gymnastics.

The Way Forward

The <button> element, the Button component, and the .ui-button affordance are three different things. Modern frontend architecture should treat them that way.

We’ve spent years learning to separate concerns—content from presentation, structure from styling, behavior from appearance. Headless libraries gave us behavioral components without visual opinions. But we stopped halfway. We decoupled behavior from styling, then immediately coupled styling back to specific elements by inlining utilities everywhere.

Affordances complete the separation. They give us reusable visual patterns that work with any element, compose cleanly with utilities, and provide a single source of truth for how interactive elements should look.

With @layer and :where(), we finally have the technical foundation to make this work without specificity conflicts. The only thing missing is the shift in how we think about our CSS architecture.

CSS-only Star Rating Component with Half Steps

2025-06-19T00:00:00+00:00

After some experimentation, research, and AI being stupid, I finally have a simple, clean implementation of a star rating component that uses only radio inputs and labels and allows for half steps. 50 lines of beautiful CSS. Let’s break it down piece by piece.

Before I dove into the code, I did some research on how others had tackled this problem with pure CSS. I found two implementations that I liked. Both used simple radio inputs and labels, which is essential to the solution I want. But, both had some limitations that I didn’t like. One didn’t support half steps, while the other relied on the FontAwesome font. I want to use simple background image SVGs and radio inputs. So, after digesting some details from those solutions, I turned to writing my own.

There are a handful of essential details. Let’s walk through them one by one.

The first detail concerns the HTML structure. Since we only want to use vanilla CSS, we have some constraints around the features we have access to. We can use the subsequent sibling selector to select elements after a hovered one. But, in a star rating component, we need to highlight the stars before the hovered one, showing which stars will be selected if the currently hovered radio is checked. In order to achieve this behavior, our HTML structure will put the radios in reverse order, from 5 stars to 0.5 stars:

<fieldset class="star-rating">
  <input type="radio" id="rating10" name="rating" value="10" />
  <label for="rating10" title="5 stars" aria-label="5 stars"></label>

  <input type="radio" id="rating9" name="rating" value="9" />
  <label for="rating9" title="4 1/2 stars" aria-label="4 1/2 stars"></label>

  <input type="radio" id="rating8" name="rating" value="8" />
  <label for="rating8" title="4 stars" aria-label="4 stars"></label>

  <input type="radio" id="rating7" name="rating" value="7" />
  <label for="rating7" title="3 1/2 stars" aria-label="3 1/2 stars"></label>

  <input type="radio" id="rating6" name="rating" value="6" />
  <label for="rating6" title="3 stars" aria-label="3 stars"></label>

  <input type="radio" id="rating5" name="rating" value="5" />
  <label for="rating5" title="2 1/2 stars" aria-label="2 1/2 stars"></label>

  <input type="radio" id="rating4" name="rating" value="4" />
  <label for="rating4" title="2 stars" aria-label="2 stars"></label>

  <input type="radio" id="rating3" name="rating" value="3" />
  <label for="rating3" title="1 1/2 stars" aria-label="1 1/2 stars"></label>

  <input type="radio" id="rating2" name="rating" value="2" />
  <label for="rating2" title="1 star" aria-label="1 star"></label>

  <input type="radio" id="rating1" name="rating" value="1" />
  <label for="rating1" title="1/2 star" aria-label="1/2 star"></label>
</fieldset>

This allows us to easily highlight all radios beneath the currently hovered/checked one:

/* color current and previous stars on checked */
input:checked ~ label,
/* color previous stars on hover */
label:hover, label:hover ~ label {
  background-color: goldenrod;
}

If rating9 were hovered or checked, all radios subsequent in the DOM (so, rating8 and below) would be highlighted in goldenrod.

But, by having the radios in DOM order from highest to lowest rating, the component would render backwards relative to the expected order. Users expect to have the 0.5 rating first, followed by the 1 star rating, then the 1.5 star rating, and so on. So, we need the rendered order to be reversed from the DOM order. Luckily, CSS provides flex layouts which make it easy to reverse the order of elements via flex-direction:

.star-rating {
  display: inline-flex;
  flex-direction: row-reverse;
  justify-content: flex-end;
}

By making the .rate container a flex container with flex-direction: row-reverse, we can reverse the order of the stars in the UI while maintaining the needed DOM order.

This technique of having the DOM order be optimized for CSS selectors, while the UI order is optimized for usage is a powerful tool to have in your CSS toolbelt.

The next essential detail is rendering the stars. Supporting half steps makes this component notably more complicated. In order to keep things straightforward, I took the FontAwesome half-star icon and manually created SVGs for both a left- and right-handed half star, with no padding:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 264 512">
  <path d="M264 0c-12.2.1-23.3 7-28.6 18L171 150.3 27.4 171.5c-12 1.8-22 10.2-25.7 21.7-3.7 11.5-.7 24.2 7.9 32.7L113.8 329 89.2 474.7c-2 12 3 24.2 12.9 31.3 9.9 7.1 23 8 33.8 2.3L264 439.8V0Z"/>
</svg>

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 264 512">
  <path d="M0 0c12.2.1 23.3 7 28.6 18L93 150.3l143.6 21.2c12 1.8 22 10.2 25.7 21.7 3.7 11.5.7 24.2-7.9 32.7L150.2 329l24.6 145.7c2 12-3 24.2-12.9 31.3-9.9 7.1-23 8-33.8 2.3L0 439.8V0Z"/>
</svg>

I then convert these SVGs into backgroung urls, using the appropriate image for each label:

/* full star steps; right-handed half star */
label:nth-of-type(odd) {
  background: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 264 512"><path d="M0 0c12.2.1 23.3 7 28.6 18L93 150.3l143.6 21.2c12 1.8 22 10.2 25.7 21.7 3.7 11.5.7 24.2-7.9 32.7L150.2 329l24.6 145.7c2 12-3 24.2-12.9 31.3-9.9 7.1-23 8-33.8 2.3L0 439.8V0Z"/></svg>') no-repeat;
}
/* half star steps; left-handed half star */
label:nth-of-type(even) {
  background: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 264 512"><path d="M264 0c-12.2.1-23.3 7-28.6 18L171 150.3 27.4 171.5c-12 1.8-22 10.2-25.7 21.7-3.7 11.5-.7 24.2 7.9 32.7L113.8 329 89.2 474.7c-2 12 3 24.2 12.9 31.3 9.9 7.1 23 8 33.8 2.3L264 439.8V0Z"/></svg>') no-repeat;
}

Since we will render stars for the labels, we can simply visually hide the inputs:

input {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

Then, we style the labels to properly render the background SVG images:

label {
  display: block;
  height: 2rem;
  width: 1rem;
}

The key detail is to have the width be half the size of the height.

With the input elements visually hidden (but still accessible in the DOM for screen readers) and the label elements rendering the half star SVG images, we have the foundation for our component:

The next detail is to highlight the star segments on hover and selection.

This is unfortunately not possible with CSS background property using an embedded SVG url. You cannot dynamically change the fill color of an SVG background image using CSS. Luckily, we can take advantage of this technique and use the mask property instead of background, which allows a background-color to bleed through. So, we update our label CSS like so:

label {
  display: block;
  height: 2rem;
  width: 1rem;
  background-color: currentColor;
}
/* full star steps; right-handed half star */
label:nth-of-type(odd) {
  mask: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 264 512"><path d="M0 0c12.2.1 23.3 7 28.6 18L93 150.3l143.6 21.2c12 1.8 22 10.2 25.7 21.7 3.7 11.5.7 24.2-7.9 32.7L150.2 329l24.6 145.7c2 12-3 24.2-12.9 31.3-9.9 7.1-23 8-33.8 2.3L0 439.8V0Z"/></svg>') no-repeat;
}
/* half star steps; left-handed half star */
label:nth-of-type(even) {
  mask: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 264 512"><path d="M264 0c-12.2.1-23.3 7-28.6 18L171 150.3 27.4 171.5c-12 1.8-22 10.2-25.7 21.7-3.7 11.5-.7 24.2 7.9 32.7L113.8 329 89.2 474.7c-2 12 3 24.2 12.9 31.3 9.9 7.1 23 8 33.8 2.3L264 439.8V0Z"/></svg>') no-repeat;
}

This now permits us to highlight the star segments on hover using a simple background-color change:

/* color current and previous stars on checked */
input:checked ~ label,
/* color previous stars on hover */
label:hover, label:hover ~ label {
  background-color: goldenrod;
}

Likewise, we can style the appropriate star segments based on checked state similarly:

/* highlight current and previous stars */
input:checked + label:hover, input:checked ~ label:hover,
/* highlight previous selected stars for new rating */
input:checked ~ label:hover ~ label,
/* highlight previous selected stars */
label:hover ~ input:checked ~ label {
  background-color: gold;
}

This makes our component beautifully interactive:

The final detail is adding a bit of spacing between the stars, but in such a way that the hover interaction is smooth and natural. My initial idea was to add a bit of margin to the full star step elements:

/* full star steps; right-handed half star */
label:nth-of-type(odd) {
  mask: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 264 512"><path d="M0 0c12.2.1 23.3 7 28.6 18L93 150.3l143.6 21.2c12 1.8 22 10.2 25.7 21.7 3.7 11.5.7 24.2-7.9 32.7L150.2 329l24.6 145.7c2 12-3 24.2-12.9 31.3-9.9 7.1-23 8-33.8 2.3L0 439.8V0Z"/></svg>') no-repeat;
  margin-inline-end: 0.25em;
}

But, this created a fragmented hover interaction:

Whenever the mouse is between stars, no stars are highlighted at all. This creates a fractured user experience, where stars are highlighted and unhighlighted in a disjointed manner. What we need is a way to ensure that there is a visual gap between stars, but when the mouse is in that visual gap, it is still technically hovering over a star segment. We can accomplish this by adding expanding the width of the label elements for the outer, half step star segments, while keeping the image width the smaller fixed width:

label:nth-of-type(odd) {
  mask: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 264 512"><path d="M0 0c12.2.1 23.3 7 28.6 18L93 150.3l143.6 21.2c12 1.8 22 10.2 25.7 21.7 3.7 11.5.7 24.2-7.9 32.7L150.2 329l24.6 145.7c2 12-3 24.2-12.9 31.3-9.9 7.1-23 8-33.8 2.3L0 439.8V0Z"/></svg>') no-repeat;
  width: 1.25rem;
  mask-size: 1rem;
}

The key detail is that the mask-size equals the default width of the stars and the width for these segments includes some visual padding. Here, I have done it manually, but we can also use CSS properties and the calc() function:

/* settable properties */
--star-size: 2rem;
--star-gap: 0.25rem;
/* computed properties */
--star-height: var(--star-size);
--star-width: calc(var(--star-size) / 2);
--star-width-plus-gap: calc(var(--star-width) + var(--star-gap));

Either way, by expanding the width of the right-hand star segments, we create a gap between the stars that still triggers the hover styles on the visually preceding star segment. This ensures that the hover interaction is seamless and continuous, providing a smoother user experience.

The only other final detail is to remove the final margin on the right-hand side of the component:

label:first-of-type {
  width: 1rem;
  /* or width: var(--star-width) */
}

We use the first-of-type selector because, remember, the far right star segment is actually the first star segment in the DOM order. Now, the star-rating component is exactly the width of the stars. If you are using the fieldset element as the wrapping element, you may want to remove the border as well:

fieldset {
  border: none;
}

But, with all of that, our vanilla CSS star rating component is now complete. It is fully functional, responsive, and accessible. It also provides a smooth user experience with no visual gaps between stars:

If you want to see the full code, check out the playground. And, if you’ve enjoyed following along, you would likely enjoy following my Twitter account: @fractaledmind.

Always use flex-wrap: wrap on flex containers

2024-12-12T00:00:00+00:00

I spent a bit of time this morning make some improvements to sqlite.directory, and I found myself needing to make a number of fixes around the mobile responsiveness of the UI. So, I thought I would take a moment to catalog a few common patterns and tips I have found useful when working with responsive design. This first tip was one that I found myself using quite a bit today.

I use flex containers a ton; I love them. But, I find myself overlooking the same responsive detail time and time again—I don’t properly handle wrapping. Let’s take a real example from the sqlite.directory header:

See the Pen responsive design tip: flex-wrap (before) by Stephen Margheim (@smargh) on CodePen.

As you can see, on a smaller screen, the website title/logo and the user info are smashed together. Just ugly. I fixed this issue in this commit where I made these two simple changes:

<header class="w-full max-w-6xl mx-auto py-4 mb-4 text-lg flex justify-between items-center border-b"> <!-- [tl! remove:1] -->
  <h2 class="flex items-center gap-2">
<header class="w-full max-w-6xl mx-auto py-4 mb-4 text-lg flex justify-between items-center flex-wrap gap-y-2 border-b"> <!-- [tl! add:1] -->
  <h2 class="flex items-center gap-2 whitespace-nowrap">
    <%= link_to root_path, class: "group" do %>
      <%= image_tag "/icon.svg", class: "inline-block" %>
      <code class="">
        <span class="text-blue-500 group-hover:underline decoration-blue-500">sqlite</span>
        <span class="inline-block group-hover:animate-bouncing -mx-3">.</span>
        <span class="text-black group-hover:underline decoration-black">directory</span>
      </code>
    <% end %>
  </h2>

  <div class="inline-flex items-center gap-2"> <!-- [tl! remove] -->
  <div class="ml-auto inline-flex items-center gap-2"> <!-- [tl! add] -->

The result speaks for itself:

See the Pen responsive design tip: flex-wrap (after) by Stephen Margheim (@smargh) on CodePen.

Let’s break down the changes precisely:

Add flex-wrap gap-y-2 to the <header> flex container
Add whitespace-nowrap to the <h2> containing the website title/logo
Add ml-auto to the <div> containing the user info

The first change is the most important. By adding flex-wrap to the flex container, we allow the children to wrap to the next line when the container is too small. This is a simple change that can make a big difference in the responsiveness of your UI.

Next, we simply manage the wrapping more elegantly. We tell the website title/logo to not wrap its text with whitespace-nowrap, and we tell the user info to always sit to the right with ml-auto.

All combined, we get a much more pleasant mobile experience. I hope this tip helps you as much as it has helped me. Happy coding!

sqlite.directory updates

2024-12-11T00:00:00+00:00

After the initial launch of sqlite.directory, I have been working on a few updates to the site. Here are some of the updates:

Show count of apps (59ba725)
Show favicon of app (d89dfbe)
Randomize the order of app entries (d703bf9)
Validate that even the optional Repository URL is a valid URL (15ad911
Make the application more responsive (07a5a3d, ea01025, e370f9d, daed3ab, 5568fdd, 93c5c43, and 3b8cf5e)
Update the PWA manifest to improve colors, description, and quick actions (31422f6)

As of writing this (December 11, 2024 at 1:30 PM CET) there are 17 applications listed on the site. I am excited to see the site grow and to see more applications listed on the site. If you have a project that uses SQLite, please consider adding it to the site. You can do so by visiting sqlite.directory and clicking the “Add entry” button. I am looking forward to seeing your project listed on the site!

Select dropdown for polymorphic associations

2024-12-10T00:00:00+00:00

When building a CRUD-oriented web application with Ruby on Rails, most things are pretty straightforward. Your tables, models, controllers, and views all naturally align, and you can lean on the Rails scaffolds. One gap, however, is dealing with polymorphic associations in your forms. Let’s explore how global IDs can provide us with a simple solution.

For this blog post, let’s consider building an app that has Posts that have polymorphic content, where a post’s content can be either an Article or a Video.

We can scaffold such a resource with the Rails CLI:

bin/rails generate scaffold Post title:string! content:belongs_to{polymorphic}

This command will create a migration file like this:

class CreatePosts < ActiveRecord::Migration[8.0]
  def change
    create_table :posts do |t|
      t.string :title, null: false
      t.belongs_to :content, polymorphic: true, null: false

      t.timestamps
    end
  end
end

And a model file like this:

class Post < ApplicationRecord
  belongs_to :content, polymorphic: true
end

These both look great, and are how you should build polymorphic associations. The issue arises when we view the scaffolded _form partial:

<%= form_with(model: post) do |form| %>
  <% if post.errors.any? %>
    <div style="color: red">
      <h2><%= pluralize(post.errors.count, "error") %> prohibited this post from being saved:</h2>

      <ul>
        <% post.errors.each do |error| %>
          <li><%= error.full_message %></li>
        <% end %>
      </ul>
    </div>
  <% end %>

  <div>
    <%= form.label :title, style: "display: block" %>
    <%= form.text_field :title %>
  </div>

  <div> <!-- [tl! highlight:3] -->
    <%= form.label :content_id, style: "display: block" %>
    <%= form.text_field :content_id %>
  </div>

  <div>
    <%= form.submit %>
  </div>
<% end %>

This form is not production-ready. We should never ask users to enter table IDs into forms. Were this a simple belongs_to association, I would always reach first for a form.collection_select and replace this text_field with something like:

<div>
  <%= form.label :content_id, style: "display: block" %>
  <%= form.collection_select(:content_id, Content.all, :id, :public_name, prompt: true) %>
</div>

With a polymorphic association like we have, however, this won’t work because we don’t have a single Content model. Yes, we could potentially reach for delegated types instead of a polymorphic association, but sometimes a straight polymorphic association is what is best for the database schema. So, how can we build a simple yet elegant form experience for a polymorphic association?

I won’t bury the lede; my answer is to reach for global IDs. Let me explain why. Simple means no (or very few) moving parts. I don’t want two dependent <select>s, where the user first selects the type and then the second select only shows the subset of options that are of that type; that requires Javascript and that shouldn’t be a requirement for a simple default. Elegant means easy to use and straightforward to build. Having one form field and a diff of no more than 10 lines of code is a good rule of thumb for elegance in this scenario. A solution built on top of global IDs allow me to build a simple and elegant solution.

Let’s start with the form field. Instead of two dependent <select>s, let’s build a single <select> with grouped options. This allows the user to clearly see that this is a polymorphic association as well as which type each option is. Here is the example of a grouped select from the MDN docs on optgroup:

Choose a dinosaur:

Our list of options are grouped with non-selectable headers. Rails has a companion form helper for building such <select>s with the grouped_collection_select helper, which requires passing a single collection that can be nested via getter methods. The example in the docs are continents that have many countries each of which has many cities, so you can do form.grouped_collection_select(:country_id, @continents, :countries, :name, :id, :name). With our polymorphic association, we can’t easy get a single collection of all possible content values, so instead of using grouped_collection_select, we can drop down and use grouped_options_for_select helper instead with our class form.select

<div>
  <%= form.label :content_gid, style: "display: block" %>
  <%= form.select(:content_gid,
        grouped_options_for_select(
          [
            [ 'Articles',
              Article
                .order(:title)
                .map { |it| [it.title, it.to_gid.to_s] } ],
            [ 'Videos',
              Video
                .order(:title)
                .map { |it| [it.title, it.to_gid.to_s] } ]
          ]
        )) %>
</div>

Here we build up our grouped options and pass that as the choices to the form.select helper. Our grouped options is a basic array of arrays, where each top-level array is a group. A group has first a string heading and then an inner array of choice tuples. This is where we turn to global IDs. A choice tuple takes a label and then a value. The label is what is shown to users and the value is what is sent back to the server. Our values need to encode both the id and the type of this particular choice for the post’s content. And this is precisely what global IDs provide us. As the globalid docs state:

A Global ID is an app wide URI that uniquely identifies a model instance:
gid://YourApp/Some::Model/id
This is helpful when you need a single identifier to reference different classes of objects.

By encoding both the class name and the ID, global IDs provide all of the information we need to set our polymorphic association. All we need is a new accessor on our model to get and set our association via global IDs:

class Post < ApplicationRecord
  belongs_to :content, polymorphic: true

  def content_gid
    content&.to_gid
  end

  def content_gid=(gid)
    self.content = GlobalID::Locator.locate gid
  end
end

Easy enough! In addition to our Post#content_id accessor we add a Post#content_gid accessor whose getter returns the associated content’s global ID and whose setter takes a global ID and uses it to set the full content association.

So, instead of using a flat collection of choices in a <select> for a standard belongs_to association via the content_id field, when I am working with a polymorphic association I reach for a grouped collection of choices via the content_gid field.

If you want to ensure that every ActiveRecord model with a polymorphic belongs_to association has this *_gid accessor, you can add the following initializer to your Rails app:

# config/initializers/polymorphic_belongs_to_gid.rb
ActiveSupport.on_load(:active_record) do
  module_parent.const_get('Associations::Builder::BelongsTo').class_eval do
    def self.define_accessors(model, reflection)
      super

      return unless reflection.polymorphic?

      mixin = model.generated_association_methods
      name = reflection.name

      mixin.class_eval <<-CODE, __FILE__, __LINE__ + 1
        def #{name}_gid
          public_send(:#{name})&.to_gid
        end

        def #{name}_gid=(global_id)
          value = GlobalID::Locator.locate global_id
          association(:#{name}).writer(value)
        end
      CODE
    end
  end
end

This patches Active Record’s association builder to additionally define the *_gid accessors for polymorphic belongs_to associations. This way, you can always reach for *_gid accessors when working with polymorphic associations.

Update (11-12-2024)

A number of people chimed in to point out the using signed global IDs would prevent the potential for client-side tampering. This is a great point and a worthy tweak. The code doesn’t get notably more complicated, but the functionality does get notably more secure. So, let’s update our setup to use signed global IDs instead of plaintext global IDs.

First, our methods (whether manually added or generated via an initializer) should read and write signed global IDs:

class Post < ApplicationRecord
  belongs_to :content, polymorphic: true

  def content_gid
    content&.to_sgid(for: :polymorphic_association, expires_in: nil)
  end

  def content_gid=(gid)
    self.content = GlobalID::Locator.locate_signed(gid, for: :polymorphic_association)
  end
end

Here we change .to_gid to .to_sgid (an alias for .to_signed_global_id) and pass both an expiration and a purpose. We don’t want this signed global ID to expire, so we pass expires_in: nil (default is that they expire in 1 month). The purpose is a string that helps ensure that the signed global ID is only used for this one intended purpose. This is a security feature that helps prevent signed global IDs from being used in unintended ways. Next, we change GlobalID::Locator.locate to GlobalID::Locator.locate_signed and pass the same purpose.

Our form now needs to use the signed global ID as the value in the <option>s. And this is a great opportunity to clean up our form code a bit. The current version is a bit verbose:

<div>
  <%= form.label :content_gid, style: "display: block" %>
  <%= form.select(:content_gid,
        grouped_options_for_select(
          [
            [ 'Articles',
              Article
                .order(:title)
                .map { |it| [it.title, it.to_gid.to_s] } ],
            [ 'Videos',
              Video
                .order(:title)
                .map { |it| [it.title, it.to_gid.to_s] } ]
          ]
        )) %>
</div>

And, it doesn’t enforce that the different possible content models need to adhere to a shared interface. So, let’s create a model concern that we can include into all “contentable” models to define and implement the needed interface:

# app/models/concerns/contentable.rb
module Contentable
  extend ActiveSupport::Concern

  class_methods do
    def to_options
      ordered.map { |it| [it.public_name, it.to_sgid(for: :polymorphic_association, expires_in: nil)] }
    end
  end

  included do
    scope :ordered, -> { order(**public_order) }
  end

  def public_name
    raise NotImplementedError
  end

  def public_order
    raise NotImplementedError
  end
end

Now, we could use this Contentable concern in our Image and Video models. For example, like this:

class Article < ApplicationRecord
  include Contentable

  def public_name = title
  def public_order = { title: :asc }
end

By defining and implementing the interface that the models that can be used in the polymorphic content association need to adhere to, we can now simplify our form code:

<div>
  <%= form.label :content_gid, style: "display: block" %>
  <%= form.select(:content_gid,
        grouped_options_for_select(
          [
            [ 'Articles',
              Article.to_options ],
            [ 'Videos',
              Video.to_options ]
          ]
        )) %>
</div>

All together, these are solid improvements that make our implementation both more secure and more maintainable.

Thanks for the great feedback and for making this code even better!

Fractaled Mind

Writing Tailwind-compatible Semantic CSS

What’s Wrong

My Approach

@utility gives you tree-shaking and autocomplete

A prefix like ui- makes affordances obvious

:where() gives you zero specificity

@variant gives you readable state styles

@apply makes compatibility a non-issue

2025 in review

Becoming a Family

The Career Arc

High Leverage Rails

Open Source

My Ruby Triathlon

Staying Connected

Writing

Life in Berlin

By the Numbers

Travel

Writing

Speaking

Open Source

What I Learned

Looking Ahead

Dialog Animation Gotchas

Stylish <dialog>s

The HTML

Semantic Elements

The Form Wrapper

Two Close Mechanisms

Focus Handling

Light Dismiss

Accessibility

The CSS Architecture

The Base Dialog Utility

The Visibility Problem

Sizing Constraints

Stacking Context

Why focus Instead of focus-visible

Slot Classes and Semantic Selectors

Animations

Asymmetric Motion

Timing Differences

The Technical Details

Button Styles

Browser Support

Interactive Demo

What’s Next

Confirmation dialogs with zero JavaScript

Adding Animations with @starting-style

Browser Support

Integrating with Turbo’s Confirm System

Addendum: Preventing Background Scroll

Appendix: Interactive Demo

Affordances: The Missing Layer in Frontend Architecture

Three Things, One Name

Unnecessary Pain

“We Tried That. It Didn’t Work.”

In Practice

A Call to Library Authors

The Way Forward

CSS-only Star Rating Component with Half Steps

Always use flex-wrap: wrap on flex containers

sqlite.directory updates

Select dropdown for polymorphic associations

`@utility` gives you tree-shaking and autocomplete

A prefix like `ui-` makes affordances obvious

`:where()` gives you zero specificity

`@variant` gives you readable state styles

`@apply` makes compatibility a non-issue

Why `focus` Instead of `focus-visible`

Adding Animations with `@starting-style`