From af8bad531492dc15a883ec62ed9694f8a7e07df7 Mon Sep 17 00:00:00 2001 From: Matthias Goudjil Date: Wed, 5 Jun 2024 19:39:02 +0200 Subject: [PATCH] docs: [storybook-and-readme] related #336 wip --- README.md | 13 +- RELEASE.md | 2 +- docs/assets/img/tailwind-css.svg | 1 + docs/assets/img/web-components.svg | 1 + docs/stories/docs/Css.mdx | 26 ++- docs/stories/docs/Introduction.mdx | 44 ++++- docs/stories/docs/TailwindPreset.mdx | 229 ++++++++++++++++----------- docs/stories/docs/VueJs.mdx | 57 ++++--- docs/stories/docs/WebComponents.mdx | 73 +++++++++ packages/components/README.md | 4 +- packages/puik/README.md | 12 +- packages/resolver/README.md | 3 +- packages/tailwind-preset/README.md | 8 +- packages/theme/README.md | 7 +- 14 files changed, 332 insertions(+), 148 deletions(-) create mode 100644 docs/assets/img/tailwind-css.svg create mode 100644 docs/assets/img/web-components.svg create mode 100644 docs/stories/docs/WebComponents.mdx diff --git a/README.md b/README.md index d70b3ca3..188effa2 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Puik is a component library that aims to provide a complete set of reusable components based on the PrestaShop Design System for all the PrestaShop ecosystem. -🚧 Please note that version 2 of this project is still in beta. There are significant changes from version 1 to version 2. For more informations, please refer to the [release-notes-v2](./RELEASE-NOTES-V2.md) +🚧 Please note there are significant changes from version 1 to version 2. For more informations, please refer to the [release-notes-v2](RELEASE-NOTES-V2.md) ## Contributing @@ -29,12 +29,11 @@ Please make sure to read the Contributing Guide before making a pull request. This monorepo contains the following libraries: -- [@prestashopcorp/puik-components](https://www.npmjs.com/package/@prestashopcorp/puik-components) a Vue 3 component library -- [@prestashopcorp/puik-web-components](https://www.npmjs.com/package/@prestashopcorp/puik-web-components) a Web component library -- [@prestashopcorp/puik-resolver](https://www.npmjs.com/package/@prestashopcorp/puik-resolver) a component resolver for our Vue 3 component library -- [@prestashopcorp/puik-theme](https://www.npmjs.com/package/@prestashopcorp/puik-theme) a CSS library containing all the classes used in our components -- [@prestashopcorp/puik-tailwind-preset](https://www.npmjs.com/package/@prestashopcorp/puik-tailwind-preset) a Tailwind Css preset that contains all the design tokens used to create the components -- [@prestashopcorp/puik](https://www.npmjs.com/package/@prestashopcorp/puik) a library containing all the other libraries +- [@prestashopcorp/puik-components](packages/components/README.md) a Vue 3 components library +- [@prestashopcorp/puik-web-components](packages/web-components/README.md) a Web components library +- [@prestashopcorp/puik-resolver](packages/resolver/README.md) a component resolver for our Vue 3 component library +- [@prestashopcorp/puik-theme](packages/theme/README.md) a CSS library containing all the classes used in our components +- [@prestashopcorp/puik-tailwind-preset](packages/tailwind-preset/README.md) a Tailwind Css preset that contains all the design tokens used to create the components ## Installation diff --git a/RELEASE.md b/RELEASE.md index 18383825..82138ed7 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,6 +1,6 @@ # How to release -To release new versions of our package we use a Github action that triggers on the creation of a new Github release +To release new versions of our package we use a Github action that triggers on the creation of a new Github release As we use [pnpm](https://pnpm.io/) to manage our monorepo the `pnpm publish` command is used in this Github action and will release all the packages not flagged with the `private` property in the `package.json` The released packages are: diff --git a/docs/assets/img/tailwind-css.svg b/docs/assets/img/tailwind-css.svg new file mode 100644 index 00000000..6a9ab499 --- /dev/null +++ b/docs/assets/img/tailwind-css.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/assets/img/web-components.svg b/docs/assets/img/web-components.svg new file mode 100644 index 00000000..a1e3ce54 --- /dev/null +++ b/docs/assets/img/web-components.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/stories/docs/Css.mdx b/docs/stories/docs/Css.mdx index 7b667e30..28c6f51b 100644 --- a/docs/stories/docs/Css.mdx +++ b/docs/stories/docs/Css.mdx @@ -2,23 +2,39 @@ import { Meta } from '@storybook/blocks' -# Css Components +# CSS Components +Puik Theme is a Css library that contains all the CSS classes used to create the Vue Components. If you don't use VueJS for your application, you can use the CSS only version of our components. It includes all the styles used in the VueJs component library. -## Usage +## Installation + +Install the `@prestashopcorp/puik-theme` package and import the css files you need + +```shell +# NPM +$ npm install @prestashopcorp/puik-theme --save + +# Yarn +$ yarn add @prestashopcorp/puik-theme -1. Include the CSS in your HTML +# pnpm +$ pnpm install @prestashopcorp/puik-theme +``` + +Or include the CSS in your HTML by using the CDN ```html ``` -2. Add the classes in your HTML +## Usage + +Once the CSS styles are loaded using the CDN or by importing the library, you can start using all the classes prefixed by `puik-` ```html diff --git a/docs/stories/docs/Introduction.mdx b/docs/stories/docs/Introduction.mdx index 80af0af0..3b1dbf2c 100644 --- a/docs/stories/docs/Introduction.mdx +++ b/docs/stories/docs/Introduction.mdx @@ -2,6 +2,8 @@ import { Meta } from '@storybook/blocks' import { linkTo } from '@storybook/addon-links' import VueJsLogo from '../../assets/img/Vue.js_Logo.png' import CssLogo from '../../assets/img/css.svg' +import WebComponentsLogo from '../../assets/img/web-components.svg' +import TailwindCssLogo from '../../assets/img/tailwind-css.svg' import Repo from '../../assets/img/repo.svg' import GitHubLogo from '../../assets/img/GitHub-Mark-64px.png' import FigmaLogo from '../../assets/img/Figma-Icon.svg' @@ -68,9 +70,17 @@ import FigmaLogo from '../../assets/img/Figma-Icon.svg' # Puik -Puik is a component library that aims to provide a complete set of reusable components based on the PrestaShop Design System for all the PrestaShop ecosystem. +
About The Project
-This library provides two ways of using the design system in your project, the first one is by using the VueJs components and the second one by using the css classes from the theme +Puik is a library that aims to provide a complete set of reusable components based on the PrestaShop Design System for all the PrestaShop ecosystem. This project includes the following packages: + +- [@prestashopcorp/puik-components](https://www.npmjs.com/package/@prestashopcorp/puik-components) a Vue 3 components library +- [@prestashopcorp/puik-web-components](https://www.npmjs.com/package/@prestashopcorp/puik-web-components) a Web components library +- [@prestashopcorp/puik-resolver](https://www.npmjs.com/package/@prestashopcorp/puik-resolver) a component resolver for our Vue 3 component library +- [@prestashopcorp/puik-theme](https://www.npmjs.com/package/@prestashopcorp/puik-theme) a CSS library containing all the classes used in our components +- [@prestashopcorp/puik-tailwind-preset](https://www.npmjs.com/package/@prestashopcorp/puik-tailwind-preset) a Tailwind Css preset that contains all the design tokens used to create the components + +This library provides three ways of using the design system in your project by using the VueJs components, the css classes from the theme or by using Web components.
Getting Started
@@ -79,18 +89,38 @@ This library provides two ways of using the design system in your project, the f VueJs Components - Setup For VueJS - Setup the library for a usage with VueJs + Setup for VueJS + Setup the Puik Components library -
+
Css Components - Setup for other language/framework - Setup the library with another language or framework + Setup for CSS components + Setup the Puik Theme library (CSS components) + + +
+ +
+ Web Components + + + Setup for WebComponents + Setup the Puik Web Components library + + +
+ +
+ Web Components + + + Setup for Tailwind CSS + Setup the Puik Tailwind Preset library
diff --git a/docs/stories/docs/TailwindPreset.mdx b/docs/stories/docs/TailwindPreset.mdx index f74044d1..7acaac12 100644 --- a/docs/stories/docs/TailwindPreset.mdx +++ b/docs/stories/docs/TailwindPreset.mdx @@ -4,19 +4,38 @@ import { Meta } from '@storybook/blocks' # Tailwind CSS Preset -If you want to use the Tailwind CSS preset used for this library you can -import the configuration in your project +Puik Tailwind Preset is a [Tailwind CSS](https://tailwindcss.com/) preset that aims to provide all the design tokens based on the PrestaShop Design System for all the PrestaShop ecosystem. + +## Prerequisites + +- Tailwind Css 3+ + +## Installation + +Install the `@prestashopcorp/puik-tailwind-preset` package + +```shell +# NPM +$ npm install @prestashopcorp/puik-tailwind-preset --save + +# Yarn +$ yarn add @prestashopcorp/puik-tailwind-preset + +# pnpm +$ pnpm install @prestashopcorp/puik-tailwind-preset +``` ## Usage +If you want to use the Tailwind CSS preset used for this library you can import the configuration in your project. + Require the puikTailwindPreset in your `tailwind.config.{js|ts}` file -```js -const { puikTailwindPreset } = require('@prestashopcorp/puik') +```typescript +const { puikTailwindPreset } = require('@prestashopcorp/puik-tailwind-preset') /** @type {import('tailwindcss').Config} */ module.exports = { presets: [puikTailwindPreset], - content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'], } ``` @@ -26,103 +45,127 @@ Congratulations you can now use all the tailwind classes used in the library ```js { - colors: { - primary: { - get DEFAULT() { - return this['800'] - }, - 100: '#FFFFFF', - 200: '#F7F7F7', - 300: '#EEEEEE', - 400: '#DDDDDD', - 500: '#BBBBBB', - 600: '#5E5E5E', - 700: '#3F3F3D', - 800: '#1D1D1B', - }, - red: { - get DEFAULT() { - return this['500'] - }, - 50: '#FFE4E6', - 100: '#FDBFBF', - 300: '#D63F3C', - 500: '#BA151A', - 700: '#A41913', + colors: { + primary: { + get DEFAULT() { + return this['800']; }, - purple: { - get DEFAULT() { - return this['500'] - }, - 50: '#F8F0F7', - 500: '#DECDE7', - 700: '#7B4FAC', - }, - blue: { - get DEFAULT() { - return this['500'] - }, - get pressed() { - return this['700'] - }, - 50: '#E8EDFD', - 100: '#D1DCFC', - 300: '#A2B8F9', - 500: '#174EEF', - 700: '#2942CC', - }, - 'ocean-blue': { - get DEFAULT() { - return this['500'] - }, - 50: '#E4F4F8', - 500: '#A4DBE8', - 700: '#5C92AA', + 100: '#FFFFFF', + 200: '#F7F7F7', + 300: '#EEEEEE', + 400: '#DDDDDD', + 500: '#BBBBBB', + 600: '#5E5E5E', + 700: '#3F3F3D', + 800: '#1D1D1B' + }, + red: { + get DEFAULT() { + return this['500']; }, - yellow: { - get DEFAULT() { - return this['500'] - }, - 50: '#FFF5E5', - 100: '#FFECCC', - 300: '#FFD999', - 500: '#ffA000', + 50: '#FFE4E6', + 100: '#FDBFBF', + 300: '#D63F3C', + 500: '#BA151A', + 700: '#A41913' + }, + purple: { + get DEFAULT() { + return this['500']; }, - amber: { - get DEFAULT() { - return this['500'] - }, - 100: '#FDF6DD', - 500: '#F8E08E', + 50: '#F8F0F7', + 500: '#DECDE7', + 700: '#7B4FAC' + }, + blue: { + get DEFAULT() { + return this['500']; }, - green: { - get DEFAULT() { - return this['500'] - }, - get marketing() { - return this['100'] - }, - 50: '#EAF8EF', - 100: '#BDE9C9', - 300: '#59AF70', - 500: '#207F4B', + get pressed() { + return this['700']; }, + 50: '#E8EDFD', + 100: '#D1DCFC', + 300: '#A2B8F9', + 500: '#174EEF', + 700: '#2942CC' }, - fontFamily: { - primary: ['IBM Plex Sans', 'Verdana', 'Arial', 'sans-serif'], - secondary: ['Prestafont', 'Verdana', 'Arial', 'sans-serif'], - materialIcons: ['Material Icons Round'], - }, - fontSize: { - '4xl': '2rem', + 'ocean-blue': { + get DEFAULT() { + return this['500']; + }, + 50: '#E4F4F8', + 500: '#A4DBE8', + 700: '#5C92AA' }, - screens: { - xs: '320px', + yellow: { + get DEFAULT() { + return this['500']; + }, + 50: '#FFF5E5', + 100: '#FFECCC', + 300: '#FFD999', + 500: '#ffA000' }, - boxShadow: { - overlay: '0px 4px 8px rgba(0, 0, 0, 0.1)', - sticky: '0px 6px 12px rgba(0, 0, 0, 0.1)', + amber: { + get DEFAULT() { + return this['500']; + }, + 100: '#FDF6DD', + 500: '#F8E08E' }, + green: { + get DEFAULT() { + return this['500']; + }, + get marketing() { + return this['100']; + }, + 50: '#EAF8EF', + 100: '#BDE9C9', + 300: '#59AF70', + 500: '#207F4B' + } + }, + fontFamily: { + primary: ['IBM Plex Sans', 'Verdana', 'Arial', 'sans-serif'], + secondary: ['Prestafont', 'Verdana', 'Arial', 'sans-serif'], + materialIcons: ['Material Icons Round'] + }, + fontSize: { + xs: ['0.75rem', { lineHeight: '1.125rem' }], + sm: ['0.875rem', { lineHeight: '1.25rem' }], + base: ['1rem', { lineHeight: '1.375rem' }], + lg: ['1.125rem', { lineHeight: '1.375rem' }], + xl: ['1.25rem', { lineHeight: '1.75rem' }], + '2xl': ['1.5rem', { lineHeight: '2rem' }], + '3xl': ['1.875rem', { lineHeight: '2.25rem' }], + '4xl': ['2rem', { lineHeight: '2.625rem' }], + '5xl': ['3rem', { lineHeight: '3.625rem' }] + }, + screens: { + xs: '320px' + }, + minHeight: { + sm: '1.75rem', + md: '2.25rem', + lg: '3rem' + }, + opacity: { + overlay: '0.8' }, + boxShadow: { + DEFAULT: '0px 1px 3px 0px rgba(29, 29, 27, 0.2)', + sm: '0px 1px 2px 0px rgba(29, 29, 27, 0.05)', + md: '0px 4px 6px -1px rgba(29, 29, 27, 0.2)', + lg: '0px 10px 15px -3px rgba(29, 29, 27, 0.2)', + xl: '0px 20px 25px -5px rgba(29, 29, 27, 0.2)', + '2xl': '0px 25px 60px -12px rgba(29, 29, 27, 0.25)', + inner: 'inset 0 2px 4px 0 rgb(0 0 0 / 0.05)', + none: 'none', + overlay: '0px 12px 60px 0px rgba(0, 0, 0, 0.1)', + sticky: '0px 6px 12px rgba(0, 0, 0, 0.1)', + 'pop-modal': '0px 12px 24px rgba(0, 0, 0, 0.1)' + } } ``` diff --git a/docs/stories/docs/VueJs.mdx b/docs/stories/docs/VueJs.mdx index 3d15b4d1..7537e99b 100644 --- a/docs/stories/docs/VueJs.mdx +++ b/docs/stories/docs/VueJs.mdx @@ -2,49 +2,55 @@ import { Meta } from '@storybook/blocks' -# VueJs components +# VueJs Components -### Prerequisites +Puik Components is a Vue Components library that aims to provide a complete set of reusable components based on the PrestaShop Design System for all the PrestaShop ecosystem. + +## Prerequisites - Node.js LTS is required. +- Vue 3 + +## Installation -### Installation +Install the `@prestashopcorp/puik-components` package -```sh -# chose your favorite package manager +```shell # NPM -$ npm install @prestashopcorp/puik --save +$ npm install @prestashopcorp/puik-components --save # Yarn -$ yarn add @prestashopcorp/puik +$ yarn add @prestashopcorp/puik-components # pnpm -$ pnpm install @prestashopcorp/puik +$ pnpm install @prestashopcorp/puik-components ``` ## Usage -#### Auto import (recommended) +### Auto import using Puik Resolver (recommended) -First you need to install `unplugin-vue-components` & `unplugin-auto-import` +First you need to install `unplugin-vue-components`, `unplugin-auto-import` and the Puik resolver `@prestashopcorp/puik-resolver` -```sh -$ npm install -D unplugin-vue-components unplugin-auto-import +```shell +$ npm install -D unplugin-vue-components unplugin-auto-import @prestashopcorp/puik-resolver # Yarn -$ yarn add unplugin-vue-components unplugin-auto-import -D +$ yarn add unplugin-vue-components unplugin-auto-import @prestashopcorp/puik-resolver -D # pnpm -$ pnpm install unplugin-vue-components unplugin-auto-import -D +$ pnpm install unplugin-vue-components unplugin-auto-import @prestashopcorp/puik-resolver -D ``` Then add the code below in your vite.config file -```typescript +ℹ️ if you don't use Vite [follow this link](https://github.com/unplugin/unplugin-vue-components?tab=readme-ov-file#installation) + +```js import { defineConfig } from 'vite' import Components from 'unplugin-vue-components/vite' import AutoImport from 'unplugin-auto-import/vite' -import { PuikResolver } from '@prestashopcorp/puik' +import { PuikResolver } from '@prestashopcorp/puik-resolver' export default defineConfig({ plugins: [ @@ -63,10 +69,10 @@ export default defineConfig({ Import the vue component and the component css directly into your vue file -```vue +```js ``` -You can find out more about [unplugin-vue-components](https://github.com/unplugin/unplugin-vue-components#readme) and [unplugin-auto-imports](https://github.com/unplugin/unplugin-auto-import#readme) in their documentation \ No newline at end of file +You can find out more about [unplugin-vue-components](https://github.com/unplugin/unplugin-vue-components#readme) and [unplugin-auto-imports](https://github.com/unplugin/unplugin-auto-import#readme) in their documentation diff --git a/packages/tailwind-preset/README.md b/packages/tailwind-preset/README.md index f3dc821b..d245145c 100644 --- a/packages/tailwind-preset/README.md +++ b/packages/tailwind-preset/README.md @@ -34,10 +34,12 @@ $ pnpm install @prestashopcorp/puik-tailwind-preset ## Usage -If you want to use the Tailwind CSS preset used for this library you can import the configuration in your project +If you want to use the Tailwind CSS preset used for this library you can import the configuration in your project. + +Require the puikTailwindPreset in your `tailwind.config.{js|ts}` file ```typescript -const { puikTailwindPreset } = require('@prestashopcorp/puik') +const { puikTailwindPreset } = require('@prestashopcorp/puik-tailwind-preset') /** @type {import('tailwindcss').Config} */ module.exports = { presets: [puikTailwindPreset], @@ -46,4 +48,4 @@ module.exports = { ## Available tokens -You can find all the available tokens [here](./theme.ts) +You can find all the available tokens [here](https://github.com/PrestaShopCorp/puik/blob/main/packages/tailwind-preset/theme.ts) diff --git a/packages/theme/README.md b/packages/theme/README.md index c8170d5b..0c6010ca 100755 --- a/packages/theme/README.md +++ b/packages/theme/README.md @@ -41,7 +41,8 @@ Or include the CSS in your HTML by using the CDN ## Usage -Once the CSS styles are loaded using the CDN or by importing the library, you can start using all the classes prefixed by `puik-` +Once the CSS styles are loaded using the CDN or by importing the library, you can start using all the classes prefixed by `puik-` + ```html - -``` \ No newline at end of file + +```