@brite-nites/create-sandbox

CLI that scaffolds the BriteBase design-system sandbox + DS explorer into a Next.js App Router + Tailwind v4 project. Used by Phase 5 of the cross-repo design-system migration.

Usage

# In the target repo's root
npx @brite-nites/create-sandbox

# Or to preview without writing
npx @brite-nites/create-sandbox --dry-run

# Targeting a different repo
npx @brite-nites/create-sandbox --target ../other-repo

What it does

1. Detects the target — verifies Next.js App Router (src/app/ or app/) and Tailwind v4 (refuses v3 with a migration link).

2. Copies the thin sandbox mount — the chrome, nav, tools, and DS explorer all ship in the package now, so this is just 4 small files:

   • src/app/sandbox/layout.tsx — mounts the Kit's SandboxShell from one config
   • src/app/sandbox/page.tsx — a starter landing page (replace with your own)
   • src/app/sandbox/design-system/page.tsx — renders the Kit's DesignSystemExplorer
   • src/components/sandbox/sandbox.config.tsx — the one SandboxConfig that drives the shell

3. Patches globals.css — appends the two required @imports (after any existing @import "tailwindcss" lines):

   @import "@brite-nites/design-system/styles";
   @import "@brite-nites/design-system/fonts/magda";

4. Adds @brite-nites/design-system to dependencies in package.json if missing.

What it doesn't do

• Geist Sans/Mono setup — that has to live in the consumer's root layout via next/font/google so Next.js can apply build-time subsetting. See @brite-nites/design-system README, "Fonts".
• npm install — the CLI updates package.json; run the install yourself afterwards.
• Conflict resolution — by default existing files are skipped (warning printed). Pass --force to overwrite.

Options

| Flag | Default | Effect | |---|---|---| | --target <path> | cwd | Target project root | | --dry-run, -n | off | Print plan, don't write | | --force, -f | off | Overwrite existing files | | --help, -h | — | Show usage |

After scaffolding

npm install            # or pnpm/yarn
npm run dev
# open http://localhost:3000/sandbox/design-system

Recommended next.config tweak. Next's dev-tools indicator and the sandbox's sidebar-footer theme toggle both default to the bottom-left corner, where they overlap and the indicator swallows clicks on the toggle. Move the indicator so the toggle stays clickable (dev-mode only — no production or consumer impact):

const nextConfig: NextConfig = {
  // …your existing config…
  devIndicators: { position: "bottom-right" },
};

Customizing the sandbox

The CLI ships a minimal sandbox — the turnkey Design System explorer + Sandbox Tools. Add your own playground groups in the nav of src/components/sandbox/sandbox.config.tsx:

export const sandboxConfig: SandboxConfig = {
  storageNamespace: "sandbox",
  designSystem: true,
  tools: true,
  brandName: "Sandbox",
  nav: [
    {
      id: "dashboards",
      label: "Dashboards",
      items: [
        { id: "dashboards/overview", label: "Overview", href: "/sandbox/dashboards", icon: <SquaresFour /> },
      ],
    },
  ],
};

And create the corresponding routes at src/app/sandbox/<group>/<page>.tsx. To rebrand, set brandName and override --brand-primary (+ --brand-accent) in globals.css after the design-system import — the disc, buttons, and ramp all recolor from that one value.

Requirements

• Next.js 15.5+ or 16 with App Router
• Tailwind v4 (not v3)
• React 19
• Node 20+

If you're on an older stack, the CLI will refuse to run with a clear error.