Atom blocks (the universal building blocks)

Almost every section in Hyprism accepts atom blocks — small, reusable content primitives you can mix in any combination. When a section schema says "blocks": [{"type": "@theme"}] or lists heading, text, button, etc., these are the blocks you can drop in.

This chapter is the reference for the 8 atom blocks. Every section chapter (6, 7, 8, 9, 10) will say things like “drop in heading + text + button” — when you need to know what those blocks actually do, you’re in the right place.

The atom blocks

Block	Purpose
🧩 Heading	A single line/paragraph with semantic h1–h6 + visual styling
🧩 Text	Rich-text paragraph (links, lists, emphasis)
🧩 Button	Primary / secondary / link-style CTAs with optional icon
🧩 Image	Single image with caption, link, aspect-ratio, effects
🧩 Icon	Icon-library or custom-upload icon with optional label
🧩 Group	Container that holds other blocks in a row / column with shared chrome
🧩 Divider	Horizontal rule (5 styles: solid, dashed, dotted, gradient, glow)
🧩 Spacer	Vertical empty space (responsive height options)
🧩 Box	Sizable container / decorative panel (own size, surface, scheme) — §5a.12
🧩 Shape	Clips a box to a polygon / library shape / freeform outline — §5a.13
🧩 Glass logo (3D)	Extrudes a logo SVG into live 3D glass on the visitor’s GPU — §5a.14

Plus the Slider, Kinetic heading, and Scramble heading blocks (§5a.9–5a.11), and every block except Spacer and Glass logo carries the Advanced settings suite (free positioning, glow/shadow, parallax, entrance animation — see below).

Universal patterns (read once, applies to every block)

Atom blocks share three universal behaviors. Understanding these once saves repeating them in each block’s section.

Inheriting alignment from the parent

Heading, Text, Button, Image, and Icon all have an Alignment setting with these options:

• Inherit from parent ← default
• Left / Center / Right

When set to Inherit, the block follows the parent section’s or group’s text-alignment. This means you can set alignment once on the parent (e.g. “section content: centered”) and every text/button inside follows automatically. Override per-block only when you want one item to break the pattern (e.g. centered headings but left-aligned body text in a card).

💡 The inherit pattern uses CSS custom properties (--ne-bw-justify), so parent → child cascade is automatic. No JavaScript involved.

Color-role picker

Heading and Text have a Color role dropdown:

• Auto / inherit ← uses the scheme default for this element type
• Heading — paint as the active scheme’s heading color
• Text — paint as text color
• Accent — paint as accent color

For most cases keep it on Auto. Use Accent to make a single word or phrase pop in the brand’s accent color, or Heading on a <h2> body text to break expected visual hierarchy.

Custom color scheme override + dark/light pair

Most atom blocks that paint something (Heading, Text, Button, Group) have the full custom-scheme settings below. Exceptions: Icon has only the toggle + a single scheme override (no dark/light pair); Image and Divider have no scheme settings (Divider has its own color mode instead).

Setting	What it does
🔧 Custom color scheme	Toggle — when off, inherit parent. When on, override with a specific scheme.
🔧 Color scheme	Pick a scheme (1–5) — visible when toggle on and the theme has no active dark/light pair
🔧 Dark mode color scheme	Pick scheme for dark mode — visible when toggle on and dark/light pair is active
🔧 Light mode color scheme	Pick scheme for light mode — visible when toggle on and dark/light pair is active

If your theme uses the dark/light toggle (chapter 2 — Foundation), the second and third pickers appear instead of the single picker, so the block has matching schemes for each mode. The toggle in the header automatically switches.

⚠️ Don’t go scheme-override-happy. Letting blocks inherit parent scheme is what makes the theme look coherent. Override only when you have a specific reason — e.g., a button on a hero that needs a contrasting scheme to stand out from the hero image.

Advanced settings

Every atom block except Spacer has an Advanced settings section at the very bottom, hidden behind a toggle. Leave it off for normal use; switch it on for free positioning and an entrance animation — the kind of per-element control most Shopify themes don’t expose. Turning the toggle off again fully resets the effect (it’s not just hidden — the block snaps back to its normal place).

