@keboola/design

The Keboola design system — shadcn-aligned, Radix-underneath, FontAwesome icons.

📦 Storybook: https://design-hh9143njj-keboola.vercel.app

📖 Decision tree: AGENTS.md — which component to use when. 🎨 Branding: ../../docs/branding.md (lands with PR #5674).

Install

yarn add @keboola/design @keboola/tailwind-config

Use

import { Button } from '@keboola/design';
import '@keboola/design/styles';

Documentation

$ yarn dev

See Storybook's documentation for an introduction to writing stories

Testing

$ yarn test

Or in UI mode:

$ yarn test:ui

For more information, read Vitest's documentation

Component tests (Storybook Vitest addon)

Every story is also run as a test via the Storybook Vitest addon (UT-4117):

• render / smoke — the story mounts in a real browser without throwing (catches broken imports, runtime errors, bad props);
• interaction — each story's play() function runs as a test.

yarn workspace @keboola/design test:stories

This is the cheap, low-flakiness base layer for testing stories. Screenshot/visual regression is a separate, complementary layer (UT-4060) — the Vitest addon does not do screenshot comparison.

How it's wired:

• vitest.storybook.config.ts — a separate Vitest config (browser mode, Playwright Chromium provider) so yarn test stays jsdom-only and browser-free; story tests are opt-in via test:stories.
• .storybook/vitest.setup.ts — applies the Storybook preview annotations (decorators, globals) so tests render exactly like Storybook.
• optimizeDeps.entries crawls every story up front so Vite optimizes all story dependencies in one pass — without it, a heavy dep (mermaid, codemirror, …) discovered mid-run makes Vite re-optimize and 404 in-flight imports.

Prerequisites: build the workspace deps once (yarn build --filter='@keboola/design^...') and install the browser (yarn workspace @keboola/design exec playwright install chromium).

Adding coverage: nothing to do — every CSF *.stories.tsx is picked up automatically. Add a play() to a story to turn it into an interaction test. (MDX docs pages — src/**/*.mdx — are not executed as tests; the addon only runs CSF stories.)

Runs locally only for now. There's no CI workflow yet — in CI (2-core runner) browser mode costs ~35 s per story file, so the suite needs a CI-viability pass (browser isolate: false, cached Vite deps, sharding, or nightly) before it's wired in. Tracked in UT-4191. Adding @storybook/addon-a11y for per-story accessibility checks is a separate follow-up.

Icons

All icons should use the Icon component, which is a wrapper around FontAwesomeIcon. Browse the available icons in the Storybook Icons page.

When using custom icons (prefix fak), pass the icon as a tuple: <Icon icon={['fak', 'custom-icon']} />.