Reconsider Design System

[seanrcollings]

Since I'm moving towards a Elements 3.0 release, I'd also like to consider rethinking the design system that we currently use based on CSS variables

Motivation

The current system has a good chunk of disadvantages:

1. Narrow definition. The system defines color tokens & specific component tokens, but not much else
2. Lack of IDE support. Makes developing with it painful / error-prone
3. Lack of a rigorous definition / naming scheme
4. CSS specificity is challenging, especially combined with styled-components class names
5. Slow to develop with. Having to switch back-and-forth between CSS & your components is tedious.

[seanrcollings]

Option 1: Styled Components Theme & Design Tokens

This option would result in two big changes:

Instead of using CSS Variables as the source of truth for customization, the source of truth is Styled Components Theme. The them would contain a set of design tokens (specifying color, sizing, typography, etc...) that components would then use to style themselves.

Each component would expose a set of "style" props that let you configure things like margins / padding/ colors, etc... This would be the main way in which you tweak the presentation of components. They would still of course expose a className and style prop, for more-direct customization, but the idea would be that it keeps you more "on-rails" so to
speak with the visual presentation.

Advantages

This system would help resolve the above issues thusly:

1. The new system will define a broad set of tokens for things like sizing, spacing, typography etc...
2. The new system is implemented in TS, so all of the design tokens will be known at compile time and can be used for intellisense
3. Since the system is being built from the ground up, I will be reworking the naming to be consistent
4. The customization you set are set directly within the class of the component, so no specificity issues will crop up
5. 99% of customizations can be done via component props & tokens, requiring you to touch the CSS less

Example

import { Button, ThemeProvider, design } from "@atomicjolt/atomic-elements";

const myTheme = design.theme.merge(
  design.themes.elementsTheme, // The default theme
  {
     "colors.primary": "#ff0000", // Override a token for the app
  }
)

function MyApp() {
  // "size.2000" refers to a token in the theme.
   return (
      <ThemeProvider value={myTheme}>
           <Button $paddingLeft="size.2000"> 
               Press Me
           </Button>
      </ThemeProvider>
   )
}

Backwards Compatibility

To make migrating straightforward, we can provide a default theme in elements whose values all reference the pre-existing CSS variables. That way, you can use that theme and it should mostly be a "drop-in" replacement.

[seanrcollings]

Option 2: Styled-System (Chakra UI)

https://www.chakra-ui.com/docs/theming/overview

https://github.com/chakra-ui/chakra-ui/blob/8cbd86c589be646304ca535bc8dadde5cffd1529/packages/react/src/styled-system/system.ts

https://github.com/chakra-ui/chakra-ui/blob/8cbd86c589be646304ca535bc8dadde5cffd1529/packages/react/src/styled-system/config.ts

[seanrcollings]

https://tr.designtokens.org/format/