@teliafi/fi-ds NPM

FI Design System

Target compatibility

React 17

Usage

Install the fi-ds package:

npm i @teliafi/fi-ds

Add the imports for PurPur tokens and TeliaSans font in your root stylesheet

@import url('https://cdn.voca.teliacompany.com/fonts/TeliaSansV10/TeliaSans.css');
@import '~@purpurds/tokens/index.css'; // installed as a subdependency of @teliafi/fi-ds

Alternatively you can import PurPur tokens in your app's entrypoint

Add the scale multiplier for PurPur styles at your root stylesheet

:root {
  --purpur-rescale: 1;
}

Development

Commands:

Start: npm start
Storybook: npm run start:storybook

Architecture

Components: lib/components
Tokens: lib/tokens
Storybook: src/stories
Development environment: src/App.tsx

Code

Styling: Use @import "@common-styles"; at the top of the stylesheet to import variables, and mixins.
Styling: For custom component use @include reset; at the component's topmost element's style rule to include default styles.

Assets

Assets that should be moved into distribution build without transpilation (like .scss variables file) live inside public

Workflow

Create a component in lib/components (you can use App.tsx for preview)
Export the component in lib/index.ts
Bump the version number in package.json
- patch (0.0.x) small, non-breaking fix/adjustment
- minor (0.x.0) non-breaking feature/fix/adjustment
- major (x.0.0) breaking change
Create a story in src/stories/(FI-DS|PurPur) (put the story under FI-DS or PurPur based on if it's a custom component or a PurPur proxy)
Create a Pull Request
Merge
Run Publish Workflow to release a new package and Storybook version

Please refer to the troubleshooting section below for common issues and gotchas.

Branch naming convention

feature/my-custom-name - new feature/component
maintenance/my-custom-name - maintenance work like workflow, readme, configuration updates
refactor/my-custom-name - refactoring work, like rewriting component implementation, syntax updates
fix/my-custom-name - bug and other types of fixes

Pull Request should contain only a single type of work, do not mix different types of work into a single Pull Request, like introducing a new component and refactoring/fixing a bug in an existing one. Please create separate PRs for these type of cases.

Commits

Naming convention

Commit naming is based on basic Conventional Commits usage. Keep it simple, e.g.: docs: update readme workflow section, fix: add Badge default color, feat: ColorDot component, style: update Heading background color, refactor: Button syntax cleanup, test: introduce Icon tests, chore: bump package version, etc.

Merge style

Squash your commits when merging.

General guiding rules

The library is intended to have a low learning and be easy to contribute to, please follow these rules when contributing:

Make it simple, stick with the KISS (Keep it simple, stupid!) design principle
Avoid building abstractions - aim for component module to be self-contained, without needing to read a bunch of common utils in order to understand how it works
Avoid premature optimization - aim for code readability, optimize performance only when issues arise
Prioritize existing PurPur components instead of creating custom ones
If introducing a breaking change, inform #fi-ds-community slack channel
Avoid ambiguous Pull Request comments, every code comment should be met with a practical suggestion
Use nitpicking to a reasonable extent - convention is important but do not hold off PRs for too long only for minor nitpick reasons

Publishing

Bump the version in package.json
Merge the version bump
Run the Github Action Publish

Hosted Storybook can be found here

Troubleshooting

PurPur integrated component is missing styles

PurPur component's style export contains only the styles for the particular component, but often times, the imported component makes use of other PurPur components, so make sure that the styles those components are imported as well into the stylesheet.

See the example of the Checkbox

You can gather the necessary styles based on component's dependencies by looking at PurPur's source code, just check the imports of the component you're integrating.

Cannot find module 'react/jsx-runtime'

This is caused due to compatibility issues between React 18 which is used by PurPur and older versions of React. In order to resolve this, you'll have to update your webpack.config.js or install CRA configuration override tool like craco and describe how to resolve this package.

resolve: {
  fallback: {
    'react/jsx-runtime': 'react/jsx-runtime.js'
  }
}

Uncaught ReferenceError: React is not defined

Likely, you'll get this error together with the previous one. If you are using Babel and React 17, you might need to add "runtime": "automatic" to Babel config.

In .babelrc config file add:

{
     "presets": [
         "@babel/preset-env",
        ["@babel/preset-react", {"runtime": "automatic"}]
     ]
 }

Otherwise you can define React globally in your entrypoint:

import React from 'react';
window.React = React

To do

Find a system jFrog user for package deployments (currently configured with a personal token of mindaugas.lazauskas@teliacompany.com)