macOS-inspired chat UI. Three model variants. Web research. YouTube search.
Customizable themes with dark, pastel, and light modes plus custom hex accents.

Full-featured chat client.

Three Yuuki model variants.
macOS-style window chrome UI.
Conversation history sidebar.
Tavily-powered web research mode.
YouTube video search integration.
Markdown message rendering.
Copy-to-clipboard on all responses.

Deeply customizable.

Dark, pastel, and light themes.
12 preset accent colors.
Native color picker integration.
Custom HEX input field.
Persistent theme preferences.

Optimized for Vercel deployment.

What is Yuuki Chat?

Yuuki Chat is a beautiful, macOS-inspired chat interface for the Yuuki language models. It provides two authentication paths -- users can connect with a Yuuki API key (yk-xxxxxxxx) from yuuki-api.vercel.app or with a Hugging Face token (hf_xxxxxxxx) for direct inference. A built-in demo mode lets users try the app instantly using a server-provided token.

The interface follows a ChatGPT-style conversational layout wrapped in macOS window chrome with traffic light buttons, a conversation sidebar, model switching, and two special modes: Research (powered by Tavily) for web search with sourced answers, and YouTube for video search via the YouTube Data API v3.

Built with Next.js 16, Tailwind CSS v4, and TypeScript. Fully optimized for Vercel deployment.

Features

Dual Authentication

Two large buttons on the token screen: Yuuki API (for yk- tokens from yuuki-api.vercel.app) and Hugging Face (for hf_ tokens from huggingface.co). A small "Use demo" button uses the server's HF_DEMO_TOKEN for instant access. Yuuki API tokens route through the OpenAI-compatible endpoint at yuuki-api.vercel.app, while HF tokens call the Inference API directly.

macOS Window Chrome

Reusable MacOSWindow component with red/yellow/green traffic light dots and a monospace title bar. Used for the token screen, theme settings panel, and visual consistency throughout. Smooth entry animations with backdrop blur effects.

Three Model Variants

Dropdown selector to switch between Yuuki Best (flagship), Yuuki 3.7 (balanced), and Yuuki v0.1 (fast). Each model maps to its HuggingFace endpoint or Yuuki API model ID. Selection persists across messages within a conversation.

Conversation Management

Sidebar with conversation history, auto-generated titles from the first message, new chat creation, and per-conversation deletion. Conversations are managed client-side with React state. The sidebar collapses on mobile with an overlay.

Web Research Mode

Toggle to enable Tavily-powered web research. When active, user queries are sent to the Tavily Search API with advanced depth and answer generation. Results include a synthesized answer plus source cards with titles, URLs, and content snippets. Sources are clickable links.

YouTube Search Mode

Toggle to search YouTube via the Data API v3. Returns video cards with thumbnails, titles, channel names, and direct links. Thumbnails are rendered inline in the chat. Mutually exclusive with Research mode.

Theme Customization

Full theme panel with three appearance modes: Dark (near-black), Pastel (warm cream tones), and Light (clean white). 12 preset accent colors for message bubbles and the send button. A native <input type="color"> picker and a custom HEX text input for precise color selection. All preferences saved to localStorage.

Responsive Design

Mobile-first layout. Sidebar collapses to an overlay on small screens. Input area auto-resizes. Research/YouTube toggle labels hide on mobile, showing only icons. Glass morphism effects on the top bar and input area.

Authentication Flow

                        Token Screen
                             |
              +--------------+--------------+
              |              |              |
         Yuuki API     Hugging Face      Demo
         (yk-xxxx)     (hf_xxxx)       (server)
              |              |              |
              v              v              v
    yuuki-api.vercel.app   HuggingFace   HF_DEMO_TOKEN
      /api/chat            Inference API  (server-side)
    (OpenAI-compatible)    (direct)       via HF API
              |              |              |
              +--------------+--------------+
                             |
                        Chat Response

Method	Token Format	Backend Route
Yuuki API	`yk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`	`POST yuuki-api.vercel.app/api/chat` (OpenAI-compatible)
Hugging Face	`hf_xxxxxxxxxxxxxxxxxxxxxxxx`	`POST api-inference.huggingface.co/models/YuuKi-OS/*`
Demo	None (server-managed)	Uses `HF_DEMO_TOKEN` env var server-side

