From 76e7daf5a16d442ac98e844582f7dc1354610886 Mon Sep 17 00:00:00 2001
From: head-gardener <49650767+head-gardener@users.noreply.github.com>
Date: Sat, 18 May 2024 16:01:01 +0300
Subject: [PATCH] doc: explain using `lib.stylix.colors` (#328)

The attrset is used heavily in styllix's modules, but the docs don't contain even a top-level explanation of its value. Though you can gather most it from skimming `base16.nix`, I think stylix should provide an entry point for users, interested in using their color schemes outside of stylix. I base this assumption on personal anecdote of people not having a good understanding of exported values even after extended usage and implementing parallel parsing logic for color scheme files.
---
 docs/src/configuration.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/docs/src/configuration.md b/docs/src/configuration.md
index 406dea3..692dddf 100644
--- a/docs/src/configuration.md
+++ b/docs/src/configuration.md
@@ -69,6 +69,37 @@ and the user-provided one are used in the user configuration if
 `stylix.base16Scheme` is not changed in the user config. If that is the case,
 only the user override is used.
 
+### Extending
+
+When passing colors to unsupported targets or creating custom modules, it
+is possible to access values from the configured color scheme through
+`lib.stylix.colors`.
+An overview of the available values is shown below.
+
+```nix
+lib.stylix.colors = {
+  base08 = "ff0000";
+  base08-hex-r = "ff";
+  base08-dec-r = "0.996094";
+  # ...
+  red = "ff0000";
+  # ...
+  withHashtag = {
+    base08 = "#ff0000";
+    # ...
+  };
+};
+```
+
+This attrset is generated by `mkSchemeAttrs` from `base16.nix`. Refer to the
+[documentation](https://github.com/SenchoPens/base16.nix/blob/main/DOCUMENTATION.md#mkschemeattrs)
+for more info.
+
+For more complex configurations you may find it simpler to use
+[mustache](http://mustache.github.io/) templates to generate output files.
+See [base16.nix](https://github.com/SenchoPens/base16.nix) documentation for
+usage examples.
+
 ## Fonts
 
 The default combination of fonts is: