Foundation: Branding, Colors, Typography, Modes

This chapter walks through Hyprism’s foundation layer — the theme-wide settings that determine how every page looks. Set these up first; section-level styling builds on top of them.

All foundation settings live behind the gear icon at the bottom-left of the theme editor.

2.1 Branding (logo + favicon)

Theme settings → Branding.

This tab only configures the visual brand assets — your logo, the optional dark-mode logo swap, and the browser-tab favicon. Brand-identity text (organization description, social profile URLs) lives in separate tabs that are cross-linked at the end of this section.

Logo

Setting	What it does
🔧 Logo	Upload your primary logo. SVG recommended for crisp rendering at any size. PNG with transparency also works. The logo’s display size is controlled per-instance — header logo width is set in the Header tab (§4.2), footer logo width in the footer logo block.
🔧 Alternate logo	Optional second logo, used in two scenarios — see the two toggles below.
🔧 Show alternate logo (static mode)	✅ Default off. Visible only when the dark/light toggle is disabled. Turn on to render the alternate logo as the page logo permanently. Useful when your site runs a permanent dark theme but the primary logo asset is dark-on-light.
🔧 Use primary logo in both modes	✅ Default off. Visible only when the dark/light toggle is enabled. When off, the storefront swaps to the alternate logo whenever dark mode is active. When on, the primary logo stays in both modes (use this if your primary asset has built-in transparency that reads well on light and dark).

💡 Most brands have a single logo with built-in transparency that reads well on both backgrounds. Only upload an alternate if your primary logo is dark-on-light (and would disappear on a dark background) or vice versa.

The logo appears in:

• The header (every page) — see chapter 4
• The footer (optional) — see chapter 5
• Email notifications and gift-card templates (Shopify-side, configured separately)

Favicon

Setting	What it does
🔧 Favicon image	Upload a 32×32 px PNG (or SVG). Used by browsers in the page tab, bookmarks, and history. Shopify auto-derives the various size variants required by mobile-OS shortcuts.

Related brand identity (not in this tab)

• Organization description + Home meta description → see chapter 13 — SEO and GEO. These power the Organization-schema description and the homepage <meta name="description">.
• Social profile URLs (Facebook, Instagram, X, YouTube, TikTok, LinkedIn, Pinterest, and more) → see Theme settings → Social media tab and chapter 13 — SEO and GEO. These populate the Organization schema’s sameAs array used by AI search engines and Google.

2.2 Color schemes (5 schemes × 34 color roles)

Theme settings → Color schemes.

This is the most powerful part of Hyprism’s design system. Every section, block, and component reads its colors from a color scheme — and Hyprism ships with 5 customizable schemes that you can assign per section.

How color schemes work

Each color scheme defines 34 color roles, grouped as follows. Setting IDs in monospace are the keys you’ll see if you edit config/settings_data.json directly; the labels in bold are what you see in the customizer (English / German).

Surfaces (2 roles)

• background — Background / Hintergrund: the section / page background
• card_bg — Card background / Karten-Hintergrund: product-card surface, surface modifiers; falls back to background if blank (the previous +5% lighten was removed)

Text (4 roles)

• text — Text body color
• heading — Heading color (H1–H6 default to this)
• text_muted — Muted text (captions, meta, secondary labels)
• link — Link color for <a> tags outside buttons; falls back to accent if blank

Accent (2 roles)

• accent — primary brand accent (glow, hover states, highlights). Also drives the auto-derived --ne-scheme-accent-glow (alpha 0.3) for section glow.
• accent_hover — hover state for accent-colored links and emphasis

Primary button (6 roles)

• button — primary button background
• button_label — primary button text
• button_border — primary button border (visible when Button border width > 0)
• button_bg_hover / button_text_hover / button_border_hover — hover states

Secondary button (6 roles)

• secondary_button_bg — secondary button background (default transparent)
• secondary_button_text — secondary button text
• secondary_button_border — secondary button border
• secondary_button_bg_hover / secondary_button_text_hover / secondary_button_border_hover — hover states

Input fields (4 roles)

• input_bg / input_text / input_border — default field treatment
• input_bg_focus — background on focus

Variant pickers (5 roles)

• variant_bg / variant_text / variant_border — unselected pill treatment
• variant_bg_selected / variant_text_selected — selected pill treatment

Pricing & badges (2 roles)

• sale_price — Sale-Preis color. Tints sale-price text on PDP + cart, plus the wishlist heart fill (--ne-color-sale alias). For Sale + New badge backgrounds see badge_bg below.
• badge_bg — Badge background. Drives .ne-badge--sale and .ne-badge--new on product cards. Defaults to accent if blank.

Decoration (3 roles)

• border — generic border color (cards, dividers, untinted surfaces)
• shadow — color mixed into theme-wide shadow tokens (--ne-shadow-sm/md/lg/xl, section + block shadow composites). Default #000 keeps existing visuals; pick a different color to tint every shadow that flows through these tokens.
• frame — decorative frame color. Read by the layered frame system (see §2.6). The role’s auto-derived --ne-scheme-frame var is alpha-modified by the Frame opacity slider in the Frame settings tab, and falls back to accent if the color field is left blank.

Auto-derived (read-only) — Hyprism also emits these for internal use; you cannot override them per scheme, they’re computed from the roles above:

• --ne-scheme-bg-elevated — background lightened by 5%
• --ne-scheme-bg-surface — background lightened by 8%
• --ne-scheme-bg-overlay — background with alpha 0.85 (reserved for modal scrims; currently unused in v0.8 — kept as forward-compat hook)
• --ne-scheme-accent-glow — accent with alpha 0.3
• --ne-scheme-accent-subtle — accent with alpha 0.1
• --ne-glass-bg-tinted — accent with the Glass opacity slider’s alpha (theme-wide glass setting)
• --ne-glass-bg-tinted-hover — same as --ne-glass-bg-tinted but ×1.4 alpha (capped at 1.0); used for glass-on-glass hover surfaces
• --ne-glass-border-tinted — accent with the glass-border alpha

Customizing a scheme

1. Theme settings → Color schemes → choose a scheme (1–5).
2. Edit any of the 34 roles using the color picker.
3. The preview updates live; check both light backgrounds and dark backgrounds work.

✅ WCAG AA contrast is a Shopify Theme Store reviewer-check. Use a contrast checker like WebAIM to verify text-on-background pairs reach 4.5:1 (normal text) or 3:1 (large text, ≥18pt).

Default scheme

Setting	What it does
🔧 Global default scheme	The scheme used as the default everywhere unless a section overrides it. ✅ Default: scheme-1.

Dark/Light pair

This is Hyprism’s signature feature for stores that offer a dark-mode toggle. Two schemes are designated as a “pair”:

Setting	What it does
🔧 Enable dark/light pair	Master toggle. Off by default.
🔧 Pair primary scheme	The scheme shown in the primary mode — by convention the dark scheme (this is the global default). ✅ Default: scheme-1.
🔧 Pair alternate scheme	The scheme shown in the alternate mode — by convention the light scheme. ✅ Default: scheme-2.

When the pair toggle is on, every section with Use global color scheme = on swaps to the alternate scheme when the dark-mode toggle is pressed. Sections with per-section schemes can opt into the pair via their own dark/light settings.

💡 By convention pair-primary is the dark scheme (near-black background, light text) and pair-alternate is the light scheme — matching the schema labels “Dark (global default)” / “Light (global default)”. The two schemes share an accent color so the brand stays consistent across both modes. (See §2.5 for the default-mode control.)

Color appearance vs dark/light pair (terminology)

Hyprism uses “Color appearance” in the customizer for the parent settings tab (so the same tab covers single-mode and pair-mode setup). Inside, the dark/light pair is the specific feature that ties two schemes together via the storefront toggle.

2.3 Typography (4 font roles + body defaults + H1–H6)

Theme settings → Typography.

Font roles (4 roles)

Hyprism reserves 4 font roles. Each role is a single font-picker — the weight is encoded inside the Shopify font picker’s value (e.g., a font picked at “Bold” is a different selection from the same family at “Regular”), so there’s no separate weight slider here.

Role	Used for	Default
🔧 Body	All body text — paragraphs, list items, table content, captions	Work Sans Regular
🔧 Subheading	Eyebrow text, section labels, small all-caps labels	Work Sans Regular
🔧 Heading	Default for H1–H6 unless overridden per-heading-level	IBM Plex Mono Bold
🔧 Accent	Quotes, callouts, hand-styled emphasis	IBM Plex Mono Regular

To change the weight or style (italic, bold, etc.) of a role, re-open the font picker and pick the variant you want — Shopify lists every available weight/style of the font family separately.

Body defaults (Body subheader)

Setting	What it does
🔧 Body size	12px – 18px (select). ✅ Default 14px.
🔧 Body line-height	Tight / Normal / Loose (select). ✅ Default Normal.

These apply to general paragraph and list copy throughout the storefront, except where a section explicitly overrides the size.

Per-heading-level settings (H1–H6)

Each heading level gets its own treatment via select-dropdowns (no free-text fields — Hyprism uses curated presets so visitors get a consistent type-scale):

Setting	What it does
🔧 Font role	Which of the 4 roles to use — Body / Subheading / Heading / Accent. Defaults to Heading for H1–H4 and Subheading for H5–H6.
🔧 Size	Fixed pixel options (select). The available range varies per level: H1 spans 28–96px (default 56px), H2 spans 24–64px (default 48px), H3 spans 20–48px (default 36px), H4 spans 18–32px (default 28px), H5 spans 16–24px (default 22px), H6 spans 14–20px (default 18px).
🔧 Line height	Tight / Normal / Loose (select). H1–H3 default to Tight, H4–H6 default to Normal.
🔧 Letter spacing	Tight / Normal / Loose (select). Defaults to Normal.
🔧 Text transform	None / Uppercase / Capitalize (select). H1–H4 default to None, H5–H6 default to Uppercase.

💡 If you want all 6 levels to look related but distinct, set the same font role and only vary the size. If you want display-heavy hero text that’s different from body H2/H3, set H1 with the Accent role and the rest with Heading.

Responsive sizing (automatic)

Hyprism does not ask merchants to set a separate mobile size. Each heading’s mobile size is derived automatically from the desktop size by a per-level shrink factor (~55% for H1 down to ~88% for H6), clamped to a sensible minimum so headings never collapse below 14–26px on small viewports.

Under the hood: each heading has both --ne-h{1..6}--size (= the desktop pixel value you picked) and --ne-h{1..6}--size-responsive (= max(min-px, desktop × factor) inside a @media (max-width: 749px) block). Section Liquid that wants an h1 should style with font-size: var(--ne-h1--size-responsive) — that variable resolves correctly on both desktop and mobile without any extra media-query work.

This is a developer-only detail — merchants just pick the desktop size and Hyprism handles the mobile scaling.

2.4 Buttons & Inputs (theme-wide defaults)

Theme settings → Buttons & Inputs. Two subheaders: Buttons, Inputs.

Buttons

Setting	What it does
🔧 Font role	Which of the 4 typography roles drives button labels — Body (✅ default), Accent, Subheading, or Heading.
🔧 Vertical padding	Range 4–24px, step 2. ✅ Default 12px.
🔧 Horizontal padding	Range 8–64px, step 4. ✅ Default 24px.
🔧 Text transform	None (✅ default), UPPERCASE, lowercase, or Capitalize — applied to every button label. Note: button text-transform has all 4 options (unlike per-heading text-transform which doesn’t include lowercase).
🔧 Border width	Range 0–4px, step 1. ✅ Default 1. Primary buttons can use 0 (filled), secondary buttons typically ≥1 (outline pattern).
🔧 Button shape (variant_btn_style)	The master shape control — Button (uses the corner-radius slider below, ✅ default), Pill (fully rounded, 9999px), or Square (0px). The schema ID is variant_btn_style for historical reasons; despite the ID this drives every button in the theme.
🔧 Corner radius (btn_border_radius)	Range 0–32px, step 2. ✅ Default 8px. Visible only when Button shape = Button; hidden in Pill / Square modes since the shape forces a fixed radius.
🔧 Glass button effect (enable_glass_buttons)	✅ Default off. Applies a glassmorphism look (backdrop blur + top highlight + bevel) to every theme button. Pairs well with a background image.
🔧 Glow on button hover (enable_button_hover_glow)	✅ Default off. Adds an accent-colored glow around primary / outline buttons on hover. Off = buttons change color on hover without a glow. Turn on for glow-heavy looks (e.g. the Signature preset). Controlled via the --ne-btn-hover-glow token (default 0 0 0 0 transparent, lit only when on).
🔧 Glass color swatches (enable_swatch_glass)	✅ Default off. When on, color swatches on product cards and product pages get a glass sheen (an inset highlight bead). Pairs well with the Glass shine effect for a consistent frosted look across swatches and surfaces.

These settings flow into every .ne-btn--primary and .ne-btn--secondary element across the theme — including atom Button blocks, Newsletter submit buttons, Contact-Form submit, PDP Add-to-cart, Cart checkout button, Quick-View ATC, sticky product bar ATC, and the variant-picker pills.

💡 Because the Button shape setting is a global, you can flip the entire store to Pill with one toggle. The corner-radius slider hides automatically when it’s no longer relevant — Pill mode is permanently 9999 px regardless of the slider value.

Inputs

