TenantAtlas/specs/218-homepage-hero/data-model.md

Data Model: Website Homepage Hero

This feature introduces no database schema and no platform-side persistence. The model is file- and route-based inside apps/website and defines how the homepage hero expresses product truth, CTA hierarchy, early trust cues, and the next-step path.

1. Homepage Hero Source Object

Represents the hero content exported from apps/website/src/content/pages/home.ts.

Field	Type	Description	Rules
eyebrow	string	Short positioning cue or category context	Required; must anchor the hero in a believable category or problem space
title	string	Primary positioning headline	Required; must frame product, problem, or outcome without hype language
description	string	Supporting copy	Required; must sharpen the headline in plain product language
primaryCta	CtaLink	Dominant next-step action	Required; exactly one dominant primary CTA
secondaryCta	CtaLink	Secondary deepening action	Required for Spec 218 hero contract; must remain lower-emphasis than the primary CTA
productVisual	HeroVisualContent	Product-near screenshot or stylized product shot	Required by the hero contract unless a temporary explicit exemption is documented
trustSubclaims	string[]	Optional early trust cues	Optional; must remain short, factual, and bounded
highlights	string[]	Optional lightweight support points	Optional; should not compete with trust subclaims when both exist

Relationships:

• Rendered by apps/website/src/components/sections/PageHero.astro
• Consumed by apps/website/src/pages/index.astro
• Secondary truth for trust-facing claims must remain compatible with apps/website/src/content/pages/trust.ts

Validation rules:

• Exactly one primary CTA and one secondary CTA must remain visible as the hero action pair
• Headline and description must not collapse into generic SaaS phrasing or stacked claims
• Trust subclaims must never become a badge wall or imply legal or compliance guarantees

2. Hero CTA Pair

Represents the two hero actions as one intentional routing pair.

Field	Type	Description	Rules
primary	CtaLink	Primary next-step action	Must lead to /contact, /demo, or an equivalent explicitly approved next step
secondary	CtaLink	Lower-emphasis exploration route	Must lead to a maintained informational surface such as /product, /trust, or /changelog
dominance	derived UI property	Relative emphasis between the two CTAs	Primary must remain visually dominant
reachability	derived route truth	Whether the linked routes are real and maintained	Hero must not point to placeholder or immature surfaces

Validation rules:

• The pair must communicate one clear next step and one clear deepening path
• Multiple equally dominant primary sales actions are forbidden

3. Hero Visual Asset

Represents the product-near media used in the hero.

Field	Type	Description	Rules
src	string	Public asset path	Must resolve to a maintained hero asset in apps/website/public or equivalent
alt	string	Accessibility text for the visual	Must describe product-relevant UI truth, not generic marketing scenery
truthBasis	derived review rule	Why the visual is considered product-near	Must be traceable to real product structure or a truthful simplification
mobilePersistence	derived render rule	Whether the visual remains visible on small screens	Must stay visible when it is a key credibility signal

Validation rules:

• No fantasy metrics, fake dashboards, or unrelated analytics wallpaper
• Cropping or stylization is allowed only when product structure remains clear

4. Trust Subclaim Set

Represents the optional early-trust layer inside the hero.

Field	Type	Description	Rules
claims	string[]	Short factual trust cues	Optional; should remain few and concise
supportRoute	route or derived surface	Where deeper trust context lives	Normally /trust
visibility	derived render rule	When trust cues are shown	Show only when claims are supportable and do not compete with the hero core

Validation rules:

• Claims must be factual and publicly supportable
• Claims must not imply absolute compliance, security, or hosting guarantees
• Trust cues must support the hero, not overrun it

5. Hero Render Contract

Represents the semantic structure that PageHero.astro must preserve.

Element	Role	Requirement
Category context	Early positioning cue	Must appear before or adjacent to the headline
Headline	Primary positioning statement	Must remain the dominant text signal
Supporting copy	Headline clarification	Must remain directly associated with the headline
CTA pair	Action transition	Must keep one dominant primary and one lower-emphasis secondary action
Product-near visual	Product truth signal	Must remain part of the hero composition
Optional trust subclaims	Early credibility cues	Must stay secondary to product and CTA understanding

Mobile meaning order:

• headline and supporting copy
• CTA pair
• product-near visual
• optional trust signals

Derived State and Availability

• No independent state machine is added by this feature.
• Hero route availability remains derived from the homepage route at /.
• Hero CTA reachability remains derived from canonical public routes in apps/website.
• Trust-subclaim legitimacy remains derived from public website truth, especially the Trust surface.
• Product-visual readiness remains asset-based; if the current visual stops being truthful enough, it must be replaced rather than papered over with abstraction.