Staff-level UI engineering

A shared component carries decisions into every product that uses it. Staff and Principal UI engineering expands that responsibility to the platform: its APIs, accessibility, releases, and the teams depending on them.

This guide examines Staff-level UI engineering for design systems and shared UI platforms. It connects browser technology and component architecture to package distribution, developer experience, and adoption. Use it to understand the scope of the work, review a role, or identify where your own practice needs to grow.

Anything here that’s a matter of record is footnoted to a primary source. Anything that’s judgment is mine, stated plainly. One caveat: Senior, Staff, and Principal aren’t standardized titles. Monzo says so directly, and GitLab’s frameworks differ from everyone else’s.¹²³ Read every level description below as one company’s answer.

What the job is

Published career frameworks show what actually changes at each level. GitLab separates Senior, Staff, and Principal individual-contributor levels, with broader technical and organizational scope at each step.⁴²³

Its Staff framework describes Staff engineers as technical leaders for a domain: owning tradeoffs and architecture, removing blockers, decomposing complex requirements, and blending technical, product, and design concerns for longer-term impact.² The Staff Frontend framework adds delivering despite unclear requirements, leading large architectural changes, improving standards and tooling, mentoring, and influencing frontend quality beyond your own tasks.⁵ Principal scope is broader still: organizational technical leadership, cross-team architecture, tradeoffs that affect the business, unblocking multiple teams at once.³⁶

Monzo’s public write-up is a useful counterweight: one company being specific rather than a framework being general. It describes Staff engineers as individual contributors with no direct reports, working on highly ambiguous problems across squads, mentoring, and creating multiplicative impact. It also admits what most ladders leave out: Staff engineers often write less code, because the scope widened underneath them.¹

Across these frameworks, each level changes who your work is for.

It’s a simplification, but it holds up well in interviews and career planning.

How scope changes at Staff level

Take a concrete case. A button component has an accessibility defect.

The Staff engineer usually still writes the fix. The difference is that the engineer also repairs whatever produced the defect, so the next one has a harder time getting out.

Make correct UI behavior easier for every product team, not only for the application you happen to be working on today.

Staff and Principal without direct reports

Staff and Principal can be individual-contributor levels. GitLab publishes both on its IC career matrix, and Monzo’s example explicitly describes the role as having no direct reports.⁴¹ Leadership travels through artifacts instead: architecture proposals, technical specifications, code reviews, standards, prototypes, migration plans, and the unglamorous work of helping other engineers reach good decisions without you in the room.

If you like building things and do not want to manage people, Staff or Principal design-system work is one of the few paths that keeps getting more interesting rather than more administrative.

From component library to UI platform

These three terms get used interchangeably, and the difference between them is most of what this guide is about.

The third row is where Staff-level UI work becomes most valuable, because it is the layer where many teams share the consequences of one architectural decision.

A platform is a pipeline with a fan-out in the middle, and every stage of it is somebody’s job:

Around that pipeline sits everything that keeps it alive: accessibility, documentation, testing, versioning, distribution, governance, adoption, support. The component is one piece, and rarely the piece that fails.

The public API

A product team using a shared component does not care whether its internals are Lit, Stencil, or hand-written Custom Elements. It cares about the contract. For a Web Component, that contract is bigger than most people first assume:

• Tag name
• Attributes
• Properties
• Methods
• Events
• Event payloads
• Slots
• CSS custom properties
• CSS parts
• DOM semantics
• Keyboard behavior
• Focus behavior
• Accessible name and role

Treat that whole surface the way you would treat an API you sell to customers. Changing an internal implementation is cheap. Changing a contract that hundreds of applications depend on is not, and the cost lands on people who did not choose it. This is the single principle that governs everything in the migration section later.

The browser platform beneath the frameworks

The HTML Standard defines Custom Elements as a way for authors to build their own DOM elements with custom behavior. The DOM Standard defines the event dispatch, composition, retargeting, and Shadow DOM concepts those elements rely on.⁷⁸ Stencil and Lit are higher-level APIs over exactly those capabilities.⁹¹⁰

That’s the reason to learn the layer underneath: a Staff-level Web Component engineer should be able to reason about a component after every framework name is deleted from the conversation. Frameworks are the top row, and the top row is the one that gets replaced.

Custom Elements

A native button is created with <button>Save</button>. A Custom Element lets you define a new element name and associate it with a JavaScript class through the browser’s registry.⁷

1class UiStatusMessage extends HTMLElement {
2  connectedCallback() {
3    if (!this.hasAttribute('role')) {
4      this.setAttribute('role', 'status')
5    }
6
7    this.textContent ||= 'Ready'
8  }
9}
10
11customElements.define('ui-status-message', UiStatusMessage)

That element now works anywhere HTML works, including inside templating languages that have never heard of it.

The lifecycle detail that catches people out is that an element can be attached, removed, and attached again. So this leaks:

1connectedCallback() {
2  window.addEventListener("resize", this.onResize);
3}

Every teardown needs to pair with its setup, the same pattern Lit recommends whenever a component listens to something it doesn’t own, like window or document.¹¹

1connectedCallback() {
2  window.addEventListener("resize", this.onResize);
3}
4
5disconnectedCallback() {
6  window.removeEventListener("resize", this.onResize);
7}

Attributes and properties are different things

They look interchangeable in a framework and they are not.

In practice that means the same component is configured two ways, and the split is not arbitrary:

1<ui-button variant="primary"></ui-button>

1userMenu.items = [
2  { id: 1, label: 'Profile' },
3  { id: 2, label: 'Sign out' },
4]

Lit provides reactive properties that trigger rendering and can optionally reflect back to attributes.¹² Stencil exposes public data through @Prop(), documented as attributes and properties on the element.¹³ Both make reflection a one-word change, which is why it gets overused. Reflect when it has a job: declarative HTML configuration, a CSS selector that needs the state, debugging visibility, or semantics that belong in markup. Reflecting a large object because the decorator allowed it just puts noise in the DOM.

Shadow DOM and styling hooks

Shadow DOM gives a host element its own encapsulated tree. The DOM Standard distinguishes the document tree from shadow trees and defines how both participate in event dispatch.⁸ Lit uses it by default.¹⁴

The component gets a small private room, and <slot> marks the doors where consumer content is allowed in:

1<!-- what the component holds internally -->
2#shadow-root
3<article>
4  <slot name="name"></slot>
5</article>
6
7<!-- what the consumer writes -->
8<ui-user-card>
9  <strong slot="name">Joshua</strong>
10</ui-user-card>

Encapsulation solves one problem and creates another: consumers still need to restyle things, and if you give them no legitimate way to do it, they’ll find an illegitimate one. Two platform mechanisms exist. CSS custom properties pass values in. CSS Shadow Parts, via the part attribute and ::part() selector, expose selected internal elements for outside styling.¹⁵

1/* Component: declare the hook */
2:host {
3  --ui-button-background: ButtonFace;
4}
5button {
6  background: var(--ui-button-background);
7}
8
9/* Consumer: use it */
10ui-button {
11  --ui-button-background: rebeccapurple;
12}

1<!-- Component: expose one internal element by name -->
2<button part="control">
3  <slot></slot>
4</button>

1/* Consumer: reach it */
2ui-button::part(control) {
3  border-radius: 999px;
4}

Both of these are API design decisions. Expose too little and consumers hack around the system, usually with !important and a selector that breaks on your next release. Expose every internal element and you have made your private implementation public, permanently. The useful question is whether you are willing to keep this element, with this name, in this position, for the next three years.

Server rendering touches this same boundary. The HTML Standard supports declarative Shadow DOM through shadowrootmode, so a shadow root can be expressed in markup instead of only constructed by client-side JavaScript.¹⁶

1<ui-card>
2  <template shadowrootmode="open">
3    <article>
4      <slot></slot>
5    </article>
6  </template>
7  Hello
8</ui-card>

Not every component needs to be server-rendered. But rendering strategy, hydration cost, search requirements, and first-paint behavior stop being one product’s concern the moment a design system is shared, because the platform’s answer becomes every product’s answer.

Events

Events are how a component reports that something happened. The DOM Standard defines bubbles, cancelable, and composed, and defaults all three to false.⁸ The third one is the one that matters here, because composed controls whether an event can cross a shadow boundary at all.

1this.dispatchEvent(
2  new CustomEvent('value-change', {
3    detail: { value: 'hello' },
4    bubbles: true,
5    composed: true,
6  }),
7)

Lit treats events as the normal way elements communicate upward, in a “data down, events up” model.¹¹¹⁷ Stencil is explicit that there is no such thing as a Stencil event: its decorators define and emit ordinary DOM events.¹⁸

The consequence is easy to state and easy to forget. Event names and event payloads are public API. Renaming value-change to valueChange is a breaking change for every listener in the estate, and unlike a renamed TypeScript export, nothing fails to compile. The listeners just stop firing.

Retargeting is the other Shadow DOM behavior worth knowing by name. When an event crosses a shadow boundary, the DOM’s retargeting rules change what an outside listener sees as event.target: it points at the host rather than the internal node actually clicked.⁸ This protects encapsulation and surprises everybody once. You don’t need to memorize the algorithm, just know it exists and reach for composedPath() when an event arrives with a target you didn’t expect.

Form controls

The HTML Standard defines form-associated custom elements and the ElementInternals capabilities that let a Custom Element participate in native form behavior properly, rather than shadowing it with a hidden input.⁷ Stencil documents support for form-associated components and their lifecycle callbacks.¹⁹

1class UiRating extends HTMLElement {
2  static formAssociated = true
3
4  #internals = this.attachInternals()
5  #value = ''
6
7  set value(nextValue) {
8    this.#value = String(nextValue)
9    this.#internals.setFormValue(this.#value)
10  }
11
12  get value() {
13    return this.#value
14  }
15}
16
17customElements.define('ui-rating', UiRating)

