S&T
Merchant Storefront
Theme Developer Hub • Extensibility Handbookv1.0.0 • Initial Release

Tangent Developer Hub & Extensibility Guide

The comprehensive developer reference and extensibility guide for Tangent. Learn how to create custom JSON templates, build modular Liquid sections and blocks, connect to window-level event bus contracts, and extend styling tokens while maintaining sub-second performance and strict Shopify quality standards.

53Modular Sections
6Extensibility Tracks
OS 2.0Native
Sub-SecondSpeed Target
System Foundations

4 Architectural Tracks

The engineering pillars underpinning every commercial preset, section, and interactive component in the platform.

[1]Track 01

[1] Liquid Runtime Engine

High-Performance Server-Side Rendering

Ultra-lean Liquid template engine executing under strict shopify theme check constraints. Zero redundant passes, atomic snippet composition, and optimized asset preload declarations delivering sub-100ms server TTFB.

Core Architecture Pillar

Atomic snippet hierarchy, native image filters, and sub-100ms server response TTFB

  • Atomic snippet hierarchy in snippets/*.liquid
  • Native image filters (image_url: width, format: webp)
  • Deterministic schema defaults without null fallbacks
[2]Track 02

[2] Autonomous Web Components

Zero-Framework Native Custom Elements

Client-side functionality is encapsulated strictly in native HTML5 Custom Elements. No monolithic React or Vue runtimes. Each element independently manages its lifecycle, keyboard focus, and DOM tree.

Core Architecture Pillar

Autonomous HTML5 custom elements without monolithic third-party framework bundles

  • <cart-drawer> with progressive drawer physics
  • <sticky-header> with zero-CLS scroll direction observers
  • <video-media> with IntersectionObserver lazy playback
[3]Track 03

[3] 53 Modular Liquid Sections

Online Store 2.0 Architectural Suite

A comprehensive encyclopedia of 53 production-tested, theme-editor customizable sections spanning 9 structural categories. Fully reorderable, supporting dynamic blocks and app embeds.

Core Architecture Pillar

53 production-tested sections 100% validated against Shopify Online Store 2.0 specifications

  • Category-mapped directory taxonomy
  • Preset-ready settings configurations
  • Native dynamic section rendering via /?section_id=
[4]Track 04

[4] Decoupled Event Bus

Asynchronous Window-Level Pub/Sub Contract

Components communicate without tight coupling through standardized CustomEvents dispatched on the global window. Modules can be added, updated, or swapped without breaking dependencies.

Core Architecture Pillar

Decoupled CustomEvent pub/sub contracts on window enabling modular component swapping

  • tangent:cart:updated for real-time totals
  • tangent:variant:changed for media & price synchronization
  • tangent:modal:opened with automatic focus trapping
Developer Extensibility Handbook

The Six Extensibility Tracks

Practical development blueprints for extending Tangent. Add new pages, custom sections, dynamic blocks, atomic snippets, custom JavaScript, and CSS tokens safely without modifying core runtime files.

Track 01

Track 1: Creating New Pages

Online Store 2.0 Modular JSON Templates

JSON templates decouple layout structure from Shopify content. You can create custom landing pages, brand stories, or campaign hubs by declaring modular sections and their display order.

3-Step How-To Recipe
1Step 01

Create a JSON template file under templates/ or add a page in Shopify Admin.

2Step 02

Define the section order in the template JSON.

3Step 03

Assign the template to your target products or pages.

Track 02

Track 2: Adding & Managing Sections

Liquid Sections, Padding Tokens & Theme Editor Presets

Custom sections provide merchant-editable building blocks with customizable spacing and presets for instant discovery.

3-Step How-To Recipe
1Step 01

Open the Shopify Theme Customizer.

2Step 02

Click "+ Add section" on any page.

3Step 03

Reorder sections and configure settings.

Track 03

Track 3: Adding Child Blocks

Dynamic Sub-Components & Content For Blocks

Blocks allow merchants to add, reorder, and configure dynamic child items within a parent section without code changes.

3-Step How-To Recipe
1Step 01

Select any section in the Theme Editor.

2Step 02

Click "+ Add block" to insert child elements (slides, metrics, columns).

3Step 03

Drag blocks to reorder.

Track 04

Track 4: Using Reusable Snippets

Isolated Variable Scope & Accessible Design Elements

Reusable snippets promote DRY architecture across sections while keeping presentation logic modular.

3-Step How-To Recipe
1Step 01

Place atomic Liquid snippets under snippets/.

2Step 02

Pass parameters cleanly to reuse cards, icons, or badges.

3Step 03

Keep presentation logic modular.

Track 05

Track 5: Storefront Behaviors & Apps

Native Custom Elements & Decoupled Event Bus

Extend storefront interactions without bloated client frameworks using native browser events and Shopify app blocks.

3-Step How-To Recipe
1Step 01

Sections communicate seamlessly across the cart drawer, predictive search, and variant selectors.

2Step 02

Integrates with official Shopify App Blocks without custom scripts.

3Step 03

Fast, zero-bloat native browser interactions.

Track 06

Track 6: Brand Styling & Colors

Theme Design Tokens & Color Harmonization

Customize typography, palettes, and layout rhythm safely by referencing theme design tokens and presets.

3-Step How-To Recipe
1Step 01

Open Theme Settings in the Customizer.

2Step 02

Choose from 5 luxury presets or adjust brand colors.

3Step 03

Spacing and typography automatically harmonize.

Quality Assurance & Production Readiness

Shopify Theme Development Best Practices & Standards

Strict engineering standards adhered to across Tangent. Use this checklist when authoring custom sections or extending store layouts.

Linter Standard

Shopify Theme Check Compliance

Strict Shopify Theme Check AST validation. Zero deprecated Liquid tags (legacy include tags are prohibited in favor of modern render tags), clean schema keys, and zero unclosed tags.

  • shopify theme check --fail-level error before every git commit
  • Parameter isolation on all Liquid snippets with zero global leakage
  • Type-safe JSON schema declarations with required defaults
Sub-Second Speed

High-Performance Image Pipeline

Optimal image delivery utilizing native image_tag filters with responsive srcset widths, explicit aspect ratios, and loading: "lazy" to guarantee zero Cumulative Layout Shift (CLS).

  • Always specify explicit aspect ratio or width/height attributes
  • Use image_tag with responsive widths: 375, 750, 1100, 1500
  • Reserve fetchpriority: "high" exclusively for the initial above-the-fold LCP image
Accessibility

WCAG 2.2 AA Accessibility Contracts

Complete keyboard operability, visible focus rings, minimum 44x44px touch targets, ARIA dialog modal semantics, and screen-reader announcements on dynamic mutations.

  • Interactive elements reachable and operable via Tab, Enter, and Space keys
  • Visible focus rings (focus-visible:ring-2 focus-visible:ring-accent-brand)
  • Live regions (aria-live="polite") on cart drawer and predictive search results
< 25 KB Budget

Performance Envelope & Zero Runtime Bloat

Strict runtime payload envelope (< 25 KB gzipped total JS). Zero monolithic third-party libraries (no jQuery, no Lodash, no React/Vue on the merchant storefront).

  • Autonomous HTML5 Custom Elements with zero runtime framework dependencies
  • Native browser APIs: IntersectionObserver, ResizeObserver, CustomEvent
  • Lazy asset loading for below-the-fold media and secondary modals
API & Environment Reference

System Specifications & Parameter Tables

Runtime Requirements & Performance Envelopes

Global platform constraints, bundle targets, and compiler requirements validated on each build.

Parameter / KeyDescription & Constraints
shopify.theme.specificationRequired
Type: string
Official Shopify OS 2.0 architecture standard with modular JSON templates.
ℹ Enforces templates/*.json dynamic section support.
Default:Online Store 2.0
shopify.theme_check.versionRequired
Type: semver
Strict Liquid linter ensuring zero deprecated Liquid tags and optimal AST parsing.
Default:>= 2.15.0
client.runtime_budget.max_jsRequired
Type: bytes
Zero third-party runtime bundles. Exclusively native Custom Elements.
Default:< 25 KB gzipped
rendering.server_ttfb_targetRequired
Type: duration
Target Shopify edge server response time on cache hit.
Default:< 100 ms
browser_support.targets
Type: browserslist
Modern evergreen browser support matrix with native dialog and shadow DOM.
Default:Chrome >= 100, Safari >= 15.4, Firefox >= 100, Edge >= 100

Autonomous Web Components Specification

Native Custom Elements registered in the theme without third-party framework dependencies.

Parameter / KeyDescription & Constraints
cart-drawerRequired
Type: CustomElement
Autonomous slide-over slideout drawer with optimistic cart mutation and tiered shipping bar.
ℹ Dispatches and listens to tangent:cart:updated.
Default:assets/cart-drawer.js
video-mediaRequired
Type: CustomElement
Deferred lazy-load wrapper for native HTML5, Vimeo, and YouTube background players.
ℹ Employs IntersectionObserver to delay video fetch until within 200px of viewport.
Default:assets/video-media.js
predictive-searchRequired
Type: CustomElement
Instant search dialog querying Shopify Predictive Search API with 300ms debounce.
ℹ Accessible keyboard focus trapping and ARIA combobox semantics.
Default:assets/predictive-search.js
sticky-headerRequired
Type: CustomElement
High-performance scroll direction observer pinning navigation on scroll up with zero CLS.
Default:assets/sticky-header.js
compare-slider
Type: CustomElement
Interactive before/after image split-screen comparison slider with touch gesture support.
Default:assets/compare-slider.js

Window Event Bus Contracts (tangent:*)

Decoupled pub/sub messaging signatures dispatched across theme sections and custom blocks.

Parameter / KeyDescription & Constraints
tangent:cart:updatedRequired
Type: CustomEvent<{ cart: object; openDrawer: boolean }>
Dispatched whenever line items are added, updated, or removed from cart state.
ℹ Bubbles: true, Composed: true on window.
tangent:variant:changedRequired
Type: CustomEvent<{ variantId: number; available: boolean; price: number }>
Dispatched when product options or swatch selections change variant identity.
tangent:modal:opened
Type: CustomEvent<{ modalId: string; triggerElement: HTMLElement }>
Notifies theme layers to manage background scrolling lock and inert flags.
tangent:search:results
Type: CustomEvent<{ query: string; totalResults: number }>
Broadcasts predictive search completion for analytics or custom UI binding.
Filesystem Architecture

Theme Structure Overview

Standard Shopify Online Store 2.0 directory blueprint organized into 5 primary architectural modules.

templates/

Online Store 2.0 JSON Templates

Declares page layout hierarchy and section sequence for index, products, collections, cart, and custom landing pages.

Modular Page Layouts
sections/

53 Modular Liquid Sections

Reorderable, merchant-configurable visual building blocks with rich settings schemas and dynamic blocks.

Customizer Components
snippets/

Reusable Liquid Snippets

Atomic UI components, badges, and accessible SVG icons cleanly parameterized without outer scope leakage.

Design System Primitives
assets/

Storefront Runtime Assets

High-performance CSS design tokens, typography styles, and native HTML5 Custom Elements under a 25 KB budget.

Native Client Runtime
config/

Theme Settings & Presets

Central settings schema defining global typography, color system, and 5 luxury commercial brand presets.

Preset & Customizer Schema