Setting	What it does
🔧 Input shape (input_shape)	Sets the corner style of every input across the theme — Button (uses the Input corner radius slider below, ✅ default), Pill (fully round), or Square (no radius).
🔧 Input corner radius (input_corner_radius)	Range 0–24px, step 1. ✅ Default 8px. Visible only when Input shape = Button. Lives here in Buttons & Inputs (next to Input shape) so inputs can stay rounded even when buttons are sharp-edged, or vice versa.
🔧 Border width (input_border_width)	Range 1–4px, step 1. ✅ Default 1. Applies to text inputs, textareas, and select dropdowns site-wide.
🔧 Glow on focus (enable_input_glow)	✅ Default off. Controls the entire focus halo via the shared --ne-input-focus-shadow token. Off → focus shows only the accent border-color change (no ring, no glow — still a clear, accessible focus state). On → focused inputs get a 3px accent ring plus the soft --ne-glow-sm blur. Applies consistently to every input that reads the token: .ne-input (Contact, search, filters), customer-account fields, and the Newsletter form (standard + merged-capsule mode).

2.5 Dark/Light mode toggle

Theme settings → Color appearance.

This tab combines both the single-mode default-scheme picker and the dark/light pair feature. The two are mutually exclusive: when the dark/light toggle is enabled, the global single-scheme picker hides (and vice versa).

Master setting

Setting	What it does
🔧 Enable dark/light toggle	Master switch for the whole feature. ✅ Default off. When off, the storefront uses one fixed color scheme everywhere. When on, the storefront ships with a sun/moon toggle button and uses two paired schemes.

Single-mode storefront (toggle off)

When the master toggle is off, one setting drives the entire storefront:

Setting	What it does
🔧 Global color scheme	The scheme used everywhere unless a section explicitly overrides it. ✅ Default Scheme 1.

The dark/light pair settings and the floating toggle settings are hidden in this mode.

Dark/light pair storefront (toggle on)

When the master toggle is on, four additional settings appear:

Setting	What it does
🔧 Default mode	What mode first-time visitors see before they’ve pressed the toggle. ✅ Default Primary. Options: Primary (start with the pair-primary scheme), Alternate (start with the pair-alternate scheme), System (read the browser’s prefers-color-scheme setting and start with primary for dark-preference or alternate for light-preference).
🔧 Toggle position	Where the sun/moon button appears. ✅ Default Header. Options: Header (renders inside the header action buttons), Bottom-right (renders as a floating button anchored to the bottom-right of the viewport), Bottom-left (same, bottom-left). There is no top-left/top-right or footer position — those positions tend to collide with cookie banners and cart drawers.
🔧 Pair primary scheme	The scheme shown when mode = primary. ✅ Default Scheme 1.
🔧 Pair alternate scheme	The scheme shown when mode = alternate. ✅ Default Scheme 2.

💡 Convention: pair-primary is usually the dark scheme (near-black background, light text) and pair-alternate is the light scheme. Then “Default mode = primary” gives you a dark-first store, “Alternate” gives you a light-first store, “System” honours the visitor’s OS preference. The two schemes should share an accent color so the brand stays consistent across both modes.

How the toggle works internally

When a visitor presses the sun/moon button:

1. The mode flips between primary ↔ alternate.
2. The <html> element’s data-ne-mode attribute is updated (CSS hook for any rule that needs to react to mode changes).
3. The mode is saved to localStorage under the key ne-color-mode.
4. Every element with a color-X class on the page swaps to its pair counterpart — using either the section’s own data-dark-scheme / data-light-scheme attributes (per-section override, see below) or the theme-wide pair.
5. A ne:mode-changed custom event is dispatched on document (apps and snippets can listen for this to re-render their own UI).
6. The sun/moon icon swaps to match.

FOUC-free switching

Hyprism reads the saved mode synchronously in <head> before the page paints, so dark-mode visitors never see a flash of light-mode content. The mechanism is a two-pass script (see CLAUDE.md Rule 204): a head-script sets data-ne-mode on <html> immediately, a body-end-script then swaps every color-X class on the page before first paint. Merchants just see clean swaps.

Per-section dark/light override

Some sections need their own dark/light pair regardless of the global pair — for example, a hero with a specific background image where you want the color scheme to follow the image rather than the global toggle. Those sections offer:

Setting	What it does
🔧 Use global scheme	When on (✅ default), follows the theme-wide setting and pair. When off, the section uses its own scheme below.
🔧 Color scheme	If “Use global” is off, pick a single scheme to use in single-mode storefronts.
🔧 Enable dark/light toggle for this section	Activates a per-section pair (visible only when “Use global” is off and the master toggle is on).
🔧 Color scheme (dark)	The section’s primary-mode scheme.
🔧 Color scheme (light)	The section’s alternate-mode scheme.

