Building a theme for a firm's website

A theme decides how a firm's public website looks: the home page and the firm's other pages, the practice area pages, the blog, the client portal's sign-in and invitation pages, and the frame around the portal's account pages. Themes are written in Liquid (the template language Shopify uses) with HTML, CSS and a little JavaScript, and they're organised like a Shopify Online Store 2.0 theme: templates made of sections, sections made of blocks, all customisable in the theme editor without touching code.

Every firm starts on the Counsel theme. The starter kit is Counsel as a project you can change.

These guides are for developers. Firm staff who only want to change colours, text or sections can do that in the theme editor: see the help center's website articles.

Three ways to work#

The guide#

1. Getting started

1. Quick start: install the CLI, create a token, start a live preview and ship your theme.
2. Theme structure: folders, required files, theme.json, file rules and limits.

2. Building a theme

1. Templates and sections: which pages a theme renders, section schemas, blocks, presets and snippets.
2. Settings: theme-wide and section settings, every setting type, colour schemes, and the platform's animation settings.
3. Styling: Tailwind CSS in the starter kit, the design tokens, and the client portal's pages.
4. Components: modal, drawer, accordion, tabs and carousel, animations, and the theme editor's events.
5. JavaScript and security: the content security policy, what scripts may do, and render limits.

3. Reference

1. Objects: every Liquid object (firm, customer, page, blog…) and its properties, with examples.
2. Liquid reference: filters, tags, forms and translations.
3. CLI reference: every command and option.
4. API reference: the REST API the CLI uses.
5. Troubleshooting: every upload error and how to fix it.

Key ideas#

• Code and content are separate. Your files (layouts, sections, snippets, CSS) are the theme's code. The JSON documents (templates/*.json, sections/*-group.json, config/settings_data.json) are its content: the firm changes them in the theme editor. A new version of your theme keeps the firm's content unless you choose to replace it.
• The firm's words live outside the theme. Page text, practice areas, team profiles, blog articles and office details are kept on the firm, not in the theme, so they survive a theme switch. Your theme reads them through objects.
• Anything you leave out falls back to the Counsel theme, file by file. A theme can be as small as a layout, a home template, a settings schema, a screenshot and a stylesheet.
• Themes are installed unpublished. Preview them, customise them, then publish when ready.

How these pages are organised#

The numbered folders are the three parts of the guide, and the number in each file name is its place in that part. The same files come in the starter kit's docs/ folder, so the links work offline too.