FI Design System

The intention behind this package is for it to be the source of truth for all DS needs when in comes to FI Engagement applications. It's maintained by all product teams' developers.

What it does:

• Exposes PurPur components
• Exposes modified PurPur components based on FI Engagement needs
• Exposes custom FI Engagement components

Target compatibility

React 17

Usage

1. Install the fi-ds package:

npm i @teliafi/fi-ds

2. 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

3. Add the scale multiplier for PurPur styles at your root stylesheet

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

Development

pnpm is used as a package manager, you can install it by running npm i -g pnpm.

Commands:

• Start: pnpm start
• Storybook: pnpm run start:storybook
• Update Purpur to latest version: pnpm run update-purpur

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

1. Create a component in lib/components (you can use App.tsx for preview)
2. Export the component in lib/index.ts
3. 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
4. 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)
5. Create a Pull Request
6. Merge
7. 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

1. Bump the version in package.json

• pnpm version patch (0.0.x) small, non-breaking fix/adjustment
• pnpm version minor (0.x.0) non-breaking feature/fix/adjustment
• pnpm version major (x.0.0) breaking change

2. Merge the version bump
3. 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 user for npm package deployments (currently configured with a personal token of [email protected])