search

tinted-theming / basenext

DRAFT version of BaseNext style specification
MIT License
7 stars 0 forks source link

Needs review/feedback #1

Open joshgoebel opened 2 years ago

joshgoebel commented 2 years ago

@belak @JamyGolden

Could you both please read style_guide.md and schema_spec.md and provide any thoughts? Right now:

Looking for feedback on the spec itself from an schema implementors perspective - ie, if everything is clear, makes sense, and you could set down and make a scheme after reading the spec...

Previous schema_spec is found in builder, but we had discussed moving it back out again to simplify the builder spec.

joshgoebel commented 2 years ago

If you have broad sweeping changes/concerns I'd prefer to discuss them, but if you just want to fix/tidy up some things feel free to open a PR.

mikeduminy commented 2 years ago

diff_deleted is used as an example override. Where could one find the list of all possible overrides?

joshgoebel commented 2 years ago

The palette table in the spec is intended to be exhaustive unless we keep adding then we likely need a separate list.

joshgoebel commented 2 years ago

But we are still in the middle of discussing - you can find the thread over in the main project repository.

bspellmeyer commented 2 years ago

Looking at the style guide, the scheme spec and the builder requirements, I find the spec somewhat confusing.

The style guide states that a theme author is still limited to 16 colors. But the spec does not enforce any limit on the number of colors used.

Take the following color scheme:

scheme: "does-not-build"
author: "John Doe"

variables:
  $red: "#FF0000"

customize:
  diff_deleted: $red

default:
  base00: "#1C2023"
  base01: "#393F45"
  base02: "#565E65"
  base03: "#747C84"
  base04: "#ADB3BA"
  base05: "#C7CCD1"
  base06: "#DFE2E5"
  base07: "#F3F4F5"
  base08: "#000000"
  base09: "#000011"
  base0A: "#001122"
  base0B: "#112233"
  base0C: "#223344"
  base0D: "#334455"
  base0E: "#445566"
  base0F: "#556677"

This scheme defines 17 colors: 16 base colors and 1 color variable $red used for the diff_deleted customization. All colors are unique. Therefore, the scheme is invalid and the builder should throw an error when trying to parse it.

Maybe the spec could stick closer to the original. Define the 16 base colors, then name them for readability, allow customizations. E.g.

scheme: "might-build"
author: "John Doe"

default:
  base00: "#FF0000"
  base01: "#393F45"
  base02: "#565E65"
  base03: "#747C84"
  base04: "#ADB3BA"
  base05: "#C7CCD1"
  base06: "#DFE2E5"
  base07: "#F3F4F5"
  base08: "#000000"
  base09: "#000011"
  base0A: "#001122"
  base0B: "#112233"
  base0C: "#223344"
  base0D: "#334455"
  base0E: "#445566"
  base0F: "#556677"

aliases:
  $black: base08
  $red: base00

overrides:
  diff_added: base03
  diff_deleted: $red

No hex codes would be allowed for aliases and overrides.

What do you think?

belak commented 2 years ago

That would also simplify parsing because they could always be processed in a single pass (palette then variables then overrides)

mikeduminy commented 2 years ago

The style guide states that a theme author is still limited to 16 colors.

If the project is going to drop the "base16" name then why do we need to adhere to the 16 color limit? I think the base9 reimagining takes things in the right direction. If the project is going to move from an opinionated theming framework to a semi-opinionated theming framework (through incorporating base24 et al) then it may be time to fundamentally challenge the concept. I'm not sure what that looks like just yet.

That would also simplify parsing because they could always be processed in a single pass (palette then variables then overrides)

IMO optimising for ease of parsing is optimising in the wrong direction.

belak commented 2 years ago

If the project is going to drop the "base16" name then why do we need to adhere to the 16 color limit?

Right now we're looking at making the "base16-project" org much broader, which doesn't limit us to a single color scheme system. "base17" is aiming to be the "next version" of base16, which will probably still be limited to 16 colors so it can work with terminal applications still. My pet project is going to be "ansi16" (once we change the org name and clean some more stuff up) which focuses on the 16 ansi colors and how to create color schemes around them. We've also looked at incorporating "base24" as well and potentially other systems.