Models

Model ID	Name	HuggingFace Endpoint	Description
`yuuki-best`	Yuuki Best	`YuuKi-OS/Yuuki-best`	Flagship model with best overall quality
`yuuki-3.7`	Yuuki 3.7	`YuuKi-OS/Yuuki-3.7`	Balanced model for speed and quality
`yuuki-v0.1`	Yuuki v0.1	`YuuKi-OS/Yuuki-v0.1`	Lightweight first generation model

Design System

Color Themes

Theme	Background	Foreground	Card	Accent
Dark	`#09090b`	`#fafafa`	`#111113`	User-selected
Pastel	`#fdf6f0`	`#2d2420`	`#fff9f5`	User-selected
Light	`#fafafa`	`#0a0a0a`	`#ffffff`	User-selected

Typography

Role	Font	Weight
Headings	Geist	Bold (700)
Body text	Geist	Regular (400)
Code / Labels	Geist Mono	Regular (400)

Design Principles

macOS window chrome. Traffic light dots, monospace title bars, bordered panels. Consistent visual language across all modal surfaces.
Three appearance modes. Dark (default), Pastel (warm), Light (clean). Each with carefully tuned background, foreground, card, muted, and border tokens.
User-controlled accent. 12 preset colors plus a native color picker and HEX input. Accent color applies to user message bubbles and the send button.
Glass morphism. Top bar and input area use backdrop blur with semi-transparent backgrounds for depth.
Mobile-first responsive. Flexbox layouts, collapsible sidebar, auto-resizing textarea, responsive toggle labels.

Tech Stack

Technology	Version	Purpose
Next.js	16	React framework, App Router, API Routes
React	19	UI component library
TypeScript	5.x	Type safety
Tailwind CSS	4	Utility-first styling with `@theme inline` tokens
shadcn/ui	Latest	Base component primitives
Lucide React	Latest	Icon library
Geist	Latest	Font family (sans + mono)
SWR	Latest	Client-side data fetching
Sonner	Latest	Toast notifications
Vercel Analytics	Latest	Page view tracking

External Services

Service	Method	Purpose
Yuuki API	REST (OpenAI-compatible)	Chat completions via `yk-` tokens
HuggingFace Inference API	REST	Direct model inference via `hf_` tokens
Tavily Search API	REST	Web research with sourced answers
YouTube Data API v3	REST	Video search results

Architecture

                           User (Browser)
                                |
                    Token Screen (3 options)
                                |
                        +-------+-------+
                        |               |
                   Authenticated     Demo Mode
                   (yk- or hf_)    (server token)
                        |               |
                        v               v
  +-------------------------------------------------------------+
  |                    Yuuki Chat (Next.js 16)                  |
  |                                                             |
  |   app/                                                      |
  |     layout.tsx           Root layout, fonts, metadata        |
  |     globals.css          Tailwind v4, 3 theme modes          |
  |     page.tsx             Auth gate -> TokenScreen / Chat     |
  |                                                             |
  |   app/api/                                                  |
  |     chat/route.ts        Routes to YuukiAPI or HF           |
  |     research/route.ts    Tavily web search                  |
  |     youtube/route.ts     YouTube Data API v3                |
  |                                                             |
  |   components/                                               |
  |     token-screen.tsx     Auth with 3 options                |
  |     chat-window.tsx      Main chat layout + sidebar         |
  |     chat-message.tsx     Message bubbles + research/yt      |
  |     model-selector.tsx   Model dropdown                     |
  |     theme-panel.tsx      Theme customization modal          |
  |     macos-window.tsx     Reusable window chrome             |
  |                                                             |
  |   lib/                                                      |
  |     auth-context.tsx     Token & source state               |
  |     theme-context.tsx    Theme mode & accent color          |
  +-------------------+-------------------+---------------------+
                      |                   |
        +-------------+--+     +----------+---------+
        |  Yuuki API     |     |  HuggingFace       |
        |  vercel.app    |     |  Inference API     |
        |                |     |                    |
        |  yk- tokens    |     |  hf_ tokens        |
        |  OpenAI compat |     |  Direct inference   |
        +----------------+     +--------------------+
                                        |
                         +--------------+--------------+
                         |                             |
                   +-----+------+            +---------+--------+
                   |  Tavily    |            |  YouTube         |
                   |  Search    |            |  Data API v3     |
                   +------------+            +------------------+

