diff --git a/README.md b/README.md index b1622b7d5..a68be25bd 100644 --- a/README.md +++ b/README.md @@ -124,14 +124,16 @@ For a list and description of features offered by the AsyncAPI React component, ## Styles -To use default styles import them as follows: +To use the default styles import them as follows: ``` js -import "@asyncapi/react-component/styles/default.css"; -// or minified version import "@asyncapi/react-component/styles/default.min.css"; ``` +The above file hasn't built-in [TailwindCSS Preflight](https://tailwindcss.com/docs/preflight) styles which reset the base styles for the main HTML tags. If you want to add styles with the CSS reset, you should import the `@asyncapi/react-component/styles/default.reset.min.css` styles. + +If you want to add custom styles (especially colors) to the component, see [theming](./docs/features/theming.md) documentation. + ## Playground This repository comes in with a [Playground application](https://asyncapi.github.io/asyncapi-react/). Test it to see the component in action and play with it before you use it in your application. diff --git a/docs/README.md b/docs/README.md index 07f600700..b59e1d419 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,6 +8,7 @@ This directory contains the following documents that relate to the project: - [Development Guide](./development/guide.md) describes how to set up a development environment, write, and run tests. It also contains the naming and architecture convention. - features: - [Anchors](./features/anchors.md) describes internal anchors in the AsyncAPI component. + - [Theming](./features/theming.md) describes how to generate/add custom styles for component. - [Highlight markdown's code blocks](./features/highlight.md) describes how to add custom language configuration for `highlight.js` used in the component. - usage: - [Using in Angular](./usage/angular.md) describes how to use the AsyncAPI component in Angular project. diff --git a/docs/features/theming.md b/docs/features/theming.md index 6358a1220..57a30ff0b 100644 --- a/docs/features/theming.md +++ b/docs/features/theming.md @@ -1 +1,53 @@ # Theming + +## Overview + +The component internally uses for styling the utility-first [TailwindCSS](https://tailwindcss.com/) framework. Check this document to known how to customize styling for component. + +## Generate theme from configuration file + +As we read in the official docs for [TailwindCSS](https://tailwindcss.com/): + +> Because Tailwind is a framework for building bespoke user interfaces, it has been designed from the ground up with customization in mind. + +...and this is how the way of customizing styles for the component was also designed. The configuration file should be in the form of a [TailwindCSS configuration file](https://tailwindcss.com/docs/configuration). Then the custom configuration file must be passed to the NodeJS script, which is located inside the `./tools/styles/script.js` in the component's package. + +The script itself takes as arguments: + +```bash +node ./tools/styles/script.js +``` + +where: +- `` is a relative path for the output css file. It must contains the name of the css file. Example: `./output/custom-theme.css` +- `` is a relative path to the custom [TailwindCSS configuration file](https://tailwindcss.com/docs/configuration). + +Important notes: + +- The custom configuration is deeply merged with the [default configuration file](../../library/tools/styles/tailwind.config.js). + +- To generate the production-ready, tree-skahable, css styles you should run the script with `NODE_ENV=production` environment: + + ```bash + NODE_ENV=production node ./tools/styles/script.js ./output/custom-theme.css ./custom-config.js + ``` + + Generating production styles will add a `.min.css` suffix to the generated files. + +- Script will generate two separate css files, one with `.reset.css` suffix with [Preflight](https://tailwindcss.com/docs/preflight) styles onboard and second without `Preflight` onboard. If you use your own base styles in your project, you should use this one with the `.reset.css` suffix. + +- If you installed the `@asyncapi/react-component` package in your project, script should be run with the `./node_modules/@asyncapi/react-component/tools/styles/script.js` path in a root of project. + +## Change manually styles + +> **NOTE:** This is not the recommended method - better to use the [configuration file](#generate-theme-from-configuration-file). + +To manually change the style you can write your own css properties for appropriate TailwindCSS class. For example, to change the a very frequently used color, you can override it by css class: + +```css +.text-gray-700 { + color: red; +} +``` + +> **NOTE:** Remember that the given override must be loaded after loading the styles from the component. diff --git a/library/package-lock.json b/library/package-lock.json index 16dfac95a..fd75f8b96 100644 --- a/library/package-lock.json +++ b/library/package-lock.json @@ -748,7 +748,6 @@ "version": "0.4.0", "resolved": "https://registry.npmjs.org/@tailwindcss/typography/-/typography-0.4.0.tgz", "integrity": "sha512-3BfOYT5MYNEq81Ism3L2qu/HRP2Q5vWqZtZRQqQrthHuaTK9qpuPfbMT5WATjAM5J1OePKBaI5pLoX4S1JGNMQ==", - "dev": true, "requires": { "lodash.castarray": "^4.4.0", "lodash.isplainobject": "^4.0.6", @@ -6052,8 +6051,7 @@ "lodash.castarray": { "version": "4.4.0", "resolved": "https://registry.npmjs.org/lodash.castarray/-/lodash.castarray-4.4.0.tgz", - "integrity": "sha1-wCUTUV4wna3dTCTGDP3c9ZdtkRU=", - "dev": true + "integrity": "sha1-wCUTUV4wna3dTCTGDP3c9ZdtkRU=" }, "lodash.clonedeep": { "version": "4.5.0", @@ -6063,8 +6061,7 @@ "lodash.isplainobject": { "version": "4.0.6", "resolved": "https://registry.npmjs.org/lodash.isplainobject/-/lodash.isplainobject-4.0.6.tgz", - "integrity": "sha1-fFJqUtibRcRcxpC4gWO+BJf1UMs=", - "dev": true + "integrity": "sha1-fFJqUtibRcRcxpC4gWO+BJf1UMs=" }, "lodash.memoize": { "version": "4.1.2", @@ -6074,8 +6071,7 @@ "lodash.merge": { "version": "4.6.2", "resolved": "https://registry.npmjs.org/lodash.merge/-/lodash.merge-4.6.2.tgz", - "integrity": "sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==", - "dev": true + "integrity": "sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==" }, "lodash.once": { "version": "4.1.1", diff --git a/library/package.json b/library/package.json index f14fde7d7..f43016a27 100644 --- a/library/package.json +++ b/library/package.json @@ -67,6 +67,7 @@ "@asyncapi/avro-schema-parser": "^0.2.0", "@asyncapi/openapi-schema-parser": "^2.0.0", "@asyncapi/parser": "^1.5.0", + "@tailwindcss/typography": "^0.4.0", "autoprefixer": "^10.2.5", "highlight.js": "^10.7.2", "isomorphic-dompurify": "^0.13.0", @@ -81,7 +82,6 @@ }, "devDependencies": { "@cypress/webpack-preprocessor": "^5.9.0", - "@tailwindcss/typography": "^0.4.0", "@types/dompurify": "^2.0.4", "@types/highlight.js": "^10.1.0", "@types/jest": "^24.0.18",