Keystone: Universal Premium Theme for WooCommerce

Overview

Keystone is Kavio Labs' universal premium block theme for WooCommerce: one modern classic design that fits every sector, with the merchandising tools of a big store. Pick one of twelve colour schemes and one of three layouts, fill the home sections with your own banners, deals and promotions, and edit any colour in the Site Editor; the whole store follows.

What you get

• 12 colour schemes (Ocean, Graphite, Emerald, Coral, Sunrise, Ruby, Teal, Indigo, Forest, Rose, Lime and the dark Midnight), every text colour checked for readable contrast. Each scheme is a Site Editor palette, so every single colour stays editable.
• 3 layouts: Market (catalog menu open next to the hero), Classic (hero slider with two side banners), Showcase (centred logo, full-width hero). Soft, sharp or round corners.
• Header and menus: top bar, sticky header, live search with products and categories, compare, wishlist and mini cart; a menu bar built from your categories with icons, labels and mega panels (columns, popular products, a banner or the best deal), a brands panel, a "More" panel, a vertical catalog menu and a phone drawer.
• Home sections in any order, each for all devices, desktop only or phones only: hero slider, promise row, category icons, product of the day with countdown and stock bar, deals that end soon, tabbed product rails, category mosaic, promotions carousel with days left, banners, brands with logos, posts with their products, customer reviews.
• Catalog: promo cells inside the product grid (banner, countdown, video, article), WooCommerce AJAX filters with active filter chips, subcategory chips or tiles, density switch, Show more or loading while scrolling, a Deals view and a phone Filter and Sort bar.
• Cards: stickers, colour swatches that switch the image, sizes, rating, hover image, quick view with options, compare, wishlist and Add to cart.
• Product pages: gallery with hover zoom and a product video, price box with the saving and the offer countdown, swatches, quantity stepper, trust block, payment chips, related products and a sticky Buy bar.
• Blog posts with attached products, Keystone visibility switches on every block, a settings page with simple tables, and the Northwire demo store (electronics) with one-click import and removal.

Pages of this documentation

Installation

Requirements

• WordPress 6.7 or newer (tested with 7.1), PHP 7.4 or newer (tested with 8.3).
• WooCommerce 10.1 or newer (tested with 11.2). The Cart and Checkout blocks and the classic cart and checkout pages are both styled. Keystone never reads or writes orders, so High-Performance Order Storage (HPOS) needs nothing extra.

Install

1. Appearance > Themes > Add New Theme > Upload Theme: choose kv-keystone-kv.zip (or the zip of your marketplace) and install it.
2. Activate Keystone.
3. Open Appearance > Keystone. On the own-site build, enter the licence key from your Kavio Labs account on the Licence tab: it switches on the theme extras (quick view, wishlist, compare, live search, promo cells, Show more, sticky bars) and the demo importer. Templates, colours, layouts and home sections work without a key.

Demo store (optional)

Appearance > Keystone > Demo store > Import the demo store adds the Northwire electronics store: 40 products (8 with colour variations), 30 categories with menu icons, labels and banners, 6 brands with logos, reviews, a product video, 4 guides with attached products, 5 pages and all the home and catalog settings. Your own products, pages and orders are never touched. Remove the demo store deletes exactly the demo items again and restores the settings you had before.

From WP-CLI: wp kv-keystone demo import, wp kv-keystone demo remove, wp kv-keystone demo status, wp kv-keystone demo scheme <name>.

Update

Upload the new zip (Upload Theme > Replace current with uploaded). Settings, colours and your Site Editor changes stay.

Configuration

Open Appearance > Keystone. Every storefront text you can change is on one of the tabs below. A section that is switched off or has no content is not shown. Images take a URL from the media library (Choose) or a theme image (theme:art-slide-1.webp); links take a full address or a path such as /shop/ or /product-category/phones/. Wrap words in *stars* to colour them (titles, the text logo).

Design

