How I Framed It

Phase 1 was about merchandising independence. I built the theme as a kit of primitives — content blocks the team could compose without code, backed by metaobjects that held the brand's product, ingredient, and routine data in structured form. The design system encoded the editorial standards so the team couldn't accidentally drift off-brand even when iterating quickly. Klaviyo was integrated for lifecycle flows. The result: the buying team could ship campaigns and new product surfaces on their own.

Phase 2 was about architectural independence. Three parallel tracks had to move in concert: the semantic foundation (ARIA, keyboard navigation, RTL), the design system (tokens from primitive hex values up to component-level semantics), and the integration layer (Algolia for search and recommendations, Clerk for auth, Vercel for deployment and QA annotation). Getting the font stack right — Archivo for Latin, Almarai for Arabic — unlocked RTL rendering across the entire storefront with no inline overrides. Getting the token architecture right (primitive → semantic → component) meant dark mode, RTL, and future theme variations could all be driven from one source of truth.

The guiding principle across both phases: the storefront is infrastructure, not a skin. Every decision was made for replaceability and long-term team ownership.

Key Decisions

Phase 1: Theme as a kit of merchandising primitives

Context: Avnzor's team was small and non-technical. Every storefront change required a developer. Campaigns were slow, seasonal updates were stressful, and the team had no visibility into what they could change without breaking something.

Choice: Section-based theme with metaobjects as the data layer. Metaobjects stored the brand's ingredient data, routine tags, and product relationships in structured form — separate from the templates. Content blocks were designed as configurable Shopify blocks so the team could compose new product surfaces from existing primitives without touching code.

Trade-off: Higher upfront build complexity. Every section needed to be designed as a system component, not a one-off layout.

Phase 2: Hydrogen over a headless theme upgrade

Context: Shopify offers headless options at different levels — a customized theme with headless-adjacent patterns, or a full Hydrogen (Remix) app.

Choice: Custom Hydrogen app. Avnzor's roadmap — quiz-driven personalization, lab upload, subscription bundles, bilingual — required full control over routing, data fetching, and component architecture. No theme could accommodate that without accumulating technical debt faster than value.

Trade-off: Significantly longer initial build time and no out-of-the-box theme editor. Every component had to be designed and built from scratch.

Token-first design system over component-first

Context: Starting with components shows faster visible progress. Starting with a token hierarchy creates a multiplier for everything built after.

Choice: Token hierarchy first. Primitive tokens (navy-500, gold-500) → semantic tokens (text-foreground, bg-muted, text-accent) → component usage. Button, Checkbox, and Dialog primitives all consume the same token set — making RTL and dark mode a config change, not a refactor.

Trade-off: Slower visible progress in the first two weeks. Framed clearly to the client as investment, not delay.

WCAG 2.1 AA as a release gate, not a post-launch task

Context: Accessibility audits are typically scheduled post-launch. For a storefront targeting GCC markets with assistive technology users, that order felt backwards.

Choice: Hard gate per route. Full audit across home, collections, PDP, cart, search, sign-in, and CMS pages before any preview URL went out — 34 issues across four severity batches, all resolved first.

Trade-off: Added roughly two weeks to the initial delivery timeline. The alternative — retrofitting ARIA and keyboard navigation into production components — would have taken longer and been far more disruptive.

Algolia with bilingual indexing over Shopify native search

Context: Shopify's native search is English-first and has no recommendation layer. Avnzor's catalog spans 1,000+ Arabic-named SKUs.

Choice: Algolia with bilingual indexing and the Recommend API for Frequently Bought Together. The sync pipeline handles Arabic title correction and indexing patches for metafield data. The FBT component renders in the correct language client-side based on locale.

Trade-off: Ongoing Algolia operational cost and custom batch-translate scripts required to maintain Arabic index quality.