@postscript/components

Postscript Component Library

Storybook

The main branch is used to create a Storybook instance at components.postscript.io, via Chromatic.

NPM package usage

This repo generates an NPM package of components. Use components by importing them individually.

npm i @postscript/components

Note: If you are not seeing the latest version of this package, you may need to run @npm i @postscript/components@latest.

import { Button } from '@postscript/components';

const App = () => <Button>A Happy Button</Button>;

Local repo usage

CSS variables, reset, and design tokens

Import our base CSS once in your project.

import '@postscript/components/dist/esm/main.css';

Import React Toastify CSS if needed.

import 'react-toastify/dist/ReactToastify.css';

Contributing

• Jira project
• Slack #front-end

Testing changes in other repos

Currently, the easiest way to test changes from a feature branch in another repo is to publish a one-off, unique version of the package under a tag specific to you. View instructions

Versioning

Commits to main will publish a new @postscript/components package version. Use one of the following conventions when commiting/titling PRs to control semantic versioning.

• Major: your commit introduces any breaking change
  • add a BREAKING CHANGE: prefix to the commit message (bumps the major version X.#.#)
  • e.g. changes to existing props, component refactors, module naming
• Minor: your commit adds new functionality in a backward compatible way
  • add a feature: or feat: prefix to your commit message (bumps the minor version #.Y.#)
  • e.g. add net new feature
• Patch: your commit changes something that already existed in a backward-compatible way
  • do not include either of the above in your commit message or description (bumps the patch version #.#.Z)
  • e.g. add/update minor styles, fix a bug, update a piece of documentation

Follow your commits to postscript-frontend, and address any changes needed to bump version.

Pull requests

PRs require one engineer approval. If working with a designer, tag them as well. Directly requesting review from those with good knowledge of your changes is helpful if they're available.

Additionally, post for review in #pull-requests and #front-end.

How to add a new Icon

We utilize SVGR CLI to turn SVGs into React components. See .svgrrc.js for our config.

• Add SVG(s) to src/icons/
• Run npm run svgr
• Upon success, a summary will be logged
• Add import * as React from 'react'; to the new module(s)
• Delete the original SVG file
• Export the JSX component in src/icons/index.ts; IconSet uses this barrel
• Run Storybook, and you should see the new component(s) in the Icon story examples automatically if everything has worked correctly

We utilize the following automatic transformations.

Creating components

Create your component with Typescript, its corresponding Storybook file, and a unit test file.

!! Be sure to add your new component to the exports list in src/index.ts and organize its display order in .storybook/preview.js

Figma Code Connect Setup

Code Connect is the developer bridge from your component codebase to Figma. With Code Connect, bring your design system component code directly into Figma's Dev Mode. Preview example components that mirror the framework of your production code.

Code Connect uses [componentName].figma.tsx files to link code component properties with Figma component properties. Once the files are created and published, direct code output for the specified components will be visible in Figma's Dev Mode. Learn More

Once created, the files only need to be modified when component updates are made.

To enable Figma Code Connect integration:

You must have:

• A Figma Dev mode seat
• A Figma access token

• Install the Figma Code Connect CLI:

npm install --global @figma/code-connect@latest

• In Figma, generate a personal access token in your account settings under the Security tab (more info).

• Create a new .env file:

touch .env

(Note: This file is listed in .gitignore and will not be listed as part of your commit.)

Then add the following to your .env file, along with your access token:

FIGMA_ACCESS_TOKEN="[your token here]"

• Making update to a component:

  • Modify the appropriate .figma.tsx file next to your component
  • Run npx figma connect publish to publish the changes to Figma
  • Commit your changes and and publish as a PR to the components repo

• Working with new components:

  • Create a .figma.tsx file alongside your component (e.g., Button.figma.tsx next to Button.tsx)
  • Import and use figma.connect() to link the component to your Figma design
  • Run npx figma connect publish to publish the changes to Figma

Example .figma.tsx file:

import figma from '@figma/code-connect';
import React from 'react';
import MyComponent from './MyComponent';

const noop = () => {
  /* no-op */
};

figma.connect(MyComponent, 'https://www.figma.com/file/...', {
  props: {
    // Define component props that can be controlled in Figma
    size: figma.enum('Size', {
      Small: 'small',
      Medium: 'medium',
      Large: 'large',
    }),
    // Use noop for event handlers
    onClick: figma.boolean('Has Click', {
      true: noop,
      false: undefined,
    })
  }
});

For more details, see the Figma Code Connect documentation.