Commerce Application

Business Rules Assessment

May 2026

Generated by Inkwell Forge — automated codebase documentation analysis. Subject matter expert review is recommended before distribution.

1. Overview

Scope

This Business Rules Assessment documents every business rule, validation, calculation, and conditional logic observable from the screen-level technical documentation of the Commerce application. Rules are extracted from five screens: Product Detail (/product/[handle]), Home (/), Search Detail (/search/[collection]), Search (/search), and Item Detail (/[page]). Business rules derived from screens not included in the assessed documentation — including the cart, checkout, account management, and any header/navigation components — are outside the scope of this document. This document reflects a partial view of the application; rules governing variant selection, add-to-cart mutations, payment processing, and order management are not covered here.

Methodology

Rules were extracted by systematically scanning each screen's documentation across all documented sections: access control (§2), UI layout and conditional rendering (§3), data flow (§4), API call response handling (§5), event handlers (§6), forms and validation (§7), explicit business logic (§8), navigation (§9), error handling (§10), and security considerations (§14). Each extracted rule is expressed declaratively — stating what must be true or what must happen — rather than describing implementation mechanics. Rules are classified using BABOK v3.0 categories (Structural, Operative, Decision), expressed in controlled natural language per SBVR v1.5 principles, and structured for decision table representation per DMN v1.5 where multiple conditions determine an outcome.

Limitations

All rules in this document are reverse-engineered from technical screen documentation written for developers; they are not derived from requirements documents, policy manuals, or stakeholder interviews. Business rationale is stated only where the documentation explicitly provides it; all other rationale fields are marked accordingly. Rules governing child components referenced in the screen documentation (e.g., ProductDescription, ThreeItemGrid, Carousel, Gallery, ProductGridItems) are not fully documented here because their internal implementations are outside the scope of the provided documentation. Where the documentation identifies a potential defect or edge case, that observation is captured in the Gap Analysis rather than as a rule.

Coverage

This Business Rules Assessment covers 5 screens of the Commerce application:

Business rules derived from screens not included in the assessed documentation are outside the scope of this document.

Disclosure

Generated by Inkwell Forge — automated codebase documentation analysis. Subject matter expert review is recommended before distribution.

How to Use This Document

• Rule Inventory — Quick lookup table of all rules by ID, domain, category, and criticality.
• Business Rules Catalog — Full rule entries with conditions, validation details, rationale, and testing implications.
• Decision Tables — Structured condition/outcome tables for all multi-condition rules.
• Gap Analysis — Identified risks, missing rules, and edge cases requiring attention.

2. Rule Inventory

3. Business Rules Catalog

3.1: Content Visibility & Access Control

Description: Rules governing which content is accessible to visitors, how missing or invalid content is handled, and the public-access policy of the storefront.

Screens involved: Product Detail (/product/[handle]), Home (/), Search Detail (/search/[collection]), Search (/search), Item Detail (/[page])

BR-001: Hidden Product Tag Suppresses SEO Indexing

Domain: Content Visibility & Access Control Category: Operative Enforcement: Server Criticality: High — a failure here would expose draft or internal products to search engine indexing, potentially surfacing incomplete or incorrect product data in search results.

Rule Statement: A product tagged with HIDDEN_PRODUCT_TAG must have its robots.index, robots.follow, and googleBot.index metadata directives set to false, preventing search engine crawling and indexing of that product page.

Conditions:

• Condition 1: product.tags includes the value of the HIDDEN_PRODUCT_TAG constant → indexable = false
• Condition 2: product.tags does not include HIDDEN_PRODUCT_TAG → indexable = true
• Action/Result: When indexable = false, the page metadata sets robots: { index: false, follow: false } and googleBot: { index: false, nosnippet: true } (or equivalent). When indexable = true, default indexing behavior applies.

Validation Details:

• Input: product.tags array from the Shopify Storefront API response
• Rule logic: indexable = !product.tags.includes(HIDDEN_PRODUCT_TAG) — boolean derived at render time
• Pass behavior: indexable = true → standard robots metadata; product is eligible for search engine indexing
• Fail behavior: indexable = false → robots.index = false, robots.follow = false injected into page <head>; product is excluded from search engine results but remains accessible via direct URL

Source Evidence: Product Detail (/product/[handle]) — §2, §8, §14

Business Rationale: Allows merchants to publish draft, internal, or test products at live URLs without those products appearing in search engine results. This is a soft-visibility mechanism, not an access control mechanism — the URL remains publicly accessible.

Related Rules: BR-009 (SEO metadata also controlled by this flag), BR-002 (the complementary hard-visibility rule)

Testing Implications:

• Positive: Product without HIDDEN_PRODUCT_TAG → verify robots metadata allows indexing
• Negative: Product with HIDDEN_PRODUCT_TAG → verify robots.index = false and robots.follow = false in rendered <head>
• Edge case: Product with HIDDEN_PRODUCT_TAG → verify page still renders and is accessible via direct URL (not a 404)
• Edge case: product.tags is an empty array → verify indexable = true

BR-002: Missing Product Handle Renders 404

Domain: Content Visibility & Access Control Category: Operative Enforcement: Server Criticality: Critical — without this rule, requests for non-existent product handles would produce broken or empty page renders rather than a proper HTTP 404 response.

Rule Statement: If getProduct returns a falsy value for a given handle, the application must call notFound() and render the 404 page, both during metadata generation and during page rendering.

Conditions:

• Condition 1: getProduct(handle) returns a truthy product object → page renders normally
• Condition 2: getProduct(handle) returns null or undefined → notFound() is called
• Action/Result: notFound() triggers Next.js's not-found boundary, rendering the application's not-found.tsx page with a 404 HTTP status

Validation Details:

• Input: Return value of getProduct(params.handle) — either a product object or a falsy value
• Rule logic: if (!product) notFound() — enforced independently in both generateMetadata and ProductPage
• Pass behavior: Product object returned → page renders with product data
• Fail behavior: Falsy return → notFound() called → Next.js 404 page rendered; no product UI is shown

Source Evidence: Product Detail (/product/[handle]) — §5, §8, §9, §10

Business Rationale: Ensures that invalid or deleted product URLs return a proper 404 HTTP response rather than a broken page, which is important for both user experience and SEO (search engines should receive 404 for removed products).

Related Rules: BR-003, BR-004 (same pattern on other screens)

Testing Implications:

• Positive: Valid handle → verify full product page renders
• Negative: Non-existent handle → verify HTTP 404 response and 404 page UI
• Edge case: Handle that previously existed but was deleted → verify 404 (not a cached stale render)
• Edge case: generateMetadata receives invalid handle → verify 404 is triggered before page body renders

BR-003: Missing Collection Handle Renders 404