Setting	What it does	Default
🔧 Advanced settings	Master toggle — reveals everything below. Off = none of it applies.	off
🔧 Offset unit	Whether offsets are measured in Pixels or % of viewport (vw/vh). % lets you place a block anywhere on screen regardless of its size.	Pixels
🔧 Offset X / Offset Y	Nudge the block horizontally / vertically without affecting the layout of its neighbours. In Pixels mode: −200…200px in fine 4px steps (precise placement). In % of viewport mode: −100…100% (vw/vh) for moving far / toward a neighbouring section. The relevant slider shows depending on the offset unit.	0
🔧 Rotation	Rotate the block (−180…180°).	0
🔧 Scale	Shrink or enlarge the block (50…150%).	100
🔧 Opacity	Fade the block (0…100%).	100
🔧 Layer (z-index)	Stack order — raise to bring the block in front of overlapping siblings, lower to push it behind. Useful with offsets to overlap blocks.	0
🔧 Overlap into neighbouring section	Lets the block spill past its section edge and overlap the section above/below (use with an offset). Layer order follows z-index (defaults to in-front). Note: turns off the section’s own corner-radius clipping while on.	off
🔧 Glow	Adds a soft accent-colored glow around the block.	off
🔧 Glow intensity	Strength of the glow (0…100%) — drives brightness, so higher = more visible. Shown when Glow is on.	50
🔧 Shadow	Adds a drop shadow under the block.	off
🔧 Shadow intensity	Strength/spread of the shadow (0…100%). Shown when Shadow is on.	50
🔧 Sharpness	100% = crisp; lower values blur the block (0% = very blurry).	100
🔧 Parallax on scroll	Master toggle — reveals the parallax controls below. The block drifts / rotates / zooms as it scrolls through the viewport (strongest at the top/bottom of the screen, neutral in the middle). Respects reduced-motion.	off
🔧 Parallax drift X / Y	How far the block drifts horizontally / vertically on scroll (−100…100%). Negative reverses the direction. Shown when Parallax is on.	0
🔧 Parallax rotation	How much the block rotates on scroll (−45…45°). Shown when Parallax is on.	0
🔧 Parallax zoom	How much the block scales on scroll (−50…50%). Shown when Parallax is on.	0
🔧 Custom mobile values	Master toggle — reveals a mobile counterpart for every advanced value below (offset, rotation, scale, opacity, glow + intensity, shadow + intensity, sharpness, parallax). Below 750px these override the desktop values; anything left at its default falls back to the desktop value. (z-index, overlap and the entrance animation are not mobile-overridable.)	off
🔧 Mobile · (each value)	The mobile version of each setting above — same ranges/units. Shown when Custom mobile values is on.	matches desktop default
🔧 Entrance animation	How the block reveals as it scrolls into view: None / Fade / Fade up / Fade down / Scale.	None
🔧 Animation delay	Delay before the entrance animation starts (0…1000ms) — stagger several blocks by giving each a larger delay. Shown when an entrance animation is chosen.	0

Notes

• Offset, rotation and scale compose — set several together (e.g. nudge + tilt) and they combine into one transform. The entrance animation layers on top and settles into the resting position.
• Glow, Shadow and Sharpness compose into a single filter; they only cost rendering when actually used. Combining advanced Glow/Shadow with a block that already has its own glow/shadow (Group, Image) may stack — use one or the other.
• The entrance animation reuses the theme’s scroll-reveal system and respects reduced-motion (visitors who prefer less motion see the block immediately, in its final position).
• Offsets move the block visually only; surrounding blocks keep their positions, so overlaps are intentional. On narrow screens, keep offsets modest to avoid pushing content off-screen. (Note: offsets are currently clipped at the section edge — overflowing into a neighbouring section is on the roadmap.)
• Spacer has no Advanced section — offset/rotation/animation on an invisible spacing element would do nothing.

---

5a.1 Heading block

A semantic heading (h1–h6) with full typography control. The most-used block in any section that needs a title.

Settings — content

Setting	What it does
🔧 Heading	The text content (single line). ✅ Default: “Heading”
🔧 HTML tag	h1 / h2 / h3 / h4 / h5 / h6 — semantic tag for screen-readers + SEO. ✅ Default h2.

⚠️ There should only be one h1 per page. Most pages have it in the hero or page-title. Use h2 for section titles, h3+ for subheadings inside sections.

Settings — typography

Setting	What it does
🔧 Visual style	Decouples visual size from semantic tag — pick a font role: Use tag (inherit from h1–h6) / Heading / Subheading / Accent / Body / Custom. ✅ Default “Use tag”.
🔧 Font size (Custom only)	10–140px — when Visual = Custom
🔧 Separate sizes for tablet / mobile (Custom only)	Toggle responsive font scaling
🔧 Font size tablet (≤990px)	Override for tablet viewport
🔧 Font size mobile (≤640px)	Override for mobile
🔧 Letter spacing (Custom only)	Tight / Normal / Loose
🔧 Line height (Custom only)	Tight / Normal / Loose
🔧 Text transform (Custom only)	None / Uppercase / Capitalize

💡 The Visual style setting is what makes Hyprism’s typography flexible. You can have a <h3> (semantic for SEO) but visually style it like subheading (the brand’s defined small-caps eyebrow). Set semantic correctly for accessibility/SEO; pick visual independently to match the page’s design rhythm.

Settings — color

Standard color-role + custom-scheme picker (see “Universal patterns” above).

Settings — layout

Setting	What it does
🔧 Text alignment	Inherit / Left / Center / Right
🔧 Margin top	0–200px
🔧 Margin bottom	0–200px. ✅ Default 16px (gives breathing room below heading before body text)
🔧 Max width (0 = full)	Cap heading width for readability; 0 = follow parent. Useful for hero overlays where headings shouldn’t span ultra-wide screens.

When to use Heading

• ✅ Section titles (h2), subheading rows (h3), card titles (h3 or h4)
• ✅ Hero overlay heading (h1 if it’s the page’s primary title)
• ✅ Promo eyebrows above a heading — set visual = accent, semantic = <p> (use Text block) or visual = subheading, semantic = <h3> if it’s a navigable subheading

---

5a.2 Text block

A rich-text paragraph supporting links, lists, bold/italic emphasis, and other rich-text formatting.

Settings — content

Setting	What it does
🔧 Text	Rich-text editor. Supports paragraphs, links, bold, italic, lists.

Settings — typography

Setting	What it does
🔧 Visual style	Body (default) / Subheading / Heading / Accent / Custom
🔧 Custom font role	When Visual = Custom, pick which of the 4 font roles to use (Body / Subheading / Heading / Accent)
🔧 Font size	10–80px. ✅ Default 16px. Applies when Visual size = Custom.
🔧 Separate sizes for tablet / mobile	Toggle responsive font scaling
🔧 Font size tablet (≤990px)	10–80px ✅ 15px
🔧 Font size mobile (≤640px)	10–80px ✅ 14px
🔧 Text transform	None / Uppercase / Capitalize
🔧 Line height (line_height)	Range 1.0–2.4, step 0.1. ✅ Default 1.6.
🔧 Paragraph spacing (paragraph_spacing)	Range 0–48px, step 2. ✅ Default 14.

