Skip to content

Andrea redesign 1: implementation handoff

Historical implementation plan. Start with the redesign story for the completed result; use current operations runbooks for commands. The redesign went live on September 27, 2026. Temporary tooling named in stage records was subsequently retired or generalized on jm/post-redesign.

Date: 2026-09-23 (America/Bogota). Branch: jm/andrea-redesign-1. Status: approved implementation plan; Step 1 local routing slice completed on 2026-09-24. See baseline and route contract.

Purpose and authorization

Implement Andrea Carolina Zambrano Garcés's first design feedback: a personal landing page, an architecture portfolio, and a real Medusa store branded Guanza, with consistent Spanish/English navigation and a shared visual identity.

This document was the handoff contract for the lead agent and later subagents. The original request authorized documentation changes and their commit only. Follow the active user's instructions for implementation, delegation, commits, pushes, and deployment. Do not modify the VPS or production catalog merely by following this plan. Preserve existing data; this is not another throwaway seed.

Work in the WSL checkout /home/justin/repos/AndreaWeb. Read AGENTS.md and the applicable .github/instructions/ documents before changing each surface. Resolve stale PoC claims against actual app code, Compose, and current runbooks.

Current behavior and reasons for redesign

Observation Evidence and implication
Root and /portfolio both display the portfolio Root must become a distinct landing page; architecture gets its own route.
/cementos/co and /cementos/co/store show the catalog Both route modules render StoreTemplate; /store additionally handles sorting, pagination, and option filters. Replace this redundant entry experience with collection selection.
co is visible in store URLs src/proxy.ts and [countryCode] routes select a Medusa commerce region. It is not a language.
/en/cementos looks different It renders CementStore in the portfolio app, the old simulated store. Spanish reaches the Next.js/Medusa app. Both languages must reach the same real commerce implementation.
Store has no consistent way home Logo currently returns to store root; portfolio link is desktop-only. All new public headers need AZ. linking to the localized personal homepage.
English is not fully available Locale-cookie/API plumbing and a conditional menu selector exist, but custom store copy is substantially Spanish. Translate the entire customer journey.
Cuenta exists Real registration/login, customer creation, cart transfer, and conditional email verification code exists. Runtime readiness and email delivery are unverified; do not describe accounts as fake or fully working without tests.
Product title overlaps image Current desktop detail grid has three columns and oversized text in a narrow first column. Reproduce with long names and fix the layout, not merely the stacking order.

Starting code: apps/storefront/src/app/[countryCode]/(main)/, apps/storefront/src/proxy.ts, apps/storefront/next.config.js, apps/storefront/src/modules/layout/templates/nav/index.tsx, apps/storefront/src/lib/data/customer.ts, apps/storefront/src/lib/data/locale-actions.ts, apps/storefront/src/modules/products/templates/index.tsx, apps/storefront/src/styles/globals.css, apps/portfolio/app/, and deploy/nginx.conf / deploy/nginx-vps.conf.example.

Scope boundaries

  • Keep the current portfolio/Vinext and storefront/Next.js applications for this iteration. Do not combine a framework migration with this redesign. Astro remains a later portfolio option.
  • Keep Medusa, PostgreSQL, Redis, Garage, and existing merchant Admin behavior.
  • Keep manual inquiry purchasing; no payment processor integration in this work.
  • Keep journal.andreazambrano.co as the blog destination. Do not change the Journal repository, domain, DNS, editor, or design. A possible future rename to diario is explicitly deferred.
  • Do not redesign or deploy the Docs site; it can receive this document in the next normal documentation export.
  • Preserve preview indexing restrictions until separately approved for launch.
  • Future store lines Velas, Zapatos, and Aretes should be easy to add, but do not publish empty collections or pretend products exist.

Public route and language contract

Spanish is the unprefixed default. English always uses /en first. Keep the same Spanish route slugs in both languages for this iteration; translate labels and content. Show accents in names, but use ASCII slugs (origenes).

Experience Spanish English Owner
Personal landing / /en portfolio
Architecture /arquitectura /en/arquitectura portfolio
Store collection carousel /guanza /en/guanza storefront
Orígenes /guanza/origenes /en/guanza/origenes storefront
Piezas Intervenidas /guanza/piezas /en/guanza/piezas storefront
Product detail /guanza/productos/<handle> /en/guanza/productos/<handle> storefront
Cart /guanza/carrito /en/guanza/carrito storefront
Customer account, if exposed /guanza/cuenta /en/guanza/cuenta storefront
Journal existing Journal Spanish destination existing Journal English destination external GitLab Pages app

