TenantAtlas/specs/400-tenantial-homepage-visual-rebuild/spec.md

Feature Specification: Tenantial Homepage Visual Rebuild

Feature Branch: 400-tenantial-homepage-visual-rebuild
Created: 2026-05-17
Status: Implemented (ready to merge)
Input: User description: "Rebuild the public website homepage for Tenantial to match a premium dark enterprise SaaS mockup direction, positioning Tenantial as evidence-first governance for Microsoft tenants."

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: The public homepage still carries generic SaaS/template signals and does not clearly position Tenantial as a serious Microsoft tenant governance product.
• Today's failure: Visitors can leave without understanding that Tenantial focuses on backup, restore, drift detection, evidence, audit trails, and structured governance reviews for Microsoft tenants.
• User-visible improvement: The homepage immediately communicates Tenantial's evidence-first governance value, uses a distinct premium dark identity, and shows a product-near static dashboard preview without implying live data.
• Smallest enterprise-capable version: Rebuild only the public homepage and the shared public shell needed by that page: header, hero, static dashboard preview, trust bar, feature pillars, call to action, footer, SEO metadata, homepage smoke expectations, and minimal public-page brand consistency where globally reachable pages would otherwise mix Tenantial and TenantAtlas.
• Explicit non-goals: No platform UI, no Filament/admin changes, no authentication flow, no CMS, no backend data, no demo-booking backend, no database changes, no Microsoft Graph integration, and no full multi-page website build.
• Permanent complexity imported: Public homepage brand direction, static marketing content, a static product-preview concept, homepage smoke coverage, and brand/SEO cleanup expectations.
• Why now: The project needs one credible Tenantial homepage direction before expanding into platform, pricing, trust, resources, or company pages.
• Why not local: Page-local copy changes alone would leave brand hierarchy, navigation intent, trust boundaries, product-preview language, and template cleanup inconsistent.
• Approval class: Core Enterprise
• Red flags triggered: None. The work creates no persisted truth, no domain state, no runtime abstraction, and no cross-domain UI framework.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 2 | Wiederverwendung: 1 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: Public website homepage. This is outside workspace, tenant, and canonical admin scopes.
• Primary Routes: /
• Data Ownership: Static public website content and static marketing preview data only. No workspace-owned, tenant-owned, platform runtime, or persisted application data is introduced.
• RBAC: None. The homepage is public and introduces no authorization behavior.

Relationship To Existing Website Specs

• Spec 223 remains the historical AstroDeck reset/rebuild frame.
• Spec 214 remains useful background for website visual discipline.
• Spec 215 remains useful for public information architecture principles.
• Spec 217 and Spec 218 remain background for homepage structure and hero discipline.
• Spec 400 is the concrete homepage implementation slice for the Tenantial mockup direction.
• Spec 400 owns the homepage implementation direction where the Tenantial mockup direction is more specific than the older AstroDeck-era homepage specs.
• Spec 400 permits website-local homepage presentation components for this slice only. It does not create a reusable public-site framework and does not broaden the AstroDeck reset into platform/admin code.
• No specs/227-* artifact is present in the current checkout. No phantom Spec 227 is created here; Spec 400 replaces the previously discussed homepage/visual-foundation path for the homepage only.

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

N/A - no shared operator interaction family touched. This feature changes a public marketing homepage, not admin notifications, operator status messaging, operation links, dashboard signals, alerts, report viewers, or other shared operator interaction contracts.

OperationRun UX Impact (mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an OperationRun; otherwise write N/A - no OperationRun start or link semantics touched)

N/A - no OperationRun start, completion, deduplication, resume, block, or link semantics touched.

Provider Boundary / Platform Core Check (mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write N/A - no shared provider/platform boundary touched)

N/A - no shared provider/platform boundary touched. The homepage may describe Microsoft tenant governance at a marketing level, but it does not change platform-core contracts, provider seams, identity scope, compare strategy, governed-subject taxonomy, or runtime vocabulary.

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