Settings — layout

Setting	What it does
🔧 Text alignment	Inherit / Left / Center / Right / Justify (text justified to both edges, unique to Text block)
🔧 Max width (0 = full)	Cap readable width; 0 = follow parent. ✅ For body copy: 600–800px (≈ 65 characters per line — readability sweet spot)
🔧 Margin top	0–200px
🔧 Margin bottom	0–200px ✅ 16px

Settings — color

Standard color-role + custom-scheme picker (see “Universal patterns” above).

Settings — effects

Setting	What it does
🔧 Drop cap	First letter rendered large (editorial / magazine style).
🔧 Highlighted text	When the rich-text contains <mark> tags (added via the rich-text toolbar), they get a brand-accent background highlight.

When to use Text

• ✅ Body paragraphs in sections, hero subheadlines, product descriptions, article excerpts
• ✅ Multiple paragraphs of editorial content
• ✅ Lists (use the rich-text toolbar to insert bullet / numbered lists)
• ⚠️ Don’t use Text block for one-word labels or eyebrows. Use Heading with <p> tag + Accent visual style instead — Text is built for paragraph-shape content.

---

5a.3 Button block

A clickable CTA — primary or secondary style. Buttons inherit theme-wide button defaults (radius, padding, shadow) from theme settings, but you can override per-block.

Settings — content

Setting	What it does
🔧 Button label	The visible text. ✅ Default “Shop now”
🔧 Link	Where the button goes (page, product, collection, URL)
🔧 Open in new tab	Adds target="_blank"
🔧 Accessibility label	Screen-reader label (overrides visible label for assistive tech) — use when label is an icon-only or vague

Settings — style

Setting	What it does
🔧 Button style	Primary (✅ default — filled, brand-accent) or Secondary (outlined). Both read colors from the active scheme’s button roles (see §2.2). There is no third “Link” style — for tertiary inline actions, use a secondary button with fx_lift: off and no shadow effects, or just an <a> inside a Text block.
🔧 Custom color scheme	✅ Default off. When on, exposes a color-scheme picker (plus dark/light pair when the theme-wide pair is active) — overrides scheme for this specific button.
🔧 Override defaults	✅ Default off. Toggle to expose the four overrides below.
🔧 Size	Inherit (✅ default) / Small / Medium / Large. Schema values are sm / md / lg. Visible when Override = on.
🔧 Shape	Inherit (✅ default) / Rounded / Pill / Square. Visible when Override = on.
🔧 Font role	Inherit (✅ default) / Body / Subheading / Heading / Accent.
🔧 Font bold	✅ Default off. Force font-weight: 700.
🔧 Font italic	✅ Default off. Force font-style: italic.

Settings — effects

Setting	What it does
🔧 Lift on hover	Subtle 2–4px upward translate on hover
🔧 Accent glow	Soft glow around the button matching the accent color
🔧 Drop shadow	Hard shadow underneath
🔧 Soft shadow	Diffuse, larger shadow — more atmospheric than drop shadow
🔧 Magnetic cursor (enable_magnet)	✅ Default off. The button leans toward the pointer as it approaches — the “magnetic CTA” effect. One global handler drives every magnetic button in the theme, so this works on any button block anywhere (Cursor FX section, heroes, etc.). Pointer-fine devices only; disabled on touch and under reduced motion.
🔧 Magnet strength	Range 10–100, step 5. ✅ Default 40. How far the button leans toward the cursor. Visible when Magnetic cursor is on.

💡 Glow + Soft shadow combined is the signature Hyprism CTA — buttons feel floating without looking heavy. Use sparingly on primary actions (1–2 per page).

Settings — icon

Setting	What it does
🔧 Icon source	None (✅ default) / Library / Custom upload.
🔧 Icon (Library)	Pick from a built-in icon library of ~26 options (arrow-right ✅ default, arrow-left, arrow-up, arrow-down, chevron-{right/left/up/down}, cart, bag, heart, star, search, user, check, x, plus, minus, download, upload, external-link, mail, phone, map-pin, play, share, info). Visible when source = Library.
🔧 Custom icon (Upload)	Upload SVG / PNG. ✅ SVG recommended. Visible when source = Upload.
🔧 Recolor custom	✅ Default on. When on, custom-uploaded icons inherit the button text color via CSS mask-image. When off, original colors stay. Visible when source = Upload.
🔧 Icon position	Left / Right (✅ default) / Only. Only renders an icon-only button (no label visible — use Accessibility label for screen-readers). Visible when source ≠ None.
🔧 Icon size	Range 12–40px, step 1. ✅ Default 18px. Visible when source ≠ None.

Settings — layout

Setting	What it does
🔧 Alignment	Inherit / Left / Center / Right
🔧 Full width	Stretches button to fill its container
🔧 Margin top / bottom	0–200px each

When to use Button

• ✅ Primary: the single most important action on the section / page — “Add to cart”, “Shop the collection”, “Sign up”
• ✅ Secondary: alternative actions — “Learn more”, “View details”, “Browse all”
• ✅ Link: tertiary / inline actions — “Continue reading →”, “Skip to checkout”
• ⚠️ Per-page, aim for 1 primary button visible at a time. Multiple primaries dilute attention.

---

5a.4 Image block