Language is independent from market: both languages initially use Colombia and COP. Selecting English must not switch region, currency, stock, or cart. Product handles need not be translated; localized content is a separate concern. Language switching retains product/collection, meaningful filters, and cart. Use explicit Spanish content fallback for untranslated merchant content; never silently manufacture product descriptions or physical specifications.

Routing implementation gate

Before parallel UI work, the lead must settle and document the concrete Next.js route/proxy strategy. A single compiled basePath: /guanza does not by itself support /en/guanza. Do not implement this as an untested Nginx text replacement.

Evaluate application-owned locale routes with an empty or deliberately isolated base path, plus coordinated reverse-proxy routing and asset namespaces. Verify that portfolio and storefront framework assets do not collide. If internal country routes remain behind rewrites, prove that links, redirects, server actions, images, APIs, and canonical URLs never leak internal /co routes. Do not deploy two independently configured copies of the shop merely to translate it.

Inventory and test all affected surfaces:

  • Next.js base path, proxy matcher, route params, localized link helper, metadata.
  • Storefront asset/image URLs, API/BFF paths, server actions and forwarded origins.
  • Cache keys/tags and locale cookies; prevent translated responses leaking across locales. Cart/auth cookie scope must survive the new routes and language toggle.
  • Local Nginx and VPS template locations for both /guanza and /en/guanza.
  • Compose/build arguments, environment templates, deploy scripts, health checks.
  • Cross-app navigation: normal anchors where appropriate; do not let one app's client router claim the other app's routes.

Centralize route builders and brand configuration at a small, justified shared boundary. Agree on the API before multiple agents consume it.

Legacy redirects

September 27 scope update from Justin: legacy bookmark/deep-link compatibility is deferred. Do not add redirect bridges, filtered compatibility pages, or old account/order routing for this cutover. Existing legacy portfolio pages may remain; old store links need not work. The migration inventory below is retained for a possible later release, not a current acceptance gate.

Create an explicit route migration table during implementation. At minimum:

  • /portfolio and /en/portfolio to their new architecture routes.
  • /cementos, /cementos/co, and /cementos/co/store to the appropriate Guanza destination. Catalog links with meaningful filters should preserve their intent; a filtered catalog must not become an unfiltered carousel by accident.
  • /en/cementos to real English Guanza; account for old #collection links.
  • Existing collection, category, product, cart, and account deep links to their equivalent new destinations, preserving supported query parameters.

Do not redirect POST/API requests with page redirect rules. Use permanent page redirects only when the mapping is finalized, avoiding chains and loops. Unknown paths should produce a helpful 404, not silently route every request to home.

Visual and content specification

Shared frame

  • Sticky header on landing, portfolio, and all storefront pages.
  • Larger AZ. wordmark, including the period, links home for the current language.
  • Arquitectura / Architecture and Guanza sit immediately beside it on the left.
  • Language control is always discoverable on the right, including mobile.
  • Store pages have accessible cart access/count. Search is optional for the first pass: add it only with working behavior, never a decorative input.
  • Footer retains Bogotá, Colombia and dynamic year. Place a quiet Diario / Journal link there initially; make a third header link or landing tile configurable later.
  • Use Cinzel for major titles; Sofia Sans Condensed for body and secondary titles, using heavier weights for navigation and small headings. Prefer self-hosted font assets with appropriate licenses and Spanish glyphs; avoid duplicate loads.
  • Sample the catalog reference background during asset preparation: a pale warm off-white, not the current stronger beige. Use charcoal text, restrained accents, thin dividers, accessible contrast, and shared design tokens across both apps.

Landing page

Use the two-tile layout in Andrea's mockup: short introductory paragraph above large Arquitectura and Guanza tiles, with their labels below. Both image and label activate the destination. Stack appropriately on narrow screens. Use her Guanza composition for the store tile and existing architecture stock imagery as an explicit placeholder. Keep headings as HTML rather than text burned into images.

Andrea's supplied draft introduction:

Bienvenidos a mi mundo. Soy arquitecta con maestría en diseño de espacios y experiencias culturales. Me enfoco en el diseño conceptual y en la psicología de los espacios. Aquí encontrarás piezas ideales para tu espacio o puedes contratar directamente mis servicios y tener el hogar de tus sueños.

This is user-supplied copy for review, not a license to invent additional degrees, awards, employment, specialties, or completed projects. Provide matching English copy and allow Andrea to revise it easily.