N/A - no operator-facing surface change. This feature changes a public marketing surface only and does not affect Filament/admin pages, tenant-scoped operator workflows, shared operator components, action surfaces, or governance decision surfaces.

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: Yes, limited to public homepage brand/content direction. No product runtime or tenant-governance truth is introduced.
• New persisted entity/table/artifact?: No.
• New abstraction?: No runtime abstraction. Any page components are website-local presentation pieces for this homepage slice.
• New enum/state/reason family?: No.
• New cross-domain UI framework/taxonomy?: No.
• Current operator problem: Prospective buyers and stakeholders cannot yet infer Tenantial's Microsoft tenant governance value from the public homepage.
• Existing structure is insufficient because: The current website direction still contains template residue and does not provide a focused brand, trust, and evidence story for Tenantial.
• Narrowest correct implementation: One homepage slice with static content, static preview data, clear CTA hierarchy, trust boundaries, accessibility/responsive expectations, SEO cleanup, and smoke coverage.
• Ownership cost: Homepage copy, static preview content, public navigation labels, and brand/SEO expectations must be maintained as later website pages are added.
• Alternative intentionally rejected: Rebuilding the full website now. That would expand scope before the homepage direction is proven.
• Release truth: Current public website direction, not platform runtime truth or future product data truth.

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility for old public template pages, old TenantAtlas/TenantPilot public copy, deleted demo routes, and template homepage content is out of scope unless explicitly required by a later spec. Public pages reachable from the updated header/footer may receive narrow brand/SEO copy cleanup so the website does not expose a mixed Tenantial/TenantAtlas public brand.

Internal package names, workspace scripts, and platform runtime contracts must not be renamed by this feature. In particular, the internal workspace package name @tenantatlas/website remains unchanged.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Browser.
• Validation lane(s): browser.
• Why this classification and these lanes are sufficient: The feature changes a public static website route, visual hierarchy, responsive behavior, copy, and SEO metadata. Browser smoke checks and screenshot review are the narrowest honest proof.
• New or expanded test families: Homepage website smoke coverage only.
• Fixture / helper cost impact: None. No database, workspace, membership, provider, session, seed, or platform setup should be required.
• Heavy-family visibility / justification: Browser coverage is intentional and scoped to the homepage shell, visual behavior, and template-residue checks.
• Special surface test profile: N/A.
• Standard-native relief or required special coverage: Homepage smoke checks plus desktop/mobile visual review.
• Reviewer handoff: Reviewers must confirm that browser coverage remains website-scoped, no hidden platform setup is introduced, and the proof checks visible content, metadata cleanup, and mobile overflow.
• Budget / baseline / trend impact: None expected beyond a small homepage smoke suite.
• Escalation needed: document-in-feature.
• Active feature PR close-out entry: Smoke Coverage.
• Planned validation commands: repository website build command; website browser smoke test command; git diff --check; desktop and mobile browser review when screenshots are intentionally captured.

User Scenarios & Testing (mandatory)

User Story 1 - Understand Tenantial Immediately (Priority: P1)

A first-time visitor opens the homepage and understands that Tenantial is an evidence-first governance platform for Microsoft tenants, not a generic SaaS template.

Why this priority: This is the minimum viable homepage outcome. If the first viewport does not establish the brand, category, and core promise, the rebuild fails.

Independent Test: Can be tested by opening / and verifying that the first viewport shows the Tenantial brand, the evidence-first governance headline, Microsoft tenant context, and primary/secondary CTAs.

Acceptance Scenarios:

1. Given a first-time visitor, When they open /, Then they see Tenantial as the public brand and the headline "Evidence-first governance for Microsoft tenants."
2. Given a visitor scanning the hero, When they read the supporting copy, Then they can identify backup, restore, drift detection, snapshot-backed audit context, evidence, and structured reviews as the product focus.
3. Given a visitor looking for the next step, When they inspect the hero actions, Then "Book a demo" is the primary CTA and "Explore the platform" is secondary.

---