Before building any of it, ask whether a native control already solves the problem. Native controls arrive with years of browser, form, keyboard, mobile, and assistive-technology behavior you’d otherwise reimplement at your own expense, on your own timeline, with your own bugs. A custom rating widget is reasonable to build. A custom checkbox usually isn’t.

Lit

Lit describes itself as a library for building lightweight Web Components. Lit components are standard Web Components; what Lit adds is a reactive base class, declarative templates, scoped styles, and a set of conveniences on top.¹⁰ The browser supplies Custom Elements, the DOM, Shadow DOM, and events. Lit supplies less boilerplate around them.

1import { LitElement, css, html } from 'lit'
2import { customElement, property } from 'lit/decorators.js'
3
4@customElement('ui-button')
5export class UiButton extends LitElement {
6  @property({ reflect: true })
7  variant: 'primary' | 'secondary' | 'danger' = 'primary'
8
9  static styles = css`
10    button {
11      font: inherit;
12    }
13  `
14
15  render() {
16    return html`
17      <button type="button" data-variant=${this.variant}>
18        <slot></slot>
19      </button>
20    `
21  }
22}

The Lit lifecycle

Lit batches reactive updates asynchronously rather than rendering once per assignment, so “when does this run” has a real answer worth knowing.¹²²⁰

Lit also exposes updateComplete, a promise resolving around the end of the update cycle. Its documentation recommends awaiting a completed render before emitting events whose listeners need to observe the new rendered state.²⁰ Learn the lifecycle well enough to answer “when should this work happen,” not well enough to recite the names.

Public property or internal state

Lit separates public reactive properties from internal reactive state.¹² The decorator you pick declares whether a value is part of the public API.

1@property()
2value = ""; // public API. You now own this for years.
3
4@state()
5private validationMessage = ""; // implementation detail. Yours to change.

If consumers do not need to set it or read it, do not make it public. Every public field is another behavior somebody will depend on, discover by accident, and file a bug about when it changes.

Reactive Controllers

Reactive Controllers package reusable state, behavior, and lifecycle participation so it can be shared across components.²¹ They earn their place for cross-cutting concerns: localization, resize observation, shared keyboard behavior, state synchronization. They stop earning it the moment they become the place unrelated component logic goes to hide. A controller that four components use is infrastructure. A controller that one component uses is a file you moved code into.

For an engineer who already knows Stencil, Lit is high-leverage as a second implementation model precisely because it forces the separation: after building the same component twice you can tell which ideas belonged to Stencil and which belonged to Web Components. That knowledge lasts longer than fluency in any single framework.

Using Web Components in React

The old line about React being unable to consume Web Components is out of date. React 19’s release notes state that it added full support for Custom Elements and passes the Custom Elements Everywhere suite, and the current React DOM documentation covers custom-element event handling including CustomEvent through JSX props.²²²³

What is still true is that interoperability and ergonomics are different questions. A component can work correctly in React and still feel foreign to a React team, which is what a thin adapter is for. @company/components publishes <ui-button> and owns the behavior; @company/react publishes Button and adapts that public API to React conventions of naming, typing, refs, and event props. Lit publishes @lit/react for exactly this.²⁴

1import * as React from 'react'
2import { createComponent } from '@lit/react'
3import { UiButton } from '@company/components/button.js'
4
5export const Button = createComponent({
6  tagName: 'ui-button',
7  elementClass: UiButton,
8  react: React,
9})

Keep adapters thin. Once a wrapper contains its own interaction model, its own state, or its own opinions about behavior, you no longer have a design system with a React adapter. You have two design systems, and only one of them has tests.

Migrating Stencil to Lit

Stencil’s compiler reads metadata from decorators like @Prop() and its event and lifecycle declarations, then compiles component output.⁹¹³¹⁸ Lit uses standard Web Components with its own reactive-property and rendering layer.¹⁰¹² The migration involves more than swapping one decorator vocabulary for another, and teams that treat it as a find-and-replace tend to ship a rewrite that breaks every consumer.

The goal is to replace the implementation and preserve the consumer contract, unless there is a deliberate, argued reason to change it. So the first deliverable is an inventory, per component, of everything a consumer can currently observe:

• Tag name
• Attributes
• Properties
• Property types
• Reflection behavior
• Methods
• Events
• Event payloads
• Bubbling and composition
• Slots
• CSS custom properties
• CSS parts
• Default content
• Keyboard behavior
• Focus behavior
• ARIA and semantics
• Form behavior

One component in Stencil and Lit

Here is a toggle in Stencil:

1import { Component, Event, EventEmitter, h, Prop } from '@stencil/core'
2
3@Component({
4  tag: 'ui-toggle',
5  shadow: true,
6})
7export class UiToggle {
8  @Prop({ reflect: true }) checked = false
9
10  @Event({ bubbles: true, composed: true })
11  checkedChange!: EventEmitter<boolean>
12
13  private toggle = () => {
14    this.checkedChange.emit(!this.checked)
15  }
16
17  render() {
18    return (
19      <button
20        type="button"
21        aria-pressed={String(this.checked)}
22        onClick={this.toggle}
23      >
24        <slot />
25      </button>
26    )
27  }
28}

And in Lit:

1import { LitElement, html } from 'lit'
2import { customElement, property } from 'lit/decorators.js'
3
4@customElement('ui-toggle')
5export class UiToggle extends LitElement {
6  @property({ type: Boolean, reflect: true })
7  checked = false
8
9  private toggle() {
10    this.dispatchEvent(
11      new CustomEvent<boolean>('checkedChange', {
12        detail: !this.checked,
13        bubbles: true,
14        composed: true,
15      }),
16    )
17  }
18
19  render() {
20    return html`
21      <button
22        type="button"
23        aria-pressed=${String(this.checked)}
24        @click=${this.toggle}
25      >
26        <slot></slot>
27      </button>
28    `
29  }
30}

The code is completely different, but the consumer sees the same tag, reflected attribute, event name and payload, slot, and keyboard behavior. That only works because someone wrote the contract down first.

This example is also deliberately small. A real migration has to account for event casing conventions, generated type definitions, framework bindings, style output, hydration strategy, form behavior, test utilities, build targets, and package structure. None of that shows up in a toggle.

Migrating in steps

Unless there’s a business reason for a rewrite, migrate a large shared library in slices, keeping consumers whole while the implementation changes underneath them.

The key point in that sequence is that a migration has consumers, and every decision in it affects another team’s sprint.

Contracts: TypeScript, packages, versions

Types as API documentation

The TypeScript Handbook documents unions, narrowing, generics, and utility types as mechanisms for describing and constraining JavaScript APIs.^25262728 These matter more in a design system than in application code, because a public component API gets reused by people who will never read its source.

A union closes a set:

1type ButtonVariant = 'primary' | 'secondary' | 'danger'
2
3const variant: ButtonVariant = 'banana'
4// Type error

A discriminated union goes further and makes invalid combinations unrepresentable, so the type describes which data is valid in which state:

1type LoadState<T> =
2  | { status: 'idle' }
3  | { status: 'loading' }
4  | { status: 'success'; data: T }
5  | { status: 'error'; error: Error }
6
7function renderState<T>(state: LoadState<T>) {
8  switch (state.status) {
9    case 'success':
10      return state.data
11
12    case 'error':
13      return state.error.message
14  }
15}

There is no state in which data exists and status is 'error', because the type will not let you construct one. TypeScript’s narrowing model refines the union from the discriminant at each branch.²⁶

Generics and open or closed types

Generics describe a relationship between types while preserving information about the values passing through.²⁷ Same shape, different data:

1interface SelectOption<TValue> {
2  label: string
3  value: TValue
4}
5
6const numberOption: SelectOption<number> = { label: 'Five', value: 5 }
7const stringOption: SelectOption<string> = { label: 'Connecticut', value: 'CT' }

The harder decision is how closed to make a type at all:

1type Size = 'small' | 'medium' | 'large'
2// versus
3type Size = string

The first gives autocomplete, catches typos, and forbids anything you didn’t anticipate. The second is extensible and lets 'smal' ship to production. There’s no universal winner: the real question is whether consumers are expected to extend this value space. Close it for strict visual consistency. Leave it open if teams legitimately need sizes you haven’t thought of, since otherwise they stop using the prop and reach for a class instead, and you lose both consistency and the signal that they needed something.

Staff-level TypeScript is less about knowing every utility type and more about designing public APIs that communicate intent, reject invalid states where practical, and stay legible to somebody who only reads the autocomplete.

Package entry points

Node and npm use package.json to describe entry points, dependencies, and module behavior, and Node supports ECMAScript modules as an official format.²⁹³⁰³¹ The exports field defines which entry points consumers are allowed to import, and Node’s own publishing guidance warns that adding exports to an existing package is a breaking change if consumers were previously importing undeclared deep paths.³²

That warning sums up this section: a four-line change to a config file, and every application that reached into your dist/ folder stops building.

1{
2  "name": "@company/components",
3  "version": "5.2.0",
4  "type": "module",
5  "exports": {
6    ".": {
7      "types": "./dist/index.d.ts",
8      "import": "./dist/index.js"
9    },
10    "./button": {
11      "types": "./dist/button.d.ts",
12      "import": "./dist/button.js"
13    }
14  },
15  "types": "./dist/index.d.ts",
16  "sideEffects": false
17}

The exact shape follows your build output. The architectural question does not: which imports have we promised to keep working? The moment your documentation contains import '@company/components/button', that path is public developer experience, whether or not anyone wrote it down as API.

