Feat: theme customization

[leweyse]

Theme Customization #139

This is a proposal for a relatively light and controlled custom theming layer.

Points to cover

• Provide the user with a set of custom properties that can be used to change Puck theme.
• Do not overwhelm the user with many options to customize.
• Control the options provided.

Challenge

Color customization is not easy if we want to keep the custom theming layer light. For example:

To use different color shades or opacity values (eg: Dropzone is selected or hovered) there are two options: create multiple custom properties for each interaction (hover, selected, dragging over, etc.) or create one custom property that Puck internally will use with different alpha values.

In this proposal I take the second option using hsl(). It's been used for most components to handle different interactions: ComponentListItem and Layer use it for hover interactions, Dropzone and DraggableComponent use it for the different states to highlight the dropzone, the target, etc.

Solution

Default theme:

Editing_._.-.Google.Chrome.2023-10-19.10-36-57.1.mp4

Custom theme:

Editing_._.-.Google.Chrome.2023-10-19.10-37-50.1.mp4

Config used:

:root {
  --puck-background: 229 22% 29%;
  --puck-foreground: 216 100% 98%;
  --puck-dropzone: 26 80% 73%;

  --puck-accent: 10 61% 78%;
  --puck-accent-foreground: 0 0% 0%;

  --puck-muted: 10 61% 78% / 0.05;
  --puck-muted-foreground: var(--puck-accent);

  --puck-popover: 229 22% 15%;
  --puck-popover-foreground: 216 100% 98%;

  --puck-border: 229, 22%, 50%;

  --puck-input: 0 0% 50%;
  --puck-input-alpha: 0.5;

  --puck-shadow: 229 22% 29%;

  --puck-radius: 0.5rem;
}

[vercel]

@leweyse is attempting to deploy a commit to the Measured Team on Vercel.

A member of the Team first needs to authorize it.

[leweyse]

Hi @chrisvxd!

This is not a complete proposal, but I'd like to know your opinion before moving forward.

This approach is quite challenging, specially if the goal is to provide more customization options.

[chrisvxd]

Hey @leweyse! This is awesome.

I'd say that I wasn't quite ready for us to jump into #139 (we typically marge issues as "Ready" when we're ready, but we haven't documented that process anywhere yet), but also appreciate it's easier to discuss things with code sometimes.

General points on this implementation:

1. Generally, I like CSS properties as an easy way to apply a theming layer, and it is compatible with some of the other options proposed in Theming #139 (like full component overrides)
2. If you can try and keep other CSS changes out of this PR, that would make it easier to review. I noticed you've changed a few pixel values, or added a shadow here and there.
3. We should avoid using inherit for colors because we don't know what other CSS is running on the page. We don't want the user's global CSS polluting the Puck CSS. This happens frequently. See fix: ensure form styles override global styles #98, fix: style clashing with dark mode root element #107, fix: scope styles in OutlineList #105.
4. We probably shouldn't be, but we use the Puck components inside the demo app. I'm noticing this in your preview frame. I don't think it really matters, because users won't be running the demo app.

To use different color shades or opacity values (eg: Dropzone is selected or hovered) there are two options: create multiple custom properties for each interaction (hover, selected, dragging over, etc.) or create one custom property that Puck internally will use with different alpha values.

In this proposal I take the second option using hsl(). It's been used for most components to handle different interactions: ComponentListItem and Layer use it for hover interactions, Dropzone and DraggableComponent use it for the different states to highlight the dropzone, the target, etc.

I think I would prefer the finer grained control, but I'm not totally sure. I imagine full control will probably be necessary for consumers to achieve on-brand color palettes, and accessibility. We could possibly use HSL (or color-mix) as a fallback, if the user doesn't specify all the values.

Your CSS property suggestions are interesting. I need to think about this properly before giving a proper response because this is the most important piece of the proposal -- they essentially act as a public facing API and any renames become breaking changes.

Initial impressions:

• I think colors properties should all carry the color prefix, i.e. puck-color-foreground
• As suggested above, we might want to introduce more properties for different states (i.e. puck-color-interactive, puck-color-interactive-hover, puck-color-interactive-focus, puck-color-button-text for links and buttons)
• How would someone configure spacing and typography?

I'll probably have more thoughts on this, but wanted to share my first take. Would also be interested to hear what @monospaced thinks.

[BleedingDev]

May I suggest LCH instead of HSL, because they keep the lightness as perceived by human? :)

https://caniuse.com/?search=lch

[chrisvxd]

Hi @leweyse! Really appreciate all the effort here.

We'd be happy to consider the introduction of some descriptive CSS properties like you're suggesting, but would want to see some changes to your proposal:

1. Removal of all stylistic changes
2. Use of existing raw color properties (e.g. --puck-color-azure-4) for all new descriptive properties, instead of HSL
3. Introduction of descriptive color properties for different states (--puck-color-interactive, --puck-color-interactive-hover), rather than inferring from HSL
4. Removal of prettier formatting for CSS (this would be easier to review as a separate PR with the formatting applied)

Additionally, we would likely keep this undocumented until the styles are stabilised. This may involve us renaming these properties and introducing breaking changes.

Some reasoning:

• HSL breaks the default Puck color system, which is based on the Measured color system and supports WCAG 2.1 AA compliance
• HSL generally makes it difficult to control the accessibility and branding of third party theming layers
• We're considering revamping the Puck identity (which will include the color system), and HSL would make it difficult to implement
• Dark mode is something we want to fully support, and needs to be a consideration of any color system we support

If you're happy with that approach, we'd appreciate it if you could update your PR with a new proposal.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
puck-demo	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Oct 24, 2023 3:54pm

[leweyse]

Hi @chrisvxd! Sorry for not being active, I've been quite busy.

From your first reply:

Hey @leweyse! This is awesome.

I'd say that I wasn't quite ready for us to jump into #139 (we typically marge issues as "Ready" when we're ready, but we haven't documented that process anywhere yet), but also appreciate it's easier to discuss things with code sometimes.

General points on this implementation:

1. Generally, I like CSS properties as an easy way to apply a theming layer, and it is compatible with some of the other options proposed in Theming (opinions wanted) #139 (like full component overrides)
2. If you can try and keep other CSS changes out of this PR, that would make it easier to review. I noticed you've changed a few pixel values, or added a shadow here and there.
3. We should avoid using inherit for colors because we don't know what other CSS is running on the page. We don't want the user's global CSS polluting the Puck CSS. This happens frequently. See fix: ensure form styles override global styles #98, fix: style clashing with dark mode root element #107, fix: scope styles in OutlineList #105.
4. We probably shouldn't be, but we use the Puck components inside the demo app. I'm noticing this in your preview frame. I don't think it really matters, because users won't be running the demo app.

To use different color shades or opacity values (eg: Dropzone is selected or hovered) there are two options: create multiple custom properties for each interaction (hover, selected, dragging over, etc.) or create one custom property that Puck internally will use with different alpha values.
In this proposal I take the second option using hsl(). It's been used for most components to handle different interactions: ComponentListItem and Layer use it for hover interactions, Dropzone and DraggableComponent use it for the different states to highlight the dropzone, the target, etc.

I think I would prefer the finer grained control, but I'm not totally sure. I imagine full control will probably be necessary for consumers to achieve on-brand color palettes, and accessibility. We could possibly use HSL (or color-mix) as a fallback, if the user doesn't specify all the values.

Your CSS property suggestions are interesting. I need to think about this properly before giving a proper response because this is the most important piece of the proposal -- they essentially act as a public facing API and any renames become breaking changes.

Initial impressions:

• I think colors properties should all carry the color prefix, i.e. puck-color-foreground
• As suggested above, we might want to introduce more properties for different states (i.e. puck-color-interactive, puck-color-interactive-hover, puck-color-interactive-focus, puck-color-button-text for links and buttons)
• How would someone configure spacing and typography?

I'll probably have more thoughts on this, but wanted to share my first take. Would also be interested to hear what @monospaced thinks.

I agree with the comments shared. I think I overthought about a "simple" layer, but I agree that the best would be to have a granular way to customize the editor.

Hi @leweyse! Really appreciate all the effort here.

We'd be happy to consider the introduction of some descriptive CSS properties like you're suggesting, but would want to see some changes to your proposal:

1. Removal of all stylistic changes
2. Use of existing raw color properties (e.g. --puck-color-azure-4) for all new descriptive properties, instead of HSL
3. Introduction of descriptive color properties for different states (--puck-color-interactive, --puck-color-interactive-hover), rather than inferring from HSL
4. Removal of prettier formatting for CSS (this would be easier to review as a separate PR with the formatting applied)

Additionally, we would likely keep this undocumented until the styles are stabilised. This may involve us renaming these properties and introducing breaking changes.

Some reasoning:

• HSL breaks the default Puck color system, which is based on the Measured color system and supports WCAG 2.1 AA compliance
• HSL generally makes it difficult to control the accessibility and branding of third party theming layers
• We're considering revamping the Puck identity (which will include the color system), and HSL would make it difficult to implement
• Dark mode is something we want to fully support, and needs to be a consideration of any color system we support

If you're happy with that approach, we'd appreciate it if you could update your PR with a new proposal.

These are fair points and I'll be glad to work on those changes. I have a couple busy days ahead, so I'll share an update during the weekend or starting next week.

[chrisvxd]

Great thanks @leweyse! No rush on this one, just when you get the time. If you have to close it, we'll likely pick this up in due course.

[leweyse]

I close this PR to have a fresh start. Still working on it.