feat: add support to Color Themes

opauloh commented 1 year ago

Hey all

At my team, we have apps that users can switch between Light and Dark Theme, and having the ability to control that type of token on Figma is something we have been really looking for, and this PR introduces a feature that adds support to that!

How it works: on Figma, you can create extra frames under the Color Themes at the same level as the other colors, and under these Frames, you can have color elements that will then get stored in specific object collections under the color token.

Screenshots

Example of how it would like in Figma:

Example of how it would like in code:

code

Which in a practical example you could use as follows:

// initialize with default theme
let theme = 'lightTheme';

// Primary action button with white color token and with different primary background color according with theme
let button = `<button style="background: ${colors[theme].primary}; color: ${colors.white}">Primary Action</button>`;

// Background color that changes according to the theme
let panel = `<div style=`color: ${colors[theme].emptyShade}`>Panel background</div>`

Description of the changes made

updated the makeColorTokens function to read up to one nested Frame and store Tokens using the frame name
updated docs with the Color Themes Support section
added test cases for Multiple Themes usage

Checklist

[x] I have read the Figmagic Contribution Guideline
[x] The PR title summarizes the change

opauloh commented 1 year ago

pinging @mikaelvesavuori

mikaelvesavuori commented 1 year ago

Hey @opauloh! Sorry for dropping the ball on this, tons at work right now + new projects coming up.

I am generally happy about this, but the issue—and how I have addressed the need for this from others—is that it should suffice to handle this as a simple "meta object" as needed, by you as the user.

Have you verified that component generation works correctly with this? (Manually ideally, since I don't necessarily trust we have tests for that)

opauloh commented 1 year ago

Hey @opauloh! Sorry for dropping the ball on this, tons at work right now + new projects coming up.

No worries @mikaelvesavuori! That's totally understandable; thanks for letting me know

Have you verified that component generation works correctly with this? (Manually ideally, since I don't necessarily trust we have tests for that)

Yes - Component generation doesn't support multi-themes, but it also doesn't break, let's suppose you have a component with a color that only exists on the colors -> theme frame.

In this scenario, when attempting to sync with Figma using --syncElements, Figmagic would warn about No matching token! Hard-coding to expected value

The component will still be created, just without a token assigned to it the color, since it currently only looks for the Colors frame and not for nested frames.

I think this is an acceptable behavior, but I would be happy to add support to components generation on a separate issue / PR. Because there are some nuances, for example, it would need to ensure the same color token exists across all themes, and it would be needed to extend the components to accept a theme prop as well.

for example

interface ButtonProps {
 children: any;
 theme: Theme,
  [propName: string]: {};
}

const Button: React.FC<ButtonProps> = ({ children, theme }) => (
  <ButtonStyled theme={theme} {...props}>{children ? children : "Button text"}</ButtonStyled>
);

And then CSS would be able to refer to the theme like this.

background-color: ${colors[theme]['danger']};

mikaelvesavuori commented 1 year ago

Hi again @opauloh! I am happy to merge this if you add a note/warning that the behavior of generated components will be as you told me above in this thread.

Consider if you have bandwidth to look at solving the issue/problem in a later PR and I will look at that as well.

opauloh commented 1 year ago

Hi again @opauloh! I am happy to merge this if you add a note/warning that the behavior of generated components will be as you told me above in this thread.

Consider if you have bandwidth to look at solving the issue/problem in a later PR and I will look at that as well.

Notes updated! I'll open an issue soon on how to proceed with the generation of the components.

opauloh commented 1 year ago

pinging @mikaelvesavuori