specs: rigorously extend the Style Guide

[trueNAHO]

Rigorously extend the Style Guide, similar to formal specifications.

Related:

• https://github.com/danth/stylix/issues/205
• https://github.com/danth/stylix/issues/207
• https://github.com/danth/stylix/pull/246#issuecomment-1928088839

[jalil-salame]

One thing I'd like to add to the style guide, is that active tabs should follow the color of the active area:

Both Chrome and Firefox have active tabs be the same color as the search bar, this makes them look to be part of the "active" area.

We should generally follow the design choices of browsers when appropriate.

[LovingMelody]

Unsure if this should be included to the style guide or in its own issue, the underlying base16 library now support the tinted-theming spec aka base24. Would be nice to see this included.

[danth]

Supporting base24 would require new code in addition to style guide changes

[trueNAHO]

The style guide could demonstrate the most common use cases with color aliases: https://github.com/danth/stylix/issues/207.

[RANKSHANK]

On the topic of base24, I've been staring down KiCAD's theme spec for a while and I'd have the same issues with how many colors are defined with base24. KiCAD's copper layers define 32 separate color values, which means either repeating values or writing something to generate sub colors which results in non consistent colors. I'm looking at a similar issue in FreeCAD where the base spec uses different shades of colors to indicate different highlights/types of constraints, one extra lighter shade of red/green/etc that's found in base24 isn't enough in these instances.

The solution I'm considering mimics vim's highlight groups:

{ lib, ... }:

rec {

    # Where r g b are 0 - 255 ints
    color = r: g: b: rec {
        inherit r g b;
        asRgbDec = "rgb(${r}, ${g}, ${b})";
        asRgbaDec = alpha: "rgba(${r}, ${g}, ${b}, ${alpha})";
        asHex = "${lib.toHexString r}${lib.toHexString g}${lib.toHexString b}";
        asHexWithHash = "#${asHex}";
        asHexAlpha = alpha: "${asHex}${lib.toHexString alpha}";
        asHexAlphaWithHash = "#${asHexAlpha}";
        asDecInt = r * 256 + g * 16 + b;
        asDecIntAlpha = alpha: asDecInt + alpha;
        newByFactor = factor: color (r * factor) (g * factor) (b * factor);
        newBlended = toBlend: color ((r + toBlend.r) / 2) ((g + toBlend.g) / 2) ((b + toBlend.b) / 2);
    };

    # Where fg bg ol are of type color
    colorGroup = fg: bg: ol: {
        inherit fg bg ol;
        newByFactor = factor: colorGroup (fg.newByFactor factor) (bg.newByFactor factor) (ol.newByFactor factor);
        newBlendedByGroup = otherGroup: colorGroup (fg.newBlended otherGroup.fg) (bg.newBlended otherGroup.bg) (ol.newByFactor otherGroup.bd);
        newBlendedByColor = color: colorGroup (fg.newBlended color) (bg.newBlended color) (ol.newBlended color);
    };

}

Color groups consist of foreground, background, and outline colors. We'd generate them from base16 palettes.

This would mean groups in lieu of general aliases to solve #207. This would also be a good spot to address #208 where we could have each target have its own set of groups that defaults to the main theme's groups. Or more likely we'd want a hierarchy of Main 󰜴 Type 󰜴 Target where type would be something like 'terminals' and 'popups' so that users easily change multiple applications. Another benefit would be for consistency in apps that have 'levels of highlight'. E.G. when an active and hovered component requires a lighter highlight when it is also pinned. This would be addressed by multiplying the existing highlight group by most likely a pre/user defined factor eg 0.15 per step.

So with that in mind usage would be something like:

tabActiveBorder = config.stylix.targets.wezterm.groups.tabActive.ol.asHexWithHash;
tabActiveText = config.stylix.targets.wezterm.groups.tabActive.fg.asHexWithHash;
tabActiveBackground = config.stylix.targets.wezterm.groups.tabActive.bg.asHexWithHash;

By keeping the group mechanism separate from the base16 spec we could migrate modules piecewise instead of having one massive PR.

I'd also opt for a separate groups folder with each group defined in a separate .nix file so as to prevent PRs that add/modify groups from resulting in merge conflicts.

[danth]

Related: #277

[trueNAHO]

The solution I'm considering mimics vim's highlight groups

VIM's highlight groups might be the most scalable and practical solution I know of.

It would resolve nearly all our open issues regarding color scheme scalability. Additionally, our documentation could simply link to VIM's highlight groups documentation.

[trueNAHO]

We should consider specifying border widths and font usage.