Guide

Best Practices

Practical guidance for getting the best results from Theme Factory. How to write effective tasks, structure your work, and avoid common mistakes.

Strategy

Section-by-Section Approach

Don't try to build an entire page in one task. Theme Factory works best when each task focuses on a single section — a hero, a product carousel, a reviews block, etc. This keeps the agent focused, the validation precise, and the output reviewable.

One section per task means:

  • The agent has clear scope and doesn't try to do too much
  • You can review and approve each section before moving on
  • If something goes wrong, you only redo one piece — not the whole page

Build Order

When building a theme from scratch, follow this order so each task builds on the foundation of the previous one:

  1. Style guide first — color schemes, typography, spacing, buttons. This sets the design system for everything that follows.
  2. Header and footer — the global frame. If they're complex (mega-menu, multi-level footer), split them into separate tasks.
  3. Page sections, one at a time — hero section, then product carousel, then reviews, then FAQ, etc. Each as its own task.

Tip: The style guide task is critical for new themes. It ensures the pipeline uses your exact colors, fonts, and spacing from the start — rather than guessing from Figma on every section.

Splitting Full Pages

If you need to build a complete page from scratch, tf split is a great way to do it. It breaks a large task into ordered sub-tasks automatically.

terminal 
# Split a full-page task into section-level sub-tasks
$ tf split homepage.md

# For new themes, include style-guide and global tasks
$ tf split homepage.md --new-theme

# Run all sub-tasks in sequence
$ tf run homepage/

Task Files

Keep It Minimal

Less is more with task files. If your task already has a Figma link, don't describe the visual design in words. The pipeline extracts colors, spacing, typography, and layout directly from Figma — your written description will only compete with it and risk hallucination.

What to include:

  • The Figma link — this is your visual spec
  • Non-obvious behavior — interactions that aren't visible in a static design
  • Metadata — theme base, theme name, git branch

What to leave out:

  • Style descriptions (colors, fonts, spacing) when Figma is provided
  • Obvious behaviors the pipeline can infer (e.g., an arrow icon next to a menu item is a submenu)
  • Lengthy explanations — the pipeline understands plain language

Always Specify Metadata

Always include # Theme Base, # Theme Name, and # Git Branch in your task files. If you leave these out, the pipeline auto-generates them — and you may end up out of sync with where your work actually lives.

my-task.md 
# GIT repo
https://github.com/org/my-store-theme.git

# Theme Base
Dawn

# Theme Name
My Store v2

# Git Branch
feature/homepage-redesign

# Task
Build the hero section.

# Figma
Desktop: https://www.figma.com/design/abc?node-id=10-250
Mobile: https://www.figma.com/design/abc?node-id=10-500

Describe Behavior, Not Style

Only describe what the pipeline can't see in the Figma. If a section has a non-obvious interaction — a click that triggers a drawer, a hover state that isn't in the static mockup, a carousel with specific autoplay timing — mention it. Otherwise, trust the Figma.

good task description 
# Task
Build the featured collections section.

Clicking a collection card opens a quick-view drawer
with the first 4 products (not a page navigation).
The carousel auto-plays every 5 seconds on desktop,
swipe-only on mobile.

Avoid: "Use font size 18px with color #333 and 24px padding." If this is in the Figma, the pipeline already knows. Writing it out risks conflicts and hallucination.

Match Detail to Scope

Not every task needs the same level of detail. The size of your task should decide how you write it.

For full page builds and new sections, keep it high-level. Provide the Figma links, mention non-obvious behaviors, and let the pipeline figure out the rest. You're painting on a blank canvas — broad strokes work.

For bug fixes and small tweaks, do the opposite. Be surgical. Tell the pipeline exactly what's wrong, where it's happening, and what the fix should look like. Vague descriptions on small tasks lead to the pipeline guessing — and guessing wrong.

full page build — keep it broad 
# Task
Build the product page based on the Figma.

# Figma
Desktop: https://www.figma.com/design/abc?node-id=10-250
Mobile: https://www.figma.com/design/abc?node-id=10-500
bug fix — be precise 
# Task
The announcement bar text is clipping on mobile
(viewport under 375px). The container has overflow:hidden
cutting off the last line. Fix the padding-bottom on
.announcement-bar__message to give the text room to breathe.

