feat: migrate UX tools to a formal Extension (ux-toolkit)

2026-06-21 00:37:17 -07:00 · 2026-03-19 14:56:13 -07:00
parent 660979c546
commit 284853b92c
16 changed files with 262 additions and 84 deletions
@@ -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"]
+}
@@ -29,7 +29,7 @@ When the user asks to "start a new task" or "create a branch":

 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/core/src/skills/builtin/_ux_git-worktree/scripts/worktree-manager.sh pr 123`.
+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`).

@@ -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.