Tailwind CSS v4

@aidsgn/tokens includes an official Tailwind CSS v4 theme. It maps predictable utilities to the same semantic CSS variables used by aidsgn components, so utilities follow Brand and Theme mode changes at runtime. It does not expose private Brand palettes or replace the framework-neutral CSS token contract.

Install and import

Install Tailwind v4 and the token package using your application’s package manager. For a PostCSS application:

npm install @aidsgn/tokens tailwindcss @tailwindcss/postcss

Configure Tailwind’s PostCSS plugin, then import the styles in this order from your global application CSS:

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

An opt-in Brand bundle belongs between the base variables and the Tailwind adapter:

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

This integration is Tailwind v4-only. There is no Tailwind v3 preset, JavaScript configuration preset, or tailwind.config.js compatibility layer.

Semantic utility names

Names preserve intent and carry an aidsgn segment so application utilities remain easy to distinguish:

<article
  class="grid gap-aidsgn-24 rounded-aidsgn-control border border-aidsgn-border-default bg-aidsgn-surface-default p-aidsgn-24 shadow-aidsgn-sm"
>
  <h2 class="type-aidsgn-heading-2 text-aidsgn-text-primary">Qualification result</h2>
  <p class="type-aidsgn-body text-aidsgn-text-secondary">Ready for review.</p>
  <button
    class="rounded-aidsgn-control bg-aidsgn-surface-action px-aidsgn-control-padding-inline py-aidsgn-control-padding-block text-aidsgn-text-inverse transition-colors duration-aidsgn-fast ease-aidsgn-standard"
  >
    Continue
  </button>
</article>

Purpose	Examples
Text and icon content	`text-aidsgn-text-primary`, `text-aidsgn-text-link`, `text-aidsgn-text-error`
Surfaces and actions	`bg-aidsgn-surface-default`, `bg-aidsgn-surface-action`, `bg-aidsgn-surface-success`
Borders and focus	`border-aidsgn-border-default`, `border-aidsgn-border-focus`
Spacing	`gap-aidsgn-24`, `p-aidsgn-16`, `px-aidsgn-control-padding-inline`
Shape and elevation	`rounded-aidsgn-sm`, `rounded-aidsgn-control`, `shadow-aidsgn-md`
Motion	`duration-aidsgn-fast`, `ease-aidsgn-standard`, `scale-aidsgn-press`

Semantic colors resolve to variables such as --aidsgn-color-surface-action, never private variables such as an Offprint ink or aidsgn blue palette step. Tailwind’s normal opacity modifiers and state variants can be combined with these color names where appropriate, but state meaning must still be conveyed programmatically and not by color alone.

Brand and Theme mode

The compiled utility declarations retain var(--aidsgn-*) values. Existing runtime selectors therefore work without a Tailwind rebuild:

<html data-aidsgn-brand="offprint" data-aidsgn-theme="dark"></html>

Use light or dark for an explicit Theme mode. Omit data-aidsgn-theme to follow prefers-color-scheme; omit data-aidsgn-brand for the default aidsgn Brand.

A product-owned Brand can define the shared variables in its own global CSS without modifying or forking aidsgn:

:root[data-aidsgn-brand="product"] {
  --aidsgn-color-surface-default: oklch(98% 0.01 90);
  --aidsgn-color-text-primary: oklch(22% 0.03 45);
  --aidsgn-color-surface-action: oklch(48% 0.16 35);
  --aidsgn-control-radius: 0.25rem;
}

@media (prefers-color-scheme: dark) {
  :root[data-aidsgn-brand="product"]:not([data-aidsgn-theme]) {
    --aidsgn-color-surface-default: oklch(20% 0.02 45);
    --aidsgn-color-text-primary: oklch(94% 0.01 90);
  }
}

:root[data-aidsgn-brand="product"][data-aidsgn-theme="dark"] {
  --aidsgn-color-surface-default: oklch(20% 0.02 45);
  --aidsgn-color-text-primary: oklch(94% 0.01 90);
}

Override every identity role the Brand owns for both modes and verify contrast; unmodified roles continue to use the base aidsgn values. The same bg-aidsgn-*, text-aidsgn-*, and rounded-aidsgn-* classes then resolve through the product’s variables.

Complete typography

aidsgn typography tokens are composite recipes. Use type-aidsgn-body, type-aidsgn-control-label, or type-aidsgn-heading-1 through type-aidsgn-heading-4. Each utility applies both:

font: var(--aidsgn-typography-body);
letter-spacing: var(--aidsgn-typography-body-letter-spacing);

This keeps family, fluid size, weight, line height, and letter spacing together, including when a Brand changes the complete recipe. Avoid recreating one recipe from separate Tailwind font, size, weight, leading, and tracking classes.

Responsive and container variants

The page-reference variants use aidsgn’s documented rem values:

Variant	Minimum width
`aidsgn-sm:`	`30rem`
`aidsgn-md:`	`48rem`
`aidsgn-lg:`	`64rem`
`aidsgn-xl:`	`80rem`

<main class="grid gap-aidsgn-24 aidsgn-md:grid-cols-2"></main>

These are page-level reference points, not device categories. Their rem units preserve user font-size behavior. Add a content-driven arbitrary variant when the composition needs another threshold instead of forcing the nearest reference.

Reusable compositions should prefer container queries:

<section class="@container/profile">
  <div class="grid gap-aidsgn-16 @min-[32rem]/profile:grid-cols-[auto_minmax(0,1fr)]"></div>
</section>

The named @aidsgn-sm: through @aidsgn-xl: container variants are also available when a shared reference genuinely fits. A local 32rem query like the example remains local because it describes that content, not a system-wide device width.

Next.js App Router and first paint

Import the CSS from the root layout’s global stylesheet. Server-rendered class names then produce meaningful initial HTML, and the browser receives the semantic variables and generated utilities before hydration. For System mode, omit data-aidsgn-theme; CSS applies the matching mode before application JavaScript runs.

For a stored explicit choice, resolve it on the server—for example from a cookie—and render the same attribute in the initial <html> element:

import { cookies } from "next/headers";

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const selected = (await cookies()).get("theme")?.value;
  const theme = selected === "light" || selected === "dark" ? selected : undefined;

  return (
    <html lang="en" data-aidsgn-theme={theme}>
      <body>{children}</body>
    </html>
  );
}

Do not render one mode on the server and replace it from localStorage after hydration; that causes a wrong first paint and can produce a hydration warning. Keep the server cookie and client selector synchronized. The repository’s Next.js production fixture verifies initial SSR markup, System/Light/Dark and alternate Brand resolution, and hydration without warnings.

CSS size and upgrades

Tailwind emits utilities that it discovers in your application source. The adapter does not generate a second primitive color palette and Offprint remains opt-in, but @aidsgn/tokens/css still supplies the framework-neutral runtime variable contract. Load component CSS selectively using the installation guide when the complete component catalog is unnecessary.

The Tailwind adapter versions with @aidsgn/tokens. Pin a compatible Tailwind v4 range, review the token package changelog during upgrades, and rebuild application CSS. New semantic roles can add utilities; a renamed utility, changed semantic mapping, or changed reference breakpoint is treated as a breaking public-contract change under the package’s pre-1.0 versioning policy.