Skip to content

Hidden-History/ui-ux-spline

BranchesTags

Repository files navigation

ui-ux-spline

3D Design Automation + Design Intelligence

A Claude Code Skill

Node.js Python Playwright Commands Claude Code License

Automate Spline Design from your terminal. Generate complete design systems. Build 3D scenes with a single workflow.

Table of Contents

Overview

ui-ux-spline is a Claude Code skill that connects two systems: automated control of the Spline Design desktop app and an AI-powered design intelligence engine.

The result is a single, coherent workflow: describe the product you are building, get a complete design system (colors, typography, UI style), and immediately use those exact values to construct and export a production-ready 3D scene — without touching the Spline GUI.

What it automates:

  • Full scene construction via 36 CLI commands (objects, materials, lights, camera, events, states, export)
  • 16 material types including Glass, Gradient, Fresnel, Noise, Matcap, and more
  • Export to embeddable iframe URL for direct use in web projects

What it generates:

  • Industry-matched color palettes (96 options)
  • UI style recommendations mapped to Spline materials
  • Font pairings, UX guidelines, and framework-specific design notes

Demo

Demo GIF coming soon. The workflow below shows the full sequence from design system generation to 3D export.

Design Prompt → Design System → Spline Scene → iframe Embed

How It Works

┌─────────────────────────────────────────────────────────┐
│                    Your Claude Session                  │
│                                                         │
│  "Build a glassmorphism hero section for a SaaS app"   │
│                          │                             │
│              ┌───────────▼───────────┐                 │
│              │  ui-ux-pro-max Engine │                 │
│              │  96 palettes          │                 │
│              │  67 UI styles         │                 │
│              │  57 font pairings     │                 │
│              └───────────┬───────────┘                 │
│                          │  design system              │
│              ┌───────────▼───────────┐                 │
│              │    Spline CLI (CDP)   │                 │
│              │    36 commands        │                 │
│              │    Playwright bridge  │                 │
│              └───────────┬───────────┘                 │
│                          │                             │
└──────────────────────────┼─────────────────────────────┘
                           │ Chrome DevTools Protocol
              ┌────────────▼────────────┐
              │  Spline Desktop (Win)   │
              │  Electron app           │
              └────────────┬────────────┘
                           │
              ┌────────────▼────────────┐
              │   iframe embed code     │
              │   ready for production  │
              └─────────────────────────┘

Runtime environment: WSL2 (Ubuntu) sends CDP commands to Spline Desktop running on the Windows side. Node.js speaks to the Electron app's exposed DevTools port. Python handles design intelligence search independently.

Installation

Requirements

Requirement Version Notes
WSL2 Ubuntu 20.04+ Required — CDP only accessible from Windows localhost
Node.js v18+ Must be the Windows installation, accessible from WSL2
Python 3.10+ For design intelligence engine
Spline Desktop Latest Must be running before connecting
rsync Any Used by installer

Install

Three install modes are supported:

# Interactive — prompts for target directory
bash install.sh

# Direct path — installs to specified location
bash install.sh /path/to/your/project

# Current directory — installs in-place
bash install.sh --here

The installer copies the CLI, design intelligence engine, and skill configuration into your project's .claude/skills/ directory and registers the spline command alias.

Verify Installation

spline status

Expected output confirms Node.js path, Spline Desktop detection, and CDP connectivity.

Commands Reference

Connection

Command Description
spline status Check environment: Node.js path, Spline detected, CDP reachable
spline connect Open CDP connection to running Spline Desktop instance
spline inspect Dump current scene structure and object tree

Objects

Supported object types: Cube, Sphere, Cylinder, Torus, Helix, Cone, Pyramid, Icosahedron, Dodecahedron, Torus Knot, Rectangle, Ellipse, Star, Polygon, Text

Command Description
spline object add <type> Add a new 3D object to the scene
spline object list List all objects in current scene
spline object select <name> Select object by name
spline object modify [options] Modify position, rotation, scale (--position x,y,z, --scale x,y,z)
spline object delete <name> Remove object from scene
spline object rename <old> <new> Rename an object

Materials

16 material types: Color, Glass, Gradient, Noise, Fresnel, Rainbow, Toon, Outline, Matcap, Depth, Displace, Pattern, Normal, Image, Video, AI Texture

Command Description
spline material color <hex> Set material color on selected object
spline material info Show material layers on selected object
spline material add Add a new material layer
spline material remove <index> Remove material layer by index
spline material type <index> <type> Set material type for a layer
spline material opacity <index> <0-100> Set layer opacity

