GitHub makes a design change reviewable
GitHub gives a team a shared history of code changes and a place to review them before they reach the main branch. For a designer, the useful starting point is one small interface change with a clear before-and-after result. You do not need to learn every Git command before contributing, but you do need to understand what is local, what has been pushed, and what has been approved.
TDP’s GitHub for designers article introduces the core concepts. This walkthrough turns them into a first contribution, using the project’s existing setup and review process. Keep your initial task bounded so you can inspect the whole diff and explain every changed file.
Step 1. Understand what you are changing
Start with one small interface improvement: for example, fixing the spacing between a field label and its input. Write down the current behavior, desired result, and screen to check. A focused task is easier to review than a mixture of layout changes, dependency updates, and new product behavior.
Git tracks changes to files. GitHub hosts repositories and provides collaboration tools such as pull requests. Your team may have several repositories; confirm which one contains the interface you are working on.
| Term | What it means for this task |
|---|---|
| Repository | The project files and their version history |
| Clone | A local copy of a repository, including its Git history |
| Branch | A separate line of work pointing to commits; it is not another deployed product by itself |
| Commit | A recorded snapshot of selected changes in your local repository |
| Push | Sending local commits to a remote repository |
| Pull request | A proposal to merge changes from one branch into another |
| Merge | Integrating the proposed changes; deployment is a separate, team-specific process |
Read the repository's README and contribution instructions. Confirm the default or development branch, naming conventions, required checks, and reviewer. Do not assume the branch is called main or that it represents the live deployment.
Step 2. Open a local copy and create your branch
If you use GitHub Desktop, choose File → Clone Repository, select the repository or enter its URL, and choose a local folder. You need access to the project. Cloning and forking are different: a fork is a separate repository on GitHub, which can be useful when contributing without write access to the original. Follow your team's preferred route.
Open the project in your editor and follow its setup instructions. Dependencies, environment files, and the local preview command vary by repository. Ask the maintainer for missing configuration instead of inventing values or sharing credentials in a pull request.
Before editing, inspect your working tree and current branch. If another task has uncommitted changes, keep them separate. Start from the team's approved base branch and create a descriptive branch for the new task.
For a repository whose base is main, this command-line example starts a new branch only after you have confirmed a clean working tree:
git status
git switch main
git pull --ff-only
git switch -c fix/settings-field-spacing
Replace main if your team uses another base. If the update fails or reports divergent history, pause and investigate with the maintainer; do not force an update to make the warning disappear. GitHub Desktop provides visual controls for switching and creating branches if you prefer not to use the terminal.
Step 3. Make one change and inspect the diff
Run the local preview and find the affected screen. Reuse the existing spacing token or component convention rather than introducing an unrelated value. If an AI agent helps, give it the exact component, intended result, and boundaries of the task.
A useful starter request is:
Fix the spacing between the label and input in the settings form.
Use the existing field component and spacing tokens.
Keep the current validation and submission behavior.
Show the changed files and explain how to verify the result.
Inspect the diff: the added and removed lines, not just the rendered screenshot. Confirm that only relevant files changed. Investigate generated files, lockfiles, or configuration changes you did not expect before including them.
Review a narrow and wide viewport, a long label, validation feedback, and keyboard focus. Run the checks required by the repository. A screenshot shows appearance; it does not prove that a form still submits correctly.
Step 4. Commit and push the reviewed work
In GitHub Desktop, review the changed files, select the changes you intend to include, write a concise summary, and commit to your task branch. A local commit does not share the changes with the team until you push it.
For the command line, stage the actual file paths you reviewed. The path below is illustrative; replace it with the file you changed:
git add path/to/SettingsField.tsx
git diff --cached
git commit -m "fix(settings): use the shared field spacing"
git push -u origin fix/settings-field-spacing
Follow your repository's conventions. TDP's naming reference suggests type(scope): description for PR titles and a descriptive branch prefix when the team does not already have a convention. These are team conventions, not requirements imposed by GitHub.
| Item | Illustrative name |
|---|---|
| Branch | fix/settings-field-spacing |
| Commit | fix(settings): use the shared field spacing |
| Pull request | fix(settings): align label and input spacing |
Keep changes reviewable by purpose. There is no universal maximum number of changed lines for a pull request. Agree on scope with the reviewer, especially when a redesign needs several dependent changes.
Step 5. Open a pull request with visual evidence
On GitHub, open a pull request from your task branch into the agreed base branch. Check both branch names before submitting. A draft is useful for early feedback when the repository supports it. Request the appropriate reviewer when the change is ready.
Use the project's PR template first. If there is none, adapt this example:
## What changed
The settings field now uses the shared spacing token between its label and input.
## Why
The previous gap differed from the surrounding fields.
## How to review
1. Open the settings screen in the preview.
2. Compare the field with its neighboring controls.
3. Check a narrow viewport, a long label, and a validation error.
4. Navigate to the field using the keyboard.
## Evidence
- Before screenshot: [attach]
- After screenshot: [attach]
- Preview URL: [add if available]
- Checks run and results: [record actual checks]
## Open questions
[State anything unresolved, or write “None.”]
Do not mark checks as passed until you run them. Preview links depend on the project's deployment setup; a pull request does not guarantee that a preview exists. Include screenshots of the states you changed, not just an attractive default view.
Step 6. Address feedback and follow the merge process
Read review comments in context. Clarify a product decision if necessary, make the agreed changes on the same task branch, repeat the relevant checks, and push the new commits. The pull request updates with those commits.
If a conflict appears, understand both versions before resolving it. Do not discard another contributor's changes just to make the conflict go away. Ask the maintainer to help if you cannot determine the intended behavior.
Merge only through the team's agreed process and after required reviews and checks are satisfied. Merging integrates the code; whether it deploys immediately, waits for a release, or needs another step depends on the repository. Confirm the actual release or preview with the owner. Start the next unrelated task on a fresh branch from the current approved base.
When the first contribution gets confusing
If the application works locally but the reviewer sees a different result, compare the branch, commit, environment, and test data. A screenshot without that context can hide the difference. Confirm that your latest reviewed change was committed and pushed before asking someone to inspect it.
If unrelated files appear in the diff, identify why they changed before including them. Generated files may belong in the repository, but temporary logs, local configuration, and credentials usually do not. Follow the contribution instructions and ask the reviewer about unfamiliar files rather than discarding or committing them blindly.
When main has changed, use the team’s documented update process. A conflict means Git cannot automatically combine overlapping edits; it does not mean one side should simply be deleted. Read the intent of both changes, resolve the result, and rerun the relevant checks. If the conflict affects behavior you do not understand, involve the owner of that code.
Make review a conversation about the result
Respond to feedback with the decision and the evidence. If a reviewer asks for a spacing change, compare it with the approved component or token. If you disagree, explain the user-facing tradeoff and show the relevant state. This keeps review tied to the product rather than personal preference.
After addressing feedback, identify what changed and which checks you repeated. A new commit can invalidate an earlier screenshot or test result. Keep the final review evidence connected to the final code, then follow the team’s merge and deployment process.
Completion checklist
- The task branch and PR base match the team's workflow.
- The diff contains only intended changes.
- Relevant interface states and required checks were reviewed.
- The PR includes the problem, result, verification steps, and visual evidence.
- Review feedback and unresolved questions are addressed.
- The merge and deployment steps are understood separately.
Common questions
Do designers need the command line to use GitHub?
No. GitHub Desktop and the web interface support many common collaboration tasks. You still need to understand branches, commits, diffs, and review, whichever interface you choose. Running the application locally may require commands documented by the project.
Is saving a file the same as making a commit?
No. Saving updates the file on disk. A commit records the selected changes in Git history. Pushing shares commits with the remote repository.
Does merging a pull request make the change live?
Not necessarily. Deployment depends on the project's automation and release process. Ask where to verify the shipped version instead of inferring it from the merge button.
Can I use AI to write the code or PR description?
Yes, when your team permits it, but you still need to inspect the actual changes and verify the claims. Give the agent repository context, ask for a focused change, and review the diff before sharing it.