aristid-ds v5.0.0

ARiSTiD Design System Readme.

Our Storybook

• Getting Started
  • Prerequisites
  • Installation
  • Usage in a project
• Development
  • Code structure
  • Creating a component
    • Component code
  • Component theming
    • Component documentation
• Nightly build
• Important
• Contributing
  • Commit
  • Gitflow - Feature - Release - Hotfix

Getting Started

Prerequisites

• npm

npm install npm@latest -g

• yarn

npm install yarn -g

Installation

1. Create a folder for this repo

mkdir DESIGN-SYSTEM

2. Clone the repo

git clone https://gitlab.aristid.com/dev/design-system.git

3. Install requiered packages

yarn install

6. Start the application

yarn storybook

7. Once the installation is complete, you can access to the application at http://localhost:6006.

Usage in a project

1. How To Import

yarn add aristid-ds

npm install aristid-ds

2. How to use KitApp

The KitApp is an essential context for the proper functioning of the design system components. This context is mainly used to supply the various components with style and translation overloads.

By default KitApp provides Aristid Theme but you can override to customize every component with theme tokens.

import {KitApp} from "aristid-ds";

<KitApp>
    <App />
</KitApp>

If you don't use KitApp, you'll get missing styles / translation and errors when using components.

1. Usage

All components are exported directly from 'aristid-ds' package.

import {KitButton, Kitcheckbox} from "aristid-ds";

4. Theme You can override default theme by passing a theme configuration to the props theme of KitApp. All tokens are available in the documentation of each components in the section Design Tokens. Your theme configuration can be ease by using the Theme Editor available in the storybook. You can edit and export a ready to use configuration.

5. Internationalization You can override default translation by passing translation configuration to the props localeof the KitApp. Major part of tokens are override by antd cf Antd translation documentation and the other part is design system tokens. You can fin them in the section Translation Tokens of each components.

Development

Code structure

1. 📁 .storybook (💡 Configuration files of Storybook)
2. 📁 src (💡 Design system code folder)
   • 📁 fonts (💡 Provided font)
   • 📁 hooks (💡 Custom Hooks)
   • 📁 Kit (💡 Components code)
     • 📁 App
     • 📁 DataDisplay
     • 📁 DataEntry
     • 📁 Feedback
     • 📁 General
     • 📁 Layout
     • index.tsx
   • 📁 theme (💡 Theming code)
     • 📁 aristid (💡 Default theme use by KitApp)
     • 📁 types (💡 Themes types declaration)
     • 📁 utils (💡 All themes utils)
       • 📁 theme-builder (💡 Use to build active theme)
       • 📁 tokens-mapper (💡 Use to map our custom tokens with Antd tokens)
       • theme-context.tsx
   • 📁 translation (💡 Translation code)
     • 📁 en-US (💡 en-US custom tokens)
     • 📁 fr-FR (💡 fr-FR custom tokens)
     • 📁 types (💡 Translation types declaration)
     • 📁 utils (💡 All translation utils)
     • locale-context.tsx
   • 📁 utils (💡 All components utils)
     • 📁 functions (💡 Function use in several components)
   • index.tsx
   • vite-env.d.ts
3. 📁 stories (💡 Storybook documentation) - 📁 01-Design - themeEditor.mdx (💡 Live theme editor page) - 📁 02-Design System (💡 Components folder) - 📁 01-General - 📁 02-Layout - 📁 03-Navigation - 📁 04-DataEntry - 📁 05-DataDisplay - 📁 06-Feedback - 📁 assets - 📁 Root - 📁 template - index.tsx (💡 Export all EditorTemplate for themeEditor.mdx) - tokens.tsx (💡 Theme tokens generate by tokens-generator.js) - types.d.ts

Creating a component

Component code

1. Create a new folder for the code of your component

mkdir DESIGN-SYSTEM/src/Kit/DataDisplay/Tooltip

2. In this folder create three files

cd Tooltip
touch index.tsx
touch types.d.ts
touch styles.module.scss

3. Example of Tooltip/index.tsx

