The GridCN Documentation

repository·main·Indexed 18 days ago

https://github.com/educlopez/thegridcn-ui

A Tron: Ares inspired design system for shadcn/ui featuring neon, glass-HUD components, Three.js effects, and six Greek-god themed color schemes (ares, tron, clu, athena, aphrodite, poseidon). It includes a customizable component registry, design tokens for Tailwind CSS, and specialized UI elements like TronAccordion and AgentAvatar, as well as a LightCycle game engine.

Tokens
31.1K
Snippets
102
Records
119
Agent score
63%

What's inside The GridCN

  1. Use the Route Handler fallback for registry files

    main
    If a component JSON file is missing from public/r/, the route handler located at src/app/r/[name]/route.ts acts as a fallback. It dynamically generates the requested component JSON from the main registry.json file. This ensures the registry remains functional even if registry:build was not executed, though static files are preferred for performance.
  2. Use the ThemeProvider and useTheme hook

    main

    The GridCN uses a ThemeProvider to manage themes via data-theme attributes on the <html> element. This allows components using CSS variables to react automatically to theme changes.

    Available themes: ares, tron, clu, athena, aphrodite, poseidon.

    To use them, wrap your application root with ThemeProvider and use the useTheme hook in client components to switch themes dynamically.

    // app/layout.tsx
    import { ThemeProvider } from "@/components/theme";
    
    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en" suppressHydrationWarning>
          <body className="...">
            <ThemeProvider defaultTheme="ares">{children}</ThemeProvider>
          </body>
        </html>
      );
    }
    // any client component
    "use client";
    import { useTheme } from "@/components/theme";
    
    export function Toggle() {
      const { theme, setTheme } = useTheme();
      return (
        <button onClick={() => setTheme(theme === "ares" ? "tron" : "ares")}>
          {theme}
        </button>
      );
    }
  3. Add components using the namespace

    main

    Once the namespace is registered, use npx shadcn@latest add followed by the component name.

    Base shadcn components (re-exported):

    npx shadcn@latest add @thegridcn/button

    Tron-flavored components:

    npx shadcn@latest add @thegridcn/data-card
    npx shadcn@latest add @thegridcn/radar
    npx shadcn@latest add @thegridcn/hud

    3D components (requires three and @react-three/fiber):

    npx shadcn@latest add @thegridcn/grid

    Install multiple components at once:

    npx shadcn@latest add @thegridcn/button @thegridcn/data-card @thegridcn/hud
    npx shadcn@latest add @thegridcn/button @thegridcn/data-card @thegridcn/hud
  4. Build the production application and registry

    main

    To ensure all registry files are generated and included in your production bundle, use the build script. The build process is configured to run registry:build before next build to guarantee that JSON files are available at /r/[name].json URLs immediately after deployment.

    pnpm build
  5. Install The GridCN via the shadcn registry

    main

    The recommended way to use The GridCN is by registering its namespace in your components.json file. This allows you to use the npx shadcn add command to install components directly into your project.

    1. Add the @thegridcn registry to your components.json:

    2. Install components using their short names (e.g., @thegridcn/button). You can install single components or multiple components at once.

    {
      "registries": {
        "@thegridcn": "https://thegridcn.com/r/{name}.json"
      }
    }
    npx shadcn@latest add @thegridcn/button
    npx shadcn@latest add @thegridcn/data-card
    npx shadcn@latest add @thegridcn/theme-ares
    
    # Install several at once
    npx shadcn@latest add @thegridcn/button @thegridcn/hud @thegridcn/radar
  6. Install a GridCN theme

    main

    Themes are installed as registry:style items. They write a single CSS file to src/styles/thegridcn-theme.css containing oklch() variables.

    Available themes: theme-ares, theme-tron, theme-clu, theme-athena, theme-aphrodite, theme-poseidon.

    Installation:

    npx shadcn@latest add @thegridcn/theme-ares

    Usage: Import the generated theme file into your global CSS file:

    /* src/app/globals.css */
    @import "tailwindcss";
    @import "../styles/thegridcn-theme.css";
    npx shadcn@latest add @thegridcn/theme-ares
  7. Export and use design tokens

    main

    You can export theme tokens as CSS or JSON files. If you are developing locally, run pnpm tokens:build to regenerate the files in public/tokens/.

    Using CSS tokens

    You can import a theme's CSS directly into your global CSS file:

    @import "https://thegridcn.com/tokens/ares.css";

    Using JSON tokens in Tailwind

    You can import the generated JSON into your tailwind.config.ts to map specific CSS variables to Tailwind theme colors.

    /* your-app/app/globals.css */
    @import "https://thegridcn.com/tokens/ares.css";
    // tailwind.config.ts
    import ares from "./tokens/ares.json" with { type: "json" };
    
    export default {
      theme: {
        extend: {
          colors: {
            primary: ares.vars["--primary"],
            // ... map the rest
          },
        },
      },
    };
  8. Configure the Light Cycle game page layout

    main

    The game is intended to be hosted at the /game route (src/app/game/page.tsx). The layout should follow these design specifications:

    • Visual Style: Full viewport, dark background, no scrolling.
    • Structure: Use a HUDFrame to wrap the canvas.
    • Components:
      • UplinkHeader: Displays "LIGHT CYCLE ARENA" on the left and the current win count on the right.
      • DerezTimer: Displays the elapsed time of the current round.
      • Controls Hint: A text hint below the canvas: "ARROW KEYS / WASD TO STEER".
    • Canvas Constraints: The canvas should be centered with a square aspect ratio and a maximum size of approximately 600-700px.
  9. Use raw theme tokens for multiple themes

    main

    If you need to support multiple themes side-by-side using data-theme switching, import the raw CSS token files instead of the full theme component. This allows you to cascade CSS variables locally.

    Available theme names: tron, ares, clu, athena, aphrodite, poseidon.

    Importing via URL:

    /* drop into your app's globals.css */
    @import "https://thegridcn.com/tokens/ares.css";

    Switching themes in JSX:

    <div data-theme="tron">
      {/* Components inside here will use Tron tokens */}
    </div>
    @import "https://thegridcn.com/tokens/ares.css";
  10. Add components via full URL

    main

    If you do not want to modify your components.json, you can install components directly using their full JSON manifest URL:

    npx shadcn@latest add https://thegridcn.com/r/button.json
    npx shadcn@latest add https://thegridcn.com/r/data-card.json

    When using this method, the CLI will fetch the manifest, resolve npm dependencies, and write the TSX files to your component directories (typically src/components/ui/ for base components or src/components/thegridcn/ for Tron components).

    npx shadcn@latest add https://thegridcn.com/r/button.json
  11. Install components from the registry

    main

    You can install components from your registry using the shadcn CLI in several ways:

    1. Using individual component URLs (Local or Remote):

    npx shadcn@latest add http://localhost:3000/r/button.json

    2. Using the main registry file:

    npx shadcn@latest add --registry ./registry.json button

    3. From a published public registry:

    npx shadcn@latest add https://your-domain.com/r/button.json
  12. Serve registry files as static assets

    main

    The recommended way to serve component registry files in production is as static assets. Running pnpm registry:build generates individual JSON files in the public/r/ directory (e.g., public/r/button.json).

    Next.js automatically serves these files at https://your-domain.com/r/[component-name].json. Using static files ensures they are included in the production build, served quickly, and can be cached by a CDN.

    pnpm registry:build