Domain: Content Visibility & Access Control Category: Operative Enforcement: Server Criticality: Critical — without this rule, requests for non-existent or unpublished collections would produce broken or empty page renders.

Rule Statement: If getCollection returns a falsy value for a given collection handle during metadata generation, the application must call notFound() and render the 404 page.

Conditions:

• Condition 1: getCollection(params.collection) returns a truthy collection object → metadata generation proceeds normally
• Condition 2: getCollection(params.collection) returns a falsy value → notFound() is called
• Action/Result: notFound() triggers Next.js's not-found boundary, rendering the application's 404 page

Validation Details:

• Input: Return value of getCollection(params.collection) in generateMetadata
• Rule logic: if (!collection) notFound() — enforced in generateMetadata
• Pass behavior: Collection found → metadata generated and page renders
• Fail behavior: Collection not found → notFound() called → 404 page rendered

Source Evidence: Search Detail (/search/[collection]) — §5, §8, §9, §10, §14

Business Rationale: Prevents access to invalid or unpublished Shopify collection handles, returning a standard 404 rather than a broken or empty page. Also prevents information leakage about the collection namespace.

Related Rules: BR-002, BR-004

Testing Implications:

• Positive: Valid, published collection handle → verify page renders with products
• Negative: Non-existent collection handle → verify HTTP 404 response
• Negative: Unpublished collection handle → verify HTTP 404 response (Shopify returns falsy for unpublished collections)
• Edge case: Collection handle that exists but has zero products → verify page renders with empty-state message (not a 404)

BR-004: Missing Page Handle Renders 404

Domain: Content Visibility & Access Control Category: Operative Enforcement: Server Criticality: Critical — without this rule, requests for non-existent Shopify page handles would produce broken renders rather than a proper HTTP 404 response.

Rule Statement: If getPage returns a falsy value for a given page handle, the application must call notFound() and render the 404 page, both during metadata generation and during page rendering.

Conditions:

• Condition 1: getPage(params.page) returns a truthy page object → page renders normally
• Condition 2: getPage(params.page) returns null or undefined → notFound() is called
• Action/Result: notFound() triggers Next.js's not-found boundary, rendering the application's 404 page

Validation Details:

• Input: Return value of getPage(params.page) — either a page object or a falsy value
• Rule logic: if (!page) notFound() — enforced independently in both generateMetadata and the Page component
• Pass behavior: Page object returned → title, body, and date render normally
• Fail behavior: Falsy return → notFound() called → Next.js 404 page rendered

Source Evidence: Item Detail (/[page]) — §2, §5, §8, §9, §10

Business Rationale: Ensures that invalid or deleted Shopify page handles return a proper 404 HTTP response rather than a broken page.

Related Rules: BR-002, BR-003

Testing Implications:

• Positive: Valid page handle (e.g., "privacy-policy") → verify full page renders
• Negative: Non-existent handle → verify HTTP 404 response and 404 page UI
• Edge case: generateMetadata receives invalid handle → verify 404 triggered before page body renders
• Edge case: Page exists in Shopify but getPage returns falsy due to API error → verify 404 rendered (not a 500)

BR-005: All Storefront Screens Are Publicly Accessible

Domain: Content Visibility & Access Control Category: Structural Enforcement: Server Criticality: Low — this is an intentional design constraint, not a defect risk. Criticality is low because the rule describes the absence of access control, which is the intended behavior for a public storefront.

Rule Statement: All five assessed screens must be accessible to any visitor without authentication, session validation, or role-based authorization checks.

Conditions: None — this rule applies unconditionally to all assessed screens.

Validation Details:

• Input: Any HTTP request to /product/[handle], /, /search/[collection], /search, or /[page]
• Rule logic: No middleware, session check, or permission gate is applied at the page or API level for any of these routes
• Pass behavior: Page renders for all visitors regardless of authentication state
• Fail behavior: Not applicable — no access denial path exists for these routes

Source Evidence: Product Detail (/product/[handle]) — §2; Home (/) — §2; Search Detail (/search/[collection]) — §2; Search (/search) — §2; Item Detail (/[page]) — §2

Business Rationale: These screens display public product catalog and content data. Requiring authentication would create friction for prospective customers and is not appropriate for a public-facing storefront.

Related Rules: BR-001 (soft visibility via SEO tags, not access control)

Testing Implications:

• Positive: Unauthenticated request to each route → verify page renders without redirect or 401/403 response
• Edge case: Request with an invalid or expired session cookie → verify page still renders (no session check)

3.2: SEO & Structured Data

Description: Rules governing how search engine metadata, Open Graph tags, robots directives, and JSON-LD structured data are generated and populated for each screen.

Screens involved: Product Detail (/product/[handle]), Home (/), Search Detail (/search/[collection]), Item Detail (/[page])

BR-006: Product JSON-LD Availability Maps from availableForSale

Domain: SEO & Structured Data Category: Decision Enforcement: Server Criticality: Medium — incorrect availability data in structured markup could mislead search engines about product stock status, affecting rich result accuracy.

Rule Statement: The availability field in the product's JSON-LD structured data must be set to https://schema.org/InStock when product.availableForSale is true, and to https://schema.org/OutOfStock when product.availableForSale is false.

Conditions:

• Condition 1: product.availableForSale === true → availability: "https://schema.org/InStock"
• Condition 2: product.availableForSale === false → availability: "https://schema.org/OutOfStock"

Validation Details:

• Input: product.availableForSale boolean from the Shopify Storefront API
• Rule logic: Ternary mapping: availableForSale ? "https://schema.org/InStock" : "https://schema.org/OutOfStock"
• Pass behavior: Correct schema.org availability URI injected into the JSON-LD <script> block
• Fail behavior: Not applicable — the mapping is deterministic; no failure path exists unless availableForSale is undefined

Source Evidence: Product Detail (/product/[handle]) — §8

Business Rationale: Enables Google and other search engines to display accurate in-stock/out-of-stock status in product rich results, improving click-through quality.

Related Rules: BR-007, BR-008

Testing Implications:

• Positive: Product with availableForSale = true → verify JSON-LD contains "https://schema.org/InStock"
• Negative: Product with availableForSale = false → verify JSON-LD contains "https://schema.org/OutOfStock"
• Edge case: availableForSale is undefined → verify behavior (likely renders "https://schema.org/OutOfStock" due to falsy evaluation)

BR-007: JSON-LD Uses AggregateOffer for Variant Price Range

Domain: SEO & Structured Data Category: Structural Enforcement: Server Criticality: Medium — using the wrong schema type would produce invalid structured data, potentially disqualifying the product from Google rich results.

Rule Statement: The product JSON-LD structured data must use the AggregateOffer schema type to represent the product's price range, populating highPrice from priceRange.maxVariantPrice.amount and lowPrice from priceRange.minVariantPrice.amount.

