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 needWorking surfaceWhat to review
A content page or homepage inside the current layoutA CMS page draftPage content together with the existing header and footer
Liquid sections and page templatesA separate theme draftThe complete theme, its settings and relevant templates
Store-wide colours, fonts or brandingStore appearance settingsA 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:read or themes: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

  1. Create a new draft page with draft_from_design.
  2. Read warnings and verify products, links, forms and editability.
  3. Preview desktop and narrow layouts, including the existing header and footer.
  4. Get approval for the exact page version and the changes intended to go live.
  5. Publish only through the agreed release process. Selecting a new homepage and setting storefront_homepage_source to cms_page are 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

  1. Use create_draft with a new, unused slug and the correct sales channel. Confirm the copy is a draft with no scheduled activation.
  2. Use section_from_design with writeTo.draftSlug. Review generated section settings and the intended ordering in templates/index.json.
  3. Validate the whole theme. File validation does not prove accessibility, layout quality or checkout correctness.
  4. Obtain its preview_url, check expiry and share only with intended reviewers.
  5. 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.

InterfaceSafer review workflowImportant boundary
MCPNew draft → write → validate → preview → separately approved activationThe guards differ between design import and generic file writes
CLIValidate, then work against an identified draftdev creates a development draft when targeting an active theme; ordinary push to an active theme goes live
RESTRead status first; use a separate new draft slugPUT replaces the file set and retains an existing theme's status; PATCH changes files in the selected theme
GitDedicated draft and controlled branch before syncSync replaces theme files; syncing an active theme affects customers
ZIP importCheck target, validation and resulting statusImport 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.