aptlylabs-ui

Aptlylabs UI

This repository is the Aptlylabs design system: React components (buttons, dialogs, forms, and more) built with shadcn/ui. You consume it as an npm package named @voxxup/aptlylabs-ui.

What you get from the package: component source (TypeScript/React) and a shared globals.css file that sets up Tailwind, fonts, and design tokens. What you still provide in your app: a normal React build (for example Vite) and Tailwind CSS v4 running in your project so those styles and utility classes are actually generated at build time. The package does not bundle a full styling pipeline for you—it expects your app to run Tailwind like any other Tailwind v4 project.

The package is published to GitHub Packages, not the public npm registry, so installing it requires GitHub authentication (see below).

Documentation site

https://ui.aptlylabs.com — live docs for this design system, built from the apps/docs app in this repository. It includes:

README — overview and how the package fits into a Tailwind v4 app
Examples — interactive demos of atomic components from @voxxup/aptlylabs-ui (browse by component, copy usage patterns)
Blocks — larger copy-paste layouts (dashboard patterns, filters, charts, tables, sign-in, multistep flows, marketing forms, settings, billing, activity feeds, and more), each with multiple variants and optional code snippets

Deployment is GitHub Pages; custom domain and build details are in docs/ui-docs-hosting.md.

Use this library in your own project

Do these steps in your application repository, not inside the aptlylabs-ui monorepo (unless you are linking locally for development).

1. Get access with a GitHub token

GitHub Packages is a separate registry from npmjs.org. When you run npm install @voxxup/aptlylabs-ui, npm must send credentials GitHub accepts. A personal access token is the usual way for developers.

Create a token in GitHub → Settings → Developer settings → Tokens.
Enable read:packages. That permission is enough to download the package.

Then make the token available to npm. Most teams use an environment variable so the token is not stored in the project:

export NODE_AUTH_TOKEN=ghp_your_token_here

Run that in the same terminal session before npm install, or configure your shell or CI to set it automatically. Never commit the token into git. If you want a machine-wide npm setup, you can put the token in ~/.npmrc instead; details and alternatives are in docs/private-registry.md.

2. Point npm at GitHub for the `@voxxup` scope

npm needs to know that packages under @voxxup/... come from GitHub Packages, not from the public registry. In your project root, add a .npmrc file (or merge these lines into an existing one):

@voxxup:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

The second line tells npm to send your token when talking to that host. After this, npm install @voxxup/aptlylabs-ui can succeed when NODE_AUTH_TOKEN is set.

3. Install the package

npm install @voxxup/aptlylabs-ui

In package.json, use a version range your team has actually published (ask your team or check release notes / GitHub Packages).

4. Add Tailwind in your app and connect the design-system CSS

This step is required for things to look correct. The library’s components use Tailwind utility classes (for example flex, gap-4, bg-primary). Those utilities are generated when your build runs Tailwind v4 over your CSS entry and the files Tailwind is told to scan.

Why install Tailwind in your app?
Tailwind runs as part of your bundler (Vite, etc.). It reads your CSS imports (including @voxxup/aptlylabs-ui/globals.css) and outputs the CSS your browser needs. The design system package lists Tailwind-related tooling for its own development; your app still needs tailwindcss and the Vite plugin (@tailwindcss/vite) so your project’s build actually executes Tailwind.

Install the tooling (Vite + React):

npm install -D tailwindcss @tailwindcss/vite

If you use something other than Vite, use your stack’s Tailwind v4 setup (for example PostCSS) instead—concept is the same: Tailwind must run on your CSS during build.

Enable Tailwind in Vite by adding the plugin next to React. Your vite.config.ts should look conceptually like this:

import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [react(), tailwindcss()],
});

Without tailwindcss() in the plugin list, imports inside globals.css (such as Tailwind’s own imports) will not be processed the way this design system expects, and the UI will often look broken or plain.

Create one root stylesheet (for example src/index.css) that does two jobs:

Pull in the design system — one line imports all shared theme and base styles:
```
@import "@voxxup/aptlylabs-ui/globals.css";
```
Tell Tailwind to look at your code — Tailwind only emits utilities for class names it sees in “source” files. The library’s CSS already scans its own package files; it does not automatically scan your App.tsx or routes. You add an explicit @source rule so classes you write in your app are included:
```
@source "./**/*.{ts,tsx}";
```
Change the glob if your components live outside src or use different extensions.

Together, a minimal index.css often looks like:

@import "@voxxup/aptlylabs-ui/globals.css";

@source "./**/*.{ts,tsx}";

Load that file once from your client entry point (for example main.tsx):

import "./index.css";

Common mistake: importing only @voxxup/aptlylabs-ui/globals.css from TypeScript without the Tailwind Vite plugin and without a @source line for your app. That usually yields missing styles or a page that looks almost unstyled. A working reference is the example/ directory in this repo (Vite + React + the same pattern).

5. Import and use components

import { Button, Card } from "@voxxup/aptlylabs-ui/components";

You can also import from a specific file when you want tighter control over bundling, for example @voxxup/aptlylabs-ui/components/button.

Add or update components in this library (contributors)

If you work inside this GitHub repository, you can add or refresh components using the shadcn CLI. From the repository root:

npx shadcn@latest add <component-name> -c packages/ui

Example:

npx shadcn@latest add button -c packages/ui

Output goes under packages/ui/src/components. Releasing a new version for other teams to install follows your usual publish process; see docs/private-registry.md for tokens with publish rights, CI, and GitHub Releases.