Illustration by Alysheia Shaw-Dansby

The Evolution of the Urban Institute’s Design Library

Data@Urban
8 min readJun 13, 2024

Imagine launching multiple websites in a year, each requiring replicating design elements like buttons, icons, and cards with images, titles, summaries, and dates across different pages. Each of these replications may also require different variations of the card, like the project below:

Previously, our web development and design teams would prototype each site individually before recreating these elements from scratch for every new project. This approach was time-consuming, inconsistent, and often led to sites that weren’t fully accessible, didn’t adhere to the best practices, or failed to align with Urban’s design standards.

Because Urban is a trusted source for changemakers and community leaders looking to improve the well-being of families and communities, we must ensure we’re creating web interfaces that are user-friendly for everyone, compatible with individual users’ assistive technologies like screen readers and speech-to-text, and adhering to best practices for web accessibility standards.

As such, we needed a new system that could leverage reusable components across all our websites. Such a system would enable our developers and designers to focus on crafting innovative solutions — rather than constantly coding or prototyping frequently used elements from scratch — and ensures our websites meet the highest security standards, are easy to maintain, and align with Urban’s mission. This strategic shift was vital for enhancing our ability to deliver innovative, secure digital content that aligned with our core values.

Exploring the shortcomings of our previous design library:

Urban’s web projects began adopting the Atomic design system in 2017. This approach revolutionized our development process by allowing the team to create and utilize reusable components, which were integrated into the templates for Drupal 8 sites (commonly referred to as Pattern Lab). The philosophy behind this approach emphasized several key strategies:

- collaborating early in the design process, which allows developers and designers to compile a catalog of shared tokens and components

- simplifying the coding process and reusing the components for new site features

- maintaining the design system separately from Drupal, making it more manageable and maintainable

- applying Atomic design principles to prototype every element of the design system

Despite the advantages of our existing design system, it had significant drawbacks. Each new Drupal site required us to recreate the entire design system from scratch, a time-consuming and inefficient process. Reusable components were also limited to the Drupal templating system, which restricted their use in our non-Drupal web projects, which prevented us from achieving the full potential of our design system.

When we began to refresh Urban’s main site, we took the opportunity to create a more versatile design system that adhered to the Atomic design principles and could be used in any web application, not just Drupal. Our internal design team began implementing Tailwind CSS for front-end styling, and by 2019, we had developed many of the elements that compromise our current design system, including buttons, font scales, spacing, colors, and various user interface components.

However, some challenges remained. Spacing was solely based on Tailwind CSS values. To bring these remaining components on board, our design team created an improved design system that synchronized every component with Urban’s guidelines and technical framework. This collaborative approach led to the creation of Lyndon in 2021.

Introducing our Lyndon design library

Lyndon — named for former president Lyndon B. Johnson, under whose leadership the Urban Institute was founded — now holds Urban’s design standards, unifying our digital experiences across various projects. Based on the powerful Stencil JavaScript framework, Lyndon generates web components optimized for performance and cross-platform compatibility. This initiative positions Lyndon as a flexible and dynamic toolkit for our designers and web development team, empowering the team to create outstanding, more efficient digital experiences.

Lyndon was crafted in Figma, which allowed us to develop a consistent suite of components, colors, spacing, and typography. Our front-end development team carefully transferred and aligned all components from Figma into Storybook, a tool that allows developers to render and document user interface elements in isolation. Integrating Storybook allowed us to streamline workflows and enhance design consistency, enabling our designers to focus on more complex creative tasks and make building mockups and prototypes more efficient. The images below demonstrate this integration. The top image displays the text style in Figma, and the bottom image shows the corresponding Storybook component. This integration ensures consistent text styles are readily available for use on the site.

Storybook presents our entire component library in an accessible, intuitive layout, acting as a development tool and a living document of our design system. From design tokens like colors and spacing to atomic components such as titles, Storybook offers interactive controls for dynamic experimentation with user interface elements. Storybook preserves these components as a story to use during development, testing, and quality assurance.

As a result, Lyndon’s lightweight, independent components ensure fast loading times and flexibility. With the button component, users can effortlessly customize the text, icon, color variant, link, size, and more by selecting from the dropdown options for each attribute.

