Theming

This page is for Twig and CSS themers. It covers the --kahunacart-* custom properties, the classes the shipped stylesheet targets, and how to choose between a variable, your own CSS, and a template override.

For the routes, templates and Twig functions behind the markup, see Storefront.

What ships

KahunaCart enqueues two files, on its own storefront routes and nowhere else:

Both are cache-busted by file mtime, so a plugin update takes effect without a hard refresh. Webhook and download responses exit before a page exists and never receive either file.

Every rule is scoped to .kahunacart, the wrapper class the shipped templates carry, so the stylesheet cannot repaint the rest of your site. Component rules wrap their outer selector in :where(), which contributes nothing to specificity, so a plain class selector in your own CSS beats most of what the plugin sets. Nothing in the file uses !important.

The stylesheet also handles :focus-visible rings on every control, tabular figures on money columns, prefers-reduced-motion, and cart tables that scroll inside themselves on a phone.

How token resolution works

The stylesheet uses internal --kc-* tokens. You never set those. Each token takes the first value that is defined, down this chain:

--kahunacart-*   your override, site or theme
      ↓
--grav-*         the theme's own design tokens, if it publishes them
      ↓
--theme-accent   a generic accent hook, for the two accent tokens only
      ↓
neutral fallback derived from --kc-fg, or an absolute colour

If your theme already defines --grav-fg, --grav-border, --grav-bg-elevated and --grav-radius-md, the storefront picks them up and you write no CSS at all.

Borders, muted text and faint fills are all derived from --kahunacart-fg with color-mix(): borders at 13% and 24%, muted text at 68%, subtle text at 60%, faint fills at 3.5%. Retarget --kahunacart-fg and the whole neutral layer moves with it.

Tokens are declared on both :root and .kahunacart, so either selector works. Use .kahunacart to restyle the storefront without touching anything else on the site.

Custom property reference

Every hook, what it paints, and what it resolves to when you leave it alone.

Override the storefront colours

Six properties usually cover the whole job.

1. Open your theme's CSS file.

2. Add the properties you want to change:

   CSSCopy

   :root {
      --kahunacart-accent: #2f7d6f;        /* hover ink, chosen-option outlines */
      --kahunacart-accent-strong: #1d5e53; /* filled: Checkout, Place order, active chip */
      --kahunacart-accent-ink: #1d5e53;    /* prices */
      --kahunacart-radius: 4px;
      --kahunacart-radius-lg: 6px;
      --kahunacart-card: #fff;             /* product cards get a real fill */
   }
   

3. Reload a storefront page.

The storefront now renders in your colours and your corner geometry. Everything you did not name still follows the page.

Support your theme's dark mode

Redefine only what changes.

1. Add a block under your theme's dark-mode selector:

   CSSCopy

   html[data-theme="dark"] {
      --kahunacart-fg: #e6e8ee;
      --kahunacart-bg: #14161c;
      --kahunacart-card: #1b1e26;
      --kahunacart-accent: #7cc9b8;
   }
   

2. Reload a storefront page in dark mode.

The neutral ramp follows the new --kahunacart-fg. You do not have to restate borders, muted text or faint fills.

Turn off the built-in stylesheet

1. Set builtin_css to false, or use the matching toggle on the General tab of the plugin's admin settings.
2. Reload a storefront page.

No stylesheet is enqueued and the kahunacart-* classes are yours to style from scratch. The switch does not turn off the option picker's script, which a theme still needs to resolve a variant.

The buy button and the option picker

partials/kahunacart-buy-button.html.twig is the partial themes include most. It always renders both of these:

• The option widgets, when the product defines axes. Each axis gets a dropdown, a row of button pills, or colour swatches, plus a <script type="application/json"> carrying the picker's data. They ship hidden.
• The plain <select name="variant_id">, which is the field the form posts.

assets/kahunacart-options.js reveals the widgets, visually hides the select, writes the resolved variant into it, and fires a change event on it. Three consequences follow:

• The form works with JavaScript off. A browser that never loads the script posts exactly what it always did.
• The POST contract is unchanged: variant_id and qty.
• A theme listening for change on the select keeps working, whichever control the customer used.

The template variables are product, variants, options and options_payload. kahunacart_product('slug') sets all four.

Colour swatches read their colour from an inline --kc-swatch custom property, set on .kahunacart-option-choice and painted by .kahunacart-option-dot. Restyling a swatch is a normal CSS rule.

Render the buy button outside the storefront routes

A quick-view modal or a product card with an inline buy form sits on a route where the script has not been enqueued for you.

1. Add the script in your template:

   TWIGCopy

   {% do assets.addJs('plugin://kahunacart/assets/kahunacart-options.js', {loading: 'defer'}) %}
   

2. If you inject the buy form after page load, call window.kahunacartOptions.start(container).

The picker is now active on that page.

Style the catalog sidebar, tree and tags

The catalog sidebar resolves through the same token chain as the rest of the storefront, so a theme that has set --kahunacart-accent and --kahunacart-fg gets the tree, the facet panel, the breadcrumb and the subcategory cards in its own colours.

The two-column layout only exists when there is a sidebar. The wrapper is not emitted on a store with no categories and no tags, so on a flat catalog these rules never apply. See Storefront. Below 40rem the layout collapses to one column with the sidebar above the listing.

The tree is <details> and <summary> with the browser's own disclosure marker, and the summary is display: list-item. ::marker is coloured from --kc-subtle. The indent is padding on the nested list rather than a margin on the item, so hover and current-page backgrounds run the full width of the rail at every depth.

Tags are not styled as category chips: a category chip goes to a place in the catalog, a tag goes to a filtered listing. If you restyle one, keep the two distinguishable.

Choose between a variable, extra CSS, and a template override

Three levels, cheapest first.

Plugin rules sit at low specificity, so a plain .kahunacart-product-card { … } in your theme wins. If you need !important, report it as a bug.

To override a template, copy the file from the plugin's templates/ into user/themes/<your-theme>/templates/ at the same relative path and edit it. The plugin appends its own directory to Twig's search path, so your theme wins. See Storefront for the full template list.

Class reference

What the stylesheet targets, grouped by page. Every class here is rendered by the shipped templates.

The --{modifier} variants on adjustments, denials, statuses and messages are all rendered whether or not the shipped stylesheet paints them, so you can branch on any of them from your own CSS. The stylesheet leaves most denial reasons looking identical.

Related

• Storefront — routes, templates and Twig functions
• Products and catalog — what the catalog pages render
• Multilanguage — what a theme needs when the store runs more than one language