Aiven Aquarium Design System

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

Installation

To install Aquarium to your app:

• 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, use import '@aivenio/aquarium/dist/styles_X.css'

• 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,
                      },
                    },
                ]
            },
        }
    },
  };
  

Development

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.

Prerequisites

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 as autoenv to automatically apply the .env file.

Optional DX improvements

• 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

Common commands

• npm ci to install dependencies
• npm run build to build the production build of the library
• npm start to start Storybook

Developing in the context of your app

To develop Aquarium components in the context of an application, it is easier to run a locally modified version of Aquarium in your application. 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.

npm link

❌ TODO: This doesn't currently work out of the box. Revise the instructions

1. In design-system directory, run npm link
2. In design-system directory, run npm link <path to your 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.
3. In the app directory, run npm link @aivenio/aquarium
4. Now <path to your app>/node_modules/@aivenio/aquarium is a symlink to your local Aquarium directory.
5. In design-system directory, run npm run watch
6. Done! Now you should be able to develop DS locally, and changes are reflected to the application which depends on @aivenio/aquarium
7. 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, then npm i to reinstall the dependency.

Copy module

⚠️ If you've installed new dependencies on the DS side, this doesn't work. See instructions for npm pack instead.

npm link can be tricky to get working. A simpler approach is to build a production build of the DS and copy it into your application's node-modules directory. Remember to restart the build process of your app once DS has been built and copied over. Here's a snippet to do all that:

cd <path to ds> \
  && npm run build \
  && cd <path to your app> \
  && rm -rf ./node_modules/@aivenio/aquarium/dist \
  && cp -R <path to ds>/dist ./node_modules/@aivenio/aquarium # && <the dev/build command of your app>

npm pack

Copy module is a hack which doesn't work when the dependencies have changed on the DS side since the last install in your app side.

You can use pack-and-install.sh utility script to create local release package and install it to your local application.

APP_PATH=<path to your app> ./pack-and-install.sh && <run dev/build command for your app>

Run it again after each change, and restart the dev server of your app. The script leaves the app's package.json and package-lock.json untouched, so run npm ci in the app to go back to the released version.

Or if you want, you can also run npm pack command manually and then install that to your app.

cd <path to ds> \
  && npm run build \
  && jq --arg file_name $(npm pack 2>&1 | tail -1) '.dependencies["@aivenio/aquarium"] = "file:<path to ds>/\($file_name)"' <path to your app>/package.json > <path to your app>/package-json-new.tmp \
  && cd <path to your app> \
  && mv package-json-new.tmp package.json \
  && npm install # && <the dev/build command of your app>

Make sure you replace all <path to ds> and <path to your app> strings with the exact absolute paths.

Running tests

Remember that source .env is needed before NPM commands.

• npm test to run all tests once
• npm test -- Button to run only tests matching Button
• 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

Other useful commands

• 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.

Build and release process

Storybook

To build storybook locally

Run npm run build:storybook.

Storybook deploy

Storybook is deployed to Cloudflare Pages everytime new code is merged to main.

The same commit is also deployed to an Aiven Runtime application service by deploy-storybook.yml, which triggers a redeploy of that service so it rebuilds the root Dockerfile and serves the MCP server alongside the UI.

The workflow needs these repo settings:

Storybook MCP server

Storybook exposes an MCP server so agents can query real component docs and props instead of guessing. It's generated from this repo's MDX docs pages and TypeScript prop types — see AGENTS.md for the rules agents in this repo follow when using it.

• Local dev: run npm start, then the MCP server is at http://localhost:6006/mcp. Already wired up for this repo via .mcp.json.

• From another project (e.g. a console pointing at this design system): once Storybook is running here, add it as a remote MCP server — claude mcp add --transport http aquarium-storybook http://localhost:6006/mcp.

• Hosted: every merge to main redeploys the container on Aiven Runtime, so there's no need to run Storybook locally just to query docs — point at <service-url>/mcp instead. Find the service URL in the Aiven console. It lives inside a VPC, so check it's reachable from where you're running the agent.

• Container: build and run the Dockerfile to get a static Storybook and a self-hosted docs-only MCP server (mcp-server/) on the same port:

  docker build -t aquarium-storybook-mcp .
  docker run --rm -p 6006:6006 aquarium-storybook-mcp
  

  Both are then served from http://localhost:6006. Only the docs toolset works here — it has no live dev server to preview or test stories against.

  Agents are served only the cross-cutting docs pages (Concepts, Design tokens, How-to guides). The per-component MDX pages are dropped, since each one's guidance lives in that component's meta JSDoc and reaches the agent through its component entry instead. Component stories, snippets and prop tables are unaffected. See mcp-server/server.ts for why this isn't done with Storybook's !manifest tag.

Aquarium package

How to build Aquarium package locally

• run npm run build
• see dist for the built code

How to create a release

1. Run npm run release -- --bump <bump> (all the dashes are needed) where bump is one of major, minor or patch.

   This command will automatically checkout a release branch, commit the version bump, and open your browser to submit a PR.

2. 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 changes

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

Background

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.

Evaluation of existing React libraries

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?

• 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.