From 274a09bbc97657163b2eabf64a5c979987fd64c3 Mon Sep 17 00:00:00 2001 From: Andy Feller Date: Wed, 23 Apr 2025 10:11:51 -0400 Subject: [PATCH 1/6] Initial `gh accessibility` command draft This commit captures the initial command along with functionality and description. There is an internal discussion about the appropriate place for some of this content. --- pkg/cmd/accessibility/accessibility.go | 150 +++++++++++++++++++++++++ pkg/cmd/root/help.go | 11 +- pkg/cmd/root/root.go | 2 + 3 files changed, 161 insertions(+), 2 deletions(-) create mode 100644 pkg/cmd/accessibility/accessibility.go diff --git a/pkg/cmd/accessibility/accessibility.go b/pkg/cmd/accessibility/accessibility.go new file mode 100644 index 000000000..4992d488b --- /dev/null +++ b/pkg/cmd/accessibility/accessibility.go @@ -0,0 +1,150 @@ +package accessibility + +import ( + "fmt" + + "github.com/MakeNowJust/heredoc" + "github.com/cli/cli/v2/internal/browser" + "github.com/cli/cli/v2/internal/text" + "github.com/cli/cli/v2/pkg/cmdutil" + "github.com/cli/cli/v2/pkg/iostreams" + "github.com/spf13/cobra" +) + +const ( + communityURL = "https://github.com/orgs/community/discussions/categories/accessibility" +) + +type AccessibilityOptions struct { + IO *iostreams.IOStreams + Browser browser.Browser + Web bool +} + +func NewCmdAccessibility(f *cmdutil.Factory) *cobra.Command { + opts := AccessibilityOptions{ + IO: f.IOStreams, + Browser: f.Browser, + } + + cmd := &cobra.Command{ + Use: "accessibility", + Aliases: []string{"a11y"}, + Short: "Learn about GitHub CLI accessibility experience", + Long: longDescription(opts.IO), + Hidden: true, + RunE: func(cmd *cobra.Command, args []string) error { + if opts.Web { + if opts.IO.IsStdoutTTY() { + fmt.Fprintf(opts.IO.ErrOut, "Opening %s in your browser.\n", text.DisplayURL(communityURL)) + } + return opts.Browser.Browse(communityURL) + } + + return cmd.Help() + }, + Example: heredoc.Doc(` + # Open the GitHub Community Accessibility discussions in your browser + $ gh accessibility --web + + # Display color using customizable, 4-bit accessible colors + $ gh config set accessible_colors enabled + + # Display issue and pull request labels using RGB hex color codes in terminals that support 24-bit truecolor + $ gh config set color_labels enabled + + # Use input prompts without redrawing the screen + $ gh config set accessible_prompter enabled + + # Disable motion-based spinners for progress indicators in favor of text + $ gh config set spinner disabled + `), + } + + cmd.Flags().BoolVarP(&opts.Web, "web", "w", false, "Open the GitHub Community Accessibility discussions in the browser") + cmdutil.DisableAuthCheck(cmd) + + return cmd +} + +func longDescription(io *iostreams.IOStreams) string { + cs := io.ColorScheme() + title := cs.Bold("LEARN ABOUT GITHUB CLI ACCESSIBILITY EFFORTS") + color := cs.Bold("CUSTOMIZABLE AND CONTRASTING COLORS") + prompter := cs.Bold("NON-INTERACTIVE USER INPUT PROMPTING") + spinner := cs.Bold("TEXT-BASED SPINNERS") + + return heredoc.Docf(` + %[2]s + + As the home for all developers, we want every developer to feel welcome in our + community and be empowered to contribute to the future of global software + development with everything GitHub has to offer including the GitHub CLI. + + We invite you to join us in improving GitHub CLI accessibility by sharing your + feedback and ideas in the GitHub Community Accessibility discussions: + %[3]s + + + %[4]s + + Color is a common approach to enhance user experiences, however users can find + themselves with a worse experience due to insufficient contrast or + customizability. + + To create an accessible experience, CLIs should use color palettes based on + terminal background appearance and limit colors to 4-bit ANSI color palettes, + which users can customize within terminal preferences. + + With this new experience, the GitHub CLI provides multiple options to address + color usage: + + 1. The GitHub CLI will use 4-bit color palette for increased color contrast based on + dark and light backgrounds including rendering markdown based on GitHub Primer. + + To enable this experience, use one of the following methods: + - Run %[1]sgh config set accessible_colors enabled%[1]s + - Set %[1]sGH_ACCESSIBLE_COLORS=enabled%[1]s environment variable + + 2. The GitHub CLI will display issue and pull request labels' custom RGB colors + in terminals with truecolor support. + + To enable this experience, use one of the following methods: + - Run %[1]sgh config set color_labels enabled%[1]s + - Set %[1]sGH_COLOR_LABELS=enabled%[1]s environment variable + + + %[5]s + + Interactive text user interfaces are an advanced approach to enhance user + experiences, which manipulate the terminal cursor to redraw parts of the screen. + However, this can be difficult for speech synthesizers or braille displays to + accurately detect and read. + + To create an accessible experience, CLIs should give users the ability to disable + this interactivity while providing a similar experience. + + With this new experience, the GitHub CLI will use non-interactive prompts for + user input. + + To enable this experience, use one of the following methods: + - Run %[1]sgh config set accessible_prompter enabled%[1]s + - Set %[1]sGH_ACCESSIBLE_PROMPTER=enabled%[1]s environment variable + + + %[6]s + + Motion-based spinners are a common approach to communicate activity, which + manipulate the terminal cursor to create a spinning effect. However, this can be + difficult for users with motion sensitivity as well as speech synthesizers. + + To create an accessible experience, CLIs should give users the ability to disable + this interactivity while providing a similar experience. + + With this new experience, the GitHub CLI will use text-based progress indicators. + + To enable this experience, use one of the following methods: + - Run %[1]sgh config set spinner disabled%[1]s + - Set %[1]sGH_SPINNER_DISABLED=yes%[1]s environment variable + `, "`", title, communityURL, color, prompter, spinner) +} diff --git a/pkg/cmd/root/help.go b/pkg/cmd/root/help.go index 7f8fb1c2e..ec6499f21 100644 --- a/pkg/cmd/root/help.go +++ b/pkg/cmd/root/help.go @@ -109,8 +109,6 @@ func rootHelpFunc(f *cmdutil.Factory, command *cobra.Command, _ []string) { return } - namePadding := 12 - type helpEntry struct { Title string Body string @@ -135,6 +133,12 @@ func rootHelpFunc(f *cmdutil.Factory, command *cobra.Command, _ []string) { helpEntries = append(helpEntries, helpEntry{"ALIASES", strings.Join(BuildAliasList(command, command.Aliases), ", ") + "\n"}) } + // Statically calculated padding for non-extension commands, + // longest is `gh accessibility` with 13 characters + 1 space. + // + // Should consider novel way to calculate this in the future [AF] + namePadding := 14 + for _, g := range GroupedCommands(command) { var names []string for _, c := range g.Commands { @@ -148,6 +152,9 @@ func rootHelpFunc(f *cmdutil.Factory, command *cobra.Command, _ []string) { if isRootCmd(command) { var helpTopics []string + if c := findCommand(command, "accessibility"); c != nil { + helpTopics = append(helpTopics, rpad(c.Name()+":", namePadding)+c.Short) + } if c := findCommand(command, "actions"); c != nil { helpTopics = append(helpTopics, rpad(c.Name()+":", namePadding)+c.Short) } diff --git a/pkg/cmd/root/root.go b/pkg/cmd/root/root.go index c0dad93ec..8cf30db1b 100644 --- a/pkg/cmd/root/root.go +++ b/pkg/cmd/root/root.go @@ -6,6 +6,7 @@ import ( "strings" "github.com/MakeNowJust/heredoc" + accessibilityCmd "github.com/cli/cli/v2/pkg/cmd/accessibility" actionsCmd "github.com/cli/cli/v2/pkg/cmd/actions" aliasCmd "github.com/cli/cli/v2/pkg/cmd/alias" "github.com/cli/cli/v2/pkg/cmd/alias/shared" @@ -122,6 +123,7 @@ func NewCmdRoot(f *cmdutil.Factory, version, buildDate string) (*cobra.Command, // Child commands cmd.AddCommand(versionCmd.NewCmdVersion(f, version, buildDate)) + cmd.AddCommand(accessibilityCmd.NewCmdAccessibility(f)) cmd.AddCommand(actionsCmd.NewCmdActions(f)) cmd.AddCommand(aliasCmd.NewCmdAlias(f)) cmd.AddCommand(authCmd.NewCmdAuth(f)) From d7e2468286db92630a0393386d717aec3c46f0fb Mon Sep 17 00:00:00 2001 From: Andy Feller Date: Mon, 28 Apr 2025 15:01:15 -0400 Subject: [PATCH 2/6] Update a11y text based on draft feedback --- pkg/cmd/accessibility/accessibility.go | 89 +++++++++++++------------- pkg/cmd/root/help.go | 1 + 2 files changed, 44 insertions(+), 46 deletions(-) diff --git a/pkg/cmd/accessibility/accessibility.go b/pkg/cmd/accessibility/accessibility.go index 4992d488b..1d4a8009f 100644 --- a/pkg/cmd/accessibility/accessibility.go +++ b/pkg/cmd/accessibility/accessibility.go @@ -12,7 +12,7 @@ import ( ) const ( - communityURL = "https://github.com/orgs/community/discussions/categories/accessibility" + feedbackURL = "https://accessibility.github.com/feedback" ) type AccessibilityOptions struct { @@ -30,27 +30,27 @@ func NewCmdAccessibility(f *cmdutil.Factory) *cobra.Command { cmd := &cobra.Command{ Use: "accessibility", Aliases: []string{"a11y"}, - Short: "Learn about GitHub CLI accessibility experience", + Short: "Learn about GitHub CLI accessibility experiences", Long: longDescription(opts.IO), Hidden: true, RunE: func(cmd *cobra.Command, args []string) error { if opts.Web { if opts.IO.IsStdoutTTY() { - fmt.Fprintf(opts.IO.ErrOut, "Opening %s in your browser.\n", text.DisplayURL(communityURL)) + fmt.Fprintf(opts.IO.ErrOut, "Opening %s in your browser.\n", text.DisplayURL(feedbackURL)) } - return opts.Browser.Browse(communityURL) + return opts.Browser.Browse(feedbackURL) } return cmd.Help() }, Example: heredoc.Doc(` - # Open the GitHub Community Accessibility discussions in your browser + # Open the GitHub Accessibility site in your browser $ gh accessibility --web # Display color using customizable, 4-bit accessible colors $ gh config set accessible_colors enabled - # Display issue and pull request labels using RGB hex color codes in terminals that support 24-bit truecolor + # Display issue and pull request labels using RGB hex color codes in terminals that support 24-bit true color $ gh config set color_labels enabled # Use input prompts without redrawing the screen @@ -61,7 +61,7 @@ func NewCmdAccessibility(f *cmdutil.Factory) *cobra.Command { `), } - cmd.Flags().BoolVarP(&opts.Web, "web", "w", false, "Open the GitHub Community Accessibility discussions in the browser") + cmd.Flags().BoolVarP(&opts.Web, "web", "w", false, "Open the GitHub Accessibility site in your browser") cmdutil.DisableAuthCheck(cmd) return cmd @@ -69,10 +69,11 @@ func NewCmdAccessibility(f *cmdutil.Factory) *cobra.Command { func longDescription(io *iostreams.IOStreams) string { cs := io.ColorScheme() - title := cs.Bold("LEARN ABOUT GITHUB CLI ACCESSIBILITY EFFORTS") - color := cs.Bold("CUSTOMIZABLE AND CONTRASTING COLORS") - prompter := cs.Bold("NON-INTERACTIVE USER INPUT PROMPTING") - spinner := cs.Bold("TEXT-BASED SPINNERS") + title := cs.Bold("Learn about GitHub CLI accessibility experiences") + color := cs.Bold("Customizable and contrasting colors") + prompter := cs.Bold("Non-interactive user input prompting") + spinner := cs.Bold("Text-based spinners") + feedback := cs.Bold("Join the conversation") return heredoc.Docf(` %[2]s @@ -81,70 +82,66 @@ func longDescription(io *iostreams.IOStreams) string { community and be empowered to contribute to the future of global software development with everything GitHub has to offer including the GitHub CLI. - We invite you to join us in improving GitHub CLI accessibility by sharing your - feedback and ideas in the GitHub Community Accessibility discussions: %[3]s + Text interfaces often use color for various purposes, but insufficient contrast + or customizability can leave some users unable to benefit. - %[4]s - - Color is a common approach to enhance user experiences, however users can find - themselves with a worse experience due to insufficient contrast or - customizability. - - To create an accessible experience, CLIs should use color palettes based on - terminal background appearance and limit colors to 4-bit ANSI color palettes, - which users can customize within terminal preferences. + To create a more accessible experience, the GitHub CLI will use color palettes + based on terminal background appearance and limit colors to 4-bit ANSI color + palettes, which users can customize within terminal preferences. With this new experience, the GitHub CLI provides multiple options to address color usage: - 1. The GitHub CLI will use 4-bit color palette for increased color contrast based on - dark and light backgrounds including rendering markdown based on GitHub Primer. + 1. The GitHub CLI will use 4-bit color palette for increased color contrast based + on dark and light backgrounds including rendering Markdown based on the + GitHub Primer design system. To enable this experience, use one of the following methods: - Run %[1]sgh config set accessible_colors enabled%[1]s - Set %[1]sGH_ACCESSIBLE_COLORS=enabled%[1]s environment variable 2. The GitHub CLI will display issue and pull request labels' custom RGB colors - in terminals with truecolor support. + in terminals with true color support. To enable this experience, use one of the following methods: - Run %[1]sgh config set color_labels enabled%[1]s - Set %[1]sGH_COLOR_LABELS=enabled%[1]s environment variable + %[4]s - %[5]s + Interactive text user interfaces manipulate the terminal cursor to redraw parts + of the screen, which can be difficult for speech synthesizers or braille displays + to accurately detect and read. - Interactive text user interfaces are an advanced approach to enhance user - experiences, which manipulate the terminal cursor to redraw parts of the screen. - However, this can be difficult for speech synthesizers or braille displays to - accurately detect and read. - - To create an accessible experience, CLIs should give users the ability to disable - this interactivity while providing a similar experience. - - With this new experience, the GitHub CLI will use non-interactive prompts for - user input. + To create a more accessible experience, the GitHub CLI gives users the ability to + disable this interactivity while providing a similar experience using + non-interactive prompts for user input. To enable this experience, use one of the following methods: - Run %[1]sgh config set accessible_prompter enabled%[1]s - Set %[1]sGH_ACCESSIBLE_PROMPTER=enabled%[1]s environment variable + %[5]s - %[6]s + Motion-based spinners communicate in-progress activity by manipulating the + terminal cursor to create a spinning effect, which can be difficult for users + with motion sensitivity or miscommunicate information to speech synthesizers. - Motion-based spinners are a common approach to communicate activity, which - manipulate the terminal cursor to create a spinning effect. However, this can be - difficult for users with motion sensitivity as well as speech synthesizers. - - To create an accessible experience, CLIs should give users the ability to disable - this interactivity while providing a similar experience. - - With this new experience, the GitHub CLI will use text-based progress indicators. + To create a more accessible experience, the GitHub CLI gives users the ability to + disable this interactivity while providing a similar experience using text-based + progress indicators. To enable this experience, use one of the following methods: - Run %[1]sgh config set spinner disabled%[1]s - Set %[1]sGH_SPINNER_DISABLED=yes%[1]s environment variable - `, "`", title, communityURL, color, prompter, spinner) + + %[6]s + + We invite you to join us in improving GitHub CLI accessibility by sharing your + feedback and ideas through GitHub Accessibility feedback channels: + + %[7]s + `, "`", title, color, prompter, spinner, feedback, feedbackURL) } diff --git a/pkg/cmd/root/help.go b/pkg/cmd/root/help.go index ec6499f21..2676cdd15 100644 --- a/pkg/cmd/root/help.go +++ b/pkg/cmd/root/help.go @@ -190,6 +190,7 @@ func rootHelpFunc(f *cmdutil.Factory, command *cobra.Command, _ []string) { Use %[1]sgh --help%[1]s for more information about a command. Read the manual at https://cli.github.com/manual Learn about exit codes using %[1]sgh help exit-codes%[1]s + Learn about accessibility experiences using %[1]sgh help accessibility%[1]s `, "`")}) out := f.IOStreams.Out From 096106a3d703ce9c8177b6608b58f6338f5478f0 Mon Sep 17 00:00:00 2001 From: Andy Feller Date: Wed, 30 Apr 2025 14:20:16 -0400 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Melissa Xie --- pkg/cmd/accessibility/accessibility.go | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/pkg/cmd/accessibility/accessibility.go b/pkg/cmd/accessibility/accessibility.go index 1d4a8009f..f05bc7bcc 100644 --- a/pkg/cmd/accessibility/accessibility.go +++ b/pkg/cmd/accessibility/accessibility.go @@ -30,7 +30,7 @@ func NewCmdAccessibility(f *cmdutil.Factory) *cobra.Command { cmd := &cobra.Command{ Use: "accessibility", Aliases: []string{"a11y"}, - Short: "Learn about GitHub CLI accessibility experiences", + Short: "Learn about GitHub CLI's accessibility experiences", Long: longDescription(opts.IO), Hidden: true, RunE: func(cmd *cobra.Command, args []string) error { @@ -87,7 +87,7 @@ func longDescription(io *iostreams.IOStreams) string { Text interfaces often use color for various purposes, but insufficient contrast or customizability can leave some users unable to benefit. - To create a more accessible experience, the GitHub CLI will use color palettes + For a more accessible experience, the GitHub CLI can use color palettes based on terminal background appearance and limit colors to 4-bit ANSI color palettes, which users can customize within terminal preferences. @@ -115,8 +115,7 @@ func longDescription(io *iostreams.IOStreams) string { of the screen, which can be difficult for speech synthesizers or braille displays to accurately detect and read. - To create a more accessible experience, the GitHub CLI gives users the ability to - disable this interactivity while providing a similar experience using + For a more accessible experience, the GitHub CLI can provide a similar experience using non-interactive prompts for user input. To enable this experience, use one of the following methods: @@ -126,12 +125,11 @@ func longDescription(io *iostreams.IOStreams) string { %[5]s Motion-based spinners communicate in-progress activity by manipulating the - terminal cursor to create a spinning effect, which can be difficult for users + terminal cursor to create a spinning effect, which may cause discomfort to users with motion sensitivity or miscommunicate information to speech synthesizers. - To create a more accessible experience, the GitHub CLI gives users the ability to - disable this interactivity while providing a similar experience using text-based - progress indicators. + For a more accessible experience, this interactivity can be disabled in favor + of text-based progress indicators. To enable this experience, use one of the following methods: - Run %[1]sgh config set spinner disabled%[1]s From 2fd1a45a81ae6466dea5598ce9825f984a6fb770 Mon Sep 17 00:00:00 2001 From: Andy Feller Date: Wed, 30 Apr 2025 14:21:02 -0400 Subject: [PATCH 4/6] Update pkg/cmd/accessibility/accessibility.go --- pkg/cmd/accessibility/accessibility.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/cmd/accessibility/accessibility.go b/pkg/cmd/accessibility/accessibility.go index f05bc7bcc..d37631d25 100644 --- a/pkg/cmd/accessibility/accessibility.go +++ b/pkg/cmd/accessibility/accessibility.go @@ -69,7 +69,7 @@ func NewCmdAccessibility(f *cmdutil.Factory) *cobra.Command { func longDescription(io *iostreams.IOStreams) string { cs := io.ColorScheme() - title := cs.Bold("Learn about GitHub CLI accessibility experiences") + title := cs.Bold("Learn about GitHub CLI's accessibility experiences") color := cs.Bold("Customizable and contrasting colors") prompter := cs.Bold("Non-interactive user input prompting") spinner := cs.Bold("Text-based spinners") From c20138d8442457c5c6f326fdbd13d73e47b06a32 Mon Sep 17 00:00:00 2001 From: Andy Feller Date: Wed, 30 Apr 2025 14:35:35 -0400 Subject: [PATCH 5/6] Update pkg/cmd/accessibility/accessibility.go --- pkg/cmd/accessibility/accessibility.go | 3 --- 1 file changed, 3 deletions(-) diff --git a/pkg/cmd/accessibility/accessibility.go b/pkg/cmd/accessibility/accessibility.go index d37631d25..19fb813a4 100644 --- a/pkg/cmd/accessibility/accessibility.go +++ b/pkg/cmd/accessibility/accessibility.go @@ -50,9 +50,6 @@ func NewCmdAccessibility(f *cmdutil.Factory) *cobra.Command { # Display color using customizable, 4-bit accessible colors $ gh config set accessible_colors enabled - # Display issue and pull request labels using RGB hex color codes in terminals that support 24-bit true color - $ gh config set color_labels enabled - # Use input prompts without redrawing the screen $ gh config set accessible_prompter enabled From 830335d9209d399ae1415ec927dd4d00ea1e0ab2 Mon Sep 17 00:00:00 2001 From: Andy Feller Date: Wed, 30 Apr 2025 15:05:07 -0400 Subject: [PATCH 6/6] PR feedback --- pkg/cmd/accessibility/accessibility.go | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/pkg/cmd/accessibility/accessibility.go b/pkg/cmd/accessibility/accessibility.go index 19fb813a4..c5de6c1a4 100644 --- a/pkg/cmd/accessibility/accessibility.go +++ b/pkg/cmd/accessibility/accessibility.go @@ -12,7 +12,7 @@ import ( ) const ( - feedbackURL = "https://accessibility.github.com/feedback" + webURL = "https://accessibility.github.com/conformance/cli/" ) type AccessibilityOptions struct { @@ -36,9 +36,9 @@ func NewCmdAccessibility(f *cmdutil.Factory) *cobra.Command { RunE: func(cmd *cobra.Command, args []string) error { if opts.Web { if opts.IO.IsStdoutTTY() { - fmt.Fprintf(opts.IO.ErrOut, "Opening %s in your browser.\n", text.DisplayURL(feedbackURL)) + fmt.Fprintf(opts.IO.ErrOut, "Opening %s in your browser.\n", text.DisplayURL(webURL)) } - return opts.Browser.Browse(feedbackURL) + return opts.Browser.Browse(webURL) } return cmd.Help() @@ -125,7 +125,7 @@ func longDescription(io *iostreams.IOStreams) string { terminal cursor to create a spinning effect, which may cause discomfort to users with motion sensitivity or miscommunicate information to speech synthesizers. - For a more accessible experience, this interactivity can be disabled in favor + For a more accessible experience, this interactivity can be disabled in favor of text-based progress indicators. To enable this experience, use one of the following methods: @@ -138,5 +138,5 @@ func longDescription(io *iostreams.IOStreams) string { feedback and ideas through GitHub Accessibility feedback channels: %[7]s - `, "`", title, color, prompter, spinner, feedback, feedbackURL) + `, "`", title, color, prompter, spinner, feedback, webURL) }