Customization
Mast is built on a design token system. All visual decisions flow from a small set of settings that you control in the Shopify theme editor.
How the token system works
Every visual property in Mast is expressed as a CSS custom property (also called a CSS variable) on the :root element. When you change a setting in the theme editor, Shopify writes the new value into the theme's settings_data.json file and re-renders all the CSS. Every section, snippet, and template that reads from that variable updates immediately.
This means you can safely override any token in the Custom CSS field in Theme settings, and your change will cascade across all sections just as the theme's own values do. There is no need to edit section files directly for purely visual customizations.
/* Example: override the accent color with a custom value */
:root {
--color-accent: #2C5F2E;
}
Color system
Mast uses seven semantic color roles instead of dozens of individual settings. Changing these seven values is sufficient to produce a coherent new visual identity. All section color pickers reference these roles by name.
| Role | Token | Mast | Press | Nocturne | Usage |
|---|---|---|---|---|---|
| Paper | --color-paper | Primary page background. Applied to body, all section backgrounds, and any surface that should read as the base layer. | |||
| Ink | --color-ink | Primary text and foreground. Used for headings, body text, borders, and icons. | |||
| Accent | --color-accent | Interactive elements. CTA buttons, active links, hover states, and selection highlights. | |||
| Highlight | --color-highlight | Secondary background. Cards, alternate section backgrounds, table stripes, and border fills. | |||
| Rule | --color-rule | Dividers and borders. Horizontal rules, table borders, and input outlines. | |||
| Surface | --color-surface | Raised surfaces. Drawer backgrounds, modal overlays, tooltips, and form fields. | |||
| Overlay | --color-overlay | Modal and drawer overlays. The semi-transparent layer that dims the page behind open panels. |
Tip
When building a custom palette, start with Paper and Ink, then derive Highlight as a slightly lighter or darker tint of Paper (5–10% difference in lightness). Set Accent last, choosing a hue that contrasts clearly with both Paper and Highlight.
Typography system
Mast uses a three-font system. Each role has a specific purpose and is applied consistently across all sections. You can change any font to any Shopify-supported font from the theme editor.
--font-headingInstrument SerifPlayfair DisplayEB GaramondUsed in: h1, h2, h3, section titles, chapter openers, display text
Choose a font with personality: a serif with optical size variation, a distinctive italic, or strong contrast between thick and thin strokes. This font carries the brand.
--font-bodyAlmaraiInterAlmaraiUsed in: Paragraphs, product descriptions, UI labels, table content, captions
Prioritize readability at 14–16px. A clean humanist sans-serif or a warm geometric sans is best. Avoid novelty fonts here.
--font-accentCourier NewIBM Plex MonoCourier NewUsed in: Eyebrow labels, code, folio numbers, chapter numbers, meta lines
Used sparingly and at small sizes. Monospace, condensed, or slab serif fonts work well. The contrast with the heading font is what gives it editorial character.
Type scale
Mast uses a modular scale with a ratio of approximately 1.25. All sizes are expressed in rem and can be globally scaled up or down using the base font size setting.
| Token | Value | px equiv. | Used for |
|---|---|---|---|
--text-display | 4rem | 64px | Chapter numbers, 404 numerals, hero display text |
--text-h1 | 2.986rem | 47.8px | Page title h1 |
--text-h2 | 2.389rem | 38.2px | Section headings |
--text-h3 | 1.907rem | 30.5px | Subsection headings, card headings |
--text-h4 | 1.526rem | 24.4px | Column headings, sidebar headings |
--text-lg | 1.125rem | 18px | Large body copy, intro paragraphs |
--text-base | 1rem | 16px | Standard body text |
--text-sm | 0.875rem | 14px | Captions, secondary labels, product meta |
--text-xs | 0.75rem | 12px | Fine print, footnotes, eyebrow labels |
Line heights and letter spacing
| Token | Value | Usage |
|---|---|---|
--leading-tight | 1.1 | Display headings, h1 |
--leading-snug | 1.25 | h2, h3, card headings |
--leading-normal | 1.5 | Body text, labels |
--leading-relaxed | 1.7 | Long-form prose, article body |
--tracking-tight | -0.025em | Display, h1, h2 |
--tracking-normal | 0em | Body text |
--tracking-wide | 0.05em | Buttons, nav items |
--tracking-widest | 0.18em | Eyebrow labels, uppercase UI labels |
Layout tokens
Layout tokens control the geometry of the store: widths, margins, gutters, and section spacing. They are set in the theme editor under Theme settings › Layout.
| Setting | Token | Range | Description |
|---|---|---|---|
| Page width | --page-width | 1000–1600px | Maximum width of the main content area. Most editorial themes use 1280–1440px. |
| Content column | --content-width | 480–800px | Width of text-only columns (Rich Text, Chapter, Article body). Controls the optimal reading line length. |
| Page margin | --page-margin | 16–80px | Horizontal padding at the left and right edges of the viewport. |
| Grid gutter | --grid-gutter | 8–48px | Space between grid columns and between grid rows in multi-column sections. |
| Section spacing | --section-spacing | xs / sm / md / lg / xl | Base vertical spacing scale for sections. Individual sections can override this. |
| Section spacing (sm) | --section-spacing-sm | 20–40px | Spacing when section padding is set to small. |
| Section spacing (md) | --section-spacing-md | 40–80px | Spacing when section padding is set to medium. The default. |
| Section spacing (lg) | --section-spacing-lg | 80–120px | Spacing when section padding is set to large. |
| Section spacing (xl) | --section-spacing-xl | 120–200px | Spacing when section padding is set to xl. Use for editorial breathing room. |
Surface system
Surfaces define the physical qualities of UI elements: how rounded they are, whether they have borders, and whether they cast shadows.
| Token | Default (Mast) | Usage |
|---|---|---|
--radius-sm | 0px | Buttons, inputs, cards in the Mast and Press presets. Mast is intentionally square. |
--radius-md | 0px | Drawers, modals. |
--radius-full | 9999px | Badges, pills, avatar fallbacks. |
--border-width | 1px | Default border width for cards, inputs, and dividers. |
--shadow-sm | none | Small elevation. Used only in the Nocturne preset for subtle surface depth. |
--shadow-md | none | Medium elevation. Drawers and modals in the Nocturne preset. |
Motion system
All animations in Mast reference shared timing and easing tokens. This ensures transitions feel consistent across sections. All animations respect the prefers-reduced-motion media query and will disable or simplify at the user's operating system setting.
| Token | Value | Usage |
|---|---|---|
--ease-default | cubic-bezier(0.4,0,0.2,1) | Standard transitions: color, border, opacity |
--ease-out | cubic-bezier(0,0,0.2,1) | Elements entering the viewport (drawers, toasts opening) |
--ease-in | cubic-bezier(0.4,0,1,1) | Elements leaving the viewport (drawers, toasts closing) |
--ease-spring | cubic-bezier(0.34,1.56,0.64,1) | Micro-interactions: hover scale, active press |
--duration-fast | 150ms | Color and opacity transitions, hover states |
--duration-default | 250ms | Standard component transitions |
--duration-slow | 400ms | Drawer and modal open/close |
--duration-reveal | 600ms | Scroll-reveal animations |
/* Reduced motion override applied globally */
@media (prefers-reduced-motion: reduce) {
*, *::before, *::after {
animation-duration: 0.01ms !important;
transition-duration: 0.01ms !important;
}
}
Button styles
Mast has three button variants, each with its own visual weight. Buttons reference the color and surface tokens, so they update automatically when you change those values.
.btn-primarySolid fill using the Ink color with Paper text. The highest-weight button. Use for the primary action on a page or section. Add-to-cart is always Primary.
.btn-secondaryOutlined with Ink border and Ink text, transparent fill. Medium weight. Use for secondary actions alongside a Primary button.
.btn-ghostNo border, no fill, text only with an underline. Lowest weight. Use for tertiary actions and navigation links styled as buttons.
Form fields
All form inputs (text, email, select, textarea) share a common visual language. Border color uses the Rule token; focus state shifts to the Accent token.
| State | Border | Background | Notes |
|---|---|---|---|
| Default | var(--color-rule) | var(--color-surface) | 1px solid border. Background is Surface, not Paper, for a subtle depth. |
| Focused | var(--color-ink) | var(--color-surface) | Border upgrades to Ink color. No box-shadow outline: keeps the look clean. |
| Error | #E8001A | var(--color-surface) | Red border matching the Press preset accent. Error message renders below the field. |
| Disabled | var(--color-rule) | var(--color-highlight) | Slightly different background and reduced opacity on text to signal non-interactivity. |
Cart drawer
The cart drawer slides in from the right side of the viewport. Its appearance is controlled by several settings in Theme settings › Cart.
| Setting | Default | Description |
|---|---|---|
| Cart type | drawer | drawer (slide-in panel) or page (navigate to /cart). Drawer is recommended for editorial stores. |
| Drawer width | 420px | Width of the cart drawer. Range: 320–560px. Wider drawers allow more product detail to show. |
| Show order notes | true | Adds an expandable order notes field above the checkout button. |
| Show shipping estimate | false | Shows a shipping estimate section based on the customer's entered country. |
| Show shipping threshold | true | Renders a progress bar showing how far the cart total is from the free-shipping threshold. |
| Shipping threshold amount | | The threshold amount in the store's base currency. Leave empty to hide the bar. |
| Show upsell | false | Renders a recommended product below the cart items. Uses algorithmic recommendations or a manually selected product. |