Dependency types

npm documents the dependency fields, and the mental model is short.³³³⁰ dependencies are needed at runtime. devDependencies are needed to build, test, or develop the package. peerDependencies declare a compatibility relationship with something the consuming environment supplies.

A React adapter declares React as a peer rather than shipping its own copy, because two React runtimes in one application is a class of bug nobody enjoys diagnosing:

1{
2  "peerDependencies": {
3    "react": ">=19"
4  }
5}

These choices decide duplicate runtimes, bundle size, install behavior, upgrade constraints, and how much support you end up giving. They are made in a config file and felt in every consuming application.

Semantic versioning for design systems

Semantic Versioning defines MAJOR.MINOR.PATCH once a public API is declared: incompatible changes bump major, backward-compatible features bump minor, backward-compatible fixes bump patch.³⁴

What SemVer won’t do is tell you what your public API is, and for a design system that reaches well past TypeScript signatures: the same surface listed earlier (attributes, events and their payloads, CSS hooks, slots, keyboard behavior, semantics, import paths, framework adapters, or visual output products built layouts around) can all be breaking. Tightening a button’s default padding by 4px ships as a patch in most teams and breaks three product layouts by Tuesday.

One package, or many

There is no standard answer, and the tradeoffs are real in both directions.

For most enterprise design systems, a small number of deliberately layered packages is the right starting point. Split when a boundary actually exists, not because the monorepo tool made splitting cheap.

Managing breaking changes

SemVer announces that a break happened.³⁴ It does not perform the migration, and the version number is the least useful part of the process to a team with forty applications and a quarter of committed roadmap.

A system used by a hundred applications needs a different policy from one used by three. The failure mode is running the hundred-application process at three applications, which reads as bureaucracy, or the three-application process at a hundred, which reads as chaos.

Accessibility, testing, and browser support

WCAG and the APG

WCAG 2.2 is a W3C Recommendation containing testable success criteria for web content.³⁵³⁶ The WAI-ARIA Authoring Practices Guide provides patterns and examples for common widgets and interaction models.³⁷³⁸ WCAG asks what outcomes accessible content must satisfy. The APG asks how a given interactive pattern might be built. Neither is a certification stamp: an APG example is a reference implementation of one pattern, not a guarantee about your product, your semantics, or your users.

Accessible behavior is part of the contract

A component isn’t accessible just because it renders <div role="dialog">. Accessibility depends on the interaction model. For a dialog that means the trigger activates it, focus moves somewhere sensible, keyboard interaction works, background interaction is handled, and on close focus returns to where the user left it.³⁸ The best accessibility work in a design system makes the safe behavior the default, so using the component correctly is easier than using it incorrectly.

Prefer native semantics wherever they fit. When the interaction really is a button:

1<!-- not this -->
2<div role="button" tabindex="0">Save</div>
3
4<!-- this -->
5<button type="button">Save</button>

ARIA is valuable and sometimes unavoidable. Using it to reconstruct semantics HTML already provides is how a design-system team acquires behavior it now has to maintain forever, for nothing in return.

Limits of automated accessibility testing

Playwright’s accessibility documentation is plain about this: automated tests catch common problems, many issues need manual testing, and the recommendation is to combine automated checks with manual assessment and inclusive user testing.³⁹ Storybook can run the same checks in component development and CI.⁴⁰

1import { test, expect } from '@playwright/test'
2import AxeBuilder from '@axe-core/playwright'
3
4test('dialog has no automatically detectable violations', async ({ page }) => {
5  await page.goto('/components/dialog')
6
7  const results = await new AxeBuilder({ page }).analyze()
8
9  expect(results.violations).toEqual([])
10})

A green result tells you a specific set of rules found nothing. It doesn’t tell you whether the keyboard flow makes sense, whether the label is comprehensible, or whether a screen-reader user’s path through the task is efficient, and all of those problems can ship with a passing test run.

Test layers

Storybook is built for developing and documenting components in isolation; Playwright runs end-to-end across Chromium, Firefox, and WebKit through one API.⁴¹⁴² A shared UI system usually wants several layers, because each answers something the others can’t.

Contract tests are the highest-leverage row for a platform team: they’re what lets the implementation move while consumer behavior stays still, and the reason the Stencil-to-Lit migration described earlier is possible at all.

Say the documented contract is: changing the open property on <ui-dialog> makes the dialog visible, and closing it emits ui-close. The test is written against that sentence, not against Lit:

1import { test, expect } from '@playwright/test'
2
3test('dialog public contract', async ({ page }) => {
4  await page.setContent(`
5    <ui-dialog id="dialog">Hello</ui-dialog>
6    <script type="module" src="/dist/ui-dialog.js"></script>
7  `)
8
9  await page.locator('#dialog').evaluate((element) => {
10    element.open = true
11  })
12
13  await expect(page.locator('#dialog')).toHaveAttribute('open')
14
15  // Continue with the documented close interaction
16  // and verify the documented public event.
17})

