fix: render template titles as FormattedText, not raw ANSI

questionary.select prints string titles literally, so SGR escapes showed as
^[[1;94m…. Use prompt_toolkit style tokens plus SearchableFormattedText so
type-to-filter keeps working.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ulises-jeremias

docs/UIUX_BRANDING_HANDOFF.md

@@ -112,14 +112,11 @@ From `cpa.config.json` or catalog `customOptions`:
 ### Category badges
 
 Interactive template choices use a fixed-width badge from `short_category_label()`
-with bright bold ANSI colors (`prompt_style.color_category`) so they stay readable
-on dark terminals. Titles may include ANSI because the picker is
-`questionary.select(..., use_search_filter=True)` — **not** autocomplete (which
-HTML-parses choice text and breaks on ANSI).
+styled with prompt_toolkit FormattedText tokens (`prompt_style.template_title_tokens`).
+Raw ANSI in string titles is avoided — `select()` prints those escapes literally
+(`^[[1;94m…`). Titles are `SearchableFormattedText` so `use_search_filter` still works.
 
-Respects `NO_COLOR`. `--list-templates` uses Rich tables for color.
-
-UX: ↑↓ browse the full catalog, type to filter, Enter to pick (CNA-parity discovery).
+Respects `NO_COLOR` (plain string titles). `--list-templates` uses Rich tables.
 
 ### Rich semantic color usage
 

packages/create-awesome-python-app/src/create_awesome_python_app/catalog.py

@@ -16,7 +16,10 @@
 from rich.table import Table
 
 from create_awesome_python_app import __version__
-from create_awesome_python_app.prompt_style import bold, color_category, dim
+from create_awesome_python_app.prompt_style import (
+    custom_template_title,
+    template_title_tokens,
+)
 
 console = Console(stderr=True)
 
@@ -27,7 +30,7 @@
 class TemplateChoice:
     """Searchable interactive template choice."""
 
-    title: str
+    title: Any
     value: str
     search: str
 
@@ -236,35 +239,40 @@ def build_template_choices(data: dict[str, Any]) -> list[TemplateChoice]:
         category_name = categories.get(category_slug, category_slug)
         badge = short_category_label(category_name).ljust(10)[:10]
         slug = str(template.get("slug", ""))
-        labels = template.get("labels", [])
-        label_suffix = ""
-        if isinstance(labels, list) and labels:
-            label_suffix = dim(" · " + ", ".join(str(label) for label in labels[:3]))
+        labels_raw = template.get("labels", [])
+        labels = (
+            [str(label) for label in labels_raw[:3]]
+            if isinstance(labels_raw, list)
+            else []
+        )
         description = str(template.get("description", "")).strip()
-        # Keep slug + short description in the title so select(use_search_filter)
-        # can match them (filter scans Choice.title only).
-        description_suffix = dim(f" — {description}") if description else ""
         name = str(template.get("name", slug))
-        # ANSI is OK here: questionary.select renders titles as terminal text.
-        # Do not pass these titles to autocomplete (HTML match highlighting).
-        title = (
-            f"{color_category(category_slug, badge)}  "
-            f"{bold(name)} ({slug})"
-            f"{label_suffix}{description_suffix}"
+        search = _search_text(template, category_name)
+        # FormattedText tokens (not raw ANSI): select() prints str titles
+        # literally, which showed ^[[1;94m… in terminals.
+        title = template_title_tokens(
+            category_slug=category_slug,
+            badge=badge,
+            name=name,
+            slug=slug,
+            labels=labels,
+            description=description,
+            search=search,
         )
         choices.append(
             TemplateChoice(
                 title=title,
                 value=template_url,
-                search=_search_text(template, category_name),
+                search=search,
             )
         )
 
+    custom_search = "custom own template url github file"
     choices.append(
         TemplateChoice(
-            title=" " * 12 + dim("Use my own template URL"),
+            title=custom_template_title(custom_search),
             value=CUSTOM_TEMPLATE_SENTINEL,
-            search="custom own template url github file",
+            search=custom_search,
         )
     )
     return choices

packages/create-awesome-python-app/src/create_awesome_python_app/prompt_style.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import os
+from typing import Any
 
 from questionary import Style
 
@@ -25,37 +26,88 @@
     }
 )
 
+# Bright prompt_toolkit style strings (not raw ANSI — select() prints str titles
+# literally, so escapes show as ^[[...m unless titles are FormattedText tokens).
+_CATEGORY_STYLES = (
+    "fg:#facc15 bold",  # yellow
+    "fg:#4ade80 bold",  # green
+    "fg:#22d3ee bold",  # cyan
+    "fg:#e879f9 bold",  # magenta
+    "fg:#60a5fa bold",  # blue
+)
+
+
+class SearchableFormattedText(list):
+    """FormattedText tokens with ``.lower()`` for questionary search filter.
+
+    ``select(use_search_filter=True)`` does ``needle in choice.title.lower()``.
+    A plain token list has no ``.lower()``; this keeps filter working while
+    titles render as styled FormattedText.
+    """
+
+    def __init__(self, tokens: list[tuple[str, str]], search: str) -> None:
+        super().__init__(tokens)
+        self._search = search
+
+    def lower(self) -> str:
+        return self._search.lower()
+
 
 def colors_enabled() -> bool:
     return not os.environ.get("NO_COLOR")
 
 
-def ansi(code: str, text: str) -> str:
-    """Wrap *text* in an ANSI SGR sequence when colors are enabled."""
-    if not colors_enabled():
-        return text
-    return f"\033[{code}m{text}\033[0m"
-
-
-# Bold bright ANSI — readable on dark terminals; select() renders these safely
-# (unlike autocomplete, which HTML-parses choice text).
-_CATEGORY_PALETTE = (
-    "1;93",  # bright yellow
-    "1;92",  # bright green
-    "1;96",  # bright cyan
-    "1;95",  # bright magenta
-    "1;94",  # bright blue
-)
-
+def category_style(slug: str) -> str:
+    idx = sum(ord(char) for char in slug) % len(_CATEGORY_STYLES)
+    return _CATEGORY_STYLES[idx]
 
-def color_category(slug: str, label: str) -> str:
-    idx = sum(ord(char) for char in slug) % len(_CATEGORY_PALETTE)
-    return ansi(_CATEGORY_PALETTE[idx], label)
 
+def plain_title_text(title: Any) -> str:
+    """Join FormattedText token text (or return a plain string title)."""
+    if isinstance(title, list):
+        return "".join(str(token[1]) for token in title)
+    return str(title)
 
-def bold(text: str) -> str:
-    return ansi("1", text)
 
+def template_title_tokens(
+    *,
+    category_slug: str,
+    badge: str,
+    name: str,
+    slug: str,
+    labels: list[str],
+    description: str,
+    search: str,
+) -> SearchableFormattedText | str:
+    """Build a select-safe title: FormattedText when colors on, else plain str."""
+    label_suffix = ""
+    if labels:
+        label_suffix = " · " + ", ".join(labels[:3])
+    description_suffix = f" — {description}" if description else ""
+    plain = f"{badge}  {name} ({slug}){label_suffix}{description_suffix}"
 
-def dim(text: str) -> str:
-    return ansi("2", text)
+    if not colors_enabled():
+        return plain
+
+    tokens: list[tuple[str, str]] = [
+        (category_style(category_slug), badge),
+        ("", "  "),
+        ("bold", name),
+        ("class:instruction", f" ({slug})"),
+    ]
+    if label_suffix:
+        tokens.append(("class:instruction", label_suffix))
+    if description_suffix:
+        tokens.append(("fg:#94a3b8", description_suffix))
+    return SearchableFormattedText(tokens, search=search or plain)
+
+
+def custom_template_title(search: str) -> SearchableFormattedText | str:
+    label = "Use my own template URL"
+    plain = " " * 12 + label
+    if not colors_enabled():
+        return plain
+    return SearchableFormattedText(
+        [("", " " * 12), ("italic fg:#94a3b8", label)],
+        search=search or plain,
+    )

packages/create-awesome-python-app/tests/test_catalog_resolve.py

@@ -17,6 +17,10 @@
     short_category_label,
     validate_extension_compatibility,
 )
