# Customizing

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

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](https://docs.ictsviluppo.example/dossier/developers/architecture#events-you-can-listen-to).

## 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.