Socket
Socket
Sign inDemoInstall

aristid-ds

Package Overview
Dependencies
34
Maintainers
0
Versions
84
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

aristid-ds

ARiSTiD design system


Version published
Maintainers
0
Created

Readme

Source
Aristid logo

ARiSTiD Design System Readme.

Our Storybook


Table of Contents

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
  1. Clone the repo
git clone https://gitlab.aristid.com/dev/design-system.git
  1. Install requiered packages
yarn install
  1. Start the application
yarn storybook
  1. 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
  1. 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";
  1. 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.

  2. 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
  1. In this folder create three files
cd Tooltip
touch index.tsx
touch types.d.ts
touch styles.module.scss
  1. 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';
  1. Ecample of Tooltip/styles.module.scss
@import '../../../css/mixins.scss';

:local(.kit-tooltip) {
    ...
}
  1. 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> {}
  1. 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
    

    In this file, you have all the tokens type definition. The tokens follow some rules you can find here [TODO]
  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.


    Example of component mapper :
    // 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.

  1. 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;
    

  1. 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
    };
    

  1. 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} />
    

  1. 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
    };
    
  2. 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
            ...
        }
        ...
    }
    
    
  3. 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

Tests

Tests can be slow when using the Design system. It is caused by jsdom which heavily use Window.GetComputedStyle. To workaround this performance issue, you shoud update the version of jsdom used by you test library (typically jest) to 21.1.0 or even 24.0.0. To achieve this, update your projects package.json and add these lines:

if using yarn:

    "resolutions": {
        "jsdom": "21.1.0"
    }

if using npm and jest:

    "overrides": {
        "jest-environment-jsdom": {
            "jsdom": "21.1.0"
        }
    }

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:

TypeDescriptionExample
testindicates any type of creation or alteration of test codesCreation of unit tests
featindicates the development of a new feature for the project.Adding a service, functionality, endpoint, etc
refactorused when there is a code refactoring that does not have any impact on the system logic/rulesCode changes after a code review
styleused when there are code formatting and style changes that do not change the system in any wayChange the style-guide, change the lint convention, fix indentations, remove white spaces, remove comments, etc…
fixused when correcting errors that are generating bugs in the systemApply a handling for a function that is not behaving as expected and returning an error
choreindicates changes to the project that do not affect the system or test files. These are developmental changesChange rules for eslint, add prettier, add more file extensions to .gitignore
docsused when there are changes in the project documentationadd information in the API documentation, change the README, etc
buildused to indicate changes that affect the project build process or external dependenciesadd/remove npm dependencies, etc…
perfindicates a change that improved system performancechange ForEach to While, etc…
ciused for changes in CI configuration filesCircle, Travis, BrowserStack, etc…
revertindicates the reversal of a previous commit

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
Logo

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
Logo

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
Logo

Creating a release

git flow hotfix start fixTooltip

Finishing a release

git flow hotfix finish fixTooltip

FAQs

Package last updated on 25 Jun 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚑️ by Socket Inc