Maintenance mode

Gaia design system (@gaiads/telia-react-component-library) is now in maintenance mode, and DS team focuses fully on Global DS.

What does this mean in practice:

• New features - No new features such as new components or significant changes to existing ones will be done to the React library as they will be delivered as Web Components.
• Fixing - bugs and other abnormal functionality Only when they are deemed critical (see below).
• Usage - guidance for components Simple guidance can be provided to teams using the components, but no complex cases or onboarding are supported.
• Helping - with a contribution of improvements/fixes to existing complex components Only when they are deemed critical (see below).
• Definition of Critical - When a feature is missing or contains bugs that break existing systems and no workaround is available, they are considered critical. This is decided on a case-by-case basis by the Core Team.

You are free to ask questions and help each other in #design-system Slack channel! Please let us know if you have any questions about this.

~ DS team

Telia React Component Library

This is a react component library and living styleguide, showing the components which should be used in Telia Finland's web applications to achieve common look & feel, and therefore user experience.

How to use

1. Install component library as a dependency
2. Add component library styles to your bundle
3. Done!

Installation

You can install component library as any node package

npm install @gaiads/telia-react-component-library --save

Alternative installation with Github

In case the artifactory for some reason is a no go for you, you can install the library using Github.

npm install --save https://{USER}:{ACCESS_TOKEN}@github.com/telia-company/telia-react-component-library/archive/{VERSION}.tar.gz

Read how to create an access token

importing components from component library in your project

Component library supports three types of module format

• CommonJS
• ES modules
• Universal Module definition (UMD)

If you need to import UMD modules you need to target the UMD file explicity

import { button } from '@gaiads/telia-react-component-library/build/index.umd.js'

In case your project is typscript codebase currently UMD build doesn't support typescript. Exporting multiple type declaration files are not supported in npm package so far and because of this typescript will give error that corresponding type declaration file is missing. To fix this issue do the following

• Create a new folder called types in same path as file which is importing component from component library
• Create a file index.umd.d.ts in the types folder

Add following contents inside the file:

declare module '@gaiads/telia-react-component-library/build/index.umd.js';

Add component library styles in your project

You should add the styles into your bundle. Usually this is done by importing them in your index.js like so:

import '@gaiads/telia-react-component-library/build/index.css';

Typescript support

The component library supports Typescript by exposing the d.ts file with component type declarations. Projects don't have to make any settings for taking this feature in use, but it works automatically for typescript projects.

Design tokens support

The component library supports design tokens by exposing the css and scss variables files with. These files can be imported from build/tokens directory.

import '@gaiads/telia-react-component-library/build/tokens/css/_variables.css';

.my-class {
  background-color: var(--gaia-color-black);
}

import '@gaiads/telia-react-component-library/build/tokens/scss/_variables.scss';

z-index support

With growing numnber of UI elements it is challenging to manage z-index. Defining set of rules for z-index makes them more manageable. Z index token can be used as follows

import '@gaiads/telia-react-component-library/build/tokens/css/_variables.css';

.my-class {
  z-index: var(--gaia-z-index-default);
}

import '@gaiads/telia-react-component-library/build/tokens/scss/_variables.scss';

.my-class {
  z-index: $gaia-z-index-default;
}

It is also possible to import z-index scss function file and use this function with z-index name.

import '@gaiads/telia-react-component-library/build/styles/zindex.scss';

.my-class {
  z-index: z('default');
}

Development

Getting started

• Fork the repository
• Clone your own fork
• Set upstream repository with git remote add upstream [email protected]:telia-company/telia-react-component-library.git
  • When pulling changes/rebasing from upstream, remember to use git pull --rebase upstream master
  • After this you should update your remote fork with git push --force-with-lease origin master
• Install dependencies with npm install
• Run storybook with npm run storybook
• Run tests in terminal with npm run test
• Access storybook in URL http://localhost:6007

Viewing designs in Zeplin

• Register to Zeplin
• Ask designers to add your Zeplin account into the Telia design projects

Coding conventions

It's very important that you read the coding conventions which have been documented in here. See also our code review checklist

Creating new component

To create new files, you can use the 'plop' script included in devDependencies.

npm run plop

You can also manually add the files. Make sure to follow coding conventions of the repo!

• Create a directory called YourComponentName in src/components
• Inside the directory, create two files for your component: YourComponentName.test.js and YourComponentName.js
• Create also YourComponentName.stories.js file under src/styleguide
• In case you need custom CSS, create file called YourComponentName.module.scss to same directory
• Update component types accordingly in @gaiads/telia-react-component-library.d.ts file

Developing the component

When developing, make sure to:

• Have 100% unit test coverage
• Add PropTypes to your component with documentation and write a storybook story for the component
• Expose your component in src/index.js and add test to src/index.test.js
• Update component types accordingly in @gaiads/telia-react-component-library.d.ts file

Getting your component to the library

• Push your changes to your own fork
• Create descriptive pull request to the upstream repository
• Wait until code and design reviews are done and make changes if asked to

Developing your project with component library (npm linking)

For this, we have to utilize npm link command. You have two options: either use the static build of the project or develop against running component library. When using the running component library you can test changes in command library's end and see the changes in our application immediately. Remember that this is only for development and when you are deploying your own project then you should always use npm install to get the latest version of component library

Develop with running component library

• Go to directory of your local copy of component library
• Run sudo npm link ../<your_project_name>/node_modules/react
• Run npm run start
• Open another terminal and go to your project where you use @gaiads/telia-react-component-library as a dependency
• Run npm link @gaiads/telia-react-component-library
• Component library is now running in different terminal and you can run your application in another. When you make changes in the component library the changes will update automatically on your application
• In case you get an error, you could try to run npm install npm-link-shared and npm-link-shared ./node_modules/@gaiads/telia-react-component-library/node_modules . react from your project directory. npm-link-shared will enable your project to use react version from the telia-react-component.library package in order to avoid errors related to different React version.
• NOTE: Running npm i will break the linking.
• NOTE: If the changes are not shown, restarting the VS code should help.

Develop with static build

• Go to directory of component library
• Run npm link
• Run npm run build
• Go to the project where you use @gaiads/telia-react-component-library as a dependency
• Run npm link @gaiads/telia-react-component-library
• Now you can start making changes to the component library and after running npm run build it should be automatically updated in your project as well
• In case you get an error, you could try to run npm install npm-link-shared and npm-link-shared ./node_modules/@gaiads/telia-react-component-library/node_modules . react from your project directory. npm-link-shared will enable your project to use react version from the telia-react-component.library pacakge in order to avoid errors related to different React version.
• NOTE: Running npm i will break the linking.
• NOTE: If the changes are not shown, restarting the VS code should help.

Versioning

Component library uses Semantic versioning.

Artifactory

Setting up artifactory for component library development purpose

Run npm login and when the command line asks, enter your deveo credentials and suiting email. After this you'll be logged in to artifactory and you are able to make actions such publishing into the artifactory.

Setting up artifactory for your project

Include .npmrc file into the root of your project. File should include:

registry=https://artifactory.verso.sonera.fi:443/api/npm/npm-registry-virtual/
always-auth = true

Then login to the artifactory by running npm login. When the command line asks, enter your deveo credentials and suiting email. After this you'll be logged in to artifactory and you are able to install the dependencies.

Remember to include the credentials also to your CI!

How to create a Release

Prerequisites for release

• In order to create change log from github create github personal token. Create a file configToken.js in the root directory and copy/paste contents from configToken-template.js into configToken.js then add personal token in configToken.js
• Check that all the changes which should be included into the release are merged into the master branch
• Choose an increment based on Semantic versioning.

Release preparations:

• On Slack #gaia-core-team channel create a team editable document for release notes
  • Copy & paste previous' content for placefolder
  • Ping team members to modify and contribute to document
• Make sure all PRs related to today's release are merged into master
• Before starting release, checkout to the master branch and make sure, that you have taken the latest changes to your local master from origin/master
• Selecting between patch, minor and major releases:
  • PATCH version when you make backwards compatible bug fixes.
    • Run npm run release-prep to patch a version
  • MINOR version when you add functionality in a backwards compatible manner.
    • If you are releasing a minor version, run SEMVER=minor npm run release-prep
  • MAJOR version when you make incompatible API changes.
    • If you are releasing a major version, run SEMVER=major npm run release-prep
• Modify text to categorize changes in packages/telia-react-component-library/CHANGELOG_LATEST.md and prepend the text in packages/telia-react-component-library/CHANGELOG.md
• Run visual test npm run visual-test
  • Observe the breaking tests and update those if necessary.
• Commit changes to the @gaiads/telia-react-component-library repository with commit message Release preparations for <VERSION>, for example Release preparations for v0.0.11
• After commiting, push your local release branch to GitHub.
  • Run git push --set-upstream origin release/<VERSION>
  • For example git push --set-upstream origin release/v6.14.1
• In GitHub create pull request out of release/v<VERSION> branch.
• Assign someone to review and approve your pull request.
• ONLY AFTER pull request was approved merge it into origin master branch.
• MAKE SURE that after merging, you follow the releasing steps for GitHub.

Releasing in GitHub

WARNING

!!Before going further make sure that you pull request is approved by your collegue and merged into master!!

Once your release preparations are in the master go to the GitHub UI.

• Select Releases tab (usually on the right side of GitHub repository page under "About") and choose "Draft a new release"
• Tag number should be the version number which you just updated to the package.json
• Release title is the version number
• Copy/Paste contents of CHANGELOG_LATEST.md in Write section
• Since we are still in pre-release phase remember to tick "This is a pre-release" checkbox
• Hit the "Publish release". This will create a tag commit
• Go to the master branch and fetch that commit git fetch and rebase git rebase origin/master, with your local master branch
• Rename .npmrc-template file to .npmrc and Run npm publish in order to publish the package into the artifactory
• Go to artifactory, login and use quick search with @gaiads/telia-react-component-library keyword to check if the latest version was indeed published.
  • It should appear on the list quite soon. If not, you might have only read access to Artifactory. It will not throw any errors in terminal, if you have only read access.
• Make sure that designers and developers have modified and added their release notes to the document created at the very beginning of these release preparations.
• Notify everyone in the #design-system slack channel about the release with a brief release notes summary.
• Flush the cards in Jira by pressing Release button in full board kanban view specifying the release version

Adding new Icons

1. Add new icon svg file into shared/icons folder
2. Make sure your icon filename has no spaces nor umlauts
3. Run npm run process-icons in order to add icon into allowed icons list. Parser takes the name from the icon's file name
4. Rollup optimizes icons automatically by running them through svgr. It removes the fill tags and compresses file. So you don't have to do anything additional optimization, just run npm run build or npm run storybook
5. Create a new build and publish the new package, in order to get the icons available everywhere

Importing variables from the library

You can use colors, baseline, breakpoints, spacing and scalableTypography sass helpers.

Using Colors

Import colors from the library and refer them with color(color_name).

@import '@gaiads/telia-react-component-library/build/styles/colors.scss';

.myview {
    color: color(purple500);
    background-color: color(gray100);
}

Using breakpoints

Import breakpoint from the library and refer them with breakpoint name such "md".

@import '@gaiads/telia-react-component-library/build/styles/breakpoints.scss';

.myview {
    width: 100%;

    @include from('md') {
        width: 80%
    }
}

Using baseline

Import baseline from the library and refer it as $baseline or $typographyBaseline.

@import '@gaiads/telia-react-component-library/build/styles/baseline.scss';

.myview {
    height: 10 * $baseline;
    font-size: 3 * $typographyBaseline;
}

Using scalableTypography

Import fluidTypographyMixins from the library and define the font size scaling @include fluid-type(minSize, maxSize); .

@import '@gaiads/telia-react-component-library/build/styles/fluidTypographyMixins.scss';


.myview {
    @include fluid-type(10px, 20px);
}