Customizing the Paper Shopify Theme as a Developer

If you're new here, you might not be aware that we recently published our first Shopify theme, Paper. In that case, you probably also don't know that we've built Paper with a focus on making it easily extendable and customizable. From the start, we wanted to create a theme that offers an exceptional developer experience, and part of that effort involves providing developers like you with great tools, resources, and guides.

Keep reading to discover the benefits of using a pre-built theme for custom projects, the unique features of Paper, and how to get started with the Paper Toolkit. Additionally, we will provide examples of adding custom Tailwind components and share some helpful tips for working with Paper.

What is a Shopify Theme

A Shopify theme is a pre-built template that determines the appearance, layout, and functionality of an online store. It provides a foundation for a store's design, allowing merchants to customize the look and feel without diving into code.

Shopify themes are built using a combination of HTML, CSS, JavaScript, and Liquid (Shopify's templating language). A Shopify store's functionality relies heavily on the theme it uses but can be extended with custom coding or by integrating with third-party apps.

Where to Find Shopify Themes

If you're a merchant or a developer in search of a theme, the best place to start is the Shopify Theme Store. The Theme Store has a large number of high-quality themes built by skilled developers and designers — all of which meet strict requirements.

Searching for Shopify themes on third-party sites may lead to lower quality themes, as these sites often don't maintain the same rigorous quality standards as the Theme Store. Additionally, there's a potential risk of coming across pirated themes, which not only result in a lack of reliable support but also prevent you from getting free updates. For the best themes, stick to the Shopify Theme Store when selecting themes.

However, the Shopify Theme Store primarily caters to merchants and does not effectively highlight themes that are particularly suitable for developers. To find developer-friendly themes, you'll need to dig a little deeper. Your best bet is to browse through the Theme Store and carefully examine the documentation provided by the theme developers. Begin by searching for development-specific guides or documentation related to theme customization. Additionally, consider reviewing documentation that covers the theme's general tech stack. For example, if your team is already comfortable working with Tailwind then it would be best to find a theme that uses that.

Why Use a Pre-Built Theme for Custom Projects

You might be wondering why you should use a pre-built theme for Shopify development project. While it's entirely possible to build a theme from scratch, and there are some advantages to doing so, in most cases, starting with a solid foundation makes the most sense. Our agency has experience with both approaches. We've found that beginning with a pre-built theme almost always offers us better results.

Using a pre-built theme for custom design or development projects has two main benefits:

Time-saving: Building a theme from scratch can be time-consuming. A pre-built theme provides a solid foundation that you can build upon, allowing you to focus on customizing your store's appearance and functionality without worrying about developing all the core features.
Consistent performance and functionality: Pre-built themes are tested and optimized for performance. They also meet the theme store requirements, ensuring that your custom project will be compatible with all core Shopify features.

Benefits of Using Paper

Paper is a developer-friendly Shopify theme that offers several unique features, making it an excellent choice for any custom Shopify project.

getting ready to submit our next theme update pic.twitter.com/pnUD6qPPMG
— Thomas (@kimurathomas) March 30, 2023

Fast and reliable: Paper is built using the latest browser-supported features, ensuring that your store loads quickly and runs smoothly. We even utilize instant.page to preload pages, further enhancing speed.
Works with JavaScript disabled: Paper is designed to function even if JavaScript is disabled, providing excellent fallbacks for core functionality.
Easily extendable: Paper's modular approach makes it simple to extend and customize the theme. It employs Tailwind CSS for effortless styling and Alpine.js for lightweight interactivity.
Meets all standards for the Shopify theme store: Paper adheres to all the requirements for the Shopify theme store, ensuring that your store remains compliant and accessible.

Paper offers a robust foundation for developers to build and customize, thanks to its approach to theme styling and JavaScript functionality. With styling powered by Tailwind, developers can leverage the comprehensive Tailwind documentation to understand the CSS classes used in Paper. If you're familiar with Tailwind, you'll appreciate the efficiency and consistency it brings to CSS development. We've all seen how messy CSS files can get when working with multiple teams on undocumented CSS code.

We've taken a similar approach when it comes to JavaScript (making it easy for developers to use):

Public source files: All source files are open-source and publicly available in our toolkit. Which makes it that much easier to implement changes to site-wide functionality.
Section specific JavaScript: To facilitate smaller tweaks and adjustments, all section and template-specific JavaScript is housed within individual section files. This organization allows for targeted modifications without affecting the overall functionality.
Alpine integration: Paper utilizes the Alpine.js framework, enabling developers to make changes to simple functionality with ease through Alpine attributes. This integration makes it even more convenient to customize and enhance your Shopify store.

Using the Paper Toolkit

If you're planning to use Paper as the foundation for a custom Shopify project, you'll want to take advantage of the Paper Toolkit. The Toolkit is designed to help you extend and customize Paper in various ways, such as:

Accessing and modifying the source code
Compiling new JavaScript/CSS assets
Running Tailwind to effortlessly customize theme styles
Enjoying a seamless setup and smooth development previews

To get started with the Paper Toolkit follow the setup guide on GitHub.

The toolkit uses the Shopify Vite Plugin and generates a assets snippet that includes <script> and <link> tags, and all the liquid logic needed to load your assets.

During development, the assets snippet will load your assets from the Vite development server and inject the Vite client to enable Hot Module Replacement. In build mode, the snippet will load your compiled and versioned assets, including any imported CSS, and use the asset_url filter to serve your assets from the Shopify content delivery network (CDN).

Making Basic Customizations to Paper

Customizing layout

In Paper, Tailwind CSS plays a significant role in shaping the layout. Two common approaches have been predominantly employed for layout styling throughout the theme: Grid and Flexbox. By identifying and modifying the associated classes, you can easily customize and enhance the layout.

The grid layout in Tailwind CSS offers a powerful way to create complex, responsive designs. It's based on the CSS Grid Layout module and allows you to create two-dimensional layouts with ease. Here are some steps to edit your Paper Shopify theme using the grid approach:

Identify the grid container: Look for the element with the grid class in your theme's HTML code. This will be the parent element for all grid items.
Define grid columns and rows: Use the grid-cols-* and grid-rows-* classes to specify the number of columns and rows in your grid. Replace the asterisk (*) with a number to define the desired layout.
Position grid items: Assign the col-start-*, col-end-*, row-start-*, and row-end-* classes to your grid items to control their position in the grid. You can also use col-span-* and row-span-* to control how many columns or rows a grid item should span.
Make your grid responsive: Use Tailwind's responsive utilities like md:grid-cols-* to adapt your grid layout for different screen sizes.

Flexbox is another powerful layout system in Tailwind CSS that makes it easy to create one-dimensional layouts. Follow these steps to edit your Paper Shopify theme using the flexbox approach:

Identify the flex container: Look for the element with the flex class in your theme's HTML code. This will be the parent element for all flex items.
Control the direction of flex items: Use the flex-row or flex-col class to define the direction in which your flex items should be displayed. Add reverse to reverse the order of the items.
Align and justify flex items: Utilize the items-* and justify-* classes to align and justify your flex items within the container. Replace the asterisk (*) with keywords like start, center, end, stretch, or baseline for alignment, and start, center, end, between, or around for justification.
Set the width of a column: To set the width of a flex item, use the w-* class and replace the asterisk (*) with a value. For example, use w-1/2 for 50% width, w-1/3 for 33.33% width, or w-full for 100% width. You can also use fixed-width classes like w-64 for a 16rem width or responsive utilities like md:w-1/2 to set the width based on screen sizes.
Make your flexbox responsive: Apply Tailwind's responsive utilities like md:flex-row to adapt your flexbox layout for different screen sizes.

Installing custom fonts

Prepare your font files:
- First, ensure you have a valid license for the font you want to install.
- Download your font in webfont file types, such as .woff2 or .woff.
- If you don't have a webfont version of your font, you can use a generator like Font Squirrel's tool to convert it.
Upload font files to your store:
- With your webfont files ready, upload them to your Shopify admin.
  1. Open your Shopify admin and navigate to Settings > Files (or Content > Files).
  2. Upload each file for your font.
Edit theme code:
1. Launch the theme editor and open theme__styles.liquid from the snippets folder.
2. Insert the following code after the {% style %} tag. Replace MY_FONT with your font name and ensure the URLs correctly link to your uploaded font.
  
  @font-face { font-family: "MY_FONT"; src: url('{{ "MY_FONT.woff2" | file_url }}') format("woff2"), url('{{ "MY_FONT.woff" | file_url }}') format("woff"); }
Update the code inside the same file to include your font. The variables -type-font-body-family, -type-font-header-family, and -type-font-nav-family control the font family used for body, headings, and navigation text.

Custom colors and gradients

The Paper theme provides a flexible color selection approach, allowing developers to easily modify and add new colors to the theme. Here's how you can update and change colors in the Paper theme:

Locate the color selection code: Search for the color selection code in your theme's schema file. The provided code example shows a select element with various color scheme options.
Update or add a new color option: To change an existing color, replace the value of the value attribute with a new Tailwind CSS color class, such as bg-sky-500 for Sky 500. Update the label attribute accordingly, for example, "Sky 500".

To add a new color option, copy one of the existing options, and modify its value and label attributes to reflect the desired color.
Customize colors for each section: Each section of the Paper theme has its custom color settings. Browse through the schema to find where you can customize colors for specific sections.

Custom animations

In the Paper theme, animations are controlled using a combination of JavaScript and CSS classes. To customize animations, you will need to understand the following key components:

js:animation class: This class is used to signal JavaScript to replace classes, creating an animation effect when a section scrolls into view.
data-delay attribute: This attribute sets the delay (in milliseconds) before the animation starts.
data-replace attribute: This attribute specifies which classes to swap in and out, thereby controlling the animation's appearance.

Here's a step-by-step guide on customizing animations in the Paper Shopify theme:

Identify the element you want to animate: Locate the HTML element you wish to apply the animation to.
Apply the js:animation class: Add the js:animation class to the target element. This class informs the JavaScript code to replace the specified classes when the section scrolls into view.
Set the initial state and duration of the animation: For example, you could set the initial state of the target element to be invisible using, opacity-0. The animation-300 class determines the duration of the animation, in this case, 300 milliseconds.
Configure the data-delay attribute: Add the data-delay attribute to the target element and set its value (in milliseconds) to control the delay before the animation starts.
Configure the data-replace attribute: Add the data-replace attribute to the target element, specifying which classes to swap in and out. For example, 'opacity-0' : 'opacity-100' causes the element to transition from invisible (opacity-0) to fully visible (opacity-100).

Adding a Component from Tailwind Components

Tailwind CSS has gained significant popularity in recent years, which is excellent because it offers numerous component libraries to choose from. While you can definitely build your own components from scratch, using a library demonstrates how quickly you can extend Paper. Let's say we're fond of one of the Tailwind UI components - the 3-column layout with illustrations, for example. Here's how we can quickly incorporate this into a Shopify section:

Copy the HTML code for the component.
In your Paper theme, create a new section file (e.g., columns.liquid).
Paste the HTML code into the new section file.
That's it - you can now use the section in your theme editor.

From here, you'd likely want to connect the schema settings to adjust the content, but that shouldn't take too long, especially if you ask GPT-4 nicely.

More Resources For You

If you want more resources for customizing Paper here's some stuff to checkout.

Thomas Kimura
Founder, Brickspace Lab Thomas is the founder of Brickspace Lab, a Canadian-based digital agency that specializes in the design and development of Shopify themes. Thomas has worked with hundreds of Shopify clients and has spent many years in the depths of ecommerce.