From a design to a reviewed theme draft EN
Bring an HTML design into CMS or Liquid without confusing preview, global styling and publication.
Use this guide when a designer or assistant brings a design into a store for review before publication. Kaduno Web is in beta. The workflow was checked against source on 13 November 2026, not executed against your store. Confirm your deployed version, permissions and configuration first.
A draft name is not a safety boundary. Applying a store-style draft changes store settings. A REST update, ordinary CLI push or Git sync targeting an active theme can change the live storefront. Work on a separate, unscheduled draft.
Choose the right surface
| What you need | Working surface | What to review |
|---|---|---|
| A content page or homepage inside the current layout | A CMS page draft | Page content together with the existing header and footer |
| Liquid sections and page templates | A separate theme draft | The complete theme, its settings and relevant templates |
| Store-wide colours, fonts or branding | Store appearance settings | A separate store-wide change, not only a page draft |
For the broader editor guide, see Kaduno Web (Norwegian). CMS publication, theme activation and global styling are separate actions.
Before you start
- Identify the store, sales channel, current active theme and homepage source. Different channels can use different themes.
- Keep a known-working copy of files and relevant appearance settings. Do not delete the previous theme as part of routine rollback preparation.
- Prefer a test store and synthetic data. A theme preview on the real domain is not an isolated environment for orders, customers or payments.
- Check permissions for the interface being used. REST theme operations use
themes:readorthemes:write; MCP follows its own authenticated role and applicable policy. One credential does not establish access through every interface. - Design import must be enabled in Settings → Appearance. It is off by default; write operations require the appropriate operator-or-higher access.
Prepare a Figma or Claude Design export
Provide HTML and CSS. A Figma URL or screenshot alone is not a ready-to-use Kaduno template; use an appropriate HTML export workflow. Check image/font rights and use full HTTPS image URLs where required. Imported scripts are not retained. Forms, login and cart behaviour must connect to Kaduno's actual features rather than being assumed to survive a visual import.
Read the import warnings. Visual similarity is not evidence that all interactions or editable settings were transferred.
Style analysis can produce a proposal without saving it. Applying that proposal
is a separate write: onboarding.applyDesignDraft with style changes the
selected store's colours and fonts. The brand scope can also change its logo and
header and requires store-admin access. Do not infer isolation from “Draft” in
the action name. Use a test store or get specific approval for the global change.
Route A: a CMS page
- Create a new draft page with
draft_from_design. - Read warnings and verify products, links, forms and editability.
- Preview desktop and narrow layouts, including the existing header and footer.
- Get approval for the exact page version and the changes intended to go live.
- Publish only through the agreed release process. Selecting a new homepage and
setting
storefront_homepage_sourcetocms_pageare additional live changes.
Creating a page draft should not replace the published homepage. Switching the
homepage source back to theme is also a live change; check the previous setup
before using that as a recovery step.
Route B: a Liquid theme
- Use
create_draftwith a new, unused slug and the correct sales channel. Confirm the copy is a draft with no scheduled activation. - Use
section_from_designwithwriteTo.draftSlug. Review generated section settings and the intended ordering intemplates/index.json. - Validate the whole theme. File validation does not prove accessibility, layout quality or checkout correctness.
- Obtain its
preview_url, check expiry and share only with intended reviewers. - Stop before
activate. Activation selects what customers see and needs a separate review and approval of that version.
section_from_design requires draft status and rejects active or scheduled themes.
The generic MCP write_files operation rejects an active theme but does not
provide the same scheduled-theme guarantee. Always inspect the actual status;
never use a scheduled theme as a supposedly isolated work copy.
Interface boundaries
A Liquid theme is a file package, including theme.manifest.json, layouts,
templates, sections, snippets, settings, assets and locales. Start from a theme
compatible with the store's features, not an arbitrary static HTML page.
| Interface | Safer review workflow | Important boundary |
|---|---|---|
| MCP | New draft → write → validate → preview → separately approved activation | The guards differ between design import and generic file writes |
| CLI | Validate, then work against an identified draft | dev creates a development draft when targeting an active theme; ordinary push to an active theme goes live |
| REST | Read status first; use a separate new draft slug | PUT replaces the file set and retains an existing theme's status; PATCH changes files in the selected theme |
| Git | Dedicated draft and controlled branch before sync | Sync replaces theme files; syncing an active theme affects customers |
| ZIP import | Check target, validation and resulting status | Import is not evidence of release approval |
A section created only in Kaduno may disappear at the next Git sync. Preserve it
in the theme repository together with its template/settings changes before
resuming sync. Do not use automatic activation or --yes as the default review
workflow.
Liquid does not automatically make arbitrary text safe HTML. Escape ordinary
product, customer, imported and settings text with escape; intentionally render
HTML only where the field contract establishes appropriate sanitisation. Theme
validation does not replace a review of escaping and scripts.
Review checklist
- Correct store, channel, language and unscheduled draft; public homepage unchanged.
- Homepage, category, product and relevant CMS pages at desktop and narrow widths.
- Empty lists, long labels, missing images and keyboard navigation.
- Relevant product, cart and B2B behaviour with agreed test data. Do not place a real order merely to test a theme.
- No credentials, private customer data or unapproved tracking scripts in files.
- Named approver has reviewed the exact version intended for activation.
Failure and recovery
Validation fails: fix the named draft file or template. Do not bypass validation or switch to editing the active theme to make a preview work.
Preview does not open: check slug, channel and expiry; obtain a new preview link if necessary. Do not activate the theme just to test it.
Git sync changes the design: compare the repository and draft, choose the working source of truth and preserve missing changes before another sync.
You need to revert: reactivating a known-working theme is another live change, not a guaranteed full-store rollback. It may not restore global appearance, CMS content or other settings. Verify the recovery scope and obtain approval; keep the previous files and settings.
Next: API credentials and safe first requests and AI permissions and approval boundaries. The Norwegian workflow is also available.