Home Upload Portal

One-Click Setup

New to UX Prototypes? Download and run the setup script for your platform — it handles everything automatically.

Mac

macOS 10.15+
Download

Windows

Windows 10+
Download
1
Download the script for your platform
2
Double-click to run it
3
Follow the prompts — you're done!

Alternative: Terminal one-liner

Mac / Linux:

curl -fsSL https://raw.githubusercontent.com/powerschool-llc/UX-PROTOTYPES/main/onboarding/mac-setup.command | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/powerschool-llc/UX-PROTOTYPES/main/onboarding/windows-setup.ps1 | iex
or

Get Started

Set up your workspace and publish your first prototype with ease.

🚀 Quick Setup (Recommended)

One command does everything! Copy and paste:

Mac / Linux: 

curl -fsSL https://raw.githubusercontent.com/powerschool-llc/UX-PROTOTYPES/main/scripts/setup-wizard.js | node

Windows (PowerShell): 

irm https://raw.githubusercontent.com/powerschool-llc/UX-PROTOTYPES/main/scripts/setup-wizard.js | node

This automatically:

  • ✅ Checks and installs prerequisites
  • ✅ Configures Git
  • ✅ Sets up GitHub authentication
  • ✅ Clones the repository
  • ✅ Configures sparse checkout (saves disk space - only your folder)
  • ✅ Installs dependencies
  • ✅ Sets up safety checks
  • ✅ Guides you through creating your first prototype

Only prompts when needed! See SETUP_ONE_LINER.md for details.

Manual Setup (Alternative)

If you prefer to set up manually or the one-liner doesn't work:

What You Need

  • Cursor (code editor)
  • GitHub account with access to this repository
  • Git installed on your computer

Step 0: One-Time Setup (Do This First!)

Where: Open Terminal (Mac) or Command Prompt (Windows)

This is a one-time setup. You only need to do this once.

1. Configure Git (if not already done)

git config --global user.name "Your Name"
git config --global user.email "your.email@powerschool.com"

What this does: Tells Git who you are (for commit history).

2. Set Up GitHub Authentication

Option A: GitHub CLI (Recommended - Easiest)

# Install GitHub CLI (if not installed)
# Mac: brew install gh
# Windows: winget install GitHub.cli

# Authenticate with GitHub
gh auth login

Follow the prompts:

  • Select "GitHub.com"
  • Select "HTTPS"
  • Authenticate in your browser
  • Done! ✅

Option B: Personal Access Token (Alternative)

