Project: [Track] - theme-ai-generator

[serguei9090]

Track

Creative Apps (GitHub Copilot)

Project Name

theme-ai-generator

GitHub Username

@serguei9090
@crhdez

Repository URL

https://github.com/serguei9090/theme-ai-generator

Project Description

Creative Theme AI Generator is an agentic productivity suite designed for designers and developers to accelerate the bridge between "mood" and "functional UI." It transforms abstract stylistic requests into actionable, accessibility-compliant theme systems through an intelligent, multi-layered reasoning loop.

At the heart of the application is a dual-brain orchestrator. The system utilizes the GitHub Copilot SDK as a "Creative Director" to reason about user intent, proposing three distinct stylistic directions (e.g., "Clean Modern," "Vibrant Hub," "Elegant Dark") before any code is generated. This "Discovery" phase ensures the AI understands the project's soul before committing to hex codes. Once a direction is chosen, the system delegates precise execution to a local Model Context Protocol (MCP) server.

This MCP server features a robust routing engine that interfaces with Gemini (via official SDK), OpenAI, and Ollama, ensuring reliable generation with deterministic local fallbacks. To bridge the gap between abstract swatches and real-word usage, the application provides high-fidelity, interactive multi-surface previews. Users can instantly see their palette applied to a responsive Website, refined Web App, Desktop Workspace, and Mobile interface.

The system prioritizes Technical Integrity over simple text generation. Every palette passes through a self-correction loop that calculates WCAG contrast ratios and automatically adjusts text colors to ensure the design is inclusive and readable. By combining creative reasoning with rigorous engineering standards, Theme AI Generator turns "vibrant purple" from an idea into a functional design system.

Demo Video or Screenshots

Demo:
https://youtu.be/73nXIDBiW3k

Photos:
https://github.com/serguei9090/theme-ai-generator/tree/main/docs/screenshots

Primary Programming Language

TypeScript/JavaScript

Key Technologies Used

Project Overview & Technology Stack

Project Description (Creative Apps Track)

Creative Theme AI Generator is an agentic productivity suite designed for designers and developers to bridge the gap between "mood" and "functional UI." It transforms abstract stylistic requests into actionable, accessibility-compliant theme systems through an intelligent, multi-layered reasoning loop.

At the heart of the application is a dual-brain orchestrator. The system utilizes the GitHub Copilot SDK as a "Creative Director" to reason about user intent, proposing three distinct stylistic directions (e.g., "Clean Modern," "Vibrant Hub," "Elegant Dark") before any code is generated. This "Discovery" phase ensures the AI understands the project's soul before committing to hex codes. Once a direction is chosen, the system delegates precise execution to a local Model Context Protocol (MCP) server.

This MCP server features a robust routing engine that interfaces with Gemini (via official SDK), Ollama, and OpenAI, ensuring reliable generation with deterministic local fallbacks. To bridge the gap between abstract swatches and real-word usage, the application provides high-fidelity, interactive multi-surface previews. Users can instantly see their palette applied to a responsive Website, refined Web App, Desktop Workspace, and Mobile interface.

The system prioritizes Technical Integrity over simple text generation. Every palette passes through a self-correction loop that calculates WCAG contrast ratios and automatically adjusts text colors to ensure the design is inclusive and readable. By combining creative reasoning with rigorous engineering standards, Theme AI Generator turns "vibrant purple" from an idea into a functional design system.

---

Technology Stack & Frameworks

The Theme AI Generator is built on a modern, high-performance monorepo architecture designed for reliability and seamless AI orchestration.

Core Runtime & Engineering

• Bun: Serves as the primary package manager, high-speed test runner, and monorepo orchestrator.
• TypeScript: Used strictly across all packages to ensure type safety and consistent data contracts between the AI and the UI.
• Next.js 15 (App Router): Powers the frontend application with Server Components for performance and API Routes for the backend proxy.
• Biome: Replaces traditional ESLint/Prettier for extreme performance in linting and formatting.
• Docker: Multi-stage builds for optimized containerized deployment.

AI & Orchestration

• GitHub Copilot SDK: Integrated as the "Creative Director" of the system to handle high-level reasoning, intent discovery, and stylistic drafting.
• Model Context Protocol (MCP): Utilizes the @modelcontextprotocol/sdk to expose color generation tools natively to AI assistants and IDEs.
• @google/genai: Official SDK for high-performance integration with Gemini 1.5 Flash and Pro models.
• Ollama: Enabled for local-first, privacy-focused AI generation.
• OpenAI SDK: Compatibility for GPT-4o and GPT-4o-mini models.

UI & Design Systems

• Tailwind CSS 4: Utilized for the styling engine, providing high-performance utility classes and fluid design.
• Radix UI: Accessible, unstyled primitives for complex components like Dialogs, Popovers, and Tabs.
• Lucide React: Modern, consistent iconography across the platform.
• React 19: Leverages the latest React features for efficient state management and concurrent rendering.
• Shadcn UI Patterns: Reusable, modular component architecture.

Quality & Testing

• Bun Test: Native, blazing-fast unit testing runner.
• Zod: Schema-driven validation for AI-generated JSON outputs.
• Lefthook: Orchestrates pre-commit hooks to enforce quality gates (linting and type-checking).

Submission Type

Team (2-4 members)

Team Members

@serguei9090 Full-Stack
@crhdez Tester, Data manager

Submission Requirements

• My project meets the track-specific challenge requirements
• My repository includes a comprehensive README.md with setup instructions
• My code does not contain hardcoded API keys or secrets
• I have included demo materials (video or screenshots)
• My project is my own work with proper attribution for any third-party code
• I agree to the Code of Conduct
• I have read and agree to the Disclaimer
• My submission does NOT contain any confidential, proprietary, or sensitive information
• I confirm I have the rights to submit this content and grant the necessary licenses

