Lens — the design system for Loom products

Content Overview

• Installation - Add Lens to your project with required dependencies
• Running Lens Locally - Test your Lens changes in development
• Contributing - Guidelines and workflows for contributing to Lens
• Adding a New Icon - Step-by-step process for adding custom icons
• Upgrading Lens Versions - How to publish and update Lens versions
• Using ADS Icons - Integrate Atlassian Design System icons
• Documentation - Access the full Lens documentation site

Installation

Add Lens to your app:

yarn add @loomhq/lens

Add dependencies:

yarn add @emotion/core
yarn add @emotion/styled

Install CSS variables

getThemeStylesString() and getAllCssVarsString() return strings that contain all CSS variables. Use these functions and inject the output to a style tag in the head:

import { getThemeStylesString, getAllCssVarsString } from '@loomhq/lens'

const style = document.createElement('style');
style.innerHTML = getThemeStylesString() + getAllCssVarsString();
document.head.appendChild(style);

In some cases you might need to inject the CSS variables to a specific element. Pass a string argument to getThemeStylesString() and getAllCssVarsString():

getThemeStylesString('.myGlobalElement')
getAllCssVarsString('.myGlobalElement')

Install CSS utilities

CSS classes are exported as a string and can be injected to a style tag in the head:

import { cssUtilities } from '@loomhq/lens'

const style = document.createElement('style');
style.innerHTML = cssUtilities();
document.head.appendChild(style);

Running Lens Locally

Want to test if your Lens changes went through? Just like how there's a Loom local, there's a Lens local.

From the Lens directory - found at libraries/lens

pnpm i
pnpm --filter @loomhq/lens dev

After running the last pnpm --filter in your terminal, a localhost address should appear. Follow it to your local lens development website.

Contributing

If you are looking to use an ADS (Atlassian Design System) component, check out this section for implementation guidance.

If you add any new Lens components, please surface any urgent pull requests in #lens-designsystem.

Adding a New Icon to Lens

1. Within the loom repository, navigate to projects/libraries/lens/src/components/icon/available-icons
2. Create a new file in the available-icons folder, and give it a literal name (e.g., bug icon → bug.tsx)

   • If the icon you are trying to add already exists in ADS, use the same name as what can be found in the ADS icon explorer

3. After creating your new icon, go to index.ts (found at /lens/src/components/icon/available-icons/index.ts) and add an export statement for your new icon in there.
4. When you're finished adding your icon into lens library, and run pnpm build → this command will automatically register your new icon to Lens and must be ran before you can view or test your new icon locally
5. Follow these steps to run Lens locally.
6. Once you have finalized your changes and your code is ready for PR, you need to run pnpm changeset from the root directory
7. After running changeset, you should be prompted with "what changeset do you need" within your terminal
8. Select the files that you have changed, and press enter to proceed until you see a patch bump prompt. Make sure to select a severity that accurately reflects the scope of your changes.
   • For example, a change that merely adds a new component or icon would be considered minor, but a change that adds a new component and removes support for another component/the previous version of that variant would be considered a major change.

Note: If there's no changeset file included in your PR, your changes won't be available to use in the rest of the repo until a changeset is merged. Think of it like merging without deploying.

Use conventional commits

Use conventional commits messages. Once the PR is merged it will kick off publishing a new version of Lens in npm.

🚨🚨 Be aware that only feat and fix can trigger a release. 🚨🚨

Upgrading Lens versions

Loom

From the root of the main Loom repo

1. Make your updates in /projects/libraries/lens

2. You should be able to see the updates reflected in your local web app.

3. Run pnpm changeset when you are done with your changes

4. In a separate PR, run pnpm changeset:version to publish a new version of Lens. You can expect a lot of files to be updated when this is run. Once the PR is merged you should see a new version on JFrog.

Add an icon to the icon set

As part of visual refresh, we are now using ADS icons. If your icon is already in ADS, please refer to this icon as an example. Newer icons are sometimes in a different package called icon-lab and you may need to bump the version to have it available to you. If your icon is not yet in either @atlaskit/icon or @atlaskit/icon-lab please work with your designer to get it added. If the addition of the icon is urgent, you can include the SVG code like in SvgScissors.

Add your new SVG to misc/eslint/common.js and projects/libraries/lens/src/components/icon/available-icons/index.ts.

To see if your icon is in a certain version, refer to @atlaskit/icon changelog or the @atlaskit/icon-lab changelog.

Documentation

https://lens.loom.dev