+from create_awesome_python_app.prompt_style import (
+    SearchableFormattedText,
+    plain_title_text,
+)
 
 SAMPLE_CATALOG = {
     "templates": [
@@ -99,19 +103,18 @@ def test_build_template_choices_are_searchable() -> None:
     choices = build_template_choices(catalog)
     first = choices[0]
     assert first.value == "file:///templates/fastapi"
-    assert "FastAPI Starter" in first.title
-    assert "OpenAPI" in first.title
-    assert "uv" in first.title
+    title_text = plain_title_text(first.title)
+    assert "FastAPI Starter" in title_text
+    assert "OpenAPI" in title_text
+    assert "uv" in title_text
     assert "openapi" in first.search
     assert "backend" in first.search
     assert "uv" in first.search
     assert choices[-1].value == CUSTOM_TEMPLATE_SENTINEL
 
 
-def test_template_choice_titles_include_bright_category_ansi(
-    monkeypatch,
-) -> None:
-    """select() can render ANSI; badges use bright bold codes for contrast."""
+def test_template_choice_titles_use_formatted_text(monkeypatch) -> None:
+    """select() needs FormattedText tokens; raw ANSI shows as ^[[…m."""
     monkeypatch.delenv("NO_COLOR", raising=False)
     catalog = {
         "categories": [
@@ -127,8 +130,10 @@ def test_template_choice_titles_include_bright_category_ansi(
         ],
     }
     title = build_template_choices(catalog)[0].title
-    assert "\033[" in title
-    assert "FastAPI Starter" in title
+    assert isinstance(title, SearchableFormattedText)
+    assert "\033" not in plain_title_text(title)
+    assert "FastAPI Starter" in plain_title_text(title)
+    assert "fastapi" in title.lower()
 
 
 def test_template_choice_titles_respect_no_color(monkeypatch) -> None:
@@ -147,6 +152,7 @@ def test_template_choice_titles_respect_no_color(monkeypatch) -> None:
         ],
     }
     title = build_template_choices(catalog)[0].title
+    assert isinstance(title, str)
     assert "\033" not in title
     assert "FastAPI Starter" in title