CSS variables and abstract design systems

Development
1

Hello all,

Currently, we mainly defined the Abstract Design System (ADS) as a set of Vue Component APIs that need to be implemented by the Design System.

One aspect that wasn’t really made explicit is the use of CSS variables.

To give a bit of context, let’s say one wish to use a few ADS elements to define a UI.

<div class='parent-container'>
  <x-form>
    <x-text-field name='myText'/>
    <x-btn variant='primary'>Submit</x-btn>
  </x-form>
</div>

The developer then wish to decorate the .parent-container with a bit of padding a light rounded border.
In the spirit and keep UIs implementation generic and adaptable to the DS in which they are deployed, the developer will need to implement CSS variables provided by the DS.

Option 1 - Reject this practice

The stricter option is to reject this possibility. Instead, developers are only allow to use UI element formally defined at the ADS level.

Pros:

  • Everything is standard

Cons:

  • A lot of weight is put on the ADS exhaustiveness (and consequence on the DS that need to implement it)
  • Not really flexible, with the risk of bypass when developers are block because of ADS constraints

Option 2 - Provide a clear list of CSS variables

We agree on a clear and documented list of CSS variables that are exposed by the DS. Developers are allowed to use those CSS variables to customize their UI elements in a reusable way.
Developers are advised to use ADS standard UI elements as much as possible.

Pros:

  • Give some room for flexibility, allowing for fine-tuning of the UI elements

Cons:

  • Enlarge the surface of the ADS API

Conclusion

Before proposing a concrete list of CSS variables, I’d like to have a conceptual agreement on the direction to pursue.
I’m +1 for option 2 (and consequently, -1 for option 1) because I think this is a better tradeoff in terms of development cost of the DS, while also giving developers (and designer) some room for fine-tuning their UIs.

WDYT?
Thanks

2

To clarify, in this example a set of the possible variables exposed would be something like

--parent-container-border: ...
--parent-container-color: ...
--parent-container-bg-color: ...

If that’s the case I agree that Option 2 is better from a customization POV. But the variable list would indeed be very extensive.

3

Option 1 - Reject this practice

An additional con I can see is that this accumulation of UI elements would make the ADS more complex. Complexity could be another reason pushing devs to bypass the ADS. Ofc this would apply mostly to new developers for which coding a button from scratch would be faster than to find the exact button they need in the ADS (assuming there is one that fits their needs).

Option 2 - Provide a clear list of CSS variables

I’m not sure to understand the con of this solution. Compared to the option 1, it feels like having a couple more variables is lighter than having a whole new UI element in the ADS (I suppose UI elements in the ADS are considered API).

+1 for option 2, it looks closer to what’s been done historically in XWiki. For XS development option 1 could work. But from what I undestood the ADS is meant to be useful for extensions and customizations too. For those the flexibility of option 2 would be needed.

Maybe we want to separate “generic variables” from “specific variables” with a naming convention. With the example --parent-container-color: var(--g-primary-color) we could have --g-primary-color be a generic variable and --parent-container-color a “specific variable”. All are part of the API but we encourage and make it easier to use the generic variables.

Typically in today’s XWiki, the generic variables could be edited with a few clicks on the colorTheme object while the specific variables would need an extra CSS sheet.
I think it’d be interesting to have at least two levels.

I just realized this is exactly the same as the idea behind Alias and Component-specific tokens from design tokens ^^`

1 Like
4

Not exactly, the idea is more to have a CSS customization for .parent-container that would only rely on variables exposed by the DS API.

The whole point being to rely as much as possible on variables names that would be common to all DS implementations.
Nothing prevents some components to define more specialized variables if that helps, but the goal is to have these variable themselves defined by deriving DS variables.

For instance:

<style scope>
.parent-container {
   background-color: var(--ads-default-background-color);
   padding: var(--ads-padding-xs);
}
</style>
5

Yes this is part of the first cons “A lot of weight is put on the ADS exhaustiveness”.

Probably because it is a much lighter “cons” that the ones of option 1 :slight_smile:

To reassess what I said in my previous message, the goal is to define the smallest set of useful variables, so only the generic variables ones. This is really close to what’s done with XWiki’s theme (the implementation of the DS for XWiki’s skins would basically be a straightforward mapping to these variables)

1 Like
6

I see, thanks for the clarification. It’s closer to how XS works then, I’m okay with it provided we don’t block a component from having their own variables if needed. Third-party DS vary greatly in their implementation, and having the variables set in stone could block them from being adopted (or, at the very least, make it very inconvenient).

I’m still on board with option 2.

Thanks

1 Like
7

+1 for option 2 as well.

Thanks,
Marius