Organize CSS variables in two-tiered design tokens

[lokesh]

Problem / Opportunity

DRY up our design variables and reduce magic numbers for values. This will help with consistency and make design updates much simpler.

Proposal

Use a common design tokens pattern, which uses two-layers for organizing variables.

Primitives (raw values) A small, curated set of base values that work well together. Constraining the palette ensures visual harmony and prevents arbitrary values from creeping into the system. ↓ Semantic Tokens (design intent) These map design intent to specific primitives. They’re referenced throughout the app, and their names communicate where they should be used. This provides a single point of control for updating categories of components.

As an example, if we wanted to increased the border radius of larger components, this becomes trivial: change @radius-card from @radius-lg to @radius-xl, and all card-like components update consistently. Do the same for @radius-container etc.

// PRIMITIVES FOR RADIUS
// Border radius design tokens
@radius-sm: 2px;
@radius-md: 4px;
@radius-lg: 8px;
@radius-xl: 16px;
@radius-xxl: 32px;
@radius-full: 100%;

// SEMANTIC RADIUS VARIABLES
@radius-button: @radius-md;       // buttons, tabs, pills
@radius-input: @radius-md;        // inputs, textareas
@radius-card: @radius-lg;         // cards, panels
@radius-container: @radius-lg;    // containers, wrappers
@radius-overlay: @radius-xl;      // dialogs, modals

Breakdown

Requirements Checklist

Create tokens for...

• [ ] colors
• [x] font families - PR
• [ ] font sizes and weights
• [ ] line heights
• [x] border radius - PR
• [ ] spacing
• [ ] borders

Utilize tokens in existing LESS files...

• [ ] colors
• [x] font families - PR
• [ ] font sizes and weights
• [ ] line heights
• [ ] border radius
• [ ] spacing
• [ ] borders

Create individual PRs for each task.

Stakeholders

@lokesh @cdrini @mekarpeles @jimchamp @RayBB

---

Instructions for Contributors

• Before creating a new branch or pushing up changes to a PR, please first run these commands to ensure your repository is up to date, as the pre-commit bot may add commits to your PRs upstream.

[rrrr08]

I have made the feature as you requested. I have not added the docs for them. If needed I can add them. Please review the changes and tell me if any further improvement is needed.

Thank you.

[G-Sham]

Hi @lokesh!

While the token definitions are being finalized in PR #11558, I would like to sign up for the 'Utilize tokens' phase to help speed things up.

Specifically, I can work on refactoring the existing LESS files to use the new Spacing tokens once the definitions are merged.

May I claim the Utilize tokens... > spacing checkbox?

[lokesh]

@G-Sham Let me get a couple more design token categories defined tomorrow and then I'll ping you with some examples on how I think they could be utilized and any gotchas. You can then pick one category to tackle if you're interested. Thanks for offering to help!

[G-Sham]

Thanks @lokesh! That sounds great. ​I'm ready to pick up a category whenever you have the definitions ready. Standing by!

[lokesh]

@G-Sham Here’s the PR that defines the border variables: https://github.com/internetarchive/openlibrary/pull/11602

It includes a couple usage examples where hardcoded border values are replaced with the new variables. Next step: we should skim through the app and swap in these variables anywhere we can do so without large visual changes, small border color shifts are expected as things get normalized.

I expect we’ll still need additional border variables to cover all existing patterns, so as you review, please note any gaps you run into and we can follow up. Happy to chat through anything that’s unclear.

[G-Sham]

Thanks @lokesh! I will review PR #11602 to understand the new variables. I'll start by skimming the LESS files to find hardcoded border values and swapping them out. I'll make a list of any gaps as I go.