Better describe the accents and shades, and showcase them better in the web UI

[pbsds]

I'll preface this issue by saying i have only used the Web UI so far. Oh, and what a great project!

I am currently having to brute-force my way through when using the web UI to make my theme, which is an indication of a underlying problem: The lack of intention for each shade and accent

Specifically accent1 has no other description than "syntax", and is not showcased at all in the code preview in the web UI. It also seems like the literals in the code preview are colored by accent0, which have the description "error, vcs deletion" description. Some colors are both used in the foreground and in the background, making it hard to create a cohesive color experience.

I propose the following:

• Add code examples for more languages.
  Of interest are languages with explicit typing
• Add a terminal example more user can easily recreate locally.
  This makes for a better reference.
• Switch around some of the accents for better consistency, more on that below
• The shade colors should not be used as both foreground (text) and background colors, there should be a clearly defined separation. Perhaps reserve shade 0, 1 and 2 for background and the rest for foreground colors?

While at it, I suggest the following descriptions from either what I've observed to be their primary use, or what i think they should changed into:

color	current description	proposed description	note
shade0	background color	background color
shade1	UI	UI shading, borders	1
shade2	UI, text selection	UI shading, text selection, buttons	2
shade3	UI, code comments	code comments
shade4	UI	UI hints
shade5	UI	UI titles	3
shade6	foreground text	secondary foreground text
shade7	foreground text	primary foreground text
accent0	error, vcs deletion	error, vcs deletion
accent1	syntax	???	4
accent2	warning, vcs modification	warning, vcs modification
accent3	success, vcs success	literals, success, vcs success
accent4	syntax	success, vcs addition
accent5	syntax	syntax, control flow	5
accent6	syntax, caret/cursor	syntax, directives
accent7	syntax, special	syntax, types, constants

Notes:

1. currently used as the font color in the editor ruler
2. borders currently use this, perhaps move borders to shade1? The terminal example also use this color alot, which i believe misrepresents the normal terminal experience
3. currently used as the editor ruler highlight and the color of the unordered list
4. I have seriously no idea where this is used
5. is currently the text-selection color in the web UI, even though shade2 is supposed to be this going by the current description

They should indicate what the colors will be used for in the templates. And also indicate for the template authors where they should use the colors.

This does not have to be the "hard" definition, but perhaps be more like a common guideline. The 'notes' column however is worth noting, since they describe why the current situation confuse me.

I understand a lot of this came as baggage from base16 schemes

[mjswensen]

@pbsds , thank you so much for taking the time to write this up with great clarity and detail. You have made some excellent points.

I agree that the color descriptions could be clarified. There is a tricky balance to strike, however—each theme renders slightly differently, and different editors/IDEs/terminals may use the colors in slightly different contexts; hence the need to keep the descriptions as general as possible. Obviously there is also the fact that the descriptions are pretty much irrelevant for the other tools that themer supports (like Firefox, Slack sidebar, etc.).

Just some initial thoughts. There is definitely some work to do here.

[shlemas]

I was planning to write this up in a separate issue but saw this related one open already, so I'll add to it. Sorry in advance for the long comment. 😉

I came across themer today and have been playing around with it. Up until now I used base16 but never had the patience to cobble everything together to actually get it up and running myself, always used pre-generated things. It was way easier to get up and running with themer, so thanks!

I noticed one thing in common with base16, which is that the templates for generating terminal themes seem to be using an undocumented convention for mapping accent colors to named ANSI colors. This convention assumes for example that accent5 is blue. This has been an annoying problem with base16 in my experience, where a number of terminal themes generated by the base16-shell project give "wrong" terminal colors, perhaps because theme authors did not keep in mind (or did not know) how specific base00-base0F colors mapped to specific terminal color codes in unrelated projects that were generating terminal themes. (Hard to blame them.)

In general, the themes I see (such as those on the themer website) follow a clear convention for the accent colors, and I think it would be useful to document that convention, because some templates (particularly those generating terminal themes) make hard assumptions about them:

Color Key	Typical Usage	Conventional Color	ANSI Color (themer-iterm, themer-terminal)
accent0	error, VCS deletion	Red	Red
accent1	syntax	Orange	Red (Bright)
accent2	warning, VCS modification	Yellow	Yellow, Yellow (Bright)
accent3	success, VCS addition	Green	Green
accent4	syntax	Cyan	Cyan, Cyan (Bright), Green (Bright)
accent5	syntax	Blue	Blue, Blue (Bright)
accent6	syntax, caret/cursor
accent7	syntax, special	Magenta	Magenta, Magenta (Bright)
shade0	background color
shade1	UI
shade2	UI, text selection
shade3	UI, code comments
shade4	UI
shade5	UI
shade6	foreground text
shade7	foreground text

This of course wouldn't mean theme authors are required to follow this convention. Some themes are weird and limited/monotone. Even still, those themes are going to be put through templates like the terminal theme generators, and those templates are going to make hard assumptions about specific accent colors being "yellow", "blue", etc., per the above table, and authors should at least be aware of it. And for more typical traditional color schemes that define a fuller gamut of colors, they may as well follow the convention - again, for the templates that rely on it. The convention already exists and is relied upon whether it's clearly documented in the readme or not, and I think it's better for it to be documented. The result would hopefully be a more consistent theme ecosystem for themer.

Thanks for reading. BTW I added the ANSI Colors column for more specific info on how the terminal theme templates use them because it's what I looked into first, but I'm not proposing that both columns should be in the readme. The Conventional Colors column would be good enough, because the ANSI Colors column is consistent with it.

[mjswensen]

Thank you for the very clear and thorough writeup, @shlemas . I think what you're saying makes a lot of sense.

I'm going to open up a PR that updates both the readme and the web UI, and would love your feedback to see if it would be adequately helpful.

[mjswensen]

Also would be interested to hear your thoughts, @pbsds — what would you recommend in addition to the changes proposed in the PR?

[pbsds]

Looks fine to me.

I think what initially prompted me to create this issue is how difficult it was to recreate Railscast using themer. (If you visit the link then you'll notice how I for example had to enter the same color in multiple fields and abuse the intermediate shades to faithfully recreate the theme) Themer has met its goal to be a tool to quickly slap together a cohesive theme across multiple programs, and what I got caught up with is is the lack of fine grained control.

Railscast simply doesn't follow the 'color wheel' convention themer facilitates. Perhaps adding a small note about this convention can ease friction?

[mjswensen]

Thanks @pbsds , makes sense.