saccoai-design-variations

This skill takes an already-built website and produces N alternative design directions — each on its own git branch with a Vercel preview URL. The client gets a comparison table with clickable links to review each direction side-by-side before committing to one.

The skill works on any Next.js project, whether built by the saccoai pipeline or not. It invokes saccoai-frontend-design once per variation, using cross-variation constraints to guarantee each direction is genuinely different — not just a palette swap of the same idea.

Inputs

Input	Required	Default	Description
Project path	Yes	cwd	Path to an existing built Next.js project
--variations N	No	3	Number of alternative designs to generate
--depth shallow|deep	No	shallow	How much of the visual layer to change
Aesthetic hints	No	auto-diversify	Optional per-variation direction (e.g., "make one brutalist, one editorial")

Execution Model

Single-agent hybrid. Sequential by default. Uses superpowers for parallelism:

• dispatching-parallel-agents for Phase 2 (generating N design briefs in parallel) and Phase 4 (deploying N branches in parallel)
• Phase 3 is sequential per variation — git branch operations cannot be parallelised

Preconditions

• Clean working tree: Run git status before starting. If uncommitted changes exist, abort with a warning. Variations branch from HEAD — a dirty working tree contaminates all branches.
• Next.js project: The project root must contain package.json with a next dependency.

Phase 1: Analyze Current Design

Understand the existing site's design so variations are genuinely different from the original.

Path A — pipeline-built site

If .saccoai/design-brief/design-brief.md exists:

1. Read .saccoai/design-brief/design-brief.md — current creative direction, visual anchor, signature element, typography, color strategy
2. Read .saccoai/design-system/tokens.css — current palette as CSS custom properties

This is the fast path: all design context already exists.

Path B — any Next.js project

If no .saccoai/ output exists, reconstruct the design snapshot by reading:

1. src/app/globals.css (or app/globals.css) — scan the @theme block for color tokens and CSS custom properties
2. Root layout (src/app/layout.tsx or app/layout.tsx) — identify next/font family imports and font variable assignments
3. Homepage component — scan for spatial patterns: hero layout, section structure, grid usage, heading treatment
4. src/components/ — scan for spatial patterns (card styles, section padding, grid usage) and check for Framer Motion usage (motion components, animation variants, transition configs)
5. src/app/globals.css — check for background atmosphere treatments (gradients, grain, overlays, textures)

Synthesize findings into a Current Design Snapshot kept in working memory (not written to disk):

Current Design Snapshot
- Visual anchor: {typography-led / color-led / composition-led / texture-led / motion-led}
- Display font: {family}
- Body font: {family}
- Primary color: {hex}
- Accent color: {hex}
- Background: {hex or treatment}
- Spatial rhythm: {uniform / varied}
- Motion: {immediate / reveal / staggered / dramatic / none detected}
- Atmosphere: {clean / textured / gradient / layered / dark atmospheric}
- Signature element: {if identifiable}

This snapshot is the baseline that all variations must diverge from.

Phase 2: Generate Alternative Design Briefs

For each variation (1 through N), invoke saccoai-frontend-design to produce a new design brief.

Diversification Strategy

Spread variations across different visual anchors from saccoai-frontend-design:

• typography-led — the typeface IS the design; layout is simple to let type breathe
• color-led — a bold or unusual color relationship defines the site
• composition-led — the layout itself is the statement; asymmetry, overlap, or dramatic negative space
• texture-led — surface and atmosphere define the mood; grain, mesh gradients, layered transparencies
• motion-led — movement tells the story; scroll-driven reveals or a choreographed entrance sequence

Assignment rules:

1. If user provided aesthetic hints: map each hint to a variation. Fill remaining slots by auto-diversifying across anchors not yet used.
2. If no hints (auto-diversify): assign a different anchor to each variation. Start with the anchor furthest from the current design's anchor. For N > 5, allow anchor reuse but require different emotional territories.

Cross-Variation Constraints

Pass these constraints to saccoai-frontend-design for each variation to prevent convergence:

• "Do NOT use font {X}" — where X is any font used by the current design or another variation
• "Do NOT use {color} as primary" — where color is the primary of the current design or another variation
• "Visual anchors already used: {list}" — so saccoai-frontend-design picks a different anchor
• "Signature elements already used: {list}" — to prevent duplicate signature elements across variations

Build the constraint list incrementally: after each brief is generated, add its fonts, primary color, anchor, and signature element to the exclusion lists passed to subsequent variations.