• Colour scheme: twelve cards; one click applies the scheme and keeps your other style changes. Fine-tune any colour in Appearance > Editor > Styles > Colors (Page, Surface, Headings, Text, Accent, Links, Menu bar, Top bar, Footer, Highlight, Sale badge, In stock and more).
• Layout: Market, Classic or Showcase. Corners: soft, sharp or round (pill buttons).
• Text logo: shown when the site has no logo image (Appearance > Editor > Site logo).

Header & menu

• Top bar with three messages (they rotate on phones), Phone number, Opening hours.
• Sticky header, Live search suggestions, Search placeholder.
• Menu bar: number of categories in the bar (the rest goes into More), Catalog menu on or off, its label and number of categories, Brands item label, Deals link label (every product on sale), an Extra link (empty = the posts page).

Category menu fields

On Products > Categories > Edit each category has a Keystone menu box: Menu icon (50+ icons for every kind of shop), Menu label (New, Hot, -30%) and its colour, and the Mega menu banner (image, title, text, link). Without a banner the panel shows the best deal of the category.

Home page

• Section order: hero, usp, cats, deal, tabs, mosaic, promos, banners, brands, blog, reviews.
• Every section has Show and Show on (all devices, desktop and tablet only, phones only).
• Hero slider: seconds per slide (autoplay pauses on hover, on focus and for visitors who prefer reduced motion), slides (label, title, text, image, button, link, price badge) and two side banners (Classic layout).
• Promise row, Category icons (title, category ids or slugs, number), Product of the day and deals (product id or SKU; empty = the product on sale with the biggest saving that has a sale end date; deals: ids or the products on sale ending soonest), Product tabs (title and source: best sellers, newest, on sale, featured, top rated, ids or a category).

Merchandising

• Category mosaic: tiles with title, text, image, link, size (normal, wide, tall) and colour (empty = your top categories).
• Promotions carousel: title, text, badge, image, link, end date (YYYY-MM-DD; "N days left" is shown and the card hides itself after the date) and colour.
• Banners, Brands (WooCommerce brands with their logo image), Blog, Customer reviews (average and quotes; empty = your latest 5-star product reviews). Write only real figures and quotes.

Catalog

• Pagination: Show more button, load more while scrolling, or page numbers. Subcategories: chips, tiles or hidden. Products per row: 3, 4 or 5. Filter and Sort bar on phones.
• Promo cells: category slugs (empty = every category and the shop; a category also covers its subcategories), position, size (1 or 2 cells), type (banner, countdown promo, video, article), title, text, image, button, link, end date, video (MP4/WebM from the media library or a YouTube / Vimeo link), article id (a page or post) and colour.
• Product cards: brand line, second image on hover, colour swatches and sizes, quick view, wishlist, compare, quantity stepper. Stickers: discount, new (days), best seller (top N), low stock line.

Product page

Sticky Buy bar, Hover zoom, In-stock line, Trust block (icon, title, text), Payment chips (plain text, no logos), Related products title. The product video is set per product: Product data > General > Product video.

Footer & mobile

Newsletter band (title, text, button, link), About text, Social links (Name|URL per line), Bottom bar on phones, Back to top, Free-shipping amount for the cart progress bar (empty = from your Free shipping method).

Demo store and Licence

See Installation. Reset settings puts every Keystone setting back to the defaults.

Using Keystone

Colours in the Site Editor

Keystone's colour schemes are Site Editor palettes. After choosing a scheme on Appearance > Keystone, open Appearance > Editor > Styles > Colors > Palette and change any colour: buttons, links, menu bar, top bar, footer, highlight or sale badge. Hover colours, soft tints and the hero background are derived from your colours automatically.

Sections anywhere

Every home section is also a block pattern in the inserter (category Keystone sections): Hero slider, Promise row, Category icons, Product of the day and deals, Product tabs, Category mosaic, Promotions carousel, Banners, Brands, Latest posts and Customer reviews. Place them on any page; they show the content of the theme settings. The front page template holds the whole home page in your section order; add any other block before or after it in the Site Editor.

Visibility switches

Select any block in the editor and open Keystone visibility in the sidebar: Hide on desktop (1024 px and wider), Hide on tablet (768 to 1023 px), Hide on phone (below 768 px). Hidden blocks are shown faded in the editor.

