@cognite/cogs.js NPM

Cogs.js

Cogs.js is the UI Building Blocks for Cognite Applications.

Mission Statement

Cogs.js aims to solve, or assist to solve, the following problems:

Lack of design consistency across applications within Cognite.
Improving developer experience when creating designs from Figma
Lack of single source for common, reusable tokens and atoms (Icons, Colors, type, etc)

Cogs.js also aims to replace antd.

Cogs.js exports several base tokens, such as Colors, Typography and Icons. It also exports several atom components, such as buttons. Finally, it exports some smaller molecules, such as a loading screen.

Installation!

Start off by installing the package through yarn.

$ yarn add @cognite/cogs.js

$ npm install @cognite/cogs.js

Use

You can see what's available within the storybook.

Contribution

Cogs.js should be a community driven effort. See the Design System board for more of what needs doing!

Releases and Commit messages

Releases are automated by semantic-release. Each commit can trigger a release. We use the conventionalcommit pattern to decide whether a commit is a PATCH, MINOR or MAJOR release.

Commit message prefix fix: indicates PATCH release,
Commit message prefix feat: indicates MINOR release,
Commit message prefix {ANY_PREFIX}!: so for example feat!: or even refactor!: indicate MAJOR release.

Making a new component checklist

Use the Button component as an example, for a starting place

Place a new folder into either Atoms, Components or Tokens
In that folder, have an index.ts that exports everything, Button.tsx and Button.stories.tsx.
Add Button.spec.tsx next to Button.tsx.
All styles related to that component go into the matching directory in the styles directory

Guidelines:

In all cases, you should build your component in the most agnostic way possible - using pure CSS. Then build your React component to use these styles. Sometimes this isn't feasible, and thats okay.
Remember to export your component in src/index.ts, or you won't see it in NPM!

Your stories should look like this:

HTML only version (when at all possible, provide a HTML only version for non-React users.)
React component (required, showing the basic use)
Example stories (whatever you think is good)
Playground (if it seems useful)

Adding util functions

If you have common, reused functions, you can also place them here! Provide the function, any tests, and a README describing the function in a single folder under Utils.

Jest matchers

@cognite/cogs.js exposes custom jest matchers to aid in writing unit tests. To integrate this in your tests, do the following:

Import the expect extensions somewhere in the setup process. This is commonly done in src/setupTests.ts. However, please consult your jest.config.js to see which files are provided to setupFilesAfterEnv.

import '@cognite/cogs.js/extend-expect';

Then in your tests, the new extensions can be used natively. For example:

import React from 'react';
import { render, screen } from '@testing-library/react';

import DeleteButton from './DeleteButton'; // your custom component

describe('DeleteButton', () => {
  it('is disabled by default', () => {
    render(<DeleteButton />);
    const button = screen.getByRole('button', { name: 'Delete item' });
    expect(button).toBeInTheDocument();
    expect(button).toBeDisabled();
    expect(button).toContainCogsIcon('Delete');
  });
});

Figma Icons

We make use of Figma's API to get icons. To update icons in cogs.js, we currently manually run a script to fetch them from figma, and then make a PR containing any additions or changes generated by the output of the script.

Before running the script, it is required to have an access token, which can be fetched according to these instructions, and then stored under the local environment variable (ie. in .bash_profile) named FIGMA_TOKEN.

Now you may run:

$ yarn figma:icons

This will take all the icon symbols from the 'CogniteIcons' figma file as SVGs and place them into an output folder. After that, it will parse all the SVG icons, replacing colors and turning them into components It will then prettify all files. You can delete the output folder after running the script :)