Feat/how to copy styles to project

packages/components/README.md

@@ -11,6 +11,31 @@ See [example](../example)
 - `npm run build` in this package
 - `npm run build:components` in the root of this project
 
+### How to use components on projects
+
+#### Styles
+
+1. Install [sass](https://www.npmjs.com/package/sass) and [modern-normalize](https://www.npmjs.com/package/modern-normalize)
+2. Copy `/styles` folder to your project
+    - (Optional) If you want to preserve JS exports and functions install [polished](https://www.npmjs.com/package/polished)
+    - (Optional) If you want to preserve tests, they are written in [jest](https://www.npmjs.com/package/jest) and you must not mock `index.scss` imports (like with `moduleNameMapper` in jest config)
+3. Remove unwanted component styles from `styles/index.scss` and add yours project specific
+4. Update configs in `styles/tokens/**/index.scss` according to your project needs
+5. Import `styles/index.scss` to your project (like in `_app.tsx` in Next.js)
+6. Use styles in your components like in the examples
+
+    ```scss
+    @use '../../styles/tokens';
+
+    .my-class {
+      color: tokens.color('primary');
+    }
+    ```
+
+    ```jsx
+    const MyComponent = () => <span className="text-color-primary">text</span>
+    ```
+
 ## Principles
 
 ### Headless UI components

packages/components/package.json

@@ -32,6 +32,7 @@
     "classnames": "^2.3.1",
     "downshift": "^6.1.7",
     "jest-axe": "^6.0.0",
+    "modern-normalize": "^1.1.0",
     "polished": "^4.1.3",
     "preact": "~10.5.14",
     "preact-render-to-string": "~5.1.19",

packages/components/src/components/Bar/styles/config.scss

@@ -1,7 +1,7 @@
 // ---------------------------------------------
 // BAR - CONFIGURATION
 // ---------------------------------------------
-@use "../../../tokens";
+@use "../../../styles/tokens";
 
 $spacing: (
   default: tokens.space(),

packages/components/src/components/Bar/styles/mixins.scss

@@ -3,7 +3,7 @@
 // ---------------------------------------------
 
 @use "./config";
-@use "../../../tokens";
+@use "../../../styles/tokens";
 @use "../../../styles/utils";
 
 @mixin bar {

packages/components/src/components/Button/styles/config.scss

@@ -3,7 +3,7 @@
 // ---------------------------------------------
 
 @use "sass:map";
-@use "../../../tokens";
+@use "../../../styles/tokens";
 @use "../../../styles/utils";
 @use "./../../Icon/styles/config" as icons;
 

packages/components/src/components/Button/styles/mixins.scss

@@ -6,7 +6,7 @@
 @use "sass:list";
 @use "./config";
 @use "../../../styles/utils";
-@use "../../../tokens";
+@use "../../../styles/tokens";
 
 // CONTENTS
 // Base

packages/components/src/components/Card/styles/config.scss

@@ -1,4 +1,4 @@
-@use "../../../tokens";
+@use "../../../styles/tokens";
 
 $card: (
   default: (

packages/components/src/components/Card/styles/mixins.scss

@@ -1,6 +1,6 @@
 @use "sass:map";
 @use "./config";
-@use "../../../tokens";
+@use "../../../styles/tokens";
 @use "../../../styles/utils";
 
 @mixin card($card: config.$card) {

packages/components/src/components/DropdownMenu/styles/config.scss

@@ -2,7 +2,7 @@
 // DROPDOWN - CONFIGURATION
 // ---------------------------------------------
 
-@use "../../../tokens";
+@use "../../../styles/tokens";
 @use "../../../styles/utils.scss";
 
 $dropdown-menu-max-height: 300px;

packages/components/src/components/FileUploader/styles/style.scss

@@ -1,4 +1,4 @@
-@use "../../../tokens";
+@use "../../../styles/tokens";
 
 .file-uploader {
   &__preview-item {

packages/components/src/components/Label/styles/config.scss

@@ -2,7 +2,7 @@
 // FORMS - LABEL - CONFIGURATION
 // ---------------------------------------------
 
-@use "../../../tokens";
+@use "../../../styles/tokens";
 @use "../../../styles/utils";
 
 $label: (

packages/components/src/components/Modal/styles/config.scss

@@ -1,5 +1,5 @@
 @use "sass:color";
-@use "../../../tokens";
+@use "../../../styles/tokens";
 @use "../../../styles/utils";
 
 $modal-overlay-z-index: 500;

packages/components/src/components/Modal/styles/mixins.scss

@@ -1,7 +1,7 @@
 @use "sass:map";
 @use "./config";
 @use "../../../styles/utils";
-@use "../../../tokens";
+@use "../../../styles/tokens";
 
 @mixin modal($settings: config.$modal) {
   @each $breakpoint, $props in $settings {

packages/components/src/components/Modal/styles/style.scss

@@ -1,4 +1,4 @@
-@use "../../../tokens";
+@use "../../../styles/tokens";
 @use "./mixins";
 
 .modal {

packages/components/src/components/Pagination/styles/style.scss

@@ -1,4 +1,4 @@
-@use "../../../tokens";
+@use "../../../styles/tokens";
 
 .pagination {
   margin-bottom: tokens.space();

packages/components/src/components/Select/styles/config.scss

@@ -2,7 +2,7 @@
 // FORMS - SELECT - CONFIGURATION
 // ---------------------------------------------
 
-@use "../../../tokens";
+@use "../../../styles/tokens";
 @use "../../../styles/utils";
 
 $select: (

packages/components/src/components/Select/styles/style.scss

@@ -1,6 +1,6 @@
 @use "./config";
 @use "../../../styles/utils";
-@use "../../../tokens";
+@use "../../../styles/tokens";
 
 // Replace letters
 @function str-replace($string, $search, $replace: "") {

packages/components/src/components/Slider/styles/style.scss

@@ -1,4 +1,4 @@
-@use "../../../tokens";
+@use "../../../styles/tokens";
 @use "../../../styles/utils";
 
 :root {

packages/components/src/components/Table/styles/style.scss

@@ -1,4 +1,4 @@
-@use "../../../tokens";
+@use "../../../styles/tokens";
 @use "../../../styles/utils";
 
 .table {

packages/components/src/index.ts

@@ -31,7 +31,7 @@ import {
   spaces,
   fonts,
   shadows,
-} from "./tokens";
+} from "./styles/tokens";
 
 import "./styles/utilities.scss";
 import "./styles/layout.scss";

packages/components/src/styles/globals.scss

@@ -1,3 +1,4 @@
-@import "../tokens/colors/globals";
-@import "../tokens/space/globals";
-@import "../tokens/font/globals";
+// NOTE: tokens create css variables in the :root so make sure you are importing globals only once and preferably here so we don't pollute .css files with multiple variabile definitions
+@import "./tokens/colors/globals";
+@import "./tokens/space/globals";
+@import "./tokens/font/globals";

packages/components/src/styles/index.scss

@@ -1,4 +1,10 @@
+// normalize
+@import "modern-normalize/modern-normalize.css";
+
+// globals
 @import "./globals";
+
+// component styles
 @import "./../components/Bar/styles/style.scss";
 @import "./../components/Button/styles/style.scss";
 @import "./../components/Card/styles/style.scss";
@@ -10,5 +16,7 @@
 @import "./../components/Select/styles/style.scss";
 @import "./../components/Slider/styles/style.scss";
 @import "./../components/Table/styles/style.scss";
+
+// utilites and overrides
 @import "./utilities.scss";
 @import "./layout.scss";

packages/components/src/styles/layout.scss

@@ -3,7 +3,7 @@
 // ---------------------------------------------
 
 @use './utils';
-@use '../tokens';
+@use './tokens';
 
 // mixin for utilities with layout targeting
 @mixin spacing-reset-classes($breakpoint: "") {

packages/components/src/tokens/TokensTable.tsx → packages/components/src/styles/tokens/TokensTable.tsx

@@ -5,8 +5,8 @@
 import React, { useMemo } from "react";
 
 import { Table, Code } from "@lighting-beetle/lighter-styleguide";
-import flattenObject from "../utils/flattenObject";
-import { SCSSVarsMap } from "../utils/scssVarsToMap";
+import flattenObject from "../../utils/flattenObject";
+import { SCSSVarsMap } from "../../utils/scssVarsToMap";
 import { Column } from "react-table";
 
 type UsageFormatFunc = ({

packages/components/src/tokens/breakpoints/breakpoints.test.ts → packages/components/src/styles/tokens/breakpoints/breakpoints.test.ts

@@ -5,7 +5,7 @@
 
 import { renderSync } from "sass";
 import { breakpoint } from ".";
-import scssTestImporter from "../../utils/scssTestImporter";
+import scssTestImporter from "../../../utils/scssTestImporter";
 
 function renderSass(args) {
   return renderSync({

packages/components/src/tokens/breakpoints/index.scss → packages/components/src/styles/tokens/breakpoints/index.scss

@@ -1,7 +1,7 @@
 @use "sass:meta";
 @use "sass:map";
 @use "sass:list";
-@use "./../../styles/utils.scss";
+@use "./../../utils.scss";
 
 $breakpoints: (
   xs: 0,

packages/components/src/tokens/breakpoints/index.ts → packages/components/src/styles/tokens/breakpoints/index.ts

@@ -1,6 +1,6 @@
 // TODO: useBreakpoint hook can be probaly useful here
 
-import scssVarsToMap from "../../utils/scssVarsToMap";
+import scssVarsToMap from "../../../utils/scssVarsToMap";
 import breakpointsFromSCSS from "./export.module.scss";
 
 export const breakpoints = scssVarsToMap(breakpointsFromSCSS);

packages/components/src/tokens/colors/colors.test.ts → packages/components/src/styles/tokens/colors/colors.test.ts

@@ -5,7 +5,7 @@
 
 import { renderSync } from "sass";
 import { color, colorHex } from ".";
-import scssTestImporter from "../../utils/scssTestImporter";
+import scssTestImporter from "../../../utils/scssTestImporter";
 
 function renderSass(args) {
   return renderSync({

packages/components/src/tokens/colors/index.ts → packages/components/src/styles/tokens/colors/index.ts

@@ -1,4 +1,4 @@
-import scssVarsToMap from "../../utils/scssVarsToMap";
+import scssVarsToMap from "../../../utils/scssVarsToMap";
 import colorsFromSCSS from "./export.module.scss";
 
 export const colors = scssVarsToMap(colorsFromSCSS);

packages/components/src/tokens/font/index.ts → packages/components/src/styles/tokens/font/index.ts

@@ -1,4 +1,4 @@
-import scssVarsToMap from "../../utils/scssVarsToMap";
+import scssVarsToMap from "../../../utils/scssVarsToMap";
 import fontsSCSSVars from "./export.module.scss";
 
 export const fonts = scssVarsToMap(fontsSCSSVars);

packages/components/src/tokens/shadows/index.ts → packages/components/src/styles/tokens/shadows/index.ts

@@ -1,4 +1,4 @@
-import scssVarsToMap from "../../utils/scssVarsToMap";
+import scssVarsToMap from "../../../utils/scssVarsToMap";
 import shadowsSCSSVars from "./export.module.scss";
 
 export const shadows = scssVarsToMap(shadowsSCSSVars);

packages/components/src/tokens/space/index.scss → packages/components/src/styles/tokens/space/index.scss

@@ -1,7 +1,7 @@
 @use "sass:meta";
 @use "sass:map";
 @use "sass:list";
-@use "./../../styles/utils.scss";
+@use "../../utils.scss";
 
 $spaces: (
   default: 16px,

packages/components/src/tokens/space/index.ts → packages/components/src/styles/tokens/space/index.ts

@@ -1,5 +1,5 @@
-import { rem } from "../../styles";
-import scssVarsToMap from "../../utils/scssVarsToMap";
+import { rem } from "../..";
+import scssVarsToMap from "../../../utils/scssVarsToMap";
 import spacesFromSCSS from "./export.module.scss";
 
 export const spaces = scssVarsToMap(spacesFromSCSS);

packages/components/src/tokens/space/spaces.test.ts → packages/components/src/styles/tokens/space/spaces.test.ts

@@ -5,7 +5,7 @@
 
 import { renderSync } from "sass";
 import { space, spaceValue } from ".";
-import scssTestImporter from "../../utils/scssTestImporter";
+import scssTestImporter from "../../../utils/scssTestImporter";
 
 function renderSass(args) {
   return renderSync({

packages/components/src/styles/utilities.scss

@@ -1,5 +1,5 @@
 @use './utils';
-@import "../tokens/font/utilities.scss";
+@import "./tokens/font/utilities.scss";
 
 .visually-hidden {
   @include utils.visually-hidden();

packages/components/src/styles/utils.scss

@@ -1,7 +1,7 @@
 @use "sass:map";
 @use "sass:list";
 @use "sass:math";
-@use "../tokens/font";
+@use "./tokens/font";
 
 /// Base on -zf-map-next https://github.com/zurb/foundation-sites/blob/develop/scss/util/_breakpoint.scss
 /// Find the next key in a map.

packages/components/tsconfig.json

@@ -6,7 +6,12 @@
     "**/*.tsx",
     "./react-table-config.d.ts"
   ],
-  "exclude": ["node_modules", "dist", "out", "src/tokens/TokensTable.tsx"],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "out",
+    "src/styles/tokens/TokensTable.tsx"
+  ],
   "compilerOptions": {
     "target": "ES2018"
   },

packages/design-system/package.json

@@ -18,7 +18,6 @@
     "glob": "~7.2.0",
     "mdx-bundler": "^8.0.0",
     "micromatch": "~4.0.4",
-    "modern-normalize": "^1.1.0",
     "netlify-cms-app": "~2.15.44",
     "netlify-cms-widget-mdx": "~0.4.4",
     "next": "~12.2.5",

packages/design-system/src/pages/_app.tsx

@@ -1,5 +1,4 @@
 import React from "react";
-import "modern-normalize/modern-normalize.css";
 import "components/styles.scss";
 
 function MyApp({ Component, pageProps }) {

packages/example-forms/package.json

@@ -14,7 +14,6 @@
     "@lighting-beetle/next-lighter-config": "workspace:^",
     "components": "workspace:^",
     "micromatch": "~4.0.4",
-    "modern-normalize": "^1.1.0",
     "next": "~12.2.5",
     "next-transpile-modules": "~9.0.0",
     "react": "~17.0.2",

packages/example-forms/src/pages/_app.tsx

@@ -1,5 +1,4 @@
 import React from "react";
-import "modern-normalize/modern-normalize.css";
 import "components/styles.scss";
 
 export default function MyApp({ Component, pageProps }) {

packages/example-table/package.json

@@ -11,7 +11,6 @@
   "dependencies": {
     "@lighting-beetle/next-lighter-config": "workspace:^",
     "components": "workspace:^",
-    "modern-normalize": "^1.1.0",
     "next": "~12.3.0",
     "next-query-params": "^4.0.0",
     "next-transpile-modules": "~8.0.0",

packages/example-table/src/pages/_app.tsx

@@ -1,7 +1,6 @@
 import React from "react";
 import { NextAdapter } from "next-query-params";
 import { QueryParamProvider } from "use-query-params";
-import "modern-normalize/modern-normalize.css";
 import "../components/Flats/filters/styles/style.scss";
 import "components/styles.scss";
 

packages/example/next.config.js

@@ -11,5 +11,4 @@ export default createConfig({
     },
   },
   plugins: [transpileModules(["components"])],
-  analyzeBundle: true,
 });

packages/example/package.json

@@ -13,7 +13,6 @@
   "dependencies": {
     "@lighting-beetle/next-lighter-config": "workspace:^",
     "components": "workspace:^",
-    "modern-normalize": "^1.1.0",
     "next": "~12.2.5",
     "next-transpile-modules": "~9.0.0",
     "react": "~17.0.2",

packages/example/src/pages/_app.tsx

@@ -1,5 +1,4 @@
 import React from "react";
-import "modern-normalize/modern-normalize.css";
 import "components/styles.scss";
 
 export default function MyApp({ Component, pageProps }) {