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

Implementation Plan: Tenantial Homepage Visual Rebuild

Branch: 400-tenantial-homepage-visual-rebuild | Date: 2026-05-17 | Spec: spec.md
Input: Feature specification from /Users/ahmeddarrazi/Documents/projects/wt-website/specs/400-tenantial-homepage-visual-rebuild/spec.md

Status: Implementation complete in this branch. This plan now records the bounded Spec 400 implementation slice and its validation path.

Summary

Rebuild the public / homepage in /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website so Tenantial is presented as a premium dark enterprise SaaS product for evidence-first Microsoft tenant governance. The implementation approach is a static Astro website slice: update homepage content, public shell/navigation/footer, website-local design tokens, a static product-near dashboard preview, SEO metadata, narrow public-page brand consistency, and Playwright smoke expectations without adding platform runtime, backend data, auth, database, Filament, Livewire, or Microsoft Graph coupling.

Technical Context

Language/Version: TypeScript 5.9, Astro 6 static components, HTML, CSS
Primary Dependencies: Astro 6.0.0, Tailwind CSS 4.2.2 through CSS-first @theme and @tailwindcss/vite, astro-icon, @iconify-json/lucide, Playwright 1.59.1
Storage: N/A - static public website content only; no database or persisted runtime data
Testing: Playwright smoke tests under /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/tests/smoke plus Astro static build
Validation Lanes: browser
Target Platform: Static public website generated by Astro and served by the website deployment container
Project Type: Web frontend static site in /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website
Performance Goals: Static homepage renders without heavy third-party scripts, body-level horizontal overflow, clipped CTA text, or live-data dependencies; desktop and mobile first-read content remains usable and readable
Constraints: No platform/auth/API/database/Graph coupling; no fake customer proof, certifications, or uptime claims; Tailwind v4 conventions only; use existing workspace script names and WEBSITE_PORT behavior; dark page must maintain accessible focus, contrast, and non-color-only status meaning; dark visual direction must use the Spec 400 Obsidian/Ivory/Mint baseline: near-black page background, ivory primary text, muted warm gray secondary text, mint primary accent, amber warning, coral critical, violet evidence/review accents, and WCAG-readable contrast for text and controls
Scale/Scope: One public route (/) plus shared public shell elements used by that route: header, footer, SEO metadata, website-local styles/tokens, static homepage sections, homepage smoke tests, and minimal brand/SEO cleanup on existing public pages reachable from the global shell

UI / Surface Guardrail Plan

• Guardrail scope: No operator-facing surface change.
• Native vs custom classification summary: N/A for Filament/admin surfaces. Public website components may be customized within apps/website.
• Shared-family relevance: None for operator-facing shared families.
• State layers in scope: Public website page and shell state only; no admin shell, detail state, URL-query state, tenant state, or operation state.
• Audience modes in scope: Public visitor, MSP buyer, enterprise IT buyer, security/compliance reviewer.
• Decision/diagnostic/raw hierarchy plan: Public marketing first-read content only; no operator diagnostics or support/raw evidence surfaces.
• Raw/support gating plan: N/A.
• One-primary-action / duplicate-truth control: Homepage keeps "Book a demo" as the primary CTA and "Explore the platform" as secondary; repeated CTA sections preserve this hierarchy.
• Handling modes by drift class or surface: N/A.
• Repository-signal treatment: Report-only for website smoke review; no guardrail exception.
• Special surface test profiles: N/A.
• Required tests or manual smoke: Homepage Playwright smoke coverage, metadata/template-residue assertions, mobile overflow check, desktop/mobile screenshot review.
• Exception path and spread control: None.
• Active feature PR close-out entry: Smoke Coverage.

Shared Pattern & System Fit

• Cross-cutting feature marker: No for operator-facing systems; yes only in the public website sense that header/footer/site metadata may be updated for Tenantial.
• Systems touched: Public website app under /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website; homepage page, content, layout navigation/footer, styles, static visual component, existing public-page brand copy, and smoke tests.
• Shared abstractions reused: Existing website shell, layout, primitive/content/section components where they fit; existing Playwright smoke helper style.
• New abstraction introduced? why?: No runtime or domain abstraction. A page-local static dashboard preview component is acceptable as presentation, not shared product truth.
• Why the existing abstraction was sufficient or insufficient: Existing Astro/Tailwind/Playwright website structure is sufficient. Existing copy, light palette, TenantAtlas brand, and product visual direction are insufficient for the Tenantial dark enterprise homepage.
• Bounded deviation / spread control: Homepage-specific static preview and dark visual treatment stay in apps/website; no platform or admin design system changes. Existing internal workspace names such as @tenantatlas/website remain unchanged.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: No.
• Central contract reused: N/A.
• Delegated UX behaviors: N/A.
• Surface-owned behavior kept local: N/A.
• Queued DB-notification policy: N/A.
• Terminal notification path: N/A.
• Exception path: None.

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: No.
• Provider-owned seams: N/A.
• Platform-core seams: N/A.
• Neutral platform terms / contracts preserved: Existing runtime contracts remain unchanged.
• Retained provider-specific semantics and why: Marketing language may say "Microsoft tenants" because the public product positioning targets that environment. It must not change provider contracts, identifiers, compare semantics, governed-subject taxonomy, or runtime naming.
• Bounded extraction or follow-up path: None.

Constitution Check

Pre-Design Gate

PASS. No unresolved gate failures.

