Skip to main content

Layout System

QwickApps React Framework provides a flexible, responsive layout system that helps you create professional web applications without complex CSS. The layout system is built on modern CSS Grid and Flexbox technologies with mobile-first responsive design.

Overview​

The layout system consists of:

  • 🏗️ Structural Components - Core layout containers and wrappers
  • 📐 Spacing System - Consistent spacing with semantic size names
  • 📱 Responsive Breakpoints - Mobile-first responsive design patterns
  • 🎯 Layout Patterns - Common page layouts and compositions

Core Layout Components​

Section​

The foundational layout container that provides consistent spacing and alignment.

<Section
  maxWidth="container"     // container | wide | full
  padding="large"          // small | medium | large | none
  backgroundColor="light"  // light | dark | primary | transparent
  textAlign="center"       // left | center | right
>
  <HeroBlock title="Welcome to QwickApps" />
</Section>

Max Width Options:

  • container: 1200px max width, centered
  • wide: 1440px max width for wider layouts
  • full: 100% width, no max-width constraint

Container​

Simple content container with responsive width.

<Container size="medium">
  <Article title="Blog Post" content="..." />
</Container>

Responsive Grid System​

CardListGrid​

Flexible grid system for card-based layouts.

<CardListGrid
  columns={{
    mobile: 1,
    tablet: 2, 
    desktop: 3,
    large: 4
  }}
  gap="medium"
  alignItems="stretch"
>
  {items.map(item => (
    <ProductCard key={item.id} {...item} />
  ))}
</CardListGrid>

FeatureGrid​

Specialized grid for feature displays.

<FeatureGrid
  columns={3}
  features={[
    {
      icon: "⚡",
      title: "Fast Performance",
      description: "Lightning-fast loading times"
    },
    {
      icon: "🔒",
      title: "Secure by Design", 
      description: "Built-in security best practices"
    },
    {
      icon: "📱",
      title: "Mobile First",
      description: "Responsive across all devices"
    }
  ]}
/>

Common Layout Patterns​

Landing Page Layout​

function LandingPage() {
  return (
    <QwickApp appId="landing">
      {/* Hero Section */}
      <Section backgroundColor="primary" padding="large">
        <HeroBlock
          title="Build Amazing Apps"
          subtitle="With QwickApps React Framework"
          ctaButtons={[
            { label: "Get Started", href: "/start" },
            { label: "View Demo", href: "/demo" }
          ]}
        />
      </Section>

      {/* Features Section */}
      <Section padding="large">
        <FeatureGrid
          title="Why Choose QwickApps?"
          columns={3}
          features={featuresData}
        />
      </Section>

      {/* Testimonials */}
      <Section backgroundColor="light" padding="medium">
        <CardListGrid columns={{ mobile: 1, desktop: 2 }}>
          {testimonials.map(testimonial => (
            <TestimonialCard key={testimonial.id} {...testimonial} />
          ))}
        </CardListGrid>
      </Section>

      {/* CTA Section */}
      <Section backgroundColor="primary" padding="medium">
        <CallToAction
          title="Ready to Get Started?"
          description="Join thousands of developers building with QwickApps"
          primaryButton={{ label: "Start Building", href: "/signup" }}
          secondaryButton={{ label: "Contact Sales", href: "/contact" }}
        />
      </Section>
    </QwickApp>
  );
}

Blog/Content Layout​

function BlogPage() {
  return (
    <QwickApp appId="blog">
      {/* Page Header */}
      <PageBannerHeader
        title="Blog"
        subtitle="Latest news and tutorials"
        breadcrumbs={[
          { label: 'Home', href: '/' },
          { label: 'Blog', href: '/blog' }
        ]}
      />

      {/* Main Content */}
      <Section padding="large">
        <Container size="wide">
          <div style={{ display: 'flex', gap: '2rem' }}>
            {/* Main Content */}
            <main style={{ flex: '2' }}>
              <CardListGrid columns={{ mobile: 1, tablet: 2 }}>
                {blogPosts.map(post => (
                  <BlogCard key={post.id} {...post} />
                ))}
              </CardListGrid>
            </main>

            {/* Sidebar */}
            <aside style={{ flex: '1' }}>
              <SearchBox placeholder="Search articles..." />
              <CategoryList categories={categories} />
              <RecentPosts posts={recentPosts} />
            </aside>
          </div>
        </Container>
      </Section>
    </QwickApp>
  );
}

