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.