Introduction
Git isn't just for developers. Designers who work with code — design systems, documentation, prototypes, or design tokens — benefit enormously from version control. Git lets you experiment without fear, review changes before they go live, and collaborate without overwriting each other's work.
You don't need to master every Git command. A handful of workflows cover 95% of what you'll need: creating branches, making commits, opening pull requests, and handling conflicts.
This guide covers practical Git workflows oriented toward design-development collaboration.
Key Concepts
Branching
Branches let you work on changes without affecting the main codebase. Create a branch, make changes, then merge back via a pull request. If something goes wrong, your branch is isolated.
# Create and switch to a new branch
git checkout -b feature/update-design-tokens
# See all branches
git branch -a
# Switch between branches
git checkout main
git checkout feature/update-design-tokens
Commits
A commit is a snapshot of your changes with a description. Write clear commit messages that explain what changed and why.
# Stage changes
git add tokens/colors.json
git add tokens/typography.json
# Commit with a descriptive message
git commit -m "Update brand colors to match new palette"
# Or stage and commit in one step
git commit -am "Fix spacing tokens for mobile"
Pull Requests
Pull requests (PRs) are how changes get reviewed before merging. They show a diff of all changes and allow comments, discussions, and approval workflows.
Practical Examples
1. Typical Design Token Update
# 1. Start from latest main
git checkout main
git pull origin main
# 2. Create a branch
git checkout -b design/update-colors
# 3. Make your changes (edit files)
# 4. Stage and commit
git add .
git commit -m "Update primary color palette
- Changed primary-500 from #3B82F6 to #2563EB
- Updated hover states to match
- Adjusted contrast ratios for accessibility"
# 5. Push to remote
git push origin design/update-colors
# 6. Open a PR on GitHub/GitLab
2. Handling Conflicts
# If someone else changed the same file:
git pull origin main
# Git shows conflict markers:
# <<<<<<< HEAD (your changes)
# =======
# >>>>>>> main (their changes)
# Edit the file to resolve, then:
git add resolved-file.json
git commit -m "Resolve merge conflict in color tokens"
3. Useful Git Aliases
# Add to ~/.gitconfig
[alias]
s = status
co = checkout
br = branch
cm = commit -m
lg = log --oneline --graph --all
undo = reset --soft HEAD~1
Best Practices
- ✅ Always work on a branch, never directly on main
- ✅ Write descriptive commit messages explaining what and why
- ✅ Pull latest main before starting new work
- ✅ Make small, focused commits rather than large batch changes
- ✅ Use PRs for all changes — even small ones
- ❌ Don't force push to shared branches
- ❌ Don't commit generated files (node_modules, build output)
Common Pitfalls
- 🚫 Working on main directly — creates merge conflicts and risky deploys
- 🚫 Huge commits with vague messages — impossible to review or revert
- 🚫 Not pulling before pushing — causes unnecessary merge conflicts
- 🚫 Committing secrets or API keys — use .gitignore and environment variables