AlixPartners UI Component Library

A reusable React component library aligned with the AlixPartners Design System.

Published as @alixpartners/ui-components on npm. The current major is 3.x.

What’s new in 3.x

• React 19 support alongside React 18.3+ — consuming apps are not forced to upgrade React
• Automatic npm publish on merge to main, with Slack release notes
• Composite tokens — typography from Figma lands as SCSS mixins (@mixin ap-*) that apply the full text style (size, weight, line-height, letter-spacing, transform), not one-off hardcoded values
• Design tokens, icon web-font, and illustrations generated in-repo from Figma, with automated PRs when the design system changes
• ESM library build (Vite 6) with CSS injected into the bundle — no separate stylesheet import
• Storybook 9 as the component workshop
• CI unit-tested and built against both React 18 and React 19
• Icon font ships woff / woff2 only (legacy .eot / .svg formats dropped)

Version support

3.0 is not backwards compatible with 1.x. Existing 1.x apps can stay on that line. New work should use 3.x.

React support

Peer dependencies accept React ^18.3.1 || ^19.0.0, so apps can stay on 18.3 or move to 19.

Useful links

Installation

npm install @alixpartners/ui-components

Install the peer dependencies if the consuming app does not already have them:

npm install react@^18.3.1 react-dom@^18.3.1

React 19 is equally valid:

npm install react@^19.0.0 react-dom@^19.0.0

radix-ui and notistack ship with the package (kept external at build time so they can share runtime state with an app that also uses them). You do not need to install them separately unless you want a top-level copy for your own code.

Styles (including the icon font and design-system tokens) are bundled with the package. You do not need a separate CSS import.

The package is ESM-only. Import it from ESM / bundler code (import), not require().

Usage

import { Button } from '@alixpartners/ui-components'

function App() {
  return (
    <Button type="primary" variant="default">
      Click me
    </Button>
  )
}

ToastProvider (and useToast) wrap the app once:

import { ToastProvider, useToast } from '@alixpartners/ui-components'

function App() {
  return (
    <ToastProvider>
      <Page />
    </ToastProvider>
  )
}

Components

Explore every component, variant, and prop in Storybook. Public exports include:

Browse the hosted Storybook, or run it locally:

npm run storybook

Design tokens

Tokens, the icon web-font, and illustrations are generated from Figma inside this repo (design-tokens/). A pipeline syncs design-system changes and opens a PR against development.

Atomic tokens (colors, spacing, sizes) become $ap-* SCSS variables. Composite tokens — currently typography — become @mixin ap-* mixins so a component can apply a whole text style in one include, for example @include ap-button-md-contained.

Landing a Tokens Studio export

When UX exports tokens from Figma (Tokens Studio multi-file .zip), run /sync-design-tokens in Claude Code or Cursor with this repo open. Attach the zip and the design-system version (e.g. 1.5.0). The command unpacks the export into design-tokens/tokens/, rebuilds src/assets/_variables.scss, repairs broken $ap-* consumer refs, and opens a PR against development on design-tokens/<version>.

/sync-design-tokens
/sync-design-tokens 1.5.0
/sync-design-tokens --sync          # also refresh icons/illustrations from Figma
/sync-design-tokens --dry-run       # unpack + rebuild + report; no commit/push/PR

The zip must contain $metadata.json (folder / multi-file export), not a lone tokens.json. Claude Desktop does not load repo slash commands — use Claude Code or Cursor, or follow .claude/skills/sync-design-tokens/SKILL.md with the zip attached.

Regenerating locally

npm run tokens:build    # parse JSON tokens → SCSS (no Figma secrets)
npm run tokens:sync     # fetch from Figma, rebuild font + SCSS + illustrations
npm run tokens:verify   # fail if src/assets/_variables.scss has drifted

See design-tokens/README.md for inputs, outputs, and the surprises (positional icon codepoints, non-reproducible font binaries, typography mixins).

Build

npm run build

Output lands in dist/. The published entry is dist/main.js (ESM) with types at dist/main.d.ts.

Using a local build in another project

# In this repo:
npm link

# In the consuming project:
npm link @alixpartners/ui-components

Then import from @alixpartners/ui-components as usual.

Testing

CI runs unit tests and a production build against React 18.3.1 and React 19.1.0.

npm run test              # Vitest (unit + Storybook projects)
npm run test:unit         # unit tests only (happy-dom)
npm run test:storybook    # Storybook interaction tests
npm run test:playwright   # Playwright e2e
npm run coverage          # Vitest coverage

Publishing

Do not publish by hand. Merging to main publishes @alixpartners/ui-components to the public npm registry.

1. Bump the version in package.json, package-lock.json, and CHANGELOG.md (on development)
2. Open a pull request from development → main
3. When the PR is merged, .pipelines/publish-prod.yml builds the library, runs npm publish --access public, and posts the changelog to Slack

The pipeline needs secret variables NPM_TOKEN (npm automation token with publish rights for @alixpartners) and SLACK_WEBHOOK_URL.

Package: npmjs.com/package/@alixpartners/ui-components

Contributing

See CONTRIBUTING.md for the process and component structure. Open pull requests against development.