• Spec Candidate Gate: Passed in spec with exactly one approval class (Core Enterprise), approval score 11/12, and decision approve.
• Inventory / snapshots / Graph / deterministic capabilities: N/A. No platform inventory, snapshots, Graph calls, or capability resolver behavior.
• Read/write separation: PASS. Public static website change only; no write/change operation.
• RBAC / workspace / tenant isolation: N/A. Public homepage introduces no authorization, tenant route, workspace context, global search, or destructive action.
• OperationRun / Ops-UX: N/A. No queued, scheduled, remote, long-running, or operation-link behavior.
• Data minimization: PASS. Static demo preview data only; no secrets, tenant data, or live payloads.
• Test governance: PASS. Browser lane is explicit and scoped to homepage route/build behavior.
• Proportionality / bloat: PASS. No persisted entity, enum/status family, resolver, registry, interface, DTO layer, or cross-domain UI framework.
• Shared pattern first: PASS. Reuse website shell/primitives/test helpers where practical; no operator-facing shared path touched.
• Provider boundary: PASS. Microsoft tenant wording remains marketing positioning and does not enter platform-core contracts.
• Filament / Livewire: N/A. No Filament v5, Livewire v4, provider registration, global search, destructive action, or Filament asset behavior is touched.

Post-Design Gate

PASS. Phase 0 and Phase 1 artifacts keep the feature static, bounded, and website-local.

• research.md resolves technical choices without adding framework or runtime coupling.
• data-model.md models static content only and explicitly avoids persisted data.
• contracts/public-homepage.yaml documents public route expectations and does not define a backend API.
• quickstart.md uses existing website build/test commands and does not introduce Sail, Laravel, Filament, database, or platform setup.
• No NEEDS CLARIFICATION markers remain.

Test Governance Check

• Test purpose / classification by changed surface: Browser for public homepage route, content, responsive behavior, metadata, and visual smoke.
• Affected validation lanes: browser.
• Why this lane mix is the narrowest sufficient proof: The behavior is user-visible static website rendering. Browser smoke tests and build catch route, content, responsive, and metadata regressions without database or platform setup.
• Narrowest proving command(s): cd /Users/ahmeddarrazi/Documents/projects/wt-website && corepack pnpm build:website; cd /Users/ahmeddarrazi/Documents/projects/wt-website && WEBSITE_PORT=4321 corepack pnpm --filter @tenantatlas/website test:smoke
• Fixture / helper / factory / seed / context cost risks: None. No DB, session, workspace, tenant, provider, member, or seed setup.
• Expensive defaults or shared helper growth introduced?: No. Any smoke helper additions must remain website-only.
• Heavy-family additions, promotions, or visibility changes: Browser coverage is deliberate and homepage-scoped; no heavy-governance family.
• Surface-class relief / special coverage rule: N/A.
• Closing validation and reviewer handoff: Reviewers should verify no platform setup appears in website tests, no unverified trust claims appear, no old brand/template residue remains on the homepage or globally reachable public shell, and mobile body overflow is absent.
• Budget / baseline / trend follow-up: None expected.
• Review-stop questions: Stop if smoke tests require platform state, if the dashboard preview depends on live data, if unsupported trust claims appear, if hidden horizontal overflow remains, or if navigation points to stale template routes.
• Escalation path: document-in-feature.
• Active feature PR close-out entry: Smoke Coverage.
• Why no dedicated follow-up spec is needed: This is a contained homepage browser smoke update. A separate follow-up is only needed if the visual system expands into a cross-page public website framework.

Project Structure

Documentation (this feature)

/Users/ahmeddarrazi/Documents/projects/wt-website/specs/400-tenantial-homepage-visual-rebuild/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── public-homepage.yaml
└── tasks.md              # Created later by /speckit.tasks

Source Code (repository root)

/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/
├── src/
│   ├── pages/
│   │   └── index.astro
│   ├── content/pages/
│   │   └── home.ts
│   ├── lib/
│   │   ├── site.ts
│   │   └── seo.ts
│   ├── components/
│   │   ├── layout/
│   │   │   ├── Navbar.astro
│   │   │   ├── PageShell.astro
│   │   │   └── Footer.astro
│   │   ├── content/
│   │   │   └── DashboardPreview.astro       # expected new or renamed static preview
│   │   └── sections/
│   │       ├── FeaturePillars.astro          # expected new or adapted homepage section
│   │       ├── TrustBar.astro                # expected new or adapted homepage section
│   │       └── CTASection.astro
│   ├── styles/
│   │   ├── tokens.css
│   │   └── global.css
│   └── types/
│       └── site.ts
    ├── public/
│   └── favicon.svg
└── tests/smoke/
    ├── changelog-core-ia.spec.ts
    ├── home-product.spec.ts
    ├── smoke-helpers.ts
    └── visual-foundation-guardrails.spec.ts

Structure Decision: Use the existing Astro website app and existing smoke-test family. The implementation should prefer adapting existing content/layout/primitives before adding new components. Any new dashboard or section component must remain website-local presentation and must not become a shared platform/admin abstraction.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
None	N/A	N/A

Proportionality Review

• Current operator problem: Prospective buyers and stakeholders cannot currently understand Tenantial's Microsoft tenant governance value from the public homepage.
• Existing structure is insufficient because: Current homepage content, brand naming, light visual direction, and product visual do not match the premium dark Tenantial direction or required evidence-first story.
• Narrowest correct implementation: One static homepage slice plus the public shell/styling/smoke checks needed for that page.
• Ownership cost created: Website-local homepage content, static preview data, navigation mapping, public SEO metadata, and smoke assertions must be maintained.
• Alternative intentionally rejected: Full multi-page website rebuild or platform-coupled product data preview.
• Release truth: Current public website direction only.

Phase 0: Research Output

Completed in research.md. All planning unknowns are resolved.

Phase 1: Design And Contracts Output

Completed artifacts:

• data-model.md
• contracts/public-homepage.yaml
• quickstart.md

Agent context update command:

cd /Users/ahmeddarrazi/Documents/projects/wt-website
.specify/scripts/bash/update-agent-context.sh codex