Parallel Execution

Use superpowers dispatching-parallel-agents to generate all N briefs simultaneously, passing each agent its pre-assigned anchor and cumulative constraints. After all agents complete, run a dedup check: if any two variations share the same display font or primary color, have the offending variation regenerate with stricter constraints.

Output

Each variation's design brief saved to:

.saccoai/variations/
├── variation-1-{label-slug}/
│   └── design-brief.md
├── variation-2-{label-slug}/
│   └── design-brief.md
└── variation-3-{label-slug}/
    └── design-brief.md

The label is a short human-readable name derived from the emotional territory (e.g., editorial-warmth, bold-technical, refined-minimal).

Phase 3: Create Branches and Apply Variations

Run sequentially — one variation at a time to keep git state clean.

3a: Create Branch

From the project root, for each variation:

# If branch already exists from a previous incomplete run, delete and recreate
git branch -D design/variation-N-{label-slug} 2>/dev/null || true
git checkout -b design/variation-N-{label-slug}

Always branch from main (or the current default branch at the time this skill started), not from a previous variation branch.

3b: Apply Changes

Shallow mode (--depth shallow)

Surgical token and font swap. Only these files change:

1. globals.css — replace the @theme block

Replace the existing color tokens with the variation's palette from its design brief. Example:

/* Before */
@theme {
  --color-primary: #1a1a2e;
  --color-accent: #6c63ff;
  --color-background: #ffffff;
}

/* After (variation: editorial-warmth) */
@theme {
  --color-primary: #2d1810;
  --color-accent: #c9622f;
  --color-background: #faf7f2;
}

Update dark mode values (:root[data-theme="dark"] or .dark class) to match the variation's dark mode palette from the brief.

2. Root layout — swap next/font imports

Replace the font imports and CSS variable assignments:

// Before
import { Inter, Playfair_Display } from "next/font/google";
const display = Playfair_Display({ subsets: ["latin"], variable: "--font-display" });
const body = Inter({ subsets: ["latin"], variable: "--font-body" });

// After (variation: bold-technical)
import { Syne, IBM_Plex_Sans } from "next/font/google";
const display = Syne({ subsets: ["latin"], variable: "--font-display", weight: ["700", "800"] });
const body = IBM_Plex_Sans({ subsets: ["latin"], variable: "--font-body", weight: ["400", "500"] });

3. Animation config — if the variation's motion plan differs significantly from the current (e.g., current is staggered, variation is immediate), update shared animation variant constants in the animation config file or shared motion components.

What does NOT change in shallow mode:

• Component structure, HTML markup, and Tailwind utility classes
• Page layouts and section ordering
• Image treatments
• Card border-radius, shadows, spacing

Deep mode (--depth deep)

Everything in shallow, plus a full visual layer re-implementation. Deep mode only modifies the homepage, root layout, and shared components — it does not re-implement every page.

Reference saccoai-frontend-design/references/visual-techniques.md for CSS implementation patterns throughout.

4. Hero section — re-implement layout per the variation's spatial composition: asymmetric vs centered, image placement, heading treatment (split heading, oversized initial cap, etc.)

5. Card styles — adjust border-radius, box-shadow, spacing, and hover behavior across card components per the brief's spatial composition and atmosphere

6. Section rhythm — modify section padding and spacing patterns (uniform spacing for trust/minimal briefs, varied spacing for editorial/creative briefs)

7. Background atmosphere — add or remove grain textures, mesh gradients, dot grids, or glow effects as specified in the brief's visual atmosphere. Implementations in visual-techniques.md.

8. Motion patterns — re-implement entrance narrative, scroll reveal behaviors, and hover interaction states per the brief's motion plan (see saccoai-frontend-design for motion plan categories)

9. Signature element — implement the variation's unique signature element exactly as described in the design brief

10. Typography scale — adjust heading sizes, line heights, and letter spacing in globals.css or Tailwind config to match the brief's typographic scale

3c: Commit and Return to Main

git add -A
git commit -m "design: variation N — {label} ({depth} mode)"
git checkout main

After all variations are committed to their branches, the working tree is back on main and clean.

Phase 4: Deploy Previews

Use superpowers dispatching-parallel-agents to push and deploy all variation branches simultaneously.

For each variation branch:

1. git push origin design/variation-N-{label-slug}
2. If the project is linked to Vercel with git integration, Vercel auto-deploys a preview from the push. Wait for the deployment to complete and collect the preview URL.
3. If no auto-deploy detected after push: run vercel deploy on the branch, or instruct the user to run vercel link first.