If you prefer not to use GitHub CLI:

  1. Go to: https://github.com/settings/tokens
  2. Click "Generate new token (classic)"
  3. Give it a name (e.g., "UX Prototypes")
  4. Select scope: repo (full control of private repositories)
  5. Click "Generate token"
  6. Copy the token (you'll use it as your password when pushing)

Step 1: Clone the Repository

Where: Terminal (Mac) or Command Prompt (Windows)

Copy and paste this:

git clone https://github.com/powerschool-llc/UX-PROTOTYPES.git
cd UX-PROTOTYPES

What this does: Downloads the repository to your computer. The repository root contains all the files you need.

💾 Save Disk Space with Sparse Checkout (Optional but Recommended)

During setup, you'll be asked for your name. If you provide it, the system will configure sparse checkout to only download your folder, keeping your drive from filling up with everyone else's prototypes.

What sparse checkout does:

  • ✅ Only checks out your folder: designers/Your Name/
  • ✅ Still includes essential files (scripts, package.json, etc.)
  • ✅ Saves significant disk space
  • ✅ You can still view other designers' work later

To view another designer's work later: 

npm run fetch-designer "Designer Name"

To fetch all folders (disable sparse checkout): 

npm run fetch-all

Note: If you skip sparse checkout during setup, you can enable it later: 

git sparse-checkout init --cone
git sparse-checkout set "designers/Your Name/" "scripts/" "package.json" "index.html" ".gitignore" ".github/" "thumbnails/" "templates/"
git checkout main

Step 2: Open in Cursor and Build Your Prototype

Where: Open Cursor (your code editor)

  1. Open the folder in Cursor:
- File → Open Folder - Navigate to UX-PROTOTYPES (the repository root) - Click Open
  1. Create your prototype:
- Open Terminal in Cursor (View → Terminal) - Run: npm run create - Enter your name when prompted - Enter your prototype name (e.g., "login-flow") - Press Enter to make it public (or type 'n' for private)
  1. Start building:
- Your prototype folder is created at designers/your-name/prototype-name/ - Open index.html in that folder - Start building with HTML, CSS, and JavaScript

What this does: Creates your prototype folder and gets you ready to build in Cursor.

Step 3: Publish to GitHub Pages

Where: Terminal in Cursor

Copy and paste this:

# First, verify your Git setup (recommended)
npm run verify

# Then stage, commit, and push safely
git add .
git commit -m "Add my prototype"
npm run safe-push

What this does:

  • npm run verify - Checks that you're pushing to the correct repository (validates Git configuration)
  • git add . and git commit - Stages and commits your changes
  • npm run safe-push - Safely pushes to GitHub with validation (includes automatic Git hook checks)

Note: Git hooks are automatically installed during setup. These hooks validate your repository before every push to prevent accidental pushes to wrong repositories.

Your prototype goes live automatically in 2-3 minutes.

That's It!

Your prototype is live at: https://laughing-broccoli-2e6ewew.pages.github.io/

Learn at Your Own Pace

The setup is simple, publishing is easy. Now you can focus on prototyping your way.

Need more help? See GUIDE.md Just need commands? See COMMANDS.md

Complete Guide

Everything you need to know about creating and sharing prototypes.

Complete Guide

Everything you need to know about creating and sharing prototypes.

Creating Prototypes

The Simple Way

npm run create

Enter your name and prototype name when prompted. This creates a prototype in designers/your-name/prototype-name/.

What Gets Created

  • index.html - Your prototype file
  • prototype.json - Configuration
  • README.md - Documentation template

Building Your Prototype

Open Your Prototype

cd designers/your-name/prototype-name
cursor .

Or open index.html directly in your browser.

Build It

Edit index.html with HTML, CSS, and JavaScript. Use any framework you want.

Test Locally

For HTML prototypes: 

open index.html  # Mac
start index.html # Windows

For React/Vue: 

npm install
npm run dev

Sharing Your Prototype

Make It Public

Edit prototype.json: 

{
  "public": true,
  "description": "Your description here"
}

Push to GitHub

# First, verify your Git setup
npm run verify

# Then stage, commit, and push safely
git add designers/your-name/prototype-name/
git commit -m "Add my prototype"
npm run safe-push

Your prototype goes live automatically on both platforms in 2-3 minutes:

  • GitHub Pages (if repo is public)
  • Render (works with private repos)

Why use npm run safe-push?

  • Validates you're pushing to the correct PowerSchool repository
  • Prevents accidental pushes to wrong repositories
  • Shows confirmation before pushing
  • Built-in safety checks
  • Automatically triggers dual deployment to GitHub Pages and Render

🛡️ Safety System

This repository includes a multi-layer safety system to prevent pushing to wrong repositories and ensure data integrity.

What is the Safety System?

The safety system consists of:

  1. Git Hooks - Automatic validation before pushes and commits
- pre-push hook: Validates repository before every push - pre-commit hook: Validates prototype.json files before commits - Blocks force pushes to main/master branches - Cannot be easily bypassed
  1. Verification Scripts - Manual validation tools
- npm run verify - Checks Git configuration - npm run safe-push - Safe push with confirmation
  1. Repository Validation - Automatic checks
- Verifies correct PowerSchool repository - Detects multiple remotes - Validates directory structure

How Hooks Work

Git hooks run automatically when you:

  • Push: The pre-push hook validates your repository
  • Commit: The pre-commit hook validates prototype.json files

Hooks are installed automatically when you:

  • Run the setup script (setup.sh or setup.bat)
  • Run npm run install-hooks manually

What Happens When Validation Fails?

If validation fails, you'll see clear error messages:

Repository Validation Failed: 

❌ ERROR: Wrong repository configured
   Current: https://github.com/wrong-repo.git
   Expected: github.com/powerschool-llc/UX-PROTOTYPES
   
   To fix this:
   git remote set-url origin https://github.com/powerschool-llc/UX-PROTOTYPES.git

Force Push Blocked: 

🛑 FORCE PUSH BLOCKED
Force pushes to main branch are NOT allowed.

Verifying Hooks Are Installed

Check if hooks are installed: 

ls -la .git/hooks/pre-push
ls -la .git/hooks/pre-commit

If hooks are missing, install them: 

npm run install-hooks

Troubleshooting

Prototype Not Showing on Homepage?

  1. Check prototype.json has "public": true
  2. Verify you pushed to GitHub
  3. Check GitHub Actions completed: https://github.com/powerschool-llc/UX-PROTOTYPES/actions

Can't Push to GitHub?

Repository Validation Failed: If you see "Wrong repository configured" or "Repository validation failed":

# Check current remote
git remote -v

# Fix if wrong
git remote set-url origin https://github.com/powerschool-llc/UX-PROTOTYPES.git

# Verify it's fixed
npm run verify

Multiple Remotes Detected: If you see a warning about multiple remotes:

# List all remotes
git remote -v

# Remove wrong remotes
git remote remove 

# Verify again
npm run verify

Force Push Blocked: If you see "FORCE PUSH BLOCKED":

  • Force pushes to main/master are not allowed for safety
  • Create a feature branch instead
  • Force push to the feature branch if needed
  • Create a pull request to merge

Git Credentials: Verify your Git credentials: 

git config user.name
git config user.email

Make sure you have write access to the repository.

Hooks Not Working: If hooks don't seem to be running:

# Check if hooks exist
ls -la .git/hooks/pre-push

# Install hooks if missing
npm run install-hooks

# Verify hooks are executable
chmod +x .git/hooks/pre-push
chmod +x .git/hooks/pre-commit

Build Errors?

For React/Vue prototypes: 

cd designers/your-name/prototype-name
npm install

Advanced Topics

Private Prototypes

Set "public": false in prototype.json. Your prototype won't appear on the homepage but is still accessible via direct URL.

Naming Your Prototype

Use lowercase with hyphens:

  • ✅ login-flow
  • ✅ dashboard-widget
  • ❌ Login Flow (spaces)
  • ❌ my_prototype (underscores)

Figma Integration

Connect Cursor with Figma for design-to-code workflows. See FIGMA_MCP_SETUP.md for details.

Render Integration

Manage your Render services directly from Cursor. Once set up, you can ask me to list services, update environment variables, view deployment logs, and more. See RENDER_MCP_SETUP.md for setup instructions.

Need Help?

  • Check this guide
  • See existing prototypes for examples
  • Ask the team on Slack/Teams
  • Open an issue on GitHub

Commands

Quick reference for common tasks.

Commands

Quick reference for common tasks.

Create Prototype

npm run create

Creates a new prototype folder. Prompts for your name and prototype name. Automatically validates repository before creating.

Navigate to Prototype

cd designers/your-username/prototype-name

Test Locally

# HTML
open index.html

# React/Vue
npm install && npm run dev

Share Prototype

# Verify Git setup first
npm run verify

# Stage and commit
git add designers/your-username/prototype-name/
git commit -m "Add my prototype"

# Safe push with validation - automatically deploys to GitHub Pages AND Render
npm run safe-push

After pushing:

  • Prototype automatically deploys to GitHub Pages (if repo is public)
  • Prototype automatically deploys to Render (works with private repos)
  • Both deployments happen automatically - no manual steps needed!

Generate Homepage

npm run generate

Regenerates the homepage index.html with all public prototypes.

Prototype Versioning

Create version checkpoints for your prototypes. This allows you to rollback your prototype to a previous version without affecting the core system or other prototypes.

Create Prototype Version

# Interactive mode (prompts for designer name, prototype name, and version)
npm run create-prototype-version

# Or with arguments
npm run create-prototype-version --designer="Parag Desai" --prototype="my-prototype" --version="1.0"

Creates a version checkpoint for your prototype. This is useful before making major changes.

Rollback Prototype

npm run rollback-prototype --designer="Parag Desai" --prototype="my-prototype" --version="1.0"

Rolls back your prototype to a previous version. After running this command, you'll need to commit the changes:

# Stage the changes
git add "designers/Parag Desai/my-prototype"

# Commit
git commit -m "Rollback my-prototype to v1.0"

# Push
npm run safe-push

Important Notes:

  • ✅ Rollback only affects your specific prototype
  • ✅ Core system will NOT be affected
  • ✅ Other designers' prototypes will NOT be affected
  • ⚠️ You must commit the rollback manually (prevents accidental rollbacks)

For more details, see PROTOTYPE_VERSIONING_GUIDE.md

Sparse Checkout (Save Disk Space)

Fetch a Specific Designer's Folder

npm run fetch-designer "Designer Name"

Example: 

npm run fetch-designer "Damon Tribble"

Adds a specific designer's folder to your sparse checkout so you can view their prototypes without downloading everything.

Fetch All Folders

npm run fetch-all

Disables sparse checkout and fetches all designer folders. Use this if you want to see everyone's work.

Note: Sparse checkout is automatically configured during setup if you provide your name. This saves disk space by only checking out your folder by default.

Safety & Verification

Verify Git Configuration

npm run verify

Validates your Git setup:

  • Checks repository URL is correct
  • Verifies branch
  • Detects multiple remotes
  • Shows warnings for issues

Install Git Hooks

npm run install-hooks

Installs Git safety hooks (pre-push and pre-commit). Hooks are also installed automatically during setup.

Safe Push

npm run safe-push

Safely pushes with validation:

  • Runs repository verification
  • Shows confirmation prompt
  • Executes git push after validation

Always use this instead of git push directly.

Deploy (Full Workflow)

npm run deploy

Complete deployment workflow:

  • Verifies Git configuration
  • Generates homepage
  • Prepares for commit and push

Need explanations? See GUIDE.md

Figma MCP Setup

Connect Cursor with Figma for design-to-code workflows.

🎨 Figma MCP Setup Guide

Connect Cursor with Figma for seamless design-to-code workflows

What is Figma MCP?

Figma MCP (Model Context Protocol) allows Cursor's AI to:

  • Read your Figma designs
  • Generate code from designs
  • Understand design context
  • Help translate designs into prototypes

It's like having an AI assistant that can see your Figma files!

Quick Setup (Automated)

The easiest way is to let the setup script do it for you:

# During initial setup, when prompted:
Set up Figma MCP integration in Cursor? (y/n): y

Or run it manually:

node scripts/setup-figma-mcp.js

That's it for Cursor! The script automatically:

  • ✅ Finds your Cursor config file
  • ✅ Adds Figma MCP configuration
  • ✅ Sets everything up

Manual Setup (If Needed)

Step 1: Enable MCP Server in Figma

  1. Open Figma desktop app (not browser version)
  2. Open any Figma file
  3. Switch to Dev Mode:
- Click the "Dev Mode" toggle in the top toolbar - Or press Shift + D
  1. Enable MCP Server:
- Look at the right sidebar - Find "MCP Server" section - Toggle it ON - Note the server URL (usually http://127.0.0.1:3845/mcp)

Step 2: Configure Cursor

The setup script handles this automatically, but if you need to do it manually:

  1. Open Cursor
  2. Open Command Palette:
- macOS: Shift + Command + P - Windows/Linux: Shift + Ctrl + P
  1. Search for: "Cursor Settings" or "MCP Settings"
  2. Add Custom MCP Server:
- Click "Add Custom MCP" - Enter: 
{
       "mcpServers": {
         "figma-desktop": {
           "url": "http://127.0.0.1:3845/mcp"
         }
       }
     }
  1. Save the configuration

Step 3: Restart Cursor

Close and reopen Cursor to activate the connection.

Verify It's Working

  1. Open Cursor
  2. Open a Figma file in Figma desktop app
  3. In Cursor, try asking:
- "What's in my current Figma selection?" - "Generate code for the selected component" - "What colors are used in this design?"

If Cursor can see your Figma design, it's working! ✅

Troubleshooting

"Cursor does not appear to be installed"

Solution:

  • Install Cursor from https://cursor.sh/
  • Run the setup script again

"MCP Server not found" in Figma

Solution:

  • Make sure you're using Figma desktop app (not browser)
  • Make sure you're in Dev Mode
  • Check that MCP Server is toggled ON in the right sidebar
  • Restart Figma if needed

Cursor can't connect to Figma

Solution:

  1. Verify Figma desktop app is running
  2. Verify MCP Server is enabled in Figma
  3. Check the server URL matches: http://127.0.0.1:3845/mcp
  4. Restart both Cursor and Figma
  5. Check Cursor's MCP settings are correct

Config file not found

Solution:

  • Make sure Cursor has been opened at least once
  • The config directory is created on first launch
  • Try opening Cursor, then run the setup script again

Permission errors

Solution:

  • Make sure you have write permissions to the config directory
  • On macOS/Linux, you might need to check file permissions
  • Try running the script with appropriate permissions

What You Can Do With Figma MCP

Once set up, you can:

  • Ask Cursor about your designs:
- "What components are in this Figma file?" - "What's the spacing between these elements?" - "What fonts are used?"
  • Generate code from designs:
- "Create HTML for the selected component" - "Generate React component from this design" - "What CSS would match this Figma design?"
  • Understand design context:
- Cursor can see your design while you code - Better suggestions based on your designs - Faster prototype creation

Advanced Configuration

Custom MCP Server URL

If your Figma MCP server uses a different URL:

  1. Edit Cursor's MCP config file:
- macOS: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json - Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json - Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  1. Update the URL in the config:
{
     "mcpServers": {
       "figma-desktop": {
         "url": "YOUR_CUSTOM_URL_HERE"
       }
     }
   }
  1. Restart Cursor

Need Help?

  • Check Cursor's MCP documentation
  • See Figma's MCP setup guide: https://help.figma.com/hc/en-us/articles/35281186390679
  • Ask the team on Slack/Teams
  • Open an issue on GitHub

Happy designing and coding! 🎨💻