The shop landing is a large image-led carousel below the shared header, with only Orígenes and Piezas Intervenidas initially. Use centered Cinzel collection titles and explicit previous/next controls plus one indicator per actual slide. Do not copy the mockup's five dots when only two collections exist.

Clicking the collection opens its product grid. Support keyboard and touch, visible focus, descriptive control labels, and reduced motion. No auto-advance by default. The carousel should approximately fill the initial viewport beneath the header; footer follows below, with natural scrolling on short/mobile screens.

Use a data-driven collection definition with display order, localized names and copy, image/alt text, route slug, and Medusa collection identity. Guanza is the store brand, not the collection name. Audit the existing GUANZA and Piezas Intervenidas collections and product assignments before mapping the former to Orígenes. Preserve IDs and merchant edits. Do not rerun destructive seed/reset commands. Any production relabeling/data change needs a separate reviewed application step.

Collection grid and product detail

Grid: consistently framed images, product name and price below, restrained zoom inside the frame on hover, visible focus, responsive columns, and working filters, sorting, pagination, stock, sale prices, and variants where already supported. Use actual Medusa values. Do not copy prices from inspiration imagery as catalog data.

Detail: prefer two desktop columns (gallery; information and purchase controls), stacked on mobile. Keep long names within their column, with shrinkable grid children and intentional word wrapping. Never fix title/image overlap by hiding text or placing text above the image with z-index. Preserve full product images, variant selection, image changes, availability, quantities, and cart actions.

Architecture and galleries: explicit interaction requirements

Opening section fills roughly the viewport under the header: biography, studies at Universidad de los Andes in Bogotá, methodology/services draft, and contact on one side; Andrea's portrait/collage on the other. Mobile stacks naturally.

Below it, display multiple projects as landscape presentation-board previews with descriptions and per-project galleries. Use doblecarta proportions (typically 17:11 landscape) without forcing every future asset into a crop. Boards and drawings must use contain-style presentation so annotations remain visible.

The BIG references are inspiration for project imagery and storytelling only:

Do not reproduce panning or scroll-driven cycling between project sections. Andrea's site must provide explicit left/right buttons and optional swipe/keyboard navigation. Ordinary page scrolling must continue scrolling the page.

Do not leave a selected project permanently enlarged. Clicking a board opens a dismissible overlay/lightbox covering most of the viewport, within the same /arquitectura page. Closing via a visible button or Escape restores the project list, prior scroll position, and focus on the triggering item. Only one overlay may be open. Trap focus while open and keep background content inert. Project selection must not navigate to a new project page. If URL state is used for sharing/back behavior, keep the pathname and define Back-to-close semantics.

Within the overlay, use clear previous/next controls, image counter, project title/caption, and fit-to-view boards. Swipe must not be required. Inline preview arrows must not accidentally open the overlay. Keep the selected board consistent when opening/closing. Load large boards on demand, with useful low-resolution previews and explicit dimensions to avoid layout shifts.

Define an editable project data model: stable ID, localized title/summary, location/year/type/Andrea's role when supplied, ordered boards with dimensions, alt text/captions/credits, and optional featured/order fields. Placeholder projects must be marked as demonstration content, not claimed as Andrea's real work.

Contacts, accounts, and inquiry semantics

  • Architecture email: andrea@andreazambrano.co.
  • Shopping email: retain cementos@andreazambrano.co until explicitly changed; the Guanza rebrand does not authorize inventing a new mailbox.
  • LinkedIn: https://www.linkedin.com/in/andreaczambranog/.
  • Business WhatsApp approved by the user: +57 318 0703540, normalized as 573180703540 in ignored runtime configuration. Replace the former personal destination when deploying the approved release. Do not hard-code it into client bundles or rendered page links.
  • Use a server-side contact handoff for the architecture CTA as well as shopping. Keep origin validation and configured destinations; do not accept arbitrary redirect targets. Match the site's styling with text or a discreet monochrome icon; no large green WhatsApp badge.
  • Server-side configuration prevents embedding the number in page markup but does not make it secret: users can inspect the eventual WhatsApp redirect.
  • Keep guest shopping primary. Audit customer registration, login/logout, email verification/delivery, account pages and cart transfer locally before deciding account prominence. Hide or demote an unverified flow rather than pretending it works. Do not delete existing accounts or remove backend authentication.
  • WhatsApp/email/clipboard inquiry is not payment, reservation, or a confirmed Medusa order. Sending it must not decrement stock or empty the cart. Preserve browser Back behavior and localized variant/quantity/price message formatting.

Visual reference inventory and asset handoff

