Spec: IceGraph marketing landing page (separate repo)

[YanivZalach]

Goal

Create a dedicated marketing landing page for IceGraph: a visitor who has never heard of IceGraph should understand what it is and why they need it within the first screen, and should leave with an obvious next step (try the live demo, or run it against their own tables).

This is not the app and not the docs page. It is the front door that sends people to them.

The page needs to do its best to popup as the first result when a user is typing icegraph, and iceberg.

Where it lives

A separate repository from YanivZalach/IceGraph. GitHub allows only one Pages site per repo, and this repo's Pages site is already the live app demo (/IceGraph/). The landing page needs its own repo so it can deploy on its own schedule (the app demo only deploys on v* tags).

This ticket specs the page. Repo creation, stack, and deploy setup are open items (see below).

Audience

Data / platform engineers who already run Apache Iceberg in production, plus engineers trying to learn Iceberg internals. They are technical, skeptical of marketing language, and want to see the product before reading about it.

Message the page must land

1. What it is: an interactive, read-only debugger and visualizer for Apache Iceberg table metadata.
2. Why it matters: Iceberg table state is opaque. Snapshots, manifests, delete files, and rewrite operations are hard to reason about from SQL alone, so debugging a bad table state means digging through metadata by hand.
3. What changes: IceGraph renders the metadata as a navigable graph and timeline, so the table's structure and its evolution are visible directly.
4. Why it is safe to try: read-only by design, never modifies data or metadata, and can run against a read-only Spark Connect user.

Page structure

Section by section, described by what the visitor sees and understands. Ordering matters; each section should earn the scroll to the next.

1. Hero (above the fold)

• One-line statement of what IceGraph is, readable in under three seconds.
• One supporting line on the problem it solves.
• Two calls to action: a primary one that opens the live demo, and a secondary one that goes to the GitHub repo.
• A product visual dominating the fold, not a stock illustration. The graph view is the strongest asset here. It should feel alive (subtle motion, or a short looping capture) rather than a flat screenshot.
• Visitors should be able to tell this is a real, working tool before scrolling.

2. The problem

• Short, concrete framing of what debugging an Iceberg table looks like today: opaque snapshot history, manifests and delete files that are hard to inspect, no way to see how a table got into its current state.
• Should read as recognition, not as a sales pitch. If an Iceberg user does not nod here, the rest of the page will not convert.
• Keep it tight, a few beats, not paragraphs.

3. What you actually see

• The core of the page: show the product's distinct views and what each one answers.
  • Graph view: the metadata hierarchy, snapshots down to manifests and data files, across branches.
  • Timeline: how the table evolved, commit by commit, including operation types such as rewrites.
  • Metadata view: the table's current spec and properties.
  • File tree: partitions and files in a familiar hierarchical browser.
• Each view gets a visual plus one line on the question it answers. Visual first, text second.
• A visitor should be able to skim only the images and still understand the product surface.

4. Why it is production safe

• Read-only by design, no writes to data or metadata.
• Works against a read-only Spark Connect user.
• This section exists to remove the single biggest objection (pointing a debugging tool at production), so it should be short, plain, and unmissable.

5. Get started

• The fastest path to a running instance, presented as a copyable command.
• Second path for scripted access via the Python client and CLI.
• Should communicate "this takes a minute, not an afternoon."
• Any command shown must be copyable in one click.

6. Scope and honesty

• State the opinionated constraints plainly: Spark Connect only, Iceberg table format version 2.
• Being upfront here filters out bad-fit visitors and builds trust with good-fit ones. It should read as a design decision, not as an apology.

7. Footer

• Links to the live demo, GitHub repo, docs, Docker Hub, PyPI, and the roadmap board.
• Nothing else competing for attention.

Visual direction

• Dark, high contrast, developer-tool aesthetic. Should feel adjacent to the app itself so arriving at the demo is not jarring.
• Take cues from strong modern developer product pages (t3 code was the reference given): generous vertical space, a large confident hero, product imagery doing most of the work, and very little body text per section.
• Motion used sparingly and with purpose: reveal on scroll, subtle depth in the hero. Nothing that delays the first meaningful paint or fights the reader.
• Typography carries the hierarchy. One display weight for section openers, one readable body size, no more than two type scales competing.
• Product visuals need real breathing room. Screenshots should be framed (device or panel chrome, soft shadow) rather than dropped flat on the background.
• No stock photography, no generic 3D blobs, no illustrated personas.

Quality bar

• Reads correctly on mobile, including the hero. Product visuals must stay legible at phone width, cropped or swapped if needed.
• Loads fast on a cold visit. Large captures or video should not block the hero from rendering.
• Accessible: real contrast ratios, keyboard reachable links and buttons, meaningful alt text on product imagery, and motion that respects reduced-motion preferences.
• Correct social preview (title, description, image) when the link is shared.

Success criteria

• A first-time visitor can state what IceGraph is after the hero alone.
• A first-time visitor can state why they would use it after one scroll.
• The live demo is reachable from the fold and from the footer.
• Nothing on the page contradicts the product's actual scope (Spark Connect, table v2, read-only).