# The Shuffle

> AI-Powered Visual Design Prompt & System Generator by Clockwork. Deal through color palettes, font pairings, UI architectures, navigation systems, publication layouts, and photography directions to generate an executable master design blueprint (Markdown & JSON) for AI coding assistants and modern web frameworks.

The Shuffle (https://shuffle.clockworkwd.com) bridges the gap between creative visual direction and AI-assisted code generation. Rather than prompting AI coding agents with vague stylistic descriptions, The Shuffle guides users through structured King-of-the-Hill elimination tournaments across six core visual pillars, producing strict design constraints, verified WCAG AA contrast ratios, and drop-in CSS custom properties.

## Core Capabilities

- **Intelligent Brand Ingestion**:
  - AI Vision URL Scraper: Extracts true visual brand colors and locates official logos directly from live website URLs.
  - Vector Artwork Conversion: Accepts SVG, PNG, JPG, and automatically converts vector Adobe Illustrator (`.ai`) and Encapsulated PostScript (`.eps`) assets to crisp, transparent artwork.
  - Bring Your Own Colors (BYOC): Instantly generate cohesive light and dark variations from 3 custom brand hex values.
  - Describe Your Brand: AI-assisted palette generation from semantic prompts.

- **Color Architecture**:
  - 33 curated thematic palettes categorized by aesthetic vibe.
  - King-of-the-Hill tournament elimination interface.
  - Real-time swatch color picker tweaking with persistence.
  - Automated WCAG AA contrast ratio compliance auditing.

- **Typography Studio**:
  - Serif vs. Sans pre-filtering.
  - 30 battle-tested Google Font pairings (including Pro Mixed pairs).
  - Dynamic in-card UI mockup previews styled with the active palette.
  - Google Fonts Studio with search across 1,700+ Google Fonts and granular font weight controls (100–900).

- **UI & Interface Architecture**:
  - Standardized visual comparison across 7 distinct archetypes: Minimalist, Soft, Brutalist, Enterprise, Editorial, Neomorphic, Retro 90s.
  - Uniform form fields and component knobs to isolate pure stylistic differences (borders, radii, shadows, typography scale).

- **Navigation Architecture**:
  - 5 responsive navigation layouts: Floating Island, Sticky Header, Off-Canvas Dock, Fullscreen Overlay, and Utility Header.

- **Publication & Blog Architecture**:
  - Complete publishing systems with paired specifications for both Archive Feed (`archive.php` with search, topic pills with counts, and lead dispatches) and Single Post article reader (`single.php` with drop caps, key takeaways, and author bio cards).
  - 5 bespoke publication styles: Editorial Magazine, Tech Changelog, Bento Grid, Minimalist Newsletter, and Resource Hub.

- **Photography Direction**:
  - 12 curated photographic styles with deterministic sample previews, lighting guidelines, and mood tags.

- **Realistic 3D Previews**:
  - Live preview rendering inside 16:10 desktop browser frames and 9:19.5 smartphone bezels with interactive 3D isometric tilt.

- **Master Design Blueprint Export**:
  - Production-ready Markdown prompt and JSON design tokens.
  - Ready for immediate handoff to Antigravity, Astro, Cursor, Claude Code, Windsurf, or custom web projects.
  - Client Share Links (`/share/[token]`) with pre-rendered social unfurl cards (OpenGraph PNG thumbnails).

## Quick Links

- [Web Application](https://shuffle.clockworkwd.com): Interactive design tournament and preview studio.
- [Community Gallery](https://shuffle.clockworkwd.com/gallery): Browse and fork community-created design blueprints.
- [Pro Features](https://shuffle.clockworkwd.com/pro): Client share links, brand board PDFs, and Figma design tokens.
- [Full Documentation for LLMs](https://shuffle.clockworkwd.com/llms-full.txt): Detailed specifications, token schemas, and integration guides.
- [Sitemap](https://shuffle.clockworkwd.com/sitemap.xml): Machine-readable site index.

## Usage with AI Coding Agents

When building an application using a blueprint exported from The Shuffle:
1. Provide the Markdown blueprint as the primary system prompt or design context.
2. Inject the CSS custom properties from the blueprint into `src/styles/global.css` or the project root.
3. Import the specified Google Fonts in your HTML `<head>` or framework layout.
4. Adhere strictly to the typography scale, border radii, shadow depths, and component constraints defined in the blueprint.