id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
33689	Django theme color variables are inconsistently named and poorly documented	Murray Chapman	stimver	"I have written a number of UI customizations for Django and it's difficult to be sure I've done the right thing because the color variables names and usage philosophy is inconsistent.

Consider these variables:
{{{#!css
  --body-fg: #333;
  --body-bg: #fff;
  --body-quiet-color: #666;
  --body-loud-color: #000;
}}}

The first two are obvious since they are paired, but it's not clear the `quiet` and `loud` colors are meant to be used as foreground/text or background colors.

Other variables such as `--primary` and `--selected-row` have no suffix and it's unclear how they're supposed to be used.

The `--message-*-bg` variables aren't pared with any `-fg` equivalents; this creates an undocumented dependency on which text colors they are compatible with or even use. Without `-fg` equivalents it's also impossible to precisely control.

I've also seen some variables used as both text and background colors in the Django CSS.

Also: since the scope of these variables is `:root` it's probably a good idea to prefix them all with `--django` to avoid collisions with third-party CSS which may accidentally cause name collisions.

The documentation for the theming feature just points developers at the CSS file but doesn't give any guidance on the philosophy or mechanism. It would really help if there was a consistent naming scheme and style guide for using them."	Cleanup/optimization	assigned	contrib.admin	4.0	Normal		theme dark mode color variables documentation	Sarah Abderemane Antoliny	Accepted	0	0	0	0	0	0