Internally, the section renders with data-dark-scheme="X" data-light-scheme="Y" attributes — the swap script reads these first and only falls back to the theme-wide pair when they’re absent.

2.6 Frame system (decorative window)

Theme settings → Frame.

The frame is Hyprism’s signature decorative window — a configurable border around the page content that adds depth and visual identity. It’s optional but defining.

Master toggle + style

Setting	What it does
🔧 Enable frame	Master switch. ✅ Default off. When off, no frame is rendered and the rest of the Frame-tab settings have no visual effect.
🔧 Frame style	Line (a thin inset border around the content area, ✅ default) or Area (a large outset box-shadow that extends from the frame edge outward, creating a vignette/spotlight effect). No “Off” value — turn off the master toggle above to disable the frame.
🔧 Frame offset	How far the frame sits from the viewport edge. Range 0–40px, step 2. ✅ Default 8px.

Frame inset padding (Padding subheader)

The padding controls how far the content sits inside the frame. Set independently per side so you can match wider page margins on left/right with tighter margins on top/bottom.

Setting	What it does
🔧 Top	Range 0–80px, step 4. ✅ Default 0.
🔧 Right	Same range / default.
🔧 Bottom	Same range / default.
🔧 Left	Same range / default.

Frame appearance (after the padding header)

Setting	What it does
🔧 Border width	Thickness of the frame line in Line style. Range 1–6px, step 1. ✅ Default 1px. (In Area style this still drives the inner-edge stroke that anchors the box-shadow.)
🔧 Frame color scheme	Which color scheme provides the frame color role. Visible only when the dark/light toggle is off. ✅ Default Scheme 1.
🔧 Frame scheme (dark mode)	Visible when the dark/light toggle is on. ✅ Default Scheme 1.
🔧 Frame scheme (light mode)	Visible when the dark/light toggle is on. ✅ Default Scheme 2.
🔧 Corner radius	Roundness of the frame corners. Range 0–32px, step 2. ✅ Default 16px.
🔧 Frame opacity	Alpha applied to the frame color. Range 5–100%, step 5. ✅ Default 20%. Low default lets the frame feel like a soft inset rather than a hard border.
🔧 Effect	None (✅ default), Glow (accent-colored aura pulsing along the frame edges, picks up --ne-scheme-accent-glow), or Shadow (drop-shadow underneath the frame).
🔧 Effect position	Above content (✅ default — effect renders over the page content, framing the foreground) or Below content (effect renders underneath content, framing the background).

💡 Frame is most striking on stores with a defined wallpaper-style background. On stores with a plain white/dark background, leave the master toggle off or use Line style with a low opacity for a subtle inset.

Per-scheme color control (Rule 201)

The actual frame color comes from the color scheme’s frame role — you saw it in §2.2. To change the frame color, edit the frame role of the scheme you assigned in Frame color scheme (or Frame scheme (dark/light) if the dark/light pair is on). The frame element on the page gets the corresponding .color-X class added, so the color cascades through CSS naturally instead of being captured at render time (technical detail: this avoids a Liquid per-scheme-loop variable quirk — see CLAUDE.md Rule 200/201).

2.7 Effects (theme-wide glass, glow, shadow, animations)

Theme settings → Effects. Three subheaders: Glassmorphism, Section glow + shadow intensities, Animations.

Glassmorphism

The glass surface is the most distinctive Hyprism effect — a translucent surface that blurs whatever is behind it.

Setting	What it does
🔧 Glass blur	The size of the backdrop-blur. Range 0–40px, step 2. ✅ Default 16px.
🔧 Glass opacity	The alpha of the glass surface fill, expressed as a percentage of full opacity. Range 0–30%, step 1. ✅ Default 3%. (Capped at 30% deliberately — values higher than that visually destroy the “frosted” effect.)
🔧 Glass saturate	Boosts color saturation seen through the glass (gives it that “frosted but vivid” look). Range 100–200%, step 5. ✅ Default 140%.
🔧 Glass shine	Adds a button-style top highlight + bevel to every glass surface (sections, cards, blocks, tiles) — the same refined sheen the header buttons use. ✅ Default off.
🔧 Glass tint intensity	How strongly the accent color tints a glass surface when that surface’s “Tint glass with accent” toggle is on (per-section, per-card-grid, cart drawer, sticky bar, quick view, footer). Range 5–100%, step 5. ✅ Default 50%. Higher = more saturated accent overlay.

These settings are the single source of truth for every glass surface in the theme — every section’s glass mode, every block’s glass mode (group, icon, bento tile, before-after handle, hotspot card, store-map info card, quick-view trigger, etc.). Adjust once, the entire theme follows.

⚠️ Functional overlays (modal backdrops, drawers, lightboxes) do NOT use these settings. Those have fixed blur/dim values because they need to stay readable independent of merchant preference. If you set glass opacity to 0, you don’t want modal backdrops to disappear — they keep their built-in dim.

Section glow + shadow intensities

These intensities are multipliers that scale glow and shadow effects across every section and block that uses them. You set them once globally, every component scales proportionally.

Setting	What it does
🔧 Section glow intensity	Range 50–200%, step 5. ✅ Default 100%. Multiplies the glow blur radius and alpha across all sections and glow-enabled blocks. Block-level glows automatically pick up ~60% of the section multiplier so blocks stay subtler than full sections (see CLAUDE.md Rule 207).
🔧 Section shadow intensity	Range 50–200%, step 5. ✅ Default 100%. Multiplies drop-shadow blur, offset, and alpha across all sections and shadow-enabled blocks. Same 60% block scaling pattern.

Glow is the soft accent-colored aura that surrounds glow-enabled sections — it uses --ne-scheme-accent-glow (the active scheme’s accent color at ~30% alpha). Shadow is the classic drop-shadow underneath shadow-enabled sections — it uses --ne-scheme-shadow (the active scheme’s shadow color, mixed through color-mix()).

Animations

Setting	What it does
🔧 Enable scroll animations	Master toggle for scroll-triggered section entrance animations. ✅ Default on. When off, sections appear instantly without animation.
🔧 Animation style	The kind of entrance animation. Options: Fade up (slide in from below, ✅ default), Fade down (slide in from above), Scale (scale up from 95%), or None (instant — same effect as turning the master toggle off).
🔧 Animations replay	Whether animations replay on every scroll-into-view or only the first time. Options: Once (✅ default — animate the first time a section enters the viewport, then leave it static), Always (re-trigger every time the section scrolls in and out).
🔧 Add-to-cart animation	When an item is added to the cart, the header cart icon pops and a small product-image preview flies to the cart icon. ✅ Default on.
🔧 Animation style	The pop style of the cart icon when an item is added. Options: Bounce (✅ default), Pop, Pulse, Wobble. Only shown when Add-to-cart animation is on.

💡 Always looks lively but can feel jittery in long pages. Once is the safer default. Both respect prefers-reduced-motion — visitors with motion-reduction enabled get no animation regardless of these settings.

2.8 Background (page wallpaper + X-Ray effect)

Theme settings → Background. Two subheaders: Background image, X-Ray effect.

Background image

Setting	What it does
🔧 Background image	Upload a wallpaper-style image. Always covers the viewport — Hyprism uses CSS background-size: cover internally so the image fills the page width without tiling.
🔧 Alternate background image	Visible only when the dark/light toggle is on. Upload a second image that the storefront swaps to whenever dark mode is active. Use this if your primary background only reads well on one mode.
🔧 Use primary image in both modes	Visible only when the dark/light toggle is on. ✅ Default off. When on, the primary image stays in both modes and the alternate is ignored — useful if your primary image is mood-neutral and works in both.
🔧 Overlay opacity	Range 0–100%, step 2. ✅ Default 92%. Darkens (or tints, depending on the active scheme’s bg-overlay) the wallpaper for text readability. High default keeps text crisp on busy images.
🔧 Scroll behaviour	Fixed (image is anchored to the viewport, content scrolls over it — classic parallax-ish feel, ✅ default) or Scroll with page (image scrolls with the rest of the page).

The background sits at the lowest z-index layer (z=0). Everything else (content, frame, header) stacks on top. The overlay tint color comes automatically from the active color scheme — there is no separate background-overlay-color setting; it adapts when the color scheme changes.

💡 For Linux-rice aesthetics, a moody abstract wallpaper with a high overlay opacity (~90%) keeps the wallpaper as texture without overwhelming content. For minimalist brands, leave Background empty — the scheme’s background color fills the page.

X-Ray effect

X-Ray is a Hyprism signature feature: an interactive “spotlight” that follows the mouse cursor across the background. Underneath the spotlight, content layers become semi-transparent so the wallpaper shows through. It’s purely decorative — content remains fully clickable.

Setting	What it does
🔧 Enable X-Ray cursor effect	✅ Default off. When on, the storefront tracks the mouse and renders an animated spotlight that reveals the background layer beneath the cursor.
🔧 X-Ray spot size	Range 20–800px, step 20. ✅ Default 200px. The diameter of the spotlight. Larger values feel slower and more atmospheric; smaller values feel like a precision flashlight.