User Story 2 - Evaluate Trust Without False Proof (Priority: P2)

An IT, MSP, security, or compliance stakeholder reviews the homepage and sees credible trust positioning without fake customer logos, unsupported certifications, or exaggerated availability/security claims.

Why this priority: Tenantial operates in a governance and evidence domain; credibility depends on restrained claims and clear proof boundaries.

Independent Test: Can be tested by reviewing the trust bar, feature pillars, static preview, and footer for allowed claims and absence of unverified social proof.

Acceptance Scenarios:

1. Given no verified customer logos are available, When the trust bar renders, Then it uses neutral credibility statements rather than named real customer logos.
2. Given no verified security certifications are provided, When the homepage renders, Then it does not claim SOC 2, ISO certification, uptime guarantees, or "trusted by" proof.
3. Given a stakeholder reviewing capabilities, When they reach the feature pillars, Then Backup, Restore, Drift Detection, Evidence, Audit Trail, and Governance Reviews are all present with concise descriptions.

---

User Story 3 - Inspect A Product-Near Preview (Priority: P3)

A visitor sees a product-near dashboard preview that communicates posture, findings, drift, evidence, backup status, reviews, and recent activity while clearly remaining static marketing content.

Why this priority: The mockup direction depends on a strong preview surface, but false live-data implications would undermine trust.

Independent Test: Can be tested by checking that the dashboard preview is visible, readable, responsive, and framed as static demo content.

Acceptance Scenarios:

1. Given the homepage has loaded, When a visitor views the preview, Then they see static demo values for overall posture, findings, drift detected, evidence items, and backup status.
2. Given the preview contains status information, When colors are removed or unavailable, Then labels or text still communicate the status meaning.
3. Given a visitor is on mobile, When they reach the preview, Then the page remains usable without body-level horizontal overflow.

---

User Story 4 - Verify Public Launch Readiness (Priority: P4)

A website owner reviews the homepage before launch and can confirm that old template residue, wrong brand names, broken CTAs, and unsupported promises are absent.

Why this priority: The rebuild should establish a clean baseline before later public pages reuse the direction.

Independent Test: Can be tested through homepage smoke checks, metadata review, link review, and desktop/mobile visual review.

Acceptance Scenarios:

1. Given the homepage is ready for review, When the visible copy and metadata are checked, Then AstroDeck/template positioning and old public brand names are absent.
2. Given a reviewer inspects navigation, When they follow homepage CTAs and nav links, Then links are intentional and do not silently point to dead template routes.
3. Given a reviewer checks desktop and mobile, When the page is visually reviewed, Then text does not clip, CTAs remain visible, and the header adapts to the viewport.

Edge Cases

• If dedicated destination pages do not yet exist, homepage links must still be intentional and must not point to stale template routes.
• If no real logo asset is available, the homepage may use a simple Tenantial mark that does not imply a third-party endorsement.
• If no real customer proof is available, the trust bar must use neutral product-focus statements instead of fake logos or named companies.
• If a visitor uses a narrow mobile viewport, the hero, CTA text, header, and dashboard preview must not create body-level horizontal overflow.
• If motion reduction is preferred by the visitor, decorative movement must not be required to understand the page.
• If status colors are not distinguishable, status labels and text must still communicate meaning.
• If platform authentication is not implemented or no sign-in destination is known, homepage sign-in treatment must not imply a completed login flow.

Requirements (mandatory)

Constitution alignment (required): This feature introduces no Microsoft Graph calls, no write/change behavior, no queued or scheduled work, no OperationRun, no AuditLog changes, no tenant isolation changes, and no platform runtime behavior.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): This feature introduces no persisted product truth, no domain abstraction, no enum/status/reason family, and no cross-domain UI framework. The only new source of truth is the public homepage brand/content direction, bounded to the website.

Constitution alignment (XCUT-001): This feature does not touch shared operator interaction families. Public website navigation and marketing preview elements must remain website-local.

