docs: Amend code examples to Codex WikimediaUI theme style
Open, Needs TriagePublic
Actions

Assigned To

None

Authored By

	Volker_E
	Jan 10 2024, 1:26 PM

Description

Background

With updated VitePress in T352587: Upgrade Codex to Vite 5.x and Vitepress 1.0 the software features a number of new vars, that are not covered by DST design decisions yet:

--vp-code-block-color: rgba( 255, 255, 245, 0.86 );
--vp-code-block-bg: #292b30;
--vp-code-block-divider-color: #000;
--vp-code-color: var( --color-emphasized );
--vp-code-lang-color: rgba( 235, 235, 245, 0.38 );
--vp-code-tab-text-color: rgba( 235, 235, 245, 0.6 );
--vp-code-tab-hover-text-color: rgba( 255, 255, 245, 0.86 );
--vp-code-tab-active-text-color: rgba( 255, 255, 245, 0.86 );

Goal

Ensure that all code interface parts on the Codex documentation site are using design system colors.

Details

	Subject	Repo	Branch	Lines +/-
	Update Codex from v1.2.1 to v1.3.0	mediawiki/core	master	+10 K -10 K
	docs: Fix code color regression and contrast issue	design/codex	main	+2 -1

Customize query in gerrit

Related Objects
Search...

		Status	Subtype	Assigned	Task
		Open		None	T304062 docs: Codex doc site visual design/user experience improvements
		Open		None	T354759 docs: Amend code examples to Codex WikimediaUI theme style

Event Timeline

Volker_E renamed this task from docs: Amend code examples to Codex Wikimedia UI style to docs: Amend code examples to Codex WikimediaUI theme style.Jan 10 2024, 1:26 PM

Volker_E created this task.

Volker_E mentioned this in T304062: docs: Codex doc site visual design/user experience improvements.

Change 989495 had a related patch set uploaded (by VolkerE; author: VolkerE):

[design/codex@main] docs: Fix minor code color regression

https://gerrit.wikimedia.org/r/989495

gerritbot added a project: Patch-For-Review.Jan 10 2024, 1:29 PM

Volker_E mentioned this in T352587: Upgrade Codex to Vite 5.x and Vitepress 1.0.Jan 10 2024, 1:31 PM

@Volker_E should this be in the sprint?

CCiufo-WMF moved this task from Inbox to Triaging on the Design-System-Team board.Jan 10 2024, 2:35 PM

Ah never mind, I see this will require a bit of decision making on which tokens, and where. I'm going to backlog it for now.

@Volker_E adding in these new variables was necessary to work around an issue in the default Vitepress theme, where some of our dark code theme colors were being overridden by the light docs theme. Since we don't switch between light and dark mode (which Vitepress kind of expects now), we had to force the code styles to remain the same at all times.

The actual colors in question come from Dracula, a color theme for PrismJS (our syntax highlighting library). The code for this color theme in Prism does not expose CSS variables so I had to create some with matching values here to restore our previous styles after upgrading Vitepress.

I don't think these colors should be considered part of Codex and don't see a need to expose them for others to use – this is purely for our own docs site.

Codex could some day expand to include a color scheme for syntax highlighting for use around the Wiki-verse (I think this would be cool to do eventually), and if that happens then we should update our own docs to match. But in the mean time I think it's okay to just use an off-the-shelf syntax theme for the purposes of documenting our code which we do not consider a part of our own design system.

I am not so much concerned about the syntax highlighting colors itself than about the code section background and some minor breakage of WCAG contrast in the coding language tag that we should not feature on our design system documentation, as it's really big visual breakage of our system, where we already have similar colors and rules to apply in place.