# Designer Migration Guide

> Migrate from the shared monorepo to your own dedicated designer repo.
> **Read time: ~3 minutes.**

---

## What Changed and Why

Your prototypes now live in their own GitHub repository (e.g., `ux-prototypes-drew-kimrey`)
instead of a shared folder inside the parent `UX-PROTOTYPES` repo.

**Why:** The parent repo was growing huge (700 MB+) and slow to clone.
Each designer repo is small (~50–200 MB), faster to clone, and gives you a
clean Git history with only your own work.

Your prototypes still appear on the same live site — nothing about the URLs
or the viewer changes.

---

## One-Time Setup

### 1. Clone your designer repo

```bash
git clone https://github.com/powerschool-llc/ux-prototypes-YOUR-NAME.git
cd ux-prototypes-YOUR-NAME
```

> **Your repo URL** is `ux-prototypes-` + your name lowercased with hyphens.
> Examples:
> - Drew Kimrey → `ux-prototypes-drew-kimrey`
> - Damon Tribble → `ux-prototypes-damon-tribble`
> - James O'Byrne → `ux-prototypes-james-obyrne`

### 2. Open in Cursor

Open the repo root (not a subfolder) in Cursor:

```bash
cursor .
```

Your Cursor rules live in `.cursor/rules/` at the repo root and apply
to all your prototypes automatically.

### 3. Install dependencies

```bash
npm install
```

### 4. Verify your prototypes are there

Your prototypes are at the root of the repo (e.g., `my-prototype/`),
not inside a `designers/Your Name/` subfolder — you _are_ the repo.

---

## Daily Workflow

### Creating a prototype

```bash
npm run create
```

Your name is auto-detected from the repo. Just enter the prototype name.

### Making changes and publishing

All changes go through **pull requests** that **auto-merge** after validation:

```bash
# 1. Create a branch
git checkout -b feature/describe-your-change

# 2. Make your changes, then stage and commit
git add .
git commit -m "feat: describe what you changed"

# 3. Push and create a PR
git push -u origin feature/describe-your-change
gh pr create --fill
```

That's it. The PR auto-merges in ~10 seconds after `prototype.json` validation passes.
Your changes appear on the live site within ~2 minutes.

### Why PRs instead of pushing to main?

- **Batches changes** — one Render redeploy per PR merge, not per commit
- **Catches mistakes** — validates your `prototype.json` before going live
- **Clean history** — squash-merged PRs keep the commit log tidy
- **No manual approval** — auto-merge means it's still instant

### Quick shortcut for small changes

```bash
git checkout -b fix/quick-update && git add . && git commit -m "fix: quick update" && git push -u origin fix/quick-update && gh pr create --fill
```

---

## How It Works Behind the Scenes

```
You push → PR auto-merges → notify-parent.yml fires
→ parent repo updates submodule pointer → Render redeploys → live in ~2 min
```

You never need to touch the parent repo. Everything is automated.

---

## FAQ

**Where are other designers' prototypes?**

They're in the parent repo's `designers/` folder as submodules. You can
still view any prototype at `https://ux-prototypes.onrender.com/designers/Name/prototype/`.
You just won't have their code on your machine (saves disk space).

**How does my work get to the live site?**

Merge a PR in your repo → a GitHub Action notifies the parent repo →
parent updates the submodule pointer → Render redeploys in 2–3 minutes.

**Can I push directly to main?**

Main is protected — all changes go through PRs. This is intentional to
batch deploys and validate prototypes. PRs auto-merge so it's just as fast.

**Do I need `npm run safe-push`?**

No. That's a monorepo safety tool. In your designer repo, `git push` and
`gh pr create` are all you need.

**How do I share a prototype with someone?**

The prototype URL format is the same:
`https://ux-prototypes.onrender.com/designers/Your%20Name/prototype-name/`

**How do I pull the latest if someone else pushed to my repo?**

```bash
git checkout main
git pull origin main
```

---

## Troubleshooting

**"Permission denied (publickey)" when pushing**

Set up HTTPS with GitHub CLI:
```bash
gh auth login
# Select GitHub.com → HTTPS → Authenticate in browser
```

Or switch to HTTPS manually:
```bash
git remote set-url origin https://github.com/powerschool-llc/ux-prototypes-YOUR-NAME.git
```

**"Repository not found" when cloning**

Make sure you have access to the `powerschool-llc` organisation.
Ask your team lead to add you if needed.

**My prototype isn't showing on the live site after merge**

1. Check that `prototype.json` has `"public": true`
2. Wait 3–5 minutes for the automation to run
3. Check [GitHub Actions](https://github.com/powerschool-llc/UX-PROTOTYPES/actions)
   on the parent repo — look for `update-submodule` workflow runs

**PR validation failed**

The `Validate prototype.json` check caught an error. Common issues:
- `prototype.json` is invalid JSON (syntax error)
- Missing required field: `name`, `designer`, or `public`
- `"public"` is a string (`"true"`) instead of boolean (`true`)

Fix the issue, push again, and the PR will re-validate.

**Cursor rules aren't applying**

Make sure you opened the repo root in Cursor (not a prototype subfolder).
Rules in `.cursor/rules/` apply to everything inside the repo.

---

*Questions? Ask in `#ux-prototypes` on Slack or open an issue on
[UX-PROTOTYPES](https://github.com/powerschool-llc/UX-PROTOTYPES/issues).*