Reinstating Primer Style CLI content within `cli/cli` repository #11060

andyfeller · 2025-06-02T20:21:42Z

This draft pull request is to open a discussion with maintainers and contributors about bringing https://github.com/primer/cli/ content into cli/cli repository.

These design documents formed the basis of how the GitHub CLI was designed and have provided guidance to date. This is a precursor to expanding these docs based upon the work done in v2.72.0 with accessibility enhancements.

This commit brings the https://github.com/primer/cli/ content into the repository for contributors and maintainers. Minimal changes to the original content have been made as this is being hosted as pure markdown.

Help content automatically render

BagToad · 2025-06-02T21:35:15Z

Love it! I miss having this resource, so I'm very happy to see it come back in some form, especially one that we can improve more directly.

Some random questions that come to mind:

should we decouple this from primer? Wondering if we should rename it to avoid confusion and also take full responsibility of the content.
should this be treated as a part of a larger cli/cli style guide that includes design and implementation/code specific guidance. This is a bit of a question hiding as an idea - to me this is a component of a larger engineering guidelines story and it might make sense to ponder how it fits into the big picture.
are we changing licenses by republishing it here? I'm not sure with what licensing the original primer CLI docs were under. It probably doesn't matter but it came to mind.
do we ever envision this showing up on a GitHub CLI web page like cli.github.com/something? More of a curiosity driven question since I'm not even sure if I want that myself.

Copilot

Pull Request Overview

This PR reinstates the Primer Style CLI design content into the cli/cli repository, bringing in foundational guidelines that shaped the GitHub CLI’s design and paving the way for expanded accessibility and style documentation.

Adds a “Getting Started” primer with core design principles and process steps.
Adds a “Foundations” primer covering language, typography, spacing, color, and more.
Adds a “Components” primer detailing syntax, prompts, state, and UI patterns.
Introduces a top-level docs/primer/README.md linking all primer sections.

Reviewed Changes

Copilot reviewed 4 out of 48 changed files in this pull request and generated 2 comments.

File	Description
docs/primer/getting-started/README.md	Added core principles, process guidance, and prototyping tips.
docs/primer/foundations/README.md	Added foundational design constraints and accessibility notes.
docs/primer/components/README.md	Added reusable UI pattern definitions for CLI components.
docs/primer/README.md	Added top‐level navigation to primer sections.

Comments suppressed due to low confidence (2)

docs/primer/getting-started/README.md:54

The backslash before the asterisk appears unintended and will render a literal '*'. Remove the backslash or rephrase to avoid stray characters.

- Ensure similar commands are visually and behaviorally parallel. \* For example, any create command should behave the same

docs/primer/getting-started/README.md:55

Remove the escape before the asterisk to prevent rendering a stray '*', or reword this bullet without the backslash.

- Anticipate what people might want to do next. \* For example, we ask if you want to delete your branch after you merge.

docs/primer/getting-started/README.md

Copilot · 2025-07-02T15:32:08Z

docs/primer/getting-started/README.md