The 13 screenshots supplied in the redesign request are design references. Their temporary Windows files may not exist for a future agent. Before visual work, preserve needed references/approved assets in an appropriate project location, record provenance, and optimize separately. Do not depend on a user's Temp path at build/runtime. Obtain the original catalog/boards when available; screenshots are sufficient for this first preview, not a substitute for final high-resolution art.

Reference Meaning Clipboard file identifier
1, 2 Current Spanish real store vs English PoC inconsistency 78f28b9b-00d1-4b8f-8fbc-071230327690, 531ea133-3984-4469-ab5a-79407f772382
3 Existing Medusa collections fa2ff34e-5839-4534-bbf9-82aba72650a4
4, 10 Landing layout a9b67a10-e52b-4a3d-80f1-612d5d754b5e, 052248c2-b9e8-40e2-b9d5-ea4eb5ead006
5 AZ. wordmark and left navigation 69bf5a6e-16a5-4854-ab71-27d1696e8f4a
6 Guanza tile/collection artwork 4ddc254f-ba45-4d69-bc8d-ee7adfdf795d
7, 8 Orígenes carousel composition da5cd263-4f6a-46d9-894b-279bdf220961, 769b2f25-62b7-4368-b7fa-f76e5645e175
9 Piezas Intervenidas imagery and thumbnail/price treatment fbd095fa-e658-4670-ac78-8feba5469c57
11 Cinzel / Sofia Sans Condensed 307fc4ac-4871-4152-bc89-176b59c5b7b2
12 Catalog background, hierarchy, price styling 2ecbfc8f-b5ef-43c6-80df-27723ac74b27
13 Architecture project stack with gallery arrows 5d7efdf2-71fa-452f-834c-c4574fc74942

Files originally follow C:/Users/tweek/AppData/Local/Temp/codex-clipboard-<id>.png. The request also mentions a catalog cover and additional grid/three-tile examples; do not assume an unlisted original PDF or extra image was supplied. Follow the described design using available material. Generated/stock illustrations may be used for explicit placeholders, never as evidence of Andrea's completed work or as an inaccurate depiction of a purchasable product.

Implementation sequence and checkpoints

  1. Baseline and route contract. Inspect current branch/status, local services, app instructions, deployed-route templates, tests and catalog mappings. Record baseline screenshots and reproduce the product overlap. Settle the route, region/locale, cookie, asset, and proxy strategy described above. Exit: both language paths can reach the same real storefront in a local integration spike. Completed locally: both entry paths reach the same Medusa catalog through the opt-in Compose/Nginx overlay; existing production routing is unchanged. The baseline document records evidence and later cutover gates.
  2. Shared foundation. Introduce brand tokens, fonts, route builders, shared navigation conventions and contact configuration. Agree on component/config interfaces before parallel work. Exit: header/footer equivalence on both apps, including mobile and localized home links. Completed locally: both apps now have aligned AZ. navigation, type/color tokens, public contact contracts, and footer conventions. The new Guanza routes retain the legacy catalog and cart bridge until Steps 4–5. See the foundation handoff for exact routes, caveats, and checks. Nothing has been deployed.
  3. Landing and architecture. Implement tiles, intro, biography/contact area, project model, inline gallery controls and dismissible overlay. Exit: usable desktop/mobile demonstration with clearly labeled placeholder projects. Completed locally: both languages have a two-tile landing and architecture page with contact links and conceptual galleries. The overlay preserves the selected board, scroll position, and focus. See the Step 3 handoff for content and release caveats. Architecture WhatsApp remains pending the server-side contact handoff.
  4. Guanza and collection browsing. Implement two-slide landing, existing collection mappings, catalog cards/filtering, and two-column product details. Exit: real Medusa browsing with no title overlap or simulated catalog fallback. Implemented locally: both language routes now use the same Medusa-backed carousel, collection grids, and product details. Four clearly marked sample Piezas Intervenidas products and images were added to the VPS catalog by explicit authorization, but the redesign has not been deployed. Browser-level layout and commerce journey review remain in Steps 5–6. See the Step 4 handoff.
  5. Localization and commerce continuity. Translate UI and message flows, implement route-preserving toggle, check account readiness, and connect new business contact configuration. Exit: one cart survives browsing, language changes and inquiry handoff; prices and stock still come from Medusa. Implemented locally: the bilingual Guanza UI and inquiries use one Medusa cart/region; the architecture WhatsApp handoff is server-only. Account entry is hidden pending the documented delivery/authentication checks. See the Steps 5–6 handoff and account audit.
  6. Integration and visual review. Run checks below, gather screenshots, fix regressions, document known placeholders and remaining content requests. Present the local preview to Justin/Andrea before production work. Local integration completed: the proxy-based carousel, catalog, product, cart and contact journeys were exercised; a stock-control regression was fixed. A real phone/tablet/touch/zoom/reduced-motion and Andrea content pass remains a release gate. See the Steps 5–6 handoff.
  7. Release preparation after approval. Coordinate both frontend builds, environment values, proxy configuration and redirects. Audit any Medusa relabeling separately. Record rollback commands and old route behavior. Preserve all persistent volumes. Use the existing deployment runbook and obtain required deployment authorization; do not infer it from approval of this plan. Preparation substeps 1–4 completed locally: production build/route settings, isolated release rehearsal, private backup and database restore check, and rollback targets are recorded in the release-preparation handoff. Substeps 5–8 completed on September 27, 2026: merged/pushed to main, final frontend images deployed with the new private settings/routing after refreshed backups were verified off-server. Justin completed interactive sudo; collection title-only relabeling and public HTTP/browser/cart/contact checks passed. The backend image and persistent volumes are preserved. See the cutover handoff for exact release identity and outstanding artwork, real-device and dependency follow-ups. Legacy bookmark compatibility is deferred by Justin.

