vibespot 0.4.4 → 0.5.0

package/assets/conversion-guide.md

@@ -345,6 +345,34 @@ The base template loads CSS in this order (each can override the previous):
 }
 ```
 
+### Link & Button Hover Problem
+
+HubSpot's theme applies default `a:hover` styles (blue color, underline, font change) that override your button/link styling.
+
+**Solution**: For every button/link element, combine the base selector with `:hover`, `:focus`, and `:active` to lock down `color`, `text-decoration`, and `font-family`:
+
+```css
+/* Lock visual properties across ALL interaction states */
+.my-module__cta,
+.my-module__cta:hover,
+.my-module__cta:focus,
+.my-module__cta:active {
+  color: #ffffff;
+  text-decoration: none;
+  font-family: inherit;
+  background: var(--cta-bg);
+  border: none;
+}
+
+/* Then add intentional hover effects separately */
+.my-module__cta:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px rgba(0,0,0,0.2);
+}
+```
+
+**CRITICAL**: Every `<a>` tag styled as a button MUST have explicit `:hover` and `:focus` rules that re-declare `color`, `text-decoration: none`, and `font-family`. Without this, HubSpot's defaults will bleed through.
+
 ### Body Background Problem
 
 The page wrapper structure is:

package/assets/design-guide.md

@@ -301,6 +301,7 @@ Every hero must have:
 - Primary: filled, bold, with icon →
 - Secondary: outlined or ghost style
 - Always include hover + active + focus states
+- CRITICAL: Re-declare color, text-decoration: none, and font-family on :hover/:focus/:active — HubSpot's theme overrides link hover styles
 - Padding: `px-6 py-3` minimum (generous click area)
 - Border radius: `rounded-lg` to `rounded-full`
 

package/assets/hubspot-rules.md

@@ -465,7 +465,20 @@ If your theme uses different names, use alternate_names in theme fields.json:
 
 ---
 
-## 8. Common Error Messages → Causes
+## 8. Link & Button Hover Override
+
+HubSpot's `theme-overrides.css` applies default `a:hover` styles that override your button styling with blue color, underlines, and font changes.
+
+**Every `<a>` styled as a button MUST include `:hover`, `:focus`, and `:active` rules** that explicitly re-declare:
+- `color` (your intended color, not HubSpot's blue)
+- `text-decoration: none`
+- `font-family: inherit`
+
+Without these, HubSpot's defaults bleed through on hover/focus states even when base styles look correct.
+
+---
+
+## 9. Common Error Messages → Causes
 
 | Error | Likely Cause |
 |-------|-------------|
@@ -483,7 +496,7 @@ If your theme uses different names, use alternate_names in theme fields.json:
 
 ---
 
-## 9. HubL Syntax Quick Reference
+## 10. HubL Syntax Quick Reference
 
 ### Variables and Expressions
 ```
@@ -532,7 +545,7 @@ If your theme uses different names, use alternate_names in theme fields.json:
 
 ---
 
-## 10. Pre-Upload Checklist
+## 11. Pre-Upload Checklist
 
 Before deploying any HubSpot CMS code, verify:
 

package/assets/humanify-guide.md

