Skip to content

UIUX_BRANDING_HANDOFF.md

Latest commit

 

History

History
433 lines (316 loc) · 19.6 KB

UIUX_BRANDING_HANDOFF.md

File metadata and controls

433 lines (316 loc) · 19.6 KB
Raw

UI/UX And Branding Handoff

Use this document as the opening context for a new chat focused on improving the Create Python App (CPA) ecosystem branding, UI/UX, website, landing pages, template presentation, and developer-facing engagement.

Goal

Run a complete UI/UX and branding review across the Create Python App ecosystem and then implement improvements that make the project feel more polished, trustworthy, memorable, cozy, modern, and attractive to developers.

The target outcome is not just "better looking". The goal is better engagement, higher adoption, clearer positioning, stronger brand identity, and a more delightful first impression across GitHub, PyPI, the website (when it exists), and generated/template-facing experiences.

Repositories And Areas To Review

Primary repositories:

  • Create-Python-App/create-python-app (this monorepo)
  • Create-Python-App/cpa-templates (template and extension catalog)
  • Create-Python-App/homebrew-tap and Create-Python-App/aur-package (distribution)
  • Website repository (optional, not yet created; see docs/CPA_TEMPLATES_TRACKING.md)

Primary surfaces:

  • Root repository README in create-python-app
  • Package README in packages/create-awesome-python-app/README.md
  • SVG hero banner at packages/create-awesome-python-app/assets/hero.svg
  • CLI terminal experience (create-awesome-python-app)
  • Template catalog (templates.json in cpa-templates)
  • Extension/addon catalog pages (future website)
  • Template landing pages or docs pages
  • Generated project starter UIs, especially FastAPI and full-stack templates
  • Any demo screenshots, cards, badges, icons, diagrams, and onboarding copy
  • Docker image, Homebrew formula, and AUR package presentation

CPA Brand Foundation

Working identity from docs/BRAND.md (to be refined):

  • Tagline: One command. Any Python stack.
  • Story: choose template -> add addons -> ship with uv
  • Positioning: Composable scaffolding CLI for production-ready Python apps.
  • Tooling anchor: uv-first workflow (PyPI via uvx, workspace dev via uv sync).

Designers should treat this as a starting point, not a final brand system. The next pass should evaluate whether the tagline, story arc, and visual identity fully support adoption and trust.

CLI Terminal Experience (Current Implementation)

The CLI is the primary interactive surface today. Designers and implementers must understand how it behaves before proposing changes.

Output channel: Rich on stderr

All user-facing CLI output uses Rich Console(stderr=True) in:

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

Stdout stays clean for piping and scripting. Status, tables, prompts metadata, and colored messages go to stderr.

