![](https://github.com/loomhq/lens/blob/main/assets/lens-banner.png?raw=true)

# Lens — the design system for [Loom](https://www.loom.com) products

[![npm](https://img.shields.io/npm/v/@loomhq/lens?style=for-the-badge)](https://www.npmjs.com/package/@loomhq/lens)

## Content Overview

- [Installation](#installation) - Add Lens to your project with required dependencies
- [Running Lens Locally](#running-lens-locally) - Test your Lens changes in development
- [Contributing](#contributing) - Guidelines and workflows for contributing to Lens
- [Adding a New Icon](#adding-a-new-icon-to-lens) - Step-by-step process for adding custom icons
- [Upgrading Lens Versions](#upgrading-lens-versions) - How to publish and update Lens versions
- [Using ADS Icons](#add-an-icon-to-the-icon-set) - Integrate Atlassian Design System icons
- [Documentation](#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](#add-an-icon-to-the-icon-set).

If you add any new Lens components, please surface any urgent pull requests in [#loom-design-system-lens](https://atlassian.enterprise.slack.com/archives/CJ52CKB27).

### 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](https://atlassian.design/components/icon/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.](#running-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.

### Adding a New Illustration to Lens
Follow [this guide](https://hello.atlassian.net/wiki/spaces/~712020ed7894b2bdcb46ecacd40aff80a4be0e/pages/6562186947/Adding+a+new+ADS+Illustration+to+Lens) to add a new illustration to Lens. After running the prompt in the guide, verify the following:

1. **File location and export** — Your illustration lives in `projects/libraries/lens/src/illustrations/` and is exported from the `index.tsx` file in that folder.

2. **Theme support** — Your illustration works in both light and dark mode. This includes when dark mode is applied via `data-lens-theme="dark"` on a parent element rather than on the body. Use the code playground on the Illustration Component page to test this.

3. **Color definitions** — Illustration colors are defined in `projects/libraries/lens/src/colors.ts`. The theme-specific colors should have been added to the appropriate dark and light mode entries, and only static colors added to `illustrationColors`.

*Note: For illustrations that aren't from ADS, reach out in [#loom-design-system-lens](https://atlassian.enterprise.slack.com/archives/CJ52CKB27) first.*

### Use conventional commits

Use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) 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](http://github.com/loomhq/loom)

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](https://packages.atlassian.com/ui/packages/npm:%2F%2F@loomhq%2Flens).

### Add an icon to the icon set

As part of visual refresh, we are now using [ADS icons](https://atlassian.design/components/icon/icon-explorer). If your icon is already in ADS, please refer to [this icon as an example](src/components/icon/available-icons/account.tsx). 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](src/components/icon/available-icons/scissors.tsx).

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](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/src/master/platform/packages/design-system/icon/CHANGELOG.md) or the [@atlaskit/icon-lab changelog](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/src/master/platform/packages/design-system/icon-lab/CHANGELOG.md).

## Documentation

https://lens.loom.dev