Proposal: Better theme system for the dApp Kit

[kkomelin]

Problem/Motivation

(1) Current dApp Kit theme system which is based on Vanilla Extract CSS-in-JS solution is not easy to customize which prevents the Connect Button and Connect Popup from being adopted wider.

The classes which current setup of Vanilla Extract produces are scoped, for example [data-dapp-kit].Button_buttonVariants_variant_primary__x1s81q1, so you cannot easily override them through custom external CSS.

Many popular ecosystem projects (not by Sui Foundation) use their own custom connect buttons - we need to know why. Maybe historically because they had been built before the dApp Kit release or maybe because it's hard to integrate the connect button and popup into existing design built with Tailwind or Mui for example.

(2) Current theme system doesn't provide styles for the dark mode. An attempt to add it has been left without attention probably because of some more important priorities.

(3) Current theme system doesn't rely on Radix color scheme/variables even though the dApp Kit uses Radix under the hood. Radix has its own set of CSS variables, which the dApp Kit is not using currently.

To sum up, if one wants to integrate the ConnectButton from the dApp Kit into their project, they need to marry Radix styles, dApp Kit styles and Tailwind theme.

Current Workaround

Currently I use the following workaround for my Tailwind-based projects:

(1) I define a CSS variable for a common style, for example fontFamily:

/* index.css */
:root {
  --sds-font-inter: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif;
}

(2) I override dApp Kit theme settings using my newly created CSS variable:

// theme.ts
export const lightTheme: ThemeVars = {
  // ...
  typography: {
    fontFamily: 'var(--sds-font-inter)',
    // ...
  },
}

(3) I pass the theme to the dApp Kit wallet provider:

// main.tsx
<WalletProvider theme={lightTheme}>
  {children}
</WalletProvider>

If there is a Radix CSS variable for something like background color, we need to use it in the dApp Kit themes to better marry the different theme systems.

But this solution doesn't give me full control. For example, I still cannot change the button padding, for example, because it is not extracted to a CSS variable:

[data-dapp-kit].Button_buttonVariants_size_lg__x1s81q4, [data-dapp-kit] .Button_buttonVariants_size_lg__x1s81q4 {
    border-radius: var(--dapp-kit-radii-large);
    padding: 16px 24px;
}

Better Solution

I suggest us starting a discussion on how we can unify styles in the dApp Kit theme system, provide the default dark theme and make the Kit theme more customizible.

[williamrobertson13]

Hey @kkomelin! Thank you so much for the feedback here! I'll provide some of the reasoning behind how we approached the pre-built component part of dApp Kit, and I'll also convert this to a discussion in case other folks want to chime in with any struggles/suggestions/ideas!

The goal of dApp Kit is to provide React builders with an all-in-one library for easily creating decentralized applications and streamlining many common functionalities needed by decentralized applications. As part of this, we ship a set of lower-level hooks and the pre-built component kit. I'll mention that if you're not getting the right level of customization out of the pre-built components, you can always opt to re-construct your own components using the wallet-related hooks provided by dApp Kit. With that said, we do have a lot of improvements to make to the theming system so that fewer folks feel the need to roll custom components - a default dark theme as you mentioned above, more theming customization options, better documentation, etc. This is unfortunately the current world today since we haven't been able to prioritize these improvements.

Now back to some of the technical decision-making! We use vanilla-extract as opposed to solutions like Tailwind or dynamic CSS-in-JS libraries so we can ship raw CSS stylesheets with the library. This has the benefit of not creating differing styling dependencies between dApp Kit and applications, which means that applications don't have to be concerned with how CSS is generated/built for dApp Kit. vanilla-extract also provides nice APIs for theming which made this solution attractive over plain CSS modules for example. The CSS scoping aspect is also intentional so application CSS styles don't accidentally interfere with the styles needed to properly display the pre-built UI components. We've found that shipping pre-styled UI components is difficult but this is the most reasonable solution.

The next thing I'd call out is that while dApp Kit uses Radix Primitives under the hood for accessible/flexible UI primitives, we don't expect folks to use Radix Themes or Colors in their apps. To support other design systems like MUI, Headless, etc. we don't take an opinionated stance here and let folks plug whatever variables or values they want into the dApp Kit theme. If plugging the correct variables from Radix Themes was a pain or not giving the level of customization you need, I'd roll custom components that more or less stitch together the existing components in dApp Kit but using the base components provided by Radix Themes.

If you have any other pain points or feedback, I'd love to better understand them as we continue to work on dApp Kit :)