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

| Line | Status | | ---- | ------ | | v3.x | Current — production | | v2.x | Previous major | | v1.x | Legacy only (critical fixes) |

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.

| React version | Supported | | ------------- | --------- | | 18.3+ | Yes | | 19.x | Yes |

Useful links

| Resource | URL | | -------- | --- | | Design system docs | Platforms Design System | | Storybook | apuilibdev.azurewebsites.net | | npm | @alixpartners/ui-components | | Figma | Platforms Design System | | Slack | #platforms-components-library |

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 radix-ui@^1.4.2 notistack@^3.0.1

React 19 is equally valid:

npm install react@^19.0.0 react-dom@^19.0.0 radix-ui@^1.4.2 notistack@^3.0.1

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) also need notistack at runtime. 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:

| Group | Components | | ----- | ---------- | | Actions | Button, SplitButton | | Inputs | Input, Textarea, Checkbox, Radio, RadioGroup, Toggle, Search, Datepicker, Dropdown, Creatable, TagsFields, RichTextEditor | | Feedback | Banner, Toast, ToastProvider, useToast, Tooltip, Dialog, Spinner, Ghost | | Navigation | NavBar, CorusHeader, Breadcrumb, Tab, TabNavigation | | Files | FilePicker, DragAndDrop | | Display | Tag, Icon, Illustration |

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.