oil-oil/citycraft

Landing Page Builder

Philosophy

This skill produces landing pages that are visually audacious — not the typical nested-container, card-grid, predictable web template. Every output should feel like a deliberate design artifact:

• Bold layout — Clip-path dividers instead of horizontal lines. Type bleeding off-screen. Elements breaking out of their grid. Full-viewport headlines.
• SVG as a design core — Not decorative sprinkles. SVG paths animate on scroll, icons have personality, background textures from <feTurbulence> noise.
• Layered depth — GSAP ScrollTrigger creates genuine spatial depth: sections that overlap and cover the previous one, sticky panels pinned while content slides over them, parallax on separate z-layers.
• Textured backgrounds — Every section has texture. Never a flat solid background.
• Surprising navigation — The nav is never a standard horizontal bar.

---

Bundled Assets (USE THESE — do not reinvent)

This skill comes with pre-built assets. Read and use them directly:

File	What's in it	When to use
assets/style-preview-template.html	57-city style preview cards	Step 2: sed fill __PRODUCT_NAME__ + __PRODUCT_HEADLINE__, save as style-preview.html, open
assets/options-preview-template.html	Interactive demos: nav styles, color variants, transition styles, hero/features/testimonials variants	Step 3: sed fill city color tokens + product name, save as options-preview.html, open
assets/textures.css	6 CSS texture classes (.texture-kyoto, .texture-paris, .texture-tokyo, etc.)	Copy the matching class into style.css
assets/gsap-snippets.js	6 GSAP animation functions (blur entrance, line reveal, parallax, sticky steps, blast menu, magnetic pill)	Copy the relevant functions into main.js
assets/clip-paths.css	8 clip-path divider classes (.clip-diagonal-br, .clip-parallelogram, .clip-arc-bottom, etc.)	Use at least 2 in style.css for section dividers
assets/sections/hero-variants.html	3 Hero section templates (full-screen sprawling / split-screen tension / minimal descending)	Step 4: pick the variant matching the user's typography preference, copy and adapt
assets/sections/features-variants.html	6 Features section templates (big numbers / alternating display / timeline / bento grid / horizontal scroll / Q&A expand)	Step 4: pick based on content type (stats → big number, how-it-works → timeline)
assets/sections/testimonial-variants.html	6 Testimonials templates (compact cards / single column quote / masonry collage / horizontal scroll / conversation bubbles / avatar wall)	Step 4: pick based on testimonial volume and visual style preference
assets/sections/conversion-variants.html	Pricing table, FAQ, brand wall, power CTA	Step 4: copy relevant section, all use CSS custom properties
references/product-demo-hero.md	Product demo hero principles + scene design guide	Read when user wants to show product workflow in hero (see Step 3/4)

The quality guarantee of this skill comes from using these assets. They encode specific design decisions that make outputs distinct. Don't describe what to do — copy the code and adapt it.

---

The Workflow

Step 1: Understand the Product

Reuse the product and style already provided by the user; only ask when product information is missing:

"Tell me about your landing page — the product/service name, and a one-sentence description."

If the user has already provided the product description, chosen a city, or delegated the decision to the Agent, proceed directly to the corresponding step.

Step 2–3: Optional Style & Layout Preview

Reuse directly if the user has already made a selection; if the Agent is choosing, read the relevant city entries, explain the rationale, and continue. When comparison is needed, generate local previews following the Preview Workflow. If no preview capability is available, present a few candidates in the conversation—do not treat opening a page as the user having made a choice.

Step 4: Generate the Landing Page

Output into {product-name}-landing/:

{product-name}-landing/
├── index.html
├── style.css
├── main.js
└── assets/
    └── icons.svg

4a — Bash Assembly (do this first, before writing any file)

The goal is to avoid outputting bundled asset code as model tokens. Instead, use Bash to copy and pipe the ready-made assets into the output files. Only product-specific content (copy, tokens, overrides) is written by the model.

Step 1 — Set up directories

_SKILL_DIR="<absolute directory of the current skill>"
_OUT="./{product-name}-landing"
mkdir -p "$_OUT/assets"

Step 2 — Assemble section variants into a staging file

Plan which variants to use (see table below), then pipe each into a staging file:

# Replace B / C / B / PRICING with the user's actual choices
python3 "$_SKILL_DIR/assets/scripts/extract_variant.py" \
  "$_SKILL_DIR/assets/sections/hero-variants.html" B > "$_OUT/_sections.html"
python3 "$_SKILL_DIR/assets/scripts/extract_variant.py" \
  "$_SKILL_DIR/assets/sections/features-variants.html" C >> "$_OUT/_sections.html"
