How medhachoum/cinematic-landing-kit works
1. What this repository is
This is not a production app codebase; it is a prompted build system / knowledge pack for generating cinematic landing pages with Claude Code. The repo’s job is to supply persistent project memory, a ready-made HTML scaffold, and Higgsfield prompt structure so the generated page is consistent, luxurious, and visually coherent.
2. Top-level architecture
The repo is organized into three layers:
- Execution guidance: CLAUDE.md
- Domain memory / rules: memory/*.md
- Implementation templates: templates/*
That separation is the key architectural boundary: the model reads instructions and rules first, then fills a working skeleton rather than inventing the system from scratch.
3. CLAUDE.md as the entrypoint
CLAUDE.md is the operational contract for Claude Code. It likely contains the condensed workflow, quality gates, and the order in which the memory files should be consulted. In architecture terms, it is the bootstrap layer that tells the agent how to behave for every project using this kit.
4. memory/ as persistent design policy
The nine memory files are the real “architecture spec” of the kit. They encode:
- page construction playbook
- scroll-film canvas strategy
- seamless section transitions
- cinematic hero behavior
- theming and blend-mode constraints
- Higgsfield generation pipeline
- modesty / identity rules
- preview and environment gotchas
- quality bar and rejection criteria
This folder functions as a policy and tribal-knowledge layer, preventing the agent from repeating known mistakes.
5. Main rendering model: scroll-driven cinematic page
The landing page is architected around a scroll-film experience rather than conventional static sections. The core idea is:
- scroll position drives cinematic progression
- visuals change as a sequence of scenes
- transitions are designed to feel like continuous film edits, not discrete page jumps
The readme emphasizes a “Apple × Cartier / Hermès” aesthetic, so the architecture prioritizes motion, atmosphere, and typographic restraint over component density.
6. Asset-generation pipeline via Higgsfield
A major subsystem is the visual asset pipeline. Higgsfield is used to generate:
- reference-informed key visuals
- matching boundary frames between scenes
- frame sequences for film-like sections
- transparent cutouts for the hero
- web-optimized outputs after validation
The pipeline is driven by prompt templates and controlled by the memory rules, which enforce consistency of identity and style across generated assets.
7. Template-driven page assembly
templates/index.skeleton.html is the implementation scaffold for the final landing page. The readme describes it as already working, with only placeholders to fill. This suggests the final page is assembled by replacing templated values rather than authoring from scratch.
Architecturally, this makes the HTML skeleton the composition layer where generated copy, theming choices, and assets are bound into a complete landing page.
8. Prompting contract for asset creation
templates/HIGGSFIELD-PROMPTS.template.md is a structured prompt template for producing assets. Its role is to standardize the input to Higgsfield so the generated outputs share:
- consistent product identity
- correct modesty constraints
- matching scene boundaries
- stable visual language
This is an important boundary: prompts are treated as versioned templates, not ad hoc text.
9. Preview and local validation
templates/launch.json points to a static preview workflow. The repo expects validation in a real browser, not a hidden tab. The architecture therefore includes a manual visual QA loop: generate assets, assemble page, open preview, inspect motion and appearance, then refine.
10. Technology and runtime constraints that affect architecture
The repo’s architecture is shaped by several explicit runtime rules:
- Canvas-based sequence rendering instead of controlling video playback directly
- Node.js for static preview serving
- Python + OpenCV for frame extraction
- awareness that hidden tabs can pause animation
- avoidance of brittle tooling assumptions like jq/ffmpeg in the pipeline
These constraints matter because they define what kinds of automation are reliable in the workflow.
11. Visual system boundaries
The memory docs enforce strong boundaries around visual identity:
- the hero is animated and atmospheric, not a static image with fade
- transparent cutouts are preferred for moving elements because blend modes break under transforms
- transitions between sections should be boundary-matched, not crossfaded from unrelated stills
- theme is chosen per product and must remain consistent across all assets
In diagram terms, the visual system is a set of constrained modules rather than freely composable effects.
12. Overall data flow
The end-to-end flow is:
product brief + reference image → Claude reads CLAUDE.md and memory → theme/story/structure decisions → Higgsfield prompt generation → visual asset creation and validation → HTML skeleton population → local preview and QA → final polished landing page
That is the core architecture of the repository: a repeatable creative production pipeline with explicit knowledge, controlled generation, and browser-based verification.
Main entry points: CLAUDE.md CLAUDE.md · 06-higgsfield-pipeline.md Higgsfield Pipeline · index.skeleton.html HTML Skeleton · HIGGSFIELD-PROMPTS.template.md Prompt Template
Components 16
Bootstrap
Operational entrypoint and repo overview
Policy Memory
Persistent rules for cinematic landing generation
- Build Playbook · Page construction process and generation sequence
memory/01-build-playbook.md - Scroll Film · Scroll-driven cinematic page architecture and scene progression
memory/02-scroll-film-canvas.md - Transitions · Rules for seamless section boundaries and matched visual handoffs
memory/03-seamless-transitions.md - Cinematic Hero · Behavior and constraints for the animated hero treatment
memory/04-cinematic-hero.md - Theming · Theme selection, blend-mode limits, and consistency constraints
memory/05-theming.md - Higgsfield Pipeline · Prompt-to-asset generation flow for scene visuals and cutouts
memory/06-higgsfield-pipeline.md - Modesty Rules · Product identity and modesty constraints for generated visuals
memory/07-modesty-and-identity.md - Env Gotchas · Preview and environment caveats that affect validation and motion behavior
memory/08-preview-and-env-gotchas.md - Quality Bar · Review criteria and rejection conditions for final output
memory/09-quality-bar.md
Templates
Implementation skeletons and prompt contracts
- HTML Skeleton · Ready-made landing page structure populated from generated content and assets
templates/index.skeleton.html - Prompt Template · Structured Higgsfield prompt format for generating consistent assets
templates/HIGGSFIELD-PROMPTS.template.md - Launch Config · Static preview launch setup for local browser-based validation
templates/launch.json
Other components
- Brief Flow · Product brief and reference image to theme, prompts, assets, HTML, and preview
- QA Loop · Browser inspection and iterative refinement after asset generation and page assembly
Connections 22
- README → CLAUDE.md: documents · The README explains the kit and how the operational entrypoint is used
- CLAUDE.md → Build Playbook: loads · Claude Code consults the build workflow first
- CLAUDE.md → Scroll Film: loads · Bootstrap instructions point to the scroll-film page model
- CLAUDE.md → Transitions: loads · Bootstrap instructions include the handoff rules between scenes
- CLAUDE.md → Cinematic Hero: loads · Hero behavior is part of the core execution contract
- CLAUDE.md → Theming: loads · Theme and style constraints are consulted during generation
- CLAUDE.md → Higgsfield Pipeline: loads · Asset generation pipeline guidance is part of the core flow
- CLAUDE.md → Modesty Rules: loads · Identity and modesty constraints must be applied during generation
- CLAUDE.md → Env Gotchas: loads · Preview and runtime caveats influence how the kit is executed
- CLAUDE.md → Quality Bar: loads · Acceptance criteria govern final output quality
- Build Playbook → Brief Flow: orchestrates · The playbook coordinates the end-to-end production flow
- Brief Flow → Prompt Template: generates · Brief and reference inputs are turned into structured Higgsfield prompts
- Prompt Template → Higgsfield Pipeline: drives · The prompt template feeds the asset generation pipeline
- Higgsfield Pipeline → QA Loop: produces · Generated assets are validated in-browser before final assembly
- QA Loop → HTML Skeleton: fills · Validated copy and assets populate the HTML scaffold
- HTML Skeleton → Launch Config: served by · The page is opened through the local preview launch config
- Scroll Film → HTML Skeleton: shapes · The scroll-film model determines how the HTML page is structured
- Transitions → Higgsfield Pipeline: constrains · Scene boundaries guide how matching assets are generated
- Cinematic Hero → Theming: constrains · Hero treatment must stay within the selected theme
- Modesty Rules → Prompt Template: constrains · Prompt generation must preserve product identity and modesty rules
- Env Gotchas → QA Loop: warns · Runtime caveats affect how preview validation is performed
- Quality Bar → QA Loop: checks · The quality bar defines what the visual review should reject or accept