Product/SaaS Layout​

function ProductPage() {
  return (
    <QwickApp appId="product">
      {/* Hero with Cover Image */}
      <CoverImageHeader
        title="QwickApps React Framework"
        subtitle="Build faster, scale better"
        backgroundImage="/product-hero.jpg"
      />

      {/* Product Features */}
      <Section padding="large">
        <FeatureGrid
          columns={2}
          features={productFeatures}
          layout="alternating" // Image left/right alternating
        />
      </Section>

      {/* Pricing Section */}
      <Section backgroundColor="light" padding="large">
        <Container size="medium">
          <h2>Choose Your Plan</h2>
          <CardListGrid columns={{ mobile: 1, tablet: 2, desktop: 3 }}>
            {pricingPlans.map(plan => (
              <PricingCard key={plan.id} {...plan} />
            ))}
          </CardListGrid>
        </Container>
      </Section>

      {/* FAQ Section */}
      <Section padding="large">
        <Container size="medium">
          <h2>Frequently Asked Questions</h2>
          <FAQList items={faqData} />
        </Container>
      </Section>
    </QwickApp>
  );
}

Dashboard Layout​

function DashboardPage() {
  return (
    <QwickApp 
      appId="dashboard"
      enableScaffolding={true}
      showThemeSwitcher={true}
    >
      {/* Dashboard Header */}
      <Section backgroundColor="light" padding="small">
        <Container size="full">
          <div style={{ display: 'flex', justifyContent: 'space-between' }}>
            <h1>Dashboard</h1>
            <Button label="New Project" variant="primary" />
          </div>
        </Container>
      </Section>

      {/* Metrics Grid */}
      <Section padding="medium">
        <Container size="full">
          <CardListGrid 
            columns={{ mobile: 1, tablet: 2, desktop: 4 }}
            gap="medium"
          >
            <MetricCard title="Projects" value="24" trend="+12%" />
            <MetricCard title="Users" value="1,342" trend="+5.4%" />
            <MetricCard title="Revenue" value="$12,450" trend="+23%" />
            <MetricCard title="Growth" value="15.2%" trend="+2.1%" />
          </CardListGrid>
        </Container>
      </Section>

      {/* Main Dashboard Content */}
      <Section padding="medium">
        <Container size="full">
          <div className="dashboard-grid">
            <div className="main-content">
              <RecentActivity activities={activities} />
              <ProjectsList projects={projects} />
            </div>
            
            <div className="sidebar">
              <QuickActions actions={quickActions} />
              <TeamMembers members={team} />
            </div>
          </div>
        </Container>
      </Section>
    </QwickApp>
  );
}

Spacing System​

Consistent Spacing Scale​

QwickApps uses a consistent spacing scale based on rem units:

--spacing-xs: 0.25rem;    /* 4px */
--spacing-sm: 0.5rem;     /* 8px */
--spacing-md: 1rem;       /* 16px */
--spacing-lg: 1.5rem;     /* 24px */
--spacing-xl: 2rem;       /* 32px */
--spacing-2xl: 3rem;      /* 48px */
--spacing-3xl: 4rem;      /* 64px */

Semantic Spacing Names​

Components use semantic names that map to the spacing scale:

<Section padding="small">    {/* --spacing-lg */}
<Section padding="medium">   {/* --spacing-xl */}
<Section padding="large">    {/* --spacing-3xl */}

<CardListGrid gap="small">   {/* --spacing-md */}
<CardListGrid gap="medium">  {/* --spacing-lg */}
<CardListGrid gap="large">   {/* --spacing-xl */}

Custom Spacing​

For precise control, use CSS custom properties:

<Section
  sx={{
    paddingTop: 'var(--spacing-2xl)',
    paddingBottom: 'var(--spacing-xl)',
    marginBottom: 'var(--spacing-lg)'
  }}
>
  Content
</Section>

Responsive Breakpoints​

Mobile-First Approach​

QwickApps uses a mobile-first responsive design system:

/* Base styles (mobile) */
.component { 
  padding: var(--spacing-md);
}

/* Tablet and up */
@media (min-width: 768px) {
  .component { 
    padding: var(--spacing-lg);
  }
}

/* Desktop and up */
@media (min-width: 1024px) {
  .component { 
    padding: var(--spacing-xl);
  }
}

/* Large desktop and up */
@media (min-width: 1440px) {
  .component { 
    padding: var(--spacing-2xl);
  }
}

