WIP: color modes docs

[BinaryMuse]

This PR is a WIP for improving the Primer CSS "Support -> Color system", "Support -> Variables", and "Utilities -> Colors" pages for a post-color-modes world.

• Preview (color system)
• Preview (variables)
• Preview (color utilities)
• Preview (migration guide)

Color scales

Now that most of the usable colors are represented by functional variables, there's less of a need to document the individual color scale values. However, I've included them just in case they're needed for some dotcom hacks.

These tables are automatically generated based on the values from Primer Primitives.

Functional variables

I had more trouble when starting to look into documenting the functional variables. There are a huge number of them, and arguably some of them probably shouldn't really be used by end-users of the system at all. For example, --color-calendar-graph-day-L2-bg serves a very specific purpose and that color shouldn't be used for any other components, even if the color matches, so does it need to be documented at all? Further, some of the values aren't colors at all, e.g. --color-btn-primary-shadow is 0 1px 0 rgba(27,31,35,0.1) (and, again, is for a specific component, so should it be documented at all?)

For this category of colors, I'm starting to lean toward hand-written documentation, detailing how to pick one of the reusable functional colors (e.g. how do I pick between text-primary vs text-secondary vs text-tertiary) rather than just generating a huge list of all the functional colors.

Variables

For the "Support -> Variables" page, I think we can keep this the way it is, just with the Sass color variables removed (but leave the other Sass variables, like $spacer-* etc).

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/primer/primer-css/rdjeaawx3
✅ Preview: https://primer-css-git-mkt-color-modes-docs.primer.now.sh

[BinaryMuse]

/cc folks who might have opinions on this: @colebemis @emplums @auareyou @broccolini @simurai

[BinaryMuse]

Note to self: move capitalize to CSS

[simurai]

Would this make state-hoverPrimaryBg into state-hover-primary-bg? That would be nice for copy&pasta.

[colebemis]

I used the kebabCase function from lodash to convert hoverPrimerBg to hover-primer-bg in https://primer.style/primitives

[simurai]

I had more trouble when starting to look into documenting the functional variables. There are a huge number of them, and arguably some of them probably shouldn't really be used by end-users of the system at all.

Hmm.. yeah, I have the same concerns. I think initially we should encourage people to only use the "global" variables. The rest is kinda "private".

I also wonder... now that all the variables got moved to primer/primitives, do we even wanna show them in the Primer CSS docs? Or how should it be different to https://primer.style/primitives/? I guess we should have the utilities still in Primer CSS since technically still lives in primer/css.

Otherwise the docs itself look nice. ✨

[BinaryMuse]

I think initially we should encourage people to only use the "global" variables. The rest is kinda "private".

I agree. I'm trying this out now, will see how it goes. I want to find a good balance between having docs that are useful and well presented as well as docs that don't go out of date when we change Primer Primitives 🙈

I also wonder... now that all the variables got moved to primer/primitives, do we even wanna show them in the Primer CSS docs? Or how should it be different to https://primer.style/primitives/?

Good question. /cc @colebemis for thoughts. Is the plan to add the Primer Primitives docs to the primer.style homepage, or was this a temporary or experimental thing?

[colebemis]

Is the plan to add the Primer Primitives docs to the primer.style homepage, or was this a temporary or experimental thing?

I created primer.style/primitives as a temporary way to reference color variables. But I think it could make sense to build it out into something more permanent. Then we can link to it from the Primer CSS docs.

[auareyou]

I think initially we should encourage people to only use the "global" variables. The rest is kinda "private".

I agree. I'm trying this out now, will see how it goes. I want to find a good balance between having docs that are useful and well presented as well as docs that don't go out of date when we change Primer Primitives 🙈

Agree as well! What I was hoping for is to write a guide on how to use the global variables and use for our color docs as well. I have a lot of hoarded notes I can provide to either help with this or help wrtiing it .

[BinaryMuse]

I have a lot of hoarded notes I can provide to either help with this or help wrtiing it .

Thanks, @auareyou, I'd love any notes you've collected! I'll be putting the finishing touches on a first go next week.

[cheshire137]

What's the URL for this file? I still find myself needing to refer to the new names like color-text-secondary instead of text-gray, and the old URL I was using, https://github.com/primer/css/blob/mkt/color-modes-docs/docs/content/support/v16-migration.mdx#utility-classes, now 404s. 🙇‍♀️

[simurai]

@cheshire137 Ahh.. sorry. Updated the links. Eventually it will show up in https://primer.style/css, but for now you can see it with this preview URL: https://primer-css-git-release-1600-primer.vercel.app/css/support/v16-migration

[cheshire137]

Thank you!