Customizing

Most changes a merchant asks for don’t need code: sections, blocks, color schemes and the Custom Liquid section cover a lot. When code is the only way, these practices keep the theme readable and easier to bring forward to a new version.

Custom code

Changes to the code of Dossier are not covered by theme support, and a theme with edited code files no longer receives updates automatically. Before you edit the code, duplicate your theme in Online Store > Themes and work on the copy. Need help? Hire a Shopify Partner: ICT Sviluppo, the team behind Dossier, can do it for you.

Keep a list of every file you change: when the merchant moves to a new version of Dossier, you will need to apply your changes again.

Add your own styles

assets/theme.css is generated and contains only the utility classes the theme already uses. Don’t edit it: add your own stylesheet instead.

1. Create assets/custom.css.
2. Load it in layout/theme.liquid, right after theme.css: {{ 'custom.css' | asset_url | stylesheet_tag }}.
3. Use the theme’s CSS variables, such as var(--color-ink), var(--color-surface) and var(--font-heading), so your styles follow the color schemes and the fonts set in the theme editor.

Write logical properties (margin-inline-start, not margin-left) to keep right-to-left languages working.

Add your own JavaScript

Create a module in assets/ and load it with <script type="module"> where it is needed, or in layout/theme.liquid if it is needed on every page. Prefer a custom element, as the theme does: it starts when its tag appears in the page, also after a Section Rendering update, and it doesn’t need a global variable. To react to the theme, listen to its events.

Add a section or a block

• Name a new section section-<name> and give it a color_scheme setting applied with color-{{ section.settings.color_scheme }} on its root, like the other sections.
• Name a block shared by several sections gen-<name>, and a block for one section only _<section>-<name>, then add it to that section’s blocks list.
• Put every visible text in locales/en.default.json and every label in locales/en.default.schema.json, and translate the keys in the other locale files.
• Read alternative text from the image (image.alt), not from a setting.

What not to change

• Setting IDs and section or block types. Templates saved by the merchant refer to them: renaming one loses the merchant’s content.
• The files in assets/ generated from the theme’s sources, other than with care: they are replaced as a whole by each update of Dossier.
• The section groups’ structure: the cart drawer and the cart notification turn on by their presence in g-sidebars.json.
• Markup that keeps pages working without JavaScript: the <details> of menus and the real <form> elements of the product and the cart.

Keep the theme accessible

Dossier aims at WCAG 2.2 AA. When you add markup, keep a visible focus on everything interactive, give every control a name, keep a contrast of at least 4.5:1 for text, and respect prefers-reduced-motion for animations.