For developers
This page is for developers and agencies who extend Kyoto for a merchant, and for app developers who integrate with it. Code changes are outside our support (see Support policy), but we keep the names on this page stable so your work survives updates.
Before you edit code: duplicate the theme and work on the copy. Changes to theme files are not carried into a new version when the merchant updates Kyoto; they have to be made again. Where you can, use the Custom liquid section or block instead of editing files: those are saved as settings and survive updates.
How Kyoto is built
- Online Store 2.0 theme with JSON templates, section groups (header, footer, overlays) and theme blocks.
- No external JavaScript or CSS libraries. Interactive parts are Web Components, and each section, block and snippet keeps its own CSS and JavaScript.
- Progressive enhancement: products can be browsed and added to the cart without JavaScript. Every form is a real Shopify form.
- Colors, spacing, radii and motion are CSS custom properties generated from the theme settings.
- Apps are supported through app blocks (
@app) in 27 sections (listed in Apps) and through app embeds. The theme needs no app code in its files.
Stable names
The names below are part of Kyoto's public interface. We don't rename or remove them in minor or patch updates; if one ever has to change in a major version, the old name keeps working alongside the new one for two more major versions and the change is listed in the changelog. Anything not listed here (inner class names, internal attributes) may change between versions.
Classes and data attributes
| Name | What it marks |
|---|---|
.product-form, [data-product-form] | The add to cart form on product pages and in featured product sections |
.price | A price |
.product-media | The product media gallery |
.cart-line | A line in the cart page and cart drawer |
[data-cart-count] | The cart item count in the header |
[data-cart-form] | The cart form |
[data-cart-native] | Add this to a product form to stop the theme from handling its submit (the browser posts it normally) |
Form ids
| Id | Use |
|---|---|
cart-form | The cart form on the cart page and in the drawer. An input anywhere on the page with form="cart-form" is submitted with the cart (for example a custom cart attribute). |
product-form-<section id> | The product form of a section. Inputs with form="product-form-<section id>" are added as line item properties, wherever they are placed. |
JavaScript events
All events are dispatched on document.
| Event | detail | When |
|---|---|---|
variant:change | { variant, previousVariant, sectionId } | The shopper chose another variant |
cart:updated | { cart, source, item?, items? } | The cart changed. cart is the full /cart.js object. The theme's own sources start with cart-. |
cart:error | { message, status } | Adding or changing failed |
cart:refresh (listened to) | none | Dispatch it to make the theme reload the cart display, for example after your app changed the cart |
collection:updated | { url, sectionId } | The product grid was replaced after filtering, sorting or loading more |
free-shipping:reached | { context } | The free shipping minimum was reached during this visit |
store:selected | { store } | The shopper chose a store in the Store selector section |
Kyoto also dispatches and listens to Shopify's standard storefront cart events (shopify:cart:lines-update, shopify:cart:note-update, shopify:cart:attributes-update, shopify:cart:error, shopify:cart:view). When an app changes the cart and dispatches one of these, the theme refreshes the cart display.
window.themeCart
| Method | Returns |
|---|---|
add(formData, options?) | Promise<{ ok, cart?, items?, message?, status? }>. Adds items and runs the theme's after-add behavior (drawer or notification). |
change(key, quantity) | Same shape. Quantity 0 removes the line. |
update(body) | Same shape. body is { note?, attributes? }. |
refresh() | Promise<{ ok, cart? }>. Reloads the cart display. |
The methods never throw; failures come back as ok: false and as a cart:error event.
CSS custom properties
| Property | Value |
|---|---|
--theme-color-foreground | The body text color |
--theme-header-height | The height of the sticky header, for offsetting your own sticky elements |
--z-header, --z-drawer, --z-modal | The stacking levels the theme uses; place app layers relative to them |
Many sections and blocks also expose their size settings as custom properties on their root element (for example the size ruler, museum label and media stage), so a stylesheet can restyle them. Those are documented in the theme files' comments.
Adding your own CSS or JavaScript
- Small additions: add a Custom liquid section or block with a
<style>or<script>tag. It is saved with the template, survives updates and can be removed in the theme editor. - Larger changes: work in a duplicated theme and keep a list of the files you changed, so you can apply them again after an update.
Every file in Kyoto starts with a comment that explains what it does, the settings it reads and its accessibility and no-JavaScript behavior.