A single image with optional caption + link + visual effects.

Settings — source

Setting	What it does
🔧 Image	Upload from Shopify Files or pick existing
🔧 Alt text override	Override the image’s alt-text for accessibility/SEO. If empty, uses the image’s default alt.
🔧 Link	Wrap image in an <a> — picker (product/collection/page/URL)
🔧 Open in new tab	target="_blank"

Settings — layout

Setting	What it does
🔧 Aspect ratio	Natural (✅ default — image’s intrinsic ratio) / 1:1 / 4:3 / 3:4 / 16:9 / 9:16 / 21:9.
🔧 Alignment	Inherit (✅ default) / Left / Center / Right.
🔧 Max width	Range 0–2000px, step 20. ✅ Default 0 (= follow parent). Cap image width when needed.
🔧 Corner radius	Range 0–64px, step 2. ✅ Default 0.
🔧 Margin top / bottom	Range 0–200px each, step 4. ✅ Default 0 each.

Settings — effects

Setting	What it does
🔧 Surface (image_surface)	None (✅ default — plain image) / Transparent (lets a transparent PNG sit on the page with no backplate) / Glass (frosted backplate behind the image — useful for logos/cut-out PNGs on busy backgrounds).
🔧 Glass shine (enable_shine)	✅ Default off. Adds the button-style top highlight to the image surface (most visible with Surface = Glass).
🔧 Drop shadow	Shadow under image
🔧 Accent glow	Soft accent-colored halo around image
🔧 Loading	Lazy (default — loads when scrolled into view) / Eager (loads immediately, use for above-the-fold images)

⚠️ Set Loading = Eager for only the very first image visible on page-load (hero or above-fold). Setting it on more than 1–2 images hurts performance because the browser blocks waiting for all eager images before painting the page.

Settings — caption

Setting	What it does
🔧 Caption	Optional text below the image (editorial style)

When to use Image

• ✅ Inline product / brand imagery in content sections
• ✅ Editorial illustrations alongside Text blocks
• ✅ Click-to-anywhere image cards (image + Link)
• ⚠️ For galleries (multiple images in a row), use the dedicated Gallery section (chapter 6) — not multiple Image blocks side-by-side. Gallery has lightbox, swipe, and grid layout built in.

---

5a.5 Icon block

An icon (from the built-in library OR custom upload) with optional label below.

Settings — content

Setting	What it does
🔧 Icon (library)	Pick from built-in library (star, heart, check, arrow, chevron, search, etc.)
🔧 Custom icon (upload)	Upload SVG / PNG — overrides library choice
🔧 Recolor custom (when uploaded)	When on, custom-uploaded icons inherit the active text color via CSS mask
🔧 Label	Optional text below the icon (e.g. “Free shipping” with truck icon)

Settings — appearance

Setting	What it does
🔧 Icon size	Range 16–160px, step 2. ✅ Default 48px.
🔧 Stroke width	Range 1–4, step 1. ✅ Default 2. Thickness of strokes for outline-style library icons.
🔧 Background style	None (✅ default) / Circle / Rounded square / Glass. Wraps the icon in a backplate.
🔧 Inner padding	Range 0–40px, step 2. ✅ Default 12px. Visible when background ≠ None.

Settings — color

Setting	What it does
🔧 Custom color scheme	✅ Default off. When on, exposes a color-scheme picker. Note: icon block has a single scheme override only — no dark/light pair (unlike heading/text/button/group).

Settings — layout

Setting	What it does
🔧 Alignment	Left / Center (✅ default) / Right.
🔧 Margin top	Range 0–120px, step 4. ✅ Default 0.
🔧 Margin bottom	Range 0–120px, step 4. ✅ Default 8px.

When to use Icon

• ✅ Feature lists with icon-per-row (icons in a Multicolumn section)
• ✅ “Why us” sections (truck = shipping, lock = security, etc.)
• ✅ Decorative accents in headers / footers (with backplate = Glass for that Hyprism look)
• ✅ Custom brand icons via SVG upload (use Recolor = on so icons adapt to dark/light schemes)

---

5a.6 Group block

A container that holds other atom blocks (and product / collection blocks where allowed). Use Group to:

• Create a sub-card inside a section with its own background / glass / glow
• Layout multiple blocks horizontally (button-row, icon-row)
• Apply shared spacing + alignment to a cluster

Settings — layout

Setting	What it does
🔧 Direction	Vertical (✅ default — stack) / Horizontal (row) / Overlay (stack) — all children occupy the same spot, layered on top of each other. Use Overlay to put two blocks exactly over one another (e.g. a heading over an image, or two headings); fine-tune each child’s position and stacking order with its own Advanced settings (offset + Layer/z-index).
🔧 Mobile direction	Stack (✅ default — collapse to column on mobile) / Horizontal (keep side-by-side on mobile). Visible when Direction = Horizontal.
🔧 Equalize children width	✅ Default off. When on, all children get equal width. Useful for button rows. Visible when Direction = Horizontal.
🔧 Width mode	Auto (✅ default — content-sized) / Full (100% of parent) / Percent / Fixed.
🔧 Width percent	Range 10–100%, step 5. ✅ Default 50%. Visible when Width mode = Percent.
🔧 Width value	Range 120–2400px, step 20. ✅ Default 400px. Visible when Width mode = Fixed.
🔧 Self-align	Stretch / Flex-start / Center (✅ default) / Flex-end. How the group itself is positioned in its parent.
🔧 Content alignment	Flex-start / Center (✅ default) / Flex-end / Stretch. Vertical or horizontal alignment of children depending on direction.
🔧 Justify	Flex-start / Center (✅ default) / Flex-end / Space-between / Space-around. Gap distribution between children in Horizontal mode.
🔧 Gap	Range 0–100px, step 2. ✅ Default 16px.
🔧 Padding (inner)	Range 0–100px, step 2. ✅ Default 0.
🔧 Corner radius	Range 0–48px, step 2. ✅ Default 0.

