Skip to content

MarketingSite Alignment Plan (UIKit + Flowbite)

This document defines the planned solution for aligning ConnectSoft.MarketingSite with ConnectSoft.Blazor.UIKit, while preserving Flowbite as the base component implementation layer.

Goal

Establish a clear separation of concerns:

  • Flowbite as foundational rendering/behavior layer.
  • UIKit as the canonical public API layer for ConnectSoft UI usage.
  • MarketingSite as a consumer of reusable UIKit compositions, not a source of duplicated page-specific UI primitives.

Context Summary

The current MarketingSite setup already uses Flowbite and UIKit, but key sections are still custom and tightly coupled to local page markup and styles. This creates duplication and slows reuse.

High-value custom sections currently identified:

  • Header/navigation shell
  • Footer shell
  • How-it-works timeline
  • Testimonials card grid + pagination behavior
  • Pricing cards and feature comparison layout
  • Shared CTA section pattern

Desired Target Model

flowchart LR
  marketingPages[MarketingPages] --> uikitCompositions[UIKitCompositions]
  uikitCompositions --> uikitPrimitives[UIKitPrimitives]
  uikitPrimitives --> flowbiteAdapters[FlowbiteAdapters]
  flowbiteAdapters --> flowbiteRuntime[FlowbiteRuntime]
  marketingPages --> contentBindings[ContentAndLocalizationBindings]
  contentBindings --> uikitCompositions
Hold "Alt" / "Option" to enable pan & zoom

Scope

In Scope

  • Define reusable UIKit compositions for high-reuse marketing patterns.
  • Migrate MarketingSite to consume those compositions incrementally.
  • Reduce styling drift by moving reusable style rules into UIKit-scoped styles and tokens.
  • Preserve behavior parity for responsive states, RTL, themes, and localization.

Out of Scope (Current Phase)

  • Full visual redesign.
  • Replacing Flowbite.
  • Rewriting all Marketing pages in one release.
  • Major content model refactors outside UI extraction boundaries.

Component Alignment Matrix

  1. Layout/Header.razor -> UIKit Navbar composition (MarketingHeader)
  2. Layout/Footer.razor -> UIKit Footer composition (MarketingFooter)
  3. Pages/HowItWorks.razor -> UIKit Timeline composition (FeatureTimeline)
  4. Pages/Pricing.razor -> UIKit Card/Badge/Button composition (PricingCards)
  5. Pages/Testimonials.razor -> UIKit Card/Avatar/Pagination composition (TestimonialsGrid)
  6. Shared/CtaSection.razor -> UIKit Banner/Jumbotron composition (ConversionCta)

Phased Execution Plan

Phase 1 - Contracts and Mapping

  • Define component contracts with stable parameters and RenderFragment extension slots.
  • Document mapping from current Marketing custom sections to UIKit target compositions.
  • Decide ownership boundaries between MarketingSite content binding and UIKit rendering responsibilities.

Phase 2 - UIKit Composition Buildout

  • Build/refine composition components in UIKit for each mapped section.
  • Ensure no hard dependency on Marketing routes or specific localization keys.
  • Implement variants through parameters, not duplicated markup branches.

Phase 3 - Incremental Marketing Migration

  • Replace custom section-by-section in MarketingSite layouts/pages.
  • Keep old and new sections side-by-side only as long as needed for parity checks.
  • Move page copy/localization access into lightweight page-level view models passed into compositions.

Phase 4 - Styling Convergence

  • Audit figma-redesign.css selectors tied to migrated sections.
  • Move reusable styling into UIKit component styles/tokens.
  • Keep only page-unique campaign styles local to MarketingSite.

Phase 5 - Verification and Cleanup

  • Validate desktop/mobile responsiveness, RTL, dark/light themes, and localization output.
  • Add/extend bUnit coverage for new compositions and migrated page usage.
  • Remove obsolete custom markup/CSS after parity sign-off.

Acceptance Criteria

  • Marketing layout/page sections in scope render through UIKit compositions.
  • No loss of functional behavior compared to current experience.
  • Reusable section styles are primarily owned by UIKit.
  • Marketing-specific content remains in MarketingSite, not embedded in UIKit.
  • Team can build a new page section by composing UIKit components without copying large custom blocks.

Risks and Mitigations

  • Risk: Styling regressions from CSS cascade differences.
    Mitigation: Migrate section-by-section with visual parity checks.

  • Risk: Overfitting UIKit components to Marketing-only assumptions.
    Mitigation: enforce generic API contracts and avoid route/content coupling.

  • Risk: JS behavior mismatch across menus/toggles/interactions.
    Mitigation: normalize behavior through UIKit and adapter-backed implementations.

Ownership

  • UIKit Team: composition APIs, shared styles/tokens, adapter alignment.
  • Marketing Team: content models, page composition adoption, migration execution.
  • Architecture/Frontend Leads: contract approvals and parity sign-off gates.

Implementation Notes

  • Prefer adding reusable composition docs/examples alongside component delivery.
  • Keep migration PRs small and section-focused.
  • Use parity checklists for each migrated block before old code removal.