How to use design-tokens

03Path B — Manual

B1. Consume the published package

RECOMMENDED FOR PRODUCTION

Add to your repo's .npmrc:

@gitconnections:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}

PAT with read:packages scope

Install the package:

pnpm add @gitconnections/design-tokens

In your app/globals.css (Tailwind v4, CSS-first):

@import "tailwindcss";
@import "@gitconnections/design-tokens/css/ocean-blue.css";              /* palette + states + gradients */
@import "@gitconnections/design-tokens/css/base.css";                    /* spacing/shadow/motion/z/icon tokens */
@import "@gitconnections/design-tokens/css/typography/modern-tech.css";  /* font pairing */
@import "@gitconnections/design-tokens/css/animations.css";              /* keyframes + utilities */
@import "@gitconnections/design-tokens/css/recipes.css";                 /* skeleton/spinner/focus */

Dark mode: add class="dark" on <html> — tokens already define .dark.

B2. Vendoring via the CLI

REPO CLONED

Apply a palette to your CSS:

DT=~/dev/repositories/design-tokens
# palette -> globals.css (or --target android / json)
node $DT/packages/tokens/bin/apply-palette.mjs ocean-blue --target web --out app/globals.css

Apply typography + base tokens:

node $DT/packages/tokens/bin/apply-tokens.mjs typography modern-tech --target web --out app/type.css
node $DT/packages/tokens/bin/apply-tokens.mjs base --target web --out app/base.css

Download images for a mood:

# downloads + ATTRIBUTION.md
node $DT/packages/assets/bin/assets.mjs apply ocean-blue --out public/images --roles hero-bg,card,section-bg

Derive a palette from a brand hex (AA-guaranteed):

# AA-guaranteed
node $DT/packages/tokens/bin/palette-from-brand.mjs "#2563eb" --name mybrand --write

Icons: Iconoir is the default set. Either pnpm add iconoir (web) or copy SVGs from $DT/packages/assets/icons/ui/iconoir/. Use currentColor + the --icon-size-* tokens. Phosphor/Solar available as alternatives.

Brand-new repo: Run ops/scripts/bootstrap-repo.sh <new-repo> to seed CONVENTIONS/AGENTS, then follow ops/runbooks/new-repo-bootstrap.md (step 2b applies a palette).

B3. shadcn registry

SHADCN / TAILWIND V4

Install a palette theme straight into your shadcn/Tailwind v4 project with a single command. It writes the palette's light + dark CSS vars directly into your project's globals.css.

Add a palette directly to your project:

# install a palette theme straight into your shadcn/Tailwind v4 project:
npx shadcn@latest add https://design-tokens-kit.faztdeploy.com/r/ocean-blue.json

The command writes the palette's CSS vars (light + dark) into your project's globals.css. No manual copy-paste needed.

Every palette has an item at /r/<palette>.json:

# ocean-blue palette:
https://design-tokens-kit.faztdeploy.com/r/ocean-blue.json

# luxury-gold palette:
https://design-tokens-kit.faztdeploy.com/r/luxury-gold.json

# full index of all palettes:
https://design-tokens-kit.faztdeploy.com/r/registry.json

04Developer use cases

Copy-paste cookbook — real scenarios using the design tokens in Next.js / React / Tailwind v4 and Android Compose.

1. Theme a Next.js app + dark mode toggle

NEXT.JS · APP ROUTER

Wire all token layers into app/globals.css and expose a one-liner dark toggle.

/* app/globals.css */
@import "tailwindcss";
@import "@gitconnections/design-tokens/css/ocean-blue.css";
@import "@gitconnections/design-tokens/css/base.css";
@import "@gitconnections/design-tokens/css/typography/modern-tech.css";
@import "@gitconnections/design-tokens/css/animations.css";
@import "@gitconnections/design-tokens/css/recipes.css";

// components/DarkModeToggle.tsx  (client component)
"use client";
export function DarkModeToggle() {
  return (
    <button
      onClick={() => document.documentElement.classList.toggle("dark")}
      className="focus-ring interactive rounded-[var(--radius)] px-4 py-2
                 bg-[var(--card)] text-[var(--muted-foreground)] text-sm"
    >
      Toggle dark mode
    </button>
  );
}

2. A button from tokens

REACT · TAILWIND V4

Use --primary, --radius, and recipe classes directly in Tailwind utilities.

// components/Button.tsx
export function Button({ children, onClick }: { children: React.ReactNode; onClick?: () => void }) {
  return (
    <button
      onClick={onClick}
      className="interactive focus-ring
                 bg-[var(--primary)] text-[var(--primary-foreground)]
                 rounded-[var(--radius)] px-5 py-2.5 text-sm font-semibold
                 shadow-[var(--shadow-md)] transition-all"
    >
      {children}
    </button>
  );
}

3. Hero with brand gradient

NEXT.JS · CSS VARS

Reference --gradient-hero for full-bleed sections and --gradient-brand for CTA backgrounds.

// app/(landing)/Hero.tsx
export function Hero() {
  return (
    <section
      style={{ background: "var(--gradient-hero)" }}
      className="px-6 py-24 text-center"
    >
      <h1 className="text-5xl font-bold text-[var(--foreground)] mb-4">
        Ship faster.
      </h1>
      <a
        href="/signup"
        style={{ background: "var(--gradient-brand)" }}
        className="interactive focus-ring inline-block mt-6 px-8 py-3
                   rounded-[var(--radius)] text-white font-semibold text-base"
      >
        Get started
      </a>
    </section>
  );
}

4. Loading → skeleton, then card

REACT · RECIPES

Use the .skeleton recipe class while fetching, then swap to a token-styled card.

// components/UserCard.tsx
export function UserCard({ user, loading }: { user?: User; loading: boolean }) {
  if (loading) {
    return (
      <div className="rounded-[var(--radius)] p-5 border border-[var(--border)]
                      bg-[var(--card)] space-y-3">
        <div className="skeleton h-6 w-32 rounded" />
        <div className="skeleton skeleton-text w-full" />
        <div className="skeleton skeleton-text w-3/4" />
      </div>
    );
  }
  return (
    <div className="rounded-[var(--radius)] p-5 border border-[var(--border)] bg-[var(--card)]">
      <h3 className="font-semibold text-[var(--foreground)]">{user?.name}</h3>
      <p className="text-sm text-[var(--muted-foreground)]">{user?.email}</p>
    </div>
  );
}

5. Semantic alerts

REACT · SEMANTIC TOKENS

Drive alert variants from --success, --warning, --info, --destructive — no per-color overrides needed.

// components/Alert.tsx
type Variant = "success" | "warning" | "info" | "destructive";

const VARS: Record<Variant, string> = {
  success:     "--success",
  warning:     "--warning",
  info:        "--info",
  destructive: "--destructive",
};

export function Alert({ variant = "info", children }: { variant?: Variant; children: React.ReactNode }) {
  const token = VARS[variant];
  return (
    <div
      role="alert"
      style={{
        background:   `color-mix(in srgb, var(${token}) 12%, var(--card))`,
        borderColor:  `color-mix(in srgb, var(${token}) 40%, transparent)`,
        color:        `var(${token})`,
      }}
      className="flex gap-3 items-start rounded-[var(--radius)] border px-4 py-3 text-sm"
    >
      {children}
    </div>
  );
}

6. Chart colors from the palette

RECHARTS · CSS VARS

Read --chart-1…5 at runtime or pass them as Recharts fill props.

// lib/chartColors.ts — read token values at runtime
export function getChartColors(): string[] {
  const root = getComputedStyle(document.documentElement);
  return [1, 2, 3, 4, 5].map((n) =>
    root.getPropertyValue(`--chart-${n}`).trim()
  );
}

// components/RevenueChart.tsx (Recharts example)
import { BarChart, Bar, XAxis, YAxis, Tooltip } from "recharts";

export function RevenueChart({ data }: { data: { name: string; value: number }[] }) {
  return (
    <BarChart width={480} height={240} data={data}>
      <XAxis dataKey="name" stroke="var(--muted-foreground)" />
      <YAxis stroke="var(--muted-foreground)" />
      <Tooltip
        contentStyle={{ background: "var(--card)", border: "1px solid var(--border)" }}
      />
      <Bar dataKey="value" fill="var(--chart-1)" radius={[4,4,0,0]} />
    </BarChart>
  );
}

7. Icons (Iconoir) with size tokens

ICONOIR · ACCESSIBILITY

Size icons with --icon-size-md and inherit color via currentColor. Always add aria-label on icon-only buttons.

// components/SendButton.tsx
import { SendDiagonal } from "iconoir-react";

const iconStyle = {
  width:  "var(--icon-size-md)",
  height: "var(--icon-size-md)",
};

// Decorative icon inside a labeled button — aria-hidden on the SVG
export function SendButton({ onClick }: { onClick: () => void }) {
  return (
    <button
      onClick={onClick}
      className="interactive focus-ring flex items-center gap-2
                 bg-[var(--primary)] text-[var(--primary-foreground)]
                 rounded-[var(--radius)] px-4 py-2 text-sm font-medium"
    >
      <SendDiagonal style={iconStyle} aria-hidden="true" />
      Send
    </button>
  );
}

// Icon-only button — aria-label required
export function SendIconButton({ onClick }: { onClick: () => void }) {
  return (
    <button
      onClick={onClick}
      aria-label="Send message"
      className="interactive focus-ring p-2 rounded-[var(--radius)]
                 text-[var(--muted-foreground)] hover:text-[var(--foreground)]"
    >
      <SendDiagonal style={iconStyle} />
    </button>
  );
}

8. Rebrand by swapping ONE import

ZERO-CHANGE REBRAND

Every token is a CSS var — switching the palette import re-themes the entire app without touching component code.

/* app/globals.css — swap this one line to rebrand */

/* Before */
@import "@gitconnections/design-tokens/css/ocean-blue.css";

/* After — luxury gold theme */
@import "@gitconnections/design-tokens/css/luxury-gold.css";

/* Or generate a palette from your own brand color (AA-guaranteed): */
/* node packages/tokens/bin/palette-from-brand.mjs "#6d28d9" --name client --write */
/* then: */
@import "@gitconnections/design-tokens/css/client.css";

Bonus: Android Compose — wrap app in DesignTokensTheme

ANDROID · KOTLIN · COMPOSE

The generated Theme.kt maps every palette token to Material 3's ColorScheme and exposes extras via LocalExtendedColors.

// ui/theme/Theme.kt  (generated — do not edit manually)
@Composable
fun DesignTokensTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    content: @Composable () -> Unit,
) {
    val colorScheme = if (darkTheme) DarkColorScheme else LightColorScheme
    CompositionLocalProvider(LocalExtendedColors provides extendedColors(darkTheme)) {
        MaterialTheme(colorScheme = colorScheme, content = content)
    }
}

// MainActivity.kt
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            DesignTokensTheme {
                // Use MaterialTheme.colorScheme.primary, .surface, etc.
                // Extended tokens: LocalExtendedColors.current.chartColor1
                AppNavHost()
            }
        }
    }
}