feat(theme): improve color system

[kiaking]

• close fix: improve a11y #2100

At last, finalize the color system of VitePress. The focus is to have good contrast ratio (a11y) and ease of theme customization.

VitePress Color System

I've refined the color system, and defined basics. The colors in VitePress have following "functional" colors.

• Text
• Background (BG)
• Border
• Brand (Accent)

Brand colors have exact same color scale system with 3 levels of solid colors with different brightness, and 1 soft color.

:root {
  --vp-c-indigo-1: #3451b2;
  --vp-c-indigo-2: #3a5ccc;
  --vp-c-indigo-3: #5672cd;
  --vp-c-indigo-soft: rgba(100, 108, 255, 0.14);

  --vp-c-green-1: #18794e;
  --vp-c-green-2: #299764;
  --vp-c-green-3: #30a46c;
  --vp-c-green-soft: rgba(16, 185, 129, 0.14);

  /* ... */
}

• XXX-1: The most solid color used mainly for colored text. It must satisfy the contrast ratio against when used on top of XXX-soft.
• XXX-2: The color used mainly for hover state of the button.
• XXX-3: The color for solid background, such as bg color of the button. It must satisfy the contrast ratio with pure white (#ffffff) text on top of it.
• XXX-soft: The color used for subtle background such as custom container or badges. It must satisfy the contrast ratio when putting XXX-1 colors on top of it.

Now every where in the app uses these colors. So, the minimum work users needs to do when customizing VitePress theme, is to set 5 colors. For example, if we set green as a brand color, it can be used for Vue related project docs (e.g. Vue Router).

:root {
  --vp-c-brand-1: var(--vp-c-green-1);
  --vp-c-brand-2: var(--vp-c-green-2);
  --vp-c-brand-3: var(--vp-c-green-3);
  --vp-c-brand-soft: var(--vp-c-green-soft);
}

Reduced CSS vars across the app

I've updated, and removed styles that were not being used. I kept --vp-c-brand as deprecated since people would be using this (it is aliased to --vp-c-brand-1).

---

[Akryum]

Looking good!

I find the dotted links a bit noisy on a LoDPI screen:

Solid underline are better imo:

[Akryum]

Do you have a solution for the lack of visual indicator in the root-level pane menu and the top main menu?

[kiaking]

@Akryum

Solid underline are better imo:

Good point 😳 Indeed it looks too busy on the first screens shot. Also, dashed underline might be seen as abbr text too 🤔

Do you have a solution for the lack of visual indicator in the root-level pane menu and the top main menu?

For the root-level, no, I don't have any good ideas. But, I think you only need the indicator when there is linked root level menu, and non-linked static root level menu.

If all the root level menu is clickable, user should know by hovering the label. Like in GitBook Docs. Though, still even in GitBook docs the section title is not link.

For top main menu, maybe we should add "Return to top" or change its name to the page title 🤔 But most of the docs I see don't have the top level in here, like Laravel, Tailwind, GitBook, Nuxt.

So I'm not sure why people really want this feature 👀

[Akryum]

I was more thinking of how to distinguish which item in those menus is the current selection (in the screenshots it's "Getting started" in the side pane menu and "Reference" in the top main menu)

[brc-dd]

I was more thinking of how to distinguish which item in those menus is the current selection (in the screenshots it's "Getting started" in the side pane menu and "Reference" in the top main menu)

it seems to be there for me:

which browser+version are you on? or are you emulating achromatopsia and want something like underline/box there? (similar to #2100):

[Akryum]

are you emulating achromatopsia

Yes, only relying on colors it not the most accessible

It's also why I proposed adding icons to the callouts to distinguish between info/warning/danger/tip (especially when the callout title is overridden)

[brc-dd]

Line highlighting in code blocks in light mode looks weird (unrelated to this PR). I'll try swapping out with shikiji, so other themes don't break, and we can still change the default to adaptive themes. I'll also port some more stuff from #2100 back to here.

Edit: On second thoughts, lets skip shikiji for now. I'll have to make many changes to shiki-processor since lineOptions are dropped in shikiji.

[kiaking]

I found that some colors are not fully optimized for light theme (Yellow and green) while creating mockups in Figma. Please hold on this PR. Making adjustments.

[kiaking]

@brc-dd Updated! And, updated the description as well. Please have a look at it one more time. For me this is review ready.

And I've also rethought and made UI more border-less. Now we can remove dimm-2 so we are down to 4 scale.

Also, due to now we are having light themed code blocks, we can delete .vp-adaptive-theme as well by using this new color system 👍

[kiaking]

@Akryum

It's also why I proposed adding icons to the callouts to distinguish between info/warning/danger/tip (especially when the callout title is overridden)

I have designed it. But, would be for another PR.

[brc-dd]

Links don't have sufficient contrast on hover. Instead of changing the color, we probably can change decoration / offset on hover?

[kiaking]

Oh, I didn't know we need contrast on hover 👀 Because if that's so, we need to change button hover styles as well. And Radix don't have contrast ratio on hover state.

Radix button hover 👇

I think we need to give up for hover state on contrasts other wise we will not be able to add subtle color effect and must only rely on strokes and such 🤔