From 5fc402cda0a6562aaf21af26c264d44ad21d2fbd Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Fri, 21 Apr 2023 14:30:21 +0100
Subject: [PATCH] Deprecate the `$spacing-` variables (#10686)

* Deprecate the $spacing variables

* more comments
---
 res/css/_font-sizes.pcss | 10 ++++++++++
 res/css/_spacing.pcss    | 12 ++++++++++--
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/res/css/_font-sizes.pcss b/res/css/_font-sizes.pcss
index 5c977a740f..5d83ff83df 100644
--- a/res/css/_font-sizes.pcss
+++ b/res/css/_font-sizes.pcss
@@ -14,6 +14,16 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+/*
+ * SCSS variables defining a range of font sizes.
+ *
+ * These are defined in `rem` so that they scale with the `font-size` of the root element (which is adjustable via the
+ * "Font size" setting). They exist to make the job of converting designs (which tend to be based in pixels) into CSS
+ * easier.
+ *
+ * That means that, slightly confusingly, `$font-10px` is only *actually* 10px at the default font size: at a base
+ * `font-size` of 15, it is actually 15px.
+ */
 $font-1px: 0.1rem;
 $font-1-5px: 0.15rem;
 $font-2px: 0.2rem;
diff --git a/res/css/_spacing.pcss b/res/css/_spacing.pcss
index 63197f2321..eaf46abc0e 100644
--- a/res/css/_spacing.pcss
+++ b/res/css/_spacing.pcss
@@ -14,8 +14,16 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-/* 1rem :: 10px */
-
+/* SCSS variables representing a range of standard lengths.
+ *
+ * Avoid using these in new code: we cannot adjust their values without causing massive confusion, so they are
+ * effectively equivalent to using hardcoded values.
+ *
+ * In future, we plan to introduce variables named according to their purpose rather than their size. Additionally,
+ * we want switch to custom CSS properties (https://github.com/vector-im/element-web/issues/21656), so we might have
+ * `--spacing-standard` or something. For now, you might as well use hardcoded px values for lengths (except for font
+ * sizes, for which see the `$font-<N>px` variables).
+ */
 $spacing-2: 2px;
 $spacing-4: 4px;
 $spacing-8: 8px;