Getting Started

Prerequisites

These steps are for Game One developers setting up a brand new consumer project against the hosted docs site and hosted registry, not for local development of this repository.

• A Next.js project with Tailwind CSS v4.
• Node.js >=20.9.0.
• Access to GAMEONE_REGISTRY_TOKEN for the hosted registry.
• Access to FONTAWESOME_NPM_TOKEN for the private Font Awesome npm registry.

1. Initialize shadcn in your app

If your project does not already have a components.json file, run the shadcn initializer first:

npx shadcn@latest init

Follow the prompts for your project paths and aliases. The remaining steps assume the initializer has already created your base components.json file.

2. Configure Font Awesome npm access

The Game One icon kit is hosted on Font Awesome's private npm registry. Create a .npmrc file in your project root:

@awesome.me:registry=https://npm.fontawesome.com/
@fortawesome:registry=https://npm.fontawesome.com/
//npm.fontawesome.com/:_authToken=${FONTAWESOME_NPM_TOKEN}

Set the FONTAWESOME_NPM_TOKEN environment variable in your local shell and in any CI environment that installs dependencies. The token is available in the Game One shared credentials vault.

3. Add the Game One registry

Open your project's components.json and merge in the @gameone registry. Do not replace the rest of your file:

{
  "registries": {
    "@gameone": {
      "url": "https://blocks.game-one.io/r/{name}.json",
      "headers": {
        "Authorization": "Bearer ${GAMEONE_REGISTRY_TOKEN}"
      }
    }
  }
}

Then make the registry token available anywhere you run the shadcn CLI:

export GAMEONE_REGISTRY_TOKEN=your_token_here

Add the same environment variable in CI if you install registry items during builds or automated setup scripts.

4. Install the theme tokens

The theme provides all CSS custom properties (colors, shadows, radius, slant geometry) and dark mode variants used by every component.

npx shadcn@latest add @gameone/gameone-theme

This writes styles/theme.css to your project. Import it in your app CSS after @import "tailwindcss":

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

5. Install shared utilities

The cn() utility (powered by clsx + tailwind-merge) is a dependency of almost every component.

npx shadcn@latest add @gameone/gameone-utils

This installs clsx and tailwind-merge as npm dependencies, and writes the lib/utils.ts file:

import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

6. Install the Font Awesome kit

Many Game One components use Font Awesome icons internally (checkboxes, selects, sidebar, dialogs, etc.). Install the kit registry item:

npx shadcn@latest add @gameone/fontawesome-kit

The registry item declares the required npm dependencies, so a normal install should add the Font Awesome packages automatically and write a re-export file:

export { fass, fak, fab } from "@awesome.me/kit-671299b1d5/icons"

If your package manager does not install those dependencies automatically, run this fallback command manually:

npm install --save @awesome.me/kit-671299b1d5@latest @fortawesome/fontawesome-svg-core @fortawesome/react-fontawesome

Then configure the Font Awesome CSS in your root layout. This is required to prevent a flash of unstyled icons:

import "@fortawesome/fontawesome-svg-core/styles.css"
import { config } from "@fortawesome/fontawesome-svg-core"
config.autoAddCss = false

7. Install your first component

You're ready to start adding components. The CLI automatically resolves registry dependencies, so any required utilities, hooks, or sibling components are installed alongside.

npx shadcn@latest add @gameone/button

Then use it in your app:

import { Button } from "@/components/ui/button"

export function MyPage() {
  return (
    <div className="flex gap-3">
      <Button>Default</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="slant">Slant</Button>
    </div>
  )
}

8. Install brand guidelines for AI agents

The registry includes a Cursor workspace rule that encodes Game One brand standards — colors, typography, geometry, icons, voice, and logo rules. When installed, any AI agent working on your frontend code will automatically follow the brand guidelines.

npx shadcn@latest add @gameone/brand-guidelines

This installs a .cursor/rules/gameone-brand.mdc file in your project. The rule activates automatically when agents edit .tsx, .ts, and .css files. It covers:

• Color tokens — use semantic CSS variables and Tailwind classes, never hardcoded hex
• Typography — Saira font family, display heading utilities, normal-case body text
• Geometry— sharp corners (radius 0), 69.5° slant angles, no perfect circles
• Icons — Font Awesome Sharp Solid defaults, blue for interactive only, grey for decorative
• Logo integrity — one color only, never outlined or textured, arrow always up-right
• Voice & tone — direct, confident, supportive, never speak down

For the full brand reference, and to download the Saira font, see the Brand Guidelines page.

Quick reference

Use this as the full one-time setup checklist for a new project:

# 0. Initialize shadcn once per project
npx shadcn@latest init

# 1. Export the required tokens in your shell
export FONTAWESOME_NPM_TOKEN=your_token_here
export GAMEONE_REGISTRY_TOKEN=your_token_here

# 2. Add the @gameone registry block to components.json

# 3. Theme tokens (CSS variables, dark mode)
npx shadcn@latest add @gameone/gameone-theme

# 4. Shared utilities (cn helper)
npx shadcn@latest add @gameone/gameone-utils

# 5. Font Awesome icon kit
npx shadcn@latest add @gameone/fontawesome-kit

# 6. If the kit dependencies were not auto-installed
npm install --save @awesome.me/kit-671299b1d5@latest @fortawesome/fontawesome-svg-core @fortawesome/react-fontawesome

# 7. Components — install any you need
npx shadcn@latest add @gameone/button
npx shadcn@latest add @gameone/card
npx shadcn@latest add @gameone/dialog

# 8. Brand guidelines for AI agents (Cursor rule)
npx shadcn@latest add @gameone/brand-guidelines

# 9. Add the required CSS/theme imports shown above
# ... then start installing the rest of the registry