Also collect the current main deployment URL as the baseline for comparison.

No-Vercel fallback: If the project is not linked to Vercel, skip this phase. Tell the user: "Run vercel link to connect this project, then re-run Phase 4 manually by pushing each variation branch." List the branch names so they can do it themselves.

Phase 5: Present Comparison

Save the following to .saccoai/variations/comparison.md and print it to the terminal:

## Design Variations for {project name}

Generated on {date} | Depth: {shallow|deep} | Variations: {N}

| # | Label | Branch | Preview | Visual Anchor | Signature Element | Key Difference |
|---|-------|--------|---------|---------------|-------------------|----------------|
| 0 | Current | main | {url} | {anchor} | {element} | Baseline |
| 1 | {label} | design/variation-1-{label-slug} | {url} | {anchor} | {element} | {1-line diff from baseline} |
| 2 | {label} | design/variation-2-{label-slug} | {url} | {anchor} | {element} | {1-line diff from baseline} |
| 3 | {label} | design/variation-3-{label-slug} | {url} | {anchor} | {element} | {1-line diff from baseline} |

### Variation Details

#### Variation 1: {label}
- **Emotional territory**: {combined emotions}
- **Typography**: {display font} + {body font}
- **Color**: {primary}, {accent} on {background}
- **Motion**: {entrance + scroll narrative}
- **Signature**: {element description}
- **Depth**: {shallow / deep}
- **Branch**: `design/variation-1-{label-slug}`
- **Preview**: {url}

(repeat for each variation)

### Next Steps

1. Share the preview URLs with the client for comparison
2. Once the client chooses a direction, run Phase 6 cleanup to merge and finalize

The "Key Difference" column should be a single concrete sentence: what would the client notice first when landing on this variation vs. the current design.

Phase 6: Cleanup (user-triggered)

This phase is not automatic. It runs only after the user confirms which variation they have chosen.

Before running cleanup, confirm:

• "You've chosen variation {N} — {label}. I'll merge it into main, remove the other branches, and update your design brief. This is destructive. Confirm? (yes/no)"

If confirmed:

1. Merge chosen branch into main:

   git checkout main
   git merge design/variation-N-{label-slug} --no-ff -m "design: adopt variation N — {label}"
   

   (Or instruct the user to merge via a GitHub PR if they prefer.)

2. Delete other variation branches (local + remote):

   git branch -D design/variation-M-{label-slug}
   git push origin --delete design/variation-M-{label-slug}
   

   Run for every variation except the chosen one.

3. Copy chosen brief to the active design brief:

   mkdir -p .saccoai/design-brief
   cp .saccoai/variations/variation-N-{label-slug}/design-brief.md .saccoai/design-brief/design-brief.md
   

4. Remove variations output:

   rm -rf .saccoai/variations/
   

5. Commit the cleanup:

   git add .saccoai/design-brief/design-brief.md
   git commit -m "design: finalize variation N — {label} as active design direction"
   

Composition

existing built site ──→ saccoai-design-variations
                              ├── reads:   .saccoai/design-brief/ (if exists)
                              ├── reads:   .saccoai/design-system/ (if exists)
                              ├── invokes: saccoai-frontend-design (N times, with cross-variation constraints)
                              ├── creates: git branches (one per variation)
                              ├── deploys: vercel preview URLs (one per branch)
                              └── outputs: .saccoai/variations/ (briefs + comparison)

Edge Cases

• Uncommitted changes: Abort with a warning before touching any branches.
• Branch already exists: Delete and recreate — a previous run was likely incomplete.
• Font conflict after parallel generation: If two variations share the same display font, have the offending variation regenerate with an explicit font exclusion.
• Deep mode on large sites: Only the homepage, root layout, and shared components are modified. Individual pages beyond the homepage are not touched.
• Project not linked to Vercel: Skip auto-deploy in Phase 4 and leave instructions for the user.

Standalone Usage

Invoke this skill directly when:

• A client has approved a built site and wants to see design alternatives before the final launch
• Exploring creative directions before committing to one for a new project
• A/B testing aesthetic treatments on an existing production site
• The user says "show me options", "give me alternatives", or "what else could this look like"

When invoked, ask for: the project path, how many variations (default 3), shallow or deep (default shallow), and any aesthetic direction. Then run all six phases.