IMO optimising for ease of parsing is optimising in the wrong direction.

I'm not saying it's the only variable in determining if this is the "right" method of handling variables/overrides, but it's still one worth considering - keeping complexity out of builders is something I'd like to do if possible. This is not to say I'm against complexity, but that I want to see a good reason for it.

The current base17 spec requires recursively resolving variables, which I'm not personally a huge fan of, hence why I prefer limiting the actual color values to the default palette. It allows us to limit color schemes to 16 colors easily (rather than additional processing after all variables are resolved), it simplifies the resolving of variables (removing the need for recursively resolving variables), and it still allows the usage of variables as a convenience. Plus it would allow base17 color schemes to be loaded as "just" the colors and used with base16 templates, even if a builder didn't want to support the "full" base17 spec.

mikeduminy commented 2 years ago

Two things:

  1. I didn't mean that we should enable more than 16 colors, actually I'd lean towards the other direction. The thing that intrigues me about base9 is the idea of a limited number of inputs would intelligently map to colors in template variables. It also seems that the first couple of numbers in base16 are just stepped shades of a single base color which could be generated programmatically.

What I'd propose is a system where theme authors and users can input a variable number of colors (maybe 5 to 10) and the system generates appropriate missing colors from those. The API to do this could also include the ability to be more specific for advanced cases. Let me know if I'm talking gibberish 😃

Anyway, since the project is rebranding and is planning to be more inclusive of other theming systems it seems a good time to drop the idea of numbers in the name. Which leads me on to:

  1. Maybe it is just a placeholder but I vote against the name base17. Not sure how set that is already but it feels weird to add 1 to a meaningful number to make a non-meaningful number.

If it is meant to be base16 v2 then it's worth considering if users would understand this intention. Also, it kinda sounds like a slippery slope to have the version of something communicated in the name, since that implies renaming it every time something new is added 😛

joshgoebel commented 2 years ago

The style guide states that a theme author is still limited to 16 colors. But the spec does not enforce any limit on the number of colors used.

This thinking that the style guide and the spec are separate is not correct - the style guide is the style spec. The style guide/spec speaks to all things style related. If it says 16 colors, then the # of colors is capped at 16 IF one wishes for a valid Base17 scheme. I should point out there are also MANY uses for invalid base17 themes, such as when base17 is serving as an interop format...

Allowing more than 16 colors (in the input/variable stream) was a purposeful design decision. It takes only a few lines of code for a buidler to restrict the number of colors in a format. (see below)

If the project is going to drop the "base16" name then why do we need to adhere to the 16 color limit? I think the base9 reimagining takes things in the right direction.

Exactly. This is my thinking longer-term for sure. Base17 holds onto this limit because it's been thought of as Base16 2.0 - a semi-easy upgrade for scheme authors, etc, not "the next big thing"... The next big thing could well be built on the same YAML foundation... for example as I mentioned above just removing the "max 16 colors" restriction instantly allows base9 to immediately co-exist in our system as a translated input format (invalid base17 format).

In my opinion long-term the push should be to get templates to using fully semantic colors rather than a fixed palette of 16 (with all the problems that fixed semantic bindings has)... and once templates are there then the color cap is entirely arbitrary and one could create schemes with ANY number colors, or shades of colors. In that sense base17 and it's 16 base colors would be a transitional format, not the final destination.

But then I've always wanted broader-interop with other schemes/themes formats... and once you remove color limits and the fixed semantic meaning of base colors you're 99% of the way to inter-operating with so many other systems.

keeping complexity out of builders is something I'd like to do if possible.

I'll state again that nothing I'm proposing here adds much complexity to the builders. Yes, they will never be quite as simple as before, but that does not mean they are now "complex". Sometimes it sounds like we're talking about complexity like it's a binary, yes/no. It's not... it's 1000 shades of grey. And we've been on the simple side for way too long. If we need an extra 100 lines of code to support a few new features, that is well worth it...

Also worth noting line count isn't a good measure of complexity... we could add 100 simple easy to read lines or 15 lines that are an impossible tangled mess. My focus will also be on clean and easy to read code - do things the clearest and simplest way possible... that is how you fight complexity - not by avoiding it completely.

The current base17 spec requires recursively resolving variables,

