Ginga UI

Ginga UI is an UI component library for React. This libarary is using LLM to styling components. Components will design based on the Website contents or user's prompt.

Ginga (/ɡiɴɡa/) is a Japanese word meaning "galaxy".

Recommended Environment

Frameworks

• React 18 or later
• Next.js 13 or later (Recommended to use with App Router)
• React Router v7
• React with Vite

Browsers

• Chrome on macOS, Windows, and Android
• Firefox on macOS and Windows
• Safari on macOS, iOS, and iPadOS
• Edge (chromium) on Windows

Installation

1. Install the package

npm install @ginga-ui/core

2. Import CSS variables on root component

Each component's CSS is loaded automatically when you import the component. On the root component, you only need to import the theme CSS variables. If you are using Next.js App Router, you can import it in the layout.tsx file.

import "@ginga-ui/core/variables.css";

3. Import components

import { Button } from "@ginga-ui/core";

const CustomButton = () => {
  return <Button>Button</Button>;
};

export default CustomButton;

Theme Generation

You can generate with your own theme by using ThemeClient class powered by Vercel AI SDK.

Environment Variables

ThemeClient uses Vercel AI SDK to generate themes. The SDK automatically reads API keys from environment variables:

• OpenAI: OPENAI_API_KEY
• Anthropic: ANTHROPIC_API_KEY
• Google: GOOGLE_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY

Set these environment variables in your .env file or deployment environment. provider: "browser" needs no API key.

Basic Usage

import { ThemeClient } from "@ginga-ui/utils";

const themeClient = new ThemeClient({
  provider: "openai",
});

const CustomButton = () => {
  const handleClick = async () => {
    await themeClient.generateTheme("the image of you thought");
  };

  return <Button onClick={handleClick}>Button</Button>;
};

export default CustomButton;

SSR Mode (Recommended)

If you want to generate theme on server side, you can write like this. Recommended to use with Next.js App Router.

import { Button } from "@ginga-ui/core";
import { ThemeClient } from "@ginga-ui/utils";

export default async function Home() {
  const themeClient = new ThemeClient({
    provider: "openai",
  });

  const { CSSCode } = await themeClient.generateTheme("fairy tale");

  return (
    <div>
      <style>{CSSCode}</style>
      <Button>Button</Button>
    </div>
  );
}

Supported Providers and Models

Specify the provider explicitly with provider. If model is omitted, the default model for that provider is used.

Provider	provider	Default model	Other examples
OpenAI	"openai"	gpt-5.6-luna	gpt-5.6-terra, gpt-5.6-sol
Google	"google"	gemini-3.7-flash	gemini-3.5-flash-lite, gemini-2.5-pro
Anthropic	"anthropic"	claude-haiku-4-5	claude-sonnet-5, claude-opus-5
Gemini Nano	"browser"	-	-

You can use any model supported by the Vercel AI SDK.

Gemini Nano

provider: "browser" runs Gemini Nano, the model shipped with Chrome and Edge. It needs no API key and no network request, but it only works in the browser, so call it from a Client Component instead of a Server Component. model is ignored.

"use client";

import { getBrowserAIAvailability, ThemeClient } from "@ginga-ui/utils";

const generate = async () => {
  const availability = await getBrowserAIAvailability();

  if (availability === "unavailable") {
    return;
  }

  const themeClient = new ThemeClient({ provider: "browser" });

  const { CSSCode } = await themeClient.generateTheme("deep sea", {
    onDownloadProgress: (progress) => console.log(progress),
  });
};

getBrowserAIAvailability() returns "unavailable" / "downloadable" / "downloading" / "available". Fall back to a cloud provider when it is "unavailable". The first run downloads several gigabytes of model data, so report the progress with onDownloadProgress.

Examples

Use the default model of a provider:

const themeClient = new ThemeClient({
  provider: "openai",
});

Use an explicit model:

const themeClient = new ThemeClient({
  provider: "anthropic",
  model: "claude-opus-5",
});

ThemeClient Constructor Options

Name	Description	Default Value	Required
provider	LLM provider to use. "openai" / "google" / "anthropic" / "browser".	-	Yes
model	Model name to use for theme generation.	Default model of the provider	No

Variables

All generated design are delivered by CSS variables. You can use these variables on your own CSS.

Name	Description	Default Value
--color-primary	Accent color	#1677ff
--color-secondary	Main text color	#000000
--color-background	Background color	#ffffff
--width-border	Border width	2px
--size-radius	Border radius	1rem
--font-family	Font family	sans-serif

Additionaly, --color-primary and --color-secondary are generated more variants. This is color scales with --color-background. Here are initial values.

:root {
  --color-primary: #1677ff;
  --color-primary-0: #e3f4ff;
  --color-primary-1: #cce4ff;
  --color-primary-2: #99c5ff;
  --color-primary-3: #63a5ff;
  --color-primary-4: #3689ff;
  --color-primary-5: #1878ff;
  --color-primary-6: #006fff;
  --color-primary-7: #005ee5;
  --color-primary-8: #0054ce;
  --color-primary-9: #0048b6;
  --color-secondary: #000;
  --color-secondary-0: #f8f9fa;
  --color-secondary-1: #f1f3f5;
  --color-secondary-2: #e9ecef;
  --color-secondary-3: #dee2e6;
  --color-secondary-4: #ced4da;
  --color-secondary-5: #adb5bd;
  --color-secondary-6: #868e96;
  --color-secondary-7: #495057;
  --color-secondary-8: #343a40;
  --color-secondary-9: #212529;
  --color-white: #fff;
  --color-black: #000;
  --color-background: #fff;
}

Components

Usage of components can be found in the Storybook.

• Accordion
• Anchor
• Box
• Button
• Card
• Checkbox
• Dialog
• FormControl
• Heading
• Image
• Input
• List
• Paragraph
• Radio
• Select
• Slider
• Switch
• Tab
• Table