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;