The test doesn’t depend on which library rendered the dialog, which is what lets the implementation change safely.

Browser support policy

Playwright supports testing Chromium, Firefox, and WebKit, covering the major engine families in automated runs.⁴²⁴³

Don’t start compatibility planning by asking what polyfills you need. Start by asking which browsers and product environments the organization has actually promised to support: that answer determines the polyfills, feature detection, fallbacks, and which high-risk interactions get checked by hand.

Then write the policy down and publish it. Every product consuming the system inherits those decisions whether or not they were told, and an unstated policy gets discovered during an incident.

Tokens, governance, and adoption

The stable design tokens format

The Design Tokens Community Group, a W3C Community Group, published the first stable Design Tokens Format Module in October 2025, defining a file format for exchanging tokens between tools.⁴⁴⁴⁵ Its technical material describes tokens as individual design-system values: color, spacing, typography.⁴⁶

1{
2  "color": {
3    "action": {
4      "primary": {
5        "$type": "color",
6        "$value": {
7          "colorSpace": "srgb",
8          "components": [0.1, 0.3, 0.8],
9          "alpha": 1
10        }
11      }
12    }
13  }
14}

Follow the applicable DTCG version rather than that simplification. What matters more than the syntax: a token is a named design decision that can travel between tools and platforms without a human retyping a hex value into a second system and introducing a third one by accident.

Figma Code Connect

Figma’s Code Connect documentation describes it as a way to connect code components in a repository to their Figma counterparts in Dev Mode, with documented support for HTML and Web Components.⁴⁷⁴⁸

It links a Figma component, the design intent behind it, a component API, and an implementation, but neither side is automatically correct: sometimes the design model is stale, sometimes the code API is wrong, and sometimes the two model genuinely different concepts and need an explicit translation between them.

That’s what makes design-code mismatch a Staff-level problem rather than a ticket. Resolving it usually requires design and engineering to agree on what the thing is, and no amount of renaming a prop substitutes for that conversation.

Governance

The word sounds bureaucratic. In practice it answers a short list of questions that would otherwise get re-litigated every quarter: who can add a component, who owns the API, what counts as breaking, how proposals get reviewed, who signs off on accessibility, how deprecated APIs get removed, and how design and code stay in step.

Good governance reduces repeated arguments. Bad governance either blocks everything or lets the system drift into inconsistency, and both failure modes look like “we have a process.”

A lightweight proposal flow is usually enough: problem, evidence of consumer need, proposed API, alternatives, accessibility and design review, engineering review, prototype, decision. Not every button change needs an RFC. A change to how every button in the company reports its state probably does.

Decisions worth remembering get an Architecture Decision Record, which can be very small:

1# ADR: Dialog uses native <dialog> internally
2
3## Status
4
5Accepted
6
7## Problem
8
9We need a consistent modal-dialog primitive.
10
11## Constraints
12
13- Must support keyboard users.
14- Must work in supported browsers.
15- Must expose a stable Web Component API.
16- Must allow future internal replacement.
17
18## Decision
19
20Use the native <dialog> element inside the component.
21
22## Alternatives considered
23
24- Custom fixed-position div
25- Third-party dialog primitive
26
27## Consequences
28
29Positive:
30
31- More platform behavior is delegated to the browser.
32
33Negative:
34
35- We must validate browser behavior against our support policy.

The record matters more than the template. Eighteen months later, when someone proposes replacing the internals, they can find out why the decision was made instead of re-deriving it or assuming it was arbitrary. Leave enough context that the next engineer can disagree with you knowledgeably.

Diagnosing low adoption

A design system can be technically excellent and still fail. When adoption is weak, diagnose before prescribing: “we need better documentation” is the answer teams reach for regardless of the actual problem. Nine questions, and what a “no” to each one is really telling you:

Most of these problems can’t be fixed with better documentation.

Developer experience

Storybook’s model centres on building and documenting components in isolation, which is why it’s the common tool here.⁴¹ But the documentation site is one part of a longer surface: package installation, import paths, TypeScript autocomplete, naming, examples, error messages, release notes, migration docs, framework adapters, local development speed, debugging, the contribution workflow, and where someone goes when they’re stuck at 4pm.

The bar for a component API is that an ordinary product engineer can use it correctly without knowing how the design-system team built it. If using it correctly requires understanding the implementation, the API is the bug.

Measuring success

Useful signals are mostly unglamorous: applications on the system, package versions deployed, the lag between a release and consumer upgrade, deprecated API usage, component usage, support request volume, migration completion, accessibility defects originating in shared components, and build or bundle regressions.

Every one needs context. Low adoption can mean the system is failing, or that it’s deliberately scoped to one product family. Read in groups, they answer three different questions:

Use all three, because a team measuring only the first optimizes for shipping components, and a team measuring only the third optimizes for never shipping anything.

“We have 87 components” says nothing about whether any of them are useful, accessible, maintainable, or used.