import React, {FunctionComponent} from 'react';
import {Tooltip as AntdTooltip} from 'antd';
import {IKitTooltip} from './types';

import styles from './styles.module.scss';

export const KitTooltip: FunctionComponent<IKitTooltip> = tooltipProps => {
    const {appId} = useKitTheme();
    return <AntdTooltip {...tooltipProps}  className={`${appId} ${styles['kit-tooltip']} ${tooltipProps.className ?? ''}`}/>;
};

KitTooltip.displayName = 'KitTooltip';

4. Ecample of Tooltip/styles.module.scss

@import '../../../css/mixins.scss';

:local(.kit-tooltip) {
    ...
}

5. Example of Tooltip/types.d.ts

import {TooltipProps} from 'antd';
import {HTMLAttributes} from 'react';

type AntdTooltipTypesToOmit = 'color' | 'overlayClassName' | 'overlayStyle' | 'overlayInnerStyle';

export interface IKitTooltip extends Omit<TooltipProps, AntdTooltipTypesToOmit>, HTMLAttributes<HTMLDivElement> {}

5. Export your component in /Kit/05-DataDisplay/index.tsx

import {KitTooltip} from './Tooltip';
...
export {KitTooltip};

Component theming

Every components style of the design system can be override by tokens.

1. Create a token file type The themefolder is structure as same as the Kit folder.

   mkdir DESIGN-SYSTEM/src/theme/type/components/DataDisplay/tooltip

2. Create a token file The token file is the definition of all tokens with their value. It exports a function that create the theme for the cmponent. You define this file in the aristid that is the default theme of the design system.

   mkdir DESIGN-SYSTEM/src/theme/aristid/components/DataDisplay/tooltip

3. Global theme type After that, go to file src/theme/type/index.tsxto add your component type. This files contains all components that can be override.

4. Global theme You can now add your component in the src/theme/aristid/index.tsx and you add your component and the function that creates tokens defined in point 2.

5. Component Antd mapper As we use both antd and design system tokens, we normalize all token to follow a same model. If your component uses antd tokens, you have to add a mapper in the src/theme/utils/tokens-mapper folder. This folder as the same folder structure as the rest of the application.

   // utils/tokens-mapper/DataDisplay/Tag
   
   import {IKitTagTheme} from '@theme/types/components/DataDisplay/Tag';
   
   export const mapTagKitTokenToAntdToken = (kitTagTheme: IKitTagTheme) => {
       const {colors, border} = kitTagTheme;
   
       return {
           defaultBg: colors.default.background.default,
           defaultColor: colors.default.typography.default,
           borderRadiusSM: border.radius
       };
   };

6. Global theme mapper After that, you have to add your component mapper to the global mapper in the file src/theme/utils/tokens-mapper/index.tsx.

7. Theme consumption You can use the theme in your styled component by calling the hook useKitTheme. You can get the component theme by calling theme.components.Tooltip.

   const {theme} = useKitTheme();
   
   const tooltipTheme = theme.components.Tooltip;
   
   return <KitTooltip $theme={tooltipTheme} />;

Component documentation

1. Copy - Paste the template folder (stories/template) This folder contains all required files to create component documentation.
   • examples : contains all the code of examples, index.tsx export all examples in the convenient format.
   • data.tsx: contains the API data (Args, Template, ...)
   • Component.mdx : file that contains the component documentation (usage / examples / api / tokens)
   • Component.stories.tsx : file use by storybook as a story to test and display.

2. Implement examples Create all examples needed in the documentation.

   // basic.tsx
   import React from 'react';
   
   const App = () => {
       return (
           <KitTooltip title"this is an example">
               <div>Template Example</div>
           </KitTooltip>
       );
   };
   
   export default App;

3. Export examples You have to export all of your examples in the index.tsx of the examples folder. It permits to export all files in the convenient format to be read by the custom canvas component.

   import Basic from './basic';
   
   import BasicSource from './basic?raw';
   
   export const Sources = {
       Basic: BasicSource
   };
   export default {
       Basic
   };