@@ -0,0 +1,459 @@
+# HUMANIFY.md — Anti-AI Writing Rules for Landing Page Copy
+
+> These rules strip the "AI smell" from generated landing page content.
+> Every rule exists because it triggers trained pattern recognition in readers
+> who now instinctively scan for AI-generated text. The goal is copy that
+> reads like a sharp human copywriter wrote it on their second coffee.
+
+---
+
+## 1. Banned Punctuation
+
+### Em dashes (—)
+```
+NEVER use em dashes. This is the single biggest AI tell in 2025.
+
+❌ "We build fast — so you don't have to wait"
+✅ "We build fast. You don't wait."
+✅ "We build fast, so you never wait."
+✅ "We build fast (so you never wait)."
+
+Replace with: periods, commas, parentheses, or just rewrite
+the sentence as two sentences. Hyphens for compound words
+are fine ("best-in-class"). En dashes for ranges are fine ("9–5").
+Only the em dash (—) is banned.
+```
+
+### Semicolons in marketing copy
+```
+Semicolons feel academic, not conversational. On a landing page
+they signal "a machine constructed this sentence."
+
+❌ "We handle the tech; you handle the business."
+✅ "We handle the tech. You handle the business."
+
+Exception: pricing pages or feature comparison tables where
+semicolons separate list items are fine.
+```
+
+### Excessive exclamation marks
+```
+One per page. Maximum. Zero is ideal for most B2B pages.
+Two or more screams "AI trying to sound excited."
+
+❌ "Get started today! It's free! You'll love it!"
+✅ "Get started today. It's free."
+```
+
+---
+
+## 2. Banned Words
+
+### Tier 1: Instant AI flags (NEVER use, no exceptions)
+These words appear 10-50x more often in AI text than human text.
+Readers have been trained to spot them.
+
+```
+delve / delving              → look into, dig into, explore
+tapestry                     → mix, blend, range
+multifaceted                 → complex, layered
+utilize / utilizing          → use
+leverage (as verb)           → use, take advantage of
+harness (as verb)            → use, put to work
+bolster                      → strengthen, boost
+underscore                   → show, highlight
+illuminate                   → show, explain, clarify
+facilitate                   → help, make easier, enable
+foster / fostering           → build, encourage, grow
+garner                       → earn, get, attract
+pivotal                      → important, key, critical
+crucial (overused by AI)     → important, key, essential
+commence                     → start, begin
+endeavor                     → effort, attempt, try
+myriad                       → many, a range of, lots of
+plethora                     → many, plenty of
+pertinent                    → relevant
+aforementioned               → (just name the thing again)
+wherein                      → where, in which
+henceforth                   → from now on
+```
+
+### Tier 2: AI-coded adjectives and nouns (avoid unless truly earned)
+These are real words that AI has ruined through overuse.
+Use them only when nothing else works, never as decoration.
+
+```
+comprehensive                → thorough, complete, full
+foundational                 → basic, core, fundamental
+nuanced / nuance             → subtle, detailed
+landscape (abstract)         → space, market, world, field
+realm                        → area, field, world
+beacon                       → (just cut it)
+cornerstone                  → foundation, base, core
+catalyst                     → trigger, spark, cause
+paradigm                     → model, approach, shift
+synergy                      → (just cut it)
+robust                       → strong, solid, reliable
+seamless / seamlessly        → smooth, easy, without friction
+cutting-edge                 → new, latest, modern, advanced
+groundbreaking               → new, first-of-its-kind
+game-changer / game-changing → (describe the actual change)
+revolutionary                → (describe the actual revolution)
+transformative               → (describe the actual transformation)
+innovative / innovation      → new, original, clever
+holistic                     → complete, full, whole-picture
+bespoke                      → custom, tailored, made-for-you
+curated                      → picked, selected, chosen
+```
+
+### Tier 3: AI filler verbs (replace with concrete action)
+```
+empower / empowering         → help, give, let, enable
+elevate                      → improve, raise, boost
+unlock                       → open, enable, get access to
+streamline                   → simplify, speed up, cut steps
+optimize                     → improve, tune, fix
+spearhead                    → lead, run, drive
+navigate (abstract)          → handle, manage, deal with
+embark                       → start, begin
+cultivate                    → build, grow, develop
+reimagine                    → redesign, rethink, rebuild
+```
+
+---
+
+## 3. Banned Phrases & Sentence Patterns
+
+### Opening clichés (NEVER start a headline, subheadline, or paragraph with these)
+```
+❌ "In today's [fast-paced/ever-evolving/digital] world..."
+❌ "In today's [industry] landscape..."
+❌ "In an era of..."
+❌ "In the realm of..."
+❌ "Whether you're a [X] or a [Y]..."
+❌ "Are you tired of [X]?"
+❌ "Imagine a world where..."
+❌ "Picture this:"
+❌ "Here's the thing:"
+❌ "Here's the deal:"
+❌ "Let's face it:"
+❌ "Look no further."
+❌ "Say goodbye to [X] and hello to [Y]."
+❌ "Gone are the days of..."
+❌ "It's no secret that..."
+❌ "It goes without saying..."
+❌ "At its core..."
+❌ "At the end of the day..."
+❌ "The truth is..."
+❌ "When it comes to [X]..."
+
+Instead: Start with the specific claim, fact, or benefit. Jump straight in.
+✅ "Your plumber shows up in 40 minutes. Every time."
+✅ "Three taps. One landing page. No code."
+```
+
+### The negation flip (AI's favorite "profound" structure)
+```
+❌ "It's not about X, it's about Y."
+❌ "It's not just a [tool/product], it's a [transformation/revolution]."
+❌ "It's not just X — it's Y."
+
+This pattern is now the second most recognized AI tell after em dashes.
+AI uses it because it sounds wise while saying almost nothing.
+
+Instead: Just state Y. You don't need the "not X" setup.
+❌ "It's not just a landing page builder. It's your growth engine."
+✅ "Build landing pages that actually convert."
+```
+
+### Tricolon abuse (rule of three, overused)
+```
+AI loves grouping things in threes with escalating intensity:
+❌ "Fast, reliable, and revolutionary."
+❌ "Simple, powerful, and transformative."
+❌ "Plan, build, and launch."
+
+Threes are a valid rhetorical device, but AI uses them CONSTANTLY.
+Use them once per page max. Vary with twos, fours, or unstructured lists.
+
+✅ "Fast and reliable."
+✅ "Simple enough for your intern. Powerful enough for your CMO."
+```
+
+### Rhetorical inflation (everything turned up to 11)
+```
+AI makes everything sound earth-shattering, even mundane features.
+
+❌ "Revolutionize your workflow"          (it's a form builder)
+❌ "Transform the way you connect"        (it's a contact page)
+❌ "Unleash the power of your brand"      (it's a logo section)
+❌ "Redefine what's possible"             (it's a pricing table)
+
+Instead: Be specific about what actually happens.
+✅ "Build forms in 2 minutes, not 2 hours."
+✅ "Your contact page, live in three clicks."
+```
+
+### Filler transitions
+```
+❌ "Additionally,"
+❌ "Furthermore,"
+❌ "Moreover,"
+❌ "It's important to note that..."
+❌ "It's worth mentioning that..."
+❌ "Notably,"
+❌ "Interestingly,"
+❌ "In essence,"
+❌ "In summary,"
+❌ "Needless to say,"
+❌ "That being said,"
+
+These add zero information on a landing page. Cut them entirely.
+If two sentences need connecting, the connection should be obvious
+from the content itself, or use a plain "And," "But," "So," or "Also."
+```
+
+### The fake-profound closer
+```
+❌ "The future of [X] is here."
+❌ "The question isn't whether to [X], but when."
+❌ "Ready to take the next step?"
+❌ "Your journey starts here."
+❌ "Join the revolution."
+❌ "Experience the difference."
+❌ "See what's possible."
+
+Instead: Specific CTA with outcome.
+✅ "Build your first page free. Takes 3 minutes."
+✅ "Start now. Cancel anytime."
+✅ "Book a 15-minute demo."
+```
+
+---
+
+## 4. Banned Structural Patterns
+
+### The "X. Here's why." or "X. And it matters."
+```
+❌ "Your landing page is your first impression. And it matters."
+❌ "Speed matters. Here's why."
+
+AI loves these one-two punch patterns because they simulate
+dramatic pacing. In practice they feel formulaic.
+
+Instead: Combine into one punchy sentence, or just make the case.
+✅ "First impressions close deals. Your landing page IS the first impression."
+```
+
+### Mirrored parallel structure (in every section)
+```
+AI tends to give every feature card or benefit the identical structure:
+
+❌ "Build faster. Launch sooner. Grow quicker."
+❌ "[Verb] your [noun]. [Verb] your [noun]. [Verb] your [noun]."
+
+Vary the structures across cards. Mix questions, statements, and fragments.
+✅ Card 1: "Live in 3 minutes."
+✅ Card 2: "No developer needed."
+✅ Card 3: "Looks like you hired a designer. You didn't."
+```
+
+### The "Challenges" / "Despite" pattern
+```
+❌ "Despite the challenges..."
+❌ "While there are challenges, the future looks bright."
+❌ "Challenges remain, but progress continues."
+
+This is the AI equivalent of throat-clearing. On a landing page,
+you never acknowledge your own challenges. You solve the visitor's.
+```
+
+### Symmetrical section structure
+```
+AI tends to make every section feel identical:
+  Uppercase label → Big headline → Subtitle → Grid of cards → CTA
+
+Vary the rhythm. See CONTENT.md for section-level layout variation.
+Not every section needs a subtitle. Not every section needs cards.
+Some sections should just be one bold sentence and a button.
+```
+
+---
+
+## 5. Positive Writing Rules (What TO Do)
+
+### Be concrete, not abstract
+```
+AI defaults to abstraction because it hasn't lived in the real world.
+The single most effective anti-AI move is specificity.
+
+❌ "Our comprehensive solution streamlines your workflow."
+✅ "Cut 4 hours off your weekly page-building time."
+
+❌ "Fast, reliable service."
+✅ "Average response time: 42 minutes."
+
+❌ "Trusted by thousands of businesses."
+✅ "Trusted by 2,847 HubSpot teams since 2024."
+
+❌ "Affordable pricing."
+✅ "Starts at €29/month. Cheaper than your Spotify family plan."
+```
+
+### Use plain, short words
+```
+Prefer the 4th-grade word over the SAT word.
+Prefer Anglo-Saxon over Latin-derived words.
+
+❌ utilize    → ✅ use
+❌ commence   → ✅ start
+❌ facilitate → ✅ help
+❌ sufficient → ✅ enough
+❌ subsequent → ✅ next
+❌ implement  → ✅ set up, add, build
+❌ acquisition → ✅ getting, buying
+❌ methodology → ✅ method, approach, way
+```
+
+### Vary sentence length aggressively
+```
+AI writes in a metronomic 15-20 word range. Every sentence roughly the same.
+Humans don't do that.
+
+Mix:
+- Very short. (2-5 words.)
+- Medium sentences that carry the argument forward. (10-15 words.)
+- Occasional longer ones that stack up detail and create rhythm through
+  their length, pulling the reader along before landing on a point. (25+ words.)
+
+Read your copy out loud. If you can't hear the rhythm change,
+it's too uniform.
+```
+
+### Write like you'd explain it in a bar
+```
+The "bar test" from CONTENT.md applies to tone too.
+Would a smart friend say this sentence out loud?
+
+❌ "Our platform empowers businesses to seamlessly create
+    high-converting landing pages leveraging AI technology."
+
+✅ "Tell us about your business. We'll build you a landing page.
+    Takes about two minutes."
+
+If you wouldn't say it to someone holding a beer, rewrite it.
+```
+
+### Let sentences breathe
+```
+Not every sentence needs a modifier. Not every noun needs an adjective.
+
+❌ "Our innovative, cutting-edge, AI-powered platform."
+✅ "Our platform."
+
+❌ "Beautiful, responsive, modern landing pages."
+✅ "Landing pages that look good on every screen."
+
+One adjective per noun, maximum. Zero is often better.
+```
+
+### Front-load the benefit
+```
+Humans scan. Put the payoff in the first 5 words, not the last 5.
+
+❌ "With our advanced technology and years of experience,
+    we help you build pages faster."
+✅ "Build pages faster. Our tech handles the rest."
+
+❌ "By leveraging the power of AI, you can create
+    professional-looking landing pages in minutes."
+✅ "Professional landing pages in minutes. AI does the heavy lifting."
+```
+
+### Make testimonials sound like real humans
+```
+AI testimonials are obvious because they're too polished and too positive.
+
+❌ "This platform has been an absolute game-changer for our business.
+    The seamless experience and innovative features have transformed
+    our workflow entirely." — John D., CEO
+
+✅ "We used to spend a full day building landing pages. Now my
+    marketing intern does it in her lunch break. Honestly didn't
+    think that was possible." — Sarah Chen, Head of Marketing, Boxflow
+
+Rules for believable testimonials:
+- Include a specific problem that was solved
+- Include a concrete detail (time saved, money saved, specific task)
+- Keep them slightly imperfect in structure (fragments OK)
+- Names should be full names, not "John D."
+- Roles should be specific, not just "CEO"
+- Allow mild hedging ("honestly didn't think", "I was skeptical")
+- Vary length: some short (1 sentence), some longer (2-3 sentences)
+- Never start with "This product is..." — start with the person's situation
+```
+
+---
+
+## 6. Quick-Reference Banned Word List (for automated scanning)
+
+Copy this list into a linter or post-processing check. If any of these
+appear in generated copy, flag for rewrite:
+
+```
+HARD BANNED (always rewrite):
+delve, delving, tapestry, multifaceted, utilize, utilizing,
+harness, harnessing, bolster, underscore, illuminate, facilitate,
+fostering, garner, pivotal, commence, endeavor, myriad, plethora,
+pertinent, aforementioned, wherein, henceforth, beacon, synergy,
+paradigm, bespoke, holistic, spearhead, embark, reimagine,
+cultivate, cornerstone
+
+SOFT BANNED (rewrite unless truly specific and earned):
+seamless, seamlessly, cutting-edge, groundbreaking, game-changer,
+game-changing, revolutionary, transformative, innovative, innovation,
+robust, comprehensive, foundational, nuanced, landscape (abstract),
+realm, catalyst, empower, empowering, elevate, unlock, streamline,
+optimize, curated, navigate (abstract)
+
+BANNED PUNCTUATION:
+— (em dash)
+
+BANNED OPENERS (any sentence/heading starting with):
+"In today's", "In an era", "In the realm", "Whether you're",
+"Are you tired", "Imagine a world", "Picture this", "Here's the thing",
+"Here's the deal", "Let's face it", "Look no further",
+"Say goodbye to", "Gone are the days", "It's no secret",
+"At its core", "At the end of the day", "When it comes to"
+
+BANNED CLOSERS (any section/page ending with):
+"The future of [X] is here", "Your journey starts here",
+"Join the revolution", "Experience the difference",
+"See what's possible", "Ready to take the next step",
+"The question isn't whether"
+
+BANNED STRUCTURES:
+"It's not about X, it's about Y"
+"It's not just X, it's Y"
+"[X]. Here's why."
+"[X]. And it matters."
+"Despite the challenges"
+```
+
+---
+
+## 7. The Final Sniff Test
+
+After generating any page copy, read it once and ask:
+
+1. **Could I picture a specific human saying this out loud?** If not, rewrite.
+2. **Can I see/touch/count the thing being described?** If not, make it concrete.
+3. **Does every sentence sound roughly the same length?** If yes, vary it.
+4. **Are there more than zero em dashes?** If yes, remove them all.
+5. **Does the page have any word from the HARD BANNED list?** If yes, swap it.
+6. **Do the testimonials sound like they were written by the same person?** If yes, rewrite with different voices, lengths, and structures.
+7. **Would a HubSpot marketer on their third coffee read this and think "yeah, that sounds like us"?** That's the bar.
+
+---
+
+*These rules work best alongside CONTENT.md (for content density and structure) and CLAUDE.md (for visual design). Together they ensure vibeSpot outputs pages that look AND read like a human team built them.*