Conditions: None — this rule applies to all products unconditionally.

Validation Details:

• Input: product.priceRange.maxVariantPrice.amount and product.priceRange.minVariantPrice.amount from the Shopify API
• Rule logic: JSON-LD offers object uses @type: "AggregateOffer" with highPrice and lowPrice fields populated from the respective price range amounts
• Pass behavior: Valid AggregateOffer block injected into the JSON-LD <script> tag
• Fail behavior: If either price amount is missing, the JSON-LD block may contain undefined values, producing invalid structured data

Source Evidence: Product Detail (/product/[handle]) — §8

Business Rationale: AggregateOffer is the correct schema.org type for products with multiple variants at different price points. Using it enables Google to display price ranges in rich results.

Related Rules: BR-006, BR-008

Testing Implications:

• Positive: Product with multiple variants at different prices → verify JSON-LD @type is "AggregateOffer" and highPrice ≥ lowPrice
• Edge case: Product with a single variant (min = max price) → verify highPrice equals lowPrice in JSON-LD
• Edge case: priceRange.maxVariantPrice.amount is missing → verify JSON-LD does not contain undefined as a string

BR-008: JSON-LD Price Currency Sourced from Min Variant Price

Domain: SEO & Structured Data Category: Structural Enforcement: Server Criticality: Low — incorrect currency code in structured data would affect rich result display accuracy but would not break the page or user workflow.

Rule Statement: The priceCurrency field in the product JSON-LD structured data must be sourced from priceRange.minVariantPrice.currencyCode.

Conditions: None — this rule applies unconditionally.

Validation Details:

• Input: product.priceRange.minVariantPrice.currencyCode (e.g., "USD", "EUR")
• Rule logic: priceCurrency field in the AggregateOffer JSON-LD block is set directly from this value
• Pass behavior: Valid ISO 4217 currency code injected into JSON-LD
• Fail behavior: If currencyCode is missing, priceCurrency will be undefined in the JSON-LD output

Source Evidence: Product Detail (/product/[handle]) — §8

Business Rationale: Not stated in documentation — verify with business stakeholders.

[Not documented — WHO: Product owner or SEO specialist; WHAT: Is it intentional to source priceCurrency from the minimum variant price rather than a store-level currency setting, and what should happen if variants have different currency codes?; WHERE: Insert in the Business Rationale field of BR-008 above]

Related Rules: BR-007

Testing Implications:

• Positive: Product with minVariantPrice.currencyCode = "USD" → verify JSON-LD priceCurrency is "USD"
• Edge case: Multi-currency store where min and max variant prices have different currency codes → verify which currency code is used

BR-009: Product SEO Metadata Controlled by Hidden Product Tag

Domain: SEO & Structured Data Category: Decision Enforcement: Server Criticality: High — failure to suppress robots metadata for hidden products would allow draft or internal products to be indexed by search engines.

Rule Statement: If a product is tagged with HIDDEN_PRODUCT_TAG, the page metadata must set robots.index = false, robots.follow = false, and equivalent googleBot directives; otherwise, default indexing metadata must apply.

Conditions:

• Condition 1: product.tags.includes(HIDDEN_PRODUCT_TAG) is true → robots: { index: false, follow: false }, googleBot: { index: false } (or equivalent)
• Condition 2: product.tags.includes(HIDDEN_PRODUCT_TAG) is false → default robots metadata (indexing permitted)

Validation Details:

• Input: product.tags array; HIDDEN_PRODUCT_TAG constant from lib/constants
• Rule logic: indexable = !product.tags.includes(HIDDEN_PRODUCT_TAG) → used to conditionally set robots metadata in generateMetadata
• Pass behavior: Non-hidden product → standard metadata; page eligible for indexing
• Fail behavior: Hidden product → robots.index = false injected into <head>; page excluded from search results

Source Evidence: Product Detail (/product/[handle]) — §2, §8

Business Rationale: Allows merchants to maintain draft or internal products at live URLs without those pages appearing in search engine results.

Related Rules: BR-001

Testing Implications:

• Positive: Product without HIDDEN_PRODUCT_TAG → verify <meta name="robots"> allows indexing
• Negative: Product with HIDDEN_PRODUCT_TAG → verify <meta name="robots" content="noindex,nofollow"> in rendered HTML
• Edge case: Product with HIDDEN_PRODUCT_TAG removed → verify robots metadata reverts to indexable on next render

BR-010: Collection SEO Title Uses Fallback Chain

Domain: SEO & Structured Data Category: Decision Enforcement: Server Criticality: Medium — incorrect or missing SEO titles reduce search result quality but do not break functionality.

Rule Statement: The <title> tag for a collection page must use collection.seo.title if present; otherwise it must fall back to collection.title.

Conditions:

• Condition 1: collection.seo?.title is truthy → use collection.seo.title as the page title
• Condition 2: collection.seo?.title is falsy → use collection.title as the page title

Validation Details:

• Input: collection.seo?.title and collection.title from the Shopify API
• Rule logic: collection.seo?.title || collection.title — optional chaining with logical OR fallback
• Pass behavior: SEO-specific title used when available; collection title used as fallback
• Fail behavior: If both are falsy, the page title will be empty or undefined

Source Evidence: Search Detail (/search/[collection]) — §8

Business Rationale: Allows merchants to set SEO-optimized titles that differ from the collection's display name, following Shopify's standard SEO override pattern.

Related Rules: BR-011

Testing Implications:

• Positive: Collection with seo.title set → verify <title> uses seo.title
• Positive: Collection with no seo.title → verify <title> uses collection.title
• Edge case: Both seo.title and collection.title are empty → verify <title> behavior

BR-011: Collection SEO Description Uses Three-Tier Fallback

Domain: SEO & Structured Data Category: Decision Enforcement: Server Criticality: Medium — missing or poor meta descriptions reduce search result quality but do not break functionality.

Rule Statement: The meta description for a collection page must use collection.seo.description if present; otherwise collection.description; otherwise a generated string of the form "[collection.title] products".

Conditions:

• Condition 1: collection.seo?.description is truthy → use as meta description
• Condition 2: collection.seo?.description is falsy AND collection.description is truthy → use collection.description
• Condition 3: Both are falsy → use "${collection.title} products" as the generated fallback

Validation Details:

• Input: collection.seo?.description, collection.description, collection.title
• Rule logic: collection.seo?.description || collection.description || \${collection.title} products``
• Pass behavior: Most specific available description is used
• Fail behavior: If collection.title is also falsy, the generated fallback produces " products" (empty prefix)

Source Evidence: Search Detail (/search/[collection]) — §8

Business Rationale: Ensures every collection page has a meaningful meta description for search engines, even when merchants have not explicitly configured SEO fields.

