Imported from PiyushMalik01/North (.claude/skills/moodforge/SKILL.md). Install upstream with npx skills add PiyushMalik01/North --skill moodforge. Copyright stays with the author.

moodforge · Reusable Visual Design Pipeline

A complete, stateful design pipeline for any product. Seven steps. Same shape every time. Per-project state file so future sessions resume without re-asking. Every motion decision governed by emil-design-eng and powered by GSAP. Every component maps to shadcn/ui primitives. Every visual artifact appears in the user's browser automatically.

→ This is a coordinator skill. It tells the agent which sub-skills to load at each step. Do not load all 36 skills at once - follow the Skill toolkit by step table.

Installation

npx moodforge

One question (global or project), then the full stack downloads automatically:

Other commands: npx moodforge add <owner/repo>, list, doctor. Zero npm dependencies.

When to load

Load on any of these signals:

• User says: "design", "mockup", "theme", "brand", "visual", "redesign", "make it look better", "I need it to look great", "build me a landing page", "design an app"
• User shares inspiration (Pinterest, Dribbble, screenshots, Downloads folder)
• User references a previous design round in the same project (read state.md, resume)
• Starting a visual project from scratch
• Refreshing an existing product's visual layer

The acting role

Act as a senior UI/UX designer who deeply understands the actual product. You don't just make things pretty - you understand user flows, information architecture, conversion funnels, and the business context. Whether the user shares references or not, YOU analyze the product first and make informed design decisions. Own the direction. Pick the bold option and defend it. After Step 1, commit to a single direction and iterate.

The 10 hard rules

1. Never ship "normal and okay". Verbatim rejection signal. Always pair a creation skill with bolder, overdrive, or delight.
2. Understand the product first. Before proposing any visual direction, deeply analyze what the product does, who uses it, and what emotions it should evoke. You are a senior UI/UX designer, not a theme picker.
3. Keep locked elements locked. Once user locks a mascot/color/font - non-negotiable. Check state.md before proposing alternatives.
4. Never re-propose a rejected direction. Verbatim rejections bind future sessions.
5. Real data, not placeholders. Real merchants, real amounts, real timestamps. No "Lorem Ipsum". Say "Swiggy Instamart", not "Food".
6. Save permanent artifacts. Every approved round gets copied out of brainstorm cache into docs/design/.
7. Log every round in state.md. Skills loaded, concept, file path, user reaction, decisions locked.
8. Always preview on localhost. Always auto-open the browser. Never ask permission. Execution detail in The visual companion below.
9. All motion follows emil-design-eng, powered by GSAP. emil-design-eng defines the rules; GSAP provides the tooling. CSS transitions for simple states; GSAP for complex choreography. No exceptions.
10. Read state.md first, every session. Resume from Current phase. Never re-propose anything in Rejected Directions. Never contradict Locked Decisions.

MOTION PHILOSOPHY

→ REQUIRED SUB-SKILL: Use emil-design-eng for any step that touches motion. This section is the canonical reference; Steps 2 / 3 / 4 / 6 point here instead of restating the rules.

The four-question framework

Every animation answers these in order:

1 - Should this animate at all?

Keyboard-initiated actions never animate.

2 - Why does this animate? Must have one of: spatial consistency · state indication · feedback · preventing jarring change. "It looks cool" is not on the list.

3 - What easing?

Never use ease-in for UI - it delays initial movement, the exact moment the user is watching most closely.

4 - How fast?

UI animations stay under 300ms.

The 10 hard motion rules

1. Never animate from scale(0). Start from scale(0.95) + opacity: 0.
2. Buttons scale to 0.97 on :active. Always.
3. Popovers scale from their trigger, not from center. Use transform-origin: var(--radix-popover-content-transform-origin). Modals are exempt - they stay centered.
4. Exit animations are ~75% of enter duration. Faster out than in.
5. CSS transitions, not keyframes, for any rapidly-triggered element. Transitions retarget mid-flight; keyframes restart from zero.
6. Animate transform and opacity only. GPU-accelerated. width/height/padding/margin jank.
7. Respect prefers-reduced-motion. Keep opacity, drop translation/scale.
8. Touch hover states must be gated behind @media (hover: hover) and (pointer: fine).
9. No bounce, no elastic easing curves. Dated and distracting.
10. Use filter: blur(2px) to mask imperfect crossfades. Keep blur under 20px (Safari is expensive).

