[Django] #33689: Django theme color variables are inconsistently named and poorly documented
Django
-------------------------------------+-------------------------------------
Reporter: | Owner: nobody
murraylchapman |
Type: | Status: new
Cleanup/optimization |
Component: | Version: 4.0
contrib.admin | Keywords: theme dark mode
Severity: Normal | color variables
Triage Stage: | Has patch: 0
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 0 |
-------------------------------------+-------------------------------------
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/33689>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
-------------------------------------+-------------------------------------
Type: | Status: new
Cleanup/optimization |
Component: contrib.admin | Version: 4.0
Severity: Normal | Resolution:
Keywords: theme dark mode | Triage Stage: Accepted
color variables documentation |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Changes (by Carlton Gibson):
* keywords: theme dark mode color variables => theme dark mode color
variables documentation
* easy: 1 => 0
* stage: Unreviewed => Accepted
Comment:
OK, lets accept as a documentation ticket to begin: if we can get the
skeleton of a style-guide in place, it'll be easier to see/justify
renaming variables.
I've removed the Easy pickings flag as I think is likely a medium sized
project to do well. (Out of interest, were you proposing to create the
style guide? 🙂)
--
Ticket URL: <https://code.djangoproject.com/ticket/33689#comment:1>
Django
-------------------------------------+-------------------------------------
Type: | Status: new
Cleanup/optimization |
Component: contrib.admin | Version: 4.0
Severity: Normal | Resolution:
Keywords: theme dark mode | Triage Stage: Accepted
color variables documentation |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Murray Chapman):
Replying to [comment:1 Carlton Gibson]:
> (Out of interest, were you proposing to create the style guide? 🙂)
This should probably be done by someone with a modicum of visual design
talent, which I don't have 🙂, and familiarity with the Django admin's
existing visual style.... which I don't see documented or described
anywhere. There are probably people more passionate and experienced about
this than me, so I'll defer to any of them.
I can offer some guidance based on a long career building websites,
though:
Scope::
(''Not suggesting that these need to be done as part of this ticket,
but they should be kept in mind'')
* be mindful that visual theme overlaps with usability, accessibility,
brand identity, and widget design
* there are things beyond color that should be made variables (e.g.
margins; border width/radius)
Consistency::
* variables should be consistently named, and refer to concepts rather
than specific use cases or colors
* it should be easy to determine the target of a color: Text?
Background? Border? Shadow?
* text/background color variables should always be paired (current
implementation makes assumptions about text/background pairings that are
difficult to deduce)
Completeness::
* every color should be a variable (some are still hardcoded)
* every variable should be documented and an example given
Accessibility::
* accessibility issues like visual impairment and color blindness
should be considered (good work already done on improving visual contrast)
* usability best practices strongly discourage using color alone to
communicate meaning or state (e.g. don't use a red background and assume
people will know that means "error". Should be accompanied by verbiage or
an icon)
Maintainability::
* very helpful for developers would be a visual "crib sheet" that
shows all colors/widgets on a single web view. Ideally this would be part
of `contrib.admin` (so developers can test theme changes) as well as in
the online documentation
* future commits to stylesheets should be policed for hardcoded
colors, ideally via automation
* technical designs should be mindful of ease of maintenance and
future expansion (e.g. introduction of other CSS variables for things like
border widths)
Django has '''excellent''' documentation and a high-quality/consistent
visual design; I'm hoping we can get this formally defined/declared
somewhere so plugin/extension authors can build consistently on top of it.
--
Ticket URL: <https://code.djangoproject.com/ticket/33689#comment:2>
Django
-------------------------------------+-------------------------------------
Reporter: Murray Chapman | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: contrib.admin | Version: 4.0
Severity: Normal | Resolution:
Keywords: theme dark mode | Triage Stage: Accepted
color variables documentation |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Michael):
I agree with the original poster. It takes a bit of trial and error to
skin the admin. Sometimes you skin something in one situation, and then
the same variable is used elsewhere, and then it clashes (doesnt work
visually) down the line. I also have had clashes with Django CSS custom
property names.
Just a side comment: In the web framework context, it is a common pattern
to use a two letter acronym for namespacing, e.g. `tw` for tailwind, `ng`
for angular. We could prefix all variables with `dj`. e.g. ` --dj-body-
fg`.
Another solution would be to place properties under a top level admin
container instead of `:root`, e.g.
{{{
.admin-top-level-container {
--body-fg: black;
}
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/33689#comment:3>
Django
-------------------------------------+-------------------------------------
Type: | Status: assigned
Cleanup/optimization |
Component: contrib.admin | Version: 4.0
Severity: Normal | Resolution:
Keywords: theme dark mode | Triage Stage: Accepted
color variables documentation |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* owner: nobody => stimver
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/33689#comment:4>
Django
-------------------------------------+-------------------------------------
Reporter: Murray Chapman | Owner: stimver
Type: | Status: assigned
Cleanup/optimization |
Component: contrib.admin | Version: 4.0
Severity: Normal | Resolution:
Keywords: theme dark mode | Triage Stage: Accepted
color variables documentation |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* cc: Sarah Abderemane (added)
--
Ticket URL: <https://code.djangoproject.com/ticket/33689#comment:5>
Django
-------------------------------------+-------------------------------------
Reporter: Murray Chapman | Owner: stimver
Type: | Status: assigned
Cleanup/optimization |
Component: contrib.admin | Version: 4.0
Severity: Normal | Resolution:
Keywords: theme dark mode | Triage Stage: Accepted
color variables documentation |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* cc: Antoliny (added)
--
Ticket URL: <https://code.djangoproject.com/ticket/33689#comment:6>