mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-06-20 16:26:44 -07:00
feat: migrate UX tools to a formal Extension (ux-toolkit)
This commit is contained in:
Keith Guerin
@@ -0,0 +1,25 @@
|
||||
# UX Toolkit: Extension Context
|
||||
|
||||
This extension provides the specialized toolset for the AI DevTools UX team.
|
||||
When this extension is active, the agent must adhere to the following standards
|
||||
and workflows.
|
||||
|
||||
## 🚨 Agent Directives
|
||||
|
||||
1. **Worktree Strategy**: Always prefer the **Base Folder Strategy**. Use
|
||||
`_ux_git-worktree` to manage sibling directories for all tasks.
|
||||
2. **PR Maintenance**: Use `_ux_finish-pr` to handle the final polish of pull
|
||||
requests, ensuring all tests pass and snapshots are updated.
|
||||
3. **UI Review**: Use `_ux_designer` to audit any new Ink/React components
|
||||
against the v1.0 Design Principles (Density, Progressive Disclosure, State).
|
||||
4. **UX Writing**: Use `_ux_string-reviewer` to ensure all user-facing strings
|
||||
comply with project terminology and clarity rules.
|
||||
|
||||
## Mandatory Workflow
|
||||
|
||||
- **ALWAYS** use the `_ux_git-worktree` skill for branch management.
|
||||
- **ALWAYS** use the `_ux_finish-pr` skill for pull request maintenance.
|
||||
- Never use standard `git checkout -b`.
|
||||
- Use `worktree-manager.sh pr <number>` for semantic PR checkouts.
|
||||
- When operating in a worktree, ensure the primary `main/.git` path is included
|
||||
in your trusted directories to bypass macOS sandbox restrictions.
|
||||
@@ -0,0 +1,40 @@
|
||||
# 🚀 Welcome to the UX Team "Global Toolbox"
|
||||
|
||||
You have successfully installed the Gemini CLI UX power-ups!
|
||||
|
||||
These tools are designed to help us sprint toward the **Gemini 1.0 Milestone**
|
||||
without fighting the CLI. They are "opinionated" and built specifically for the
|
||||
UX "Vibe Coding" workflow.
|
||||
|
||||
## 🛠️ Your New Superpowers
|
||||
|
||||
You now have four new commands available in your Gemini CLI session. Because
|
||||
they are synced globally, **you can use them on any branch.**
|
||||
|
||||
- `/_ux_git-worktree` : Ditch nested branches! Use this to manage your tasks in
|
||||
parallel sibling folders (Base Folder Strategy). It auto-runs `npm install`
|
||||
for you!
|
||||
- `/_ux_finish-pr` : Your co-author assistant. It runs tests, updates snapshots,
|
||||
fixes CI linting, and squashes your messy trial-and-error commits before
|
||||
force-pushing.
|
||||
- `/_ux_designer` : Run this against your new React/Ink components to guarantee
|
||||
they adhere to the v1.0 strict standards (Signal over Noise, Coherent State,
|
||||
Density).
|
||||
- `/string-reviewer` : Audits UI text for strict adherence to the project
|
||||
terminology.
|
||||
|
||||
## 🧠 Why are we doing this?
|
||||
|
||||
We are intentionally keeping these tools in a "floating" Draft PR branch rather
|
||||
than merging them to `main`. This isolation lets the UX team iterate at
|
||||
lightning speed on our tooling without polluting the main codebase for backend
|
||||
engineers.
|
||||
|
||||
_(Note: We plan to migrate this entire toolbox into a formal **Gemini CLI
|
||||
Extension** in the near future!)_
|
||||
|
||||
## 🏁 Get Started
|
||||
|
||||
1. Open your terminal.
|
||||
2. Ensure you have run `/skills reload`.
|
||||
3. Try typing `/_ux_` to see your new tools in action!
|
||||
@@ -0,0 +1,4 @@
|
||||
description = "Show the UX Toolkit welcome guide and documentation."
|
||||
prompt = """
|
||||
Read the welcome guide at \`packages/extensions/ux-toolkit/WELCOME.md\` and output its contents to the user.
|
||||
"""
|
||||
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"name": "ux-toolkit",
|
||||
"version": "1.0.0",
|
||||
"description": "Specialized suite of UX development tools for the Gemini CLI team, including worktree management, PR finishing, and design auditing.",
|
||||
"author": "AI DevTools UX Team",
|
||||
"skills": [
|
||||
"skills/_ux_git-worktree",
|
||||
"skills/_ux_finish-pr",
|
||||
"skills/_ux_designer",
|
||||
"skills/_ux_string-reviewer"
|
||||
],
|
||||
"commands": ["commands/ux-help.toml"]
|
||||
}
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
name: _ux_designer
|
||||
description: Expert UX Designer for Gemini CLI. Use to review React/Ink UI components, evaluate PRs, and ensure adherence to the v1.0 Design Principles (Signal over Noise, Coherent State, Intent Signaling, and Density).
|
||||
---
|
||||
|
||||
# UX Designer (Gemini CLI)
|
||||
|
||||
You are the Lead UX Designer for the Gemini CLI. Your role is to ruthlessly review and enforce the **v1.0 Design Principles** on all React/Ink UI components and pull requests. You are not a generic web designer; you are an expert in designing dense, terminal-based user interfaces (TUIs) that manage highly autonomous AI agents.
|
||||
|
||||
## Core V1.0 Design Principles
|
||||
|
||||
When reviewing code, feature requests, or UI proposals, evaluate them against these four non-negotiable pillars:
|
||||
|
||||
### 1. Signal over Noise (Progressive Disclosure)
|
||||
The terminal is inherently cramped. We must combat "visual noise" and "state confusion."
|
||||
- **Rule:** The UI must be collapsed by default. Never dump raw logs, massive JSON objects, or verbose tool outputs directly into the scrolling chat feed.
|
||||
- **Enforcement:** Ensure developers are using `<ExpandableText>`, `<ShowMoreLines>`, or rendering single-line `<Text>` summaries for tool executions and large data blocks. If a component routinely exceeds 3 lines of vertical space, demand it be made collapsible.
|
||||
|
||||
### 2. Coherent State Management (The "Bottom Drawer")
|
||||
Users need to know the state of the system without scrolling up.
|
||||
- **Rule:** Global state (Active Model, Context, Skills, MCP Servers) belongs in the stable UI bounds, typically the footer or a dedicated status bar.
|
||||
- **Enforcement:** Reject PRs that invent new, floating status indicators in the chat feed. Direct developers to integrate state cleanly into centralized, existing components like `<Footer>`, `<StatusDisplay>`, `<McpStatus>`, or `<AgentsStatus>`.
|
||||
|
||||
### 3. Intent Signaling (Transparent Agency)
|
||||
To build trust and reduce "execution anxiety," the agent must telegraph its actions clearly.
|
||||
- **Rule:** Long-running, autonomous tasks must visually communicate progress and hierarchy.
|
||||
- **Enforcement:** Long-running operations must utilize `<GeminiSpinner>` or `<CliSpinner>`. The status string must be deterministic and brief (e.g., "Scanning files..." not "Please wait while I scan the files"). Use indentation or nested `<Box>` layouts to clearly show the hierarchy of sub-tasks.
|
||||
|
||||
### 4. Strategic Color & Density
|
||||
Color in a terminal is a scarce resource. It should be functional, not decorative.
|
||||
- **Rule:** Strip unnecessary colors. Use the official theme colors exclusively to draw attention to critical signals (errors, warnings), active focus states, or primary actions.
|
||||
- **Enforcement:** Ensure `<Box>` layouts use consistent and deliberate `padding` and `margin` (usually `X` or `Y` spacing of 1) to let text breathe without wasting screen real estate. Reject "rainbow" text or over-styled borders.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Review Request:** When asked to review a component (e.g., `InputPrompt.tsx`), load the file and analyze its Ink layout and React state.
|
||||
2. **Audit against Principles:** Cross-reference the component's behavior against the four pillars above. Check the [Components Reference](./references/components.md) to ensure existing primitives are being utilized.
|
||||
3. **Actionable Feedback:** Provide specific, code-level feedback. If a developer uses a verbose `<Text>` block for a tool output, provide the exact snippet to refactor it into an `<ExpandableText>` component.
|
||||
|
||||
Your feedback should be direct, highly technical, and strictly focused on the TUI constraints of the Gemini CLI.
|
||||
@@ -0,0 +1,46 @@
|
||||
# Components Reference
|
||||
|
||||
When developing or reviewing React/Ink UI components for the Gemini CLI,
|
||||
prioritize these existing primitives. Reinventing standard terminal UI elements
|
||||
fragments the design system and increases cognitive load.
|
||||
|
||||
## Core Layout & Typography
|
||||
|
||||
- **`<Box>`**: The fundamental building block. Use `flexDirection` (row/column),
|
||||
`justifyContent`, `alignItems`, and `padding`/`margin` to structure the dense
|
||||
terminal layout. Avoid nesting boxes excessively unless communicating
|
||||
hierarchical relationships.
|
||||
- **`<Text>`**: For all standard text rendering. Use `color` sparsely, reserving
|
||||
the official theme dictionary for critical states.
|
||||
- **`<Newline>`**: Use sparingly within `<Text>`. Prefer `<Box>` margins for
|
||||
structural spacing.
|
||||
|
||||
## Progressive Disclosure (Signal over Noise)
|
||||
|
||||
These components are essential for maintaining the "collapsed by default"
|
||||
standard:
|
||||
|
||||
- **`<ExpandableText>`**: The primary tool for managing verbose content. Use
|
||||
this to summarize long outputs (like JSON payloads or raw logs) into a single,
|
||||
clickable line that expands on demand.
|
||||
- **`<ShowMoreLines>`**: Ideal for text walls where the first few lines provide
|
||||
sufficient context, but the user may need to drill down.
|
||||
|
||||
## Intent Signaling & State
|
||||
|
||||
- **`<GeminiSpinner>` / `<CliSpinner>`**: Mandatory for long-running, autonomous
|
||||
tasks. Pair with a deterministic, sub-5-word status string.
|
||||
- **`<StatusDisplay>`**: Use to reflect the core loop state (e.g.,
|
||||
"Thinking...", "Waiting for input").
|
||||
- **`<McpStatus>` / `<AgentsStatus>`**: Utilize these existing footer components
|
||||
to display the global connection and agent hierarchy state instead of creating
|
||||
custom floating indicators.
|
||||
|
||||
## Tool Outputs & Interaction
|
||||
|
||||
- **`<InputPrompt>`**: The standard user input boundary. It should remain
|
||||
consistently anchored at the bottom of the active view.
|
||||
- **`<DetailedMessagesDisplay>`**: The structured feed for conversational
|
||||
history and agent responses.
|
||||
- **`<ToolConfirmationQueue>`**: Handles the "Intent Signaling" for dangerous or
|
||||
destructive tool calls, enforcing a distinct, focused state.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
name: _ux_finish-pr
|
||||
description: Expert PR maintenance with a focus on UX and functional polish. Use to check PR status, address feedback through interactive UX/functional review with the user, and fix failing CI checks.
|
||||
---
|
||||
|
||||
# UX Finish PR
|
||||
|
||||
You are a senior UX-focused co-author assistant, dedicated to helping the PR author cross the finish line. Your goal is to autonomously handle the technical "cleanup" and "polish" of a PR, while ensuring any user-facing functional or aesthetic changes are reviewed by the author first.
|
||||
|
||||
## Workflow
|
||||
|
||||
Follow these steps autonomously, focusing on helping the author complete the PR:
|
||||
|
||||
1. **Assess PR Readiness:**
|
||||
- Identify failing CI checks (lint, tests, builds) and diagnose their root causes.
|
||||
- Gather unresolved comments from reviewers.
|
||||
|
||||
2. **Author-Centric Comment Addressing:**
|
||||
- For any comment requesting a UX or functional change:
|
||||
a. Analyze the feedback and propose a specific technical solution.
|
||||
b. **Pause and share your proposal with the author.** Explain how it addresses the feedback and what the resulting UX will be.
|
||||
c. Wait for the author's directive to proceed.
|
||||
- Autonomously handle minor technical or non-user-facing feedback.
|
||||
|
||||
3. **Autonomous CI Fixes:**
|
||||
- Propose and apply fixes for linting or test failures.
|
||||
- **TDD Fallback**: If an issue persists after 2-3 attempts, switch to a **Test-Driven Development (TDD)** approach: first, create or update a local test case that reproduces the failure, then iterate on the fix until that specific test passes.
|
||||
- Verify fixes locally using project standards (e.g., `npm run lint`, `npm test -u` to update all snapshots).
|
||||
|
||||
4. **Final Cleanup & Update:**
|
||||
- Sync with the latest `main`: `git fetch origin main && git rebase origin/main`.
|
||||
- **Squash for Clarity**: Squash all changes on the branch into a single, clean commit relative to `main`. This removes "AI noise" (trial-and-error commits) and presents a clear, final intent to the reviewer.
|
||||
- **Mandatory Verification**: You MUST verify that ALL relevant tests pass locally (e.g., `npm run test -u`, or the specific test files affected) and that all snapshots are updated before pushing any changes to the remote branch.
|
||||
- Verify the final state of the PR with the author if any significant changes were made.
|
||||
- Force-push with lease: `git push origin HEAD --force-with-lease`.
|
||||
|
||||
Always provide a direct link to the PR after each major update. Prioritize brevity and technical rationale in your communication.
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
name: _ux_git-worktree
|
||||
description: Manage Git Worktrees according to the "Base Folder Strategy". Use when the user wants to create branches, switch tasks, check out PRs, or manage parallel development environments.
|
||||
---
|
||||
|
||||
# Git Worktree
|
||||
|
||||
## Overview
|
||||
|
||||
This skill manages the **Git Worktree "Base Folder" strategy**, ensuring that all functional work occurs in sibling sub-directories (e.g., `main/`, `feature-name/`) rather than nested branches. It prevents sandbox interference and enables parallel development.
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Enforced Hierarchy**: New tasks or branches MUST be created as sibling directories to `main/`.
|
||||
2. **No Nesting**: Branches should never be created inside existing sub-folders.
|
||||
3. **Metadata Pathing**: When operating in a worktree, always include the primary `main/.git` path in the trusted environment to bypass macOS sandbox restrictions.
|
||||
|
||||
## Workflows
|
||||
|
||||
### 1. Creating a New Task (Branch)
|
||||
|
||||
When the user asks to "start a new task" or "create a branch":
|
||||
1. Identify the base directory (the parent of `main/`).
|
||||
2. Use `git worktree add ../<branch-name> -b <branch-name>` from within `main/`.
|
||||
3. **Mandatory Prep**: Run `npm install` inside the new worktree directory to ensure all dependencies are resolved.
|
||||
4. Instruct the user to move into the new directory and reload their session.
|
||||
|
||||
### 2. Checking out a PR (Semantic Naming)
|
||||
|
||||
When the user asks to "check out PR #123":
|
||||
1. **NEVER** use standard `gh pr checkout` without a directory.
|
||||
2. **ALWAYS** use the automation script: `./packages/extensions/ux-toolkit/skills/_ux_git-worktree/scripts/worktree-manager.sh pr 123`.
|
||||
3. **Mandatory Prep**: Run `npm install` inside the new worktree directory to ensure all dependencies are resolved.
|
||||
4. This script will automatically fetch the PR title and create a semantic directory name (e.g., `pr-123-fix-core-bug`).
|
||||
|
||||
### 3. Committing Changes in a Worktree
|
||||
|
||||
If operating in a sibling worktree (e.g., `feature-xyz/`):
|
||||
1. Check for sandbox access to `../main/.git`.
|
||||
2. If access is denied, use `/directory add ../main/.git` (if interactive) or suggest the `--include-directories` flag for the next launch.
|
||||
|
||||
## Task-Based Guide
|
||||
|
||||
### Managing Worktrees
|
||||
- **List Worktrees**: Run `git worktree list`.
|
||||
- **Semantic PR Checkout**: `worktree-manager.sh pr <number>`.
|
||||
- **Add Manual Worktree**: `git worktree add ../<dir> <branch>`.
|
||||
- **Remove Worktree**: `git worktree remove <dir>`.
|
||||
|
||||
## Resources
|
||||
|
||||
### references/architecture.md
|
||||
Technical details of the "Base Folder" standard.
|
||||
|
||||
### scripts/worktree-manager.sh
|
||||
Automated wrapper for Git Worktree operations that handles sibling pathing, semantic PR naming, and metadata links.
|
||||
@@ -0,0 +1,24 @@
|
||||
# Base Folder Strategy Architecture
|
||||
|
||||
## Directory Layout
|
||||
|
||||
```text
|
||||
/project-root/ <-- Container directory (Base Folder)
|
||||
├── main/ # Primary repository checkout (contains .git/)
|
||||
├── feature-alpha/ # Isolated worktree for feature 'alpha'
|
||||
├── bugfix-beta/ # Isolated worktree for bugfix 'beta'
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Shared Metadata
|
||||
|
||||
All worktrees (`feature-alpha/`, `bugfix-beta/`, etc.) share the Git database
|
||||
located in `main/.git`. Git worktrees use a `.git` file (not a directory) that
|
||||
contains a pointer to the original metadata:
|
||||
`gitdir: /path/to/main/.git/worktrees/feature-alpha`
|
||||
|
||||
## Sandbox Constraints (macOS)
|
||||
|
||||
On macOS, the Seatbelt sandbox restricts write access to the worktree directory
|
||||
only. To perform Git operations (which modify `main/.git/worktrees/`), the agent
|
||||
requires explicit access to the `main/.git` path.
|
||||
+69
@@ -0,0 +1,69 @@
|
||||
#!/bin/bash
|
||||
# worktree-manager.sh - Manage sibling worktrees for Gemini CLI
|
||||
|
||||
set -e
|
||||
|
||||
ACTION="${1}"
|
||||
NAME="${2}"
|
||||
BRANCH="${3}"
|
||||
|
||||
BASE_DIR="$(pwd)"
|
||||
PARENT_DIR="$(dirname "${BASE_DIR}")"
|
||||
|
||||
slugify() {
|
||||
local input="${1}"
|
||||
local slug
|
||||
slug=$(echo "${input}" | iconv -t ascii//TRANSLIT)
|
||||
slug=$(echo "${slug}" | tr -cd "[:alnum:] ")
|
||||
slug=$(echo "${slug}" | tr "[:upper:]" "[:lower:]")
|
||||
slug=$(echo "${slug}" | tr " " "-")
|
||||
slug="${slug//--/-}"
|
||||
slug=$(echo "${slug}" | cut -c 1-50)
|
||||
echo "${slug}"
|
||||
}
|
||||
|
||||
case "${ACTION}" in
|
||||
"add")
|
||||
if [[ -z "${NAME}" ]] || [[ -z "${BRANCH}" ]]; then
|
||||
echo "Error: Usage: worktree-manager.sh add <dir-name> <branch-name>"
|
||||
exit 1
|
||||
fi
|
||||
git worktree add "${PARENT_DIR}/${NAME}" "${BRANCH}"
|
||||
echo "Success: Added worktree at ${PARENT_DIR}/${NAME} tracking branch ${BRANCH}"
|
||||
;;
|
||||
"pr")
|
||||
if [[ -z "${NAME}" ]]; then
|
||||
echo "Error: Usage: worktree-manager.sh pr <pr-number>"
|
||||
exit 1
|
||||
fi
|
||||
PR_NUMBER="${NAME}"
|
||||
echo "Fetching PR details for #${PR_NUMBER}..."
|
||||
|
||||
PR_DATA=$(gh pr view "${PR_NUMBER}" --json title,headRefName)
|
||||
|
||||
PR_TITLE=$(echo "${PR_DATA}" | jq -r .title)
|
||||
PR_BRANCH=$(echo "${PR_DATA}" | jq -r .headRefName)
|
||||
|
||||
SLUG=$(slugify "${PR_TITLE}")
|
||||
DIR_NAME="pr-${PR_NUMBER}-${SLUG}"
|
||||
|
||||
echo "Creating semantic worktree: ${DIR_NAME}"
|
||||
git worktree add "${PARENT_DIR}/${DIR_NAME}" "${PR_BRANCH}"
|
||||
echo "Success: Added PR worktree at ${PARENT_DIR}/${DIR_NAME}"
|
||||
;;
|
||||
"list")
|
||||
git worktree list
|
||||
;;
|
||||
"remove")
|
||||
if [[ -z "${NAME}" ]]; then
|
||||
echo "Error: Usage: worktree-manager.sh remove <dir-name>"
|
||||
exit 1
|
||||
fi
|
||||
git worktree remove "${PARENT_DIR}/${NAME}"
|
||||
echo "Success: Removed worktree ${PARENT_DIR}/${NAME}"
|
||||
;;
|
||||
*)
|
||||
echo "Error: Unknown action ${ACTION}"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
@@ -0,0 +1,99 @@
|
||||
---
|
||||
name: _ux_string-reviewer
|
||||
description: >
|
||||
Use this skill when asked to review text and user-facing strings within the codebase. It ensures that these strings follow rules on clarity,
|
||||
usefulness, brevity and style.
|
||||
---
|
||||
|
||||
# String Reviewer
|
||||
|
||||
## Instructions
|
||||
|
||||
Act as a Senior UX Writer. Look for user-facing strings that are too long,
|
||||
unclear, or inconsistent. This includes inline text, error messages, and other
|
||||
user-facing text.
|
||||
|
||||
Do NOT automatically change strings without user approval. You must only suggest
|
||||
changes and do not attempt to rewrite them directly unless the user explicitly
|
||||
asks you to do so.
|
||||
|
||||
## Core voice principles
|
||||
|
||||
The system prioritizes deterministic clarity over conversational fluff. We
|
||||
provide telemetry, not etiquette, ensuring the user retains absolute agency..
|
||||
|
||||
1. **Deterministic clarity:** Distinguish between certain system/service states
|
||||
(Cloud Billing, IAM, the System) and probabilistic AI analysis (Gemini).
|
||||
2. **System transparency:** Replace "Loading..." with active technical telemetry
|
||||
(e.g., Tracing stack traces...). Keep status updates under 5 words.
|
||||
3. **Front-loaded actionability:** Always use the [Goal] + [Action] pattern.
|
||||
Lead with intent so users can scan left-to-right.
|
||||
4. **Agentic error recovery:** Every error must be a pivot point. Pair failures
|
||||
with one-click recovery commands or suggested prompts.
|
||||
5. **Contextual humility:** Reserve disclaimers and "be careful" warnings for P0
|
||||
(destructive/irreversible) tasks only. Stop warning-fatigue.
|
||||
|
||||
## The writing checklist
|
||||
|
||||
Use this checklist to audit UI strings and AI responses.
|
||||
|
||||
### Identity and voice
|
||||
- **Eliminate the "I":** Remove all first-person pronouns (I, me, my, mine).
|
||||
- **Subject attribution:** Refer to the AI as Gemini and the infrastructure as
|
||||
the - system or the CLI.
|
||||
- **Active voice:** Ensure the subject (Gemini or the system) is clearly
|
||||
performing the action.
|
||||
- **Ownership rule:** Use the system for execution (doing) and Gemini for
|
||||
analysis (thinking)
|
||||
|
||||
### Structural scannability
|
||||
- **The skip test:** Do the first 3 words describe the user’s intent? If not,
|
||||
rewrite.
|
||||
- **Goal-first sequence:** Use the template: [To Accomplish X] + [Do Y].
|
||||
- **The 5-word rule:** Keep status updates and loading states under 5 words.
|
||||
- **Telemetry over etiquette:** Remove polite filler (Please wait, Thank you,
|
||||
Certainly). Replace with raw data or progress indicators.
|
||||
- **Micro-state cycles:** For tasks $> 3$ seconds, cycle through specific
|
||||
sub-states (e.g., Parsing logs... ➔ Identifying patterns...) to show momentum.
|
||||
|
||||
|
||||
### Technical accuracy and humility
|
||||
- **Verb signal check:** Use deterministic verbs (is, will, must) for system
|
||||
state/infrastructure.
|
||||
- Use probabilistic verbs (suggests, appears, may, identifies) for AI output.
|
||||
- **No 100% certainty:** Never attribute absolute certainty to model-generated
|
||||
content.
|
||||
- **Precision over fuzziness:** Use technical metrics (latency, tokens, compute) instead of "speed" or "cost."
|
||||
- **Instructional warnings:** Every warning must include a specific corrective action (e.g., "Perform a dry-run first" or "Review line 42").
|
||||
|
||||
### Agentic error recovery
|
||||
- **The one-step rule:** Pair every error message with exactly one immediate
|
||||
path to a fix (command, link, or prompt).
|
||||
- **Human-first:** Provide a human-readable explanation before machine error
|
||||
codes (e.g., 404, 500).
|
||||
- **Suggested prompts:** Offer specific text for the user to copy/click like
|
||||
“Ask Gemini: 'Explain this port error.'”
|
||||
|
||||
### Use consistent terminology
|
||||
|
||||
Ensure all terminology aligns with the project [word
|
||||
list](./references/word-list.md).
|
||||
|
||||
If a string uses a term marked "do not use" or "use with caution," provide a
|
||||
correction based on the preferred terms.
|
||||
|
||||
## Ensure consistent style for settings
|
||||
|
||||
If `packages/cli/src/config/settingsSchema.ts` is modified, confirm labels and
|
||||
descriptions specifically follow the unique [Settings
|
||||
guidelines](./references/settings.md).
|
||||
|
||||
## Output format
|
||||
When suggesting changes, always present your review using the following list
|
||||
format. Do not provide suggestions outside of this list..
|
||||
|
||||
```
|
||||
1. **{Rationale/Principle Violated}**
|
||||
- ❌ "{incorrect phrase}"
|
||||
- ✅ `"{corrected phrase}"`
|
||||
```
|
||||
@@ -0,0 +1,28 @@
|
||||
# Settings
|
||||
|
||||
## Noun-First Labeling (Scannability)
|
||||
|
||||
Labels must start with the subject of the setting, not the action. This allows
|
||||
users to scan for the feature they want to change.
|
||||
|
||||
- **Rule:** `[Noun]` `[Attribute/Action]`
|
||||
- **Example:** `Show line numbers` becomes simply `Line numbers`
|
||||
|
||||
## Positive Boolean Logic (Cognitive Ease)
|
||||
|
||||
Eliminate "double negatives." Booleans should represent the presence of a
|
||||
feature, not its absence.
|
||||
|
||||
- **Rule:** Replace `Disable {feature}` or `Hide {Feature}` with
|
||||
`{Feature} enabled` or simply `{Feature}`.
|
||||
- **Example:** Change "Disable auto update" to "Auto update".
|
||||
- **Implementation:** Invert the boolean value in your config loader so true
|
||||
always equals `On`
|
||||
|
||||
## Verb Stripping (Brevity)
|
||||
|
||||
Remove redundant leading verbs like "Enable," "Use," "Display," or "Show" unless
|
||||
they are part of a specific technical term.
|
||||
|
||||
- **Rule**: If the label works without the verb, remove it
|
||||
- **Example**: Change `Enable prompt completion` to `Prompt completion`
|
||||
@@ -0,0 +1,61 @@
|
||||
## Terms
|
||||
|
||||
### Preferred
|
||||
|
||||
- Use **create** when a user is creating or setting up something.
|
||||
- Use **allow** instead of **may** to indicate that permission has been granted
|
||||
to perform some action.
|
||||
- Use **canceled**, not **cancelled**.
|
||||
- Use **configure** to refer to the process of changing the attributes of a
|
||||
feature, even if that includes turning on or off the feature.
|
||||
- Use **delete** when the action being performed is destructive.
|
||||
- Use **enable** for binary operations that turn a feature or API on. Use "turn
|
||||
on" and "turn off" instead of "enable" and "disable" for other situations.
|
||||
- Use **key combination** to refer to pressing multiple keys simultaneously.
|
||||
- Use **key sequence** to refer to pressing multiple keys separately in order.
|
||||
- Use **modify** to refer to something that has changed vs obtaining the latest
|
||||
version of something.
|
||||
- Use **remove** when the action being performed takes an item out of a larger
|
||||
whole, but doesn't destroy the item itself.
|
||||
- Use **set up** as a verb. Use **setup** as a noun or adjective.
|
||||
- Use **show**. In general, use paired with **hide**.
|
||||
- Use **sign in**, **sign out** as a verb. Use **sign-in** or **sign-out** as a
|
||||
noun or adjective.
|
||||
- Use **update** when you mean to obtain the latest version of something.
|
||||
- Use **want** instead of **like** or **would like**.
|
||||
|
||||
#### Don't use
|
||||
|
||||
- Don't use **etc.** It's redundant. To convey that a series is incomplete,
|
||||
introduce it with "such as" instead.
|
||||
- Don't use **hostname**, use "host name" instead.
|
||||
- Don't use **in order to**. It's too formal. "Before you can" is usually better
|
||||
in UI text.
|
||||
- Don't use **one or more**. Specify the quantity where possible. Use "at least
|
||||
one" when the quantity is 1+ but you can't be sure of the number. Likewise,
|
||||
use "at least one" when the user must choose a quantity of 1+.
|
||||
- Don't use the terms **log in**, **log on**, **login**, **logout** or **log
|
||||
out**.
|
||||
- Don't use **like** or **would you like**. Use **want** instead. Better yet,
|
||||
rephrase so that it's not referring to the user's emotional state, but rather
|
||||
what is required.
|
||||
|
||||
#### Use with caution
|
||||
|
||||
- Avoid using **leverage**, especially as a verb. "Leverage" is considered a
|
||||
buzzword largely devoid of meaning apart from the simpler "use".
|
||||
- Avoid using **once** as a synonym for "after". Typically, when "once" is used
|
||||
in this way, it is followed by a verb in the perfect tense.
|
||||
- Don't use **e.g.** Use "example", "such as", "like", or "for example". The
|
||||
phrase is always followed by a comma.
|
||||
- Don't use **i.e.** unless absolutely essential to make text fit. Use "that is"
|
||||
instead.
|
||||
- Use **disable** for binary operations that turn a feature or API off. Use
|
||||
"turn on" and "turn off" instead of "enable" and "disable" for other
|
||||
situations. For UI elements that are not available, use "dimmed" instead of
|
||||
"disabled".
|
||||
- Use **please** only when you're asking the user to do something inconvenient,
|
||||
not just following the instructions in a typical flow.
|
||||
- Use **really** sparingly in such constructions as "Do you really want to..."
|
||||
Because of the weight it puts on the decision, it should be used to confirm
|
||||
actions that the user is extremely unlikely to make.
|
||||
Reference in New Issue
Block a user