Constitution alignment (DECIDE-AUD-001 / OPSURF-001): This feature does not change admin detail/status surfaces, audience modes, support/raw evidence disclosure, or operator next-action surfaces.

Constitution alignment (PROV-001): This feature does not change provider/platform seams. Microsoft tenant language is marketing positioning only and must not create runtime provider coupling.

Constitution alignment (TEST-GOV-001): Browser coverage is intentional, homepage-scoped, and must not introduce database, workspace, provider, membership, session, or platform defaults.

Constitution alignment (OPS-UX / OPS-UX-START-001): N/A - no OperationRun behavior is created, queued, completed, deduplicated, resumed, blocked, or linked.

Constitution alignment (RBAC-UX): N/A - no authorization plane, capability, membership, global search, mutation, or destructive action behavior changes.

Constitution alignment (BADGE-001): N/A - no admin status badge semantics change. Public marketing status labels in the static preview must be descriptive and not become a shared status taxonomy.

Constitution alignment (UI-FIL-001): N/A - no Filament, Blade admin, Livewire, Resource, RelationManager, or Page changes.

Constitution alignment (UI-NAMING-001 / DECIDE-001 / UI surface rules): N/A for operator-facing naming and action-surface contracts. Public homepage copy must still use calm, precise, user-facing language and avoid implementation-first labels.

Functional Requirements

• FR-001: / MUST render a Tenantial-specific public homepage.
• FR-002: The homepage MUST present Tenantial as an evidence-first governance platform for Microsoft tenants.
• FR-003: The homepage MUST use a premium dark enterprise visual direction with high-contrast text and restrained accent colors.
• FR-004: The homepage MUST show the headline "Evidence-first governance for Microsoft tenants."
• FR-005: The homepage MUST include supporting copy that communicates backup, restore, drift detection, snapshot-backed audit context, verifiable evidence, and structured governance reviews.
• FR-006: "Book a demo" MUST be visible as the primary CTA.
• FR-007: "Explore the platform" MUST be visible as the secondary CTA.
• FR-008: CTA and navigation destinations MUST be intentional and MUST NOT silently point to dead template routes.
• FR-009: If no implemented sign-in destination is known, "Sign in" MUST NOT be presented as a prominent functional promise.
• FR-010: The desktop header MUST include Tenantial branding and navigation labels for Platform, Solutions, Resources, Pricing, Company, Sign in, and Book a demo.
• FR-011: The homepage MUST include a static product-near dashboard preview.
• FR-012: The dashboard preview MUST be clearly static marketing/demo content and MUST NOT depend on backend, API, authentication, tenant, or platform data.
• FR-013: The dashboard preview MUST show static demo values for overall posture, findings, drift detected, evidence items, and backup status.
• FR-014: The dashboard preview MUST include supporting areas for recent findings, drift timeline, backups and restores, reviews, and evidence spotlight.
• FR-015: The homepage MUST include a trust bar using neutral credibility statements such as Microsoft tenant focus, evidence-oriented workflows, audit review workflow design, and operator-led governance.
• FR-016: The trust bar MUST NOT use real customer logos, certification claims, uptime claims, "trusted by" statements, or security/compliance promises unless independently verified.
• FR-017: The feature pillars MUST include Backup, Restore, Drift Detection, Evidence, Audit Trail, and Governance Reviews.
• FR-018: Feature pillar copy MUST remain concise, product-specific, and free of unsupported compliance or security promises.
• FR-019: The homepage MUST include a final CTA section with "Build tenant governance on evidence, not assumptions." or equivalent wording with the same meaning.
• FR-020: The homepage footer MUST include Tenantial branding and footer link groups for Platform, Solutions, Resources, Pricing, Company, Contact, Legal, Privacy, and Security.
• FR-021: Visible homepage copy MUST NOT contain AstroDeck, template demo positioning, Open Source, MIT Licensed, TenantCTRL, TenantPilot, or TenantAtlas as public brand names.
• FR-022: Homepage SEO metadata MUST be Tenantial-specific and MUST describe evidence-first governance for Microsoft tenants.
• FR-023: Homepage metadata MUST NOT contain AstroDeck/template titles, old public brand names, fake customer proof, or unverified certification claims.
• FR-024: The homepage MUST have exactly one primary page heading.
• FR-025: Keyboard users MUST be able to reach and identify interactive homepage controls, including navigation and CTAs.
• FR-026: Status information in the dashboard preview MUST NOT rely on color alone.
• FR-027: The homepage MUST provide sufficient contrast on the dark background for body copy, labels, links, and CTAs.
• FR-028: The homepage MUST remain usable on mobile, tablet, desktop, and wide desktop viewports.
• FR-029: The mobile homepage MUST NOT create body-level horizontal overflow.
• FR-030: The header MUST collapse or simplify on mobile without hiding essential navigation and CTA access from keyboard users.
• FR-031: Decorative icons or visual flourishes MUST NOT be required to understand the page content.
• FR-032: Decorative motion, if present, MUST be subtle and respect reduced-motion preferences.
• FR-033: The homepage MUST NOT introduce platform, auth, database, Microsoft Graph, Filament, Livewire, or runtime API coupling.
• FR-034: Existing root workspace script names and website port conventions MUST remain unchanged.

