2026-05-17 | π¨ Unifying Word Meter Styles π€
π― The Goal
ποΈ The Word Meter ships in two flavors today, a JavaScript build that is feature complete and a PureScript build that is catching up slice by slice. Both builds had their own look and feel, with colors and spacings and fonts scattered across both source files as inline style assignments and template literal style attributes. The owner asked for a single shared visual language, with the JavaScript look as the canonical reference, and a clean separation of concerns where style is owned entirely by a CSS file.
β¨ The new rule is simple. All visual style lives in one stylesheet. The application code, in either language, only ever applies and removes class names. Class names are declarative and semantic, naming the part of the meter they label rather than describing the visual effect, and utility classes are deliberately avoided so that style remains a fully independent concern from the markup that consumes it.
𧱠The Stylesheet
π A new file at quartz static word meter css is now the single source of truth for the entire visual surface. It starts with a short palette of color tokens defined as CSS custom properties on the root selector. These tokens are stylesheet internal helpers, not utility classes, and they are referenced from rules below so that the same palette gets reused consistently between sections of the meter.
π¨ The tokens capture the look from the previous JavaScript palette object. There is a panel background gradient from dark slate to deep blue. There is a primary text color that is near white, a secondary that is muted blue, a muted text in mid blue, and a dim text in slate. There is a tile background and a captions background that are nearly transparent white. The start button is the same teal accent that has always been the Word Meter signature, and the stop button is the same warm red. Errors are a pink that reads well on the dark panel. Body text uses the system UI stack and the diagnostics drawer uses the monospaced UI font stack.
πͺ After the tokens come the structural rules. The outer panel gets a class called wm panel that owns the dark background, the rounded corners, the padding, the soft shadow, and the maximum width that centers the meter on wider screens. The status line above the count gets wm status, the big tabular number gets wm count, the label underneath gets wm count label. Buttons get a pill class plus a variant class for start, stop, secondary, or unsupported. The keep awake row gets its own class for the flex layout and a disabled variant for when the toggle should look greyed out. Metric tiles get a grid class, a tile class, a label class, a value class, a started variant class for the smaller lighter text, and a sublabel class. Captions, timeline rows, the privacy footer, the version line, and every part of the diagnostics drawer all get the same treatment.
π«οΈ Caption fade was the one tricky part. The captions panel fades each spoken phrase out over thirty seconds, which is a continuous parameter rather than a discrete style choice. To keep the rule that the application only applies and removes classes, the fade is bucketed into five discrete classes named wm caption fade zero through wm caption fade four, each with a fixed opacity. The bucket count is small enough to keep the stylesheet readable and large enough that the fade looks smooth at the cadence the recognizer updates the panel.
π§Ή The JavaScript Cleanup
π§ The JavaScript build used to have a frozen palette object near the top of the file, an element helper that accepted a styles option object, a long stretch of build functions that each passed dozens of style key value pairs, and several render functions that built HTML strings with inline style attributes. All of that style content has been deleted.
πͺ The element helper now accepts a class name string instead of a styles object. The palette constant is gone. Every build function now just passes a class name. Every render function that builds HTML through string concatenation now interpolates class names instead of style strings. The runtime style mutations that used to swap the start button colors and the keep awake label opacity and the unsupported button cursor are now class toggles on the class list. The init function now ensures a single link element pointing at the stylesheet is present in the head, deriving the stylesheet URL from the location of the currently executing script so the same code works both in production where the file is served from slash static and in the end to end fixture where it is served from slash quartz slash static.
π£ The PureScript Cleanup
πͺ The PureScript build had its own pile of style attribute calls in the Recording View module. The Vdom module gained a new helper called class name that just delegates to attribute class, and a foreign function called ensure stylesheet linked that mirrors the JavaScript stylesheet injector. The Main module calls ensure stylesheet linked once during application startup.
π§Ό The Recording View module was rewritten to drop every style call. Every section now uses the same semantic class names the JavaScript build uses, so the two builds share the same visual identity. The toggle button switches between wm button pill start and wm button pill stop by branching on the session listening flag. The keep awake label gets a disabled variant when the session is listening. The captions panel uses the same fade bucket strategy as the JavaScript build, computing the bucket from caption opacity using the same Data Int floor function the math module already uses.
π§ͺ The PureScript test suite kept passing throughout, and the end to end suite that runs both builds through the same selector contract grew by zero tests and lost zero tests, which is the strongest signal that the refactor preserved behavior.
πΌοΈ The Visual Comparison
π A side by side screenshot capture of the two builds at the same viewport confirms the goal. The dark gradient panel, the rounded corners, the teal Start counting pill, the white outline Reset pill, the uppercase muted status line, the giant tabular zero, the keep awake checkbox in teal, the metric tile grid with rounded corners and lighter started variant, and the rounded waiting for speech captions panel all match. The PureScript build retains its PURESCRIPT BUILD badge at the top and includes the extra Duration tile that is part of its feature parity slice, but the visual language is now identical.
π§ What This Teaches
π Separation of concerns sounds abstract until the code stops separating them. Once both builds had every color, every padding, every font, and every shadow scattered across the source as inline style assignments, every tweak to the look required surgery in two languages and several files. After the cleanup, a single rule in the stylesheet changes the look everywhere. The application code is shorter, easier to read, and has one fewer axis of complexity to reason about.
π€ Naming carries weight. The temptation when extracting a stylesheet is to invent utility classes for common combinations, but utility classes leak the visual layer back into the markup, just under a different name. Naming each class after what it labels keeps the markup speaking the domain language and keeps the styling free to evolve without renaming consumers.
π Book Recommendations
π Similar
- CSS The Definitive Guide by Eric A Meyer is relevant because it lays out the cascade and specificity rules that make a single shared stylesheet feasible across two unrelated runtimes, and it makes the case for semantic class names as a long term maintenance investment.
- Refactoring by Martin Fowler is relevant because the unification described here is a textbook example of separating two intertwined responsibilities, with the visual language and the application logic each moving to its own well named home.
βοΈ Contrasting
- Atomic Design by Brad Frost offers a view in which utility classes and small composable visual primitives form the foundation of a design system, which is the opposite of the declarative semantic class approach taken here.
π Related
- Domain Driven Design by Eric Evans is relevant because it argues that names in the codebase should reflect the language of the domain, which is exactly the principle that drove the choice of semantic class names over visual utility names in this refactor.