@neuralytics/alpine-ds

⚠️ Work in progress — this design system is under active development. Expect breaking changes between minor versions until 1.0.0.

Documentation

Changelog: CHANGELOG.md

Component playground (Histoire): not published yet.

For monorepo-level docs (setup, architecture, contribution workflow), see the repository README.

Components already available

• AlpineButton
• AlpineIcon

Prerequisites

• vue ^3.5.25
• tailwindcss ^4.1.17

Integration

1. Install the package: pnpm add @neuralytics/alpine-ds
2. Install the dependencies: pnpm add -D tailwindcss @tailwindcss/vite
3. Register the Tailwind Vite plugin in your vite.config.ts (required for Tailwind to actually process anything — without it your styles silently stay empty):

import tailwindcss from "@tailwindcss/vite"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [
    // ... your other plugins ...
    tailwindcss(),
  ],
})

4. Import the design system's CSS theme in your main style file:

Without a tailwind.config (recommended) — theme.css already handles detection of the package's classes, no content entry needed:

@import "tailwindcss";
@import "@neuralytics/alpine-ds/theme.css";

With a tailwind.config — if your project already has a tailwind.config.ts/.js (custom theme.extend, plugins, content...), keep it alongside the CSS import:

@import "tailwindcss";
@config "./tailwind.config.ts";
@import "@neuralytics/alpine-ds/theme.css";

Nothing needs to change in tailwind.config.ts itself — keep your own theme.extend, plugins, content, etc. as they are, the DS's classes and colors come entirely from theme.css.

Migrating from the old JS preset? Remove the presets: [alpineDsPreset] entry (or wherever you imported @neuralytics/alpine-ds/tailwind-preset) and any content glob you'd added just to scan @neuralytics/alpine-ds's own files — both are now handled by theme.css. tailwind-preset is still published but deprecated.

5. Set the accent color in your project's main.ts:

import { setAccentColorTheme } from "@neuralytics/alpine-ds"

setAccentColorTheme("#fe4e29")

Note that this function can be called at any time. Calling it in your main.ts gives you a default value.

6. (Optional) Set the text color of the primary AlpineButton if white doesn't fit your accent color:

import { setButtonTextColor } from "@neuralytics/alpine-ds"

setButtonTextColor("#000000")

This only affects the primary button's text (not disabled or loading states) and defaults to white if never called.

7. Import a component in a .vue file

import { AlpineButton } from "@neuralytics/alpine-ds"

Colors

The Design System uses the following Tailwind colors:

• gray (aliased to Tailwind's neutral scale)
• red
• yellow (aliased to Tailwind's amber scale)
• green
• blue
• accent (required)

These are the only colors available: any other Tailwind color utility (e.g. bg-purple-500) will not generate any CSS.

Note that all colors use 10 shades: 50, 100, 200, ..., 900. accent must be provided by the consumer via setAccentColorTheme (see step 5 of Integration); the other colors already have a default value.

Icons

AlpineIcon and AlpineButton's icon prop accept Iconify names from two collections only: mdi:* (Material Design Icons) and line-md:* (Material Line Icons). Any other collection logs a console warning and won't render.

Icons are fetched on demand from the Iconify API and cached — no bundling or extra Tailwind configuration needed for icons.