Related Rules: BR-010

Testing Implications:

• Positive: Collection with seo.description → verify meta description uses seo.description
• Positive: Collection with no seo.description but with description → verify fallback to description
• Positive: Collection with neither → verify generated "[title] products" string
• Edge case: All three sources are empty → verify meta description output

BR-012: Item Detail SEO Title Uses Two-Tier Fallback

Domain: SEO & Structured Data Category: Decision Enforcement: Server Criticality: Medium — missing SEO titles reduce search result quality but do not break functionality.

Rule Statement: The <title> tag for an item detail page must use page.seo.title if present; otherwise it must fall back to page.title.

Conditions:

• Condition 1: page.seo?.title is truthy → use page.seo.title
• Condition 2: page.seo?.title is falsy → use page.title

Validation Details:

• Input: page.seo?.title and page.title from the Shopify API
• Rule logic: page.seo?.title || page.title — optional chaining with logical OR fallback
• Pass behavior: SEO-specific title used when available; page title used as fallback
• Fail behavior: If both are falsy, the page title will be empty

Source Evidence: Item Detail (/[page]) — §8

Business Rationale: Follows Shopify's standard SEO override pattern, allowing merchants to set search-optimized titles distinct from the page's display title.

Related Rules: BR-013

Testing Implications:

• Positive: Page with seo.title set → verify <title> uses seo.title
• Positive: Page with no seo.title → verify <title> uses page.title
• Edge case: Both are empty → verify <title> tag output

BR-013: Item Detail SEO Description Uses Two-Tier Fallback

Domain: SEO & Structured Data Category: Decision Enforcement: Server Criticality: Medium — missing meta descriptions reduce search result quality but do not break functionality.

Rule Statement: The meta description for an item detail page must use page.seo.description if present; otherwise it must fall back to page.bodySummary.

Conditions:

• Condition 1: page.seo?.description is truthy → use page.seo.description
• Condition 2: page.seo?.description is falsy → use page.bodySummary

Validation Details:

• Input: page.seo?.description and page.bodySummary from the Shopify API
• Rule logic: page.seo?.description || page.bodySummary
• Pass behavior: Most specific available description is used
• Fail behavior: If both are falsy, the meta description will be empty or undefined

Source Evidence: Item Detail (/[page]) — §8

Business Rationale: Follows Shopify's standard SEO override pattern, allowing merchants to set search-optimized descriptions distinct from the page body summary.

Related Rules: BR-012

Testing Implications:

• Positive: Page with seo.description → verify meta description uses seo.description
• Positive: Page with no seo.description but with bodySummary → verify fallback to bodySummary
• Edge case: Both are empty → verify meta description output

BR-014: Item Detail OpenGraph Type Is article

Domain: SEO & Structured Data Category: Structural Enforcement: Server Criticality: Low — incorrect OpenGraph type affects social sharing previews but does not break functionality.

Rule Statement: All item detail pages (/[page]) must set the OpenGraph type metadata to "article".

Conditions: None — this rule applies unconditionally to all item detail pages.

Validation Details:

• Input: Static value — not derived from page content
• Rule logic: openGraph.type = "article" set in generateMetadata
• Pass behavior: Social platforms receive og:type = "article" when the URL is shared
• Fail behavior: Not applicable — this is a static assignment

Source Evidence: Item Detail (/[page]) — §8

Business Rationale: Treats all Shopify Pages (policy pages, about pages, FAQs) as article-type content for social sharing purposes, enabling richer link previews on platforms that support the article OpenGraph type.

Related Rules: BR-015, BR-016

Testing Implications:

• Positive: Any item detail page → verify <meta property="og:type" content="article"> in rendered HTML
• Contrast: Home page → verify og:type is "website", not "article" (BR-016)

BR-015: Item Detail OpenGraph Timestamps Sourced from Shopify

Domain: SEO & Structured Data Category: Structural Enforcement: Server Criticality: Low — incorrect timestamps affect social sharing metadata accuracy but do not break functionality.

Rule Statement: The OpenGraph publishedTime metadata for an item detail page must be sourced from page.createdAt, and modifiedTime must be sourced from page.updatedAt.

Conditions: None — this rule applies unconditionally.

Validation Details:

• Input: page.createdAt and page.updatedAt ISO 8601 timestamps from the Shopify API
• Rule logic: openGraph.publishedTime = page.createdAt, openGraph.modifiedTime = page.updatedAt
• Pass behavior: Social platforms receive accurate publication and modification timestamps
• Fail behavior: If either timestamp is missing or malformed, the OpenGraph tag may contain an invalid date string

Source Evidence: Item Detail (/[page]) — §8

Business Rationale: Provides social platforms and search engines with accurate content freshness signals for Shopify page content.

Related Rules: BR-014, BR-028

Testing Implications:

• Positive: Page with valid createdAt and updatedAt → verify og:published_time and og:modified_time in rendered HTML
• Edge case: updatedAt is malformed → verify OpenGraph tag output

BR-016: Home Page OpenGraph Type Is website

Domain: SEO & Structured Data Category: Structural Enforcement: Server Criticality: Low — incorrect OpenGraph type affects social sharing previews but does not break functionality.

Rule Statement: The home page (/) must set the OpenGraph type metadata to "website".

Conditions: None — this rule applies unconditionally to the home page.

Validation Details:

• Input: Static value — hardcoded in the metadata export
• Rule logic: openGraph.type = "website" set as a static constant in app/page.tsx
• Pass behavior: Social platforms receive og:type = "website" when the home URL is shared
• Fail behavior: Not applicable — this is a static assignment

Source Evidence: Home (/) — §8

Business Rationale: Identifies the home page as a generic website page (as opposed to a product or article), which is the correct OpenGraph type for a storefront homepage.

Related Rules: BR-014

Testing Implications:

• Positive: Home page → verify <meta property="og:type" content="website"> in rendered HTML

3.3: Product Display & Merchandising

Description: Rules governing how products are displayed, how many are shown, how empty states are handled, and how merchandising decisions are encoded in the UI.

Screens involved: Product Detail (/product/[handle]), Home (/), Search Detail (/search/[collection]), Search (/search)

BR-017: Product Gallery Capped at Five Images

Domain: Product Display & Merchandising Category: Structural Enforcement: Server Criticality: Medium — exceeding this limit is not possible given the implementation, but the rule defines the maximum gallery size regardless of how many images Shopify returns.

Rule Statement: The product gallery must display at most 5 images, regardless of the number of images returned by the Shopify API for a given product.

Conditions: None — this cap applies unconditionally to all products.

Validation Details:

• Input: product.images array from the Shopify API (may contain any number of images)
• Rule logic: product.images.slice(0, 5).map(...) — array is sliced to a maximum of 5 elements before being passed to the Gallery component
• Pass behavior: Up to 5 images are passed to Gallery; additional images are silently discarded
• Fail behavior: Not applicable — the slice operation always produces an array of 0–5 elements

