Your First Primitive

Step-by-step golden path — install Button, import, render, apply variants, and use design tokens.

This guide walks you through using your first Catalyst primitive from install to a fully styled, accessible button. We use @pmi/catalyst-button as the example — the same pattern applies to every other primitive.

1. Install the package

Catalyst primitives are published individually. Install only what you need:

npm install @pmi/catalyst-button

If you haven't configured the Azure DevOps registry yet, complete the Installation guide first.

2. Configure Tailwind

Before adding anything to your tailwind.config.ts, check the primitive's documentation page to see whether it exports a Tailwind preset.

For @pmi/catalyst-button — no custom Tailwind preset is exported. This means you don't need to add anything extra to your config. tailwindThemePreset from @pmi/catalyst-theme is sufficient:

This is the pattern to follow for every primitive: open its documentation page → check the Installation section → add a preset to tailwind.config.ts only if one is listed. If none is listed, tailwindThemePreset alone is enough.

3. Import and render

Import the Button component and render it in your JSX:

import { Button } from '@pmi/catalyst-button';

export default function App() {
  return <Button>Click me</Button>;
}

This renders a default button with the solid variant, md size, and accent color — the Catalyst baseline.

4. Apply variants

Button exposes CVA-powered variant props. Adjust variant, size, and color to match your design:

import { Button } from '@pmi/catalyst-button';

export default function App() {
  return (
    <div className="flex gap-4">
      {/* Variants */}
      <Button variant="solid">Solid</Button>
      <Button variant="outline">Outline</Button>
      <Button variant="ghost">Ghost</Button>

      {/* Sizes */}
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>

      {/* Colors */}
      <Button color="accent">Accent</Button>
      <Button color="neutral">Neutral</Button>
      <Button color="danger">Danger</Button>
    </div>
  );
}

All available variants, sizes, and colors are listed on the Button documentation page under CVA Setup.

6. Render as a different element (`asChild`)

Use the asChild prop when you need to render the button as a router link or anchor — the button's styles and accessibility props are merged onto the child element:

import { Button } from '@pmi/catalyst-button';

export default function Nav() {
  return (
    <Button asChild variant="solid" color="accent">
      <a href="/docs">Read the docs</a>
    </Button>
  );
}

asChild uses the Radix UI Slot primitive under the hood. The child element inherits all button props — including aria-* attributes.

What you built

Step	What happened
Installed `@pmi/catalyst-button`	Got the component and its Tailwind preset
Added `tailwindThemePreset`	Design tokens and button utilities available in Tailwind
Rendered `<Button>`	Accessible, styled button with correct ARIA attributes
Applied variant props	Switched visual style without touching CSS
Used `asChild`	Delegated rendering to `<a>` without losing styles or accessibility

Next steps

Explore the full Button API — all variants, sizes, and props
Add another primitive — follow the same install → preset → render → variant pattern
Read the IDE Setup guide to get JSDoc tooltips and Tailwind token autocomplete in VS Code