Suggested cohesive commits when implementation commits are authorized: route and locale foundation; shared branding/navigation; landing/portfolio galleries; Guanza browsing/product layout; inquiry/account localization; integrated routing and deployment documentation. Keep each functional and reviewable.

Subagent ownership contract

Delegate only after the user authorizes agent work and the lead settles shared interfaces. Each task receives this document, exact owned paths, inputs/outputs, acceptance checks, and current route/brand definitions.

Owner Work Must coordinate with lead
Lead/integration Routing, proxy, cookies, shared tokens/header contract, release plan and verification Shared packages/config, Compose, Nginx, lockfiles and backend data changes remain single-owner
Landing/architecture agent Portfolio landing, biography, project data, inline/overlay galleries Consume agreed header/tokens/route helpers; no framework migration
Guanza presentation agent Carousel, collection grid, product detail layout Consume agreed collection mapping, locale props and route builders
Localization/commerce agent UI dictionaries, toggle behavior, cart/inquiry continuity, account audit Coordinate cookie/auth/contact boundaries; no production accounts or sends

Do not have several agents edit global styles, package lockfiles, shared header, proxy or the same dictionaries simultaneously. Use isolated worktrees or agreed file ownership. The lead integrates and runs full cross-app verification. Agents report changed files, tests actually run, screenshots, assumptions, and unresolved issues; they do not independently deploy or reset catalog data.

Acceptance checklist

  • Root is the new two-tile landing; architecture has its own canonical route.
  • AZ. returns home everywhere; header remains available and fits mobile.
  • Spanish and English share the real catalog and layout; no public PoC store.
  • Public store paths omit /co; region remains Colombia/COP in both languages.
  • Toggle preserves corresponding page and populated cart, without locale leaks.
  • Deferred by Justin: legacy page/deep-link redirects and compatibility.
  • Both collections open the correct Medusa products; no destructive reseeding.
  • Product cards, prices, variants, inventory and cart quantities work.
  • Long product titles never overlap images at narrow, medium or wide widths.
  • Collection carousel is usable with buttons, keyboard and touch; no forced autoplay.
  • Architecture boards are uncropped, with explicit section controls and no scroll hijacking.
  • Project overlay closes via button/Escape and restores focus, scroll and normal project size.
  • Contact links use approved mailboxes/LinkedIn and configured business WhatsApp.
  • Inquiry handoff preserves cart and never implies paid/confirmed/reserved stock.
  • Account readiness is explicitly documented and UI exposure matches verified behavior.
  • Cinzel/Sofia Sans Condensed and catalog-inspired palette agree across apps.
  • Footer retains Bogotá, Colombia/year and a working existing Journal link.
  • Placeholder work and content gaps are identified for Andrea's review.
  • Relevant unit/rendered tests, lint/build and local proxy integration pass.
  • Browser review includes small phone, tablet, desktop, keyboard, zoom and reduced motion.
  • Preview noindex remains; new metadata/canonicals reflect new routes.
  • Docs/runbooks record actual routing/build/env changes and rollback procedure.

Use focused regression tests for route mapping, locale/region separation, cart continuity, inquiry origin checks, and meaningful gallery behavior. Do not create production customers or send real contact messages as incidental testing. Use local fixtures and inspect handoff destinations without submitting messages.