Architecture and design system

Kingsbell is an Online Store 2.0 theme built around Shopify-native Liquid, JSON templates, sections, theme blocks, assets, settings, routes, forms, and customer objects. The architecture avoids a separate frontend framework and keeps merchant customization inside Shopify's theme model.

Runtime directories

Kingsbell uses the standard Shopify theme structure:

assets/      CSS, JavaScript, and packaged storefront assets
blocks/      Reusable theme blocks
config/      Global settings schema and saved theme configuration
layout/      Storefront document layouts
locales/     Storefront and theme-editor translations
sections/    Merchant-configurable sections and section groups
snippets/    Reusable Liquid rendering units
templates/   JSON and Liquid entry templates

Repository-only material such as .design, QA documents, scripts, and companion contracts is excluded from the Shopify runtime.

Architectural layers

The theme can be understood as five layers:

1. Foundation — global tokens, fonts, base styles, layout, metadata, icons, and accessible primitives.
2. Commerce engine — products, variants, forms, cart, filters, search, recommendations, and pricing.
3. Template system — standard templates plus alternate editorial, archive, commission, and private compositions.
4. Content system — blogs, articles, galleries, quotations, interviews, research notes, reusable cards, and flexible blocks.
5. Companion boundary — theme-facing member presentation plus a separate specification for secure entitlement enforcement.

Keep these layers separate. A visual section should not duplicate cart logic, and a Liquid member gate should not be treated as backend authorization.

Canonical visual direction

Kingsbell's default system is based on:

• Obsidian and Alabaster base tones;
• restrained champagne accents;
• Playfair Display for editorial headings;
• Inter for interface and body copy;
• sharp geometry and low-contrast outlines;
• large negative space;
• structured 12-column desktop layouts;
• product photography as the primary visual driver;
• tonal depth instead of heavy shadows.

Merchants can change the global palette, fonts, spacing, radius, buttons, forms, motion, and product-card presentation without replacing the underlying component architecture.

Colour roles

The default colour palette is:

Theme settings map these palette values into semantic roles such as page background, surface, text, muted text, border, accent, button, button text, and error.

Use semantic roles in components. Do not hard-code palette values into new sections unless the value is intentionally local and merchant-configurable.

Typography

The default heading font is Shopify-hosted Playfair Display. The default body font is Shopify-hosted Inter.

Global controls include:

• heading and body font families;
• heading and body scales;
• body line height;
• heading letter spacing;
• label letter spacing;
• uppercase button labels.

Preserve semantic heading order independently of visual size. A section's styling must not require every large title to be an h1.

Layout tokens

Global layout controls include:

• maximum page width;
• maximum reading width;
• desktop and mobile side margins;
• grid gutter;
• default section spacing;
• internal spacing scale;
• corner style.

The default maximum page width is 1440px, reading width is 780px, grid gutter is 32px, and section spacing is 120px.

Use the shared page-width, grid, spacing, and content-width tokens instead of defining unrelated container widths in each section.

Theme blocks

Reusable blocks in /blocks include:

• heading;
• text;
• button;
• image;
• statistic;
• resource card;
• spacer;
• group.

The Flexible content section can render these theme blocks and app blocks. Groups support one nested level of composition. Avoid deeper block trees because they become difficult to understand and maintain in the theme editor.

Snippets and reusable commerce units

Kingsbell uses snippets for repeated behavior such as:

• responsive images;
• icons;
• metadata;
• pricing states;
• product cards;
• option selection;
• product forms;
• access evaluation;
• generated CSS tokens.

When extending a reusable behavior, update the shared snippet rather than copying it into multiple sections. Preserve the existing parameter contract or update all call sites together.

Progressive enhancement

Core content and commerce should remain understandable before JavaScript enhances it.

Examples:

• tabbed content is readable as sequential panels without JavaScript;
• reading progress is optional enhancement;
• copy-link behavior includes a fallback;
• Ajax filters and cart actions should not erase Shopify's underlying routes and forms;
• reveal effects are disabled or reduced for visitors who request reduced motion.

Accessibility baseline

The foundation includes:

• a skip link;
• focus-visible treatment;
• a focusable main content target;
• semantic form controls;
• reduced-motion behavior;
• responsive image alt handling;
• keyboard-aware tabs and navigation;
• no positive tabindex or autofocus in validated theme code.

Every new component must preserve keyboard access, visible focus, sensible source order, and readable states at browser zoom.

Theme-editor lifecycle

Shopify can reload sections independently inside the theme editor. Component JavaScript must support:

• initial page load;
• section load and unload;
• block selection where relevant;
• repeated initialization without duplicate listeners;
• DOM replacement after Ajax rendering.

Do not assume a component is initialized only once per page.

Design-reference boundary

The .design directory contains prototypes and screenshots used to derive production sections and templates. It is reference material only.

Do not:

• link storefront assets from .design;
• import prototype JavaScript into the theme;
• depend on prototype route structures;
• treat screenshots as implementation specifications when they conflict with Shopify behavior, accessibility, or merchant configurability.

The production theme is the source of truth for runtime behavior.