Promo cells, videos and articles

Add a cell on Appearance > Keystone > Catalog: choose the category, the place in the grid and the size. A countdown cell counts down to its end date and hides itself afterwards. A video cell opens the video in a dialog (YouTube and Vimeo use their privacy-friendly players and load only when the shopper presses play). An article cell opens a page or post in a dialog with a link to the full page.

Products in a post

On the post edit screen, the Products in this post box takes product ids or SKUs. They appear as a product rail under the post, and the post card on the home page shows the number of products.

Phones

Phones get a bottom tab bar (Home, Catalog, Search, Saved, Cart), a drawer menu with category icons, a Filter and Sort bar on category pages and a sticky Buy bar on product pages.

Developer notes

• Block theme, text domain kv-keystone, PHP namespace KavioLabs\Keystone, option kv_keystone_settings (one autoloaded array; the schema in inc/Settings.php drives defaults, sanitising and the settings page).
• Storefront parts are marker groups in templates, parts and patterns (class ks-dyn-*, for example ks-dyn-header, ks-dyn-home, ks-dyn-home-deal, ks-dyn-card, ks-dyn-pinfo); inc/Blocks.php fills them on render_block.
• The product grid is WooCommerce's Product Collection; each item renders the Keystone card (inc/Cards.php). Promo cells are inserted into the product template output (inc/Catalog.php, filter render_block_woocommerce/product-template).
• Colour tokens: --ks-* CSS variables read the theme.json palette (--wp--preset--color--*) and derive hover and tints with color-mix(). Schemes are styles/*.json palettes; inc/schemes.php is generated by tests/gen-theme-json.js.
• Category menu data: term meta kv_keystone_icon, kv_keystone_label, kv_keystone_tone, kv_keystone_banner_*. Product video: product meta _kv_keystone_video. Post products: post meta _kv_keystone_products.
• Caches: transients kv_keystone_menu, kv_keystone_deals, kv_keystone_hits, kv_keystone_brands (cleared when products, categories, brands or settings change).
• Script: assets/js/theme.js (no jQuery except the variation form events on product pages), settings in window.ksCfg; add to cart, quick view and lists use the Store API. Editor: assets/js/editor.js.
• Visibility classes: ks-hide-d, ks-hide-t, ks-hide-m (usable in any block's Additional CSS classes).
• WP-CLI: wp kv-keystone demo import|remove|status|scheme <name>|set '<json>'.
• Source tools (not shipped): tests/gen-theme-json.js, tests/gen-templates.js, tests/build-css.js, tests/demo/build-pack.js, tests/e2e.js, tests/gallery.js, tests/compose.js.

FAQ

Does Keystone work with the Cart and Checkout blocks?

Yes, and with the classic cart and checkout pages too. The theme only styles them; payment and shipping plugins keep working.

Is it compatible with HPOS?

Yes. The theme never reads or writes orders.

Where are the wishlist and compare lists saved?

In the shopper's browser (localStorage). No account, no cookie, nothing sent to the server.

Do the filters reload the page?

No. Keystone uses WooCommerce's own Product Filters block (AJAX through WooCommerce's Interactivity router) and adds your global attributes (colour first, then size) automatically.

Can I use my own colours?

Yes: pick the closest scheme, then edit any colour in Appearance > Editor > Styles > Colors.

Why does a product not show colour swatches?

Swatches use an attribute called Colour, Color, Shade or Finish. The colour comes from the term colour (WooCommerce visual attributes) or from the colour name. For variable products the card swatch switches to the variation image of that colour.

What happens without a licence key?

Basic mode: templates, colours, layouts and home sections keep working; quick view, wishlist, compare, live search, promo cells, Show more and the sticky bars are switched off. The admin is never blocked.

Does the theme load anything from other servers?

No. The font is self-hosted; YouTube or Vimeo players load only when a shopper presses play on a video you added.

Is Keystone translation ready?

Yes, with languages/kv-keystone.pot. The theme ships in English.