Version and banner

  • --version prints the package version string only (no banner, no extra copy).
  • --info / -i prints environment diagnostics via print_env_info() (OS, Python, uv tooling).
  • There is no animated or ASCII-art startup banner today.
  • The package README references packages/create-awesome-python-app/assets/hero.svg as a static banner image (dark slate background #0f172a, teal headline #14b8a6). This is minimal and not yet aligned with a full brand system.

Interactive vs non-interactive (CI)

Default behavior:

want_interactive = interactive if interactive is not None else (not _in_ci())
  • When CI is 1, true, or yes, interactive prompts are skipped unless --interactive is passed explicitly.
  • In non-interactive mode without --template, the CLI exits with: --template is required in non-interactive mode.
  • CI pipelines and Docker runs should use explicit flags: --template, --addons, --no-interactive, --set key=value.

Flags:

  • --interactive / --no-interactive override the CI default.
  • --set key=value supplies custom option answers without prompts.

Questionary prompt flows

Interactive mode uses questionary with CPA_PROMPT_STYLE (high-contrast blue/green), qmark="?", and pointer="❯".

1. Template selection (select + search filter)

When no --template is provided and interactive mode is on:

  • Prompt: Pick a template
  • Control: questionary.select with use_search_filter=True (↑↓ browse, type to filter)
  • Choices: Choice(title, value) from build_template_choices() in catalog.py
  • Each choice shows a colored category badge, bold name, slug, optional labels, and description
  • Final choice: Use my own template URL -> questionary.text for a custom URL

2. Extension selection (checkbox, two-step)

When no --addons are provided and interactive mode is on:

  • Step A: Which kinds of extensions do you need? -- category-level checkbox
  • Step B: per selected category, {CategoryName} extensions -- item-level checkbox
  • Choices are filtered by template type compatibility

3. Custom options (text / confirm)

From cpa.config.json or catalog customOptions:

  • confirm for boolean options
  • text for string options
  • Password/invisible types are skipped with a yellow warning

Category badges

Interactive template choices use a fixed-width badge from short_category_label() 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 (plain string titles). --list-templates uses Rich tables.

Rich semantic color usage

Style Meaning Examples
[red] Blocking error, exit code 1-2 Invalid --set, invalid --refresh, missing template, catalog slug errors, strict version mismatch, cache verify failure
[yellow] Warning, recoverable Catalog fetch fallback, config parse warning, skipped custom option, version behind latest (non-strict), cache outdated
[green] Success Created {project}, cache clean/remove success, cache verify pass
[cyan] Primary identifier Cache entry IDs
[dim] Secondary/metadata URLs, refs, ages, empty-state hints

Error and warning message tone

Current copy is direct, actionable, and developer-oriented:

  • States what failed and what to do next.
  • Catalog errors: Invalid catalog slug: '{spec}'. Run --list-templates / --list-addons or pass a full URL.
  • Validation errors name the flag and expected format: Invalid --set {item} (expected key=value)
  • Refresh errors enumerate valid values: always, stale, manual
  • Missing dependency: questionary not available (exit 1)
  • Catalog resilience: [cpa] Could not refresh catalog ({err}); using disk cache. or using fixture.
  • Version notice: You are running create-awesome-python-app {current}, latest is {latest}.

Tone guidelines for future copy:

  • Prefer imperative next steps over apology.
  • Keep messages one or two lines; use [dim] for supplementary detail.
  • Prefix recoverable catalog issues with [cpa] for grep-friendly logs.
  • Avoid jargon; assume the reader is a Python developer familiar with uv and git URLs.

Cache subcommand UI

create-awesome-python-app cache provides dir, list, clean, verify, outdated, update, doctor.

Visual patterns:

  • Column-aligned tables for list and outdated
  • [OK] / [FAIL] style marks via green check / red cross in terminal (Unicode today; consider ASCII [ok] / [fail] if brand requires strict ASCII everywhere)
  • Empty states use [dim] with a hint to populate the cache

What Was Already Done

CPA is earlier in its branding maturity than Create Node App (CNA). Documented baseline:

Completed in create-python-app:

  • Root README.md with ecosystem table, install paths (uvx, Homebrew, AUR, Docker), and monorepo layout.
  • Package README at packages/create-awesome-python-app/README.md with minimal hero SVG reference.
  • Placeholder hero SVG at packages/create-awesome-python-app/assets/hero.svg (dark background, teal text).
  • Working brand notes in docs/BRAND.md (tagline and story).
  • Full interactive CLI with CNA-parity flows (select+filter templates, checkbox extensions, custom options).
  • Rich stderr output and semantic coloring across scaffold and cache commands.
  • Catalog integration with cpa-templates default URL and CPA_CATALOG_URL override.

Not yet done (gaps vs CNA handoff completeness):

  • No website repository or deployed landing pages.
  • No polished npm/PyPI README engagement copy (PyPI README is minimal).
  • Hero SVG and root README lack a cohesive visual identity system.
  • No screenshots, template cards, or curated "build paths" for marketing.
  • Generated template starter UIs not yet reviewed for premium first-run experience.
  • docs/UIUX_BRANDING_HANDOFF.md was a placeholder until this document.

Known Current State

The CLI experience is functional and CNA-aligned for catalog flows, but the broader UI/UX and branding system still needs a full pass.

Current CLI aesthetic:

  • Rich semantic colors (red/yellow/green/cyan/dim).
  • Bright category badges + high-contrast CPA_PROMPT_STYLE on select/checkbox prompts.
  • Minimal hero SVG (slate + teal).
  • No startup banner or branded prompt chrome beyond questionary defaults.

Current brand direction (from docs/BRAND.md):

  • uv-first Python scaffolding.
  • Composable templates + extensions.
  • Production-ready positioning.

Do not assume the current teal-on-slate hero or hash-colored badges are final. Treat them as implementation defaults to review and potentially evolve toward a cohesive design system.

User Intent For The New Chat

The user wants a complete review and improvement cycle for:

  • UI/UX of landing pages (when website exists).
  • Branding across the whole CPA project.
  • Website repo quality and visual design (greenfield).
  • Template previews and starter UX in cpa-templates.
  • Visual consistency between GitHub, PyPI, docs, CLI, and templates.
  • Engagement and adoption.
  • A more cozy, attractive, polished, memorable brand.
  • CLI prompt flow polish (select+filter, checkbox, error tone, banner).

The user explicitly wants the new chat to review everything, not only CLI internals or README tweaks.

Desired Review Mindset

Start with discovery and audit before implementing.

Review the ecosystem like a product designer, brand strategist, frontend engineer, and developer advocate.

Assess:

  • First impression (GitHub README, PyPI page, first uvx run).
  • CLI prompt clarity and perceived quality.
  • Visual hierarchy in terminal lists and cache tables.
  • Messaging clarity (tagline, story, uv positioning).
  • Brand memorability.
  • Emotional tone (cozy vs cold infrastructure).
  • Developer trust.
  • Copy quality across errors, warnings, and success states.
  • Accessibility (contrast, NO_COLOR respect, screen reader limits of terminal UIs).
  • Responsiveness (N/A for CLI; required for website and template UIs).
  • Consistency across surfaces.
  • Conversion path from visitor to first scaffold.
  • Conversion path from user to contributor.
  • Whether generated templates feel premium or generic.
  • Parity and differentiation vs Create Node App.

Avoid generic "AI slop". The design should not feel like a generic SaaS landing page or generic neon devtool. It should feel intentional, distinctive, and warm.

Branding Direction To Explore

Explore a brand that balances:

  • Cozy developer workspace.
  • Polished open-source infrastructure.
  • Productive scaffolding/composition.
  • Friendly automation.
  • Craft, clarity, and reliability.
  • Modern but not cold.
  • Technical but approachable.
  • uv-native Python identity (distinct from Node/npm CNA).

Potential themes to evaluate:

  • Cozy command center.
  • Developer greenhouse/nursery for growing Python apps.
  • Modular workbench.
  • Creative coding studio.
  • Friendly infrastructure toolkit.
  • Warm terminal / soft cyberpunk.
  • Bento-grid developer dashboard.
  • Calm productive OS.
  • "Ship with uv" velocity story.

Potential visual vocabulary:

  • Soft gradients.
  • Warm dark mode.
  • Cream/off-white surfaces.
  • Muted greens, amber, violet, cyan (align with hero teal #14b8a6 or evolve it).
  • Friendly geometric icons.
  • Cards with depth but not heavy glassmorphism.
  • Clear screenshots and product diagrams.
  • Human-readable CLI examples in docs.
  • Template cards that feel curated, not dumped from JSON.
  • Stable category colors shared between terminal badges, website, and docs.

Questions The New Chat Should Answer

Before implementation, produce a complete audit answering:

  • What is the current brand personality?
  • What should the brand personality become?
  • Does the CLI first run explain the product clearly in the first 5 seconds?
  • Do select+filter and checkbox flows feel premium and discoverable?
  • Should website/docs category badges use semantic colors (CLI titles stay plain for questionary)?
  • Does the PyPI package README convert visitors into users?
  • Does the root GitHub README convert visitors into contributors?
  • Are templates presented in a way that feels premium and trustworthy?
  • Are template/generated UIs visually appealing enough?
  • Are screenshots, demos, and visual assets consistent?
  • Are colors, fonts, spacing, and iconography coherent across CLI, README, and templates?
  • Is NO_COLOR / non-interactive / CI behavior documented and visually acceptable?
  • Are CTAs clear (uvx install, template pick, addon select)?
  • Is AI-ready positioning clear but not gimmicky?
  • What is missing for adoption and trust?
  • What should be redesigned first for highest impact?
  • How does CPA differentiate from CNA while maintaining parity?

Suggested Work Plan For New Chat

  1. Discover repositories and docs (README.md, docs/, AGENTS.md, CONTRIBUTING.md, docs/BRAND.md, CI config).
  2. Run the CLI interactively and in CI mode; capture stderr output samples.
  3. Read catalog.py and cli.py for prompt and color behavior.
  4. Inspect cpa-templates catalog and starter template UIs.
  5. Inspect the website repo if/when created.
  6. Audit current UI/UX and branding across all surfaces.
  7. Produce a prioritized design strategy.
  8. Define a cohesive brand direction (extend docs/BRAND.md).
  9. Propose CLI banner, hero SVG, and category color system updates.
  10. Implement improvements incrementally.
  11. Validate with lint/build/tests and manual CLI screenshots where applicable.
  12. Open PRs only after review and green checks.

High-Impact Improvements To Consider

CLI and terminal:

  • Optional branded banner on first interactive run (respect --no-interactive and CI).
  • Refined questionary styling or custom prompt prefix aligned with brand.
  • Semantic category color map shared with docs/website.
  • Improved empty states and catalog fallback messaging.
  • ASCII-safe success/error marks if Unicode checkmarks are undesirable in some terminals.
  • Consistent [cpa] prefix for all recoverable warnings.

Website (future):

  • Rework homepage hero and above-the-fold messaging.
  • Product story: choose template, add addons, ship with uv.
  • Visual template/extension catalog cards using stable category colors.
  • Popular recipes or build paths (e.g. FastAPI + GitHub setup).
  • Contributor-oriented section.
  • Screenshots or diagrams consistent with the brand.
  • Mobile layout and spacing.
  • CTA hierarchy toward uvx create-awesome-python-app@latest.

Templates (cpa-templates):

  • Review generated landing pages and starter homepages.
  • Replace generic starter screens with polished, branded examples.
  • Premium first-run experience after scaffold completes.
  • Ensure accessibility and responsive behavior in web templates.

Docs and READMEs:

  • Engaging PyPI README with raw GitHub hero URL for reliable rendering.
  • Contributor-focused root README.
  • Align messaging across README, docs/BRAND.md, and future website.
  • Consistent terms: templates, extensions/addons, uv, CI-friendly, cpa.config.json.
  • Document interactive vs --no-interactive UX for CI authors.

Visual identity:

  • Define palette and typography recommendations (extend hero SVG direction).
  • Define card/icon/badge style for catalog and docs.
  • Define illustration/hero style.
  • Define voice and tone (match CLI error copy guidelines).
  • Define how "cozy" and "developer infrastructure" coexist.
  • Define category badge colors for website/docs cards (CLI already uses bright ANSI badges).

Constraints And Standards

  • Documentation, PR descriptions, and commit messages should be in English.
  • Respect repo-specific instructions and existing conventions.
  • Do not commit without review.
  • Prefer small, correct changes over large unfocused rewrites.
  • Validate commands with evidence (uv run pytest, make lint, etc.).
  • Preserve PyPI/GitHub rendering compatibility.
  • For SVGs, avoid invalid XML, external fonts, scripts, and unsupported constructs.
  • For PyPI README images, prefer absolute raw GitHub URLs if PyPI rendering is required.
  • Use accessible contrast and readable text sizes.
  • Respect NO_COLOR and CI non-interactive defaults in any new CLI styling.
  • Keep Rich output on stderr; do not break stdout piping.
  • Prefer ASCII in new user-facing docs unless terminal fidelity requires otherwise.

CLI Behavior Reference (Quick)

# Interactive (default when not in CI)
uvx create-awesome-python-app@latest my-app

# Non-interactive (CI / scripting)
uvx create-awesome-python-app@latest my-app \
  --template fastapi-starter \
  --addons github-setup \
  --no-interactive \
  --no-install

# Version (stderr, plain version string)
create-awesome-python-app --version

# List catalog (Rich tables on stderr)
create-awesome-python-app --list-templates
create-awesome-python-app --list-addons --template fastapi-starter

Environment variables affecting UX:

Variable Effect
CI Disables interactive prompts unless --interactive
NO_COLOR Honored by Rich output (list tables, messages)
CPA_CATALOG_URL Override catalog source
CPA_NO_CATALOG_CACHE Force catalog refresh
CPA_STRICT_VERSION Treat version mismatch as error

Suggested Opening Prompt For New Chat

Use this as the first message in the new chat:

We need to do a full UI/UX and branding review of the Create Python App ecosystem.

Please start with discovery and audit before implementing. Review the root create-python-app repo, the package README, cpa-templates, and docs/BRAND.md. The goal is to improve engagement, attraction, branding, cozy developer experience, visual consistency, and conversion across GitHub, PyPI, docs, CLI, and generated starter UIs.

The CLI already uses Rich on stderr and questionary select/checkbox flows with
`CPA_PROMPT_STYLE` plus bright ANSI category badges. Evaluate whether those
defaults should evolve into a cohesive brand system. Pay attention to error
message tone, interactive vs CI non-interactive behavior, and the minimal hero SVG.

Previous work established basic READMEs and BRAND.md notes, but now I want a broader review and a stronger cohesive brand direction. Do not assume the current teal-on-slate hero or terminal colors are final.

Focus on: CLI prompt UX, landing pages (when website exists), template catalog presentation, generated starter pages, README visual presentation, copy, CTAs, accessibility, cozy/premium branding, and developer trust.

First, inspect the repos and produce a prioritized audit + implementation plan. Then implement the highest-impact improvements, validate, self-review, and prepare PRs when ready.

Final Note

The next chat should not simply tweak the hero SVG or badge colors in isolation. It should treat the whole Create Python App ecosystem as a product and brand that needs a cohesive design system, stronger storytelling, and better visual polish across every developer touchpoint -- from the first uvx run through the generated template's first page.