docs: design system documentation for beginners #603
Description
Improve Design System Documentation For Beginners
The current design system/token documentation is confusing, as the whole design system is confusing. I come from Blazor development and thought Fluent UI would be a good choice as UI language, with this library being the main entry point into the Fluent ecosystem.
Don't get me wrong, I'm all in for algorithmic colors, but the documentation currently does not prepare one for what that means.
So just as an input, let me share my thoughts when I initially discovered the library:
When it comes to colors, the documentation only mentions DesignTokens, with links to a generic documentation, but fails to mention how DesignTokens work within this library.
A simple question the documentation should be able to answer is: How do I apply custom colors? And if it's via DesignToken, which DesignTokens exists and what are they used for?
As far as I understood it, there's no need for theming in this library, as there're only 3 color-related DesignTokens:
NeutralBaseColor- which affects mostly background and font colorAccentBaseColor- the most important tool to give a colorized touch to a websiteBaseLayerLuminance- technically a float, but only used for lightmode/darkmode so two default values are hidden behind theStandardLuminanceenum.
Now there're more tokens that make up a theme (Density, BodyFont, etc.), but in terms of colors that's it I guess?! But there're so much more Tokens - am I expected to change any of them? Most of them sound as if they're computed anyway?!
And if I apply an AccentBaseColor, I cannot expect the color to actually show up. In my case, I thought I'll do a black background (darkmode) with a red button. As I've found out, there's no combination of red on black that satisfies the contrast requirements and it always ends up orange-ish. But within the FAST ecosystem, there's a Color Explorer that allows for this combination! Then again, as mentioned in an Issue, they use the old recipes. Recipe? What's that?
But then there's a Fluent UI React Theme Designer that also allows for red on black background. Is this also outdated? What do React devs have what we don't have?
I think the 3.0.0 release will be awesome, as it adds important components. Nevertheless, I think the documentation, as well as the template, should get their design related parts improved. For example, this library could benefit form it's own Color Explorer as all the others that can be found don't work or apply for various reasons.