Key Entities

• Homepage Message: The public brand, category, headline, supporting promise, and CTA hierarchy for the / route.
• Static Dashboard Preview: A product-near visual using fixed demo values to communicate governance posture, findings, drift, evidence, backup status, reviews, and recent activity.
• Trust Statement: A neutral credibility statement that supports confidence without implying verified customer proof, certifications, or availability guarantees.
• Feature Pillar: A concise capability card describing one of Tenantial's required homepage capabilities: Backup, Restore, Drift Detection, Evidence, Audit Trail, or Governance Reviews.
• Footer Link Group: A public website navigation group that points visitors toward product, company, contact, legal, privacy, and security information without template residue.

Assumptions

• The public brand for this homepage is Tenantial.
• No verified customer logos, security certifications, or uptime claims are available for this slice.
• The "Book a demo" destination defaults to /contact unless a valid existing destination is confirmed before implementation.
• The "Explore the platform" destination defaults to /product until a dedicated platform route exists.
• Header route defaults: Platform -> /product, Solutions -> /solutions, Book a demo -> /contact, and Explore the platform -> /product. Resources, Pricing, Company, and Sign in must not link to missing same-name routes; they may be de-emphasized, mapped to an existing intentional route, or rendered non-prominently until real routes exist.
• No secondary public pages are built by this spec.
• The dashboard preview uses static demo content, not screenshots, live product data, or platform API data.
• Existing website font choices may be reused if they support the premium enterprise direction.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: In a stakeholder review, at least 8 of 10 reviewers can identify Tenantial as a Microsoft tenant governance platform within 5 seconds of viewing the first homepage viewport.
• SC-002: 100% of required homepage sections render on desktop and mobile review: header, hero, static dashboard preview, trust bar, feature pillars, CTA section, and footer.
• SC-003: Review of visible copy and homepage metadata finds 0 occurrences of AstroDeck, Open Source, MIT Licensed, TenantCTRL, TenantPilot, TenantAtlas, or other old/template public brand positioning.
• SC-004: Desktop and mobile review confirms 0 body-level horizontal overflow issues at narrow mobile, tablet, desktop, and wide desktop widths.
• SC-005: At least 90% of reviewers can identify Backup, Restore, Drift Detection, Evidence, Audit Trail, and Governance Reviews from the homepage without needing external documentation.
• SC-006: Trust review finds 0 unverified customer, certification, uptime, or security/compliance claims.
• SC-007: Accessibility review confirms the page has one primary heading, keyboard-visible controls, readable contrast on dark backgrounds, and non-color-only status meaning.
• SC-008: Homepage smoke validation confirms the route renders, required brand/capability copy is visible, required CTAs are visible, static preview content is present, and mobile overflow is absent.