Settings — chrome

Setting	What it does
🔧 Custom color scheme	✅ Default off. When on, exposes scheme picker + dark/light pair — overrides parent scheme.
🔧 Glass	✅ Default off. Apply the theme’s glass blur/saturate/opacity to the group’s background.
🔧 Glass tint with accent	✅ Default off. When Glass is on, tints the surface with the scheme accent.
🔧 Accent glow	✅ Default off. Soft halo around the group. Scaled by global Block glow multiplier (60% of section glow intensity, Rule 207).
🔧 Drop shadow	✅ Default off. Shadow under the group. Scaled by global Block shadow multiplier.

Blocks accepted (nested)

The Group block is a recursive container — it accepts any of these blocks as children: heading · text · button · image · video · icon · group (nested groups!) · spacer · divider · recently-viewed-grid · wishlist-grid

When to use Group

• ✅ Card-shaped clusters inside a section (e.g., a glass-frosted “Why us” card on the home page hero)
• ✅ Button rows (Direction = Horizontal, Equalize children = on, Gap = 12px) so 2–3 CTAs sit balanced
• ✅ Icon + Heading + Text triplets (Direction = Vertical, Gap = 8px, Padding = 24px)
• ✅ “Feature highlight” cards (Direction = Vertical, Glass = on, Padding = 32px)

💡 Group’s Equalize children width setting is what makes button rows look professional — without it, two buttons with different label lengths look unbalanced.

---

5a.7 Divider block

A horizontal rule — clean visual separation between content clusters.

Settings

Setting	What it does
🔧 Style	Solid (default) / Dashed / Dotted / Gradient / Glow
🔧 Thickness	1–12px (default 1px)
🔧 Width	10–100% of parent (default 100%)
🔧 Alignment	Left / Center / Right (when Width < 100%)
🔧 Color mode	Border (inherits scheme border color) / Text (scheme text color) / Accent (scheme accent color) / Custom (pick a color)
🔧 Custom color	Color picker (visible when Color mode = Custom)
🔧 Margin top	0–200px (default 16)
🔧 Margin bottom	0–200px (default 16)

When to use Divider

• ✅ Between distinct content clusters within a single section (multiple text paragraphs that don’t deserve separate sections)
• ✅ Between footer rows
• ✅ Around editorial callouts (Style = Gradient or Glow for a more decorative break)
• ⚠️ Don’t overuse — between every text block, dividers turn into visual noise. Spacer or just margin-bottom is often enough.

💡 Glow style is unique to Hyprism — it renders the divider as a soft accent-color line that looks like a glowing wire. Pairs beautifully with the Linux-rice / glass aesthetic.

---

5a.8 Spacer block

Pure vertical empty space. Used to fine-tune the rhythm between blocks when margins alone aren’t enough.

Settings

Setting	What it does
🔧 Height	0–400px (default 32px) — the empty space added
🔧 Separate sizes for tablet / mobile	When on, override the height per viewport
🔧 Height tablet (≤990px)	0–400px (default 24) — smaller on tablet
🔧 Height mobile (≤640px)	0–400px (default 16) — even smaller on mobile

When to use Spacer

• ✅ Adding extra room around a hero / CTA cluster that the section’s padding doesn’t quite get right
• ✅ Pushing the next block down when relative margin-bottom values aren’t flexible enough
• ✅ Responsive control — when you want 64px on desktop but only 16px on mobile (impossible with a single fixed margin)
• ⚠️ Most spacing is better handled via section padding + block margins. Use Spacer for the cases those can’t reach.

---

5a.9 Slider block

A rotation-track container used inside the Brand Slider section (§10.3). Contains brand child blocks (one per logo). Handles the auto-scroll mechanics, default logo styling, and slide composition.

Settings

Setting	What it does
🔧 Speed	Range 10–150, step 5. ✅ Default 40. Pixels-per-second scroll speed. Higher = faster.
🔧 Direction	Left-to-right (✅ default) or Right-to-left.
🔧 Grayscale	✅ Default on. Renders all logos as monochrome (uniform editorial-row look).
🔧 Fade edges	✅ Default on. Soft fade at the left/right edges so logos appear to fade in/out rather than hard-cut.
🔧 Pause on hover	✅ Default on. Stops auto-scroll when the cursor hovers the slider.
🔧 Default logo height	Range 20–120px, step 5. ✅ Default 50px. Per-brand block can override.
🔧 Gap	Range 16–96px, step 8. ✅ Default 48px. Horizontal gap between logos.
🔧 Opacity	Range 20–100%, step 5. ✅ Default 60%. Logo opacity (lifts to 100% on hover when grayscale is on).

Accepted child blocks

brand only.

---

5a.10 Kinetic heading block (kinetic-heading)

The complete Kinetic headline animation (§9.6) as a standalone block — drop it into any section with a block area (Hero, Cursor FX, Section grid, Group, …). Category Text. Same engine and look as the section, block-scoped.

