Technical Story: [description | ticket/issue URL]

Context and Problem Statement¶

As we grow our codebase across two different projects (Adventure Manager and App), we want to build in tools that encourage reuse of design components.

Decision Drivers ¶

• Reuse of well-designed components (build once, build well)
• Make it simpler to work across both projects
• Design consistency for the end user within each project

Considered Options¶

• Customize MUI ad-hoc
• Deisgn system per-project
• Shared design system with atoms
• Shared design system with all components

Decision Outcome¶

We should share atomic design items - buttons, inputs, checboxes etc. Larger components (layouts, templates, etc) should live within the individual projects. We should no longer import atoms direct from MUI, but from our design system.

We can introduce an eslint rule to prevent this:

rules: {
    "no-restricted-imports": [
        "error", {
        "patterns": [{ 
                "group": ["@mui/*"],
                "message": "Import from the design system",
            }],
        },
    ]
}

Then, we can replace:

import { Button } from '@mui/material';

with

import { Button } from '@design/button';

where src/design-system/Button.tsx is just

import { Button } from '@mui/material';
export { Button }

This does nothing meaningful in the short term, but allows us to easily make changes to our core atoms by editing a single file.

For example, to introduce additional CSS across all instances:

// src/design-system/Button.tsx
import { Button } from '@mui/material';
export styled(Button, { ... })

Or to move away from MUI

// src/design-system/Button.tsx
export const Button = () => {
    ...
}

Positive Consequences ¶

• Single place to create atoms and ensure consistent design
• We can put the effort in to design nice components and know that they'll be used everywhere
• No direct reliance on MUI in the codebase
• Shared component behaviour for developers working across projects

Negative Consequences ¶

• Difficult to understand Atoms vs larger components
• Some MUI imports are utils, not component
• Some MUI imports are unlikely to be styled (Box, Stack etc.)

Pros and Cons of the Options ¶

Customise MUI Ad Hoc¶

This is one of our current codebase patterns.

• Easy to move quickly
• Duplication of code
• If code is not duplicated exactly, design inconstencies creep in
• No way of easily updating components

Design System Per Project¶

• Easier for larger components that might behave differently between projects
• More difficult to work between projects
• No way to reuse well-designed components between projects

Shared design system with Atoms¶

• Well designed small components can be shared
• Easy to design once, and update everywhere
• Consistent between projects
• Removes confusion of trying to make larger components work between projects

Shared design system with all components¶

• Would give most consistency
• Tough to make more complex components work across projects
• Less flexible