Apollo Design System

Description

The Apollo design system is a collection of ViewComponents styled using Tailwind CSS based on a modified version of Tailwind UI. Apollo components may also utilize Stimulus or Alpine.js to provide interactivity to a component.

The primary goals of Apollo are to:

  1. Provide a consistent look and feel across the app.
  2. Make it easy for engineers to build UIs by reducing the number of decisions we need to make.
  3. Provide a single place to change the look or behavior of a component, where a change will propagate to the entire app.

To achieve this, Apollo components strive to be opinionated. They should be flexible enough to easily build what you want. However, they should be constrained enough that any UI built with Apollo feels cohesive.

Apollo is designed to be generic and without Wunder-specific code. This approach helps us maintain separation between the design system and the rest of the application. For shared UIs specific to Wunder, we build components, partials, or helpers outside of Apollo, using its components as a sturdy and stable base.

Technology Status at Wunder

Adopt. This is our preferred technology for building UIs.

Notes/Resources

  • For client side interaction see the section on Hotwire.

What to do when a component isn’t quite what we want?

There are multiple options, and each situation is unique and might require something different. That said, the below options are ordered best to worst.

  1. Do nothing—is the new functionality really needed?
  2. Update the existing component to do what we want. All existing usages will have the new functionality.
  3. Add an option to the component, so the old and new functionality is a choice. This enhances flexibility, but comes at a cost. The more options a component has:
    • the harder it is to maintain
    • we have more decisions to make, both product and engineering, when building features
    • the app looks and functions less consistently, which can hinder UX.
  4. (Discouraged) Eject from the existing component, make a custom work around to get the behavior you want for that specific page, at the cost of not using the built-in component.
    • In rare cases, inline styles may be necessary. Ideally, we would find the patterns where inline styles are used, and make first-class features to support their use cases.

Ultimately, choosing an option above is a judgment call, but the above order should be helpful in making the decision.