Recommendation for supporting base 16 colors in default dark and light styles including chroma?

[andyfeller]

As a core maintainer of the GitHub CLI, I'd like to support users with low vision needs by limiting our CLIs to base 16 ANSI colors, which users can configure their terminals to render with sufficient contrast for their personal needs.

Before we get to specifics, please let me say how much I appreciate collaborating with glamour maintainers. I'm open to any ideas and suggestions as well as contributing back to the project where possible! 🙇

Problems

There are 4 challenges that I'd like to work with the glamour maintainers as long time supporters and collaborators so other glamour users may benefit:

1. How should CLIs override the default light and dark styles?

   These styles use various 8-bit colors for markdown elements such a document, headers, links, images, in-line code, and code blocks. In order to minimize how much users have to understand glamour and specify a custom glamour style, we want to continue allowing glamour to respond to user's appearance preferences but use slightly different colors.

   I'm unsure how glamour maintainers expect CLI developers to customize these default styles other than:

   1. Hard code overrides for specific, known element styles to use base 16 colors

      This approach is a bit brittle as it requires significant diligence on the user's part to monitor changes within the default styles whenever any dependency is updated. This is likely to lead to inconsistent results.

      var (
          ansiBlack         = stringPtr("0")
          ansiRed           = stringPtr("1")
          ansiGreen         = stringPtr("2")
          ...
      )
      
      func makeDefaultStyleColorsAccessible() {
          // Changes to the `dark` style for users with low vision.
          glamour.DarkStyleConfig.Document.StylePrimitive.Color = ansiWhite             // Original value of 252
          glamour.DarkStyleConfig.Heading.StylePrimitive.Color = ansiBrightCyan         // Original value of 39
          ...
      
          // Changes to the `light` style for users with low vision.
          glamour.LightStyleConfig.Document.StylePrimitive.Color = ansiBlack             // Original value of 234
          glamour.LightStyleConfig.Heading.StylePrimitive.Color = ansiBrightBlue         // Original value of 27
          ...
      }

   2. Completely override the dark and light styles

      Somewhat less brittle except for new markdown elements being added to the default styles, this would ensure glamour is doing exactly what we expect.

   3. Tell users to define their own custom style using GLAMOUR_STYLE environment variable

      This is absolutely the worst approach from a user friendly, out of the box experience! I'd like to believe none of us want to resort to this option.

2. How should CLIs override the terminal256 Chroma formatter for rendering code blocks?

   glamour uses chroma to render code blocks, which can support 3-bit, 4-bit, and 8-bit color depths.

   Unlike the default styles, CLIs cannot easily override the CodeBlockElement rendering necessary to customize this behavior without forking the project.

3. Which colors would glamour maintainers use to make these styles aesthetically pleasing and sufficiently contrasting?

   A colleague pointed me to chalk/ansi-styles when I was researching how to downsample these 8-bit colors to their nearest base 16 colors. Recognizing there is a deeper rabbit hole regarding color quantization, I don't know if this should be an algorithmic decision or something a designer should weigh in on.

   See below for collapsed table I used to convert from 8-bit to 4-bit for proof of concept purposes.