4. Modify Component.mdx

   • Rename Component in the file name by your component name (ex : Tooltip.mdx).
   • Rename Component in the file by your component name.
   • Complete all examples you want to display in documentation.

   // Tooltip.mdx
   import { Meta, Story, Canvas } from "@storybook/addon-docs";
   import { Controls } from "@storybook/addon-docs";
   import { argTypes, Template } from "./data";
   import Examples, { Sources } from './examples';
   import CustomCanvas from '../../../../.storybook/components/CustomCanvas.jsx';
   import DesignTokens from '../../.storybook/components/DesignTokens';
   import fields from '../tokens';
   import * as Tooltip from './Tooltip.stories';
   
   <Meta of={Tooltip} />
   
   # Tooltip
   
   Brief component description.
   
   ## Examples
   
   ##### Basic
   Example description
   
   <CustomCanvas content={Examples.Basic} source={Sources.Basic} id="tooltip-basic"/>
   
   ## Api
   
   <Canvas of={Tooltip.Api} />
   
   <Controls of={Tooltip.Api} />
   
   ## Design Tokens
   
   <DesignTokens path="components.Tooltip" tokens={fields?.components?.Tooltip} />

5. Modify Component.stories.tsx

   • Rename Component in the file name by your component name (ex : Tooltip.stories.tsx).
   • Rename the meta object title attribute by the pass of the component (ex : title: 'Design System/DataDisplay/Tooltip'). The path specify where the component will be placed in the storybook.
   • Replace KitComponent by your component (ex KitTooltip).

   // Tooltip.stories.tsx
   import type {Meta, StoryObj} from '@storybook/react';
   import {KitTooltip} from '@components/DataDisplay';
   import {argTypes, Template} from './data';
   
   const meta: Meta<typeof KitTooltip> = {
       component: KitTooltip,
       title: 'Design System/DataDisplay/Tooltip',
       argTypes: argTypes
   };
   
   export default meta;
   type Story = StoryObj<typeof KitTooltip>;
   
   export const Api: Story = {
       render: Template
   };

6. Import Component Theme Editor Template In the data.tsx file, you defined a EditorTemplate. It permits to modify in live all tokens and get a preview of the component. You have to import this Editor in the stories/index.tsxand add it inside the object that contains all theme editor that already exist.

   import {EditorTemplate as Tooltip} from './02-Design System/05-DataDisplay/Tooltip/data';
   
   export default {
       ...
       DataDisplay: {
           ...
           Tooltip
           ...
       }
       ...
   }

7. Design tokens generation When everything is setup, you have to run the tokens-generator script to generate all design tokens in the documentation.

   node tokens-generator.js

   After the script run, section Design Tokens documentation is up to date with all design tokens.

Nightly build

A nightly version of the package is published on daily basis on branch develop (assuming new commits have been pushed on develop branch). To use it just install the more recent next version :

    yarn add aristid-ds@next

Note: Though it is useful to test upcoming feature, this version should NEVER be used in production

Important

Every import of antd library should pass by antd or ant/es. lib import will lead to issues in the build process.

Contributing

Any contributions you make are greatly appreciated. If you have a suggestion that would make this better, please create a pull request. You can also simply open an issue with the appropriate tag to report a bug or inconsistencies in documentation.

Commit

Commit message must respect the following pattern :

git commit -m "type[(component)] : message"

The type is telling us what change or iteration is being made. We have the following types:

Example :

git commit -m "style(Tooltip) : Change color on hover"

📚 Based on this article.

Gitflow

We use Gitflow as Git branching model for this project. We have two branches to record our project history :

• main (💡 Stores the official release history)
• develop (💡 Serves as an integration branch for features)

📚 Based on this article.

Feature

Creating a feature branch

git flow feature start addTooltipComponent

Continue your work and use Git like you normally would.

Finishing a feature branch

git flow feature finish addTooltipComponent

Release

Creating a release

git flow release start 0.1.0

⚠️ - Don't forget to update the version number in package.json

Finishing a release

git flow release finish '0.1.0'

Hotfix

Creating a release

git flow hotfix start fixTooltip

Finishing a release

git flow hotfix finish fixTooltip