Source Evidence: Product Detail (/product/[handle]) — §4, §8

Business Rationale: Not stated in documentation — verify with business stakeholders.

[Not documented — WHO: Product owner or UX designer; WHAT: What is the business rationale for capping the gallery at 5 images? Is this a UX decision, a performance decision, or a design constraint?; WHERE: Insert in the Business Rationale field of BR-017 above]

Related Rules: None

Testing Implications:

• Positive: Product with 3 images → verify Gallery receives 3 images
• Boundary: Product with exactly 5 images → verify Gallery receives all 5
• Boundary: Product with 6 or more images → verify Gallery receives exactly 5 (6th and beyond are discarded)
• Edge case: Product with 0 images → verify Gallery receives an empty array and handles it gracefully

BR-018: Related Products Section Suppressed When Empty

Domain: Product Display & Merchandising Category: Operative Enforcement: Server Criticality: Low — this is a UI cleanliness rule; no data or workflow is affected.

Rule Statement: The Related Products section must not render if getProductRecommendations returns an empty array.

Conditions:

• Condition 1: relatedProducts.length === 0 → RelatedProducts component returns null; section is absent from the DOM
• Condition 2: relatedProducts.length > 0 → section renders with product tiles

Validation Details:

• Input: Array returned by getProductRecommendations(product.id)
• Rule logic: if (!relatedProducts.length) return null
• Pass behavior: One or more recommendations → section renders with <h2>Related Products</h2> and product tiles
• Fail behavior: Zero recommendations → section is entirely absent from the DOM; no empty-state message is shown

Source Evidence: Product Detail (/product/[handle]) — §5, §8, §10

Business Rationale: Prevents a visually empty "Related Products" section from appearing on product pages that have no algorithmic recommendations, keeping the page clean.

Related Rules: None

Testing Implications:

• Positive: Product with recommendations → verify "Related Products" section renders
• Negative: Product with no recommendations → verify "Related Products" section is absent from DOM (not just hidden)
• Edge case: getProductRecommendations returns null instead of an empty array → verify behavior

BR-019: Homepage Features Exactly Three Products in Hero Grid

Domain: Product Display & Merchandising Category: Structural Enforcement: Server Criticality: Medium — if fewer than three products are available, the ThreeItemGrid component's behavior is undefined at the page level; the grid may render incorrectly.

Rule Statement: The homepage hero grid must feature exactly three products, as determined by the ThreeItemGrid component's data source.

Conditions: None — the three-product constraint is structural to the ThreeItemGrid component.

Validation Details:

• Input: Products fetched by ThreeItemGrid from Shopify (collection or featured products)
• Rule logic: The ThreeItemGrid component is designed to render exactly three products; the specific collection or curation mechanism is internal to that component
• Pass behavior: Three products render in the hero grid
• Fail behavior: Behavior when fewer than three products are available is not documented at the page level — handled internally by ThreeItemGrid

Source Evidence: Home (/) — §3, §8

Business Rationale: The three-product hero grid is a merchandising decision encoding a specific visual layout for the homepage above-the-fold section, giving maximum visual prominence to three curated products.

Related Rules: None

Testing Implications:

• Positive: Shopify collection contains ≥3 products → verify three products render in the hero grid
• Edge case: Shopify collection contains fewer than 3 products → verify ThreeItemGrid behavior (not documented at page level)

⚠️ This workflow continues beyond the documented screens. The internal data fetching and rendering logic of ThreeItemGrid (components/grid/three-items) is not covered in this document. Verify the complete behavior with the development team before treating this as a comprehensive description.

BR-020: Empty Collection Renders "No Products" Message

Domain: Product Display & Merchandising Category: Operative Enforcement: Server Criticality: Medium — without this rule, an empty collection would render a blank page with no feedback to the user.

Rule Statement: If a collection exists but contains zero products, the page must render the message "No products found in this collection" instead of a product grid.

Conditions:

• Condition 1: products.length === 0 → render <p>No products found in this collection</p>; do not render the Grid component
• Condition 2: products.length > 0 → render the Grid with ProductGridItems

Validation Details:

• Input: products array returned by getCollectionProducts
• Rule logic: Conditional rendering based on products.length
• Pass behavior: Products exist → grid renders
• Fail behavior: No products → paragraph message renders; grid is absent

Source Evidence: Search Detail (/search/[collection]) — §3, §8, §10

Business Rationale: Provides clear user feedback when a collection has no products, rather than displaying a confusing blank page.

Related Rules: BR-021

Testing Implications:

• Positive: Collection with products → verify grid renders, no "no products" message
• Negative: Collection with zero products → verify "No products found in this collection" message renders
• Negative: Verify grid component is absent from DOM when collection is empty

BR-021: Empty Search Results Render "No Match" Message

Domain: Product Display & Merchandising Category: Operative Enforcement: Server Criticality: Medium — without this rule, a search with no results would render a blank page with no feedback.

Rule Statement: If a search query returns zero products, the page must render the message "There are no products that match " followed by the bolded search term, and must not render the product grid.

Conditions:

• Condition 1: products.length === 0 AND searchValue is truthy → render no-results message with bolded search term
• Condition 2: products.length > 0 → render product grid (and summary paragraph if searchValue is truthy)

Validation Details:

• Input: products array from getProducts; searchValue from searchParams.q
• Rule logic: {products.length === 0 && searchValue && <p>There are no products that match <strong>{searchValue}</strong></p>}
• Pass behavior: Results exist → grid renders
• Fail behavior: No results with a query → no-results message renders; grid is absent

Source Evidence: Search (/search) — §3, §8, §10

Business Rationale: Provides clear user feedback when a search query returns no matching products.

Related Rules: BR-020, BR-023, BR-024

Testing Implications:

• Positive: Search with results → verify grid renders, no "no products" message
• Negative: Search with no results → verify "There are no products that match" message with bolded search term
• Edge case: No search query and no products → verify neither message nor grid renders

BR-022: Search Result Count Uses Singular/Plural Grammar

Domain: Product Display & Merchandising Category: Operative Enforcement: Server Criticality: Low — this is a display quality rule; incorrect grammar does not affect functionality.

Rule Statement: The search results summary must display "result" (singular) when exactly one product is returned, and "results" (plural) when more than one product is returned.

Conditions:

• Condition 1: products.length > 1 → resultsText = "results"
• Condition 2: products.length <= 1 (i.e., 0 or 1) → resultsText = "result"

Validation Details:

• Input: products.length integer
• Rule logic: const resultsText = products.length > 1 ? "results" : "result"
• Pass behavior: Grammatically correct text rendered in the results summary
• Fail behavior: Not applicable — the ternary always produces one of the two strings

