Eclipse UI

The problem

A barre studio and a HIIT box shouldn't look the same, but in Eclipse the only thing that changed from one instance to another was the brand color. Views wrote their colors by hand: across the 17 public views there were 442 loose references to variables ([var(--color-…)]), 207 Tailwind palette classes (gray-500, white…) and 48 icons pasted in as <svg>. Changing a studio's voice or shape meant editing view by view, in every instance.

On top of that, the base brand color, a gold (#a3946b), was used as text and as a button background: it measured between 2.7 and 3.0:1, and WCAG AA asks for 4.5:1. Across five pages, axe found 58 elements with insufficient contrast.

What I needed was a system that separated two things: what every studio deserves equally and what makes each one different.

The idea: base and personality

The base is what doesn't change from one studio to another, and if a component breaks one of these guarantees, it isn't done: truly accessible (measured AA contrast, visible focus, full keyboard support, reduced motion respected); only tokens and scales, never a loose color or size; hierarchy through layers and 1 px borders, with shadows saved for what floats; physical motion; integrated with Rails (controls send their value with name:, work with Turbo and with the form builder), and code that belongs to whoever uses it, with no black boxes.

The personality is what each studio decides, in five traits:

The traits move with 27 dials that fit in one theme.css block. The engine derives the rest: the palette, the hover states, the text on the brand, the layers, the shadows, the radii and the durations. I started from six personalities designed for different kinds of studios, and each one is a starting point, not a closed theme:

Bringing one to a studio means copying its block into theme.css and moving the dials it needs. Everything else realigns on its own.

The guardians: so the base doesn't depend on memory

A system that promises AA contrast in any combination of dials can't be checked by eye. So the base has guardians that run with the tests:

• Contrast. A list of 22 text and surface pairs (config/eclipse_ui/contrast.yml) is measured in a real browser in the six personalities and in the studio's theme.css, in light and dark: 308 measurements in 0.6 s. A browser measures them because the engine derives colors with color-mix(in oklab) and oklch(from …), and reimplementing that in Ruby would be a second copy of the engine that sooner or later would say something different from the screen. If a studio picks a brand color that makes some text unreadable, the test says which one.
• Tokens. Eight rules go through every component and its CSS and fail, with file and line, if a hex shows up, a Tailwind palette color, a shadow that doesn't follow the dial, a text size in px, a rounded off the scale or a hand-written variable where there's a named utility.
• Catalog. Every component has an entry, a demo, props, an ARIA pattern and keyboard support. A piece can only say "stable" if a real view in the app uses it.

Contrast stopped being an aesthetic decision: brand-colored text uses text-primary-text, a derived tone that passes AA in every personality (5.7:1 at minimum), and the text on a brand button is picked automatically (6.0:1 on the gold).

Physics without React

Components that feel alive usually come from React libraries. Eclipse is Rails with Stimulus, so I wrote the physics from scratch: spring.js is 127 lines with no dependencies, with a fixed-step integrator (1/240 s) that behaves the same on a 60 Hz screen as on a 120 Hz one.

• Five named presets instead of durations: snappy gets within 1% of its target in 300 ms (buttons, indicators), gentle in 550 ms (tabs, dialogs) and responsive in 192 ms, with a 0.9% bounce saved for returns and toast stacks.
• It keeps its velocity. If the target changes mid-way (a drag, a magnetic button that follows the cursor), the spring doesn't restart: it keeps going from where it was. That's the difference between something that feels physical and something that feels animated.
• It obeys the studio and the person. The rhythm dial (--eui-motion) scales the time of every spring and of the CSS transitions, and with prefers-reduced-motion everything jumps to the end.

Today 34 Stimulus controllers use it: slide to book, rolling digits, tabs with a sliding pill, modals that settle, toasts you can drag away.

In the real app: the demo's public site

The real test was dressing the demo's entire public site in the components: navigation, footer, notices, confirmations, home, schedule, class, pricing, contact, sign in, sign up, account and About. The screenshots use the same database in both versions; only the code changes.

What changed in the code of the public views:

What changed in accessibility (axe 4.10, WCAG 2.1 AA, on home, schedule, class, pricing and sign in, on desktop in light mode):

The footer was the last to fall: its labels and credits used text-faint, at 3.66:1 on black, and the system itself says text-faint isn't for text that has to be read. Now they use text-muted-foreground. On the phone and in dark mode, axe still flags small labels in the schedule and the class with that same tone (from 3.4 to 4.3:1); that's the next thing to align.

From internal system to product

Eclipse UI was born inside Eclipse. For it to work outside the app, it had to stop being part of it.

• Its own repository. I split Eclipse UI from the app into its own repository, as a Rails gem (eclipse_ui). Eclipse uses it as a read-only copy that updates with one command (bin/update_eclipse_ui), and tests prevent editing it inside the app. The booking pack (class, schedule, packages, booking…) stayed in Eclipse: it's what sets it apart from other studio software.
• From documentation to product page. The public site went from documentation to a product page, under the idea "Don't let your app look AI-made". At the top, the same page switches on its own between the six personalities. The motion can be paused (WCAG 2.2.2) and doesn't start on its own if the person asks for reduced motion. Below are still the catalog, System and Personalities: a static export with the demos working without a server, which doesn't publish the components' code, only how to use them.
• Outside Rails. From the site you can download for free, with no account: the engine in a single CSS file (eclipse-ui.css) and, for each personality, its theme.css, its shadcn.css and its DESIGN.md.
• The shadcn.css is measured. It carries shadcn/ui's values measured in a real browser on top of the engine and converted to OKLCH. The reason is the same as with contrast: measure what the screen paints instead of reimplementing the engine.
• The DESIGN.md is for the AI. It's a set of instructions for an AI agent (Claude Code, Cursor) to apply the personality on every screen: which tokens to use, which rules to follow and what would make the app look AI-made.

What I learned

• Naming the traits was more useful than adding dials. With "voice, shape, color, air and rhythm", a studio owner can say what they want to change without talking about CSS, and every request lands on a specific dial.
• A guardian is worth more than a rule in a document. The token and contrast rules run with the tests: a component that breaks them doesn't pass, whether a person or an AI wrote it.
• The guide is for the AI too. The same guide (docs/GUI.md) and a set of instructions for the agent that writes the UI make new code come out with tokens, physics and accessibility from the start.
• An internal design system becomes a product when it works outside its app. And today, the people who most need a design personality are the ones building with AI.

What's next: bring the studio dashboard (what the owner uses every day) to Eclipse UI and test in real Safari and Firefox.

How it was measured: the screenshots and axe 4.10.3 ran in Chromium with Playwright, at 1440 × 900 and 390 × 844, against Eclipse's commit 99cdd64 (before Eclipse UI) and against main, with the same database. The code count runs the Ui::Guardrails rules over the same public views in both commits (17 files before; 19 after, because two partials came out of them). The spring timings simulate spring.js with its own integrator and a 100 px travel.

Related

• Eclipse case study →
• How I build →