agentleFS
itsmylife44itsmylife44/shopify-theme-builder/.claude/skills/theme-tooling/SKILL.md

theme-tooling

Skill1 starsChanged 55 days agoMITView on GitHub

Theme Check, `theme dev` and Section Catalog conventions for this repo. Use when validating a theme with Theme Check, previewing with `shopify theme dev`, or writing or reviewing a Section Catalog section.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run npm run check:theme (Theme Check on the example Theme, one line per offense as file:line severity check: message).

    line 16
  2. Very specific:

    Run shopify theme dev --path <dir> --store <shop>.myshopify.com and open the printed http://127.0.0.1:9292 link.

    line 25
  3. Distinctive:

    When the Studio copies a catalog section into a Theme that lacks some Base Theme keys, it adds them in English to every locale file, so …

    line 32
  4. Distinctive:

    Every catalog section follows all of these:

    line 36
  5. Very specific:

    Native placeholders: When an image, video, product or collection is blank, render Shopify's placeholder: {{ 'image' | placeholder_svg_tag: …

    line 49

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Theme tooling

The product skill lives in skills/shopify-theme-builder/, the only folder npx skills add installs; the folder paths below (base-theme/, catalog/, studio/) are inside it. Run npm scripts from the repo root, and the shell commands below from skills/shopify-theme-builder/.

