Self-document CSS variable naming conventions

app/styles/themes.scss

@@ -1,30 +1,66 @@
+/*
+# CSS VARIABLE NAMING CONVENTIONS
+
+Primary variables are fully-formed CSS properties.
+Form: --{primary-name}
+Examples:
+  --brand-color
+  --primary-text-color
+  --accent-filter
+
+Meta-variables are combined to make primary variables.
+Form: --{primary-name}_{property}
+Examples:
+  --brand-color_h   (int, hue)
+  --brand-color_s   (percent, saturation)
+  --brand-color_l   (percent, lightness)
+  --brand-color_hsl (csv of the 3 variables above)
+
+Modifiers are variations of primary variables made by modifying their meta-values.
+Form: --{primary-name}--{modifier}
+Examples:
+  --brand-color--faint
+  --brand-color--hicontrast
+  --primary-text-color--faint
+*/
+
 body {
-  --brand-color_hsl: var(--brand-color_h), var(--brand-color_s), var(--brand-color_l);
+  // Primary variables
   --brand-color: hsl(var(--brand-color_hsl));
+  --accent-filter: saturate(1.3) hue-rotate(-20deg) brightness(1.2);
+  --primary-text-color: hsl(var(--primary-text-color_hsl));
+  --background-color: hsl(var(--background-color_hsl));
+
+  // Meta-variables
+  --brand-color_hsl: var(--brand-color_h), var(--brand-color_s), var(--brand-color_l);
+  --primary-text-color_hsl: var(--primary-text-color_h), var(--primary-text-color_s), var(--primary-text-color_l);
+  --background-color_hsl: var(--background-color_h), var(--background-color_s), var(--background-color_l);
+
+  // Modifiers
   --brand-color--faint: hsla(var(--brand-color_hsl), 0.1);
   --brand-color--med: hsla(var(--brand-color_hsl), 0.2);
-  --accent-filter: saturate(1.3) hue-rotate(-20deg) brightness(1.2);
   --accent-filter--hover: saturate(1.3) hue-rotate(-20deg) brightness(1.3);
-  --primary-text-color_hsl: var(--primary-text-color_h), var(--primary-text-color_s), var(--primary-text-color_l);
-  --primary-text-color: hsl(var(--primary-text-color_hsl));
   --primary-text-color--faint: hsla(var(--primary-text-color_hsl), 0.6);
-  --background-color_hsl: var(--background-color_h), var(--background-color_s), var(--background-color_l);
-  --background-color: hsl(var(--background-color_hsl));
 }
 
 body.theme-mode-light {
-  --primary-text-color_h: 0;
+  // Primary variables
-  --primary-text-color_s: 0%;
-  --primary-text-color_l: 0%;
-  --background-color_h: 0;
-  --background-color_s: 0%;
-  --background-color_l: 94.9%;
   --foreground-color: #ffffff;
   --highlight-text-color: hsl(
     var(--brand-color_h),
     var(--brand-color_s),
     calc(var(--brand-color_l) - 8%)
   );
+
+  // Meta-variables
+  --primary-text-color_h: 0;
+  --primary-text-color_s: 0%;
+  --primary-text-color_l: 0%;
+  --background-color_h: 0;
+  --background-color_s: 0%;
+  --background-color_l: 94.9%;
+
+  // Modifiers
   --brand-color--hicontrast: hsl(
     var(--brand-color_h),
     var(--brand-color_s),
@@ -33,18 +69,23 @@ body.theme-mode-light {
 }
 
 body.theme-mode-dark {
-  --primary-text-color_h: 0;
+  // Primary variables
-  --primary-text-color_s: 0%;
-  --primary-text-color_l: 100%;
-  --background-color_h: 0;
-  --background-color_s: 0%;
-  --background-color_l: 20%;
   --foreground-color: #222222;
   --highlight-text-color: hsl(
     var(--brand-color_h),
     var(--brand-color_s),
     calc(var(--brand-color_l) + 8%)
   );
+
+  // Meta-variables
+  --primary-text-color_h: 0;
+  --primary-text-color_s: 0%;
+  --primary-text-color_l: 100%;
+  --background-color_h: 0;
+  --background-color_s: 0%;
+  --background-color_l: 20%;
+
+  // Modifiers
   --brand-color--hicontrast: hsl(
     var(--brand-color_h),
     var(--brand-color_s),