@atom-learning/theme 1.2.0 → 1.3.0

package/README.md

@@ -1 +1,69 @@
-# theme
+# theme
+
+These repository contains the Atom Learning Design System tokens, like colours, sizes, spaces, font families and so on.
+
+## How to add new tokens that are not part of the theme specification
+
+If you need to add tokens that are not part of the [theme specification](https://github.com/system-ui/theme-specification#key-reference), follow the instruction below. You can also have a look at [this PR](https://github.com/Atom-Learning/theme/pull/25) where we did it for aspect ratios.
+
+* In `system-ui-theme.js`, in `schema` add a new field as an empty object, like `ratios: {}`
+* Also in `system-ui-theme.js`, in `matchSchema`, add a new field named `[category].[type]`, which value references the field you added to `schema` in the previous step. For example if the category is ratios, and the type is ratio, it would look like `'ratios.ratio': 'ratios`
+* Depending on what you are adding you might have to add it to an existing .json file or create a new one. In our example, we created a new one `src/properties/ratios.json`, and added all our tokens there. The json structure is as follow
+  - first level: the `category` mentioned in the step above
+  - second level: the `type` mentioned in the step above
+  - third level: the token name, as you would use it with `$`, e.g.: `$16-9`
+  - fourth level: `value`, the value the token will be replaced by.
+
+  e.g.:
+  ```json
+  {
+    "ratios": {
+      "ratio": {
+        "16-9": {
+          "value": "16/9"
+        },
+        "3-2": {
+          "value": "3/2"
+        },
+        "4-3": {
+          "value": "4/3"
+        },
+        "1-1": {
+          "value": "1/1"
+        },
+        "3-4": {
+          "value": "3/4"
+        }
+      }
+    }
+  }
+  ```
+
+  * In `style.config.js` add your new category (if you added a new category) to the filter of the formatter `'custom/format/scss-map-flat'`. So it's treated the same way than `'size'` and `'effects'`
+
+  * In `theme-map.js` add the (css property -> category) relation to `themeMap`, in this example, we added `aspectRatio: 'ratios'`. This `themeMap` config is exported and used by projects using our `theme` repo. It's used by `createStitches()` from `@stitches/react` so that we don't have to reference the `type`, so we can call the token like `'$16-9'` instead of `'$ratios$16-9'`
+
+### How is `themeMap` used?
+
+For example, in `components` repo we use it like this:
+
+```
+...
+import { createStitches, defaultThemeMap } from '@stitches/react'
+import { themeMap } from '@atom-learning/theme/theme-map'
+
+...
+
+const stitchesConfig = createStitches({
+  theme: atomTheme as Theme,
+  themeMap: {
+    ...defaultThemeMap,
+    ...themeMap
+  },
+  utils,
+  media
+})
+```
+
+### Why/When do we need `themeMap`?
+Some CSS properties are not included in the [defaultThemeMap](https://stitches.dev/docs/api#defaultthememap). If they are missing (e.g.: aspectRatio) you need to add them to our custom `themeMap` which we pass to stitches [themeMap](https://stitches.dev/docs/api#thememap) config

package/lib/index.d.ts

@@ -139,5 +139,12 @@ export type Theme = {
     "1": string
     "2": string
     "3": string
+  },
+  "ratios": {
+    "16-9": string
+    "3-2": string
+    "4-3": string
+    "1-1": string
+    "3-4": string
   }
 }

package/lib/index.js

@@ -139,5 +139,12 @@ module.exports = {
     "1": "0 3px 6px hsla(0, 0%, 20%, 0.1), 0 3px 6px hsla(0, 0%, 20%, 0.1)",
     "2": "0 10px 20px hsla(0, 0%, 20%, 0.1), 0 6px 6px hsla(0, 0%, 20%, 0.1)",
     "3": "0 14px 28px hsla(0, 0%, 20%, 0.15), 0 10px 10px hsla(0, 0%, 20%, 0.1)"
+  },
+  "ratios": {
+    "16-9": "16/9",
+    "3-2": "3/2",
+    "4-3": "4/3",
+    "1-1": "1/1",
+    "3-4": "3/4"
   }
 }

package/lib/index.scss

@@ -1,6 +1,6 @@
 
 // Do not edit directly
-// Generated on Wed, 22 Feb 2023 12:09:52 GMT
+// Generated on Tue, 02 May 2023 09:29:20 GMT
 
 $color-text-foreground: #1f1f1f;
 $color-text-subtle: #545454;
@@ -99,6 +99,13 @@ $effects-shadows: (
   2: (0 10px 20px rgba(51, 51, 51, 0.1), 0 6px 6px rgba(51, 51, 51, 0.1)),
   3: (0 14px 28px rgba(51, 51, 51, 0.15), 0 10px 10px rgba(51, 51, 51, 0.1))
 );
+$ratios-ratio: (
+  16-9: 16/9,
+  3-2: 3/2,
+  4-3: 4/3,
+  1-1: 1/1,
+  3-4: 3/4
+);
 $size-font: (
   xs: 12px,
   sm: 14px,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atom-learning/theme",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Design tokens and assets for Atom Learning",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -11,7 +11,8 @@
     "clean": "del ./lib"
   },
   "files": [
-    "lib"
+    "lib",
+    "theme-map.js"
   ],
   "author": "",
   "license": "ISC",

package/theme-map.js

@@ -0,0 +1,5 @@
+module.exports = {
+  themeMap: {
+    aspectRatio: 'ratios'
+  }
+}