@toptal/picasso

Picasso is Toptal's component library, based on Toptal's design system - BASE. UI designs and documentation can be found for most components at picasso.toptal.net.

Installation instructions

yarn add @toptal/picasso @toptal/picasso-provider @toptal/picasso-tailwind tailwindcss @tailwindcss/postcss postcss autoprefixer

Create tailwind.config.js in the root of the project

Please note that Picasso Tailwind preset has to be used along with @toptal/base-tailwind preset.

const path = require('path')

const projectRoot = __dirname

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    path.join(projectRoot, 'node_modules/@toptal/picasso/**/*.js'),
    path.join(projectRoot, 'node_modules/@toptal/picasso-*/**/*.js'),
    // if your project is also using topkit
    path.join(projectRoot, 'node_modules/@topkit/**/*.js'),
    // adjust for your project infrastructure
    path.join(projectRoot, '{hosts,libs,namespaces}/**/src/**/*.{ts,tsx}'),
  ],
  presets: [
    require('@toptal/base-tailwind'),
    require('@toptal/picasso-tailwind'),
  ],
  corePlugins: {
    preflight: false,
  },
}

Add Tailwind CSS directives to your CSS source files

/* index.css */
@layer theme, base, components;
@import 'tailwindcss/theme.css' layer(theme);
@import '@toptal/picasso-tailwind/base';
@import 'tailwindcss/utilities.css';
@config "./tailwind.config.js";

Global reset (@toptal/picasso-tailwind/base)

The @toptal/picasso-tailwind/base import ships Picasso's global reset (page box model, body/root layout, font smoothing) inside @layer base. Because it is cascade-layered, all Tailwind utilities and any unlayered application CSS win over it — the reset is a baseline, never an override.

The reset establishes a content-box page box model (html { box-sizing: initial } with universal inheritance); Picasso components stay border-box via the PicassoRootNode island.

To opt out of the reset, omit the import (this replaces the former <Picasso reset={false} /> prop, which no longer exists).

Setup webpack to use PostCSS loader with tailwindcss plugin

If you are reusing webpack configuration from @toptal/davinci-engine you can skip this step as it is setup automatically if tailwind.config.js is in the repository.

Make sure to check all webpack configuration, Application (start/build), Storybook, Cypress

// webpack.config.js

...
{
  test: /\.css$/i,
  use: [
    'style-loader',
    'css-loader',
    {
      loader: 'postcss-loader',
      options: {
        postcssOptions: {
          config: false,
          plugins: {
            '@tailwindcss/postcss': {},
          },
        },
      },
    },
  ],
},

...

When using Vite or NextJS, adding tailwind config with correct content should be sufficient in most cases, depending on your configuration.

For more info, you can check out the official Tailwind docs:

Install Tailwind CSS with Vite

Install Tailwind CSS with Next.js

Start using the library

import Picasso from '@toptal/picasso-provider'
import { Button } from '@toptal/picasso'
...

render () {
  return (
    <Picasso>
      <Button>Hello world!</Button>
    </Picasso>
  )
}

A Picasso component rendered at root level is required for the library's global services — fonts, favicon, notifications, and the responsive breakpoint context — to work properly.

Merging classes

When working with TailwindCSS merging classes is vital. Read our Merging classes tutorial to make it right.

Documentation

Documentation and demos are available at picasso.toptal.net.

Decisions

Our decisons are documented at GitHub