Rule of thumb: The smaller the task, the more specific your description should be. A full section build can afford ambiguity — a one-line bug fix cannot.

Pipeline vs Chat

When to Use Pipeline

Use tf run (the full pipeline) for building new things — creating a section, adding a feature, implementing a design from Figma. The pipeline is intelligent: it understands plain language, reads Figma, plans the implementation, writes code, and validates the output.

The pipeline is slower but thorough. It goes through multiple agents (context, analyzer, dev, validator) and iterates to get things right. Worth the wait for substantial work.

  • Creating a new section from a Figma design
  • Building a complete component (header, product card, etc.)
  • Any task that needs planning and multi-file changes

When to Use Chat

Use tf chat (the super agent) for quick, targeted fixes — padding is off, a color doesn't match, an element needs to be repositioned. Chat is fast but works best with specific instructions.

Unlike the pipeline, chat doesn't plan or validate — it's a direct conversation with an agent that has full access to your theme. Give it precise details:

terminal 
# Start a chat session on the latest repo
$ tf chat --latest

# In chat, be specific:
"Change the hero section padding to 80px top and 60px bottom"
"The CTA button color should be #E8251A, not #FF0000"
"Move the logo 10px to the left in the header"

Tip: You can also paste screenshots into chat to show visual bugs. The agent can analyze images and fix what it sees.

While Running

Don't Touch Shopify Admin

This one is critical. Never make changes in the Shopify admin while a pipeline task is running.

Here's why: the pipeline pulls the latest state of your theme from Shopify at the very start of a run. That snapshot becomes the foundation for everything it builds. If you jump into the admin and tweak a setting, reorder sections, or update content mid-run — the pipeline has no idea. It's working off an older version of your theme. When it pushes its changes, your admin edits get overwritten silently.

The timing is simple:

  • Before you start a task — make all the admin changes you need
  • During the task — hands off the Shopify admin entirely
  • After the task completes — you're free to edit again

Think of it like this: The pipeline takes a photo of your store at the start. Everything it builds is layered on top of that photo. If you rearrange the furniture while it's working, the final result won't match reality.

Chat & Saving

The same principle applies to tf chat — but with a twist. Chat pulls the latest theme state when the session starts, and then keeps working off that snapshot for the entire conversation.

This means: if you save changes in the Shopify admin while a chat session is active, the agent won't see them. It's still working off the version it pulled at the start. Worse — if the agent then pushes its own changes, your admin saves get lost.

The rule:

  • Don't save changes in Shopify admin while a chat session is active
  • If you absolutely need to make an admin change mid-conversation — quit the chat session first, make your edits, then start a new chat

Tip: Starting a fresh chat session is cheap — it only takes a few seconds. Don't risk losing work just to save yourself a restart.

Iteration

Follow-Up Tasks

A section won't always be perfect in one run. That's expected. Don't hesitate to create a follow-up task to refine what was built. The pipeline works incrementally — each run builds on the current state of the theme.

Batching Fixes

After building 3 or 4 sections, you'll likely have a handful of small issues across them. Instead of creating a fix task for each one, combine them into a single fix task:

fixes.md 
# Task
Fix the following issues:

1. Hero section: CTA button should have rounded corners (8px)
2. Product carousel: spacing between cards is too tight on mobile
3. Reviews section: star rating icons are misaligned vertically
4. Footer: newsletter input field is too narrow on tablet

Tone Matters

The pipeline responds well to context about what worked and what didn't. If a previous run got 90% right and you're fixing the remaining 10%, say so. This tells the pipeline to refine rather than rebuild:

follow-up task 
# Task
The hero section from the last run looks great, but it has
a couple of issues:

1. The background image isn't covering the full viewport height
2. The subheading font weight should be lighter (300 instead of 400)

Everything else is exactly right — don't change the layout or colors.

Tip: Being explicit about what's working prevents the pipeline from over-correcting. "Don't change the layout" is a useful constraint that keeps the scope tight.