Responsive Props​

Many components accept responsive values:

<Section
  padding={{
    mobile: 'medium',
    tablet: 'large',
    desktop: 'large'
  }}
  textAlign={{
    mobile: 'center',
    desktop: 'left'
  }}
/>

<CardListGrid
  columns={{
    mobile: 1,
    tablet: 2,
    desktop: 3,
    large: 4
  }}
  gap={{
    mobile: 'small',
    desktop: 'medium'
  }}
/>

Advanced Layout Techniques​

CSS Grid Areas​

For complex layouts, use CSS Grid areas:

<div className="page-layout">
  <header className="header">
    <PageBannerHeader title="Complex Layout" />
  </header>
  
  <main className="main">
    <Article content={mainContent} />
  </main>
  
  <aside className="sidebar">
    <NavigationMenu items={menuItems} />
  </aside>
  
  <footer className="footer">
    <Footer sections={footerSections} />
  </footer>
</div>
.page-layout {
  display: grid;
  grid-template-areas:
    "header header"
    "main sidebar"
    "footer footer";
  grid-template-columns: 2fr 1fr;
  grid-template-rows: auto 1fr auto;
  min-height: 100vh;
  gap: var(--spacing-lg);
}

.header { grid-area: header; }
.main { grid-area: main; }
.sidebar { grid-area: sidebar; }
.footer { grid-area: footer; }

/* Mobile Layout */
@media (max-width: 767px) {
  .page-layout {
    grid-template-areas:
      "header"
      "main"
      "sidebar"
      "footer";
    grid-template-columns: 1fr;
  }
}

Flexbox Utilities​

Use flexbox for component-level layouts:

<div className="flex-container">
  <div className="flex-item">
    <Button label="Action 1" />
  </div>
  <div className="flex-spacer" />
  <div className="flex-item">
    <Button label="Action 2" />
  </div>
</div>
.flex-container {
  display: flex;
  align-items: center;
  gap: var(--spacing-md);
}

.flex-spacer {
  flex: 1;
}

.flex-item {
  flex-shrink: 0;
}

Layout Best Practices​

✅ Do​

  • Use the Section component for consistent page structure
  • Leverage responsive props instead of writing custom media queries
  • Follow the mobile-first approach
  • Use semantic spacing names (small, medium, large)
  • Test layouts on multiple screen sizes
  • Keep grid columns flexible and responsive

❌ Don't​

  • Mix different spacing systems in the same project
  • Use fixed pixel widths for responsive components
  • Ignore mobile users (mobile-first approach)
  • Create overly complex nested grids
  • Forget to test on actual devices
  • Hard-code breakpoints in custom CSS

Accessibility Considerations​

Semantic HTML Structure​

<QwickApp>
  <header>
    <PageBannerHeader />
  </header>
  
  <main>
    <Section as="article">
      <Article />
    </Section>
  </main>
  
  <footer>
    <Footer />
  </footer>
</QwickApp>

Focus Management​

Ensure logical tab order and keyboard navigation:

<Section>
  <h2>Contact Form</h2>
  <FormBlock
    fields={[
      { name: 'name', label: 'Name', tabIndex: 1 },
      { name: 'email', label: 'Email', tabIndex: 2 },
      { name: 'message', label: 'Message', tabIndex: 3 }
    ]}
    submitButton={{ tabIndex: 4 }}
  />
</Section>

Screen Reader Support​

Use proper heading hierarchy and landmarks:

<QwickApp>
  <Section as="main" aria-label="Main content">
    <h1>Page Title</h1>
    <Section as="section" aria-labelledby="features-heading">
      <h2 id="features-heading">Features</h2>
      <FeatureGrid features={features} />
    </Section>
  </Section>
</QwickApp>

Performance Optimization​

Lazy Loading​

Load layout-heavy components on demand:

<Section>
  <Suspense fallback={<LoadingSpinner />}>
    <LazyFeatureGrid features={features} />
  </Suspense>
</Section>

Image Optimization​

Optimize layout images with responsive loading:

<CoverImageHeader
  title="Hero Section"
  backgroundImage={{
    mobile: "/hero-mobile.webp",
    tablet: "/hero-tablet.webp", 
    desktop: "/hero-desktop.webp"
  }}
  loading="eager" // Above fold
/>

<Section>
  <FeatureCard
    image="/feature.webp"
    loading="lazy" // Below fold
  />
</Section>

What's Next?​