---
title: Inversion of control in design systems
description:
  Encouraging component composition, avoiding overly complex component
  maintenance, and empowering teams
date: '2025-01-23'
image: 'omar-flores-lQT_bOWtysE-unsplash.webp'
---

## The promise of design systems

UI component libraries and design systems enable brand consistency at scale. By
leveraging a design system, large organizations can ship consistently branded
digital experiences without the need to re-build repetitive UI elements across
multiple applications simultaneously.

Designers and engineers on a design system team may view a component library as
a means of establishing visual and logical control over disparate teams and
processes, narrowing the range of possibilities that can be produced across a
large digital footprint.

For example, the component may include some opinions about where icons can be
placed. In our initial draft, we built a button component that accepts an `icon`
prop:

### A simple problem: a button with an icon

```tsx
import { Button } from '@company/ui'

function MyApp() {
  return <Button icon="plus-circle">Click me</Button>
}
```

> Designers and engineers on a design system team may view a component library
> as a means of establishing visual and logical control over disparate teams and
> processes, narrowing the range of possibilities that can be produced across a
> large digital footprint.

Ta-dah! In this example, the `Button` handles the icon via a unique identifier,
rendering it on the right hand side of the element only. Now we can _require_
teams within our company to only position icons on the right and make sure we
keep our buttons visually consistent across applications.

### Fix #1

Unfortunately, we immediately get a request to support icons on the left &mdash;
and the requesting team has a very strong argument for doing so that we never
could have anticipated when we first started. How can we handle this without
publishing a breaking change to our component? Maybe the better original
component API would have looked something like this:

```tsx
import { Button } from '@company/ui'

function MyApp() {
  // `iconPosition` can be "right" or "left", defaulting to "right" when nothing is set
  return (
    <Button icon="plus-circle" iconPosition="left">
      Click me
    </Button>
  )
}
```

Ta-dah! We did it. Now we have solved our problem and we can ride in to the
sunset truly and confidently victorious. We do have two separate props that are
tightly coupled, but at least they both start with the name `icon` so that
shouldn't be too painful...

### Fix #2 (not again)

Once again we receive a request from a team building an application &mdash; and
they really need **two icons at once**, one icon on each side _simultaneously_.
Well, this will be difficult to support with our existing component API but
let's roll up our sleeves and give it a shot.

```tsx
import { Button } from '@company/ui'

function MyApp() {
  return (
    <>
      {/* We still need to support our old API, so let's leave this as an example of what that looks like */}
      <Button icon="plus-circle" iconPosition="left">
        Click me
      </Button>
      {/* We can also support this newer approach (definitely bulletproof this time!) */}
      <Button rightIcon="plus-circle" leftIcon="checkmark">
        Click me
      </Button>
    </>
  )
}
```

I'm not sure what would happen if an engineer tried to use `iconPosition` and
`leftIcon` at the same time, but surely no one would do something so foolish,
right?

### Fix #3 (It won't stop)

After declaring victory, we ride in to the sunset. At least until another team
requests our help with the `Button` component. This time they aren't too
concerned with `iconPosition`, but they do want to change the color of the icon
somehow &mdash; and ideally they could use a design token to do so.

Well, that shouldn't be too hard (though we do have to support all of our
existing component API surface when we make this change):

```tsx
import { Button } from '@company/ui'

function MyApp() {
  return (
    <>
      {/* Well, `iconColor` will work here but we definitely can't have two different colors at once */}
      <Button icon="plus-circle" iconPosition="left" iconColor="fg.action">
        Click me
      </Button>
      {/* Aha! We *can* support two different colors with this API though */}
      <Button
        rightIcon="plus-circle"
        leftIcon="checkmark"
        rightIconColor="fg.action"
        leftIconColor="fg.success"
      >
        Click me
      </Button>
    </>
  )
}
```

> What started with good intentions (control over design) has quickly devolved
> in to a mess for the engineering team, all without any material benefit with
> regards to design consistency and standardization.

