docs: improve theming docs

.github/foundation.md

@@ -100,37 +100,50 @@ const foundation = {
       facebookActive: "#0B5CC1",
     },
   },
-  base: {
-    fontFamily:
-      '"Roboto", -apple-system, ".SFNSText-Regular", "San Francisco", "Segoe UI", "Helvetica Neue", "Lucida Grande", sans-serif',
-    fontSizeSm: "12px",
-    fontSizeMd: "14px",
-    fontSizeLg: "16px",
-    borderRadius: "3px",
-    sizeSm: "16px",
-    sizeMd: "24px",
-    sizeLg: "32px",
-    sizeXl: "44px",
-    size2xl: "52px",
-    opacitySmall: "0.3",
-    opacityMedium: "0.5",
-    opacityLarge: "0.8",
-    fontWeightNormal: "400",
-    fontWeightMedium: "500",
-    fontWeightBold: "700",
-    space2xs: "4px",
-    spaceXs: "8px",
-    spaceSm: "12px",
-    spaceMd: "16px",
-    spaceLg: "24px",
-    spaceXl: "32px",
-    space2xl: "40px",
-    space3xl: "52px",
-    durationFast: "0.15s",
-    durationNormal: "0.3s",
-    durationSlow: "0.4s",
-    transitionDefault: "ease-in-out",
-    lineHeight: "1.4",
+  fontWeight: {
+    normal: "400",
+    medium: "500",
+    bold: "700",
+  },
+  fontSize: {
+    small: "13px",
+    normal: "15px",
+    large: "16px",
+    extraLarge: "18px",
+  },
+  fontFamily: {
+    base: "'Roboto', -apple-system, '.SFNSText-Regular', 'San Francisco', 'Segoe UI', 'Helvetica Neue', 'Lucida Grande', sans-serif",
+  },
+  space: {
+    XXSmall: "4px",
+    XSmall: "8px",
+    small: "12px",
+    medium: "16px",
+    large: "24px",
+    XLarge: "32px",
+    XXLarge: "40px",
+    XXXLarge: "52px",
+  },
+  size: {
+    small: "16px",
+    medium: "24px",
+    large: "32px",
+    extraLarge: "44px",
+    extraExtraLarge: "52px",
+  },
+  breakpoint: {
+    smallMobile: 320,
+    mediumMobile: 414,
+    largeMobile: 576,
+    tablet: 768,
+    desktop: 992,
+    largeDesktop: 1200,
+  },
+  borderRadius: {
+    circle: "50%",
+    small: "2px",
+    normal: "3px",
+    large: "6px",
   },
 };
 ```

.github/theming.md

@@ -46,6 +46,35 @@ const App = () => (
 
 **Note: This approach is recommended only if you are not using OrbitProvider. We manage the addition of CSS variables within OrbitProvider until the migration to Tailwind is complete**.
 
+We provide two different ways of customizing the Orbit Tailwind foundation. You can either use the
+`foundation` parameter of the `orbitPreset` function inside your tailwind config file or you can use the `tokensToCssVars` from the `@kiwicom/orbit-design-tokens` package to add css variables on your page. That might be useful, if you need to change the foundation values dynamically in runtime.
+
+## Customizing the Orbit Tailwind foundation with `orbitPreset`
+
+The [orbitPreset](https://github.com/kiwicom/orbit/blob/master/packages/orbit-tailwind-preset/README.md)
+accepts `foundation` parameter, which allows you to customize the foundation values used by the preset.
+
+```js
+module.exports = {
+  presets: [orbitPreset({ foundation: palette: {
+    product: {
+      light: "#9ae5da",
+      lightHover: "#7fded0",
+      lightActive: "#64d7c6",
+      normal: "#00a991",
+      normalHover: "#009882",
+      normalActive: "#008f7b",
+      dark: "#005448",
+    },
+    }})],
+  ]
+}
+```
+
+Except `palette` colors you can define your own values for other foundation values: `fontWeight`, `fontSize`, `fontFamily`, `lineHeight`, `breakpoint`, `size`, `space`, `borderRadius`. You can look at the example of foundation object [here](https://github.com/kiwicom/orbit/blob/master/.github/foundation.md)
+
+## Customizing the Orbit Tailwind foundation with `tokensToCssVars`
+
 Our Tailwind CSS preset package utilizes CSS variables for the theme,
 making it easy for you to customize the default palette with your own colors.
 To simplify this process, our tokens package includes a utility function that converts a theme object into a CSS variables string,

packages/orbit-tailwind-preset/README.md

@@ -16,7 +16,10 @@ npm install --save-dev @kiwicom/orbit-tailwind-preset
 
 The default exported preset (`orbitComponentsPreset`) includes all of the Orbit's foundation styles (typography, colors, spacing, etc…) and all the needed configuration for component-specific classes used internally.
 
-The `orbitComponentsPreset` function accepts an optional object with one property, `disablePreflight`, which is `false` by default. When set to `true`, it disables the normalization of the browser's default styles. We recommend leaving it enabled, as it avoids the need to reset the browser's default styles manually. The normalization is done by the [Tailwind CSS Preflight](https://tailwindcss.com/docs/preflight) plugin.
+The `orbitComponentsPreset` function accepts an optional object with two properties, `disablePreflight`, which is `false` by default. When set to `true`, it disables the normalization of the browser's default styles. We recommend leaving it enabled, as it avoids the need to reset the browser's default styles manually. The normalization is done by the [Tailwind CSS Preflight](https://tailwindcss.com/docs/preflight) plugin.
+
+The `foundation` property allows you to customize the foundation values used by the preset. [Read more in
+theming section](https://github.com/kiwicom/orbit/blob/master/.github/theming.md)
 
 ## Configuration