"Dim the gutter" setting appears to do nothing #317

Activity

1. flyingrobots

   added

   bugSomething isn't workingSomething isn't working

   on Sep 7, 2026
2. flyingrobots commented on Sep 7, 2026

   

   flyingrobots

   on Sep 7, 2026

   OwnerAuthor

   More actions

   Investigated. The setting is not broken in code, and I backed out an attempted fix because it violated two existing invariants. Recording the diagnosis so the next attempt starts from the real constraint.

   What is actually happening

   Dimming is expressed only as the ANSI SGR 2 "faint" attribute. applyGutterVariant in src/ui/jedit-themes.ts sets identical foreground colours for both variants and distinguishes them purely by modifier:

   for (const token of Object.values(tokens)) {
     token.backgroundColor = variables.surface;
     if (variant === GUTTER_VARIANT.Dimmed) {
       token.modifiers = [JEDIT_TEXT_MODIFIER.Dim];
     }
   }

   Measured across all 8 built-in themes and all 9 gutter tokens, the rendered foreground RGB is identical between gutter.normal and gutter.dimmed — channel distance 0 in every case, contrast ratio unchanged to two decimals.

   So the toggle does mutate the model, the model does reach the renderer, and the renderer does select a different token set. Whether anything appears on screen depends entirely on whether the terminal implements SGR 2. Many do not, and render faint identically to normal.

   Why this is not a one-line fix

   spec/theme-switch.spec.mjs already constrains both variants:

   • token.foregroundVariables.length > 0 — foregrounds must be named palette variables, not literal RGB
   • contrastRatio(fgRGB, bgRGB) >= 3 — applied to dimmed as well as normal

   I tried blending the dimmed foreground toward the surface. It produced a visible difference in every theme, but it fails both rules: an RgbColor has no variable name, and a genuinely dimmer colour cannot also hold contrast ≥ 3 against the same surface. Reverted.

   Read together, those two rules plus the identical colours suggest the current design is deliberate: keep the gutter legible and traceable to named palette variables, and delegate the visual dimming to the terminal.

   Options, all requiring a decision rather than a patch

   1. Introduce a named dimmed palette variable per theme (e.g. mutedDim) and relax the contrast floor for the dimmed variant only. Keeps naming discipline; needs a considered floor, and pairs naturally with Audit every jedit theme for legibility #309.
   2. Keep SGR 2 and set expectations — document that gutter dimming requires a terminal implementing faint, and note it in the setting label.
   3. Remove the setting, per the suggestion in Settings drawer covers the surface it configures #318 that it may not earn its place.

   My recommendation is 1, folded into the #309 theme audit, since that work has to establish per-surface contrast floors anyway. 3 is defensible if the setting is not worth the palette work.

   No code change on this issue.