> For the complete documentation index, see [llms.txt](https://design-packs.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://design-packs.gitbook.io/docs/fundamentals/design-system.md). # Design System ## Apply global styles: the Design System **New to the Design System? Start here.** This guide assumes you've never used it before. By the end you'll understand what it is, how it keeps your store looking consistent, and exactly how to set it up. *** ### What is the Design System? The **Design System** is a way to define your store's look — your headings, body text, buttons, colors, images, and layout — **in one place**, and then reuse those styles across every Design Packs section. Instead of styling each section by hand, you create a central **Style Guide**, then point your sections and blocks at it. Change the Style Guide once, and everything that follows it updates together. If you've used styles in a word processor, or components in a design tool like Canva or Figma, it's the same idea — a set of reusable, named styles for your whole storefront. {% embed url="" %} *** ### The problem it solves Picture building a store **without** a Design System: * You add a hero section and style its heading and button. * You add a featured-collection section and style *its* heading and button — trying to remember the exact font, size, and color you used before. * You add five more sections and do it all again. Then you decide your buttons should be navy instead of black. Now you're hunting through **every section, one by one**, updating each button and hoping you didn't miss any. Miss a few, and your store looks slightly "off" — mismatched buttons, headings that don't quite line up, colors that are *almost* the same. This is the everyday reality of styling a store section by section: it's slow, it's easy to get wrong, and consistency slowly drifts as the store grows. *** ### How the Design System helps your Shopify store Turning it on gives you three big wins: #### 1. A consistent, professional look — automatically Every "Primary" heading uses the same font, size, and weight. Every "Primary" button looks identical, everywhere. Consistency is one of the biggest signals of a trustworthy, professional store — and here you get it by default instead of by willpower. #### 2. Restyle your whole store in seconds Want navy buttons? Change the Primary button **once** in the Style Guide. Every button across every section that uses "Primary" updates instantly. A rebrand that used to take an afternoon now takes a minute. #### 3. Faster building, fewer mistakes When you add a new section, you don't re-style it from scratch — you just point it at roles you've already defined ("Primary heading," "Body text," "Primary button") and it inherits the right look immediately. No copying hex codes, no guesswork. {% hint style="info" %} The Design System is **completely optional**. Every section works fine without it. Turn it on when you want consistency across many sections and an easy way to restyle your store from one place. {% endhint %} *** ### How it keeps Design Packs sections consistent Here's the key idea in one sentence: > You define a **style once** as a named **role**, and any block can **point at that role** instead of carrying its own copy of the styling. Because many blocks point at the *same* role, they can't drift apart — they're all reading from one source. And because that source lives in your Style Guide, updating the role updates everyone who follows it, at once. ``` YOUR STYLE GUIDE (define once) ┌─────────────────────────────┐ │ Primary button = navy, │ │ rounded, bold │ └──────────────┬──────────────┘ │ (many sections point at it) ┌──────────────┼──────────────┐ ▼ ▼ ▼ Hero button Newsletter btn Collection btn (Primary) (Primary) (Primary) └──────────────┴──────────────┘ Change the role → all three update together ``` That's the whole model. The rest of this guide is just *how* to set it up and use it. *** ### Key terms A few words you'll see throughout. Skim these now; they'll make everything else click. | Term | What it means | | ----------------------------- | ----------------------------------------------------------------------------------------------------------- | | **Design System section** | The central section where you define all your reusable styles. You set this up once. | | **Role** | A named style, like "Primary heading," "Body text," or "Add to cart button." Roles live in the Style Guide. | | **Section** | A large building block of a page (a hero, a featured collection, a rich-text area). | | **Block** | A smaller element inside a section (a heading, a paragraph, a button, an image). | | **The Design System setting** | A per-section switch that lets that section pull styles from your Style Guide. | | **🌈 style picker** | The dropdown on a block where you choose which role it should follow. | | **Tweak** | Turning on a block's own controls to override a role for that one block only. | *** ### How it all fits together The Design System has just **two pieces** that work as a pair: | Piece | What it is | You touch it… | | ------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------ | | **Design System Section** | One section where you define your roles (headings, text, buttons, media, layout, colors). | **Once**, up front. | | **Design System setting** | A setting inside each section that opts it into the Style Guide. | **Per section**, as you build. | The workflow is always the same: **set up the Design System → opt a section in → set the section's color scheme and layout → pick roles on its blocks.** *** ### Part 1 — Build your Design System This is where you define your store's look. You only do this once. #### Add the Design System section 1. In the Shopify theme editor, add a new section and search for **Design System** 2. When prompted, pick a **starter style** (below) or begin from the default. {% embed url="" %} {% hint style="warning" %} Add the Design System **once** for global styles. It defines styles for the whole store, so it isn't meant to be duplicated across templates. Many merchants add it to the homepage or a dedicated template. {% endhint %} #### Choose a starter style You don't have to start from a blank page. The Style Guide ships with ready-made presets: * **Design System: Default** — a neutral baseline with every role available. * **Design System: Bold Display** — large, high-impact display type. * **Design System: Modern Minimal** — clean, understated type and buttons. * **Design System: Editorial Serif** — classic, magazine-style serif headings. Pick the one closest to your brand, then adjust. {% embed url="" %} #### How the Style Guide applies: Global vs. Section style At the very top of the Style Guide is an **Apply as** setting. It decides *how far this Style Guide reaches*: * **Global style** *(default)* — these styles apply to **every Design Packs section that hasn't opted out**. This is your main, storewide look. You don't have to point each section at it — sections inherit it automatically (this is what the **Default** setting in Part 2 means). * ```

Styles apply to every Design Packs section that hasn't opted out

``` * **Section style** — these styles apply **only** to sections that reference this guide by name. When you choose it, you give the guide a **Style name** (e.g. `custom-styles`), then paste that name into a section's **Section Style Name** or Custom classes field. {% embed url="" %} {% hint style="info" %} **When to use Section style:** Keep one as your **Global style** for the whole store, then add extra Design Systems set to **Section style** for alternate looks — a dark variant, a seasonal theme, a special landing-page style — and apply each only where you name it. The global guide handles everything; section styles handle the exceptions. {% endhint %} A couple of related options appear alongside it: * **Hide preview tab** (Global style only) — hides the Style Guide's preview tab in the theme editor while keeping its styles active. * **Opt a section out** — add `dsgn-pck__no_design_system` to any section's **Custom classes** field to exclude it from the Global style entirely. Handy for older sections that don't yet show the Design System setting. #### The roles you can define Inside the Design System you'll find a block for each family of styles. Each one holds named roles: | Design System block | Roles inside | | ------------------------- | ---------------------------------------------------------------- | | **Typography — Headings** | Primary, Secondary, Display, Eyebrow, Subheading, Custom 1–5 | | **Typography — Text** | Body text, Small text, Lead, Pagination, Breadcrumbs, Custom 1–3 | | **Buttons — Main** | Primary, Secondary, Tertiary, Link | | **Buttons — Custom** | Custom 1–4 | | **Buttons — Product** | Add to cart, View options | | **Media** | Images, Videos | | **Layout** | Full width, Wide, Boxed, Narrow | | **Color schemes** | Light, Dark, Bold, Accent, Muted, Scheme 1–5 | | **Custom CSS** | Advanced global CSS | {% hint style="info" %} You don't have to configure every role. Anything you leave alone keeps a sensible default — only touch the roles you care about. Headings, Body text, and your main buttons are the highest-impact place to start. {% endhint %} The sections below walk through each one. #### Typography — Headings Defines your heading styles. Each role — **Primary**, **Secondary**, **Display** (extra-large, attention-grabbing), **Eyebrow** (small uppercase label above a heading), **Subheading**, and **Custom 1–5** — can set font, size, weight, style, line height, letter spacing, text transform, color, and a separate 📱 mobile size. {% embed url="" %} #### Typography — Text Defines your body-copy styles: **Body text** (the everyday paragraph style, also used for rich-text content, read-more text, and product-card info), **Small text** (captions and footnotes), **Lead** (an emphasized intro paragraph), **Pagination**, **Breadcrumbs**, and **Custom 1–3**. Controls mirror headings — font, size, weight, color, spacing.
#### Buttons Buttons are split into three blocks so you can define a full button system: * **Main** — **Primary**, **Secondary**, **Tertiary**, and **Link** (a text-style button with no fill or border by default). * **Custom** — **Custom 1–4** for any extra button styles you need. * **Product** — **Add to cart** and **View options**, so your storewide shopping buttons stay consistent. For each button role you can set text (font, size, weight, color), background, border, rounded corners, drop shadow, padding, and **hover** styles. There's also a **"Strip baseline button styles"** option for building clean text-link buttons. {% embed url="" %} #### Media styles The **Media** block sets a shared look for **standalone images and videos** (product galleries and product-card images are handled separately). Two roles — **Images** and **Videos** — each offer: | Control | What it does | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Rounded corners** | Corner radius in px. Leave at the "skip" value to inherit and not change existing corners. | | **Border width** & **Border color** | Add a border; the color appears once width is above 0. | | **Drop shadow** | Choose **Subtle / Medium / Strong**, a **Custom** value, or **None**. "Default" leaves any existing shadow untouched. | | **Enable overlay** | Adds a color or gradient overlay on top of the media — useful for darkening images behind text. | | **Additional CSS selectors** | Extend which elements this role styles (advanced). | {% embed url="" %} {% hint style="info" %} Corners, border, and shadow have a **skip / default** state meaning *"don't touch it."* That lets Media add, say, rounded corners everywhere without wiping out shadows you set elsewhere. {% endhint %} #### Layout styles The **Layout** block defines named **width presets** that control how wide a section's content sits and the space around it: | Role | Typical use | Default max width | | -------------- | -------------------------------------- | ----------------- | | **Full width** | Edge-to-edge heroes and banners | No cap (`none`) | | **Wide** | Standard content, most of the screen | `1400px` | | **Boxed** | Comfortable, contained content | `1100px` | | **Narrow** | Reading-width text and focused content | — | Each preset offers **Size** (% of screen), **Maximum width** (a hard cap like `1600px`, or `none`), **Margin top / bottom**, **Padding** (None, Range sliders, or a Custom shorthand), and optional **📱 mobile overrides**. {% embed url="" %} {% hint style="info" %} Layout presets keep spacing consistent, so every "Boxed" section lines up to the same measurements instead of each one guessing its own width. {% endhint %} #### Color schemes The **Color schemes** block defines named palettes you can reuse instead of setting colors one at a time. Each scheme — **Light**, **Dark**, **Bold**, **Accent**, **Muted**, and **Scheme 1–5** — holds a **Text** color, a **Background** color, and an optional **Background gradient**. Sections and blocks that support color schemes can then reference a named palette (e.g. "Dark"), so your dark sections all share the exact same colors — and recoloring them all is a one-place edit. {% embed url="" %} #### Custom CSS For anything the built-in controls don't cover, the **Custom CSS** block lets you add global CSS. You can **scope** it to **Design Packs sections only** or the **whole page**, and target different **breakpoints** (mobile, tablet, desktop, or a custom media query). {% hint style="info" %} This block is intended for users comfortable writing CSS. You can skip it entirely — everything else in the Design System works without it. {% endhint %} *** ### Part 2 — Apply the Design System to a section Compatible Design Packs sections have a **Design System (optional)** setting: {% embed url="" %} | Option | What it does | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Default** | The section **inherits** your Design System styles, but **doesn't show** the Design System settings. This is how every section starts when first installed — so you never see extra settings for a Design System you aren't using. | | **Show Design System settings** | The section opts in and **reveals** the Design System controls — the 🌈 style pickers on its blocks — so you can choose roles and tweak them. | | **Do not apply to this section** | Explicitly keeps this section out of the Design System entirely. | To actively work with the Design System on a section — picking roles per block — choose **Show Design System settings**. {% hint style="info" %} **Why "Default" is the starting point:** every section is set to **Default** when first installed. On Default, a section still inherits Design System styling if you have a Style Guide, but its Design System controls stay hidden — so you're never shown settings for a system you haven't set up. Switch to **Show Design System settings** when you want to pick and adjust roles yourself. {% endhint %} *** ### Part 3 — Set styles for the whole section Some Design System choices apply to the **entire section** rather than one block. As soon as you set a section to **Show Design System settings**, these appear right in the section's own settings — so you can style a section as a unit before you ever touch its individual blocks. **🌈 Color scheme** — Pick one of the palettes you defined in the Design System's **Color schemes** (Light, Dark, Bold, Accent, Muted, Scheme 1–5), or choose **Custom** to set colors for just this section. This colors the whole section consistently, and every section set to the same scheme stays in sync. * **Tweak scheme colors** — override the chosen scheme's text and background for **this section only**, without changing the scheme itself. **🌈 Layout preset** — Choose one of your **Layout** width presets (Full width, Wide, Boxed, Narrow), or **Custom**. This controls how wide the section's content sits and the spacing around it, matching every other section on the same preset. * **Tweak spacing** — override the preset's margins and padding for **this section only**. *** ### Part 4 — Choose a style for each block Once a section is set to **Show Design System settings**, its blocks gain a **🌈 style picker** — for example **🌈 Heading style**, **🌈 Text style**, or **🌈 Button style**. Open a block and choose the role it should follow: * Pick a role (**Primary**, **Secondary**, **Body text**, **Add to cart**, …) and the block instantly adopts that role's look from your Design System. * Pick **None** to leave the block on its own styling instead. {% embed url="" %} {% hint style="success" %} **This is the payoff.** Change the Primary button once in the Style Guide, and every block set to "Primary" across your store updates together. {% endhint %} A block can follow more than one role at a time — for example a block that has both a heading and a paragraph can point its heading at a heading role and its text at a text role simultaneously. *** ### Part 5 — Tweak an individual block (exceptions) Sometimes you want a block to *mostly* follow a role but differ in one small way — a Primary button that's a little wider here, or a different color in one spot. Enable **Tweak style** on the block (for buttons it reads **"Tweak button style"**). This reveals that block's own controls **on top of** the role: * Anything you set here overrides the role **for this block only**. * Anything you leave untouched keeps inheriting from the Design System. {% embed url="" %} {% hint style="warning" %} Tweaks are per-block. They **don't** change the role in your Style Guide, so other blocks using the same role are unaffected. {% endhint %} #### "Inherit" vs. "override to nothing" Some tweak controls include an **inherit** option so you can be precise: * Leaving a control at its **inherit / default** value means *"let the Design System decide."* * Setting an explicit value — including an explicit `0`, like no border or no rounded corners — means *"override the role and force this."* Setting to -1 means that it will inherit the Design System setting. So you can follow the role for most properties and deliberately strip one back to nothing where you need to. *** ### Real-world examples **Launching a sale.** You want every button to pop in red for the weekend. Open the Design System, change the Primary button background to red, save. Every Primary button across your store is red. On Monday, change it back — done. **Rebranding.** New brand fonts and colors just landed. Update the Headings, Text, and Buttons roles in the Style Guide once. Your whole store adopts the new brand without touching individual sections. **Adding a new landing page.** You build a new page from Design Packs sections. Instead of re-styling each one, you set each section to **Show Design System settings** and pick roles. The page matches the rest of your store instantly. **One-off hero button.** Your homepage hero needs an oversized button that's bigger than your standard Primary. Keep it on the Primary role, enable **Tweak**, and bump just the size. Every other Primary button stays exactly as it was. *** ### Best practices * **Start with the big three.** Configure Headings, Body text, and your main Buttons first — they cover most of what shoppers see. * **Use roles, not tweaks, as the default.** Reach for **Tweak** only for genuine one-off exceptions. The more you rely on roles, the more consistent (and easier to update) your store stays. * **Name-match intentionally.** Use "Primary" for your most important action everywhere, "Secondary" for the next, and so on. Consistent meaning makes the system predictable. * **Set it up early.** It's easiest to build on the Design System from the start, but you can adopt it on an existing store section by section at your own pace. * **Test mobile.** Many roles have 📱 mobile options — check your key headings and layout on a phone. *** ### Troubleshooting **I picked a role but nothing changed.** Check that (1) the section is set to **Show Design System settings**, (2) the block's 🌈 style is set to a role and not **None**, and (3) that role is actually configured in your Desigm System. **My tweak isn't sticking.** Make sure **Tweak style** is enabled on that block, and that the control you changed is set to an explicit value rather than its inherit/default option. **One button looks different from the rest.** It's probably on a different role, or has **Tweak** enabled. Open it and confirm its 🌈 style and whether Tweak is on. **I don't want a section to follow the Design System at all.** Set its Design System setting to **Do not apply to this section** — that opts the section out entirely. (Note that **Default** still *inherits* Design System styles; it only hides the settings.) *** ### FAQ **Do I have to use the Design System?** No — actively configuring it is optional. Sections start on **Default**, which means they inherit your Design System styles (if you've set up a Design System) without showing any extra settings. If you never set up a Design System, there's nothing to inherit and your sections look exactly as they always have. You only opt in — via **Show Design System settings** — when you want to pick and adjust roles yourself. **Will turning it on change my existing sections?** Only sections you opt in, and only the blocks where you pick a role. Everything else is untouched. **Can one block follow more than one role?** Yes. A block with both a heading and body text can point each at its own role at the same time. **Does it work on every Design Packs section?** The Design System is being rolled out across Design Packs sections. Any section showing the **Design System (optional)** setting supports it and even without the setting, older sections will inherit the styles (but none of the block-level selectors will appear) **Can I make a single element different without affecting the others?** Yes — enable **Tweak** on just that block. Other blocks on the same role won't change. **Where do I change styles once I've set everything up?** In your **Design System** section. Edit a role there, and every block following it updates.