Quick Setup Summary

How to Run (Quick Instructions)

Evaluators can refer to the README.md for full details, but for a fast start:

Option A: Local One-Liner (Requires Bun)

bun install && cp .env.example.mini .env && cp .env apps/web/.env.local && bun run dev

UI available at http://localhost:3000

Option B: Docker Environment

# Build the image
docker build -t theme-ai-web .

# Run the container (using mini env presets)
docker run -p 3000:3000 --env-file .env.example.mini theme-ai-web

Option C: Native MCP Server

If you want to test the tool logic directly in an AI IDE (like Claude Desktop or VS Code):

1. bun install
2. bun run mcp:dev (Starts server on port 41234)

Technical Highlights

Technical Highlights & Innovations

In the implementation of Theme AI Generator, we focused on building a resilient, agentic system that prioritizes professional utility over simple prompt-and-response patterns.

Dual-Brain Orchestration (Creative Reasoning vs. Precise Execution)

We are most proud of our "Creative Director" architecture. Instead of asking one model to "pick colors," we split the task:

• The Director (Copilot SDK): Reasons about the user's high-level intent and drafts creative directions.
• The Engine (MCP & Core Service): Executes the precisely formatted extraction of hex codes, validation, and normalization.
  This separation allows for high-quality conversational discovery without losing the strict data contract required by a design system.

The Accessibility Self-Correction Loop

To solve the common problem of AI models proposing "pretty" but unreadable palettes, we implemented an automated Technical Integrity Gate.

• Decision: Every generated palette is programmatically scanned for WCAG 2.1 contrast ratios (e.g., text vs background).
• Action: If a palette fails, the system automatically recalibrates the offending colors toward the nearest accessible value while preserving the brand hue. The user is then notified that "Readability adjustments were applied."

Resilience via Multi-Provider Fallback Routing

We built a provider-agnostic core logic that handles the "messiness" of modern LLM APIs.

• Strategy: Current execution routes through Ollama (local), Gemini (SDK), OpenAI, and the Copilot SDK.
• Decision: We implemented a deterministic fallback mechanism. If an upstream provider is rate-limited or unavailable, the system transparently shifts to a local generator, ensuring creative flow is never interrupted.

Monorepo Shared Core Architecture

We chose a monorepo structure to solve the "duplicated logic" problem.

• Decision: The @theme-ai/core package contains the entire "brain" (prompts, validation, accessibility math). This single source of truth is shared between the Next.js Web App (for the UI) and the Native MCP Server (for IDE integration).
• Result: You get the same intelligent behavior whether you are chatting in a browser or asking Copilot in VS Code.

High-Fidelity Multi-Surface Previews

Moving beyond isolated color swatches, we developed a preview system that renders palettes into complex UI patterns (Mobile, Analytics, Desktop, Content). This allows users to evaluate color "vibe" and "usability" in context, which is the true test of any design system.

Challenges & Learnings

Challenges & Learnings

Building the Theme AI Generator involved several complex engineering hurdles, particularly around secure authentication, agentic flow, and maintaining a strict design system contract.

1. GitHub Auth & Copilot SDK Integration

One of our first major challenges was implementing the GitHub OAuth flow to work seamlessly with the Copilot SDK.

• The Struggle: We had to ensure that the user could authenticate securely via GitHub, and that these credentials would then be correctly passed to the Copilot Client to enable the "Creative Director" features.
• The Learning: We learned the importance of robust token management and session handling in a Next.js environment. By properly isolating the authentication logic, we were able to support both the official GitHub OAuth flow and manual API key overrides for maximum flexibility.

2. Solving the Orchestration Logic (The "Dual-Brain" Problem)

The core technical challenge of the project was designing the orchestration layer.

• The Struggle: We didn't want a simple "prompt-in/palette-out" system. We wanted a multi-step conversation where the AI first reasons about the project and then applies technical constraints. Solving the logic to hand off high-level "Director" insights from the Copilot SDK to the low-level "Engine" tools in the MCP server was a significant architectural hurdle.
• The Learning: We solved this by implementing a Director-Worker pattern. The Copilot SDK acts as the brain that understands the user’s "mood," while the LLM Service acts as the precision tool that extracts hex codes and validates them. This required building a custom assistantOrchestrator that manages the state transitions between discovery and execution.

3. Theme Palette Precision & Validation

Getting an LLM to consistently output a valid, high-contrast, 5-color palette is harder than it looks.

• The Struggle: Models often hallucinate invalid hex codes or ignore specific keys in the JSON schema. Additionally, ensuring that the generated colors actually met accessibility standards was a non-negotiable requirement for us.
• The Learning: This led to the development of our Technical Integrity Gate. We learned that the "Agent" shouldn't just be an LLM; it should be an LLM wrapped in deterministic logic. By implementing strict Zod schema validation and an automatic WCAG contrast correction loop, we ensured that every output was production-ready.

4. Monorepo Resilience

Managing a local MCP server alongside a web application created potential for duplicated logic and configuration drift.

• The Struggle: Ensuring that the web app and the standalone MCP server used the exact same prompt templates and validation math.
• The Learning: We adopted a Monorepo architecture with a shared @theme-ai/core package. This simplified our development significantly: any improvement to the orchestration or a palette fix was instantly available to both the web UI and the native MCP tool. It taught us that "Write Once, Run Everywhere" is a powerful paradigm for AI tools.

Contact Information

serguei246@gmail.com, https://www.linkedin.com/in/serguei-castillo/, crhdez1987@gmail.com

Country/Region

United States