Introducing Anthology — a modern SCSS framework for writing styles that scale!
Hi 👋
I’d like to introduce myself just a little before diving into this On the Radar post. My name is Ian. I joined Radar last July as a full-stack engineer and I’ve been leading the charge on Radar RELAY’s major UI/UX updates. I’ll be showing off a personal project that sparked a company-wide push to implement our internal design system; a project that was kicked around long before I was a part of the team, but finally came together once I presented the ideas in this article.
Anthology — “What!?” and “Why!?” 🤷
Radar — the parent brand of RELAY— is venturing into new products and categories. We’ve spent a great deal of energy on the sweeping transition from a product-isolated brand into a singular, company-wide voice. This movement has been a long-term goal and we’ve prepared for it with long-term engineering solutions. One of our greatest challenges as a growing, multi-product company is finding consensus around design and UX — and especially how that vision is translated into code. We’ve previously discussed our approach to an open-design system, where we teased an internal SCSS framework called Anthology. Now, I’m here to present a deeper look into Anthology and how we use it to enforce the design specs and the Radar brand at a programmatic level across current and future products.
We view Anthology as a pattern with some tooling to keep things consistent. On its own, Anthology doesn’t provide any style definitions — it just forces good behavior when writing style sheets. We took inspiration from atomic CSS. The first implementation shared a lot of ideas with Tachyons. As we audited our options in the open-source community, we came to realize that our needs are quite unique and required features that didn’t exist together in the wild. Radar RELAY has particularly complex layout requirements, light/dark theming, and over 115 unique Vue components to form its retail experience. In addition to planning for the next big thing, we had to support Radar RELAY’s front end rewrite in an incremental way.
We set a few design goals for ourselves:
- Anthology-generated selectors should be purely declarative and decoupled from markup structure.
- Selectors should target just one CSS property.
- Writing CSS sucks, so the developer should write less of it.
Before we unpack these design goals, it helps to have context around what Anthology does internally. In the simplest terms, Anthology takes a CSS property like display and creates single-responsibility class selectors for its well-known properties. In your markup, you might use it like this:
Simple enough… just like Tachyons so far! Anthology has a few super powers as well, like theming, pseudo-targets, and mobile-first responsiveness. And what CSS framework is complete without a grid system!? Anthology is highly configurable to suit your specific use-case. I encourage you to read the Getting Started section of Anthology’s documentation to learn more about its features and usage.
Prototyping at the Speed of Plaid 🚀
The beta release of Radar’s latest product —ION— was fully realized using Vue and Anthology just days after design specs were finalized. We owe this speed to our continuous experimentation with features of RELAY, which we’ve iterated using Anthology since last September. In the intervening time, we’ve re-implemented most of RELAY’s front end application. This is happening alongside a company-wide rebrand and expansion into new products and categories. The point is: we are moving faster than ever before. Anthology is a key reason why.
Our design team has seen a similar improvement in output thanks to Anthology. As a team, we have coalesced around a shared design language, right down to the vocabulary we use to describe colors and measurements — we’ve configured Anthology to enforce these practices at a code level.
Thus, “Give me a small margin around this element” is codified by the style sheet.
Small, medium, and large are no longer ambiguous terms between designer and developer, they are associated with CSS selectors like .margin-small, .margin-medium, and .margin-large, they now also have flexibility across screen sizes.
“Give me small margin on mobile, up to a large margin on desktop.”
Using Anthology’s responsive features, we use combination of selectors like so: .margin-small .margin-large-@desktop. Theming is similarly possible. Imagine this: .backgroundColor-light .backgroundColor-dark-#night.
Pixel-perfect designs are possible with minimal CSS, highly-expressive markup, and none of the usual back-and-forth between design and engineering teams. Best of all, common properties can be centralized and shared across projects. For us, this means ION looks distinctively like a Radar product with almost none of the usual boilerplate in its style sheet. Additionally, if we decide to change a hex-code in the future, existing implementations will adapt seamlessly — it’ll just work!
Creating Anthology Rules (easy as 🥧)
Anthology is a blank slate until you give it some rules. You’re still writing SCSS, but the emphasis turns to configuration. A simple rule definition looks like this:
Anthology takes care of generating CSS selectors for each “adjective” mapped to the CSS property margin-right. If we’ve configured responsive breakpoints, themes, or pseudo-targets, then those selectors will be generated, too.
Another important mixin is A(extend, ...), which enables other parts of our style sheet to make use of Anthology rules.
This brings all the benefits of Anthology’s feature-set to object-oriented CSS as well. Using these paradigms together is very powerful indeed! Your style sheets can be lighter, too, as margin-right is defined in one place only.
Anthology Plays Nice With Your Scripts 👨💻
As creators, sometimes we need to break the rules. HTML, CSS, and JavaScript traditionally separate hierarchy, design, and behavior into isolated concerns—this is unarguably a good practice, but web engineering is changing. Component-based frameworks like Vue and React blur the lines between the button and the click (don’t believe me? See the meteoric rise of CSS in JS libraries like styled-components… also JSX). Anthology makes it easy to work within edge cases where your scripts need to solve design problems that HTML + CSS simply cannot handle alone.
Anthology provides a JavaScript API that is designed to utilize CSS values from within Anthology-generated style sheets.
In just a few steps, you can access a high-level interface to your style sheet:
😮 Super clean!
The function signatures are 1:1 with the SCSS API, so you can grab the value from a specific breakpoint, theme, or pseudo-target as well.
Learn Anthology 💪
Anthology is big. Way bigger than we initially thought it would be.
We set out to build a library with a high degree of flexibility and a low barrier to entry. The API is expansive, full of shortcuts, corner cases, and advanced concepts. Getting started is the easy part, but this short introduction is only the appetizer. The next step is to read the docs and build something yourself! If you’re feeling generous (and adventurous), you can show the project some love by contributing code examples.
At Radar, we believe in an open financial system and we rely on open-source projects to get there. We want UX in the dApp space to evolve and Radar to evolve with it. That’s why Anthology is freely available and MIT-licensed. We encourage any level of community contribution, from general feedback to opening issues, new features, bug fixes, and more! Fork it or bootstrap yourself with our boilerplate repository.