Well, we made the consuming team happy but this is getting really gnarly and
hard to maintain. In order to support icons in two positions, each with distinct
imagery and color, we now have _7 props we need to maintain_ &mdash; and nearly
all of them are tightly coupled with one another, meaning each time we need to
change 1 we put the other 6 at risk of a break. Not good.

Not to mention, the design team's goal of controlling the visual positioning of
icons within buttons has now been lost. Now we have lost consistency _and_ we
have a highly complex component simultaneously. What a mess.

What started with good intentions (control over design) has quickly devolved in
to a mess for the engineering team, all without any material benefit with
regards to design consistency and standardization.

## Enter component composition and inversion of control

Looking from the end result, it's easy to see how a component API like this can
naturally evolve over time and end in a unenviable place. A rather simple
component that accepts an icon is now extremely complex and brittle to maintain.
If we could hop in a time machine, how could we have handled this better?

### Children/slots and the compound component

Instead of using string props, it's time to use `children` (in some other
frameworks this might be content projection or a `slot`) to make the component
surface area much smaller while keeping everyone happy (especially the design
system engineering team):

```tsx
import { Button, ButtonIcon } from '@company/ui'

function MyApp() {
  return (
    <>
      {/* To reposition the icon, we just put it first in the DOM order just like regular HTML */}
      <Button>
        <ButtonIcon icon="plus-circled" />
        Click me
      </Button>
      {/* And here is the same icon on the right */}
      <Button>
        Click me
        <ButtonIcon icon="plus-circled" />
      </Button>
      {/* And now one icon on each side */}
      <Button>
        <ButtonIcon icon="success" />
        Click me
        <ButtonIcon icon="plus-circled" />
      </Button>
      {/* And now each icon has its own color */}
      <Button>
        <ButtonIcon icon="success" color="fg.success" />
        Click me
        <ButtonIcon icon="plus-circled" color="fg.action" />
      </Button>
    </>
  )
}
```

Success! We have accomplished a few things with this approach:

1. We have decoupled props &mdash; the `ButtonIcon` component has its own props
   that control its appearance, but they are distinct from the parent `Button`
2. Teams can implement icons in whichever order they choose in an
   easy-to-understand way, no component API documentation required
3. The `Button` component is much less likely to break accidentally when its
   internal structure changes compared to the old approach
4. Teams can even use conditional logic within a button instance more easily,
   using JSX to conditionally add and remove icons based on conditions relevant
   to their users

### Empowerment over top-down control

By empowering application teams to better serve the needs of their users, design
system teams can build components with a much better developer experience all
while reducing the risk of regression defects in the future. Teams may build
wild and crazy things using their newfound power of component composition
&mdash; and at the end of the day that's OK. Application teams are _almost
always closer to their users and the needs of the business_ and giving
application teams the keys to their own destiny is the only way to effectively
build a design system at scale

## Learn more

Inversion of control, component composition, and compound components are not new
ideas, yet many design systems still fail to empower their application teams to
build high quality digital products by inverting (giving up) control.

If you are having trouble taking the component composition high road (or
convincing others to do the same), read through some helpful articles on the
subject from industry experts to learn more about the how of the approach:

- [Inversion of Control by Kent C. Dodds](https://kentcdodds.com/blog/inversion-of-control)
- [Compound Components by Ryan Florence](https://www.youtube.com/watch?v=hEGg-3pIHlE)
- [Compound Components by Kyle Shevlin](https://kyleshevlin.com/compound-components/)


Encouraging component composition, avoiding overly complex component maintenance, and empowering teams

Inversion of control in design systems

---
title: Building a Collapsible Web Component with Lit
description: Learn how to build a re-usable web component using slots
date: '2022-02-04'
image: 'colin-carter-w1g2o4J_4Dg-unsplash.webp'
---

Web components allow engineers to author re-usable, custom HTML elements which
can be used across platforms and frameworks. With a web component, an engineer
can build a custom component once, and re-use it within a React project, an
Angular project, or even a Ruby on Rails project.

I've written about
[implementing a collapsible component accessibly](/building-an-accessible-collapsible-element)
with vanilla HTML, so let's dive in with implementing this component using
[Lit](https://lit.dev).

## A simple example

For starters, let's take a look at a non-compound collapsible element:

<iframe src="https://stackblitz.com/edit/blogbuilding-a-compound-web-component-with-lit-01?ctl=1&embed=1&file=src/my-collapsible.ts&hideExplorer=1&hideNavigation=1&theme=dark"></iframe>

In this example, a single component controls the state of the element as well as
passed-in content. A `title` prop is used to handle the content of the
triggering element. Everything works! We can use our component like any other
HTML element, and it works as expected:

```html
<my-collapsible title="My Collapsible Element">
  <p>This content will show and hide dynamically</p>
</my-collapsible>
```

After patting ourselves on the back, we quickly receive a request for a new
feature - an implementing team now wants to add a custom icon inside the
triggering button. OK, that should be easy enough - we can just add a
`title-icon` prop:

```html
<my-collapsible
  title="My Collapsible Element"
  title-icon="<svg id='some-inline-svg'></svg>"
>
  <p>This content will show and hide dynamically</p>
</my-collapsible>
```

Nice! This solves our problem. Except, what do we do if an implementing team
wants to use a `.png` as an icon? Or maybe they want to pass in a custom web
component instead of an inline SVG? And what if they want to put the icon on
either side of the triggering element content? Or maybe they want to apply a
color to that particular icon instance? We could quickly end up creating a
component with a lot of hard-to-manage surface area:

```html

<my-collapsible
  title="My Collapsible Element"
  title-icon=""
  title-icon-image="/path/to/icon.png"
  title-icon-color="hotpink"
  icon-position="left"
>
  <p>This content will show and hide dynamically</p>
</my-collapsible>
```

## Slots to the rescue

Fortunately for us, the
[slot element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot)
allows us to expose multiple places within our component in which to render
child content, including arbitrary HTML or custom elements:

<iframe src="https://stackblitz.com/edit/blogbuilding-a-compound-web-component-with-lit-02?ctl=1&embed=1&file=src/my-collapsible.ts&hideExplorer=1"></iframe>

We have removed the `title` prop entirely, and have no need for any of the
icon-related props either, as an implementing team can slot in whatever content
they want via the `"title"` slot.

```html
<my-collapsible>
  <h2 slot="title">
    Click Me
    <svg id="this-is-my-inline-svg">...</svg>
  </h2>
  <p slot="content">This content will show and hide dynamically</p>
</my-collapsible>
```

### Wrapping Up

In this example, we implemented a simple, accessible collapsible custom element
using [Lit](https://lit.dev). By leveraging slots over props, we were able to
dramatically simplify the component API, reducing our maintenance overhead as
well as the risk of defects.

In a future post, I'll discuss a more complex pattern that can offer even more
control to implementing teams, all while maintaining a simple component API
using the
[compound component](https://kentcdodds.com/blog/compound-components-with-react-hooks)
pattern.

Learn how to build a re-usable web component using slots

Building a Collapsible Web Component with Lit

---
title: Building an Accessible, Re-usable Heading Component
description:
  Learn how to build a re-usable, accessible heading component with React.
date: '2021-04-22'
image: 'grant-ritchie-_-gToenDbXg-unsplash.webp'
---

[HTML headings](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements)
are not semantically complex elements though they are frequently used
inappropriately by both designers and engineers alike.

## Why Use Headings?

Each heading can be specificied with a level (1 through 6) and render text
content to the DOM. Generally, headings are used to group content in a
hierarchical fashion, much like a newspaper or magazine article.

```html
<h1>Man Lands on the Moon!</h1>

<h2>Who Landed?</h2>

<h3>The First Man on the Moon</h3>

<p>Neal Armstrong!</p>

<h3>The Rest</h3>

<p>Buzz Aldrin was also there!</p>

<h2>Were There Aliens?</h2>

<p>Sadly, no.</p>
```

In a traditional document layout, heading levels correspond naturally with the
flow of content. This document flow helps users quickly scan for content
visually and helps screen reader users navigate quickly around a page. WebAIM
wrote a
[great article on the subject](https://webaim.org/techniques/semanticstructure/#headings).

## Common Pitfalls

Both visual designers and developers make some common mistakes when using
headings in their work, largely stemming from the typical connection between
style and semantic meaning.

For better or for worse, modern web applications do not tend to contain long
blocks of structured content, making maintaining a strict heading hierachy more
difficult. Visual designers may, for example, hope to use a heading that _looks
like_ a level 5 heading when, according to the document hierarchy, a level 2
heading might be more appropriate.

Similarly, developers will often (inappropriately) leverage headings as a means
of styling. Without enough knowledge of the importance of the heading hierarchy
of a document, an engineer may reach for an `<h6 />` when a `<p />` with bold
styling was needed.

## Abstraction to the Rescue

Fortunately, building a re-usable `Heading` component abstraction can help
separate the visual presentation from the semantic meaning of a heading instance
without relying on manual, one-off styling.

### Styling

First, let's apply some styling to headings globally that will apply directly to
HTML elements. Generally, styling HTML elements globally should be avoided,
however, styling headings in this manner can help ensure authored content
(possibly provided via a CMS) renders with the relevant hierarchical
presentation.

Take the following CSS, for example, with font size values generated from
[modularscale.com](https://modularscale.com):

```css
h1,
h2,
h3,
h4,
h5,
h6 {
  font-weight: 700;
  font-family: serif;
}

h1 {
  font-size: 2.986rem;
}

h1 {
  font-size: 2.488rem;
}

h3 {
  font-size: 2.074rem;
}

h4 {
  font-size: 1.728rem;
}

h5 {
  font-size: 1.44rem;
}

h6 {
  font-size: 1.2rem;
}
```

### Providing Semantic Control

With styling handled, now we need a re-usable way to generate the heading level
from a single component:

```jsx
import React from 'react'
import './heading-styles.css'

function Heading({ as, children }) {
  const Component = as

  return <Component>{children}</Component>
}

function MyPage() {
  return (
    <>
      <Heading as="h1">My Page</Heading>

      <Heading as="h2">More Information</Heading>
    </>
  )
}
```

### Separate Form from function

With the DOM rendering handled, now we incorporate a new prop `looksLike` that
helps divorce presentation from the underlying semantics. In this example, we
leverage the
[ARIA heading role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role)
paired with the `aria-level` attribute in order to have more granular control
over the DOM semantically:

```jsx
import React from 'react'
import './heading-styles.css'

function Heading({ as, looksLike, children }) {
  const Component = looksLike ? looksLike : as
  const headingLevel = as.replace('h', '')

  return (
    <Component role="heading" aria-level={headingLevel}>
      {children}
    </Component>
  )
}

function MyPage() {
  return (
    <>
      <Heading as="h1">My Page</Heading>

      <Heading as="h2" looksLike="h3">
        More Information
      </Heading>
    </>
  )
}
```

Now, the "More Information" heading _looks_ like a level 3 heading, but is
semantically a level 2 heading.

## Conclusion

Building a re-usable, accessible component abstraction can help improve the
developer experience of a project while also improving the end-user experience.
Spending a little time to introduce such an abstraction can pay off in the long
run, allowing for easier feature development, all while lowering the risk of
accessibility defects.


Learn how to build a re-usable, accessible heading component with React.

Building an Accessible, Re-usable Heading Component

---
title: Encouraging Accessibility Best Practices with Cypress.io
description:
  How to write automated tests that encourage others to adopt best practices and
  avoid introducing invalid HTML.
date: '2021-01-24'
image: 'maarten-deckers-T5nXYXCf50I-unsplash.webp'
---

When building a web site or application with accessibility in mind, laundry
lists of rules and requirements come to mind. This often leads organizations to
adopt [accessibility checklists](http://accessibility.voxmedia.com/) that
hopefully provide designers and engineers with a concrete series of requirements
that all products must meet.

Despite their complexity, nearly all of these requirements start with a
foundation in semantically valid HTML. Though this may sound like a low bar to
meet, many engineers struggle to write semantically valid markup, particluarly
when those engineers may have more expertise in pure programming rather than the
ins-and-outs of HTML.

## Abstractions Upon Abstractions

When building for the web using modern JavaScript frameworks, oftentimes the
actual DOM that is being rendered to the page is abstracted away via several
layers of custom components. These abstractions are great on the surface - they
allow for code re-use, visual consistency, and UX consistency. Unfortunately,
custom components can also cause engineers to lose the forest for the trees, and
ignore the final, rendered markup with which end users interact.

Take this JSX that renders a page with a data table of recipes:

```jsx
export function MyRecipesPage() {
  <Page title="My Recipes">
    <SortableTable data={recipes}>
    <Button to="/">Go Back</Button>
  </Page>
}
```

Looks great! The page works as expected and the code is easy to read thanks to
component abstractions. But how can an engineer have confidence that these
components are rendering valid markup? What if that `<Button>` component is
incorrectly rendering an HTML button instead of an anchor tag? What if
`<SortableTable />` is just a series of `div` and `span` tags rather than a
semantically meaningful data table?

## Automated Testing

Ideally, a layer of automated testing at the component level would catch these
problems, while also encouraging engineers to choose components available to
them that render semantically valid markup.

### Enzyme Shallow Mounting

For years in the React community, testing a page component like this would
probably start with using [Enzyme](https://enzymejs.github.io/enzyme/), a
library with utilities for testing React components in a Node-based virtual DOM
environment like [jsdom](https://github.com/jsdom/jsdom#readme). One would
probably start with something like this using Enzyme's `shallow` method:

```js
describe('MyRecipesPage', () => {
  it('renders a Page with a title', () => {
    const wrapper = shallow(<MyRecipesPage />)
    const page = wrapper.find('Page')

    expect(page).toExist()
    expect(page).toHaveProp('title', 'My Recipes')
  })

  it('renders a SortableTable with recipes data', () => {
    const mockRecipes = []
    const wrapper = shallow(<MyRecipesPage recipes={mockRecipes} />)
    const table = wrapper.find('SortableTable')

    expect(table).toExist()
    expect(table).toHaveProp('data', mockRecipes)
  })

  it('renders a Button that returns the user to the landing page', () => {
    const wrapper = shallow(<MyRecipesPage recipes={mockRecipes} />)
    const button = wrapper.find('Button')

    expect(button).toExist()
    expect(button).toHaveProp('to', '/')
  })
})
```

These tests look like they are verifying the rendered output - but all they are
doing is verifying that the components used in the page component were actually
returned. Do these tests provide future engineers with confidence in the final
rendered DOM? Assuming future engineers were interested in testing the HTML
semantics of the page, they might be concerned with answering the following
questions:

- Does `<MyRecipesPage />` have a valid heading?
- Is the data rendered in a valid HTML table?
- Does the button actually render as a link or does it (incorrectly) render as
  an HTML button?

### Cypress to the Rescue

Refactoring these tests with [Cypress](https://cypress.io) can help address some
of these concerns:

```js
describe('"My Recipes" page', () => {
  beforeEach(() => cy.visit('/recipes'))

  it('renders with a relevant page title', () => {
    cy.title().should('include', 'My Recipes Page') // Checking for a unique <title />
    cy.get('h1').should('be.visible').should('contain', 'My Recipes Page')
  })

  it('renders with a table that contains recipe data', () => {
    cy.get('table').should('be.visible')
    // Verify data renders as expected
    cy.get('tbody tr').eq(0).should('contain', 'Chicken Pot Pie')
    cy.get('tbody tr').eq(1).should('contain', 'Green Curry')
  })

  it('renders with a link to go back to the home page', () => {
    cy.get('a')
      .should('be.visible')
      .should('contain', 'Go Back')
      .should('have.attr', 'href', '/')
  })
})
```

Great! Now these tests run in the browser _and_ are grabbing elements from the
DOM instead of React component abstractions that may or may not be producing the
markup we are expecting.

These tests can be taken a step further using
[Cypress Testing Library](https://www.npmjs.com/package/@testing-library/cypress).

#### Cypress Testing Library

Cypress Testing Library offers a series of methods to help query elements more
granularly, allowing room for code refactors as well as the addition of new
features to the page. If the page were to introduce an additional link, for
example, the prior test checking for the home page anchor tag would fail:

```jsx
export function MyRecipesPage() {
  <Page title="My Recipes">
    <SortableTable data={recipes}>
    <Button to="/">Go Back</Button>
    <Button to="https://google.com">Find More Recipes</Button>
  </Page>
}
```

And now this test would need to changed:

```js
it('renders with a link to go back to the home page', () => {
  // This test was broken by the introduction of another anchor tag!
  // Not ideal since the original "Go Back" link continued to work as expected.
  cy.get('a')
    .eq(0)
    .should('be.visible')
    .should('contain', 'Go Back')
    .should('have.attr', 'href', '/')

  cy.get('a')
    .eq(1)
    .should('be.visible')
    .should('contain', 'Find More Recipes')
    .should('have.attr', 'href', 'https://google.com')
})
```

Instead of grabbing raw HTML elements, the `cy.findByRole` method (made
available via Cypress Testing Library) can be used to check for valid,
accessible DOM output all while reducing the risk of test brittleness:

```js
describe('"My Recipes" page', () => {
  beforeEach(() => cy.visit('/recipes'))

  it('renders with a relevant page title', () => {
    cy.title().should('include', 'My Recipes Page')
    // Using the `name` option helps grab the relevant heading that contains the content we are looking for
    cy.findByRole('heading', { name: 'My Recipes Page' }).should('be.visible')
  })

  it('renders with a table that contains recipe data', () => {
    cy.findByRole('table').within(() => {
      cy.get('tbody').within(() => {
        cy.findAllByRole('row').eq(0).should('contain', 'Chicken Pot Pie')
        cy.findAllByRole('row').eq(1).should('contain', 'Green Curry')
      })
    })
  })

  it('renders with a link to go back to the home page', () => {
    // This test will not be as brittle - it will find a link that has this content
    // no matter how many links are added to the page.
    cy.findByRole('link', { name: 'Go Back' }).should('have.attr', 'href', '/')
    cy.findByRole('link', { name: 'Find More Recipes' }).should(
      'have.attr',
      'href',
      'https://google.com'
    )
  })
})
```

So Cypress Testing Library helped solve three key problems with testing the
recipes page UI:

1. The tests are much less brittle now that they no longer rely on the order of
   DOM elements (nor will they break when new elements are introduced to the
   page)
2. The tests are able to handle valid HTML semantics whether they are derived
   from native HTML tags _or_ valid
   [ARIA roles](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques)
3. When future engineers work on this page, it will be more difficult to
   introduce invalid HTML even if such a bug were introduced via a higher level
   abstraction

An engineering team that leans heavily on `cy.findByRole` as their primary means
of querying elements in their tests will also catch accessibility problems
earlier. If an element is tough to query via `cy.findByRole`, that probably
means that a screen reader user (or even search engine crawler) would have
trouble interpreting the page as well and is an early indication that an
accessibility bug is present.

### Wrapping Up

Moving away from testing higher level abstractions with tools like
[Enzyme](https://enzymejs.github.io/enzyme/) helps protect against the
introduction of invalid markup. By leveraging [Cypress](https://cypress.io) and
[Cypress Testing Library](https://github.com/testing-library/cypress-testing-library)
(particluarly the `cy.findByRole` method) engineers can make automated testing
less brittle _and_ ensure their markup is meeting accessibility requirements all
within a real browser environment.


How to write automated tests that encourage others to adopt best practices and avoid introducing invalid HTML.

A frontend engineering leader driven to create accessible user interfaces at scale.

The latest

Inversion of control in design systems

Building a Collapsible Web Component with Lit

Building an Accessible, Re-usable Heading Component

Encouraging Accessibility Best Practices with Cypress.io