Making and sharing decisions

Start architecture questions with constraints

Someone asks how you’d build a design system for fifty applications. The weak answer is “I would use Lit.” Lit may well be right, but nothing yet established makes it right.

Start by discovering constraints. What frameworks consume the system? Is server rendering required? Which browsers are supported? What already exists, and who depends on it? How many teams, and how independent are they? How quickly can consumers upgrade, given their release process? What accessibility standard does the organization target, and is it a legal obligation? Are there native or mobile consumers of the same tokens? How are packages published? Is the organization optimizing for strict consistency or product flexibility? Who owns governance?

Let the architecture follow from the answers.

A repeatable decision model

Work through the consumer, problem, constraints, options, tradeoffs, decision, rollout, and measurement, in that order, every time.

Take a real question: should the shared system be React components or Web Components?

The decision comes after that, and it’s defensible because everyone can see what it was weighed against. Staff-level interviewing is mostly about demonstrating which facts determine the answer, not naming the interviewer’s preferred technology.

Leading through written artifacts

GitLab’s Staff and Principal frameworks emphasize architectural leadership, standards, mentorship, cross-team work, and enabling others.²³ Without direct reports, all of that has to travel through things you make: an RFC, an ADR, a prototype, a migration guide, an API specification, an accessibility contract, a reference implementation, a code review, a test harness, a release plan, documentation.

The best Staff engineers don’t make themselves indispensable by holding knowledge. They make their judgment reproducible, in tools and standards and examples, so the same decision gets made correctly in rooms they’re not in. That’s also the difference between mentoring and being an answer machine. Compare:

Mistakes to avoid

Three habits are worth resisting, because each one looks like diligence.

You do not need to master every frontend framework. A UI-platform engineer gets far more leverage from deep platform knowledge plus strong adaptation skills. Go deep on HTML, CSS, JavaScript and TypeScript, accessibility, component and API design, and browser behavior. Stay strong on Lit or Stencil, React interoperability, testing, package tooling, and design tooling. Working knowledge is enough for other consumer frameworks, build systems, and SSR environments. Frameworks change, but platform concepts carry over.

Complexity is not seniority. Nobody demonstrates Staff-level ability by selecting the most sophisticated available architecture. Sometimes the correct decision is to use <button>, or to not build the component, or to keep the old API for another year because migration costs more than the benefit is worth. Judgment includes knowing when not to introduce an abstraction.

Not every problem is a design-system problem. Some UI is legitimately product-specific. A design system should absorb repeated organizational patterns, not every unique feature that happens to look tidy in a shared repo. Ask whether multiple consumers will genuinely benefit, or whether product logic is being moved into shared infrastructure because it feels neater there. The wrong abstraction creates more coupling than the duplication it replaced.

A practice project

The most useful practice project for this specialization is a very small component platform, designed so you have to solve platform problems instead of feature problems.

1ui-system/
2├── packages/
3│   ├── tokens/
4│   ├── components/
5│   └── react/
6├── apps/
7│   ├── docs/
8│   └── react-demo/
9└── tests/

Four components is enough: ui-button, ui-text-field, ui-alert, and ui-dialog, because they cover progressively harder concerns in order. The button covers semantics, the text field covers form participation, the alert covers announcements and status, and the dialog covers focus management and modality, which is where many component libraries give up.

That last stage teaches more Staff-level thinking than building ten additional visual components, because it is the only one where the hard part is other people.

A ten-week study plan

If you want the same thing on a schedule, this is the sequence I would run. The deliverable column is the part that matters; the study column is just what you need in order to produce it.

Self-assessment checklist

The checklist has three groups. It isn’t a certification, and nobody will ask you to produce it. It’s useful the same way a preflight checklist is: gaps are hard to see until you look for them.

Finding the right role

Job titles to search

The title matters far less than the work, but you have to type something into the search box:

• Staff Design Systems Engineer
• Principal Design Systems Engineer
• Staff UI Engineer
• Principal UI Engineer
• Staff Frontend Engineer, Design Systems
• UI Platform Engineer
• Staff UI Platform Engineer
• Principal UI Platform Engineer
• UX Engineer
• Staff UX Engineer
• Principal Product Design Engineer
• Design Systems Architect

Reading the job description

A real platform role gives one person responsibility across several of these: shared component architecture, Web Components or platform standards, accessibility, design tokens, component APIs, package publishing, semantic versioning, documentation, Storybook, cross-framework consumers, React adapters, Figma integration, browser support, testing infrastructure, governance, adoption, migration strategy, developer experience, technical specifications, cross-team architecture, and mentoring.

The faster tell is the language. Job descriptions leak scope:

There is nothing wrong with the right-hand column. Those are good jobs, and simply a different career. Taking one while expecting the other is how people end up frustrated eighteen months later. The same goes for a short contract when what you want is stability: no amount of technical fit fixes that mismatch.

Industries that hire for this work