4. Should glamour react to the same ACCESSIBLE env var used by huh to default to an accessible experience?

   Similar to NO_COLOR convention`, the terminal community does not have a standard for users to communicate their need for an accessible experience out of the box.

   I think building upon this foundation will provide a unified experience across charmbracelet projects as we continue to support our low vision user needs. 🫶

References

Conversion table used for proof of concept from 256 colors to 16 colors

In the following chart, any base 16 color already being used was preserved with color codes 16 and higher being downsampled:

8-bit	4-bit
0	0
1	1
2	2
3	3
4	4
5	5
6	6
7	7
8	8
9	9
10	10
11	11
12	12
13	13
14	14
15	15
16	0
17	0
18	0
19	4
20	4
21	12
22	0
23	0
24	0
25	4
26	4
27	12
28	0
29	0
30	0
31	4
32	4
33	12
34	2
35	2
36	2
37	6
38	6
39	14
40	2
41	2
42	2
43	6
44	6
45	14
46	10
47	10
48	10
49	14
50	14
51	14
52	0
53	0
54	0
55	4
56	4
57	12
58	0
59	0
60	0
61	4
62	4
63	12
64	0
65	0
66	0
67	4
68	4
69	12
70	2
71	2
72	2
73	6
74	6
75	14
76	2
77	2
78	2
79	6
80	6
81	14
82	10
83	10
84	10
85	14
86	14
87	14
88	0
89	0
90	0
91	4
92	4
93	12
94	0
95	0
96	0
97	4
98	4
99	12
100	0
101	0
102	0
103	4
104	4
105	12
106	2
107	2
108	2
109	6
110	6
111	14
112	2
113	2
114	2
115	6
116	6
117	14
118	10
119	10
120	10
121	14
122	14
123	14
124	1
125	1
126	1
127	5
128	5
129	13
130	1
131	1
132	1
133	5
134	5
135	13
136	1
137	1
138	1
139	5
140	5
141	13
142	3
143	3
144	3
145	7
146	7
147	15
148	3
149	3
150	3
151	7
152	7
153	15
154	11
155	11
156	11
157	15
158	15
159	15
160	1
161	1
162	1
163	5
164	5
165	13
166	1
167	1
168	1
169	5
170	5
171	13
172	1
173	1
174	1
175	5
176	5
177	13
178	3
179	3
180	3
181	7
182	7
183	15
184	3
185	3
186	3
187	7
188	7
189	15
190	11
191	11
192	11
193	15
194	15
195	15
196	9
197	9
198	9
199	13
200	13
201	13
202	9
203	9
204	9
205	13
206	13
207	13
208	9
209	9
210	9
211	13
212	13
213	13
214	11
215	11
216	11
217	15
218	15
219	15
220	11
221	11
222	11
223	15
224	15
225	15
226	11
227	11
228	11
229	15
230	15
231	15
232	0
233	0
234	0
235	0
236	0
237	0
238	0
239	0
240	0
241	0
242	0
243	0
244	7
245	7
246	7
247	7
248	7
249	7
250	7
251	7
252	7
253	7
254	7
255	7

Screenshot demonstrating native MacOS Terminal where users can customize ANSI color wells to improve color contrast for personal accessibility needs

Additional note for readers: the Basic theme in MacOS Terminal works in conjunction with the Appearance settings in System Preferences, switching to either light or dark based on the time of day. Users like myself may set a different theme to be default, which does not adhere to the Appearance setting.

[meowgorithm]

👋 Hey, @andyfeller! Thanks for jotting all this down. There's a lot of good stuff in here. Here are some initial thoughts:

As a core feature, Glamour will automatically downsample all colors to the highest supported color profile, including Chroma definitions. So, for example, when Glamour is used in the stock macOS terminal (which supports 256 colors), everything will be downsampled to ANSI256. Similarly, in Linux without a window manager, everything will be downsampled to ANSI16.

This means that, given a flag or environment variable, we can totally have Glamour render everything at ANSI16.

All that said, we'd love to bundle a simple ANSI16 theme as well. Accessibility aside, many users like it when everything in their terminal uses the same palette (we recently added an ANSI16 theme to Sequin for this reason).

We also agree about doubling down on supporting ACCESSIBLE, similar to NO_COLOR, especially since we've already started down that path with Huh, and because we agree that it's time for a de-facto standard.

[andyfeller]

Thank you for your insights and diligence regarding charmbracelet/sequin#22, @meowgorithm! ✨ ❤️

I'll be honest I haven't dug into sequin yet nor saw the v2 alpha release of lipgloss, so I'll need to grok the PR and underlying changes to get up to speed.

As a core feature, Glamour will automatically downsample all colors to the highest supported color profile, including Chroma definitions. So, for example, when Glamour is used in the stock macOS terminal (which supports 256 colors), everything will be downsampled to ANSI256. Similarly, in Linux without a window manager, everything will be downsampled to ANSI16.

Good call out! As an exercise, I'll do some experimenting overriding TERM to something with only base 16 colors and seeing how this works with dark and light themes.

All that said, we'd love to bundle a simple ANSI16 theme as well. Accessibility aside, many users like it when everything in their terminal uses the same palette (we recently added an ANSI16 theme to Sequin for this reason).

My primary concern is whether there needs to be separate ANSI16 light and dark themes versus a single theme that supposedly works in both. In the GitHub CLI case, we use color for certain states of various GitHub primitives, which I wouldn't expect change between appearances, however I don't know if markdown rendering should be consistent or not. 🤷

[williammartin]

I just have a minor concern about ACCESSIBLE that it's very general. Accessibility requirements are wide ranging and bucketing them all under one configuration seems like it might unduly impact the experience of some users that only have some requirements e.g. a user may have colour vision deficiency but still want a rich interactive prompting experience.

I don't have a proposal for how to solve this right now, but I did want to raise it early in any discussion. Thanks.

[andyfeller]

I just have a minor concern about ACCESSIBLE that it's very general. Accessibility requirements are wide ranging and bucketing them all under one configuration seems like it might unduly impact the experience of some users that only have some requirements e.g. a user may have colour vision deficiency but still want a rich interactive prompting experience.

I don't have a proposal for how to solve this right now, but I did want to raise it early in any discussion. Thanks.

That's a fair assessment @williammartin and know @jtmcg and I were talking around this to some degree earlier today; this is an easier problem then NO_COLOR with https://no-color.org/ 🤔

Frankly, I don't have an answer right now about the degree that CLIs put in controls to allow users to customize various accessibility concerns:

• should prompting be managed separately from markdown rendering styles?
• should users have application-specific overrides (GH_ACCESSIBLE) on top of a convention?