python3 "$_SKILL_DIR/assets/scripts/extract_variant.py" \
  "$_SKILL_DIR/assets/sections/testimonial-variants.html" B >> "$_OUT/_sections.html"
python3 "$_SKILL_DIR/assets/scripts/extract_variant.py" \
  "$_SKILL_DIR/assets/sections/conversion-variants.html" PRICING >> "$_OUT/_sections.html"
python3 "$_SKILL_DIR/assets/scripts/extract_variant.py" \
  "$_SKILL_DIR/assets/sections/conversion-variants.html" CTA >> "$_OUT/_sections.html"

For testimonials use: A, B, C, D, E, F For conversion sections use: PRICING, COMPARE_PRICING, BRAND_WALL, CTA, FAQ_A, FAQ_B

Step 3 — Copy bundled CSS utilities into style.css base

# Texture: use --texture flag (never read full city-styles.md)
python3 "$_SKILL_DIR/assets/scripts/get_city_tokens.py" "CITY_NAME" --texture > "$_OUT/_texture.css"
# Clip-paths: copy all classes, model picks which to apply via class names
cat "$_SKILL_DIR/assets/clip-paths.css" >> "$_OUT/_texture.css"

Step 4 — Copy GSAP snippets into main.js base

cat "$_SKILL_DIR/assets/gsap-snippets.js" > "$_OUT/_gsap-base.js"

Now read the three staging files (_sections.html, _texture.css, _gsap-base.js) to understand what's available, then write the final output files.

4b — Section Variant Reference

Common page sequences:

• SaaS tool: Hero D → Features C → Features A → Testimonials A → Pricing → FAQ A → CTA
• Agency portfolio: Hero A → Features B → Testimonials C → CTA
• Developer tool: Hero B → Features C → Features A → Testimonials A → Pricing → FAQ B → CTA
• Luxury product: Hero C → Features B → Testimonials B → CTA
• B2C app: Hero E → Features E → Testimonials F → CTA

If the user needs...	Use this template	Variant
Hero — massive bold statement	Full-screen sprawling	A
Hero — product visual + headline	Split-screen tension	B
Hero — elegant, story-first	Minimal descending	C
Hero — product has a workflow to show	Product demo type	D (also read references/product-demo-hero.md)
Hero — typography-led, high-impact	Text explosion type	E
Hero — editorial storytelling	Magazine tear type	F
Hero — playful product launch	Pop-out card type	G
Features — data/metrics focus	Big numbers	A
Features — product screenshots	Alternating display	B
How it works — step-by-step	Timeline	C
Features — modular story blocks	Bento grid type	D
Features — browseable capability ribbon	Horizontal scroll carousel type	E
Features — objection handling	Q&A expand type	F
Pricing table	Pricing table	PRICING
Pricing comparison with toggle	Compare pricing table	COMPARE_PRICING
Testimonials — compact grid	Compact card grid	A
Testimonials — magazine style	Single column quote wall	B
Testimonials — masonry layout	Masonry collage	C
Testimonials — horizontal scroll	Horizontal scroll strip	D
Testimonials — conversation bubbles	Conversation bubbles	E
Testimonials — avatar wall	Video avatar wall	F
Trusted brand logos	Brand wall	BRAND_WALL
Final CTA	Power CTA section	CTA
FAQ — editorial layout	Editorial layout type	FAQ_A
FAQ — card grid	Full-width focus type	FAQ_B

4c — Write the Output Files

index.html — Write with the Write tool. No markdown block, directly to file.

• Document structure: <html>, <head> (Google Fonts, GSAP CDN, link to style.css + main.js), <body>
• Nav HTML matching the selected nav style
• Paste <style> blocks and <section> HTML from _sections.html in page order
• Replace all placeholder copy with real product copy — fit the city aesthetic's tone of voice
• No Lorem Ipsum, no placeholder text
• Break template uniformity: vary visual weight across items within each section. The template shows a repeating pattern — make one item the focal point (accent background, larger card, featured badge, different internal layout) and let others recede. No section should look like a grid of clones.

<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollTrigger.min.js"></script>

style.css — Write with the Write tool. Structure:

1. :root block — full design token system: colors from $CITY_* tokens, chosen fonts, spacing scale, radii. This is the only part the model writes from scratch.
2. Paste texture + clip-path CSS from _texture.css
3. Nav CSS matching the selected nav style (from references/nav-catalog.md)
4. Layout and typography overrides — only what differs from section defaults

clamp() for ALL headline font sizes:

• Hero main heading: clamp(2.8rem, 7vw, 7rem) — even sprawling type does not exceed 7rem
• Section heading: clamp(2rem, 4vw, 4rem)
• Big numbers / decorative numbers: clamp(4rem, 10vw, 9rem)
• Subheadings / body text: clamp(1rem, 1.4vw, 1.2rem)

Do NOT add comments to style.css — they consume tokens and add no value to the output file.

main.js — Write with the Write tool. Structure:

1. gsap.registerPlugin(ScrollTrigger)
2. Paste the relevant functions from _gsap-base.js — required minimum:
   • initHeroEntrance() — stagger hero elements in
   • initParallax() — at least 2 layers at different speeds
   • Section heading reveals on viewport entry
   • initStickySteps() OR initBlastMenu() OR initMagneticPill() — matching nav/layout
3. Call sequence at bottom; ScrollTrigger.refresh() after fonts load

Do NOT add comments to main.js.

assets/icons.svg — SVG sprite with <symbol> elements. At minimum: logo mark, nav toggle, arrow, checkmark, 2–3 product-relevant feature icons. Icon style must match the city aesthetic's stroke weight and geometry.

After all files are written, delete the staging files:

rm -f "$_OUT/_sections.html" "$_OUT/_texture.css" "$_OUT/_gsap-base.js"

---

Design Laws (Never Break These)

1. No #ffffff backgrounds. Not on sections, not on cards. Warm neutrals: #f5ede0. Cool: #edf0ee. Dark: #08060f. Cards get a slight tint, never pure white.
2. No #6366f1. Color comes from the city style palette.
3. Decide the transition type independently for each section boundary. Every pair of adjacent sections has its own visual relationship — don't reuse the same clip-path class everywhere. The user chooses a transition direction (geometric sharp / organic soft / cover-blend / minimal line / AI auto) in the options preview. Use that direction to constrain which classes you pick: GEOMETRIC → diagonals, chamfers, steps; ORGANIC → curves, scallops, arcs; BLEND → cover overlays and gradient dissolves; MINIMAL → hairline rules. If __AI_CHOOSE__, scan the selected city's entry in references/city-styles.md for divider/transition language first. Then apply per-boundary logic: consider what the two sections are (hero → features, features → pricing, etc.), their relative energy, and the overall page rhythm. Available classes in assets/clip-paths.css: diagonal (clip-diagonal-*, clip-parallelogram), curved (clip-round-bottom, clip-scallop, clip-arc-bottom), gradient dissolve (section-dissolve), flat rule (section-rule).
4. No generic icons. Match the city style's stroke weight and geometry.
5. Two typefaces minimum. Display/serif for headlines + clean sans for body. From references/city-styles.md. Decorative/script accent fonts (when a city style mentions one) go on watermarks, pull quotes, or ornamental elements — never on buttons, nav, or body copy.
6. Nav must surprise. Use the chosen nav from references/nav-catalog.md with its full surprise element implemented.
7. Use bundled assets. The texture, GSAP snippets, and clip-paths must come from the skill's asset files — not reimplemented from scratch.
8. .line-wrap CJK fix. Whenever the page has Chinese or Japanese text and uses .line-wrap { overflow: hidden } for line reveal animations, add padding-top: 0.15em; margin-top: -0.15em; to prevent CJK ascenders from being clipped at the top.
9. No clone grids. When a section contains multiple repeating items (feature rows, pricing cards, FAQ items, testimonials), they must not all share the same visual treatment. One item should be the focal point — larger, accented, or with a distinct layout — while others form the supporting cast. A section should feel like a poster with visual hierarchy, not a spreadsheet of identical rows. This is the single biggest cause of pages looking "templated" rather than designed.

---

Reference Files

• references/city-styles.md — Exact design parameters (fonts, colors, textures, motion, icons) for each city aesthetic
• references/nav-catalog.md — 4 nav styles with full implementation notes and GSAP code
• references/imagery-derivation.md — How to translate any non-city description (scene, era, material, emotion) into a concrete design token system. Read this whenever the user describes something that isn't one of the 57 city cards.
• references/product-demo-hero.md — When and how to build a time-driven product workflow demo in the Hero (Variant D). Includes scene design guide, 3-act structure, onEnter() callback patterns, and product-type → scene mapping table. Read this whenever the user wants to show their product's process in the hero.

Facts & Degradation

Testimonials, customer logos, numbers, and prices in templates are structural examples only; if no evidence is available, delete them or replace with real product descriptions—do not fabricate endorsements. The implementation must support keyboard operation, prefers-reduced-motion, and static readable content when scripts or CDN loads fail. Visual acceptance notes must specify the actual viewports and states checked; do not claim visual acceptance if rendering has not occurred.