Convert design guideline from Figma to azd-style-guide.md

cli/azd/AGENTS.md

@@ -157,6 +157,21 @@ func (a *myAction) Run(ctx context.Context) (*actions.ActionResult, error) {
 - **Shell-safe output**: When emitting shell commands in user-facing messages (e.g., `cd <path>`), quote paths that may contain spaces. Use `fmt.Sprintf("cd %q", path)` or conditionally wrap in quotes
 - **Consistent JSON types**: When adding fields to JSON output (`--output json`), match the types used by similar fields across commands. Don't mix `*time.Time` and custom timestamp wrappers (e.g., `*RFC3339Time`) in the same API surface
 
+### CLI UX & Style
+
+When working on CLI output, terminal UX, spinners, progress states, colors, or prompts for **core azd flows**, you **MUST read** the style guide before making any changes or recommendations:
+
+📄 **`cli/azd/docs/style-guidelines/azd-style-guide.md`** (full path from repo root)
+
+This file is the authoritative reference for core azd terminal UX patterns including:
+- Progress report states (`(✓) Done`, `(✗) Failed`, `(!) Warning`, `(-) Skipped`)
+- Spinner type (bar-fill `|=======|`)
+- Color conventions (`WithSuccessFormat`, `WithErrorFormat`, `WithHighLightFormat`, etc.)
+- User input patterns (text input, list select, yes/no confirm)
+- Prompt styling (`?` marker in bold blue, `[Type ? for hint]`, post-submit states)
+
+> **Note**: This style guide covers **core azd flows only**. Separate guidelines for agentic flows and extension-specific UX will be provided in dedicated files in the future. Do not apply core azd patterns to agentic or extension flows without a dedicated style reference.
+
 ### Code Organization
 
 - **Import order**: stdlib → external → azure/azd internal → local
@@ -307,6 +322,7 @@ go build
 
 Feature-specific docs are in `docs/` — refer to them as needed. Some key docs include:
 
+- `docs/style-guidelines/azd-style-guide.md` - CLI style guide (colors, spinners, progress states, terminal UX)
 - `docs/style-guidelines/new-azd-command.md` - Adding new commands
 - `docs/extensions/extension-framework.md` - Extension development using gRPC extension framework
 - `docs/style-guidelines/guiding-principles.md` - Design principles

cli/azd/docs/style-guidelines/azd-style-guide.md

@@ -4,6 +4,8 @@
 
 This style guide establishes standards for code, user experience, testing, and documentation across the Azure Developer CLI project. Following these guidelines ensures consistency, maintainability, and a high-quality user experience.
 
+> **Scope**: This guide covers **core azd flows** only. Separate guidelines for agentic flows and extension-specific UX will be provided in dedicated files in the future.
+
 ## Code Style Guidelines
 
 ### Go Conventions
@@ -70,90 +72,230 @@ func (s *Service) Run(ctx context.Context) error {
 
 ### Progress Reports
 
-Progress reports provide real-time feedback during multi-step operations. Use progress reports to:
+Progress reports provide real-time feedback during a single command's execution, showing the status of individual steps as they happen. Use progress reports to:
 
 - Show status of long-running commands
 - Display individual service provisioning/deployment states
 - Help users troubleshoot by showing exactly which step failed
 
 #### Progress Report States
 
-Items in a progress report list can be in one of five states:
+Items in a progress report list can be in one of six states:
 
-1. **Loading**: `|===    | [Verb] Message goes here`
+1. **Loading**: <code><span style="color:gray">|===    |</span> [Verb] Message goes here</code>
    - Indicates operation in progress
    - Shows loading bar animation
 
-2. **Done**: `(✓) Done: [Verb] Message goes here`
+2. **Done**: <code><span style="color:green">(✓) Done:</span> [Verb] Message goes here</code>
    - Green checkmark indicates successful completion
    - Past tense verb
 
-3. **Failed**: `(✗) Failed: [Verb] Message goes here`
+3. **Failed**: <code><span style="color:red">(✗) Failed:</span> [Verb] Message goes here</code>
    - Red X indicates error
    - Include specific error message below
 
-4. **Warning**: `(!) Warning: [Verb] Message goes here`
+4. **Warning**: <code><span style="color:#c5a332">(!) Warning:</span> [Verb] Message goes here</code>
    - Yellow exclamation for non-blocking issues
    - Command continues but user should be aware
 
-5. **Skipped**: `(-) Skipped: [Verb] Message goes here`
+5. **Skipped**: <code><span style="color:gray">(-) Skipped:</span> [Verb] Message goes here</code>
    - Gray dash indicates intentionally skipped step
    - Different from failed - this is expected behavior
 
 #### Progress Report Guidelines
 
 - **Indentation**: Progress items are always indented under the main command
-- **Hierarchy**: Sub-steps appear indented under parent steps
 - **Verb consistency**: Use present progressive for loading, past tense for completed
 - **Contextual information**: Include resource names, identifiers when relevant
 
 #### Examples
 
 **Success scenario:**
 
-```
-Provisioning Azure resources (azd provision)
+<pre>
+<b>Provisioning Azure resources (azd provision)</b>
 Provisioning Azure resources can take some time.
 
-  (✓) Done: Creating App Service Plan: plan-r2w2adrz3rvwxu
-  (✓) Done: Creating Log Analytics workspace: log-r2w2adrz3rvwxu
-  (✓) Done: Creating Application Insights: appi-r2w2adrz3rvwxu
-  (✓) Done: Creating App Service: app-api-r2w2adrz3rvwxu
-```
+  <span style="color:green">(✓) Done:</span> Creating App Service Plan: plan-r2w2adrz3rvwxu
+  <span style="color:green">(✓) Done:</span> Creating Log Analytics workspace: log-r2w2adrz3rvwxu
+  <span style="color:green">(✓) Done:</span> Creating Application Insights: appi-r2w2adrz3rvwxu
+  <span style="color:green">(✓) Done:</span> Creating App Service: app-api-r2w2adrz3rvwxu
+</pre>
 
 **Failure scenario:**
 
-```
-Provisioning Azure resources (azd provision)
+<pre>
+<b>Provisioning Azure resources (azd provision)</b>
 
-  (✓) Done: Creating App Service Plan: plan-r2w2adrz3rvwxu
-  (✓) Done: Creating Log Analytics workspace: log-r2w2adrz3rvwxu
-  (✗) Failed: Creating Cosmos DB: cosmos-r2w2adrz3rvwxu
-
-  The '{US} West US 2 (westus)' region is currently experiencing high demand
-  and cannot fulfill your request. Failed to create Cosmos DB account.
+  <span style="color:green">(✓) Done:</span> Creating App Service Plan: plan-r2w2adrz3rvwxu
+  <span style="color:green">(✓) Done:</span> Creating Log Analytics workspace: log-r2w2adrz3rvwxu
+  <span style="color:red">(✗) Failed:</span> Creating Cosmos DB: cosmos-r2w2adrz3rvwxu
+  <span style="color:red">The '{US} West US 2 (westus)' region is currently experiencing high demand and cannot fulfill your request. Failed to create Cosmos DB account.</span>
 
-ERROR: Unable to complete provisioning of Azure resources, 'azd up' failed
-```
+<span style="color:red">ERROR:</span> Unable to complete provisioning of Azure resources, 'azd up' failed
+</pre>
 
 **Skipped scenario:**
 
-```
-Note: Steps were skipped because _____ (directory, or specified service name)
-If you want to deploy all services, you can run azd deploy --all or
-move to root directory.
+<pre>
+  <span style="color:green">(✓) Done:</span> [Verb] Message goes here
+  <span style="color:green">(✓) Done:</span> [Verb] Message goes here
+  <span style="color:gray">(-) Skipped:</span> [Verb] Message goes here
+</pre>
+
+### Success / Error / Warning Logs
+
+These logs represent the final outcome of a command, displayed after execution completes. Standard logs (Success, Error, Warning) use an **all-caps prefix** followed by a colon to separate the log type from the message.
+
+All logs should:
+
+- Be **succinct**
+- Be **human legible**
+- **Provide a path forward** when possible
 
-  (✓) Done: [Verb] Message goes here
-  (✓) Done: [Verb] Message goes here
-  (-) Skipped: [Verb] Message goes here
+There are some specific edge cases where the log prefix is not required.
+
+#### Log Format
+
+```
+PREFIX: Message goes here.
 ```
 
-### Command Output Standards
+#### Log Types
+
+**Success logs** — Indicate the success of a specific command or action. Success logs use the green (or bright green) color variable (`WithSuccessFormat`).
+
+<pre>
+<span style="color:green">SUCCESS: Message goes here.</span>
+</pre>
+
+**Error logs** — Indicate when an error occurs, or indicate overall command failure. Error logs use the red (or bright red) color variable (`WithErrorFormat`). Error logs should attempt to follow a `[Reason] [Outcome]` structure when possible.
+
+<pre>
+<span style="color:red">ERROR: Message goes here.</span>
+</pre>
+
+**Warning logs** — Used when a command or action has an outcome that may provide unexpected results, or when the user needs to be made aware of something potentially destructive. Warning logs use the yellow (or bright yellow) color variable (`WithWarningFormat`).
+
+<pre>
+<span style="color:#c5a332">WARNING: Message goes here.</span>
+</pre>
+
+**Next steps logs** — The arrow indicates the next step. Used when the command output includes follow-up actions or recommended next steps for the user. Next steps logs use the format `(->) NEXT STEPS:` followed by the message.
+
+<pre>
+(->) NEXT STEPS: Message goes here.
+</pre>
+
+#### In-Context Examples
+
+**Success example:**
+
+<pre>
+<span style="color:green">SUCCESS: Your Azure app has been deployed!</span>
+You can view the resources created under the resource group case-code-test-rg in Azure Portal:
+<span style="color:cyan">https://portal.azure.com/#@/resource/subscriptions/.../resourceGroups/case-code-test-rg</span>
+</pre>
+
+**Error example:**
+
+<pre>
+<span style="color:red">ERROR: 'todo-mongojs' is misspelled or missing a recognized flag.</span>
+Run <span style="color:#5555ff">azd up --help</span> to see all available flags.
+</pre>
+
+**Warning example:**
+
+<pre>
+<span style="color:#c5a332">WARNING: You have already provisioned Azure resources to the (US) West US (westus) region.</span>
+You may want to run <span style="color:#5555ff">azd down</span> to delete your existing resources before provisioning to a new region.
+</pre>
+
+### User Inputs
+
+Certain azd commands require the user to input text, select yes/no, or select an item from a list. Examples include:
+
+- Inputting an environment name (text input)
+- Initializing a new Git repository (y/n)
+- Selecting a location to deploy to (list select)
+
+#### General Guidelines
+
+All input requests are in bold and begin with a blue `?`. This helps ensure that they stand out to users as different from other plain text logs and CLI outputs.
+
+#### Text Input
+
+Text input captures a single line of input from the user.
+
+**Initial state:**
+
+The prompt is displayed with a `[Type ? for hint]` helper in **hi-blue bold text** via `WithHighLightFormat` (Bright Blue, ANSI 94), followed by ghost-text (secondary text color) as placeholder content.
 
-- **Structured output**: Support `--output json` for machine-readable output
-- **Progress indicators**: Use spinners and progress bars for long operations
-- **Colorization**: Use consistent colors (green=success, red=error, yellow=warning)
-- **URLs**: Always include relevant portal/console URLs for created resources
+<pre>
+<span style="color:#5555ff"><b>?</b></span> This captures a single line of input: <span style="color:#5555ff"><b>[Type ? for hint]</b></span>
+</pre>
+
+**Hint feature:**
+
+If the user types `?`, a hint line appears below the prompt to provide additional guidance. 
+
+<pre>
+<span style="color:#5555ff"><b>?</b></span> This captures a single line of input: <span style="color:#5555ff"><b>[Type ? for hint]</b></span>
+<span style="color:grey"><b>Hint: This is a help message</b></span>
+</pre>
+
+#### Yes or No Input
+
+- Yes/no inputs include a `(Y/n)` delineator at the end of the input request (before the colon).
+- Users can either input `y`/`n` or hit the return key which will select the capitalized choice in the `(Y/n)` delineator.
+
+<pre>
+<span style="color:#5555ff"><b>?</b></span> Do you want to initialize a new Git repository in this directory? (Y/n):
+</pre>
+
+#### List Select
+
+The list select pattern presents a list of options for the user to choose from.
+
+**Initial state:**
+
+The prompt is displayed with a `Filter:` line showing ghost-text ("Type to filter list") and a footer hint in **hi-blue text** via `WithHighLightFormat` (Bright Blue, ANSI 94). The active selection is indicated by `>` and displayed in bold blue text.
+
+<pre>
+<span style="color:#5555ff"><b>?</b></span> Select a single option:  <span style="color:#5555ff"><b>[Use arrows to move, type to filter]</b></span>
+
+  <span style="color:#5555ff"><b>> Option 1</b></span>
+    Option 2
+    Option 3
+    Option 4
+    Option 5
+    Option 6
+    ...
+</pre>
+
+**Display rules:**
+
+- The list should display no more than 7 items at a time.
+- When a list contains more than 7 items, ellipses (`...`) should be used to help users understand there are more items available up or down the list.
+- If possible, the most commonly selected item (or the item we want to guide the user into selecting) should be highlighted by default.
+- The active selection in the list should be bold and in blue text, prefixed with `>`.
+
+**Hint:**
+
+- The `[Type ? for hint]` pattern follows the same behavior as Text Input — **hi-blue bold** via `WithHighLightFormat` (Bright Blue, ANSI 94).
+
+**After submitting:**
+
+Once the user makes their selection:
+
+- The input changes from primary text to hi-blue text
+- The `[Type ? for hint]` helper disappears
+- If the hint line was visible, it also disappears
+- The list collapses and the selected value is printed in blue text next to the prompt
+
+<pre>
+<span style="color:#5555ff"><b>?</b></span> Select an Azure location to use: <span style="color:#5555ff">(US) East US 2 (eastus2)</span>
+</pre>
 
 ### CLI Color Standards
 
@@ -252,6 +394,36 @@ Note: There is a discrepancy in the naming convention between ANSI Color coding
 
 </details>
 
+### Loading Animation (Progress Spinner)
+
+`azd` uses a **bar-fill spinner** to indicate ongoing operations. The animation displays a pair of `|` border characters with `=` fill characters that bounce back and forth, alongside a status message describing the current operation.
+
+#### Animation Behavior
+
+The spinner **animates in place** on a single line by overwriting itself. The `=` fill characters grow and bounce back and forth between the `|` borders, creating a fluid loading effect:
+
+```
+|=====  | Creating App Service: my-app-r2w2adrz3rvwxu
+```
+
+The full animation cycle frames are:
+
+```
+|       |  →  |=      |  →  |==     |  →  |===    |  →  |====   |  →  |=====  |  →  |====== |  →  |=======|
+|=======|  →  | ======|  →  |  =====|  →  |   ====|  →  |    ===|  →  |     ==|  →  |      =|  →  |       |
+```
+
+These frames repeat continuously on the **same line** until the operation completes. The spinner bar is displayed in **hint-colored** text (gray) to keep focus on the status message.
+
+#### Implementation
+
+Use `console.ShowSpinner()` and `console.StopSpinner()` from [`pkg/input/console.go`](../../pkg/input/console.go) to display the bar-fill spinner. These are the standard functions used across all azd commands.
+
+```go
+// Start or update spinner
+console.ShowSpinner(ctx, "Creating App Service: my-app-r2w2adrz3rvwxu", input.Step)
+```
+
 ## Testing Standards
 
 ### Test Structure