+Use [this template](https://docs.google.com/document/d/1JIRErIUuJ6fTgabiFYfCH3x91pyHuytbfa0QLnTfXKM/edit?usp=sharing), or format your document with these steps:
+
+1. Choose a dark background (File > Page Setup > Page Color)
+1. Choose a light text color


[nitpick] See previous comment: update list numbering to '2.' for this item to reflect sequence.

williammartin

Fantastic. No notes.

williammartin

Well, maybe one note that we might want to link to here from the main README or from CONTRIBUTING.md

andyfeller · 2025-07-05T18:54:58Z

Well, maybe one note that we might want to link to here from the main README or from CONTRIBUTING.md

praise: good catch! apparently there was a link to the old section within the Primer Style site, so I just updated it to point to these new docs

cli/.github/CONTRIBUTING.md

Lines 53 to 65 in 89f15e9

    
           ## Design guidelines 
        
           ### Proposing a design 
        
           You may propose a design to solve an open bug or feature request issue that has both [the `needs-design` and `help-wanted` labels][needs design and help wanted]. 
        
           To propose a design: 
        
           - Open a new issue using the [design proposal issue template](./ISSUE_TEMPLATE/submit-a-design-proposal.md). 
        
           - Include a link to the issue that the design is for. 
        
           - Describe the design you are proposing to resolve the issue, leveraging the [CLI Design System][]. 
        
           - Mock up the design you are proposing using our [Google Docs Template][] or code blocks. 
        
             - Mock ups should clearly illustrate the command(s) being run and the expected output(s).

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [cli/cli](https://github.com/cli/cli) | minor | `v2.74.2` -> `v2.76.1` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>cli/cli (cli/cli)</summary> ### [`v2.76.1`](https://github.com/cli/cli/releases/tag/v2.76.1): GitHub CLI 2.76.1 [Compare Source](cli/cli@v2.76.0...v2.76.1) #### `gh pr create` regression fix This release fixes a regression introduced in `v2.76.0` where organization teams were retrieved outside of intentional use cases. This caused problems for GitHub Enterprise Server users using the GitHub Actions automatic token that does not have access to organization teams. For more information, see cli/cli#11360 #### What's Changed ##### 🐛 Fixes - Fix: `gh pr create`, only fetch teams when reviewers contain a team by [@BagToad](https://github.com/BagToad) in cli/cli#11361 ##### 📚 Docs & Chores - add tenancy aware for san matcher by [@ejahnGithub](https://github.com/ejahnGithub) in cli/cli#11261 - Run Lint and Tests on `push` to `trunk` branch by [@andyfeller](https://github.com/andyfeller) in cli/cli#11325 - update ownership of pkg/cmd/release/shared/ by [@ejahnGithub](https://github.com/ejahnGithub) in cli/cli#11326 - Automate spam issue detection by [@babakks](https://github.com/babakks) in cli/cli#11316 - Improve `api` `--preview` docs by [@jsoref](https://github.com/jsoref) in cli/cli#11274 - Incorporate govulncheck into workflows by [@andyfeller](https://github.com/andyfeller) in cli/cli#11332 - chore(deps): bump advanced-security/filter-sarif from 1.0.0 to 1.0.1 by [@dependabot](https://github.com/dependabot)\[bot] in cli/cli#11298 - chore(deps): bump github.com/sigstore/sigstore-go from 1.0.0 to 1.1.0 by [@dependabot](https://github.com/dependabot)\[bot] in cli/cli#11307 **Full Changelog**: cli/cli@v2.76.0...v2.76.1 ### [`v2.76.0`](https://github.com/cli/cli/releases/tag/v2.76.0): GitHub CLI 2.76.0 [Compare Source](cli/cli@v2.75.1...v2.76.0) ####

Copilot Coding Agent Support GitHub Copilot Pro+ and Copilot Enterprise subscribers can now assign issues to GitHub Copilot during issue creation using: - Command-line flag: `gh issue create --assignee @copilot` - Launching web browser: `gh issue create --assignee @copilot --web` - Or interactively selecting `Copilot (AI)` as assignee in `gh issue create` metadata For more details, refer to [the full changelog post for Copilot coding agent](https://github.blog/changelog/2025-05-19-github-copilot-coding-agent-in-public-preview/). #### What's Changed ##### ✨ Features - Assign Copilot during `gh issue create` by [@andyfeller](https://github.com/andyfeller) in cli/cli#11279 - Display immutable field in `release view` command by [@bdehamer](https://github.com/bdehamer) in cli/cli#11251 ##### 🐛 Fixes - FIX: Do not fetch logs for skipped jobs by [@babakks](https://github.com/babakks) in cli/cli#11312 - Transform `extension` and `filename` qualifiers into `path` qualifier for web code search by [@samcoe](https://github.com/samcoe) in cli/cli#11211 ##### 📚 Docs & Chores - FIX: Workflow does not contain permissions by [@BagToad](https://github.com/BagToad) in cli/cli#11322 - Add automated feature request response workflow by [@BagToad](https://github.com/BagToad) in cli/cli#11299 **Full Changelog**: cli/cli@v2.75.1...v2.76.0 ### [`v2.75.1`](https://github.com/cli/cli/releases/tag/v2.75.1): GitHub CLI 2.75.1 [Compare Source](cli/cli@v2.75.0...v2.75.1) #### What's Changed ##### 🐛 Fixes - Ensure hostnames are visible in CLI website by [@andyfeller](https://github.com/andyfeller) in cli/cli#11295 - Revert "Fix: `gh pr create` prioritize `--title` and `--body` over `--fill` when `--web` is present" by [@andyfeller](https://github.com/andyfeller) in cli/cli#11300 ##### 📚 Docs & Chores - Ensure go directive is always .0 version in bump by [@williammartin](https://github.com/williammartin) in cli/cli#11259 - Minor (1-word) documentation typo in generated `~/.config/gh/config.yml` by [@kurahaupo](https://github.com/kurahaupo) in cli/cli#11246 - Automate closing of stale issues by [@babakks](https://github.com/babakks) in cli/cli#11268 - Filter the `third-party/` folder out of CodeQL results by [@BagToad](https://github.com/BagToad) in cli/cli#11278 - Exclude `third-party` source from golangci-lint by [@andyfeller](https://github.com/andyfeller) in cli/cli#11293 #####

Dependencies - Bump Go to 1.24.5 by [@github-actions](https://github.com/github-actions)\[bot] in cli/cli#11255 - chore(deps): bump github.com/sigstore/protobuf-specs from 0.4.3 to 0.5.0 by [@dependabot](https://github.com/dependabot)\[bot] in cli/cli#11263 - chore(deps): bump golang.org/x/term from 0.32.0 to 0.33.0 by [@dependabot](https://github.com/dependabot)\[bot] in cli/cli#11266 - chore(deps): bump golang.org/x/sync from 0.15.0 to 0.16.0 by [@dependabot](https://github.com/dependabot)\[bot] in cli/cli#11264 - chore(deps): bump golang.org/x/text from 0.26.0 to 0.27.0 by [@dependabot](https://github.com/dependabot)\[bot] in cli/cli#11265 - chore(deps): bump golang.org/x/crypto from 0.39.0 to 0.40.0 by [@dependabot](https://github.com/dependabot)\[bot] in cli/cli#11275 #### New Contributors - [@kurahaupo](https://github.com/kurahaupo) made their first contribution in cli/cli#11246 - [@github-actions](https://github.com/github-actions)\[bot] made their first contribution in cli/cli#11255 **Full Changelog**: cli/cli@v2.75.0...v2.75.1 ### [`v2.75.0`](https://github.com/cli/cli/releases/tag/v2.75.0): GitHub CLI 2.75.0 [Compare Source](cli/cli@v2.74.2...v2.75.0) #### What's Changed ##### ✨ Features - init release verify subcommands by [@ejahnGithub](https://github.com/ejahnGithub) in cli/cli#11018 - Embed Windows resources (VERSIONINFO) during build by [@babakks](https://github.com/babakks) in cli/cli#11048 - Support `--no-repos-selected` on `gh secret set` by [@williammartin](https://github.com/williammartin) in cli/cli#11217 ##### 🐛 Fixes - Fix: `gh pr create` prioritize `--title` and `--body` over `--fill` when `--web` is present by [@dankrzeminski32](https://github.com/dankrzeminski32) in cli/cli#10547 - fix: get token for active user instead of blank if possible by [@anuraaga](https://github.com/anuraaga) in cli/cli#11038 - Use Actions API to retrieve job run logs as a fallback mechanism by [@babakks](https://github.com/babakks) in cli/cli#11172 - Fix query object state mutation during pagination by [@babakks](https://github.com/babakks) in cli/cli#11244 - Handle `HTTP 404` when deleting remote branch in `pr merge` by [@babakks](https://github.com/babakks) in cli/cli#11234 ##### 📚 Docs & Chores - chore: fix function name by [@jinjingroad](https://github.com/jinjingroad) in cli/cli#11149 - chore: update Go version to 1.24 in devcontainer configuration and docs by [@tMinamiii](https://github.com/tMinamiii) in cli/cli#11158 - Ensure lint workflow checks whether 3rd party license and code is up to date by [@andyfeller](https://github.com/andyfeller) in cli/cli#11047 - docs: install\_linux.md: add Solus linux install instructions by [@chax](https://github.com/chax) in cli/cli#10823 - Fix missing newline in install\_linux.md by [@BagToad](https://github.com/BagToad) in cli/cli#11160 - Ensure automation uses pinned go-licenses version by [@andyfeller](https://github.com/andyfeller) in cli/cli#11161 - Add `workflow_dispatch` support to MR Help Wanted check by [@BagToad](https://github.com/BagToad) in cli/cli#11179 - Remove unused `GH_TOKEN` env variable from workflow by [@BagToad](https://github.com/BagToad) in cli/cli#11190 - Add workflow to automate go version bumping by [@williammartin](https://github.com/williammartin) in cli/cli#11189 - Fix inconsistent use of tabs and spaces by [@Stefan-Heimersheim](https://github.com/Stefan-Heimersheim) in cli/cli#11194 - Decouple arg parsing from MR finder by [@babakks](https://github.com/babakks) in cli/cli#11192 - docs: consistently use `apt` in installation instructions by [@tklauser](https://github.com/tklauser) in cli/cli#11216 - Ensure bump go script has git user configured by [@williammartin](https://github.com/williammartin) in cli/cli#11229 - Inject token into bump-go workflow by [@williammartin](https://github.com/williammartin) in cli/cli#11233 - Reinstating Primer Style CLI content within `cli/cli` repository by [@andyfeller](https://github.com/andyfeller) in cli/cli#11060 - Add setup-go to bump-go workflow by [@williammartin](https://github.com/williammartin) in cli/cli#11237 - Ensure GoReleaser does not break on Mac OS and Linux when skipping Windows `.rsyso` generation script by [@andyfeller](https://github.com/andyfeller) in cli/cli#11257 #####

Dependencies - Bump all dependencies except dev-tunnels by [@williammartin](https://github.com/williammartin) in cli/cli#11203 - Update microsoft dev-tunnels to v0.1.13 by [@williammartin](https://github.com/williammartin) in cli/cli#11205 - Consume dependabot minor versions for go modules by [@williammartin](https://github.com/williammartin) in cli/cli#11213 #### New Contributors - [@jinjingroad](https://github.com/jinjingroad) made their first contribution in cli/cli#11149 - [@tMinamiii](https://github.com/tMinamiii) made their first contribution in cli/cli#11158 - [@chax](https://github.com/chax) made their first contribution in cli/cli#10823 - [@dankrzeminski32](https://github.com/dankrzeminski32) made their first contribution in cli/cli#10547 - [@anuraaga](https://github.com/anuraaga) made their first contribution in cli/cli#11038 - [@Stefan-Heimersheim](https://github.com/Stefan-Heimersheim) made their first contribution in cli/cli#11194 **Full Changelog**: cli/cli@v2.74.2...v2.75.0 </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

Hasnahbokhari1990 · 2025-07-30T04:35:16Z

docs/primer/README.md

+
+Design guidance on how we format content in in the Terminal through text formatting, color and font weights.
+
+## [Foundations](foundations)


andyfeller added 5 commits June 2, 2025 16:08

Initial restore of Primer CLI docs

e6cc90a

This commit brings the https://github.com/primer/cli/ content into the repository for contributors and maintainers. Minimal changes to the original content have been made as this is being hosted as pure markdown.

Rename READMEs

a9468ae

Help content automatically render

Add missing files

3008aba

Fix spacing

180f629

Primer formatting

4ba6d05

andyfeller temporarily deployed to cli-automation June 2, 2025 20:21 — with GitHub Actions Inactive

andyfeller marked this pull request as ready for review July 2, 2025 15:31

Copilot AI review requested due to automatic review settings July 2, 2025 15:31

andyfeller requested a review from a team as a code owner July 2, 2025 15:31

andyfeller requested a review from williammartin July 2, 2025 15:31

andyfeller temporarily deployed to cli-automation July 2, 2025 15:31 — with GitHub Actions Inactive

cliAutomation assigned andyfeller Jul 2, 2025

Copilot AI reviewed Jul 2, 2025

View reviewed changes

williammartin approved these changes Jul 3, 2025

View reviewed changes

williammartin reviewed Jul 3, 2025

View reviewed changes

Update contribution design link

89f15e9

andyfeller enabled auto-merge July 5, 2025 18:55

andyfeller merged commit d033770 into trunk Jul 5, 2025
15 checks passed

andyfeller deleted the andyfeller/cli-primer-prototype branch July 5, 2025 19:02

Hasnahbokhari1990 reviewed Jul 30, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Reinstating Primer Style CLI content within `cli/cli` repository #11060

Reinstating Primer Style CLI content within `cli/cli` repository #11060

Uh oh!

andyfeller commented Jun 2, 2025

Uh oh!

BagToad commented Jun 2, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI Jul 2, 2025

Uh oh!

williammartin left a comment

Uh oh!

williammartin left a comment

Uh oh!

andyfeller commented Jul 5, 2025

Uh oh!

Uh oh!

Hasnahbokhari1990 Jul 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		Design guidance on how we format content in in the Terminal through text formatting, color and font weights.

		## [Foundations](foundations)

Reinstating Primer Style CLI content within cli/cli repository #11060

Reinstating Primer Style CLI content within cli/cli repository #11060

Uh oh!

Conversation

andyfeller commented Jun 2, 2025

Uh oh!

BagToad commented Jun 2, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Copilot AI Jul 2, 2025

Choose a reason for hiding this comment

Uh oh!

williammartin left a comment

Choose a reason for hiding this comment

Uh oh!

williammartin left a comment

Choose a reason for hiding this comment

Uh oh!

andyfeller commented Jul 5, 2025

Uh oh!

Uh oh!

Hasnahbokhari1990 Jul 30, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Reinstating Primer Style CLI content within `cli/cli` repository #11060

Reinstating Primer Style CLI content within `cli/cli` repository #11060