Source Layout

yuuki-chat/
    app/
        layout.tsx                  # root layout, Geist fonts, metadata
        globals.css                 # Tailwind v4, 3 theme modes, glass effects
        page.tsx                    # auth gate (token screen vs chat)
        api/
            chat/route.ts           # routes to Yuuki API or HuggingFace
            research/route.ts       # Tavily web search
            youtube/route.ts        # YouTube Data API v3 search
    components/
        token-screen.tsx            # 3-option auth screen
        chat-window.tsx             # main chat UI with sidebar
        chat-message.tsx            # message bubbles with research/yt
        model-selector.tsx          # model dropdown
        theme-panel.tsx             # theme customization modal
        macos-window.tsx            # reusable macOS window chrome
    lib/
        auth-context.tsx            # token & source state management
        theme-context.tsx           # theme mode & accent color state
        utils.ts                    # cn utility

Installation

Prerequisites

Node.js 18 or later
pnpm (recommended) or npm

Clone and Run

git clone https://github.com/YuuKi-OS/yuuki-chat
cd yuuki-chat
pnpm install
pnpm dev

The app will be available at http://localhost:3000.

Build for Production

pnpm build
pnpm start

Deploy to Vercel

The recommended deployment method. Connect the repo to Vercel and configure the environment variables.

# Or deploy manually with the Vercel CLI
npx vercel

Environment Variables

Configure these in your Vercel project settings under Settings > Environment Variables:

Variable	Required	Description
`HF_DEMO_TOKEN`	Yes	Hugging Face API token used for the "Use demo" button. Get one at huggingface.co/settings/tokens
`TAVILY_API_KEY`	Yes	Tavily API key for the Research mode. Get one at tavily.com
`YOUTUBE_API_KEY`	Yes	YouTube Data API v3 key for YouTube search. Get one at console.cloud.google.com

Note: User-provided tokens (yk- and hf_) are sent from the client per-request and are never stored server-side. Only the demo token lives as an environment variable.

Configuration

Metadata

SEO metadata is configured in app/layout.tsx:

export const metadata: Metadata = {
  title: "Yuuki Chat - AI Chat Interface for Yuuki Models",
  description: "A beautiful macOS-inspired AI chat interface powered by Yuuki language models...",
};

Theme Tokens

All design tokens are defined in app/globals.css using Tailwind v4's @theme inline directive. Three complete theme sets (:root, .dark, .pastel) with full token coverage.

Models

Model configuration is defined in app/api/chat/route.ts:

const HF_MODELS = {
  "yuuki-v0.1": "https://api-inference.huggingface.co/models/YuuKi-OS/Yuuki-v0.1",
  "yuuki-3.7": "https://api-inference.huggingface.co/models/YuuKi-OS/Yuuki-3.7",
  "yuuki-best": "https://api-inference.huggingface.co/models/YuuKi-OS/Yuuki-best",
};

Project	Description
Yuuki API	Inference API platform with key management and usage tracking
Yuuki Web	Official landing page for the Yuuki project
yuy	CLI for downloading, managing, and running Yuuki models
yuy-chat	TUI chat interface for local AI conversations
Yuuki-best	Best checkpoint model weights
Yuuki Space	Web-based interactive demo

License

MIT License

Copyright (c) 2026 Yuuki Project

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Built with patience, a phone, and zero budget.

README.md

AI Chat Interface for Yuuki Models

What is Yuuki Chat?

Features

Dual Authentication

macOS Window Chrome

Three Model Variants

Conversation Management

Web Research Mode

YouTube Search Mode

Theme Customization

Responsive Design

Authentication Flow

Models

Design System

Color Themes

Typography

Design Principles

Tech Stack

External Services

Architecture

Source Layout

Installation

Prerequisites

Clone and Run

Build for Production

Deploy to Vercel

Environment Variables

Configuration

Metadata

Theme Tokens

Models

Related Projects

Links

License