Andrea's first redesign

Collection naming update

The second Guanza collection is now Piezas Intervenidas in Spanish and Reimagined Pieces in English. The English carousel uses the shorter Reimagined heading; collection navigation, page headings, metadata, and accessible collection names use the full name. Product labels use Pieza intervenida / Reimagined piece. Descriptive image alt text and merchant-entered product content stay unchanged.

Public URLs remain /guanza/piezas and /en/guanza/piezas. The hero image is /guanza/piezas-intervenidas.webp. The old country-prefixed /[countryCode]/collections/[handle] page has been removed without redirects.

For Medusa, edit only the existing collection's title to Piezas Intervenidas. Its ID, handle piezas-únicas, product assignments, variants, prices, inventory, and Garage media must remain unchanged. The explicit, idempotent apps/backend/src/scripts/rename-piezas-collection.ts operation can apply the title-only update with npx medusa exec ./src/scripts/rename-piezas-collection.ts from the backend directory in the intended environment. It does not run at startup or as part of a normal frontend deployment. Editing the title in Admin is equivalent. Never run seed or fixture scripts to apply this rebrand.

The collection was previously named Piezas Únicas / Unique Pieces. Historical redesign handoffs now use the current display name for readability; their recorded internal handles and dated technical facts remain unchanged. The rebrand changes presentation, not ownership or identity of catalog data.

Rebrand release — October 24, 2026

The storefront was deployed from bf8865d2544005883f1c64e8e3fd9d3d63991d8f on feat/ui-piezas-rebrand, using the storefront target without migrations. The automatic planner also flags Medusa because it sees maintenance-script changes; review confirmed those were scripts and tests, not a backend runtime change, so the running backend image was retained.

The reviewed title-only operation ran once through medusa exec, using the existing backend image and normal production configuration in a temporary container with the compiled script mounted read-only. Collection ID pcol_01M20YT7JJD5PKNVP034ZHMV7B and handle piezas-únicas were preserved; only its title changed to Piezas Intervenidas. No seed, migration, product reassignment, or media import ran.

Public Spanish and English carousel and collection pages returned HTTP 200 with the approved names. The renamed hero image and a product image returned HTTP 200; the removed legacy collection route returned HTTP 404. The storefront passed its health check. Medusa, PostgreSQL, Redis, and Garage retained their existing running containers and persistent volumes.

Original redesign

Andrea's first redesign turned a portfolio-and-store prototype into a coherent bilingual experience: a personal landing page, an architecture portfolio, and Guanza, a real Medusa-backed store with distinct collections. It went live on September 27, 2026, without replacing the commerce database or resetting Andrea's catalog.

This topic explains the choices, implementation and review process. For current commands, use local operations and the deployment runbook. The original step handoffs linked below are dated engineering records, not instructions to repeat the migration.

What we started with

The portfolio homepage and /portfolio showed the same architecture page. Spanish store links reached the Medusa storefront under /cementos/co, while the English /en/cementos route showed a separate simulated catalog. The store had duplicate catalog entry pages, inconsistent navigation back to Andrea's homepage, and oversized product titles that could overlap their images.

We captured the existing layout before changing it:

The baseline record includes the original portfolio and catalog screenshots, route inventory and data audit. Separating observations from assumptions mattered: a route file did not prove a working account journey, and an empty local collection table did not describe the VPS.

Design direction

Andrea wanted a quiet architectural presentation, not a conventional storefront full of competing controls. Her references guided these decisions:

• One personal entrance. The landing introduces Andrea and offers two clear destinations: Arquitectura and Guanza. The Journal remains a separate site.
• A shared visual language. Cinzel supplies display titles and the AZ. wordmark; Sofia Sans Condensed supplies body and interface text. Fontsource variable-font packages are pinned and bundled into both applications, so the browser does not need to contact Google Fonts.
• Catalog-paper colors. The outer background is the lighter off-white #f0efec, sampled from Andrea's catalog reference. Product-image fields use the slightly darker #e9e7e5, with thin dividers and restrained clay accents.
• Direct browsing controls. Architecture galleries use explicit buttons and an optional overlay. The inspiration site's required panning and persistent enlarged project panels were not copied.
• Collections before products. The Guanza entrance gives Orígenes and Piezas Intervenidas their own visual space. Empty future collections are not shown.