Setting	What it does
🔧 Heading	The headline text.
🔧 HTML tag	H1–H6 / Paragraph (✅ H2) — independent of the visual size.
🔧 Font / Font size / Line height / Uppercase / Alignment	Typography, same as the section.
🔧 Color role	Auto (inherit) (✅) / Heading / Text / Accent.
🔧 Reveal effect	Rise (✅) / Fade / Tracking / Scramble (decode) / None.
🔧 Scramble mode / Animation length	Scramble only. Once / Loop + duration.
🔧 Word stagger	Rise / Fade / Tracking only.
🔧 Hover effect	None (✅) / Accent / Glow / Weight / Lift / Tracking / Skew / Underline.

All the motion, accessibility and degradation behavior is identical to §9.6.

5a.11 Scramble heading block (scramble-heading)

A simpler, decode-only variant of the above — a standalone heading that scrambles and decodes word-by-word, front-to-back (random characters cycle, then lock to the target) when it scrolls into view. Category Text in the block picker. (Use Kinetic heading above if you also want the Rise / Fade / Tracking reveals or hover effects.)

Setting	What it does
🔧 Heading	The text to decode.
🔧 Scramble mode	Once on scroll-in (✅ default) / Endless loop.
🔧 Animation length	Range 2–12, step 1. ✅ Default 5. How long the word-by-word decode takes — higher = slower / longer.
🔧 HTML tag	H1–H6 / Paragraph (✅ H2) — the tag crawlers read, independent of the visual size.
🔧 Font	Heading (✅ default) / Subheading / Body / Accent — which theme font role.
🔧 Font size	Range 20–160px, step 2. ✅ Default 56px. Scales down responsively (clamp).
🔧 Color role	Auto (inherit) (✅ default) / Heading / Text / Accent — color within the active scheme.
🔧 Alignment	Inherit (✅ default) / Left / Center / Right.

Accessibility: the engine sets aria-label to the real text, so screen readers read the final headline (not the scrambling characters); with reduced motion the text renders static and fully legible. The scrambling characters are tinted with the scheme accent.

When to use Scramble heading

• ✅ A tech / terminal flourish inside a hero or any composed section
• ✅ A looping “decode” banner (Endless loop) as a brand statement
• ⚠️ Don’t stack many looping instances on one page — one or two reads as intentional; more is noisy

---

5a.12 Box block (box)

A sizable container that can hold other atom blocks or stand alone as a decorative panel (a glass tile, a colour block, a backdrop). Category Layout in the block picker. Think of it as a Group block (5a.6) that you can also give an explicit size, its own surface, and its own colour scheme — useful as a building brick behind/around other content.

Setting	What it does
🔧 Width	Auto / Full / Percent (✅ default 50%) / Fixed (px). Percent + Fixed reveal a slider.
🔧 Height	Auto (✅ default — fits content) / Fixed (px) / Viewport (vh).
🔧 Surface	Solid (✅ default — the scheme’s card colour) / Transparent / Glass (frosted).
🔧 Tint glass with accent	Glass only — tints the frost with the scheme accent.
🔧 Corner radius	Rounds the box corners.
🔧 Glow / Shadow	Optional depth around the box.
🔧 Use custom colour scheme	Paint the box from a scheme other than the section’s (with a Dark/Light pair when the theme toggle is on).
🔧 Advanced settings	The full per-block advanced suite (see §5a above) — offset, rotate, scale, opacity, glow/shadow, section-overlap, parallax, entrance animation, separate mobile values.

It accepts the same blocks a Group does, so you can nest headings, text, buttons, images — even another Box or a Shape — inside it.

When to use Box

• ✅ A coloured / glass panel behind a cluster of content (a “card” you fully control the size of)
• ✅ An empty decorative tile in a composed layout (leave it without children)
• ✅ A backdrop layer in a Group set to Overlay (stack) — put a Box behind a heading

---

5a.13 Shape block (shape)

Clips a box to an arbitrary shape and backs it with a colour, glass, or an image. This is the most distinctive layout primitive in Hyprism — most themes only give you rectangles. Category Layout in the block picker. Three modes:

Mode	What it draws
Regular	A regular polygon — triangle, square, pentagon, hexagon … up to 12 sides — at any rotation.
Special	A hand-tuned library shape: diamond, star, chevron, parallelogram, trapezoid, cross, arrow.
Freeform	A shape whose corners you place — add a Corner sub-block per vertex and set each one’s X / Y.

Core settings

Setting	What it does
🔧 Shape mode	Regular (✅ default) / Special / Freeform.
🔧 Sides	Regular only — 3–12. ✅ Default 6 (hexagon).
🔧 Rotation	Regular only — 0–355°.
🔧 Special shape	Special only — Diamond / Star / Chevron / Parallelogram / Trapezoid / Cross / Arrow.
🔧 Aspect ratio	Square (1:1, ✅) / Landscape (4:3) / Portrait (3:4) / Wide (16:9) / Tall (9:16) / Banner (3:1).
🔧 Corner radius	0–40px — rounds every corner of the shape (true geometric rounding, works with any surface including glass). In Freeform you can override this per corner (see below).
🔧 Width	Auto / Full / Percent (✅ 50%) / Fixed (px).
🔧 Surface	Solid (✅) / Transparent / Glass / Shader. The fill shows only inside the shape — the cut-away corners are transparent (the page shows through, never a square background).
🔧 Use custom colour scheme	Fill the shape from another scheme (Dark/Light pair supported).

