Veeqo Components

Introduction

The frontend component library for reusable components in Veeqo which aim to reflect the Veeqo Design System. When possible we should aim to re-use components in this library all over the frontend and reduce the amount of custom components we create.

Performance: This library has been re-written and refactored with the aims of enable tree-shaking which will allow us to reduce our bundle size and decrease page load times while also simplifying the library making it easier to work with and develop.

In the longer term Icons and Integrations WILL be moved to their own library, but currently live in veeqo-frontend. For now please use individual icons to preserve tree shaking, while downstream uses can use the old component library Glyph component if needed (not tree shakable, huge size).

Links ⚓️

This Library: Storybook 📋 | Playroom 🛝 (not deployed)

Old Library: Storybook 📋 | Playroom 🛝

Getting Started

Setup should be simple, clone the repo and use npm i to install all dependencies.

• Start storybook with npm run storybook, which starts on localhost:3000
• Start Playroom with npm run playroom:start, which starts on localhost:9000

Testing

With this new library we aim to improve the quality of the code, and would like good test coverage of our components covering its main behaviour. Note:

• We use React testing library.
• Run tests with npm run test
• Watch (listen to changes/ file saves) tests with npm run test:watch optionally with a filepath.

Prettier Setup

Everything should mostly be setup already, if prettier isn't automatically formatting please check your .vscode/settings.json and adjust if needed (don't push to git).

You will need to install ESlint and Prettier VSCode Extensions, if you haven't already.

Publishing to NPM

We currently deploy to NPM, which is an automated process once you merge.

Publishing

Versioning will happen on the package.json version number, and is for the library as a whole instead of per component for simplicity.

Production releases happen automatically when you merge to main. The package is published to NPM with the latest tag.

Beta releases are triggered manually via GitHub Actions and publish with the beta tag (see below).

After you have made your changes, use npm run patch or npm run minor or npm run major according to the update size:

• This create update the version number by the amount specified in the command you entered above.
• Create a git tag for that version, making the version history straightward to look back on.
• Update the changelog based on your commits.
• Push this readme change upstream

If you run the script more than once we will have duplicate tags, which will ruin the changelog (easy to spot) and stop us using those versions in the future. Please use npm tags:remove v<yourversion> to remove the tag.

After this is done, merge your PR and GitHub actions will do the rest! If your version hasn't deployed within a few mins (check here), please reach out on slack.

Local Linking

Can't figure out getting NPM Link to work, which would be ideal... this is one alternative.

From this repo run npm run build:tarball this will create a tarball file, similar to what is brought down from NPM and allow you to install that on other projects (like Veeqo) by updating the dependency in the package.json like:

    "@veeqo/ui": "file:../veeqo-ui/veeqo-ui.tgz"

Deploying a beta version

1. Update version number to <next-version>-beta-<attempt_num>, i.e. 9.0.0-beta-2
2. Push your branch with the latest changes to Github, including the version number update
3. Navigate to https://github.com/veeqo/veeqo-ui/actions/workflows/publish.yml
4. Click "Run workflow" and select the branch with your beta version

The workflow will validate the version format and publish with the beta tag to NPM.

Alternatively you can deploy to npm with a beta version, as long as you are part of our NPM org:

• Update version number to <next-version>-beta-<attempt_num>, i.e. 9.0.0-beta-2
• Run npm publish --tag beta to publish this with a beta tag (important)

Icons

Overview

The UI library now integrates directly with our Figma Design System for icons. Design system icons are exported from Figma as optimized SVGs and then converted to React components, ensuring consistency between design and implementation.

Usage

Import icons directly from the design system components:

import { InfoIcon, WarningIcon } from '@veeqo/ui';

Structure

src/icons/
├── design-system/      # Figma-generated icons
│   ├── components/     # React components
│   └── imports/        # Raw SVGs
├── custom/             # Custom icons (temporary)
├── Docs.mdx            # Markdown documentation
├── icons.stories.ts    # Icon stories
├── index.ts            # Main export path
├── types.ts            # Shared type definitions

Adding/Updating Icons

1. Icons should be added/updated in the Figma Design System first
2. Run the following commands to update the icon library:

npm run figma:export  # Export SVGs from Figma
npm run build:icons   # Convert SVGs to React components

These scripts:

• Connect to Figma and export optimized SVGs
• Generate TypeScript React components from those SVGs
• Standardize icon colors (converting base ink color to currentColor)
• Apply consistent formatting and linting

For detailed information about the icon build process, see our Icon System Documentation.

Custom Icons

While we transition to using Figma as our source of truth, some custom icons still exist in the custom/ directory. These will gradually be replaced with design system versions.

Icon Development

To work with icons locally:

1. Copy .env.sample to .env and add your Figma access token
2. Run the export and build commands mentioned above
3. Icons will be available in the design system components directory

For more detailed information about the icon system, see our Icon System Figma Integration Documentation.

Adding additional SVG icon sets

The build script supports multiple icon sets through the ICON_SETS configuration object. To add a new icon set:

Create a new directory structure for your icons

src/icons/
└── your-icon-set/
    ├── components/     # Generated React components
    └── imports/        # Raw SVGs

Add your configuration to ICON_SETS in the build script

const ICON_SETS = {
  // Existing configurations...
  yourIconSet: {
    import: './src/icons/your-icon-set/imports', // Directory containing source SVG files
    output: './src/icons/your-icon-set/components', // Directory where React components will be generated
    svgrConfig: {
      plugins: ['@svgr/plugin-jsx', '@svgr/plugin-prettier'],
      typescript: true,
      exportType: 'named',
      ref: false,
      prettierConfig: './.prettierrc',
      // Additional SVGR configurations as needed:
      replaceAttrValues: {
        '#000000': 'currentColor', // Replace specific colors
      }, // SVGR transformation options, for full list of options see: https://react-svgr.com/docs/options/
      icon: 24, // Set default icon size
    },
  },
};

This will add it to the build script npm run build

The build script will automatically:

• Clean the output directory
• Generate React components from SVGs
• Create index files for exports
• Apply consistent formatting and linting

Figma Export Scripts

The UI library includes automated scripts to export assets from Figma files. For detailed information on configuring and extending these scripts, see scripts/figma-export/README.md.

Quick Start

# Export design system icons
npm run figma:export

# Export integration marks
npm run figma:export-integrations