Reference, conceptual and sample imagery is labeled. Deploying the reviewable experience did not turn that imagery or provisional product facts into Andrea's final approved content.

One domain, two frontend applications

The redesign kept the existing Vinext portfolio, Next.js storefront and Medusa backend. Combining a visual redesign with a framework migration would have expanded the release and its failure modes unnecessarily.

Experience	Spanish	English	Application
Personal landing	/	/en	Portfolio
Architecture	/arquitectura	/en/arquitectura	Portfolio
Guanza entrance	/guanza	/en/guanza	Storefront
Orígenes	/guanza/origenes	/en/guanza/origenes	Storefront
Piezas Intervenidas	/guanza/piezas	/en/guanza/piezas	Storefront
Product	/guanza/productos/<handle>	/en/guanza/productos/<handle>	Storefront
Cart	/guanza/carrito	/en/guanza/carrito	Storefront

Spanish is unprefixed; English always begins with /en. Both languages use Medusa's Colombia region and COP. Changing language must not change the market, inventory, selected variant or cart.

A Next.js basePath of /guanza would not also support /en/guanza. Instead, one storefront build uses an empty basePath and application-owned public locale routes. Nginx dispatches both store route families to that same service. Next's built assets have a /guanza prefix to avoid collision with the portfolio assets; store BFF endpoints live under /guanza/api, while architecture contact remains /api/contact/whatsapp in the portfolio.

Cross-application navigation uses ordinary anchors. Neither application's client router owns the other's pages, and the portfolio does not need Medusa to render.

Building the experience in contained steps

The implementation followed seven stages, keeping the route contract ahead of the visual work and production operations separate from local experiments.

Stage	Main result	Engineering record
1. Baseline and routes	Captured the existing UI; established bilingual routing, app ownership and asset isolation	Baseline
2. Shared foundation	Shared brand, fonts, colors, header/footer and contact boundaries	Foundation
3. Landing and architecture	Two destination tiles, bilingual content, controlled architecture galleries	Landing and architecture
4. Guanza and collections	Collection carousel, Medusa product browsing and four marked Piezas samples	Guanza browsing
5. Localization and continuity	Equivalent customer journeys, route-preserving language switch, guest cart and inquiry handoffs	Steps 5–6
6. Integration and review	Proxy-based browser review, inventory-control fix and viewport/gallery refinements	Layout review, product gallery
7. Release and cutover	Production-image rehearsal, backups, bounded frontend switch and live verification	Preparation, cutover

The original plan preserves the starting requirements and acceptance criteria. Each stage used focused tests, builds and linting, followed by integration checks where application boundaries mattered.

What the visual review changed

Review used the actual working site, not only mockups. Andrea and Justin's feedback refined how content uses the viewport:

Landing: the introductory text spans the same content width as the tiles. The footer includes Andrea's email and a WhatsApp launch control, without displaying the number. Above the phone breakpoint, tile heights reduce only when necessary to keep the footer visible, with a 160px minimum. Very short windows and larger text scroll normally; phone layouts stack the tiles. The footer stays in document flow and never overlays content.

Store entrance: the collection carousel keeps the first viewport focused on the collection visual. Its footer follows just below that opening space.

Collection pages: the large heading's surrounding whitespace was tightened to bring products into view sooner.

Product detail: one natural-proportion image replaces stacked fixed portrait frames. A bounded thumbnail rail, previous/next controls and a localized position counter expose multiple photos. Details, variant options and the buy panel have consistent margins. The product section fills at least the viewport below the header; related pieces follow immediately afterward, or farther down only when the actual content needs more space. Related cards are horizontally aligned, with their heading centered over the grid rather than a lowered middle card.