Two folders form every Theme: base-theme/ (Shopify's Skeleton, vendored under its own LICENSE.md; provenance in base-theme/PROVENANCE.md) and catalog/ (the Section Catalog, laid out like a theme: catalog/sections/<name>.liquid). An example Theme is base-theme/ with catalog/ copied on top.

The Studio composes only the home, product and collection pages. Every other JSON template (page, password) uses the Base Theme's own section, a basic layout built from the .basic-page classes in base-theme/assets/critical.css with a color scheme setting, so it follows the Brand. The generic page's page section sets its title and content in one centered --width-prose column. The contact page is the exception: catalog/templates/page.contact.json shows the catalog's contact-form alone (enabled only on page templates; the page's title as its heading, the page's content as an intro, and a centered, split-with-details or with-an-image layout), and the product skill copies both into every Theme in step 3. So is the cart page: catalog/templates/cart.json uses the catalog's main-cart (enabled only on cart templates, with accelerated checkout buttons, an optional order note, discounts, the Base Theme's tax-note under the subtotal, which the _product-price block shows under the price too, and, when the free_shipping_threshold theme setting is set, how far the cart is from free shipping with a progress bar, which the shipping-note block states too; a quantity change or a removal updates the page in place through /cart/change.js with the Section Rendering API, like the drawer, announced in a role="status" region after the section, so its Update button sits in a <noscript>; an empty cart shows four products of its empty_collection, all products by default, which the drawer hides; a stacked or summary-sidebar layout, the note and the checkout buttons outside the items <form> joined to it by form=, so accelerated checkout buttons sit in the summary but in no form), also copied in step 3. With the Cart type theme setting on drawer (the default), the header's <cart-drawer> shows the same main-cart in a <dialog>, fetched through the Section Rendering API (/cart?section_id=main-cart, or sections in the /cart/add.js and /cart/change.js responses); main-product and featured-product hand their add to cart to it, and post to /cart/add as before when there is none. After an add or a quantity change, a visually hidden role="status" region in the drawer announces "Cart updated, subtotal X" (cart.updated, from the data-status of main-cart), and after a variant change the main product's own region, outside the <product-info> it re-renders, announces the new price and availability (product.variant_status). Product cards (the Base Theme's product-card snippet, in featured-collection, main-collection, main-search and related-products, behind a show_quick_add setting) hand it their quick add too: a product without variants posts its one variant, and one with variants opens the catalog's quick-add section in a <dialog>, fetched through the Section Rendering API (<product url>?section_id=quick-add; enabled only in the header group, with no preset, so neither the Studio nor the Theme Editor offers it; its script and styles live in the header, since a section fetched that way loads neither on the card's page), also copied in step 3. And the search page: catalog/templates/search.json uses the catalog's main-search (enabled only on search templates, with the same filters and sorting as the collection page, and results for products, articles and pages; when nothing is found, search tips and the products of its no_results_collection under a heading, or the shop's collections when none is set), also copied in step 3. Both pages' filters sit in a <facet-filters> element: below 750px one "Filter and sort" button opens them in a <dialog> drawer that closes with "Show N results", and on every width a change fetches the section through the Section Rendering API (?section_id=) and swaps its data-facets-part regions (the form, the role="status" count, the chips, the results), updating the URL and keeping focus; without JavaScript the form submits with its Apply button. And the blog page: catalog/templates/blog.json uses the catalog's main-blog (enabled only on blog templates, with tag links, pagination and a grid, list or featured-first layout), also copied in step 3. And the article page: catalog/templates/article.json uses the catalog's main-article (enabled only on article templates, with tag links and, when the blog allows them, paginated comments and a comment form), also copied in step 3. And the 404 page: catalog/templates/404.json uses the catalog's main-404 (enabled only on 404 templates, with the Creator's heading and text, a search form and a link back to the shop, and a centered, split-with-an-image, with-suggestions or big-number layout), also copied in step 3. And the collections list page: catalog/templates/list-collections.json uses the catalog's main-list-collections (enabled only on list-collections templates, with collection cards sorted alphabetically or by date, and pagination), also copied in step 3. The header's search box fetches its suggestions from the catalog's predictive-search section through /search/suggest (enabled only in the header group, with no preset, so neither the Studio nor the Theme Editor offers it), also copied in step 3. There are no customers/* templates: the header links to Shopify's new customer accounts, which need none, so a shop still on classic customer accounts gets no account pages. The catalog files every new Theme starts with are listed once, in starterFiles in studio/server/create-theme.mjs, which the product skill's create-theme command (studio/bin/create-theme.mjs) copies in step 3 and the tests read: add a new starter page's section and template there.

Validate

Run npm run check:theme (Theme Check on the example Theme, one line per offense as file:line severity check: message). Done means it exits 0: zero errors, the same gate CI applies. To check a scratch section, pass a folder laid out like catalog/: node scripts/check-theme.mjs <dir>.

Preview with theme dev

shopify theme dev needs the Shopify CLI (Node ≥ 22.12), a login, and a store (a free development store works). It serves the theme from a folder and hot-reloads files saved there by any process: CLI 4.8.0 watches the folder with chokidar, which reports OS file events whoever writes the file (checked on 2026-09-22 with CLI 4.8.0 against a development store: a file written by another process was synced within a second, Synced » update sections/hello-world.liquid, and the rendered page showed it). A write by the Studio or an agent reaches the preview the same way as a save in an editor.

The Studio runs theme dev itself (npm run studio -- --theme <dir> --store <shop>.myshopify.com --store-password <password>) and shows its status and link. --store is required, so theme dev never falls back to the store the CLI used last (shopify store create dev --demo-data makes a free development store with sample products). Development stores always have a storefront password (Shopify admin › Online Store › Preferences), and theme dev can't ask for it from the Studio; the Studio passes it through SHOPIFY_FLAG_STORE_PASSWORD. Give each Theme its own store: the CLI keeps one development theme per store per machine, so two theme dev runs on one store overwrite each other. The Studio reads its status and link from the CLI's output (studio/server/preview.mjs), so it needs Shopify CLI 4.8.0 or newer (the version that output was checked against). On first run the CLI prints a login link in the Studio's terminal and waits; the Studio shows "Login required" until the preview starts. With CI set the CLI can't log in and stops: run shopify auth login, then start the Studio again.

  1. Assemble a Theme folder: mkdir -p <dir> && cp -R base-theme/. catalog/. <dir>
  2. Run shopify theme dev --path <dir> --store <shop>.myshopify.com and open the printed http://127.0.0.1:9292 link.
  3. Edit the section in catalog/, then copy that file into <dir> again: the folder is a copy, and edits made there stay there.

Shop language

A Theme ships English as its default locale: locales/en.default.json (storefront text) and locales/en.default.schema.json (Theme Editor labels). When the shop's language isn't English, the product skill adds locales/<code>.json and locales/<code>.schema.json (the convention is in the product skill's SKILL.md, step 3.3). Theme Check's MatchingTranslations fails on a key missing from, or added to, the shop's language file.

When the Studio copies a catalog section into a Theme that lacks some Base Theme keys, it adds them in English to every locale file, so Theme Check keeps passing; translate them afterwards. In this repo, add new keys only to base-theme/locales/en.default.json.

Section Catalog conventions

Every catalog section follows all of these:

  • Description. The file starts with a one-sentence description, {% comment %}Customer quotes in a grid.{% endcomment %}, which the Studio shows in its section picker. ({% doc %} fails Theme Check in sections.)
  • Self-contained. One file in catalog/sections/, depending only on what base-theme/ ships. A section may render a Base Theme snippet, like product-card; when the Studio copies a catalog section into a Theme that lacks a Base Theme snippet, it copies the snippet too. Themes copy sections once; afterwards the copy belongs to the Theme.
  • Brand only through settings. Use the Base Theme's Brand, never hardcoded colors or fonts: the color_schemes group in config/settings_schema.json and the CSS variables snippets/css-variables.liquid sets from it (--color-background, --color-foreground, --color-button, --color-button-label, --color-accent, --color-border, --font-heading--*, --font-body--*, --font-accent--*). Headings pick up the heading font, weight, case and letter spacing from assets/critical.css; a price takes the shared price class, which sets tabular figures and, with text-label, the accent font. Text sizes and line heights come from the type scale (--font-size-*, --line-height-* in snippets/css-variables.liquid): a heading takes its size from its level, and a shared class from assets/critical.css (text-display, text-h1 to text-h6, text-body, text-small, text-label) gives any element another step. h1 to h3 and text-display wrap whole words in balanced lines (overflow-wrap: normal; text-wrap: balance), and display type has its own mobile size (type_display_size_mobile). A section never sets a font-size or line-height of its own; the Section Catalog tests fail on one.
  • Style system. Sections use the style system's variables from snippets/css-variables.liquid, never raw design values: padding, margins and gaps take a step of the spacing scale (--space-2xs 0.25rem, --space-xs, --space-sm, --space-md 1rem, --space-lg, --space-xl, --space-2xl 3rem), a section pads its top with --section-spacing-start and its bottom with --section-spacing (padding-block: var(--section-spacing-start) var(--section-spacing)) and spaces a grid of items with --grid-gap (gap: var(--grid-row-gap) var(--grid-gap) for cards with text below), both set by the density the Merchant picks, content widths are --width-narrow (forms), --width-text (text beside media) or --width-prose (running text, 70ch), touch targets are min-inline-size and min-block-size of var(--target-size) (44px: icon buttons like menu and close, variant options) or var(--target-size-min) (24px: any other icon control, a menu link, a label around a checkbox; assets/critical.css already gives buttons, summaries, selects and fields theirs), borders are var(--border-width) solid var(--color-border), inputs and selects included (--color-border-subtle for dividers), links in the Merchant's running text sit in a wrapper with the shared rte class and a sale price in a price__sale span, both in the scheme's --color-accent, corners take the radius of the shape family the Merchant picks (--button-radius for buttons, --style-border-radius-inputs for inputs, selects and option pickers, --style-border-radius-cards for cards, --style-border-radius-media for contained images and videos, --style-border-radius-badges for badges, tags and filter chips; full-bleed media stays square), so a section never sets a border-radius of its own, a product image (product card, product page, featured product, quick add, predictive search, and collection images, which show a product's when the collection has none) sits in a box with background-color: var(--media-background) (the media tint) and takes padding: var(--media-inset), object-fit: var(--media-fit) and mix-blend-mode: var(--media-blend) (the media treatment the Merchant picks: cropped to fill its box, or framed whole; thumbnails skip the inset), while every other image or video poster always covers its box with object-fit: cover and none of the --media-* variables (the Section Catalog tests pin which sections use them), muted text color: var(--color-foreground-muted) (the scheme's text mixed toward its background only as far as 4.5:1 allows, never an opacity, which drops below it), faded controls (a thumbnail not shown, an option not available) opacity: var(--opacity-muted) and disabled controls var(--opacity-disabled). assets/critical.css shares the focus ring (also on the label after a visually-hidden input), the visually-hidden class and the tint of Shopify's placeholders (give placeholder_svg_tag the placeholder class), so a section declares none of them. Layouts switch at the one breakpoint, @media (min-width: 750px) or (max-width: 749px). The Section Catalog tests fail on a raw rem, px or clamp() in a padding, margin, gap, border, radius, outline or max-width outside their short allow-list, and on a raw opacity; sizes of one component, like an icon or a thumbnail, stay raw.
  • Buttons. Every button with a text label, every submit input and every link styled as a button uses the shared class from assets/critical.css: button (primary) or button--secondary. Padding, radius, border, case, weight and colors come from the --button-* and --color-(primary-|secondary-)button* variables (the theme settings make the primary button filled or an outline), and so do their hover and pressed states: --color-button-hover* and --color-secondary-button-hover, derived from the scheme with color-mix(in oklch, …), eased over --motion-duration, with scale: 0.98 when pressed, Shopify's unbranded Buy it now included; a section's own rule for a button only lays it out (width, align-self, margins). Shop's branded buttons keep Shop's own styles, like the footer's Follow on Shop button ({{ shop | login_button: action: 'follow' }}, behind show_follow_on_shop), which the Theme Store forbids restyling. Icon controls (close, menu, arrows) stay bare, and so do the choices of a disclosure list (a <button class="<section>__disclosure-option">, like each country and language in the header's and footer's selectors, which submit the localization form from a <details> instead of a select that submits on change). The Section Catalog tests fail on a labelled button without the class and on button colors in a section's stylesheet.
  • Images. Every image_tag passes sizes and keeps the width and height it adds; images in a grid sit in a fixed aspect-ratio box with object-fit, so mixed ratios keep rows even. A section with images never hard-codes their ratio: it has an image_ratio select (t:labels.image_ratio; card, the default, portrait, square, landscape, natural, labelled t:options.image_ratio.<value>), its outer element sets style="--image-ratio: {% render 'image-ratio', ratio: section.settings.image_ratio %};" (the Base Theme snippet: the card ratio, 4 / 5, 1 / 1, 4 / 3 or auto), and each image box takes aspect-ratio: var(--image-ratio), so a page follows the card ratio unless the Merchant picks another; a video, a 3D model or a small icon keeps its own. The hero and each slide also take an image_mobile, the phone <source> (media="(max-width: 749px)", sizes="100vw", its own width and height) of a <picture> whose <img> stays the main image, which a mobile image alone stands in for. The first viewport image (the first image of a section a page can open with, at section.index == 1: the hero, the first slide, image with text, editorial split, lookbook, the first collection of a collection list; the product page's main image) is eager with fetchpriority: 'high' and has no entrance animation, and those sections' heading is then the page's h1 (assign heading_tag = 'h1', h2 otherwise, with a text-* class that keeps its size); other images take loading: 'lazy' (a hero or first slide in the page's first three sections stays eager). The product-card snippet takes a loading parameter, lazy by default: the collection and search pages pass eager for their first row (forloop.index <= section.settings.columns). The Section Catalog tests check all of it.
  • Motion. A section adds no entrance animation of its own: assets/reveal.js (loaded by the layout unless the Merchant's motion setting is none) fades in, as it scrolls into view, each section out of view on load whose outer element carries {% if section.settings.reveal %} data-reveal{% endif %}. Every band section on a home has that reveal checkbox (t:labels.reveal), on by default for image-led sections and off for type-led ones (the tests list both); the sections a page opens with (main-*, the contact form), the groups and custom Liquid have none. A grid of cards carries data-reveal-stagger, so its items fade in 60ms (--motion-stagger) after each other. A transition takes its duration and easing from the motion variables in snippets/css-variables.liquid (--motion-duration for hovers, 0.2s or 0.25s; --motion-duration-reveal, 0.6s or 0.8s, with --motion-easing-enter for what enters; --motion-duration-zoom for a card image zoom; --motion-easing), which reduced motion sets to nothing, and sits in @media (prefers-reduced-motion: no-preference). With expressive motion the hero's and the shown slide's images slowly zoom to --motion-hero-zoom (1.06) over --motion-duration-hero-zoom (8s), a scale transition from an @starting-style, not an animation, so the first viewport image still has no entrance animation. Anything that moves or changes on its own for more than 5 seconds (a rotating announcement bar, a slideshow on autoplay, a marquee) has a pause control customers can press, not only a pause on hover or focus (WCAG 2.2.2): a --target-size-min button with a translated label that says what pressing does next, like the slideshow's and the announcement bar's, or the marquee's checkbox. The slideshow follows the ARIA carousel pattern: its pause button comes first, before the arrows and the slides (the controls still show below them), and its track is an aria-live region, polite except while it rotates on its own. Under reduced motion, and when the Merchant's motion setting is none, the slideshow doesn't autoplay, the hero's video doesn't play until pressed (its <hero-video> starts it only otherwise) and the marquee doesn't move; the announcement bar's rotation, which carries the shop's messages, stops after one full cycle there and when the Merchant's motion setting is none.
  • Product cards. A section that lists products renders each with {% render 'product-card', product: product, show_quick_add: section.settings.show_quick_add, anatomy: section.settings.card_anatomy %} (or placeholder: <1 to 6> for an example card, with the same anatomy), the Base Theme snippet documented by its LiquidDoc header, and keeps only the grid's layout. A section that lists a collection's products also passes collection: it, so the card links to the product within that collection (| within: collection) and the product page's breadcrumbs lead back to it. Its card_anatomy select (theme default, minimal, detailed, editorial) lets the section override the theme's Card anatomy setting. The .product-card classes in assets/critical.css style it from the --card-* variables (image ratio, text alignment, border width, padding, background, hover zoom) and its image from the --media-* ones, so a section declares no card styles of its own.
  • Direction-safe CSS. Use logical properties (margin-inline, padding-inline, inset-inline-start, text-align: start), never left or right: the layouts set dir from the locale, so a shop in Arabic or Hebrew mirrors. A text_alignment setting maps left/right to start/end (| replace: 'left', 'start' | replace: 'right', 'end'). The Section Catalog tests fail on a physical property.
  • Section spacing. Every section that is a band of the page (not a bar, the header, a fetched dialog or custom Liquid) has a spacing select (t:labels.section_spacing; none, tight, theme, the default, loose, labelled t:options.spacing.<value>) and its outer element carries data-spacing="{{ section.settings.spacing }}", which assets/critical.css turns into 0, 0.5, 1 or 1.5 × --section-spacing-theme (the density's). A section after one on the same color scheme drops its top padding (--section-spacing-start is 0, set per scheme in snippets/css-variables.liquid), unless that one ends in media, marked with the media-edge class (the hero, the slideshow, full-bleed image with text, whose spacing pads their content inside the media and keeps var(--section-spacing)), or has none. The Section Catalog tests check all of it.
  • Per-section color scheme. The schema has {"type": "color_scheme", "id": "color_scheme", "label": "t:labels.color_scheme", "default": "scheme-1"} and the outer element carries class="color-{{ section.settings.color_scheme }}", which sets the scheme's background, text color and color variables.
  • Native placeholders. When an image, video, product or collection is blank, render Shopify's placeholder: {{ 'image' | placeholder_svg_tag: 'placeholder' }}, 'product-1' to 'product-6' for product cards, 'collection-1' to 'collection-6' for collections, 'lifestyle-1'/'lifestyle-2' for hero media. An empty development store should still look like a shop.
  • Presets. Give the schema a presets entry, so the Creator can add the section in the Theme Editor, and one named preset per layout variant, like Hero: split (general.<section>_<variant> in base-theme/locales/en.default.schema.json). The Studio's section picker draws each preset from a one-line wireframe description in studio/src/wireframes.mjs (its grammar is at the top of the file): add one for each new preset, drawing as many items as it adds blocks. A preset whose section has other presets also gets a description in its wireframes.mjs entry (not in the schema), shown under its name in the picker: one line of 60 characters or fewer saying what the layout looks like, not what its settings are called (Image on one side, text on the other). test/wireframes.test.ts fails on a preset without a wireframe, or without a description when it has siblings. Group sections (enabled_on.groups) need none, since the Studio never adds them.
  • Group sections. A section that belongs in a section group, like header and footer, sets "enabled_on": {"groups": ["header"]} (or ["footer"]), so the Studio leaves it out of the sections it adds to pages. A section a page shows once, like the header, also sets "limit": 1: its preset lets the Merchant add it back after removing it, and the limit stops a second copy in the group. The group file places it (sections/header-group.json, sections/footer-group.json); when the Base Theme's group file sets settings or blocks the catalog section doesn't have, ship a replacement group file next to it in catalog/sections/ (the footer does; the header group also places the announcement-bar above the header).
  • Page sections. A section that needs a page's object, like product for the main product and related products or collection for the collection product grid, sets "enabled_on": {"templates": ["product"]} (or ["collection"]), so the Studio offers it only for that page. A section a page shows once, like the main product or the collection product grid, sets "limit": 1; the Studio refuses to add more than the limit.
  • Form fields. Every input, select and textarea (hidden inputs and submit buttons aside) has an id, unique on the page (built from section.id, a form id or forloop.index), and a <label for> that id, wrapping the field or next to it; where the design shows no label, like a search box or the newsletter email, the label takes the visually-hidden class. A placeholder or an aria-label alone is not a label (Theme Store requirement). Fields take autocomplete where it applies (email, name). The Section Catalog tests fail on a field without a matching label.
  • Storefront text. Text the Creator writes is a section setting with a default (headings, button labels). Fixed text like accessible labels and form messages uses {{ 'key' | t }} with its key added to base-theme/locales/en.default.json. When the Studio copies a catalog section into a Theme, it also adds any Base Theme locale keys (in English, to every locale file) and theme settings the Theme lacks, so a Theme made from an older Base Theme still passes Theme Check.
  • Theme Editor text. Every name, label, info and content in the schema is a t: key in base-theme/locales/en.default.schema.json, never literal text, so the shop's language can translate the Theme Editor. Reuse an existing key when the English text matches; otherwise add one in the Base Theme's groups: general.<text> for section, block, preset and header names, labels.<text> for setting labels, options.<setting>.<value> for select options, info.<section>_<setting> for help text. Theme Check's ValidSchemaTranslations fails on a key the locale lacks. Setting defaults (headings, button labels) stay literal: they are the Creator's content.
  • Theme blocks. A theme block a catalog section takes, like _product-title, _product-price, _variant-picker, size-guide, _buy-buttons, custom-liquid, shipping-note and collapsible-content in main-product, lives in base-theme/blocks/, so every Theme has it; the section lists its type in blocks and renders it with {% content_for 'blocks' %}, which also renders app blocks, in the order the Merchant sets. When the Studio copies a catalog section into a Theme that lacks a Base Theme block, it copies the block too. A section starts with the blocks its first preset lists (the main product starts with its title, price, variant picker, buy buttons, a shipping note and collapsible description, materials, care and shipping); the Studio then adds the section's own blocks and the theme blocks it lists, a private one like _product-title at most once unless its schema sets a limit, and every public theme block for a section that takes @theme. Collapsible content is a native <details>, open on desktop and collapsed on mobile, never tabs.
  • Shopify limits. A template holds at most 25 sections; a section at most 50 blocks (keep max_blocks ≤ 50); a Liquid file at most 256 KB.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.