@upbound/elements

Primitive UI components and design tokens for Upbound applications.

Installation

yarn add @upbound/elements
# or
npm install @upbound/elements

Usage

1. Import Styles

Add the compiled Tailwind CSS to your application:

CSS Import (Docusaurus, Vite, etc.):

/* In your main CSS file */
@import '@upbound/elements/styles.css';

JavaScript Import (Next.js, React):

// In your _app.tsx or root layout
import '@upbound/elements/styles.css';

2. Configure Tailwind (Optional)

If your application uses Tailwind CSS, extend your config with the shared preset:

// tailwind.config.js
module.exports = {
  presets: [require('@upbound/elements/tailwind.preset')],
  content: [
    './src/**/*.{ts,tsx}',
    // Include elements package for Tailwind class detection
    './node_modules/@upbound/elements/dist/**/*.{js,ts,tsx}',
  ],
};

The preset includes:

• Colors: Upbound brand colors and semantic tokens
• Typography: Font families (Avenir, Consolas)
• Z-Index Scale: z-1, z-2, z-5, z-51, z-100, z-101, z-102, z-110, z-120, z-200, z-1000, z-1001, z-2000
• Animations: Accordion, fade, and other UI animations

3. Import Components

import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, UButton } from '@upbound/elements';

function MyComponent() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <UButton>Open Dialog</UButton>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Hello World</DialogTitle>
        </DialogHeader>
        <p>Dialog content goes here.</p>
      </DialogContent>
    </Dialog>
  );
}

4. Framework-Specific Link/Image Components (Optional)

By default, components that render links use standard <a> elements and images use <img> elements. If you're using a framework like Next.js and want to use its optimized Link and Image components, wrap your app with ElementsProvider:

// In your _app.tsx or root layout
import { ElementsProvider } from '@upbound/elements';
import Link from 'next/link';
import Image from 'next/image';

function App({ children }) {
  return (
    <ElementsProvider Link={Link} Image={Image}>
      {children}
    </ElementsProvider>
  );
}

Without the provider, components work perfectly with standard HTML elements — no configuration needed.

This pattern also works with other routing libraries:

// React Router
import { Link } from 'react-router-dom';

<ElementsProvider Link={Link}>{children}</ElementsProvider>;

Available Exports

| Export | Description | | ----------------------------------- | --------------------------------------------------------- | | @upbound/elements | All components (Button, Dialog, Sheet, Tooltip, etc.) | | @upbound/elements/styles.css | Compiled Tailwind CSS with all design tokens + font-faces | | @upbound/elements/tailwind.preset | Tailwind CSS preset with colors, fonts, z-index | | @upbound/elements/utils | Utility functions (cn, cva, etc.) | | @upbound/elements/assets/fonts/* | Individual font files (woff2, woff, ttf, eot) |

Development

Run Storybook to develop components in isolation:

cd packages/elements
yarn storybook

Build the package:

yarn build        # Build JS + CSS
yarn build:css    # Build CSS only

Fonts

The package includes Avenir and Consolas font families with all weights and styles.

Auto-Discovered Fonts (Recommended)

Fonts are automatically included when you import styles.css:

/* Fonts are included automatically - no extra imports needed! */
@import '@upbound/elements/styles.css';

This includes:

• Avenir: weights 100-900, normal and oblique styles
• Consolas: for monospace/code text

Manual Font References

You can also reference individual font files directly:

@font-face {
  font-family: 'Avenir';
  src:
    url('@upbound/elements/assets/fonts/Avenir-Roman.woff2') format('woff2'),
    url('@upbound/elements/assets/fonts/Avenir-Roman.woff') format('woff'),
    url('@upbound/elements/assets/fonts/Avenir-Roman.ttf') format('truetype');
  font-weight: 400;
}

Tailwind Integration

The Tailwind preset configures font-sans to use Avenir and font-mono to use Consolas:

// tailwind.config.js
module.exports = {
  presets: [require('@upbound/elements/tailwind.preset')],
  // ...
};

Then use in your components:

<p class="font-sans">Uses Avenir</p>
<code class="font-mono">Uses Consolas</code>