# Getting started

Source: <https://docs.ictsviluppo.example/dossier/developers/getting-started/>

This guide is for developers and agencies who customize Dossier for a merchant. It explains how the theme is organized and how to change it without losing what makes it reliable: readable assets, working HTML without JavaScript, and accessible markup.

> **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](https://docs.ictsviluppo.example/dossier/services/).

Keep your changes small, write them down, and prefer the theme editor (settings, blocks, the Custom Liquid section) whenever it can do the job.

## Set up a local copy

You need [Shopify CLI](https://shopify.dev/docs/api/shopify-cli) and access to the store.

1. Duplicate the live theme in **Online Store > Themes**, so that you never work on the published one.
2. Pull the copy: `shopify theme pull --store <store>.myshopify.com`, then choose the duplicate.
3. Run `shopify theme dev --store <store>.myshopify.com` and open the local preview. Edits to files reload the page.
4. When you are done, push to the duplicate with `shopify theme push` and let the merchant review it before publishing.

## What is in the folders

Dossier uses the standard Shopify theme structure:

| Folder | Contents |
| - | - |
| `layout/` | `theme.liquid` and `password.liquid`. |
| `templates/` | One JSON template per page type, plus `gift_card.liquid`. |
| `sections/` | Sections and section groups (`g-header.json`, `g-footer.json`, `g-sidebars.json`). |
| `blocks/` | Theme blocks, shared (`gen-*`) or private to one section (`_<section>-*`). |
| `snippets/` | Reusable Liquid, grouped by prefix (`head-`, `media-`, `prod-`, `nav-`, `util-`…). |
| `assets/` | One stylesheet, `theme.css`, and one JavaScript module per component (`wc-*.js`) or shared helper (`util-*.js`). |
| `config/` | Theme settings schema and data. |
| `locales/` | Storefront texts and theme editor labels in English and 31 more languages. |

Every Liquid, CSS and JavaScript file opens with a comment that says what it does, which settings it reads and what it depends on. Snippets and blocks use `{% doc %}`, so the theme editor and Shopify’s tooling show their parameters. Read the header before changing a file.

## How CSS and JavaScript are built

The files in `assets/` are compiled, but neither minified nor bundled, so you can read and edit them directly:

- **`theme.css`** is generated with Tailwind CSS and contains only the utility classes the theme uses. A Tailwind class that the theme doesn’t already use has no rule in it: if you add new markup, write the CSS you need in a new stylesheet (see [Customizing](https://docs.ictsviluppo.example/dossier/developers/customizing)).
- **`wc-*.js`** files are ES modules, one per custom element, compiled from TypeScript. **`util-*.js`** files are shared modules, loaded through an import map, so that a theme update never serves an old cached copy.

The theme loads no external libraries and no files from third-party CDNs.

## Check your work

Before you hand the theme back:

- Run `shopify theme check`: Dossier ships without warnings, keep it that way.
- Try the pages you changed with JavaScript turned off: navigation, product options, add to cart and the cart must still work.
- Navigate them with the keyboard only, and check the focus is always visible.
- Test in a right-to-left language if the store sells in one.