Source Evidence: Search (/search) — §4, §8

Business Rationale: Ensures grammatically correct display of result counts (e.g., "Showing 1 result for" vs. "Showing 3 results for").

Related Rules: BR-023

Testing Implications:

• Boundary: Exactly 1 result → verify "result" (singular) is displayed
• Boundary: Exactly 2 results → verify "results" (plural) is displayed
• Edge case: 0 results → verify "result" is used (though the no-results message from BR-021 would display instead)

BR-023: Result Summary Suppressed When No Search Query

Domain: Product Display & Merchandising Category: Operative Enforcement: Server Criticality: Low — this is a UI cleanliness rule; no data or workflow is affected.

Rule Statement: The search results summary paragraph must not render when no search query (searchValue) is present.

Conditions:

• Condition 1: searchValue is truthy → render results summary paragraph
• Condition 2: searchValue is falsy (absent or empty) → do not render results summary paragraph

Validation Details:

• Input: searchValue derived from searchParams.q
• Rule logic: {searchValue && <p>Showing {products.length} {resultsText} for <strong>{searchValue}</strong></p>}
• Pass behavior: Query present → summary renders
• Fail behavior: No query → summary is absent from DOM

Source Evidence: Search (/search) — §3, §8

Business Rationale: When a user browses all products without a search query, displaying "Showing N results for [empty]" would be confusing and unhelpful.

Related Rules: BR-021, BR-022

Testing Implications:

• Positive: Search with ?q=hoodie → verify summary paragraph renders
• Negative: Browse without ?q= parameter → verify summary paragraph is absent from DOM
• Edge case: ?q= with empty string → verify summary paragraph behavior

BR-024: Product Grid Suppressed When No Results

Domain: Product Display & Merchandising Category: Operative Enforcement: Server Criticality: Low — this is a UI cleanliness rule preventing an empty grid container from rendering.

Rule Statement: The product grid (Grid and ProductGridItems components) must not render when products.length === 0.

Conditions:

• Condition 1: products.length > 0 → render Grid with ProductGridItems
• Condition 2: products.length === 0 → do not render Grid or ProductGridItems

Validation Details:

• Input: products array from getProducts
• Rule logic: {products.length > 0 && <Grid ...><ProductGridItems .../></Grid>}
• Pass behavior: Products exist → grid renders
• Fail behavior: No products → grid components are absent from DOM

Source Evidence: Search (/search) — §3, §8

Business Rationale: Prevents an empty grid container from appearing in the DOM, which could cause layout issues or confuse users.

Related Rules: BR-021

Testing Implications:

• Positive: Search returns products → verify Grid component renders
• Negative: Search returns no products → verify Grid component is absent from DOM (not just empty)

3.4: Search & Sort

Description: Rules governing how sort parameters are resolved, validated, and applied to product listings.

Screens involved: Search Detail (/search/[collection]), Search (/search)

BR-025: Sort Parameter Resolves to Valid Sort Configuration

Domain: Search & Sort Category: Decision Enforcement: Server Criticality: High — if an invalid sort key were passed to the Shopify API, the API call could fail or return unexpected results, breaking the product listing.

Rule Statement: The sort URL query parameter must be resolved to a valid sortKey and reverse pair by matching against the sorting constants array; if no match is found, the defaultSort configuration must be used.

Conditions:

• Condition 1: sort param matches a slug in the sorting array → use that entry's sortKey and reverse
• Condition 2: sort param does not match any slug (absent, misspelled, or tampered) → use defaultSort.sortKey and defaultSort.reverse

Validation Details:

• Input: searchParams.sort string (may be any value)
• Rule logic: const { sortKey, reverse } = sorting.find((item) => item.slug === sort) || defaultSort
• Pass behavior: Recognized sort slug → matching sortKey and reverse passed to API
• Fail behavior: Unrecognized or absent sort slug → defaultSort values used; no error shown to user

Source Evidence: Search Detail (/search/[collection]) — §4, §7, §8; Search (/search) — §4, §7, §8

Business Rationale: Ensures that only valid Shopify ProductSortKeys enum values are ever passed to the Shopify Storefront API, preventing API errors from invalid sort parameters.

Related Rules: BR-026

Testing Implications:

• Positive: ?sort=price-asc (valid slug) → verify correct sortKey and reverse are used
• Negative: ?sort=invalid-value → verify defaultSort is applied
• Negative: No ?sort= parameter → verify defaultSort is applied
• Edge case: ?sort= with empty string → verify defaultSort is applied
• Edge case: ?sort=PRICE (using the raw Shopify enum value instead of the slug) → verify defaultSort is applied (slug matching is case-sensitive)

BR-026: Unrecognized Sort Parameter Falls Back to Default

Domain: Search & Sort Category: Operative Enforcement: Server Criticality: Medium — without this rule, an unrecognized sort parameter could cause an API error or expose an invalid sort key to Shopify.

Rule Statement: When the sort URL parameter is absent or does not match any recognized sort slug, the application must silently apply the defaultSort configuration without displaying an error message to the user.

Conditions:

• Condition 1: sort is absent or unrecognized → apply defaultSort; no error shown
• Action/Result: Page renders with default sort order; user receives no indication that their sort parameter was ignored

Validation Details:

• Input: searchParams.sort — any string or undefined
• Rule logic: || defaultSort short-circuit in the sort resolution expression
• Pass behavior: Default sort applied silently
• Fail behavior: Not applicable — the fallback always succeeds

Source Evidence: Search Detail (/search/[collection]) — §7, §8; Search (/search) — §7, §8

Business Rationale: Provides a graceful degradation path for invalid or missing sort parameters, ensuring the page always renders with a valid sort configuration rather than showing an error.

Related Rules: BR-025

Testing Implications:

• Positive: Valid sort slug → verify correct sort applied
• Negative: Invalid sort slug → verify default sort applied, no error message shown to user
• Edge case: URL manually crafted with ?sort=<script> → verify default sort applied (no XSS risk from this path since value is only used for array lookup)

3.5: Navigation & Routing

Description: Rules governing how navigation links are constructed and how prefetching is applied.

Screens involved: Product Detail (/product/[handle])

BR-027: Related Product Tiles Link to Product Detail with Prefetch

Domain: Navigation & Routing Category: Operative Enforcement: Client Criticality: Low — prefetch is a performance optimization; its absence would not break navigation, only slow it.

Rule Statement: Each related product tile must render as a Next.js <Link> pointing to /product/[product.handle] with prefetch={true} enabled.

Conditions: None — this rule applies to all related product tiles unconditionally.

Validation Details:

• Input: product.handle string for each recommended product
• Rule logic: <Link href={/product/${product.handle}} prefetch={true}> wrapping each GridTileImage
• Pass behavior: Tile renders as a navigable link; Next.js prefetches the linked page's data when the tile enters the viewport
• Fail behavior: Not applicable — this is a static rendering rule

Source Evidence: Product Detail (/product/[handle]) — §6, §9

Business Rationale: Enables near-instant navigation to related product pages by prefetching their data when the tiles become visible, improving perceived performance.

Related Rules: None

Testing Implications:

• Positive: Related product tile renders → verify href is /product/[handle] for each tile
• Positive: Verify prefetch attribute is present on each link
• Edge case: Related product with a handle containing special characters → verify URL is correctly formed

3.6: Content Rendering

Description: Rules governing how content is formatted and rendered on the Item Detail screen.

Screens involved: Item Detail (/[page])

BR-028: Item Detail Date Formatted Using Server Locale

Domain: Content Rendering Category: Operative Enforcement: Server Criticality: Low — locale-dependent date formatting is a display quality concern; it does not affect data integrity or functionality.

Rule Statement: The updatedAt timestamp on an item detail page must be formatted as a human-readable date string using Intl.DateTimeFormat with year: "numeric", month: "long", and day: "numeric" options, using the server's default locale.

Conditions: None — this rule applies unconditionally to all item detail pages.

Validation Details:

• Input: page.updatedAt ISO 8601 timestamp string from the Shopify API
• Rule logic: new Intl.DateTimeFormat(undefined, { year: "numeric", month: "long", day: "numeric" }).format(new Date(page.updatedAt))
• Pass behavior: Valid timestamp → human-readable date string rendered (e.g., "January 15, 2024")
• Fail behavior: Malformed updatedAt → new Date(malformed) produces Invalid Date; Intl.DateTimeFormat.format() outputs the string "Invalid Date" visibly on the page

Source Evidence: Item Detail (/[page]) — §3, §8

Business Rationale: Provides users with a human-readable "last updated" date for content pages such as privacy policies and FAQs, helping users assess content freshness.

Related Rules: BR-015

Testing Implications:

• Positive: Valid ISO 8601 updatedAt → verify formatted date renders correctly (e.g., "January 15, 2024")
• Edge case: Malformed updatedAt string → verify "Invalid Date" does not appear on the page (see GAP-07)
• Edge case: Server running in a non-English locale → verify date format matches server locale

BR-029: Item Detail Page Body Rendered as Raw HTML

Domain: Content Rendering Category: Structural Enforcement: Server Criticality: Medium — raw HTML rendering from an external source carries XSS risk if the content pipeline is compromised; however, Shopify sanitizes page body content server-side.

Rule Statement: The body content of an item detail page must be rendered as raw HTML via the Prose component's html prop, using the HTML string returned by the Shopify Storefront API in page.body.

Conditions: None — this rule applies unconditionally.

Validation Details:

• Input: page.body — an HTML string from the Shopify Storefront API
• Rule logic: <Prose html={page.body} /> — the Prose component receives the raw HTML string and renders it (implementation details of Prose are outside the scope of this document)
• Pass behavior: Rich text content renders with typographic styling applied by Prose
• Fail behavior: If page.body is an empty string, Prose renders with no content; title and date still display

Source Evidence: Item Detail (/[page]) — §3, §14

Business Rationale: Shopify Pages are authored in a rich text editor that produces HTML output. Rendering the HTML directly preserves the merchant's formatting (headings, lists, links, bold/italic text) without requiring a custom content renderer.

Related Rules: None

Testing Implications:

• Positive: Page with rich HTML body → verify formatted content renders (headings, lists, links)
• Edge case: page.body is an empty string → verify page renders without error (title and date still visible)
• Security: Page body containing <script> tags → verify scripts are not executed (depends on Prose implementation)

4. Decision Tables

DT-01: Product SEO Indexability

Related Rules: BR-001, BR-009 Hit Policy: Unique

DT-02: Search Results Display State

Related Rules: BR-021, BR-023, BR-024 Hit Policy: Unique

DT-03: SEO Metadata Title Resolution — Collection

Related Rules: BR-010 Hit Policy: First

DT-04: SEO Metadata Description Resolution — Collection

Related Rules: BR-011 Hit Policy: First

DT-05: SEO Metadata Resolution — Item Detail Page

Related Rules: BR-012, BR-013 Hit Policy: First

DT-06: JSON-LD Availability Mapping

Related Rules: BR-006 Hit Policy: Unique

5. Validation Rules Summary

6. Calculation Rules Summary

7. Rule Dependency Map

8. Gap Analysis

GAP-01: No Server-Side Enforcement of Image Cap

Type: Implicit Rule Affected Domain: Product Display & Merchandising Risk Level: Low Description: The 5-image cap (BR-017) is enforced by product.images.slice(0, 5) in the page component before passing the array to Gallery. However, the Shopify API query for product images may request more than 5 images (the documentation notes "images (up to 5+)"), meaning the API call fetches data that is then discarded. There is no documented enforcement of this cap at the API query level (e.g., requesting only 5 images from Shopify). This is an efficiency concern rather than a correctness concern. Recommendation: Verify whether the Shopify GraphQL query for product.images limits the result to 5 nodes at the query level (e.g., images(first: 5)). If not, consider adding this limit to the query to avoid fetching and discarding unnecessary data. Related Rules: BR-017

GAP-02: JSON-LD Script Injection Without HTML-Safe Serialization

Type: Implicit Rule Affected Domain: SEO & Structured Data Risk Level: Medium Description: The product JSON-LD block is injected via dangerouslySetInnerHTML={{ __html: JSON.stringify(productJsonLd) }}. The documentation explicitly notes that JSON.stringify does not escape HTML special characters (<, >, &), which could allow a product title or description containing </script> sequences to break out of the <script> tag. The data source is the Shopify API (not user input), which reduces the risk, but it is not zero — a compromised or misconfigured Shopify store could return malicious content. Recommendation: Add a rule requiring that the JSON-LD serialization use an HTML-safe JSON serializer that escapes <, >, and & characters (e.g., replacing < with \u003c). This should be enforced as a code-level standard for all dangerouslySetInnerHTML JSON-LD injections. Related Rules: BR-006, BR-007, BR-008

GAP-03: Missing Null Guard on featuredImage in JSON-LD Body

Type: Edge Case Affected Domain: SEO & Structured Data Risk Level: High Description: The documentation explicitly identifies that productJsonLd accesses product.featuredImage.url without a null guard in the page body. If featuredImage is null or undefined, this will throw a runtime error, causing the page to fail to render. The generateMetadata function does guard this with product.featuredImage || {}, but the page body does not apply the same guard. This is an inconsistency between the metadata and page rendering paths. Recommendation: Add a null guard for product.featuredImage in the productJsonLd construction: product.featuredImage?.url. Define a business rule that the JSON-LD image field must be omitted (not set to undefined) when featuredImage is absent. Related Rules: BR-006, BR-007