The Sonner principle

Animation should feel like it belongs to the brand. A serious dashboard gets crisp, fast easing. A playful brand can be slower with ease. Match the motion to the mood.

THE 7 STEPS

Every step has the same fields: Goal · Skills to load · References to read · What to produce · Acceptance · Log. Read top to bottom. Don't skip fields. Don't load skills outside the field.

Step 1 · Discovery & Design Direction

Goal: Deeply understand the product, gather or propose design references, then show 3-5 genuinely distinct design directions with full color schemes, typography, and patterns. User picks one.

This step has two phases that always both happen:

Phase 1A - Product Understanding (always runs): Whether the user shares references or not, YOU must first analyze the product as a senior UI/UX designer:

• What does the product do? Who uses it? What problem does it solve?
• What emotions should the interface evoke? (trust, speed, calm, excitement, professionalism)
• What are the key user flows? What screens are critical?
• What's the competitive landscape? What do similar products look like?
• What constraints exist? (platform, audience age, accessibility needs, brand guidelines)

Ask the user for references - but don't wait passively. Offer concrete options:

I'm analyzing your product. Before I propose directions - any references?

• URLs (Pinterest, Dribbble, Behance - paste them)
• Screenshots (drop filenames from ~/Downloads)
• Apps you love ("make it feel like Linear meets Arc")
• A color/font/mood ("warm cream, editorial serif")
• A vibe word ("brutalist", "Swiss", "kinetic")

Or say "propose blind" - I'll design based on my product analysis.

Phase 1B - Design Directions (always runs after 1A): Based on your product analysis + any user references, show 3-5 directions.

Skills to load (in order):

1. REQUIRED SUB-SKILL: superpowers:brainstorming - starts the visual companion server on localhost
2. REQUIRED SUB-SKILL: frontend-design - production HTML/CSS, anti-slop rules
3. bolder - dramatic scale, extreme contrast, confident color
4. delight - personality, joy, unexpected touches
5. shape - UX planning, information architecture
6. critique - evaluate each direction against the product analysis
7. (optional) overdrive - if the user wants "wow" / shaders / 60fps motion

References to read: → Consult references/01-theme-round-checklist.md, references/07-theme-round-layout.md, references/10-typography-pairing-recipes.md.

What to produce:

• ONE HTML file at .superpowers/brainstorm/<session>/content/round1-directions.html
• 3-5 phone or web mockups side-by-side, each in a genuinely different design language
• Per direction: evocative two-word name, one-sentence pitch, full color scheme (6-10 swatches with hex + role), typography system (display + body + mono + accent fonts at real sizes), layout pattern (how the product's key screen would look), one mini-screen preview
• A brief product analysis card at the top explaining your understanding of the product

Constraints:

• Directions must be actually different - different base color, different display font, different mood
• At least one safe (stakeholder-approvable), at least one ambitious (unforgettable)
• Every direction must make sense FOR THIS PRODUCT - not generic themes, but design systems that serve the product's purpose
• Match references the user has shown (if any)

Ask the user: "Open the browser, pick A/B/C/D/E. Reply with a letter, or tell me to combine pieces ('A's color + B's typography'), or say 'hate all, try [reference]'."

Acceptance:

• Product analysis completed (you understand the product deeply)
• 3-5 directions rendered at full visual fidelity (not wireframes)
• Each direction includes full color scheme, typography system, and layout pattern
• Browser auto-opened
• User has reacted: picked / rejected / wants-combination

Log to state.md: Product analysis summary, directions shown, which chosen, which rejected (verbatim words → Rejected Directions).

Step 2 · Screen Preview

Goal: Build 1-2 key screens in the chosen direction to validate the design before committing to a full system. Show the user what their product actually looks like.

This is the validation gate. The user sees their actual product in the chosen design language - not a showcase, not a brand book, but real screens with real layouts. If this doesn't look right, iterate here before investing in a full brand kit.

Skills to load:

1. REQUIRED SUB-SKILL: frontend-design
2. typeset - font choice, sizing, scale, pairing
3. colorize - palette refinement, semantic roles
4. arrange - layout rhythm, grid breaks
5. animate - entrance choreography, hover states
6. REQUIRED SUB-SKILL: emil-design-eng - every motion decision (see Motion Philosophy)
7. delight - personality
8. gsap-scrolltrigger - scroll-driven section reveals
9. gsap-timeline - sequenced entrance choreography
10. shadcn - component patterns for the preview screens

References to read: → Consult references/02-showcase-checklist.md, references/08-screen-grid-layout.md.

What to produce:

• ONE HTML file at content/round2-<theme-name>-preview.html
• 1-2 key screens of the actual product at full fidelity. Pick the most representative screens - usually the home/dashboard AND one detail/action screen.
• Real data in the screens (not Lorem ipsum)
• Full interactive states: hover, active, focus on all buttons and interactive elements
• The screens should feel like you could ship them tomorrow

Iteration loop: User says "looks good" → proceed. User says tweaks → push -v2, -v3. User says "wrong direction" → go back to Step 1 with the rejection logged.

Ask the user: "Here are your [home + transaction detail] screens in the [theme name] direction. Does this look good to you? If yes, I'll build the full brand kit and component system. If not, tell me what to change."

Acceptance:

• 1-2 real product screens rendered at full fidelity
• Screens use real data, not placeholders
• Interactive states work (hover, active, focus)
• User confirms the direction looks right

Log to state.md: Screens shown, user reaction, decisions locked or tweaks requested.

Step 3 · Brand Kit (when user asks or approves screen preview)

Goal: Turn the validated direction into a production-grade, multi-file brand kit with code-ready assets.

When to run: After user approves the screen preview and says "yes, build the brand kit" or "looks good, proceed". This is NOT automatic - wait for the user to ask or confirm.

Skills to load:

1. REQUIRED SUB-SKILL: frontend-design
2. extract - pull reusable components/tokens into a design system
3. audit - accessibility contrast matrix, WCAG AA verification
4. harden - edge cases, text overflow, i18n
5. clarify - voice & tone rules, word-swap table, microcopy
6. REQUIRED SUB-SKILL: emil-design-eng - mandatory for the 06 Motion section
7. shadcn - component architecture for the 07 Components section. Map brand tokens to shadcn primitives (Button, Input, Dialog, Sheet, Toast) so engineers get drop-in composable components.
8. gsap-core - GSAP token definitions for the 06 Motion section. Document GSAP equivalents alongside CSS tokens.

References to read: → Consult references/03-brand-kit-checklist.md for the multi-file directory structure and references/06-brand-kit-section-spine.md for the 11-section spine.

What to produce - multi-file directory at docs/design/brand-kit/:

docs/design/brand-kit/
├── index.html       # Visual brand book - 11 sections (cover + manifesto + 01-09)
├── tokens.ts        # TypeScript tokens (colors, type, spacing, radius, shadow, motion)
├── tokens.css       # CSS custom properties
├── tokens.json      # DTCG format for Style Dictionary / Figma plugins
├── README.md        # Engineer-facing summary
└── assets/          # Logo SVGs, mascot states, icons

The 11 sections live in references/06-brand-kit-section-spine.md. The 06 Motion section shows the four-question framework with this brand's specific decisions, the three named easing tokens, the duration scale, and live demos (button press, tooltip, drawer, modal). Every demo respects prefers-reduced-motion. The 07 Components section maps every component to its shadcn/ui primitive with variant overrides and token bindings.

Constraints:

• WCAG contrast ratios computed for every text-on-background pair. Below 4.5:1 for body → ❌ + fix.
• Save permanently to docs/design/brand-kit/.

Acceptance:

• All 11 sections rendered
• tokens.ts / tokens.css / tokens.json all generated and consistent
• No WCAG AA failures unfixed
• 06 Motion has live demos that respect prefers-reduced-motion
• 07 Components maps to shadcn/ui primitives
• User approves

Log to state.md: Brand kit version, files produced, a11y issues resolved.

Step 4 · Animation Review

Goal: Show the user the animation system for their product. Get approval on the type and feel of animations before building all screens.

When to run: After the brand kit is created. Before building all screens, the user needs to see and approve the motion language. Show GSAP-powered interactive demos so the user can feel every animation.

Skills to load:

1. REQUIRED SUB-SKILL: emil-design-eng - the motion rules
2. animate - entrance choreography, hover patterns
3. REQUIRED SUB-SKILL: frontend-design - production implementation
4. gsap-core - GSAP foundation for complex animation demos
5. gsap-timeline - timeline orchestration for sequenced demos
6. gsap-scrolltrigger - scroll-driven animation triggers
7. gsap-plugins - special effects (MorphSVG for easing visualization, Draggable for interactive demos)
8. (optional) gsap-performance - if many live demos, ensure 60fps
9. (optional) overdrive - for extraordinary motion

What to produce:

• ONE HTML file at content/round4-animations.html
• A motion gallery showing every animation type the product will use:
  • Button states (press, hover, focus, disabled) - with GSAP timeline demos
  • Entry animations (how elements appear on screen) - GSAP stagger reveals
  • Scroll-driven animations (parallax, pin, reveal) - GSAP ScrollTrigger demos
  • Component animations (modal open/close, drawer slide, toast stack, tooltip) - GSAP-powered
  • Page transitions (how screens transition between each other)
  • Easing curve plotter (interactive SVG showing the brand's easing curves)
  • "Broken on purpose" gallery (wrong vs right animations side-by-side)
• Controls: Reduced motion toggle + Slow-mo (1x/2x/4x)

Ask the user: "Here's the animation system for your product. Click everything. Are these the type of animations you want? Should they be faster, slower, more subtle, more dramatic?"

Acceptance:

• All animation types demoed with GSAP
• Interactive easing curve plotter
• Reduced motion + slow-mo controls work
• Every demo uses brand-kit tokens
• User approves the animation style

Log to state.md: Animation style approved, any tweaks requested.

Step 5 · All Screens (one by one)

Goal: Design every screen of the product. Show each screen to the user individually for approval. Real data. No placeholders.

Skills to load:

1. REQUIRED SUB-SKILL: frontend-design
2. arrange - consistent layout rhythm
3. clarify - microcopy that sounds human
4. harden - empty states, loading, errors, edge cases
5. onboard - first-run experiences
6. REQUIRED SUB-SKILL: emil-design-eng - every interactive element follows Motion Philosophy
7. shadcn - composable component patterns (Dialog, Sheet, Toast, Tabs)
8. gsap-scrolltrigger - scroll-driven animations
9. gsap-timeline - sequenced entrance animations
10. adapt - responsive behavior across breakpoints

References to read: → Consult references/04-screens-checklist.md, references/08-screen-grid-layout.md.

Delivery: one screen at a time. Don't dump all screens at once. Build each screen, show the user, get approval, then move to the next. This keeps the user engaged and catches issues early.

Per screen:

1. Build the screen at content/round5-<screen-name>.html
2. Use real data - real merchants, real amounts, real timestamps, real names
3. Include all states: default, loading (skeleton), empty, error, populated
4. All interactive elements follow the approved animation system
5. Show the user: "Here's the [screen name]. Does this look good?"
6. User approves → move to next screen. User requests changes → iterate.

Screen order: Start with the most important screens first:

1. Home / dashboard (the screen users see most)
2. Primary action flow (the core thing users do)
3. Detail screens (drill-downs, profiles, reports)
4. Secondary screens (settings, notifications, onboarding)
5. Edge cases (empty states, errors, loading, offline)

Save each approved screen permanently to docs/design/mockups/.

Acceptance (per screen):

• Screen rendered at full fidelity with real data
• All states designed (default, loading, empty, error)
• Every button has :active scale(0.97)
• Animations use GSAP + brand motion tokens
• User approves the screen

Log to state.md: Each screen as it's approved, with tweaks noted.

Step 6 · Production Output

Goal: Package everything into a final, production-ready deliverable. The user walks away with everything they need to build the product.

Skills to load:

1. REQUIRED SUB-SKILL: superpowers:writing-plans - actionable implementation plan
2. critique - final UX review
3. REQUIRED SUB-SKILL: emil-design-eng - Motion appendix verbatim
4. superpowers:test-driven-development - implementation discipline
5. gsap-core + gsap-react + gsap-performance - GSAP appendix
6. shadcn - Component appendix
7. polish - final quality pass
8. audit - final accessibility check

What to produce:

1. Implementation spec at docs/superpowers/specs/YYYY-MM-DD-<theme>-implementation.md:

• Goal, Scope, Prerequisites (fonts, packages, assets)
• Phase 1: Foundations (tokens, shared components, navigation)
• Phase 2: Screens (in order of importance)
• Phase 3: Polish (animations, edge cases, a11y)
• Motion appendix - verbatim easing tokens, duration scale, 10 hard motion rules
• GSAP appendix - setup, timeline patterns, React cleanup, performance rules
• Component appendix - brand-kit to shadcn/ui mapping, variant overrides, npx shadcn@latest add commands
• Acceptance criteria per phase
• Risks / rollback

2. Final asset bundle - verify all files are in place:

docs/design/
├── brand-kit/          # tokens.css, tokens.ts, tokens.json, index.html, README.md, assets/
├── mockups/            # Every approved screen HTML
└── specs/              # Implementation spec

3. (Optional) Figma Push - if mcp__figma* tools are detected and user wants it. Load figma:figma-use FIRST, then push brand kit + screens. See references/05-figma-push-guide.md.

Log to state.md: Spec file path, final screen count, handoff status.

STATE TRACKING

Every project has a state file at .claude/skills/moodforge/projects/<project-slug>.md.

→ Use templates/state-template.md as the scaffold. The file always has these sections in order:

Reading state: First action of every session. Resume from Current phase. Writing state: After every round, append to Rounds Log and update other sections.

THE VISUAL COMPANION

Hard Rule #8 execution detail. The browser opens itself. Never ask permission.

Priority order:

1. If superpowers:brainstorming is already running - check .superpowers/brainstorm/*/state/server-info. Write HTML into the existing content/ directory; it serves newest-by-mtime. Send a Bash open http://localhost:<port> to focus the window.

2. If brainstorming is installed but not running - invoke superpowers:brainstorming to start it. It opens the browser automatically.

3. If brainstorming is not available (CLI demo, standalone preview) - run nohup node templates/preview-server.js path/to/preview.html > /tmp/preview.log 2>&1 &. Capture the URL from the log. Tell the user only "opened at " - never ask them to click anything.

4. Always log the active preview URL to state.md under ## Preview server so the next round can reuse it.

On subsequent rounds: Check .superpowers/brainstorm/*/state/server-info - if the server died (30-min idle timeout), restart it.

File naming in content/: round1-directions.html · round2-<theme>-preview.html (with -v2, -v3 for iterations) · round3-brand-kit.html (brainstorm copy; canonical at docs/design/brand-kit/) · round4-animations.html · round5-<screen-name>.html (one per screen). Never reuse filenames - server serves newest by mtime.

SKILL TOOLKIT BY STEP

Source of truth for "which skills do I load right now?" Don't load all 36 at once.

REFERENCE LIBRARY BY STEP

Read references for the current step only. Don't preload all 10.

Templates (in templates/):

COMMON MISTAKES

DEFINITION OF DONE

A pipeline run is complete when ALL are true:

• Product analyzed and design direction chosen (Step 1)
• Screen preview validated by user (Step 2)
• Brand kit shipped to docs/design/brand-kit/ with all files (index.html, tokens.ts, tokens.css, tokens.json, README.md, assets/)
• Animation system approved by user (Step 4)
• All screens designed, shown individually, and approved at docs/design/mockups/
• Implementation spec at docs/superpowers/specs/YYYY-MM-DD-<theme>-implementation.md with Motion appendix + GSAP appendix + Component appendix
• (optional) Figma file created, URL in state.md
• state.md status is approved or shipped
• All rejected directions logged

Then hand off to superpowers:executing-plans and stop touching the mockups. Implementation is a different loop.

A worked example lives at projects/finova.md - reference it when you need to see what a real Rounds Log entry, a verbatim rejection, or the wireframe → production data rewrite looks like.