Installation

Choose the package for your application, then load the design tokens, component styles, and element registration once at your application entry point.

Web Components

Install the tokens and native components:

npm install @aidsgn/tokens @aidsgn/components

Load the shared styles and register the complete component catalog:

import "@aidsgn/tokens/css";
import "@aidsgn/components/styles.css";
import "@aidsgn/components/register";

Native HTML owns its light-DOM structure. Include the semantic descendants in the server response; the custom element only attaches behavior:

<aidsgn-button variant="primary">
  <button
    class="aidsgn-button aidsgn-button--primary aidsgn-button--medium"
    type="button"
    aria-busy="false"
  >
    <span class="aidsgn-button__label">Save changes</span>
    <span class="aidsgn-button__spinner" role="status" aria-label="Loading" hidden></span>
  </button>
</aidsgn-button>

Prefer the React or Vue wrappers when available: they generate this structural boilerplate on the server while keeping application code concise.

React

The React wrappers require React 19 or newer.

npm install @aidsgn/tokens @aidsgn/components @aidsgn/react

Load the styles and registration entry point once in browser-facing application code:

import "@aidsgn/tokens/css";
import "@aidsgn/components/styles.css";
import "@aidsgn/react/register";

Import components from the React package:

import { AidsgnButton } from "@aidsgn/react";

export function SaveButton() {
  return <AidsgnButton>Save changes</AidsgnButton>;
}

For server-rendered applications, place the registration import at the client boundary. See React and Vue for event, ref, and server-rendering examples.

Vue

The Vue wrappers require Vue 3.5 or newer.

npm install @aidsgn/tokens @aidsgn/components @aidsgn/vue

Load the styles and registration entry point once in browser-facing application code:

import "@aidsgn/tokens/css";
import "@aidsgn/components/styles.css";
import "@aidsgn/vue/register";

Import components from the Vue package:

<script setup lang="ts">
import { AidsgnButton } from "@aidsgn/vue";
</script>

<template>
  <AidsgnButton>Save changes</AidsgnButton>
</template>

See React and Vue for events, template configuration, refs, and server-rendering examples.

Load fewer component styles

@aidsgn/components/styles.css includes the complete component catalog. To reduce the CSS payload, import the reset, shared styles, and only the component styles you use:

import "@aidsgn/tokens/css";
import "@aidsgn/components/styles/reset.css";
import "@aidsgn/components/styles/shared.css";
import "@aidsgn/components/styles/button.css";

Native Web Component users can also import an individual defineAidsgn*() function from @aidsgn/components instead of registering the complete catalog.

Tailwind CSS v4

Tailwind v4 applications can import the official semantic theme after Tailwind and the base token variables:

@import "tailwindcss";
@import "@aidsgn/tokens/css";
@import "@aidsgn/tokens/tailwind.css";

This provides Brand-aware utilities such as bg-aidsgn-surface-action, gap-aidsgn-24, and type-aidsgn-body without a JavaScript preset or copied token configuration. See Tailwind CSS v4 for PostCSS setup, naming, themes, responsive variants, Next.js first paint, CSS size, and upgrades.