💡 X-Ray only makes sense when a Background image is set — otherwise there’s nothing to reveal under the spotlight. The effect is disabled automatically on touch devices (no mouse), and respects prefers-reduced-motion.

2.9 Theme-wide layout defaults

These are the Layout tab’s top-level settings. Detailed coverage with ranges/defaults lives in chapter 3 — Layout system. The summary here is for quick reference.

Theme settings → Layout.

Setting	Detail in
🔧 Page width	§3.1
🔧 Custom page width	§3.1 (only used when Page width = Custom)
🔧 Policy content width	§3.1 — max width of the text column on the shop-policy pages (privacy, refund, terms, shipping). Range 600–1400px, ✅ default 820. These pages use Shopify’s built-in layout, so this is the one place their width can be set.
🔧 Page margin	§3.1
🔧 Section inner padding X	§3.1
🔧 Header applies page margin	§3.8
🔧 Header applies page width	§3.8
🔧 Section spacing	§3.2
🔧 Gap between header and first section	§3.2
🔧 Add spacing below footer	§3.2
🔧 Global corner radius	§3.4

(The Input corner radius setting now lives in Buttons & Inputs → Inputs, next to Input shape — see §2.4.)

Mobile-layout overrides (Layout → Mobile subheader)

Setting	What it does
🔧 Enable mobile layout overrides	Master toggle. Off by default.
🔧 Mobile page margin	(when enabled) overrides desktop page margin on mobile
🔧 Mobile section inner padding X	(when enabled) overrides desktop inner padding on mobile
🔧 Mobile section spacing	(when enabled) overrides desktop section spacing on mobile
🔧 Enable mobile touch hint	Adds a subtle swipe-hint animation to carousels on mobile (chevrons that pulse to indicate horizontal scrollability)

When mobile-layout overrides is off, the desktop values apply on every viewport. Turn it on to set mobile-specific values.

Product cards (Layout → Product cards subheader)

These are global product-card settings that apply everywhere a product card appears (product grid, featured collection, recently viewed, wishlist, etc.).

Setting	What it does
🔧 Enable Quick add	When on (✅ default), product cards show a quick-add button (the icon/style is controlled by the section using the card). Turn off to hide all quick-add buttons site-wide.
🔧 Badge shape	Pill / Rounded / Square (select). ✅ Default Pill.
🔧 Badge corner radius (badge_corner_radius)	Range 2–16px, step 1. ✅ Default 4. Visible when Badge shape = Rounded.
🔧 Badge position	Top-left / Top-right / Bottom-left / Bottom-right (select). ✅ Default Top-left.
🔧 Badge size	Small / Medium / Large (select). ✅ Default Medium.
🔧 Sale badge format	What text appears on Sale badges — Percentage (renders -X%, ✅ default), Absolute (renders -X$ using the saved-amount difference between price and compare-at price), or Text (renders the literal word “Sale”).
🔧 Show “New” badge	✅ Default off. When on, products created within the configured window get a New badge.
🔧 New-badge window (days)	Visible only when Show “New” badge is on. Range 1–90 days. ✅ Default 14 days.
🔧 Show both Sale and New	Visible only when Show “New” badge is on. ✅ Default off. When on, a product that is both new and on sale shows both badges side by side; otherwise the Sale badge takes precedence.

These are read by every product card across the theme — rendered in Liquid via snippets/product-card.liquid plus the JS-rendered cards in recently-viewed-grid and wishlist-grid which read the same CSS variables via class modifier .ne-badge--card (set in assets/critical.css).

2.10 Wishlist

Theme settings → Wishlist. Two subheaders: Heart on product cards, Wishlist page link.

The Wishlist tab controls the theme-wide on/off for the wishlist feature and configures how the heart button appears on every product card. The per-section block on the product page (product-wishlist) and the wishlist grid (wishlist-grid) have their own additional settings — see §7.6 and §7.8.

Master toggles

Setting	What it does
🔧 Enable wishlist	✅ Default on. Master switch for the whole feature. When off, all wishlist UI is suppressed and all gated settings below hide.
🔧 Show wishlist button on product cards	✅ Default on. Visible when Enable wishlist is on. When on, every product card across the theme gets a heart-shaped wishlist button at the configured position.

Heart on product cards

Setting	What it does
🔧 Heart position	Top-left / Top-right (✅ default) / Bottom-left / Bottom-right. Where the heart sits on each card.
🔧 Heart style	Outline (✅ default — line-only heart, fills only when the product is saved) or Filled (heart is always filled, fill color toggles between neutral and active).
🔧 Active color	The color the heart fills with when the product is in the wishlist. ✅ Default #f87171 (light coral, matches the default sale_price color scheme role).

