Duke Energy - One design system for design, code, and spec

Thesis: A Figma library would have failed Duke. The org was adopting React and spec-driven development at once, so the system couldn't be a handoff artifact. It had to be the one source of truth for design, code, and spec.

For the reader: If you're hiring a design-systems lead who runs the system as a product, with a deliberate starting point, a governance model, and consumers beyond designers, this one's for you.

01Project Overview & Context

The hook

Duke Energy's internal applications ran on a design system that had quietly died. It was outdated and unmaintained, and teams had stopped trusting it. So every product team was drifting back into one-off patterns, and every handoff to engineering turned into a negotiation.

At the same time, the org was making two big bets: migrating its internal application stack to React, and adopting spec-driven development (OpenSpec) as the way requirements flow to engineering. That included AI-assisted workflows that consume specs directly.

That changed the brief. I had to build one definition of the interface that design, code, and spec could all consume, and put enough governance around it that it wouldn't rot like the last one. A nicer component library wasn't the job.

My role

Lead Designer on the design system. I built it with a small, deliberate team:

• 1 associate designer
• 1 senior engineer

I owned the system's architecture and starting point, the design language and theming, the component decisions, the documentation, and the governance model for how teams request and contribute changes.

Timeline & tools

Timeframe: Roughly one year.

Stack: shadcn/ui as the foundation, React as the delivery target, OpenSpec for spec-driven definitions, Supernova for the published documentation, Figma for the design surface.

02The Problem Statement

The challenge

The old system didn't fail because of bad components. It failed from neglect. Nobody clearly owned it, there was no process for change, and engineers had no reason to use it, so they didn't. Design artifacts and shipped code drifted apart, and the system turned into a record of what the product used to look like.

Meanwhile the React migration meant every internal team was about to rebuild UI anyway. That was the window: give them a system worth adopting at exactly the moment they had to choose one, or watch a dozen teams invent a dozen new patterns.

Objectives

• Replace the unmaintained system with one teams would actually adopt
• Anchor the system in code, so design, spec, and shipped UI share one definition
• Make sanctioned patterns easier to use than one-off drift
• Put a lightweight governance model around change from day one
• Publish documentation as a real product surface, not scattered notes

03Process & Methodology

Design decisions (the why)

Start from shadcn/ui instead of building from scratch. The alternative was designing and building every component and primitive in-house. But Duke isn't in the business of building design systems from scratch. shadcn got us roughly 60% of the way there on accessible, composable React primitives, so the team spent its effort on Duke-specific patterns, theming, and governance. Nobody had to reinvent a button.

Build one source of truth for design, code, and spec instead of a Figma library. The alternative was the classic move: ship a polished Figma library and hand it to engineering. But Duke was adopting React and spec-driven (OpenSpec) development at the same time. A design-only library breaks at handoff, and it can't feed spec or agent workflows. So I anchored the system in code and derived design and docs from it. That way design, code, and spec all read from one definition.

Put a governance model around change requests from day one. The alternatives were a free-for-all contribution model or locking the system to the core team. The previous system died from neglect, with no clear owner and no process. A lightweight, explicit path to request and review changes keeps the system alive and coherent. It can evolve without splintering back into drift.

Author the documentation in Supernova as the published surface. The alternative was usage notes in Figma comments or scattered Confluence pages. If the system is the source of truth, its docs have to be a real product surface: discoverable, versioned, and tied to tokens and components. Supernova let design and code docs live together as the canonical reference.

AI in the system-building loop

A three-person team building a system for a whole org only works if you multiply yourself. I used AI as a collaborator on the system the whole way through. Not to generate designs. To do the rigorous, repetitive work design systems live or die on:

• Consistent token naming. Naming is where design systems rot first. I used AI to build and stress-test the token vocabulary (semantic role names instead of raw values) and to sweep for the drift that creeps in at scale: near-duplicate tokens, inconsistent aliasing, and names that broke the pattern, before any of it could spread into Figma and code.
• Token-to-component mapping. Every component property had to resolve to a semantic token, in both the Figma library and the React implementation. AI audited components against the token set and flagged hardcoded values and unmapped properties. That kept the two surfaces on one vocabulary, right at the seam the system existed to close.
• WCAG color accessibility. As the palette evolved, AI checked contrast pairs against WCAG AA. That meant every text-on-surface combination in the theme, not just the obvious button cases. Accessibility became part of the token set itself, so teams building from sanctioned tokens inherit passing contrast instead of re-testing it on every screen.
• Figma library audits. AI-assisted passes over the Figma library caught the hygiene problems that make people stop trusting a system: layer-naming drift, variant structures that didn't match their code props, and stray hard-coded styles where a token binding belonged.

AI didn't design the system. It made a small team's system auditable. Every convention could be checked continuously instead of decaying between manual reviews.

04The Final Solution

A design system for Duke's internal applications, anchored in code:

• React components built on shadcn/ui that engineers pull directly. The shipped component is the sanctioned pattern, not a picture of it
• Duke-specific patterns and theming layered on accessible, composable primitives, so the team's design time went to the parts that were specific to Duke
• Spec-ready definitions that fit the org's OpenSpec workflow, so requirements, design, and implementation reference the same named parts
• Published documentation in Supernova as the canonical, versioned reference for both design and code
• A governance model with clear expectations for how to use the system and an explicit path to request and contribute changes

05Outcome & Impact

What changed

We replaced the unmaintained system with one teams actually adopted. Teams got clear expectations for how to use it, sanctioned patterns instead of one-off drift, and React components engineers could pull directly. The governance model gave them a real way to request and contribute changes, so the system stays maintained instead of rotting like the last one.

Honest accounting

There's no headline metric here, on purpose. For a design system, the win is adoption and governance: do teams use it, and is it still alive a year later? Both held. I'd rather say that plainly than dress it up with invented percentages.

Learnings - what I'd do differently

I'd invest in the governance and contribution model even earlier. We proved the system worked before teams fully knew how to request changes, and adoption only moves as fast as people trust that process.