SYN-library

⭐ Getting started

This project uses node 20

Run npm ci to set up the packages required.

Run npm run storybook to view the UI libraries Storybook documentation.

🌀 Publishing to Chromatic

The storybook is published on Chromatic

This should be done as part of the chore task that updates the published version so that the published storybook matches the current npm package.

You can redeploy locally or in CI with npm run chromatic.

ℹ The project token was added to the script via the --project-token flag. If you're running Chromatic via continuous integration, we recommend setting the CHROMATIC_PROJECT_TOKEN environment variable in your CI environment. You can then remove the --project-token from your package.json script.

We should perhaps do this!

🖼️ Icons

The library's icons predominantly come from Google's Material Symbols and Icons.

Adding a new icon

1. Ensure the icon has been added to the SYN Library's Figma Icon's.
2. On Figma, right click the icon you want to add. You should see a purple 20 x 20 bounding box appear around it.
3. Select Copy as > Copy as SVG.
4. Create a file in the src/icons folder with your new icon name. It should follow the existing file name convention, [Name]Icon.tsx.
5. A standard icon should receive at least one prop, size. This number will dictate the height and width of the icon.

Use the following template to structure your icon:

import React from "react"

import { IconProps } from "./IconProps"

export const MyIcon = ({ size = 20 }: IconProps) => {
  return (
    <svg fill="none" height={size} viewBox="0 0 20 20" width={size} xmlns="http://www.w3.org/2000/svg">
      {*/ <mask> */}
      {*/ <g> */}
    </svg>
  )
}

6. Your <svg> will likely have a <path> tag within it, with the fill attribute having a hardcoded hex value (likely to be #1E2428). Change this to fill="currentColor".
7. Next, import your icon into src/icons/Icons.stories.tsx and add it to the ICONS array. Viewing the Icons story on Storybook should show all icons, including your new one.
8. Scroll to the bottom of the icon's Storybook page and change the color value using the colour wheel. Your icon should change colour.
9. Finally, export your new icon from the icon folders barrel file, src/icons/index.ts

💻 Local Project Development

You can simultaneously develop this library alongside another local project.

1. Navigate to the root directory of this UI library and run npm link.
2. Go to the root directory of your local project and run npm link @synanetics/syn-library.
3. Remember to run npm run build in the library if you make any changes, to ensure your project is using the latest version. Updates should be reflected in your local project immediately.

You will need to re-link the packages if you install other dependencies at any point during local development.

You want to unlink the local instance of the package via:

npm unlink --no-save @synanetics/syn-library

If you have made changes to the UI library and errors occur similar to the following:

SyntaxError: The requested module ABC does not provide an export named 'xyz'

Restarting WSL and VS Code will likely resolve this issue.

🧪 Testing

React Testing Library, Jest & Axe

Each component has a corresponding [Name].test.tsx within it's folder.

React Testing Library is combined with jest-axe to run unit tests and prevent accessibility errors.

To manually run all tests, run npm run test:unit.

Playwright

Playwright is used for integration tests.

Running Playwright tests

Run npm run test:integration

🚀 Publishing

The SYN-library is published to the @synanetics npm repo.

1. Checkout the latest main branch

   git switch main
   git pull

2. Create a new branch for bumping the package version

   git switch -c chore/version_bump

3. Change the version in package.json
4. Run npm install to also update the package-lock.json
5. Commit the package.json and package-lock.json changes, push, raise a PR and merge into main
6. Switch back to the main branch and pull again
7. Run npm publish to publish the library

⚙️ Installing and Usage

1. Install via npm i @synanetics/syn-library
2. At your applications root scss file, import the core SCSS file via @use "@synanetics/syn-library/core";
3. Then, anywhere in your application, you can import the required components e.g. import { Button } from "@synanetics/syn-library";

You can access SCSS variables for Colours, Typography and Input's via:

@use "@synanetics/syn-library/colours";
@use "@synanetics/syn-library/inputs";
@use "@synanetics/syn-library/typography";