Wishlist page link

Setting	What it does
🔧 Show wishlist link in header	✅ Default on. Visible when Enable wishlist is on. When on, the header gets a wishlist link/icon with a counter badge that updates as visitors add or remove items.
🔧 Wishlist page URL	URL picker. Visible when Show wishlist link is also on. Default behaviour points to /pages/wishlist (Hyprism ships a templates/page.wishlist.json for this). Override if you want the wishlist page on a different URL.

How wishlist state works

Wishlist state is stored in the visitor’s localStorage under the key ne-wishlist. Each entry is a JSON object with id, handle, title, image, price, url. Adding a product appends an entry; removing splices it out. The wishlist page reads from the same key and renders product cards via JavaScript (no server roundtrip — it’s purely browser-local).

When a wishlist update happens, saveWishlist() writes to localStorage and then immediately calls two DOM-update helpers: updateAllButtons() (toggles the active class on every wishlist heart on the page) and updateCounts() (refreshes every header badge that has a [data-wishlist-count] attribute). There is no event dispatched on the main code path — counter and button state are kept in sync directly inside the toggle handler.

Note: wishlist state lives entirely in localStorage — there is no ne:wishlist-updated JavaScript event. Custom integrations that need to react to wishlist changes should read localStorage (or listen for the browser storage event) rather than a theme event.

⚠️ Because storage is browser-local, wishlists are device-specific. A visitor’s wishlist on their phone doesn’t sync with their wishlist on a laptop. This is intentional — keeps the feature accountless and fast, with no merchant data-handling cost. Stores that want cross-device wishlist should integrate a third-party wishlist app instead.

2.11 Social media (14 platforms + 3 custom slots)

Theme settings → Social media.

Social profile URLs populate the Organization-schema sameAs array (so AI search engines, Google’s Knowledge Panel, and aggregators recognise your store as a single entity across the web) AND drive the icons rendered in the Footer’s social block.

The repeating pattern

Each of the 14 built-in platforms has the same 3-setting pattern:

Setting	What it does
🔧 {Platform} URL	Full URL to your profile. Leave blank if you don’t use that platform — Hyprism only renders icons for platforms that have a URL set.
🔧 Use custom icon for {Platform}	Toggle. Visible only when the URL is filled. ✅ Default off. When on, Hyprism uses your uploaded icon instead of the built-in SVG.
🔧 Custom icon for {Platform}	Image picker. Visible only when the custom-icon toggle is on. Upload a 1:1 SVG or PNG; Hyprism will recolor it to match the active scheme’s text color automatically.

Built-in platforms (14)

In the order they appear in the customizer panel:

1. Twitter / X
2. Facebook
3. Instagram
4. TikTok
5. YouTube
6. Pinterest
7. Discord
8. GitHub
9. LinkedIn
10. Snapchat
11. Tumblr
12. Vimeo
13. Twitch
14. Spotify

All 14 ship with a built-in monochrome SVG icon that Hyprism auto-colors to match the active color scheme. Override per-platform with the custom-icon toggle if you need a different icon for any reason (e.g. for a brand-mark variant).

Custom slots (3)

For platforms not in the built-in list (Mastodon, Bluesky, Threads, BeReal, Reddit, a podcast platform, a corporate blog, etc.), 3 custom slots are available:

Setting	What it does
🔧 Custom 1 label	Free text. Used as the aria-label and the sameAs schema entry’s name.
🔧 Custom 1 URL	Full URL to the profile.
🔧 Custom 1 icon	Image picker. Required for custom slots — there’s no built-in fallback. Upload a 1:1 SVG or PNG.

Slots 2 and 3 have the same structure. All slots only render if both label and URL are filled.

Icon recoloring

Custom-uploaded icons (whether they replace a built-in or fill a custom slot) are auto-colorised to match the active scheme’s text color. This works via CSS mask-image with background-color: currentColor — your icon should be a solid monochrome silhouette (transparent background, solid black or solid white shape). Photographic or multi-colored icons will look wrong. See CLAUDE.md for the implementation detail (search “social-icon-filter”).

Where these URLs show up

Use	Where
Footer social icons block	Footer (when the block is added)
Organization-schema sameAs array	Every page’s <head> (if Organization schema emission is on — see §13.2)
Header social link block	Optional, when added as a header block

Next

You’ve configured the foundation. Now go to:

• Chapter 3 — Layout system for per-section spacing and mobile overrides
• Chapter 4 — Header and chapter 5 — Footer to wire up the site-wide chrome
• Chapter 6 — Hero and storytelling sections to start building your home page