@canvas-inc/palette

Palette is Untapped's design system component library. This repository serves as a single source of truth for the atomic UI components that have been implemented for consistent use throughout the product. Each component is also documented with Storybook which allows us to programatically generate an interactive documentation site.

Getting Started

Palette uses Font Awesome Pro, which requires a private token to authenticate and install the package. In order to avoid committing this token to any of our repositories, we recommend storing it as a local environment variable using the following command:

echo 'export NPM_CONFIG_FONTAWESOME_TOKEN={TOKEN_GOES_HERE}' >> ~/.zshrc

Replace {TOKEN_GOES_HERE} with the private token, which can be found in the shared 1Password vault. You will need to restart any open terminal sessions for this change to take effect, or you can run source ~/.zshrc to update your current session. This command only ever needs to be run once. The token will be available for any other repos you clone which also use Font Awesome

If you see the following error: error An unexpected error occurred: "Failed to replace env in config:... then the token has not been set properly for your terminal session. Double check that the env var has been added to your .zshrc and that you restarted terminal or sourced the file before rerunning your yarn command

Run yarn start locally to start the Storybook dev server. This makes it easy to develop locally with hot-reloading to see the components and stories as you build and write them.

Developing with jumpstart-frontend Repo

While developing a new component, it's also possible to use the component while developing with the jumpstart-frontend repo. To do this, whenever you're ready to test the component, make sure the component is properly exported in the ./src/components/index.js file like so:

export { default as Button } from '@/components/Button/Button.vue';
export { default as Pagination } from '@/components/Pagination/Pagination.vue';
export { default as MyComponent } from '@/components/MyComponent/MyComponent.vue';

Once the compnent is properly exported, run yarn build in order to build the dist files.

In the jumpstart-frontend repo, run yarn add 'path/to/@canvas/palette'. For example, if a folder structure looked like this:

my-code
  |- @canvas
  |   |- palette
  |- jumpstart-frontend

the command to run in the terminal for jumpstart-frontend would be

yarn add '../@canvas/palette'

And voila! Import the component into the files as you normally would to test.

Make sure that after making any updates to the new component in @canvas/palette, re-run yarn build in the @canvas/palette repo, and then run yarn upgrade 'path/to/@canvas/palette' to upgrade.

Storybook Deployment

The main branch of this repository is setup to automatically deploy a statically generated version of Storybook to the qa and dev environment. Tagging a new github release will deploy to production.

Environment URLs

NOTE: You must be on the VPN in order to access the following sites

Production: https://palette.untapped.io

QA: https://palette-qa.untapped.io

Dev: https://palette-dev.untapped.io

Writing and Running Tests

We'll eventually get code coverage set up for this repo, and the goal would to maintain 100% code coverage for all components.

Include tests in the same directory as components and its stories. You can run yarn test or yarn test:watch while developing and writing tests.

Run yarn test:generate-output before submitting a PR and publishing to NPM registry.

Publishing to NPM

Run yarn build and then yarn publish to publish the package to the npm registry. It will ask for your npm credentials. Currently, Zama and Bao have access to our organization on npm.

The build step currently is configured to build a bundle into the dist folder.

Updating Version Numbers

When upgrading version numbers, increment x in 1.x.0 when a new component is added. If a component is updated, increment x in 1.2.x to indicate a minor component update.

Usage

In another project, such as jumpstart-me/jumpstart-frontend, add the published npm package. You will then be able to import the package in any files in that project.

Adding package (if it hasn't been added already)

yarn add @canvas-inc/palette

To import and use the components, in the <script> tag, import like so:

import { Button } from '@canvas-inc/palette

and use in your <template> tag as you would any other Vue component. Don't forget to add Button to your components key:

<template>
  <Button
    title="button title for accessibility"
    buttonText="Sample button text"
    variant="primary"
    :onClick="handleButtonClick"
  />
</template>

Troubleshooting

The engine "node" is incompatible with this module.

error [email protected]: The engine "node" is incompatible with this module. Expected version "^10 || ^12 || >=14". Got "13.14.0"
error Found incompatible module.

This error occurs when there's a node version mismatch between this module and your system. To bypass this error, append --ignore-engines to your commands and they should work, i.e., yarn --ignore-engines. The other option is to use nvm to use a different node version while developing in Palette.

In Progress

See TODO in Button.vue

In order to get a working version of Palette, with the ability to import files using import { Button } from '@canvas-inc/palette', we need to import global scss at the top of the <style> in every single Vue component. This is not ideal.

Using [email protected] seems to better support Vue 2, which is what this component libray is built on, however, it requires that additional import in each Vue component in order to use the scss variables declared in the src/assets/styles/** directory.

Version ^6.0.0 seems to only support Vue 3, although I'm not 100% sure of this. [email protected] seems to not require the individual scss imports like 5.0.0 as long as the correct rollup plugins are in place, such as rollup-plugin-scss and rollup-plugin-postcss, and maybe rollup-plugin-sass. Building and importing the component from the library seems to work just fine until the component is actually rendered, where the error Typeerror: Object(...) is not a function pops up and prevents the rendering of the component.

The ideal scenario for using rollup would be:

1. Not require importing global styles into each Vue component
2. Not throw Typeerror: Object(...) is not a function when using components
3. To have css styles injected into the Javascript files