The lbj-button component resides within the (src/components) directory, where all components are stored to ensure descriptive naming for widespread project use. (We use lbj prefixes as a nod to former president Lyndon B. Johnson.)

The lbj-button directory includes all related code. The lbj-button.tsx TypeScript file utilizes Stencil to generate the component, with the .tsx extension indicating the use of JSX and TypeScript in development. This setup enables the component to be embedded in HTML as a custom tag, rendering a button styled with Urban’s primary color and a download icon like this:

Expanding Lyndon’s Capabilities:

Aside from the .tsx file, each Lyndon component includes a story file, such as lbj-button.stories.ts. This setup allows the team to visualize and interact with the web component generated by Stencil directly in the user interface, independent of StencilJS, meaning developers don’t need to load the entire application environment, speeding up development cycles and making troubleshooting easier.

Storybook also enables the creation of multiple stories or variations for a single component, representing different features or styles. When introducing a variation to an existing component, we utilize the base component and modify it as needed.

In the image below, the Color Block component is displayed with four different variations, each designed for specific scenarios. One variant, the Color Block Minimal, is typically used to create sections with a uniform background color. Another variant, the Featured Text, is designed for more dynamic use cases, including a list of blocks that feature different background colors, headline options to link to a page or URL, and interactive elements like buttons.

Continually improving our foundations for web design and development

By facilitating more customization options and more efficient development, Lyndon has significantly transformed the way we approach web design and development at the Urban Institute. By implementing this robust design system, we have achieved more consistency across all digital platforms, enhancing user experience. Some specific improvements include:

- Increased efficiency: Development time has been reduced because teams can quickly implement predesigned components instead of crafting new elements from scratch.

- Enhanced consistency: All digital outputs adhere to a unified look, ensuring our brand identity is consistent across platforms and sites.

- More versatility: Lyndon’s adaptable design system extends beyond Drupal to the other web applications we use.

- Improved scalability: As our digital needs grow, Lyndon’s flexible framework makes it easy to scale and incorporate more complex functionalities without disrupting existing structures.

Showcasing Lyndon’s Flexibility:

Already, we’ve seen these benefits in practices. For the Student Upward Mobility Initiative website, we needed to follow Urban’s guidelines while introducing a different font family because of the project’s specific needs and stakeholders’ requests. To accommodate this request, we rolled out a new variation of Lyndon that incorporated the new font family, eliminating the need to code the font for each component. This variation was added to the Lyndon library, which allowed us to render the font by defining the mode attribute in the custom component tags. Below is the same button component from before, except now it has the new font family required by the Student Upward Mobility Initiative site. For this project and moving forward, Lyndon’s flexibility ensures each project can maintain a unique brand identity while benefiting from Lyndon’s robust infrastructure.

“Using the components from Lyndon, our designers and site producers can envision and execute virtually any page layout they can imagine. This not only makes their work more creative but also much more efficient.”
— Dave Connell, Senior Director of Digital Communication

We are committed to continuing Lyndon’s evolution to meet emerging trends and technologies in web development. Our plans include the following:

- continuously adding and updating new components to keep up with the latest web technologies and user expectations

- enhancing Lyndon’s accessibility features to make our digital content reachable to a wider audience and exceeding Web Content Accessibility Guidelines compliance standards

The Road ahead for Lyndon:

In our journey with Lyndon, we’ve turned what was once a web development bottleneck into a pathway for innovation and efficiency. By elevating our design system, we overcame the challenge of repetitive design work and aligned every digital output with our core mission. Today, we’ve set a robust, scalable foundation to embrace future web technologies and follow web accessibility standards. Our user community is instrumental in this ongoing process, helping refine Lyndon into a tool that serves the Urban Institute’s objectives and sets a new benchmark for an accessible digital research platform.

How do you see the future of web development evolving, and what role do you think accessibility will play in it? We invite you to share your thoughts and be a part of Lyndon’s evolving story.

— Farnoosh Johnson

Want to learn more? Sign up for the Data@Urban newsletter.

--

--

Data@Urban

Data@Urban is a place to explore the code, data, products, and processes that bring Urban Institute research to life.