Re: [Django] #33689: Django theme color variables are inconsistently named and poorly documented

[Django]

#33689: Django theme color variables are inconsistently named and poorly 
documented
-+-
 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
-+-
Changes (by Sarah Abderemane):

 * cc: Sarah Abderemane (added)

-- 
Ticket URL: 
Django 
The Web framework for perfectionists with deadlines.

-- 
You received this message because you are subscribed to the Google Groups 
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-updates+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-updates/010701917e71738a-2bbe3e26-eedd-47bc-abca-ff400b1d0da5-00%40eu-central-1.amazonses.com.

Re: [Django] #33689: Django theme color variables are inconsistently named and poorly documented

[Django]

#33689: Django theme color variables are inconsistently named and poorly 
documented
-+-
 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
-+-
Changes (by stimver):

 * owner:  nobody => stimver
 * status:  new => assigned


-- 
Ticket URL: 
Django 
The Web framework for perfectionists with deadlines.

-- 
You received this message because you are subscribed to the Google Groups 
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-updates+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-updates/0107018717576b4f-2f3da279-2549-4726-90bd-6403d2f80461-00%40eu-central-1.amazonses.com.

Re: [Django] #33689: Django theme color variables are inconsistently named and poorly documented

[Django]

#33689: Django theme color variables are inconsistently named and poorly 
documented
-+-
 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: 
Django 
The Web framework for perfectionists with deadlines.

-- 
You received this message because you are subscribed to the Google Groups 
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-updates+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-updates/010701847b5a3ed6-0fa1f98b-4fa8-4d5b-a006-f6faa443a15f-00%40eu-central-1.amazonses.com.

Re: [Django] #33689: Django theme color variables are inconsistently named and poorly documented

[Django]

#33689: Django theme color variables are inconsistently named and poorly 
documented
-+-
 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 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: 
Django 
The Web framework for perfectionists with deadlines.

-- 
You received this message because you are subscribed to the Google Groups 
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-updates+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-updates/01070180ba59b249-31a628de-d1d6-4e4c-80c3-70cf1712df72-00%40eu-central-1.amazonses.com.

Re: [Django] #33689: Django theme color variables are inconsistently named and poorly documented

[Django]

#33689: Django theme color variables are inconsistently named and poorly 
documented
-+-
 Reporter:  murraylchapman   |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
-+-
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: 
Django 
The Web framework for perfectionists with deadlines.

-- 
You received this message because you are subscribed to the Google Groups 
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-updates+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-updates/01070180ad89582d-b73ab4b2-2d64-47fe-9060-75fca01c8cd7-00%40eu-central-1.amazonses.com.

[Django] #33689: Django theme color variables are inconsistently named and poorly documented

[Django]

#33689: Django theme color variables are inconsistently named and poorly 
documented
-+-
   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: 
Django 
The Web framework for perfectionists with deadlines.

-- 
You received this message because you are subscribed to the Google Groups 
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-updates+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-updates/01070180ab227eb7-bfda4566-b3d5-4f68-b9a4-9aa63ba4dc1e-00%40eu-central-1.amazonses.com.