Shader surface. Choosing Shader fills the shape’s silhouette with an animated WebGL gradient — the same engine as the Shader Background section (§9.13). A Shader fill sub-group appears with: effect (9 looks: gradient-mesh / aurora / prism-shimmer / plasma / swirl / ripple / starfield / mesh-grid / caustics), colour source (scheme or up-to-three custom colours), speed, intensity, scale, warp, twist, contrast, grain, vignette, pointer interaction (glow / ripple / repel / swirl) + strength, and a “disable on mobile” toggle. All the submission-safe fallbacks apply (reduced-motion / no-WebGL → static gradient). There is no logo relief inside a Shape — the clip-path silhouette already is the shape. | 🔧 Advanced settings | Full advanced suite — including glow/shadow that follow the silhouette of the shape, not a rectangle. |

Backing the shape with an image

Pick an Image and these controls appear:

Setting	What it does
🔧 Image	The picture to clip into the shape. At 100% size it fits the shape’s bounding box — its top aligns to the shape’s highest point, not the block’s top edge.
🔧 Image size	20–300% (✅ 100). Below 100% the image shrinks and reveals the fill behind it; above 100% it zooms in.
🔧 Image position X / Y	−150…150% — moves the image freely, including past the shape edge (anything outside the shape is clipped).
🔧 Image blur	0–30px.
🔧 Image opacity	0–100%.

Overlay

Setting	What it does
🔧 Overlay colour	A tint laid over the fill / image (inside the clip).
🔧 Overlay opacity	0–100% (✅ 0 = off). Use a low value to darken an image for legible text on top, or to wash the shape in the accent.

Freeform mode — placing corners

1. Set Shape mode → Freeform.
2. Add a Corner sub-block for each vertex (minimum 3). Each numbered handle in the preview shows where that corner sits.
3. In each Corner, set its Position X and Position Y with the sliders. (The handles are a live read-out — you position by the sliders, since the customizer saves the slider values.)
4. Optional per-corner radius: turn on Custom radius for this corner in any Corner to reveal a slider that overrides the shape’s general corner radius for just that vertex — set one corner to 0 to keep it razor-sharp while the rest are rounded, or give a single corner a large radius.

When to use Shape

• ✅ Editorial hero accents — an image clipped to a slanted parallelogram or a freeform wedge
• ✅ Geometric brand motifs (hexagon tiles, a star badge, a chevron divider band)
• ✅ A glass diamond or rounded-triangle panel behind a heading (Group → Overlay)
• ⚠️ Keep text out of the thin tips of sharp shapes — clipping can cut descenders; give the shape enough size

---

5a.14 Glass logo (3D) block (glass-logo)

Turns a flat logo SVG into a real, physically-lit 3D glass object rendered live on the visitor’s GPU with Three.js — extruded, bevelled, and shaded with transmission / iridescence / clearcoat. It lazy-loads (only when scrolled near) and falls back to a flat image when the device can’t run WebGL or the visitor prefers reduced motion. Add it anywhere a Group can go, or use it as the Header logo (Header → Logo, see §4.2).

Source & fallback:

Setting	What it does
🔧 Logo SVG URL (svg_url)	Paste the URL of a logo SVG you uploaded under Settings → Files. Use a clean, single-colour vector with closed paths, text converted to outlines, no gradients. Filigree logos read poorly as glass.
🔧 Fallback image (fallback_image)	Flat PNG/JPG shown before the 3D loads and on devices without WebGL / with reduced-motion. Always set one.
🔧 Alt text (alt)	Accessible name for the fallback image.

Geometry:

Setting	What it does
🔧 Depth (depth)	2–80 (✅ 26). How far the logo is extruded — its 3D thickness.
🔧 Bevel size (bevel_size)	0–20 (✅ 6). Width of the rounded edge chamfer.
🔧 Bevel depth (bevel_depth)	0–20 (✅ 5). Depth of the chamfer.
🔧 Smoothness (smoothness)	2–48 (✅ 20). Curve/bevel segment count — higher = smoother edges, slightly heavier.

Material — preset first, sliders on demand:

Setting	What it does
🔧 Material preset (material_preset)	Pick a coherent glass look (✅ Prisma). See the preset list below. Choose Custom to reveal the nine sliders.
🔧 Glass tint … Clearcoat (Custom only)	tint, transmission, roughness, ior, thickness, iridescence, dispersion, clearcoat — the individual MeshPhysicalMaterial controls. Hidden unless the preset is Custom.

Material presets: Crystal (clear) · Prisma (signature, iridescent) · Frosted · Tinted · Bubble · Liquid metal · Amber · Obsidian · Neon · Custom (unlocks all sliders).

Environment (lighting the glass reflects):

Setting	What it does
🔧 Environment look (env_look)	Lighting mood the glass reflects and refracts (✅ Studio): Studio · Soft · High contrast · Neon · Sunset · Mono. Procedural — no HDRI files, submission-safe.
🔧 Environment intensity (env_intensity) (Custom material only)	0–30 (✅ 12). Strength of the reflected environment.

Motion & shadow:

Setting	What it does
🔧 Spin (spin)	0–200% (✅ 50). Idle rotation speed. 0 = static.
🔧 Follow cursor (mouse_follow)	✅ On. The logo tilts toward the pointer.
🔧 Ground shadow (ground_shadow)	✅ Off. Casts a soft contact shadow beneath the logo.
🔧 Shadow strength (shadow_strength) (shown when ground shadow on)	0–100% (✅ 40).

Layout:

Setting	What it does
🔧 Height (height) / Mobile height (height_mobile)	Canvas height 200–800px (✅ 420) / 160–600px (✅ 300).
🔧 Content width (content_width) / Alignment (align)	Block width 20–100% (✅ 100) and horizontal alignment (✅ Center).
🔧 Object fill (obj_fill)	20–100% (✅ 82). How much of the canvas the logo fills.
🔧 Object offset X / Y (obj_offset_x / obj_offset_y)	−100…100% (✅ 0). Nudge the logo within the canvas — it may extend past the canvas edge.
🔧 Allow overflow (allow_overflow)	✅ Off. Lets the rotating model spill past the block bounds without adding page scroll.

💡 Performance & fallbacks. The heavy Three.js bundle is loaded only when the block scrolls near the viewport (above-the-fold Header logos load on browser-idle). Reduced-motion, no-WebGL, or a failed load → the flat fallback image is shown. This block is a decorative flourish — keep the SVG simple and set a good fallback.

---

Composition patterns — putting atom blocks together

These are the most common patterns merchants build with atom blocks. Each is a starting point — adjust to taste.

”Headline cluster” — eyebrow + heading + text + CTA

Group (Vertical, Gap 16):
  ├─ Heading (visual = accent, size small, e.g. "NEW COLLECTION")
  ├─ Heading (h2, visual = heading, e.g. "Sustainable Linen")
  ├─ Text (body, max-width 600px, "Discover our new spring line…")
  └─ Group (Horizontal, Equalize, Gap 12):
        ├─ Button (Primary, "Shop now")
        └─ Button (Secondary, "Learn more")

Used in hero overlays, image-with-text sections, featured-content cards.

”Feature row” — icon + heading + text, repeated

Multicolumn section with 3 columns, each containing:
  ├─ Icon (size 48, alignment center, background = circle, glass = on)
  ├─ Heading (h3, alignment center, "Free shipping")
  └─ Text (body, alignment center, "On orders over $50")

Used in “Why us” sections, value-proposition rows.

”Editorial callout” — bordered card with mixed content

Group (Vertical, Padding 32, Radius 16, Glass = on, Gap 12):
  ├─ Heading (visual = accent, "EDITORIAL NOTE")
  ├─ Heading (h3, "On craftsmanship")
  ├─ Text (drop cap on, body, max-width 800px, multi-paragraph)
  ├─ Divider (style = gradient, margin 24)
  └─ Button (Secondary style, "Read the full essay →")

Used in article excerpts, brand-story sections, premium content embeds.

”Hero overlay with stacked CTAs”

(Inside Hero / Hero Video / Featured-Page section)

Group (Vertical, Gap 12, Self-align: left, Width: 60%):
  ├─ Heading (h1, visual = heading, "Build something beautiful")
  ├─ Text (visual = subheading, max-width 500px, "Hyprism is a Linux-rice theme…")
  └─ Group (Horizontal, Mobile direction: stack, Gap 16):
        ├─ Button (Primary, fx_glow on, "Get started")
        └─ Button (Secondary, "View demo")

The mobile-direction = stack ensures CTAs stack vertically on phones without breaking layout.

”Spacer for breathing room”

Heading (h2, "Bestsellers")
Spacer (height 24 desktop, 16 mobile)
Featured-Collection block (your products)
Spacer (height 48 desktop, 32 mobile)
Heading (h2, "From our blog")

When you want consistent vertical rhythm between section-internal clusters without relying on default margins.

---

Where atom blocks are available

Atom blocks are available in almost every Hyprism section. The few exceptions:

• Header + Footer — use their own dedicated block types (Menu, Logo, Newsletter, Social, Payment, etc.)
• Template-bound sections (cart, search results page-level) — typically already have a fixed layout; atom blocks are accepted but rarely needed

Section chapters (6–10) tell you which blocks each section allows. As a rule of thumb: if a section is a “content container” (Hero, Featured Page, Multicolumn, Image-with-Text, Custom Section, etc.), all atom blocks work.

5a.9 Slider block (slider) — the universal carousel mechanism

Although technically a sub-block (not really an “atom” — it wraps OTHER blocks), the Slider block lives at this universal layer because it powers carousels in many sections: Brand Slider, Testimonial List, Gallery, Product Grid (carousel mode), Recently Viewed (carousel mode), Related Products (carousel mode).

When you see “carousel” mode in a section’s settings, the Slider block is what runs underneath. Most of the time you don’t add it manually — it’s auto-rendered by its parent section. But it has a few merchant-facing settings worth knowing.

Settings

Setting	What it does
🔧 Speed	Range 10–150, step 5 (default 40) — for marquee-style sliders, the scroll speed. Higher = faster.
🔧 Direction	LTR (left-to-right) / RTL (right-to-left) — direction the marquee scrolls
🔧 Grayscale	Make all child content monochrome — useful for unified brand-row look
🔧 Fade edges	Mask gradient on both edges of the carousel (so content fades in/out smoothly rather than hard-cutting)
🔧 Pause on hover	Marquee pauses when hovered (recommended on for accessibility)
🔧 Default logo height (Brand Slider only)	Logo height applied to all brand blocks unless overridden
🔧 Gap	16–96px between carousel items
🔧 Opacity	Range 20–100%, step 5 (default 60%) — applied to non-active items in some slider modes

When you’ll see Slider settings

• ✅ Inside the Brand Slider section (visible in customizer when you click into the Slider block)
• ✅ As “carousel mode” options inside grid-style sections (Gallery, Recently Viewed, Wishlist) — the settings are presented differently but use the same underlying Slider block
• ⚠️ Direct Slider settings are usually inside the parent section — you rarely click into the Slider block itself. Read the parent section’s docs for the merchant-facing presentation.

Next

Chapter 6 — Hero and storytelling sections — the first content sections to master, starting with Hero Image.