GAP-04: searchParams Type Cast Bypasses Array-Value Safety

Type: Edge Case Affected Domain: Search & Sort Risk Level: Low Description: On both the Search (/search) and Search Detail (/search/[collection]) screens, searchParams is cast with as { [key: string]: string }. In Next.js App Router, searchParams values can be string | string[] when the same query parameter appears multiple times in the URL (e.g., ?sort=price-asc&sort=trending). The type cast bypasses TypeScript's type safety for this case. If sort or q were passed as arrays, the behavior would be undefined — the array object would be passed to getProducts or the sort lookup, producing unexpected results. The sort fallback (BR-026) would handle the sort case gracefully, but the q parameter passed as an array to getProducts could produce unexpected API behavior. Recommendation: Add runtime validation of searchParams values to ensure they are strings before use, rather than relying on a type cast. Define a rule that multi-value query parameters for q and sort must be handled by taking the first value or rejecting the request. Related Rules: BR-025, BR-026

GAP-05: getPage Called Twice Per Request Without Visible Deduplication

Type: Implicit Rule Affected Domain: Content Rendering Risk Level: Low Description: On the Item Detail screen, getPage is called independently in both generateMetadata and the Page component, resulting in two separate Shopify API calls per page request. The documentation notes that Next.js's fetch deduplication may apply if getPage uses the native fetch API internally, but this is not confirmed. If deduplication is not active, this doubles the API call volume for every item detail page render, which could contribute to Shopify API rate limit consumption. Recommendation: Verify whether getPage in lib/shopify uses the native fetch API with Next.js's automatic request deduplication. If not, consider refactoring to use React's cache() function to deduplicate the call within a single render pass. Define a rule that each Shopify API function must be called at most once per page render. Related Rules: BR-004, BR-012

[Not documented — WHO: Development team; WHAT: Does getPage in lib/shopify use the native fetch API, and is Next.js request deduplication active for this call?; WHERE: Insert in the Description field of GAP-05 above]

GAP-06: No Empty-State UI for Home Page Components

Type: Missing Rule Affected Domain: Product Display & Merchandising Risk Level: Medium Description: The Home screen documentation states that if ThreeItemGrid fetches zero products (e.g., an empty Shopify collection), the grid component is responsible for rendering an appropriate empty state — but no empty-state behavior is documented for ThreeItemGrid or Carousel at the page level. There is no documented rule for what the homepage should display if the featured collection is empty or if the Shopify API returns no products. This is a gap compared to the Search and Search Detail screens, which have explicit empty-state rules (BR-020, BR-021). Recommendation: Document the expected empty-state behavior for ThreeItemGrid and Carousel. Define a rule specifying what the homepage renders when the featured collection contains fewer than three products. Related Rules: BR-019

GAP-07: Malformed updatedAt Produces Visible "Invalid Date" String

Type: Edge Case Affected Domain: Content Rendering Risk Level: Medium Description: The Item Detail screen formats page.updatedAt using new Intl.DateTimeFormat(...).format(new Date(page.updatedAt)). The documentation explicitly identifies that if page.updatedAt is malformed, new Date(malformed) produces an Invalid Date object, and Intl.DateTimeFormat.format() outputs the string "Invalid Date" visibly on the page. There is no guard or fallback for this case. Recommendation: Add a rule requiring that the updatedAt date be validated before formatting. If the date is invalid, the "last updated" paragraph should either be omitted or display a fallback string. Implement a guard such as const date = new Date(page.updatedAt); if (!isNaN(date.getTime())) { /* render date */ }. Related Rules: BR-028

GAP-08: Missing page.title Has No Fallback

Type: Edge Case Affected Domain: Content Rendering Risk Level: Low Description: The Item Detail screen renders page.title directly in an <h1> element with no fallback. The documentation explicitly notes: "If page.title is missing, <h1> renders empty; no fallback is implemented." An empty <h1> is both a UX problem (blank heading) and an accessibility concern (screen readers announce an empty heading). This contrasts with the SEO metadata, which has a two-tier fallback (BR-012). Recommendation: Define a rule that the <h1> heading must not render empty. Add a fallback (e.g., a placeholder string, or suppress the <h1> if page.title is falsy). Related Rules: BR-012, BR-004

GAP-09: HIDDEN_PRODUCT_TAG Constant Value Not Documented

Type: Missing Rule Affected Domain: Content Visibility & Access Control Risk Level: Medium Description: The HIDDEN_PRODUCT_TAG constant is referenced in BR-001 and BR-009 as the mechanism for suppressing SEO indexing of draft or internal products. However, the actual string value of this constant is defined in lib/constants and is not documented in the screen documentation. Without knowing the exact tag value, merchants cannot correctly apply the tag in Shopify's admin, and QA engineers cannot test the behavior. Recommendation: Document the exact string value of HIDDEN_PRODUCT_TAG from lib/constants. Add this value to the Glossary and to the rule entries for BR-001 and BR-009.

[Not documented — WHO: Development team; WHAT: What is the exact string value of the HIDDEN_PRODUCT_TAG constant in lib/constants?; WHERE: Insert in the Glossary entry for HIDDEN_PRODUCT_TAG and in the Validation Details of BR-001 and BR-009]

Related Rules: BR-001, BR-009

GAP-10: No Rate Limiting Documented for Any Public API Call

Type: Missing Rule Affected Domain: Content Visibility & Access Control Risk Level: Medium Description: None of the five assessed screens document any rate limiting, request throttling, or abuse prevention for the Shopify Storefront API calls they make. All five screens are publicly accessible without authentication, meaning any visitor can trigger server-side Shopify API calls by requesting these pages. High-volume requests (e.g., from scrapers or denial-of-service attempts) could exhaust Shopify API rate limits or increase infrastructure costs. The documentation notes that rate limiting, if any, would be enforced by the Shopify Storefront API itself or at the Vercel platform level — but no such configuration is documented. Recommendation: Document whether rate limiting is configured at the Vercel edge, Next.js middleware, or Shopify API level. If no rate limiting is in place, define a rule specifying acceptable request rates and implement appropriate controls.

[Not documented — WHO: Infrastructure/DevOps team; WHAT: Is rate limiting configured at the Vercel edge, Next.js middleware, or any other layer for requests to the assessed screens?; WHERE: Insert in the Description field of GAP-10 above and create a new rule entry if rate limiting is confirmed]

Related Rules: BR-005

9. Glossary

9.1: Business Concepts

9.2: Rule Terminology

9.3: Domain Terms

End of Business Rules Assessment — Commerce Application — May 2026