shopify-section-builder

shopify-section-builder

A reusable skill that teaches an AI coding agent (Claude or Cursor) how to build clean Shopify theme sections from Figma designs — using plain CSS only, with no Tailwind build step and no Shopify CLI / local dev server.

It exists to fix a specific kind of mess: section styles crammed into shared stylesheets and piles of inline style="...". With this skill, every new section is self-contained — its own .liquid, its own scoped CSS file, its own snippets — and is verified against a preview link you deploy and share before it's called done.

What it enforces (the five rules)

1. One CSS file per section — assets/section-<name>.css, loaded only on pages that use the section. Never appended to a shared/global stylesheet.
2. No inline Figma styles — colors, spacing, type, radius live in the CSS file. The only inline <style> writes section-scoped CSS variables from theme-editor settings.
3. Scoped selectors — everything under a section-unique wrapper class so nothing leaks between sections.
4. Theme tokens first — reuse the theme's CSS variables before hardcoding Figma values; flag anything that has to be hardcoded.
5. Verify before done — diff the deployed preview (or a screenshot) against Figma at 375 / 768 / 1440; never auto-commit.

What's in here

.claude-plugin/
  plugin.json                Claude plugin manifest
  marketplace.json           Lets this repo be added as a plugin marketplace
skills/shopify-section-builder/
  SKILL.md                   The skill (read this first)
  references/                Phase-by-phase detail (setup, css-rules, anatomy, preview, …)
  examples/feature-grid/     A complete, correct reference section to copy
  scripts/validate-section.sh  Static checks before declaring done
AGENTS.md                    Universal entry point for any agent
.cursor/rules/               Cursor rule that points at the skill
scripts/push-to-github.sh    Helper to publish this repo

This one repo is three things at once: a Claude plugin (and its own marketplace), a drop-in skill, and a Cursor rule.

---

Install

In Claude — as a plugin (recommended)

Add this repo as a plugin marketplace, then install the plugin:

/plugin marketplace add HaydonPowerShopify/shopify-section-builder
/plugin install shopify-section-builder@haydonpower-shopify

That's it — Claude loads the skill and triggers it when your request matches (e.g. "build this Figma section in my theme"). Update later with /plugin marketplace update haydonpower-shopify.

In Claude — as a plain skill (no plugin)

If you'd rather not use the plugin system, copy just the skill folder into your skills directory:

git clone https://github.com/HaydonPowerShopify/shopify-section-builder /tmp/ssb
# per project (from your theme root):
mkdir -p .claude/skills && cp -R /tmp/ssb/skills/shopify-section-builder .claude/skills/
# or globally:
cp -R /tmp/ssb/skills/shopify-section-builder ~/.claude/skills/

Claude discovers the SKILL.md and triggers it on a matching request.

In Cursor

Cursor reads .cursor/rules/*.mdc and AGENTS.md. Two ways:

A) Drop the repo into your theme (keeps the rule and the skill files together so the rule's references resolve):

# from your Shopify theme root
git clone https://github.com/HaydonPowerShopify/shopify-section-builder \
  .cursor-skills/shopify-section-builder
cp -R .cursor-skills/shopify-section-builder/.cursor/rules/* .cursor/rules/

The rule is alwaysApply: false, so it activates when your prompt is about building a Shopify section, or when you reference it. The rule points at skills/shopify-section-builder/SKILL.md — keep the cloned .cursor-skills/ folder in place so those files stay reachable.

B) Reference it per chat: open this repo (or the cloned folder) in Cursor and start your message with "Follow skills/shopify-section-builder/SKILL.md — build this Figma frame as a Shopify section." Cursor reads the SKILL.md and references on demand.

Tip: whichever tool you use, paste the Figma frame link (or a screenshot) and say which page it belongs on (home / product / collection / page).

---

How a build goes (what the agent will do)

1. Setup — confirms the Figma source, your theme repo, which template to preview on, and how you'll verify.
2. Reads your theme — copies conventions from existing sections and your CSS variables file.
3. Generates the section: .liquid + one scoped .css + snippet + translation keys (+ JS only if interactive).
4. Wires a preview into a template with real sample content.
5. Asks you to deploy to an unpublished theme and share the preview URL (or a screenshot), then diffs it against Figma, runs the validator, and hands you staged files + a suggested commit message. You commit.