shopify-section-builder

Shopify Section Builder (plain CSS, no CLI)

Build a clean, self-contained Shopify section from a Figma design. This skill is written for a workflow where:

• You do NOT have Tailwind running — there is no npm run build:css, so write plain CSS, not utility classes. (If the theme has a compiled tailwind.css, you may reuse existing utility classes that already exist in it, but never add new ones, and never rely on a build.)
• You do NOT have the Shopify CLI / a local dev server — there is no hot reload at 127.0.0.1. You preview by deploying to a Shopify theme and opening its preview URL, then sharing that link (or a screenshot) for verification.
• The existing codebase is messy — styles for many sections crammed into one file, and lots of inline style="...". This skill exists to STOP that pattern, not extend it. Every new section is an island: its own .liquid, its own assets/section-<name>.css, its own snippets.

Read the matching references/*.md for each phase instead of holding all of it in memory.

The five rules (non-negotiable)

1. One CSS file per section. All of a section's styling lives in assets/section-<name>.css, conditionally loaded from the section. Never append a section's rules to a shared/global stylesheet, and never edit another section's CSS file.
2. No inline Figma styling. Forbidden: style="color:#...;padding:24px;font-size:18px" pulled from a Figma fill. The only allowed inline <style> is a single section-scoped block that writes CSS variables driven by theme-editor settings (padding, background, color). Everything that comes from Figma goes in the CSS file. See references/css-rules.md.
3. Scope every selector under #section-{{ section.id }} (or a section-unique wrapper class) so two instances on one page never collide and styles never bleed into other sections.
4. Match Figma, don't approximate. Use the theme's existing CSS variables / classes for color, type, spacing, radius where they exist. Hardcode a literal Figma value only when no token exists — and flag it.
5. Never declare done without visual verification. No local dev server means you verify against a preview link the user deploys and shares, or a screenshot they paste. If neither is available, deliver the files with an explicit "UNVERIFIED — here is exactly how to preview" note. Never silently claim it matches Figma. And never auto-commit — stage and suggest a message.

Workflow (5 phases)

Run in order. Skipping "read the theme" is how output drifts from the codebase.

Phase 1 — Setup & inputs

Read references/setup.md. Confirm:

• Figma source available (Figma MCP mcp__figma* tools, a shared frame link, or a clear screenshot + spec). If you have nothing to build from, stop and ask.
• The theme repo root (has sections/, snippets/, assets/, templates/, locales/, config/settings_schema.json).
• Which template the section previews on (home / product / collection / page) — ask if the Figma frame name doesn't make it obvious.
• How you'll verify at the end: browser MCP + preview link, or a pasted screenshot. Decide now so Phase 5 isn't a surprise.

Phase 2 — Read the theme

Read references/theme-conventions.md, then read the actual theme — don't assume. Minimum reads:

• 2–3 existing sections/*.liquid closest to what you're building.
• The CSS variables the theme already exposes (snippets/css-variables.liquid or similar) — colors, type scale, spacing, radius, breakpoints.
• A sibling section's assets/section-*.css to copy its CSS conventions (BEM? variable names? media-query breakpoints?).
• config/settings_schema.json for color schemes and typography tokens.
• An existing templates/*.json like the one you'll preview on, for the JSON shape.

Phase 3 — Generate

Read references/section-anatomy.md (scaffold + schema) and references/css-rules.md (the CSS file). Write, at minimum:

• sections/<name>.liquid
• assets/section-<name>.css ← the one and only place section styles live
• snippets/component-<name>.liquid for any repeated card/item markup
• locales/en.default.schema.json entries for every t: label
• assets/section-<name>.js only if the section has real interactive behavior (read references/javascript.md).

Stamp the Figma source at the top so re-runs update instead of duplicate: {%- comment -%} figma:<file-key>:<node-id> {%- endcomment -%}

Phase 4 — Wire a preview

A section file renders nothing on its own. Read references/preview-and-verify.md. Add the section to the right templates/*.json with real sample content pulled from the Figma text layers (empty defaults look broken and cause false-negative diffs). Give the preview entry an obvious key like <name>-preview so it's easy to remove later.

Phase 5 — Verify against the preview link

Read references/preview-and-verify.md § Verify. Because there's no local dev server:

1. Tell the user exactly which files to deploy (e.g. push to a development / unpublished theme via the Shopify admin Edit code screen or their GitHub theme integration) and to send you the theme preview URL (or paste a screenshot).
2. When you have the link, load it with a browser MCP, hard-reload (no cache), screenshot at the Figma breakpoints (375 / 768 / 1440), and diff concretely against Figma — exact colors, paddings, radii. "Looks close" is a fail.
3. If you only get a screenshot, diff that. If you get nothing, hand off with the UNVERIFIED note and the precise preview steps.
4. Run scripts/validate-section.sh on the section. Present screenshots + the diff list + the file list, git add the files, and suggest a commit message. Don't commit.

What this skill prevents

• A new section's CSS smeared into a shared stylesheet that already styles ten other sections.
• Inline style="..." baked from Figma fills that can't be themed or overridden.
• Unscoped selectors leaking into other sections.
• Reaching for Tailwind utilities that don't exist because there's no build.
• "It's ready" with no preview ever loaded.

When this skill does NOT apply

• Whole-page templates or theme-app-extension blocks (different file shapes).
• A pure design-system atom (extract a snippet, not a section).
• No Figma and no visual spec at all — there's nothing to match.

References

File	Read when
references/setup.md	Phase 1 — every run
references/theme-conventions.md	Phase 2 — every run
references/section-anatomy.md	Phase 3 — every run
references/css-rules.md	Phase 3 — writing the CSS file
references/javascript.md	Phase 3 — only if interactive
references/preview-and-verify.md	Phases 4 & 5 — every run
references/gotchas.md	When something renders wrong

Bundled

Path	Purpose
examples/feature-grid/	A complete, conventions-correct section to copy from.
scripts/validate-section.sh	Static checks before declaring done.