ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
94cff6ca03
TenantAtlas/specs/400-tenantial-homepage-visual-rebuild/research.md
ahmido be314c577f Spec 400: rebuild Tenantial homepage visuals (#387) 
## Summary
- rebuild the public Tenantial homepage around an evidence-first Microsoft tenant governance narrative
- replace the old hero visual with a new static dashboard preview and add dedicated Trust Bar and Feature Pillars sections
- update the shared public shell, navigation, footer, dark design tokens, assets, and homepage content to match the new brand direction
- align website smoke coverage and Spec 400 artifacts with the rebuilt homepage

## Testing
- not run in this pass
- updated website smoke specs under apps/website/tests/smoke

## Note
- `website-dev` was pushed to `origin` so the requested PR base exists remotely
- the remote `website-dev` branch is an ancestor of `origin/dev`, so this PR may also show upstream `dev` history relative to that base

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #387
2026-05-18 14:38:11 +00:00

7.5 KiB
Raw Blame History

Phase 0 Research: Tenantial Homepage Visual Rebuild

Decision: Keep the implementation inside the existing Astro website app

Decision: Use /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website as the only runtime surface for this feature.

Rationale: The feature is a public static homepage rebuild. The repo already has a standalone Astro website app with static output, a public route structure, shared layout components, SEO helpers, Tailwind v4 styling, and Playwright smoke tests. This matches the feature without platform runtime setup.

Alternatives considered:

  • Add platform/Laravel/Filament integration: rejected because the spec forbids platform coupling and this is public marketing content.
  • Create a separate website app: rejected because an Astro website app already exists.
  • Use a CMS/content collection strategy now: rejected because the spec explicitly excludes CMS and full content architecture.

Decision: Update website-local brand metadata and public brand copy from TenantAtlas to Tenantial

Decision: Treat Tenantial as the public brand for the homepage and update homepage-visible copy, SEO metadata, header/footer labels, smoke expectations, and narrow brand/SEO copy on existing public pages reachable from the global shell accordingly.

Rationale: The current website content and siteMetadata still identified the public brand as TenantAtlas. The spec requires Tenantial to be the only visible public brand on the homepage and requires old/template brand residue to be absent. Because the updated header/footer route visitors to existing public pages, those pages also need minimal brand consistency cleanup so the website does not expose mixed public-brand SEO/copy.

Alternatives considered:

  • Leave shared metadata as TenantAtlas and override only the homepage: rejected because header/footer/OG metadata would still leak the old public brand on the homepage.
  • Rename root packages and internal workspace names: rejected because the spec requires internal package names and workspace scripts to remain unchanged.
  • Redesign secondary public pages: rejected because Spec 400 is a homepage implementation slice; secondary pages receive only narrow brand/SEO consistency cleanup.

Decision: Use Tailwind CSS v4 CSS-first tokens and existing global styles

Decision: Implement the premium dark visual direction by adapting /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/styles/tokens.css and /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/styles/global.css, using Tailwind v4-compatible CSS-first @theme tokens and existing utility patterns.

Rationale: The app already imports Tailwind with @import "tailwindcss" and defines tokens with @theme. This matches project and Tailwind v4 conventions and avoids deprecated Tailwind v3 utilities.

Alternatives considered:

  • Add tailwind.config.js: rejected because Tailwind v4 in this project is CSS-first.
  • Add a one-off inline style block for all homepage visuals: rejected because homepage, header, footer, and CTA surfaces need consistent website-local tokens.
  • Add a heavy visual library: rejected because the spec requires no heavy third-party scripts for static visuals.

Decision: Build the dashboard preview as static semantic HTML/CSS, not a raster screenshot or live data

Decision: Implement a static product-near dashboard preview with fixed demo values and semantic labels.

Rationale: The spec requires the preview to be sharp, responsive, and clearly static. It must not imply live product data or depend on backend/API/auth/tenant data. HTML/CSS keeps the preview accessible, inspectable, responsive, and testable.

Alternatives considered:

  • Raster screenshot: rejected because the spec asks for HTML/CSS/SVG and because text/status assertions would be weaker.
  • Live dashboard data: rejected because the spec forbids backend/API/platform coupling.
  • Interactive preview controls: rejected because they could imply functional product behavior that is not implemented.

Decision: Map homepage navigation to existing intentional routes and de-emphasize sign-in

Decision: Use existing routes for visible CTAs where possible: Book a demo -> /contact, Explore the platform -> /product, Platform -> /product, and Solutions -> /solutions. Resources, Pricing, Company, and Sign in currently have no implemented same-name routes; they must be intentionally handled through existing routes, disabled/de-emphasized treatment, or omitted from functional link behavior instead of silently pointing at dead routes. Sign in must be text-only/de-emphasized or point only to a known valid platform URL if one is confirmed during implementation.

Rationale: The current website has /product, /solutions, /contact, /trust, /changelog, /integrations, and legal routes, but no /pricing, /company, /resources, or known sign-in route. /resources is currently gated off, and existing tests expect it to stay hidden until substantive material exists. The spec requires intentional links and forbids silent dead template routes or implying implemented auth.

Alternatives considered:

  • Create secondary pages now: rejected because the spec excludes a full multi-page website build.
  • Link to missing future routes: rejected because the spec requires intentional, non-dead routes.
  • Hide all unavailable labels: rejected because the spec expects the desktop header to carry the named navigation labels.

Decision: Use Playwright smoke coverage plus static build as validation

Decision: Validate with corepack pnpm build:website and the existing website Playwright smoke lane.

Rationale: This change is user-visible static website behavior. Browser smoke tests can verify route rendering, brand/copy, CTA hierarchy, forbidden copy, responsive overflow, metadata, and accessibility-relevant structure without database or platform setup.

Alternatives considered:

  • Laravel/Pest tests: rejected because no Laravel/platform behavior is changed.
  • Unit tests for every presentation component: rejected because this would over-test thin static presentation and add maintenance without proving user value.
  • Visual regression infrastructure: deferred because this spec only requires browser screenshot review, not a permanent screenshot regression system.

Decision: No backend API contract is introduced

Decision: The contract artifact documents the public static route expectations instead of defining a backend API.

Rationale: The homepage has user actions such as opening / and following links, but no data submission, backend mutation, authentication, or API response. A route contract gives reviewers a concrete acceptance surface while preserving the spec's no-backend boundary.

Alternatives considered:

  • Generate REST endpoints for demo booking or sign-in: rejected because those flows are out of scope.
  • Skip contracts entirely: rejected because the /speckit.plan workflow requires a contracts artifact.

Decision: No unresolved clarifications remain

Decision: All open implementation choices have reasonable defaults from the spec.

Rationale: The feature has defaults for brand, CTA destinations, logo availability, customer proof, static preview content, and secondary pages. None require user clarification before planning.

Alternatives considered:

  • Ask whether /pricing, /company, or /resources pages should be built: rejected because the spec's non-goals and assumptions exclude secondary pages for this slice.