Skip to content

Tailwind Setup

Configure Tailwind CSS 4 and the @diffgazer/ui theme variables.

@diffgazer/ui requires Tailwind CSS 4 with the @diffgazer/ui theme variables. The CSS entrypoint depends on the consumption path:

PathCSS entrypoint
Manual copy / dgadd@import "./styles/styles.css" (copied by dgadd init)
npm package@import "@diffgazer/ui/sources.css" + @import "@diffgazer/ui/styles.css"

@diffgazer/keys requires no CSS or Tailwind setup.

Vite setup

01.

Install Tailwind 4

bash
pnpm add -D tailwindcss @tailwindcss/vite
02.

Configure Vite

ts
// vite.config.ts
import tailwindcss from "@tailwindcss/vite"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [tailwindcss()],
})
03.

Import the component CSS

If you initialized with dgadd, import the copied CSS entry from your app CSS:

css
/* src/index.css */
@import "tailwindcss";
@import "./styles/styles.css";

src/styles/styles.css is the canonical component CSS entrypoint. It contains the copied theme import plus the component-level CSS that copied components expect.

In the workspace source, libs/ui/styles/styles.css is the seed entry that imports theme.css. dgadd init and the package build materialize the canonical component entry by appending registry component CSS, such as dialog backdrop and body-lock rules, to that seed.

Use theme.css only when you intentionally want token variables without component CSS, for example in an advanced integration that provides its own component styles:

css
@import "tailwindcss";
@import "./styles/theme.css";

dgadd init copies src/styles/theme.css and src/styles/styles.css, but it does not add either import to your app CSS entrypoint.

In Next App Router, import your app CSS entrypoint once from app/layout.tsx. Keep the Tailwind import, Diffgazer style imports, and any app-local @source directives in that CSS file.

Next.js / PostCSS Setup

For Next.js projects that use PostCSS instead of Vite, install the PostCSS plugin:

bash
pnpm add -D tailwindcss @tailwindcss/postcss

Create or update postcss.config.mjs:

js
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
}

Import your app CSS entrypoint once from app/layout.tsx:

tsx
import "./globals.css"

In globals.css, use the same Tailwind and Diffgazer imports as the Vite setup.

@diffgazer/keys CSS

@diffgazer/keys requires no CSS or Tailwind setup. Keyboard hooks are pure React logic with no style dependencies.

Package mode source scanning

If you install @diffgazer/ui as a runtime npm package instead of copying source files, import the package source hints before the package styles:

Info:

Note: Diffgazer packages are not yet published to npm. Until the first release, pack @diffgazer/ui from the repository and install that tarball.

css
@import "tailwindcss";
@import "@diffgazer/ui/sources.css";
@import "@diffgazer/ui/styles.css";

Theme variables

@diffgazer/ui uses a two-layer CSS variable system:

Layer 1 -- Primitives (--base-*): Raw color values from the Diffgazer monochrome palette. The prefix is product-neutral and the names are role-honest.

Layer 2 -- Semantics: Functional tokens that reference primitives.

The "Semantic tokens (dark)" column lists the dark-theme role edges; light remaps some (e.g. --primary → --base-highlight, --action → --base-accent). See Theme for the per-theme diagram.

PrimitiveValue (dark)Semantic tokens (dark)
--base-bg#0a0a0a--background
--base-fg#e5e5e5--foreground, --primary, --ring
--base-dim#9c9c9c--muted-foreground, --border-strong
--base-info#79b8ff--info
--base-success#7ee787--success
--base-danger#ff7b72--error
--base-warning#d29922--warning
--base-accent#808080--action (light); syntax highlighting
--base-border#606060--border
--base-highlight#ffffff--accent, --action
--base-highlight-foreground#000000--accent-foreground, --action-foreground
--base-selection#333333--secondary, --card, --popover, --input
--base-muted#808080--muted
--base-input-bg#0a0a0aPrimitive available for custom inputs

See Theme for the full variable diagram.

Yarn PnP

Package mode does not require consumers to hard-code a node_modules @source path. Use @import "@diffgazer/ui/sources.css"; so package source hints travel with the published package, then validate your app's CSS tooling in a PnP workspace before relying on package mode.

Dark mode

Dark mode is the default. Light mode activates via [data-theme="light"]:

html
<!-- Dark (default) -->
<html>

<!-- Light -->
<html data-theme="light">

See Dark Mode for theme switching implementation.

Font

@diffgazer/ui uses JetBrains Mono for the terminal aesthetic. Self-host a licensed font file from your app's static assets:

css
@font-face {
  font-family: "JetBrains Mono";
  font-style: normal;
  font-weight: 400 700;
  font-display: swap;
  src: url("/fonts/jetbrains-mono.woff2") format("woff2");
}

This same-origin setup works with a font-src 'self' Content Security Policy. A hosted font provider is an optional external-service tradeoff: allow its font and stylesheet origins in your CSP and account for the added visitor request. See Typography for the complete font contract.

Apply the base styles to your root element:

html
<body class="ui-base">