It does not. Recursive is the wrong word and I never should have used it. Simply allowing one label to reference another is not recursion, nor does it require a recursive resolver (as I've already demonstrated in my own implementation).

It allows us to limit color schemes to 16 colors easily

This [the limiting itself] is trivial to do in ANY case... resolved colors are added to a set... at the end either the set is 16 colors or some other number of colors... in JS this is literally 3 lines of code:

let all_colors = new Set()
// ...
all_colors.add(resolved_hex_color)
// ...
if (all_colors.size == 16)

I'd rather keep this discussion focused on end user experience, not the implementation details.

since that implies renaming it every time something new is added

It does not. Right now (in time) is unique because Chris reasserted ownership over "Base16" (or else the name never would have changed)... it will only be renamed once. Future evolutions could hold the Base17 name indefinitely. I'm not sure that will happen... As I said above I imagine it's more of a transitional format on the way to the next big thing, but if that proves not to be the case I'm fine with that also.

To summarize:

Plus it would allow base17 color schemes to be loaded as "just" the colors and used with base16 templates, even if a builder didn't want to support the "full" base17 spec.

I don't think you've thought this thru fully. This is why we need to continue to support Base16. If someone has a bunch of base16 themes, just use them. If someone has a few base17 themes, use them. Pretending Base17 IS Base16 is shooting ourselves in the foot.

You're reintroducing one of the HUGE problems Base17 attempts to resolve. Once base17 schemes can redefine semantic colors using the "core 16" will not represent a theme faithfully at all. In fact, there is no guarantee that a fully semantic theme would even roughly resemble the "remove all the semantics" base16 version of itself.

This is a problem we need to solve for how templates move forward, but personally I'm fairly certain the answer isn't "chop off all the new base17 semantic colors and just show the old base16 version"... this will have the best results on "base16->base17 not truly base17" schemes and TERRIBLE results on newer "fully semantic, the base colors are almost meaninless" themes.

I'm now starting to lean against this desire to "upgrade" all our themes right out of the gate... Just switching the YAML doesn't magically make a Base16 theme a true Base17 theme... and this is actually harmful when you mix that with the thinking you can just "Strip out" the base17 stuff to turn it back into base16... true Base17 schemes should be those that fully take advantage of the new semantic naming and color mapping - and from that point there is no way to "downgrade" them into Base16 again without losing fidelity (a little or a lot).

If this is the thinking others will bring to the table I think perhaps we need a harder break here... that we deprecate the "basexx" list and when a scheme is upgraded (it could be done via script) that the basexx colors are copied into their semantic slots and then the palette table is REMOVED. I think that would make it clear this is aprocess that is not merely intended to just be reversed and that base17 and base16 "modes" for a base17 scheme are not meant to live side by side.

joshgoebel commented 2 years ago

What I'd propose is a system where theme authors and users can input a variable number of colors (maybe 5 to 10) and the system generates appropriate missing colors from those.

I'm trying hard to make use that Base17 foundation-ally supports (or at least doesn't restrict this).. That's kind of what base9 is... we can support base9 provided Base17 makes three simple things possible:

  1. adds semantics (base9 is just a ton of semantic labels and attached colors)
  2. allows a --non-strict mode for colors... so that Base9 can spit out all it's 54 colors and builders will just quietly process
  3. templates are upgraded to support the new fully semantic world vs the old "fixed base00" color world

1 and 2 are key parts of this proposal already that I planned to see thru. And the latter is inevitable if Base16 is to grow beyond base16 and into something broader and more flexible - though it may make time.

Given these 3 things any outside system could easily generate an "interop"-Base17 file... one with no color limits, but otherwise pretty much Base17... mapping (with as high fidelity as possible) to the semantic meanings that base17 exposes...

For example one could then trivially write a TextMate Theme => BaseX converter... and all new templates that support semantic names would immediately support this, fully. (note: BaseX is what I've been calling the inter-op format informally). Note that it's impossible to do this today because of the rigid semantic bindings that Base16 imposes and this is why some schemes look terrible when ported to Base16 (see Nord).

So while building Base17 my eyes are also on what's next, base24, base9, inter-op, etc... and that definitely has guided some of the thinking slightly.