Designing for the Command Line Interface

A first version of this note was published on the blog of Specify.

In a world where we’re surrounded by screens everywhere, we tend to forget what a significant portion of today’s makers are experiencing when giving life to digital products. A dark blank canvas, with less than 1,000 pixels in width and 800 pixels in height with no other animations than a blinking box. Welcome to the terminal, the mid-1960s interface people use on the first computers and that we still use nowadays.

Tools like Warp, iTerm, Hyper.js, and ZSH, are sometimes the first ones to be installed on developers’ machines when setting up, as the terminal is one of their primary tools. Developers may also add customization and powerful features to make their terminal a little friendlier.

At Specify, we provide a CLI to developers to let them interact with our Design Data Platform. The Specify CLI helps you sync design tokens and assets from Sources, like a Figma file, and to pull them to get a fully configurable output directly in their codebase — whatever your technologies are.

Context

The Specify CLI is the developer tool companion for configuration file creation and iteration. It provides you feedback to validate your configuration and help you understand the logic behind rules and parsers.

Under the hood, Specify requires users to provide configuration files to transform their design data (colors, text styles, icons, etc.): changing the case, adding suffixes or prefixes, converting values, creating files in the right place with the correct name.

To be validated, these configuration files need to respect a specific structure. We improved our Command Line Interface (CLI) to provide meaningful feedback with hints, warnings, and error messages.

Research

I researched CLI patterns, best-in-class examples, Amanda Pinsker's Config talk about GitHub CLI, read Command Line Interface Guidelines.

I also paid closer attention to the CLI tools I was already using and created a moodboard with examples of NPM, Yarn, GitHub, JEST, Stripe, Squoosh, and Typescript Tests.

Stack

We listed what we needed with engineers and choose to use Ink and Chalk for this project to achieve these desired UI results:

• indent information on multiple levels with progress bars for each

• apply color and background color / highlight to text

• display progress bars

Building

Command line interface being probably the interface users can customize the most, I had to try multiple configurations: light/dark mode, color schemes, density, and fonts.

Colors

After digging into the American National Standards Institute (ANSI) colors, I realized I would have to deal with a rigorous amount of shades, 38 precisely:

• 16 ANSI colors (black, red, green, yellow, blue, magenta, cyan) with a normal and bright version for each one

• and 3 “basic” ones for the foreground, background, and links — note that there is no user preference detection regarding light or dark themes affecting the background and foreground colors here.

Each of these 19 colors has a dimmed variation (around 50% opacity) — leading to a total of 38 colors.

Iconography

Then, I started exploring UTF-8 possibilities and characters available for progress bars, indents, and feedback icons, like a checkmark for successes, an exclamation point for warnings, or a cross for errors, as icons can't be displayed on terminals. Finally, I ended up with enough symbols to cover all use cases.

Typography

Similar to colors, users can override both font choices and font parameters (font size, leading, kerning, etc.). As a rule of thumb, I used a monospace font1 to have the most representative idea of the final interface.

The only thing you can control is proportion. So I paid a lot of attention to the spacing system applied and when to use bold vs. keeping a regular font weight — while keeping in mind that the final display behaves like an airport flight table with rows and columns and a fixed-size box.

Spacing

Horizontal spacings should use the width of a character (same for each character with a monospace font) while vertical spacings should use the same height as a character’s line height (or leading).

Components

I created components and variants in Figma using Variants2, and engineers replicated them in React. To mimic the reality as far as possible in Figma, I created a set of Interactive Components3 for the header, progress bar, and processed rule.

As a result, we got 12 high-fidelity prototypes and iterated with engineers on successful extractions, error states, sync, help, new version, trial end, and missing payment.