Implementation of Aiven Aquarium design system, released as an npm package. Quick tour:
- We use Figma to design the system. The design tokens are controlled in a Figma page (see example page), which are synced automatically to tokens.json
- Component implementation uses design tokens to define their visual look. This will make updating the visuals easier in the future by changing the tokens.
- Aquarium design system implementation is exposed as React components via npm
- Tailwind is used for styling
-
npm install --save @aivenio/aquarium
-
Make sure to add the correct fonts in your app. Inter for Aiven theme.
-
Import the CSS to your app
- Aiven theme with
import '@aivenio/aquarium/dist/styles.css'
- If you used
THEME=X npm run build
for building, useimport '@aivenio/aquarium/dist/styles_X.css'
- Aiven theme with
-
Add React context component to the root of your React app
import MyApp from './MyApp'; + import { Context } from '@aivenio/aquarium'; const Root = () => ( return ( + <Context> <MyApp /> + </Context> ) )
-
If you encounter problems resolving EcmaScript modules disable "fullySpecified" mode using this Webpack config:
webpack: { configure: { module: { rules: [ { test: /\.m?js/, resolve: { fullySpecified: false, }, }, ] }, } }, };
Use npm 7! With older npm versions, install peerDependencies manually. If you encounter "Cannot find module..." errors, try rm -rf node_modules && npm i
. This seems to be a bug introduced in npm@7.
This project requires certain environment variables to be set before commands such as npm run build
will work. Most can be copy/pasted with the help of your teammates, but you will need to generate a NPM token yourself in order.
-
Create an npm account here if you don't already have one.
-
Generate a token for your account. You can read about how to do so here. For the purposes of building the project, read-only access will suffice.
-
Copy the sample environment file:
cp .env.sample .env
-
Add the necessary data into the newly-created
.env
file. -
Source the
.env
file for the environment variables to be set:source .env
Note that any time a new shell instance is created (for example, when you restart your computer), you need to run
source .env
again, or the variables won't be set. Consider using a solution such asautoenv
to automatically apply the.env
file. -
npm ci
to install dependencies -
npm run build
to build the project -
npm start
to start Storybook
After Figma has been edited, run:
-
npm run figma -- sync
to fetch new tokens to./tokens.json
-
npm run build
to re-create automatically generated files
- For VSCode
- Install Tailwind CSS IntelliSense extension. See https://github.com/tailwindlabs/tailwindcss-intellisense#recommended-vs-code-settings
- Install ESLint extension and optionally enable auto-format on save. See "Step 4 — Formatting on Save" from https://www.digitalocean.com/community/tutorials/linting-and-formatting-with-eslint-in-vs-code
To develop Aquarium components in the context of an application, it is easier to run a locally modified version of Aquarium in your application (e.g. Console). There are two ways to do this: npm link, or copying the module into your app. This allows you to make changes to components and instantly see the change in the context of the app.
- In design-system directory, run
npm link
- In design-system directory, run
npm link <path to app>/node_modules/react
to avoid running into conflict of having two react instances. This will otherwise break the rules of hooks and crash the app. More info on the issue here. If the command fails with errors about peer dependencies, re-run the command, adding--force
at the end. - In the app directory, run
npm link @aivenio/aquarium
- Now
<app>/node_modules/@aivenio/aquarium
is a symlink to your local Aquarium directory. - In design-system directory, run
npm run watch
- Done! Now you should be able to develop DS locally, and changes are reflected to the application which depends on
@aivenio/aquarium
- When you want to stop using the npm link, and go back to the regular imported version, in your app directory, run
npm unlink --no-save @aivenio/aquarium
, thennpm i
to reinstall the dependency.
npm link can be tricky to get working. A simpler approach is to build the module and copy it into your application's node-modules
directory:
npm run build:ds:module && cp -r dist <path to app>/node_modules/@aivenio/aquarium
Remember that source .env
is needed before NPM commands.
-
npm test
to run all tests once -
npm test -- Button
to run only tests matchingButton
-
npm run test:watch
to run tests in watch mode -
npm run test:coverage
to run all tests and see the coverage
Note! It's good idea to run tests in watch mode when developing. If for example snapshot tests fail due to some code changes it's easy to update those with the jest commandline tool. If you want to just update the snapshots that can be done with jest --updateSnapshot
. More information here
-
THEME=<brand> npm start
to start local storybook with a theme -
THEME=<brand> npm run build
to build DS module with a theme -
npm run figma -- sync -i .figma-file.json
to generate./tokens.json
but using previously fetched local file instead of fetching the huge Figma file from API. -
npm run figma -- sync --debug
to enable more verbose output -
npm run figma -- sync --foundation-page-name 'my foundations'
to override options. -
jq '.document.children[] | select(.id == "8916:120229")' .cache/figma-file.json
to slice Foundations page from whole Figma file JSON.
There is more documentation for the Figma sync tool.
Run npm run build:storybook
.
Storybook is deployed to Cloudflare Pages everytime new code is merged to main.
- run
npm run build
- see
dist
for the built code
-
Run
npm run release -- --bump <bump>
(all the dashes are needed) where bump is one ofmajor
,minor
orpatch
.This command will automatically checkout a release branch, commit the version bump, and open your browser to submit a PR.
-
Review the PR created, and merge it to main. GH actions will handle the rest.
Any API breaking change should be a major version bump and should be mentioned in release notes!
Breaking change examples:
- Rename a prop in Button component
- Rename Card component to Box
- Remove a prop
- Remove a component
These are not breaking changes:
- Add a new prop for Button
- Add a new component
- Changing storybook
- Changing tests
A lot of research was done into existing design systems, and if we could reuse parts of them. The conclusion was that we take mostly inspiration of the good ideas, and maybe use individual components by copy pasting code to our system.
Some of the projects are huge, the link most commonly points directly to the part of the code base which defines the components. For tests, I checked that tests for a few components look OK, no coverage or deeper analysis done.
Next things to consider:
- Is treeshaking possible when using just parts of the library? Size of the dist is also important factor, but after treeshaking the footprint should be quite similar across libraries
- Maturity and activeness (commits, recent activity, contributor distribution, closed vs open issues, PR merging activity)
- Are they migrating to another tech ? JS -> TS, Sass -> styled-components, etc
- Owners, is it community driven or company driven? Project with 13 stars can be super mature if it's been developed internally in a company for 20k commits for N years
- Accessibility
- Customizability, do you need to fork or can you customise while getting upstream updates?
Link | Commits* | JS/TS | Styling | License | Tests | Other |
---|---|---|---|---|---|---|
Ant Design | 18.6k | TS | Less. example | MIT | ☑️ | |
Aragon UI | 0.8k | JS | styled-components | MIT | Not much | |
Baseweb by Uber | 2.3k | JS (Flow) | style-tron | MIT | ☑️ | |
Basis | 0.3k | JS | emotion | MIT | ☑️ | |
Blueprint | 1.8k | TS | Sass | Apache 2.0 | ☑️ | |
Carbon | 6.8k | JS | CSS classnames linking to Sass | Apache 2.0 | ☑️ | ☑️ Storybook |
Fluent UI by Microsoft | 8.6k | TS | CSS in JS, seems to be a custom one | MIT | ☑️ | |
Grommet | 5.2k | JS | styled-components | Apache 2.0 | ☑️ | ☑️ Storybook |
Material UI | 11.9k | JS | CLSX, CSS in JS. Example | MIT | ☑️ | |
MongoDB design | 0.4k | JS | CSS | package.json says MIT, no LICENSE file | No | |
Pivotal UI | 4.0k | JS | Sass | MIT | ☑️ | |
Polaris by Shopify | 6.1k | TS | Sass | Modified MIT, see more | ☑️ | |
Primer by GitHub | 4.5k | JS | styled-components | MIT | ☑️ | |
React Bootstrap | 3.8k | JS | Bootstrap CSS classes | MIT (also Bootstrap is MIT) | ☑️ | |
Reactstrap | 0.8k | JS | Bootstrap CSS classes | MIT | ☑️ | |
RMWC | 1.9k | JS | CSS classnames using material-components-web by Google (source is Sass) | MIT (also material-components-web is MIT) | ☑️ | |
Salesforce Design System | 9.5k | JS | Sass | Code BSD 3-Clause, see: https://github.com/salesforce-ux/design-system#licenses | ☑️ | |
Thumbprint | 0.7k | TS | Sass | Apache 2.0 | ☑️ | |
VTEX Styleguide | 4.3k | JS | Custom Tachyons classes + CSS. Example implementation and CSS | Unlicensed | Not much | |
Zendesk Garden | 0.8k | TS | styled-components | Apache 2.0 | ☑️ | ☑️ Storybook |
- Most of these repos are monorepos managed with Lerna. Commit count is just to give rough estimate of how much the code has been iterated.
For further investigation, you can find plenty of components in GitHub: https://github.com/search?l=&p=99&q=created%3A%3E2015-01-01+extension%3Ajs+extension%3Ajsx+extension%3Ats+extension%3Atsx+size%3A%3E100+filename%3AButton.js+filename%3AButton.ts+filename%3AButton.jsx+filename%3AButton.tsx+filename%3Abutton.js+filename%3Abutton.ts+filename%3Abutton.jsx+filename%3Abutton.tsx&ref=advsearch&type=Code
You can find more design systems here: https://github.com/alexpate/awesome-design-systems. Not all of them have open source code.