From b71cff49a815a724ef9b91e3202b7485f3cc8102 Mon Sep 17 00:00:00 2001
From: Robin <robin@robin.town>
Date: Thu, 1 Feb 2024 15:04:49 -0500
Subject: [PATCH 1/3] Update design tokens

We have new icons and design tokens available, so we should update the Storybook to show them.
---
 package.json | 2 +-
 yarn.lock    | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/package.json b/package.json
index b2911b5..8f93a04 100644
--- a/package.json
+++ b/package.json
@@ -48,7 +48,7 @@
     "typescript": "^5.0.4"
   },
   "dependencies": {
-    "@vector-im/compound-design-tokens": "https://github.com/vector-im/compound-design-tokens#0.1.0",
+    "@vector-im/compound-design-tokens": "github:element-hq/compound-design-tokens",
     "deepmerge": "^4.3.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
diff --git a/yarn.lock b/yarn.lock
index de5f8b7..b1abec1 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2702,9 +2702,9 @@
     "@typescript-eslint/types" "5.59.5"
     eslint-visitor-keys "^3.3.0"
 
-"@vector-im/compound-design-tokens@https://github.com/vector-im/compound-design-tokens#0.1.0":
-  version "0.0.7"
-  resolved "https://github.com/vector-im/compound-design-tokens#920f164856a586e7d3bbb1c0e4fd0107de381e33"
+"@vector-im/compound-design-tokens@github:element-hq/compound-design-tokens":
+  version "1.0.0"
+  resolved "https://codeload.github.com/element-hq/compound-design-tokens/tar.gz/e7fb20f8d38821a7c3082d26d2f0f097731d776c"
   dependencies:
     svg2vectordrawable "^2.9.1"
 

From 23965e59c390002306d164cfdcfedfcac22a2f82 Mon Sep 17 00:00:00 2001
From: Robin <robin@robin.town>
Date: Tue, 6 Feb 2024 13:20:48 -0500
Subject: [PATCH 2/3] Add the version of compound-design-tokens back

---
 package.json | 2 +-
 yarn.lock    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/package.json b/package.json
index 8f93a04..6056282 100644
--- a/package.json
+++ b/package.json
@@ -48,7 +48,7 @@
     "typescript": "^5.0.4"
   },
   "dependencies": {
-    "@vector-im/compound-design-tokens": "github:element-hq/compound-design-tokens",
+    "@vector-im/compound-design-tokens": "github:element-hq/compound-design-tokens#semver:^1.0.0",
     "deepmerge": "^4.3.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
diff --git a/yarn.lock b/yarn.lock
index b1abec1..5668b3f 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2702,7 +2702,7 @@
     "@typescript-eslint/types" "5.59.5"
     eslint-visitor-keys "^3.3.0"
 
-"@vector-im/compound-design-tokens@github:element-hq/compound-design-tokens":
+"@vector-im/compound-design-tokens@github:element-hq/compound-design-tokens#semver:^1.0.0":
   version "1.0.0"
   resolved "https://codeload.github.com/element-hq/compound-design-tokens/tar.gz/e7fb20f8d38821a7c3082d26d2f0f097731d776c"
   dependencies:

From 7c5b004fd5d8f6de0fd6f5fd7fa06b13a9174e95 Mon Sep 17 00:00:00 2001
From: Robin <robin@robin.town>
Date: Tue, 6 Feb 2024 18:43:19 -0500
Subject: [PATCH 3/3] Document the mechanism for theming Compound on Web

---
 stories/develop/Theming.stories.mdx | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
 create mode 100644 stories/develop/Theming.stories.mdx

diff --git a/stories/develop/Theming.stories.mdx b/stories/develop/Theming.stories.mdx
new file mode 100644
index 0000000..739ffec
--- /dev/null
+++ b/stories/develop/Theming.stories.mdx
@@ -0,0 +1,23 @@
+import { Meta } from "@storybook/addon-docs";
+
+<Meta title="Develop/Theming" />
+
+# Theming
+
+The default set of design tokens provided by Compound contains some choices specific to Element's brand, which our users and customers may want to change to meet their needs. For this reason we allow Compound to be themed with custom sets of semantic tokens.
+
+## Web
+
+On Web, you can override any semantic token by redefining that token in the `custom` [cascade layer](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Cascade_layers) provided by the [design tokens package](https://github.com/vector-im/compound-design-tokens/tree/develop/assets/web). This example demonstrates how you would change the `color.icon.accent-tertiary` token to blue, rather than Element's default green:
+
+```css
+@import "@vector-im/compound-design-tokens/assets/web/css/compound-design-tokens.css" layer(compound);
+
+@layer compound.custom {
+  :root, [class*="cpd-theme-"] {
+    --cpd-color-icon-accent-tertiary: var(--cpd-color-blue-800);
+  }
+}
+```
+
+As long as you use the provided layer, this ensures that future internal changes to the package will not cause conflicts in selector specificity.