docs(carbon-react): add README and initial sass config docs (#8586)

* docs(carbon-react): add README and initial sass config docs * Update packages/carbon-react/README.md Co-authored-by: Taylor Jones <[email protected]> * Update packages/carbon-react/README.md Co-authored-by: Taylor Jones <[email protected]> * Update packages/carbon-react/README.md Co-authored-by: Taylor Jones <[email protected]> * docs(carbon-react): update README and sass docs * docs(carbon-react): update import from icons-react to react/icons Co-authored-by: Taylor Jones <[email protected]>
carbon-design-system · May 5, 2021 · c75a170 · c75a170
1 parent 6c2c9d8
commit c75a170
Show file tree

Hide file tree

Showing 6 changed files with 199 additions and 8 deletions.
diff --git a/.yarn/cache/sass-npm-1.32.12-a25605e22b-01ddd4abce.zip b/.yarn/cache/sass-npm-1.32.12-a25605e22b-01ddd4abce.zip
diff --git a/.yarn/cache/sass-npm-1.32.8-6b113b5d20-a4d67e6be7.zip b/.yarn/cache/sass-npm-1.32.8-6b113b5d20-a4d67e6be7.zip
diff --git a/packages/carbon-react/README.md b/packages/carbon-react/README.md
@@ -0,0 +1,78 @@
+# @carbon/react
+
+> React components for the Carbon Design System
+
+## Getting started
+
+To install `@carbon/react` in your project, you will need to run the following
+command using [npm](https://www.npmjs.com/):
+
+```bash
+npm install -S @carbon/react
+```
+
+If you prefer [Yarn](https://yarnpkg.com/en/), use the following command
+instead:
+
+```bash
+yarn add @carbon/react
+```
+
+## Usage
+
+**Note: this package is unstable and will change before it's 1.0 release**
+
+You can use the `@carbon/react` to bring in components, icons, and styles from
+the Carbon Design System.
+
+To include a component, you can import it:
+
+```jsx
+import { Button } from '@carbon/react';
+
+function MyComponent() {
+  return <Button>Example usage</Button>;
+}
+```
+
+To include an icon, use the `@carbon/react/icons` entrypoint and import it the
+same way you would import a component:
+
+```jsx
+import { Add } from '@carbon/react/icons';
+
+function MyComponent() {
+  return <Add />;
+}
+```
+
+For styles, you can bring them in using Sass Modules:
+
+```jsx
+@use '@carbon/react';
+```
+
+Note: you will need to configure Sass in order to correctly find modules in your
+`node_modules`. Follow [this guide](./docs/sass.md#configuration) to make sure
+your project is setup correctly.
+
+## :books: Documentation
+
+- TODO
+
+## 📚 Examples
+
+If you're looking for more examples on how to use `@carbon/react`, we have some
+examples that you can check out:
+
+- TODO
+
+## 🙌 Contributing
+
+We're always looking for contributors to help us fix bugs, build new features,
+or help us improve the project documentation. If you're interested, definitely
+check out our [Contributing Guide](/.github/CONTRIBUTING.md)! 👀
+
+## 📝 License
+
+Licensed under the [Apache 2.0 License](/LICENSE).
diff --git a/packages/carbon-react/docs/sass.md b/packages/carbon-react/docs/sass.md
@@ -0,0 +1,109 @@
+# Sass
+
+<!-- prettier-ignore-start -->
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## Table of Contents
+
+- [Overview](#overview)
+- [Configuration](#configuration)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- prettier-ignore-end -->
+
+## Overview
+
+The Carbon Design System requires [Dart Sass](http://npmjs.com/package/sass) to
+compile the styles for components. If you're running into issues where the
+styles from Carbon are not compiling, or you see `@use` rules in your code not
+being compiled by Sass, make sure to first follow the
+[configuration](#configuration) section below.
+
+If you're still running into issues with `@use` rules not compiling, most likely
+you are using Node Sass in your project. To verify if this is the case, you can
+provide options to tools like `sass-loader` in Webpack to specify the Sass
+implementation that you'd like to use.
+
+For example, this is how you would configure `sass-loader` to use the `sass`
+implementation. This normally isn't required, but can help out when running into
+the issues mentioned above.
+
+```js
+{
+  loader: 'sass-loader',
+  options: {
+    implementation: require('sass'),
+    sassOptions: {
+      includePaths: ['node_modules'],
+    },
+  },
+}
+```
+
+## Configuration
+
+You will need to configure Sass to be able to lookup packages from your
+`node_modules` folder. To do this, use the `includePaths` option and set its
+value to an array of locations where Sass should look to find `node_modules`
+folders.
+
+For most teams, this configuration will look like:
+
+```json
+{
+  "includePaths": ["node_modules"]
+}
+```
+
+For bundler specific solutions, check out the sections below for your bundler
+of choice. If you can't find what you're looking for, please make an
+[issue](https://github.com/carbon-design-system/carbon/issues/new/choose) and
+we'll try to get instructions for it added!
+
+### `sass-loader`
+
+[Link](https://www.npmjs.com/package/sass-loader)
+
+Update your `webpack.config.js` that uses `sass-loader` with the following
+options passed into `sassOptions`:
+
+```js
+{
+  loader: 'sass-loader',
+  options: {
+    sassOptions: {
+      includePaths: ['node_modules'],
+    },
+  },
+}
+```
+
+### Parcel
+
+[Link](https://www.npmjs.com/package/parcel)
+
+Create a `.sassrc` file with the following configuration:
+
+```json
+{
+  "includePaths": ["node_modules"]
+}
+```
+
+### Vite
+
+[Link](https://vitejs.dev/)
+
+Create a `vite.config.js` file with the following configuration:
+
+```js
+export default {
+  css: {
+    preprocessorOptions: {
+      scss: {
+        includePaths: ['node_modules'],
+      },
+    },
+  },
+}
+```
diff --git a/packages/carbon-react/package.json b/packages/carbon-react/package.json
@@ -35,7 +35,8 @@
   },
   "peerDependencies": {
     "react": "^16.8.6 || ^17.0.1",
-    "react-dom": "^16.8.6 || ^17.0.1"
+    "react-dom": "^16.8.6 || ^17.0.1",
+    "sass": "^1.32.12"
   },
   "dependencies": {
     "@carbon/feature-flags": "^0.3.0",
@@ -62,7 +63,8 @@
     "react-dom": "^16.8.6",
     "rimraf": "^3.0.2",
     "rollup": "^2.46.0",
-    "rollup-plugin-strip-banner": "^2.0.0"
+    "rollup-plugin-strip-banner": "^2.0.0",
+    "sass": "^1.32.12"
   },
   "sideEffects": [
     "es/feature-flags.js",

diff --git a/yarn.lock b/yarn.lock
@@ -1937,9 +1937,11 @@ __metadata:
     rimraf: ^3.0.2
     rollup: ^2.46.0
     rollup-plugin-strip-banner: ^2.0.0
+    sass: ^1.32.12
   peerDependencies:
     react: ^16.8.6 || ^17.0.1
     react-dom: ^16.8.6 || ^17.0.1
+    sass: ^1.32.12
   languageName: unknown
   linkType: soft
 
@@ -9774,7 +9776,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"chokidar@npm:>=2.0.0 <4.0.0, chokidar@npm:^3.0.0, chokidar@npm:^3.4.0":
+"chokidar@npm:>=3.0.0 <4.0.0, chokidar@npm:^3.0.0, chokidar@npm:^3.4.0":
   version: 3.5.1
   resolution: "chokidar@npm:3.5.1"
   dependencies:
@@ -28171,14 +28173,14 @@ __metadata:
   languageName: node
   linkType: hard
 
-"sass@npm:^1.24.5, sass@npm:^1.32.2, sass@npm:^1.32.4":
-  version: 1.32.8
-  resolution: "sass@npm:1.32.8"
+"sass@npm:^1.24.5, sass@npm:^1.32.12, sass@npm:^1.32.2, sass@npm:^1.32.4":
+  version: 1.32.12
+  resolution: "sass@npm:1.32.12"
   dependencies:
-    chokidar: ">=2.0.0 <4.0.0"
+    chokidar: ">=3.0.0 <4.0.0"
   bin:
     sass: sass.js
-  checksum: a4d67e6be7b3c479d44065b1dd63fc76b90cfb5f5c9684a5d93fb9721c283bae4ec3f4dab478125ee21f3618dd408a9ba65bd3ba6482ab5a422fc86e1ca18b17
+  checksum: 01ddd4abce9817d2fa46f6379bacb76605e298e8ed91fc1caed21d9b8f8ac62948f973716f8a4488f4348746aa54bb47957dfef6698e8097e07846a15fa42644
   languageName: node
   linkType: hard