From 26fad7dd0fc77c50a4c3d782a648358514ddb970 Mon Sep 17 00:00:00 2001
From: Waldir Pimenta <waldyrious@gmail.com>
Date: Mon, 4 Jul 2022 18:25:58 -0100
Subject: [PATCH] docs: Mention caveat about variable dependencies (#555)

Looking at how the variables are defined in _variables.scss, with various dependencies between them aimed at ensuring a consistent color scheme, one might expect that redefining a given variable would affect the remaining styles that depend on it.

This is not the case, however, due to the order in which the files are processed. This PR edits the documentation to mention the non-propagating behavior of redefined variables, to better guide users that wish to customize the site using custom themes, and call their attention to the need to redefine the dependency relations as well.

Co-authored-by: Matt Wang <matt@matthewwang.me>
Co-authored-by: Patrick Marsceill <pmarsceill@users.noreply.github.com>
---
 docs/customization.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/customization.md b/docs/customization.md
index 94587efc..54804f8f 100644
--- a/docs/customization.md
+++ b/docs/customization.md
@@ -69,6 +69,10 @@ For example, to change the link color from the purple default to blue, include t
 $link-color: $blue-000;
 ```
 
+Keep in mind that changing a variable will not automatically change the value of other variables that depend on it.
+For example, the default link color (`$link-color`) is set to `$purple-000`. However, redefining `$purple-000` in a custom color scheme will not automatically change `$link-color` to match it.
+Instead, each variable that relies on previously-cascaded values must be manually reimplemented by copying the dependent rules from `_variables.scss` — in this case, rewriting `$link-color: $purple-000;`.
+
 _Note:_ Editing the variables directly in `_sass/support/variables.scss` is not recommended and can cause other dependencies to fail.
 Please use scheme files.
 
-- 
GitLab