A Theme Explorer for Docs and Platform

What problem existed?

We wanted to explore what our Docs and platform would feel like carrying more of the brand’s visual language. The usual way to do that is by hand: pick a color direction, a type pairing, a light or dark ground, and rebuild each across a set of representative screens in Figma to see how it holds up.

Why did it matter?

When exploration is slow, you commit early and compare few options, and marketing, design, and engineering each react to different static mockups instead of one live thing. Branding and design-system directions get locked in before the team has seen enough alternatives side by side.

A faster loop changes the conversation. If the group can try many directions together, in minutes, on real components and real screens, alignment comes from reacting to the same live artifact rather than imagining how a Figma mockup would behave in the product.

What constraints existed?

The work was exploratory by design, and it built on inputs that already existed:

• The output is a sandbox to react to and align in, not a spec to build against.
• It draws on our team’s UI kit, the marketing site’s brand language, and its tokens.
• It had to be built the way the marketing site’s library is built (a token-driven CSS cascade with HTML partials, no runtime framework), so the front-end team already understood the structure.
• Light and dark, with every color pair passing WCAG AA, for any theme the explorer can produce.
• Cover the foundational primitives and a few recreated screens; defer the data-heavy and domain components.

What role did I play?

This was a team effort with clear ownership. Our head of design and head of marketing created the UI kit and brand language the explorer draws from. I built the explorer, and I started where that language already lived in code: the marketing site’s own repo, where the design system is a strict, four-layer, token-driven CSS library with no runtime framework.

I derived a new, self-contained token layer from the marketing site’s tokens and translated it into a themeable set, light and dark, with every value validated against WCAG AA. I mapped that color and type model onto the UI kit so it stayed true to the kit, then mapped each component to its counterpart in the production library for a 1:1 front-end reference. From there I wired the theme builder, built the components across every state, and recreated a set of product and docs screens to react to.

The build is a designer-owned prototype, not production code. The theme builder emits each selection as CSS custom properties the four-layer library reads, so the same tokens the front-end team consumes drive every component. The front-end team reviews it and owns any port into the real codebase.

What options were explored?

The explorer is itself a tool for exploring options, which is the point. Instead of testing modalities and colors by hand, we test them live:

• Color and type. The theme builder swaps primary and secondary color and the type pairing from the top bar. Every component and screen re-themes at once, and the choice carries across pages.
• Light or dark. The same components render in either mode, so a direction can be judged in both without rebuilding it.
• Density and data-viz. A few extra tokens extend the kit for denser data display, derived the same way as the kit’s core palette.

Building it this way, rather than in Figma or a framework workshop, kept it fast to change and legible to the front-end team.

What tradeoffs were considered?

The main tradeoff was a sandbox versus a spec. Keeping it a sandbox let us try throwaway directions without the weight of a system anyone had to build against yet. The cost is that nothing here is final; once the group aligns, a direction still has to be hardened into the production system.

The second was a coded explorer versus exploring in Figma, where this work usually happens and everyone knows the tool. Building it in code took more setup, but it made every option real, themeable, and instantly comparable in light and dark, which Figma mockups cannot be.

How did UX, engineering feasibility, and business strategy intersect?

The theme builder is where they met. Marketing owns the brand, design owns the system, and engineering owns what ships, and the explorer put all three in front of the same live artifact. Whether a brand color reads well is a marketing call; whether it passes contrast in light and dark is a design and accessibility call; whether it maps cleanly to a production token is an engineering call.

The components make that concrete. Rather than invent new patterns, the explorer carries over the ones the product already uses, buttons, inputs, and tables, shown across every state and mapped one to one to their production counterparts. Every theme it can produce is also checked against WCAG AA in both modes, so no one aligns on a direction that looks good but fails in the product.

How was AI used in the process?

AI is what made the fast loop possible for one designer. It helped translate the UI kit into tokens, generate the component CSS and markup across every state, recreate the example screens, wire the theme builder, and stand up an accessibility check that audits every color pair in both themes.

The hardest moment was the token translation, taking a dark-only source and deriving a themeable set that holds contrast in both modes.

Take the marketing site's dark-only token file and derive a
themeable version: a light mode and a dark mode that maps back to
the current palette. Keep every value a token, derive tints with
color-mix() instead of re-picking hex, and hold the accent green
to status only so it stays meaningful. Then check every
foreground/background pair against WCAG AA in both modes and list
any that fail, with a suggested fix.

The other was tying the explorer back to what ships, so the front-end team gets a clean reference to port from rather than a fresh interpretation.

Audit the production component library. For each primitive in this
explorer (button, input, select, table, tabs, dialog), name the
production component it maps to and the props that would carry
over. Output a table I can drop into the status board, and cite
the files so the front-end team can read them.

Together, that is the work that used to take weeks of hand-building. AI compressed it enough that we could spend our time exploring directions instead of building the scaffolding to explore them.

What was learned?

The interesting result was the workflow, not any single theme. When trying a direction drops from weeks to minutes, exploration stops being a scarce, high-stakes step and becomes something the team can do together, live, as often as it wants. That changes who gets to weigh in, and when.

It also points at a model for how design, brand, and engineering collaborate on a design system: the three groups share one live artifact that each can push on from its own angle, instead of trading static files back and forth. The kit came from design and marketing; the explorer let all three react to it together.

What was the outcome?

A dark-launched theme explorer, shared internally as a sandbox, not a public release:

• A live theme builder that swaps primary and secondary color and the type pairing, in light or dark, with every component and screen re-theming at once and the choice carried across pages.
• About two dozen foundational primitives, each in every state, plus a set of recreated screens themed live.
• An automated WCAG AA audit that passes clean in both modes, so every theme the explorer offers is accessible by construction.
• A four-layer structure mirroring the marketing site’s library, each component mapped to its production counterpart for the front-end team to port.

As a sandbox, it gave design, brand, and engineering a fast, shared place to try directions and align before anyone commits to a spec.