An organization with many products, many product teams, long-lived applications, accessibility obligations, several frontend frameworks, and one shared brand has structural reasons to fund a UI platform. An organization with two products and one team does not, and should not.

That points toward large technology firms, financial services, insurance, healthcare, enterprise SaaS, retail platforms, and government-facing systems. It says where the problems live, not that every company there has a mature design-system team. Plenty have the problem and nobody assigned to it, which is either the opportunity or the warning depending on how the rest of the interview goes.

How to describe yourself

“Frontend engineer” is accurate and tells a hiring manager almost nothing. If your differentiators are component systems, accessibility, cross-framework UI, and design-engineering infrastructure, then something like Design Systems & UI Platform Engineer carries far more signal. The specialization is an intersection: close enough to design to argue about what a component should do, close enough to engineering to ship the thing that does it.

An introduction should explain that specialty rather than recite your resume. Career foundation, specialization, technical depth, the organizational problems you solve, why this role fits:

“My background is in frontend engineering, but over time my work has concentrated on design systems and shared UI infrastructure. I focus on accessible component APIs, Web Components, developer experience, and the engineering systems needed to distribute components across products. What interests me about Staff-level UI-platform work is solving those problems once at the system level, instead of repeatedly inside individual applications.”

Treat it as an example to adapt; the structure is the reusable part.

Preparing for the interview

Prepare stories in advance so that interview time goes on reasoning rather than on remembering your own career. One story each:

Structure each one as situation, constraint, options considered, decision, result, and what you learned. “Options considered” is what separates a Staff answer from a Senior one, because it is where architectural judgment becomes visible.

Expect a system-design prompt along the lines of “design a framework-agnostic component platform used primarily by React applications.” A good answer covers requirements, browser support, token architecture, Web Component contracts, the React adapter, accessibility, testing, packaging, versioning, documentation, governance, and adoption. The interviewer will learn more from which constraint you ask about first than from your final architecture.

Expect migration questions, and notice what they are really asking. How would you migrate Stencil to Lit? Move consumers from version 4 to 5? What if 20% of products cannot upgrade this year? What if accessible behavior requires a breaking API change? Each of those questions tests consumer empathy and risk management.

And prepare a real failure. “I care too much about quality” is not a failure and every interviewer has heard it. A usable one contains a genuinely mistaken assumption. Mine: we designed an API for maximum flexibility, consumers used it inconsistently, accessibility and documentation both got harder, and we learned the system needed stronger constraints rather than more options. Staff credibility goes up when you can show your judgment changed because reality corrected it.

Questions to ask them

Ask questions that reveal the system behind the job description.

Ask that last group early rather than late. A technically perfect role can still be the wrong opportunity if its risk profile conflicts with what you need, and finding that out at offer stage wastes everyone’s time.

The long game is not learning every part of software engineering equally. It is becoming unusually capable in one vertical slice: accessible UI, component architecture, web standards, design systems, release infrastructure, cross-framework consumption, governance, adoption, platform architecture. That is depth without a detour into people management or backend distributed systems. Not every company has every rung, so chase the responsibility rather than the label.

Summary

The guide comes down to four layers.

Senior UI engineering tends to be strongest in the first two. Staff UI-platform engineering increasingly operates in the second and third. Principal scope reaches the fourth. Real companies draw those boundaries differently, so treat it as a thinking tool rather than a ladder to climb.

A Staff-level UI engineer does more than build the hardest dropdown, valuable as that is. They ask how the component should behave, how its API should behave, how product teams will consume it, how it stays accessible, how it gets tested, how it is packaged, how changes ship safely, how teams migrate, how designers and engineers stay aligned, how anyone will know whether the system is working, and how the next engineer ends up more effective than the last one.

The transition is from building UI to engineering the platform through which an organization builds UI.

Sources

Everything above that is a matter of record is footnoted, and the full reference list sits at the foot of this page. The sources are standards bodies, official framework and tool documentation, and public company engineering frameworks, in that order of preference.

If you read only eight of them, read these:

• WHATWG HTML Standard: Custom Elements for the normative definition, including form-associated elements.
• WHATWG DOM Standard for the event model, composition, retargeting, and shadow trees.
• CSS Shadow Parts for the only sanctioned way to open a shadow tree to outside styling.
• Lit documentation as the clearest writing on Web Components in general, not just on Lit.
• WCAG 2.2 for the criteria, and the ARIA Authoring Practices Guide for the patterns.
• Node.js: publishing a package for the exports trap that catches most first-time platform teams.
• Semantic Versioning because everyone cites it and fewer people have read it.
• GitLab’s engineering career matrix as the most detailed public leveling framework available.

One caution about secondary material. If you find older Microsoft FAST or Fluent Web Components articles, check them against the current FAST repository before designing anything around them. Framework-specific guidance in that ecosystem has aged considerably faster than the Web Component standards underneath it, which is a decent argument for learning the standards first.