These rules were checked at fixed widths while reducing height, with landscape and portrait products and collapsed/expanded facts. Content is never clipped just to force a one-screen layout. The gallery record also distinguishes implemented controls from future zoom, swatches and image optimization work.

The catalog remained Medusa's

The storefront did not create a competing catalog. Medusa supplies products, option values, variant IDs, calculated prices and availability. Photo files live in Garage; Medusa stores their URLs and associations. Server-side product reads request the product/variant images, options, pricing and inventory needed by the UI. Variant selection updates v_id; add-to-cart sends a real variant ID and quantity back to Medusa, not a browser-decided price.

The store brand Guanza is distinct from its collections. The pre-existing collection with internal handle guanza became Orígenes through an explicit title-only maintenance operation. Its ID, handle and product assignments were verified unchanged. Andrea now selects Orígenes or Piezas Intervenidas in the Medusa Collection field; she does not need to recreate either collection.

Four real photographs supplied by Justin became clearly marked Piezas samples, with authorized provisional names/prices and demo-only inventory. They are ordinary Medusa records that Andrea can revise or delete through Admin.

Purchasing is still a manual inquiry, not payment or a confirmed order. The cart prepares a WhatsApp, email or clipboard summary so Andrea can confirm availability, delivery and the final amount. Customer accounts were preserved, but login/registration is not advertised until the account-readiness work is completed.

Local review without changing production

Early work used an opt-in route-spike overlay. The production-like storefront build avoided a development HMR/hydration issue at the split-app proxy boundary. Later, real production Docker images were rehearsed on a separate loopback-only local port against local Medusa, without reseeding or changing VPS data.

For laptop reviews through ngrok, local Garage image URLs were unreachable from Andrea's device. An opt-in media URL adapter changed only browser-facing URLs to a same-host proxy path; Medusa's files and records were already present and were not changed. Production uses the public HTTPS media hostname and does not enable that adapter. The adapter remains available for future local reviews; see ngrok sharing.

The route spike is now retired. Normal local Compose uses the deployed route contract, while release rehearsal and read-only smoke checks remain reusable tools.

Production cutover and what we verified

Justin authorized deploying the reviewable design before final artwork was ready. The merged application release was 0f56ca8156ef96068bd0ded5fa5b833c9e4c742f. Only the two frontend images were promoted; Medusa retained its existing image. PostgreSQL, Redis and Garage retained their persistent volumes.

Before switching, we captured private configuration, rollback images, a PostgreSQL dump and Garage snapshot/archive, then verified the off-server copy. The database dump was restored only into an isolated temporary verifier. Garage's full recovery was not rehearsed, and the snapshots were not claimed to be an atomic cross-service backup.

The Nginx change preserved TLS, API/Admin/media virtual hosts and indexing restrictions. Justin performed the privileged switch in his own terminal; no password was supplied to the agent. The one-time helper validated the old release and backup, switched the prebuilt frontends, checked health and had a frontend/configuration rollback path that did not restore over merchant data.

Live verification covered both languages, split-app pages/assets/APIs, real product media, collection labels and a disposable guest cart. The same cart and COP price survived language switching. Contact and inquiry endpoints returned the configured WhatsApp redirect; it was inspected without following it or sending a message. No account, paid order or payment was created.

See the cutover record for artifact identities, backup references and the exact checks. Future releases use the normal deployment planner, not the retired cutover helper. Old store bookmarks were explicitly outside this release's compatibility scope.

What remains

The deployed release is a usable review surface, not a claim that every launch gate is complete. Andrea's final landing/carousel/portfolio visuals, product facts and image-rights review remain. Real-device touch, zoom and reduced-motion review, account readiness, optimized image delivery and dependency remediation are separate follow-ups. Indexing restrictions remain in place until explicitly approved for launch.

The directly relevant portfolio React Server Components issue was patched before deployment, but bundled toolchain and unchanged backend audit findings remain documented. Passing frontend checks did not clear the entire stack of security or operational risks.