Lights

Command Description
spline light add <type> Add light (Point, Directional, Spot)
spline light modify [options] Modify light position, intensity, color

Events & States

Command Description
spline event add <name> Add interaction event
spline event list List all events
spline event delete <name> Remove event
spline event rename <old> <new> Rename event
spline state add <name> Add animation state
spline state list List all states
spline state delete <name> Remove state
spline state select <name> Activate a state

Camera

Command Description
spline camera info Show current camera position and settings
spline camera add Add a new camera
spline camera set [options] Set camera position and target

Export

Command Description
spline export url Generate shareable scene URL
spline export code Get iframe embed code for production
spline export update Re-publish and refresh export

Scene & Utility

Command Description
spline scene info Scene metadata: name, object count, dimensions
spline scene screenshot Capture PNG of current scene
spline scene create Create a new blank scene
spline undo Undo last action
spline redo Redo last undone action

Design Intelligence

The bundled ui-ux-pro-max engine is a searchable knowledge base of design decisions, mapped to actionable outputs.

What's Included

Dataset Count Description
Color palettes 96 Industry and product-type matched (SaaS, fintech, health, e-commerce, etc.)
UI styles 67 Named design systems: Glassmorphism, Brutalism, Neumorphism, Claymorphism, and more
Font pairings 57 Google Fonts combinations with use-case notes
UX guidelines 99 Interaction and layout principles
Chart types 25 Data visualization recommendations
Framework guidelines 13 React, Next.js, Vue, Svelte, Tailwind, and more

Style-to-Material Mapping

The engine maps UI styles directly to Spline material types so design decisions propagate automatically into the 3D layer:

UI Style Spline Material
Glassmorphism Glass
Neumorphism Fresnel
Claymorphism Matcap
Brutalism Color (flat)
Aurora / Gradient Gradient
Holographic Rainbow
Sketch / Illustrated Toon

Search Usage

# Generate a complete design system for a product description
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "tech saas modern" --design-system

# Search specific datasets
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "dark fintech" --palettes
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "glassmorphism" --styles
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "dashboard analytics" --ux-guidelines

The --design-system flag returns a structured JSON object: primary/secondary/accent colors, typography stack, UI style selection, material mapping, and relevant UX guidelines — ready to pipe directly into the Spline CLI workflow.

End-to-End Workflow

The following builds a complete glassmorphism hero section for a SaaS product from scratch:

# Step 1: Generate design system for this product
python3 .claude/skills/ui-ux-pro-max/scripts/search.py "tech saas modern" --design-system
# Returns: primary #6366F1, style: Glassmorphism → Glass material

# Step 2: Connect to Spline Desktop (must be running)
spline connect

# Step 3: Build the 3D scene
spline object add Sphere
spline object rename "Sphere" "Hero Orb"
spline object modify --scale 3,3,3

# Step 4: Apply design system colors and materials
spline material color 6366F1          # Primary color from design system
spline material add                   # Add second layer
spline material type 1 Glass          # Glassmorphism → Glass mapping
spline material opacity 1 40          # 40% opacity for glass effect

# Step 5: Add and position lighting
spline light add directional
spline light modify --position 100,200,150

# Step 6: Verify scene
spline scene info
spline scene screenshot

# Step 7: Export for production
spline export url
spline export code
# Outputs: <iframe src="https://my.spline.design/..." ...></iframe>

Total time from prompt to embed code: under 5 minutes.

Known Limitations

Limitation Details
Event configuration Event type changes and action binding require the Spline GUI — not accessible via CDP
Variable creation Spline variables must be created in the UI before they can be referenced via CLI
Command latency Each command takes approximately 5-8 seconds due to Playwright CDP connection overhead per invocation
Platform Requires WSL2 + Windows. CDP port is only accessible from Windows localhost; Linux-native Spline is not supported
Spline Desktop version Behavior is tied to the internal structure of the Electron app — updates to Spline Desktop may require selector adjustments

Built With

Technology Role
Playwright Chrome DevTools Protocol automation — the bridge to Spline Desktop
Commander.js CLI framework — command parsing, help generation, argument validation
Spline Design The 3D design tool being automated
Claude Code Skill host — provides the AI session that orchestrates the workflow
Python 3 Design intelligence engine and search layer

License

MIT License — see LICENSE for full text.

Built as a Claude Code skill. Designed for developers who want production-quality 3D web assets without the GUI bottleneck.

About

Automate Spline Design from your terminal. Generate complete design systems. Build 3D scenes with a single workflow.

Resources

Readme
Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages