From 601a4f63a4d12837f12b0f42a8147e716f542d06 Mon Sep 17 00:00:00 2001
From: Ardecrown0001 <ardecrown@gmail.com>
Date: Tue, 2 Jun 2026 10:29:18 +0100
Subject: [PATCH] fix(#341): improve accessibility for ResponsiveContainer

WCAG 2.1 improvements to ResponsiveContainer and ResponsiveContainerFluid:

- Add polymorphic s prop supporting all sectioning/landmark HTML elements
  (main, section, article, aside, header, footer, nav, div) so consumers
  render semantic markup instead of a generic <div>
- Forward aria-label, aria-labelledby, aria-describedby, role, tabIndex,
  onKeyDown and all standard HTMLAttributes to the root element so keyboard
  navigation and screen reader labelling work without extra wrappers
- Add data-testid defaults ('responsive-container' / 'responsive-container-fluid')
  for reliable automated testing
- Export ResponsiveContainerFluidProps interface for type safety

ResponsiveContainerExample.tsx:
- Replace <div>-wrapped header/main/footer with as='header'/'main'/'footer'
- Add aria-label='Primary navigation' to the <nav> element
- Replace bare href='#' links with descriptive href values
- Add aria-labelledby to all <section> containers
- Add aria-hidden='true' to decorative placeholder images

jest.config.js:
- Remove ResponsiveContainer.test.tsx from testPathIgnorePatterns so the
  new a11y test suite runs in CI

Tests (53 tests, all passing):
- Default rendering, data-testid, className merging
- Responsive padding per viewport category (mobile/tablet/desktop/fallback)
- Polymorphic as prop for all 8 supported element types
- ARIA landmark roles accessible via screen reader queries
- aria-label, aria-labelledby, aria-describedby, role forwarding
- Keyboard navigation: tabIndex, onKeyDown, onClick passthrough
- No console.log in production code
- Fluid variant rendering, clamp() padding, ARIA, keyboard
- Edge cases: nested children, sibling containers, unknown attributes

Closes #341
---
 jest.config.cjs                               |   1 -
 .../responsive/ResponsiveContainer.tsx        | 153 ++++-
 .../responsive/ResponsiveContainerExample.tsx | 179 ++++--
 .../__tests__/ResponsiveContainer.test.tsx    | 549 ++++++++++++++++++
 4 files changed, 804 insertions(+), 78 deletions(-)
 create mode 100644 src/components/responsive/__tests__/ResponsiveContainer.test.tsx

diff --git a/jest.config.cjs b/jest.config.cjs
index 629d9f4d..6b083813 100644
--- a/jest.config.cjs
+++ b/jest.config.cjs
@@ -21,7 +21,6 @@ const customJestConfig = {
     '/node_modules/(?!.*(wagmi|viem|@wagmi|@viem|@walletconnect|@metamask|@coinbase|@radix-ui|@storybook))'
   ],
   testPathIgnorePatterns: [
-    '<rootDir>/src/components/responsive/__tests__/ResponsiveContainer.test.tsx',
     '<rootDir>/src/lib/__tests__/mobile-optimizer.test.ts',
     '<rootDir>/src/lib/__tests__/verify-performance-monitoring.ts'
   ],
diff --git a/src/components/responsive/ResponsiveContainer.tsx b/src/components/responsive/ResponsiveContainer.tsx
index 0e1f61e7..6d5201d8 100644
--- a/src/components/responsive/ResponsiveContainer.tsx
+++ b/src/components/responsive/ResponsiveContainer.tsx
@@ -1,15 +1,27 @@
 /**
  * ResponsiveContainer Component
- * 
+ *
  * A container component with responsive padding that scales with viewport size.
  * Provides consistent padding across all pages with fluid scaling between breakpoints.
- * 
+ *
+ * Accessibility (WCAG 2.1):
+ * - Supports polymorphic `as` prop so consumers can render semantic HTML elements
+ *   (main, section, article, aside, header, footer, nav) instead of a plain <div>.
+ * - Accepts `aria-label`, `aria-labelledby`, and `aria-describedby` to give
+ *   screen readers a meaningful context for landmark / sectioning elements.
+ * - Accepts `role` so consumers can assign explicit ARIA landmark roles when a
+ *   native semantic element is not appropriate.
+ * - Forwards all standard HTML div attributes so keyboard-navigation props
+ *   (tabIndex, onKeyDown, etc.) flow through without extra wrapping.
+ * - The `data-testid` attribute defaults to `"responsive-container"` to make
+ *   the element easily targetable in automated accessibility tests.
+ *
  * Features:
  * - Responsive padding: 16px (mobile) → 24px (tablet) → 32px (desktop)
  * - Fluid scaling between breakpoints using CSS clamp()
  * - Uses Viewport Provider for viewport detection
  * - Supports custom className for additional styling
- * 
+ *
  * Requirements: 3.1, 3.2, 8.5
  */
 
@@ -19,27 +31,91 @@ import React from 'react';
 import { useViewport } from '@/providers/ViewportProvider';
 import { cn } from '@/lib/utils';
 
-export interface ResponsiveContainerProps {
+// ---------------------------------------------------------------------------
+// Allowed semantic element types for the polymorphic `as` prop
+// ---------------------------------------------------------------------------
+type AllowedElement =
+  | 'div'
+  | 'main'
+  | 'section'
+  | 'article'
+  | 'aside'
+  | 'header'
+  | 'footer'
+  | 'nav';
+
+export interface ResponsiveContainerProps
+  extends React.HTMLAttributes<HTMLElement> {
   children: React.ReactNode;
   className?: string;
+
+  /**
+   * Render as a semantic HTML element instead of a plain <div>.
+   * Defaults to "div".
+   *
+   * @example
+   * <ResponsiveContainer as="main" aria-label="Main content">
+   *   ...
+   * </ResponsiveContainer>
+   */
+  as?: AllowedElement;
+
+  /**
+   * ARIA role override. Useful when `as="div"` but a landmark role is needed.
+   * Prefer using the `as` prop with a native semantic element where possible,
+   * as that provides better screen-reader compatibility.
+   */
+  role?: React.AriaRole;
+
+  /**
+   * Accessible label for this container region.
+   * Required (or `aria-labelledby`) when the container is rendered as a
+   * landmark element (main, nav, section, aside, etc.) so that screen readers
+   * can distinguish multiple regions of the same type.
+   */
+  'aria-label'?: string;
+
+  /** References the id of an element that labels this container region. */
+  'aria-labelledby'?: string;
+
+  /** References the id of an element that describes this container region. */
+  'aria-describedby'?: string;
+
+  /** data-testid for automated testing. Defaults to "responsive-container". */
+  'data-testid'?: string;
 }
 
 /**
  * ResponsiveContainer provides consistent, viewport-aware padding
- * 
+ *
  * Padding scales:
  * - Mobile (<768px): 16px
  * - Tablet (768-1024px): 24px (fluid scaling)
  * - Desktop (≥1024px): 32px
- * 
- * @example
+ *
+ * @example Basic usage
  * ```tsx
  * <ResponsiveContainer>
  *   <h1>Page Content</h1>
  *   <p>This content has responsive padding</p>
  * </ResponsiveContainer>
  * ```
- * 
+ *
+ * @example Semantic landmark — accessible main content region
+ * ```tsx
+ * <ResponsiveContainer as="main" aria-label="Main content">
+ *   <h1>Welcome</h1>
+ * </ResponsiveContainer>
+ * ```
+ *
+ * @example Navigation region
+ * ```tsx
+ * <ResponsiveContainer as="nav" aria-label="Primary navigation">
+ *   <a href="/home">Home</a>
+ *   <a href="/properties">Properties</a>
+ * </ResponsiveContainer>
+ * ```
+ *
  * @example With custom className
  * ```tsx
  * <ResponsiveContainer className="bg-gray-100">
@@ -50,11 +126,13 @@ export interface ResponsiveContainerProps {
 export const ResponsiveContainer: React.FC<ResponsiveContainerProps> = ({
   children,
   className,
+  as: Element = 'div',
+  'data-testid': testId = 'responsive-container',
+  ...rest
 }) => {
   const { category } = useViewport();
 
   // Calculate padding based on viewport category
-  // Using inline styles for precise control, but could also use Tailwind classes
   const getPadding = (): string => {
     switch (category) {
       case 'mobile':
@@ -69,7 +147,7 @@ export const ResponsiveContainer: React.FC<ResponsiveContainerProps> = ({
   };
 
   return (
-    <div
+    <Element
       className={cn('responsive-container', className)}
       style={{
         padding: getPadding(),
@@ -77,35 +155,74 @@ export const ResponsiveContainer: React.FC<ResponsiveContainerProps> = ({
         maxWidth: '100%',
         boxSizing: 'border-box',
       }}
+      data-testid={testId}
+      {...rest}
     >
       {children}
-    </div>
+    </Element>
   );
 };
 
+// ---------------------------------------------------------------------------
+// Fluid variant
+// ---------------------------------------------------------------------------
+
+export interface ResponsiveContainerFluidProps
+  extends React.HTMLAttributes<HTMLElement> {
+  children: React.ReactNode;
+  className?: string;
+
+  /**
+   * Render as a semantic HTML element. Defaults to "div".
+   */
+  as?: AllowedElement;
+
+  role?: React.AriaRole;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+  'aria-describedby'?: string;
+
+  /** data-testid for automated testing. Defaults to "responsive-container-fluid". */
+  'data-testid'?: string;
+}
+
 /**
- * Alternative implementation using CSS clamp() for fluid scaling
- * This version provides smooth scaling between breakpoints
+ * Alternative implementation using CSS clamp() for fluid scaling.
+ * This version provides smooth scaling between breakpoints.
+ *
+ * @example
+ * ```tsx
+ * <ResponsiveContainerFluid as="section" aria-labelledby="section-title">
+ *   <h2 id="section-title">Section Heading</h2>
+ *   <p>Content with fluid responsive padding</p>
+ * </ResponsiveContainerFluid>
+ * ```
  */
-export const ResponsiveContainerFluid: React.FC<ResponsiveContainerProps> = ({
+export const ResponsiveContainerFluid: React.FC<
+  ResponsiveContainerFluidProps
+> = ({
   children,
   className,
+  as: Element = 'div',
+  'data-testid': testId = 'responsive-container-fluid',
+  ...rest
 }) => {
   return (
-    <div
+    <Element
       className={cn('responsive-container-fluid', className)}
       style={{
         // Fluid padding using clamp()
         // Formula: clamp(min, preferred, max)
-        // Preferred value scales linearly: min + (max - min) * (viewport - minViewport) / (maxViewport - minViewport)
-        // Using CSS calc with viewport units for automatic scaling
+        // Scales linearly from 16px at narrow viewports to 32px at wide viewports
         padding: 'clamp(16px, 4vw, 32px)',
         maxWidth: '100%',
         boxSizing: 'border-box',
       }}
+      data-testid={testId}
+      {...rest}
     >
       {children}
-    </div>
+    </Element>
   );
 };
 
diff --git a/src/components/responsive/ResponsiveContainerExample.tsx b/src/components/responsive/ResponsiveContainerExample.tsx
index c5c05a1c..88fa553e 100644
--- a/src/components/responsive/ResponsiveContainerExample.tsx
+++ b/src/components/responsive/ResponsiveContainerExample.tsx
@@ -1,7 +1,8 @@
 /**
  * ResponsiveContainer Usage Examples
- * 
- * Demonstrates various use cases for the ResponsiveContainer component
+ *
+ * Demonstrates various use cases for the ResponsiveContainer component,
+ * including accessibility best-practices (semantic elements, ARIA labels).
  */
 
 'use client';
@@ -29,8 +30,14 @@ export function BasicContainerExample() {
  */
 export function StyledContainerExample() {
   return (
-    <ResponsiveContainer className="bg-gray-100 rounded-lg shadow-md">
-      <h2 className="text-xl font-semibold mb-2">Property Details</h2>
+    <ResponsiveContainer
+      as="section"
+      aria-labelledby="property-details-heading"
+      className="bg-gray-100 rounded-lg shadow-md"
+    >
+      <h2 id="property-details-heading" className="text-xl font-semibold mb-2">
+        Property Details
+      </h2>
       <div className="space-y-2">
         <p><strong>Location:</strong> San Francisco, CA</p>
         <p><strong>Price:</strong> $1,200,000</p>
@@ -46,17 +53,33 @@ export function StyledContainerExample() {
  */
 export function NestedContainersExample() {
   return (
-    <ResponsiveContainer className="bg-blue-50">
-      <h2 className="text-xl font-bold mb-4">Dashboard</h2>
-      
+    <ResponsiveContainer
+      as="section"
+      aria-labelledby="dashboard-heading"
+      className="bg-blue-50"
+    >
+      <h2 id="dashboard-heading" className="text-xl font-bold mb-4">
+        Dashboard
+      </h2>
+
       <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
-        <ResponsiveContainer className="bg-white rounded-lg shadow">
-          <h3 className="font-semibold mb-2">Statistics</h3>
+        <ResponsiveContainer
+          as="section"
+          aria-labelledby="stats-heading"
+          className="bg-white rounded-lg shadow"
+        >
+          <h3 id="stats-heading" className="font-semibold mb-2">Statistics</h3>
           <p>Total Properties: 42</p>
         </ResponsiveContainer>
-        
-        <ResponsiveContainer className="bg-white rounded-lg shadow">
-          <h3 className="font-semibold mb-2">Recent Activity</h3>
+
+        <ResponsiveContainer
+          as="section"
+          aria-labelledby="activity-heading"
+          className="bg-white rounded-lg shadow"
+        >
+          <h3 id="activity-heading" className="font-semibold mb-2">
+            Recent Activity
+          </h3>
           <p>Last updated: 5 minutes ago</p>
         </ResponsiveContainer>
       </div>
@@ -69,11 +92,18 @@ export function NestedContainersExample() {
  */
 export function FluidContainerExample() {
   return (
-    <ResponsiveContainerFluid className="bg-gradient-to-r from-purple-100 to-pink-100">
-      <h2 className="text-xl font-bold mb-4">Fluid Padding Container</h2>
+    <ResponsiveContainerFluid
+      as="section"
+      aria-labelledby="fluid-heading"
+      className="bg-gradient-to-r from-purple-100 to-pink-100"
+    >
+      <h2 id="fluid-heading" className="text-xl font-bold mb-4">
+        Fluid Padding Container
+      </h2>
       <p className="text-gray-700">
         This container uses CSS clamp() for smooth, fluid padding that scales
-        continuously with the viewport width. Resize your browser to see the effect!
+        continuously with the viewport width. Resize your browser to see the
+        effect!
       </p>
       <p className="text-sm text-gray-600 mt-2">
         Padding scales from 16px to 32px using: clamp(16px, 4vw, 32px)
@@ -83,44 +113,52 @@ export function FluidContainerExample() {
 }
 
 /**
- * Full page layout example
+ * Full page layout example — uses semantic landmark elements throughout
  */
 export function PageLayoutExample() {
   return (
     <div className="min-h-screen bg-gray-50">
-      {/* Header */}
-      <ResponsiveContainer className="bg-white border-b">
-        <header className="py-4">
-          <h1 className="text-2xl font-bold">PropChain</h1>
-          <nav className="mt-2">
-            <a href="#" className="mr-4 text-blue-600">Home</a>
-            <a href="#" className="mr-4 text-blue-600">Properties</a>
-            <a href="#" className="mr-4 text-blue-600">About</a>
+      {/* Header landmark */}
+      <ResponsiveContainer as="header" className="bg-white border-b">
+        <div className="py-4">
+          <p className="text-2xl font-bold">PropChain</p>
+          {/* Navigation landmark with descriptive label */}
+          <nav aria-label="Primary navigation" className="mt-2">
+            <a href="/home" className="mr-4 text-blue-600">
+              Home
+            </a>
+            <a href="/properties" className="mr-4 text-blue-600">
+              Properties
+            </a>
+            <a href="/about" className="mr-4 text-blue-600">
+              About
+            </a>
           </nav>
-        </header>
+        </div>
       </ResponsiveContainer>
 
-      {/* Main content */}
-      <ResponsiveContainer className="py-8">
-        <main>
-          <h2 className="text-xl font-semibold mb-4">Featured Properties</h2>
-          <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
-            {[1, 2, 3].map((i) => (
-              <div key={i} className="bg-white rounded-lg shadow p-4">
-                <div className="h-48 bg-gray-200 rounded mb-4"></div>
-                <h3 className="font-semibold">Property {i}</h3>
-                <p className="text-gray-600">$500,000</p>
-              </div>
-            ))}
-          </div>
-        </main>
+      {/* Main content landmark */}
+      <ResponsiveContainer as="main" aria-label="Main content" className="py-8">
+        <h1 className="text-xl font-semibold mb-4">Featured Properties</h1>
+        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+          {[1, 2, 3].map((i) => (
+            <article key={i} className="bg-white rounded-lg shadow p-4">
+              <div
+                className="h-48 bg-gray-200 rounded mb-4"
+                aria-hidden="true"
+              />
+              <h2 className="font-semibold">Property {i}</h2>
+              <p className="text-gray-600">$500,000</p>
+            </article>
+          ))}
+        </div>
       </ResponsiveContainer>
 
-      {/* Footer */}
-      <ResponsiveContainer className="bg-gray-800 text-white mt-12">
-        <footer className="py-8">
+      {/* Footer landmark */}
+      <ResponsiveContainer as="footer" className="bg-gray-800 text-white mt-12">
+        <div className="py-8">
           <p>&copy; 2024 PropChain. All rights reserved.</p>
-        </footer>
+        </div>
       </ResponsiveContainer>
     </div>
   );
@@ -133,9 +171,15 @@ export function ComparisonExample() {
   return (
     <div className="space-y-8">
       <div>
-        <h2 className="text-lg font-bold mb-2 px-4">Step-based Container (Default)</h2>
-        <ResponsiveContainer className="bg-blue-100">
-          <p>
+        <h2 className="text-lg font-bold mb-2 px-4">
+          Step-based Container (Default)
+        </h2>
+        <ResponsiveContainer
+          as="section"
+          aria-labelledby="step-based-heading"
+          className="bg-blue-100"
+        >
+          <p id="step-based-heading">
             This container uses step-based padding that changes at breakpoints:
             16px (mobile) → 24px (tablet) → 32px (desktop)
           </p>
@@ -144,10 +188,14 @@ export function ComparisonExample() {
 
       <div>
         <h2 className="text-lg font-bold mb-2 px-4">Fluid Container</h2>
-        <ResponsiveContainerFluid className="bg-green-100">
-          <p>
-            This container uses fluid padding that scales smoothly with viewport width
-            using CSS clamp(16px, 4vw, 32px)
+        <ResponsiveContainerFluid
+          as="section"
+          aria-labelledby="fluid-desc-heading"
+          className="bg-green-100"
+        >
+          <p id="fluid-desc-heading">
+            This container uses fluid padding that scales smoothly with viewport
+            width using CSS clamp(16px, 4vw, 32px)
           </p>
         </ResponsiveContainerFluid>
       </div>
@@ -168,35 +216,48 @@ export default function ResponsiveContainerDemo() {
         </p>
       </ResponsiveContainer>
 
-      <section>
+      <section aria-labelledby="basic-heading">
         <ResponsiveContainer>
-          <h2 className="text-2xl font-semibold mb-4">Basic Usage</h2>
+          <h2 id="basic-heading" className="text-2xl font-semibold mb-4">
+            Basic Usage
+          </h2>
         </ResponsiveContainer>
         <BasicContainerExample />
       </section>
 
-      <section>
+      <section aria-labelledby="styled-heading">
         <ResponsiveContainer>
-          <h2 className="text-2xl font-semibold mb-4">Styled Container</h2>
+          <h2 id="styled-heading" className="text-2xl font-semibold mb-4">
+            Styled Container
+          </h2>
         </ResponsiveContainer>
         <StyledContainerExample />
       </section>
 
-      <section>
+      <section aria-labelledby="comparison-heading">
         <ResponsiveContainer>
-          <h2 className="text-2xl font-semibold mb-4">Fluid vs Step-based</h2>
+          <h2 id="comparison-heading" className="text-2xl font-semibold mb-4">
+            Fluid vs Step-based
+          </h2>
         </ResponsiveContainer>
         <ComparisonExample />
       </section>
 
-      <section>
+      <section aria-labelledby="nested-heading">
         <ResponsiveContainer>
-          <h2 className="text-2xl font-semibold mb-4">Nested Containers</h2>
+          <h2 id="nested-heading" className="text-2xl font-semibold mb-4">
+            Nested Containers
+          </h2>
         </ResponsiveContainer>
         <NestedContainersExample />
       </section>
 
-      <section>
+      <section aria-labelledby="fluid-example-heading">
+        <ResponsiveContainer>
+          <h2 id="fluid-example-heading" className="text-2xl font-semibold mb-4">
+            Fluid Container
+          </h2>
+        </ResponsiveContainer>
         <FluidContainerExample />
       </section>
     </div>
diff --git a/src/components/responsive/__tests__/ResponsiveContainer.test.tsx b/src/components/responsive/__tests__/ResponsiveContainer.test.tsx
new file mode 100644
index 00000000..f32e3633
--- /dev/null
+++ b/src/components/responsive/__tests__/ResponsiveContainer.test.tsx
@@ -0,0 +1,549 @@
+/**
+ * Accessibility tests for ResponsiveContainer and ResponsiveContainerFluid
+ *
+ * Issue #341 — WCAG 2.1 review covering:
+ * - Semantic HTML / landmark elements via the `as` prop
+ * - ARIA attributes: aria-label, aria-labelledby, aria-describedby, role
+ * - Screen reader label propagation
+ * - Keyboard navigation passthrough (tabIndex, onKeyDown)
+ * - data-testid defaults
+ * - No console.log calls in production code
+ * - Responsive padding per viewport category
+ * - Fluid variant behaviour
+ */
+
+import React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+
+import {
+  ResponsiveContainer,
+  ResponsiveContainerFluid,
+  type ResponsiveContainerProps,
+} from '../ResponsiveContainer';
+
+// ---------------------------------------------------------------------------
+// Mock ViewportProvider so we control the viewport category in tests
+// ---------------------------------------------------------------------------
+const mockUseViewport = jest.fn();
+
+jest.mock('@/providers/ViewportProvider', () => ({
+  useViewport: () => mockUseViewport(),
+}));
+
+// ---------------------------------------------------------------------------
+// Helper — render with a controlled viewport category
+// ---------------------------------------------------------------------------
+function renderWithViewport(
+  ui: React.ReactElement,
+  category: 'mobile' | 'tablet' | 'desktop' = 'mobile'
+) {
+  mockUseViewport.mockReturnValue({ category });
+  return render(ui);
+}
+
+// ---------------------------------------------------------------------------
+// ResponsiveContainer — default rendering
+// ---------------------------------------------------------------------------
+
+describe('ResponsiveContainer — default rendering', () => {
+  beforeEach(() => {
+    mockUseViewport.mockReturnValue({ category: 'mobile' });
+  });
+
+  it('renders children', () => {
+    render(<ResponsiveContainer>Hello world</ResponsiveContainer>);
+    expect(screen.getByText('Hello world')).toBeInTheDocument();
+  });
+
+  it('renders as a <div> by default', () => {
+    const { container } = render(
+      <ResponsiveContainer>Content</ResponsiveContainer>
+    );
+    expect(container.firstChild?.nodeName).toBe('DIV');
+  });
+
+  it('has data-testid="responsive-container" by default', () => {
+    render(<ResponsiveContainer>Content</ResponsiveContainer>);
+    expect(screen.getByTestId('responsive-container')).toBeInTheDocument();
+  });
+
+  it('accepts a custom data-testid', () => {
+    render(
+      <ResponsiveContainer data-testid="my-container">Content</ResponsiveContainer>
+    );
+    expect(screen.getByTestId('my-container')).toBeInTheDocument();
+  });
+
+  it('merges additional className with base class', () => {
+    render(
+      <ResponsiveContainer className="bg-gray-100">Content</ResponsiveContainer>
+    );
+    const el = screen.getByTestId('responsive-container');
+    expect(el).toHaveClass('responsive-container');
+    expect(el).toHaveClass('bg-gray-100');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ResponsiveContainer — responsive padding
+// ---------------------------------------------------------------------------
+
+describe('ResponsiveContainer — responsive padding', () => {
+  it('applies 16px padding on mobile', () => {
+    renderWithViewport(
+      <ResponsiveContainer>Content</ResponsiveContainer>,
+      'mobile'
+    );
+    expect(screen.getByTestId('responsive-container')).toHaveStyle({
+      padding: '16px',
+    });
+  });
+
+  it('applies 24px padding on tablet', () => {
+    renderWithViewport(
+      <ResponsiveContainer>Content</ResponsiveContainer>,
+      'tablet'
+    );
+    expect(screen.getByTestId('responsive-container')).toHaveStyle({
+      padding: '24px',
+    });
+  });
+
+  it('applies 32px padding on desktop', () => {
+    renderWithViewport(
+      <ResponsiveContainer>Content</ResponsiveContainer>,
+      'desktop'
+    );
+    expect(screen.getByTestId('responsive-container')).toHaveStyle({
+      padding: '32px',
+    });
+  });
+
+  it('falls back to 16px for unknown viewport category', () => {
+    mockUseViewport.mockReturnValue({ category: 'unknown' });
+    render(<ResponsiveContainer>Content</ResponsiveContainer>);
+    expect(screen.getByTestId('responsive-container')).toHaveStyle({
+      padding: '16px',
+    });
+  });
+
+  it('sets maxWidth: 100% and boxSizing: border-box', () => {
+    renderWithViewport(
+      <ResponsiveContainer>Content</ResponsiveContainer>,
+      'desktop'
+    );
+    const el = screen.getByTestId('responsive-container');
+    expect(el).toHaveStyle({ maxWidth: '100%', boxSizing: 'border-box' });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ResponsiveContainer — polymorphic `as` prop (WCAG: semantic landmarks)
+// ---------------------------------------------------------------------------
+
+describe('ResponsiveContainer — polymorphic `as` prop', () => {
+  beforeEach(() => {
+    mockUseViewport.mockReturnValue({ category: 'desktop' });
+  });
+
+  const semanticElements: Array<
+    'div' | 'main' | 'section' | 'article' | 'aside' | 'header' | 'footer' | 'nav'
+  > = ['div', 'main', 'section', 'article', 'aside', 'header', 'footer', 'nav'];
+
+  semanticElements.forEach((tag) => {
+    it(`renders as <${tag}> when as="${tag}"`, () => {
+      const { container } = render(
+        <ResponsiveContainer as={tag}>Content</ResponsiveContainer>
+      );
+      expect(container.firstChild?.nodeName).toBe(tag.toUpperCase());
+    });
+  });
+
+  it('renders a <main> landmark accessible to screen readers', () => {
+    render(
+      <ResponsiveContainer as="main" aria-label="Main content">
+        Content
+      </ResponsiveContainer>
+    );
+    expect(screen.getByRole('main', { name: 'Main content' })).toBeInTheDocument();
+  });
+
+  it('renders a <nav> landmark with accessible name', () => {
+    render(
+      <ResponsiveContainer as="nav" aria-label="Primary navigation">
+        <a href="/home">Home</a>
+      </ResponsiveContainer>
+    );
+    expect(
+      screen.getByRole('navigation', { name: 'Primary navigation' })
+    ).toBeInTheDocument();
+  });
+
+  it('renders an <aside> landmark with accessible name', () => {
+    render(
+      <ResponsiveContainer as="aside" aria-label="Related content">
+        Sidebar
+      </ResponsiveContainer>
+    );
+    expect(
+      screen.getByRole('complementary', { name: 'Related content' })
+    ).toBeInTheDocument();
+  });
+
+  it('renders a <section> with aria-labelledby referencing a heading', () => {
+    render(
+      <ResponsiveContainer as="section" aria-labelledby="sec-title">
+        <h2 id="sec-title">Section Title</h2>
+        <p>Content</p>
+      </ResponsiveContainer>
+    );
+    expect(
+      screen.getByRole('region', { name: 'Section Title' })
+    ).toBeInTheDocument();
+  });
+
+  it('renders an <article> element', () => {
+    const { container } = render(
+      <ResponsiveContainer as="article" aria-label="Property card">
+        Property details
+      </ResponsiveContainer>
+    );
+    expect(container.firstChild?.nodeName).toBe('ARTICLE');
+    expect(screen.getByRole('article', { name: 'Property card' })).toBeInTheDocument();
+  });
+
+  it('renders a <header> element', () => {
+    const { container } = render(
+      <ResponsiveContainer as="header">Site header</ResponsiveContainer>
+    );
+    expect(container.firstChild?.nodeName).toBe('HEADER');
+  });
+
+  it('renders a <footer> element', () => {
+    const { container } = render(
+      <ResponsiveContainer as="footer">Site footer</ResponsiveContainer>
+    );
+    expect(container.firstChild?.nodeName).toBe('FOOTER');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ResponsiveContainer — ARIA attributes (WCAG 1.3.1, 4.1.2)
+// ---------------------------------------------------------------------------
+
+describe('ResponsiveContainer — ARIA attributes', () => {
+  beforeEach(() => {
+    mockUseViewport.mockReturnValue({ category: 'desktop' });
+  });
+
+  it('forwards aria-label to the rendered element', () => {
+    render(
+      <ResponsiveContainer aria-label="Property listing section">
+        Content
+      </ResponsiveContainer>
+    );
+    expect(
+      screen.getByLabelText('Property listing section')
+    ).toBeInTheDocument();
+  });
+
+  it('forwards aria-labelledby to the rendered element', () => {
+    render(
+      <>
+        <h2 id="label-id">Container Label</h2>
+        <ResponsiveContainer aria-labelledby="label-id">
+          Content
+        </ResponsiveContainer>
+      </>
+    );
+    const el = screen.getByTestId('responsive-container');
+    expect(el).toHaveAttribute('aria-labelledby', 'label-id');
+  });
+
+  it('forwards aria-describedby to the rendered element', () => {
+    render(
+      <>
+        <p id="desc-id">Description text</p>
+        <ResponsiveContainer aria-describedby="desc-id">
+          Content
+        </ResponsiveContainer>
+      </>
+    );
+    const el = screen.getByTestId('responsive-container');
+    expect(el).toHaveAttribute('aria-describedby', 'desc-id');
+  });
+
+  it('forwards an explicit role to the rendered element', () => {
+    render(
+      <ResponsiveContainer role="region" aria-label="Custom region">
+        Content
+      </ResponsiveContainer>
+    );
+    expect(
+      screen.getByRole('region', { name: 'Custom region' })
+    ).toBeInTheDocument();
+  });
+
+  it('does not set aria-label by default (no spurious ARIA on generic containers)', () => {
+    render(<ResponsiveContainer>Content</ResponsiveContainer>);
+    const el = screen.getByTestId('responsive-container');
+    expect(el).not.toHaveAttribute('aria-label');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ResponsiveContainer — keyboard navigation passthrough (WCAG 2.1.1)
+// ---------------------------------------------------------------------------
+
+describe('ResponsiveContainer — keyboard navigation', () => {
+  beforeEach(() => {
+    mockUseViewport.mockReturnValue({ category: 'desktop' });
+  });
+
+  it('forwards tabIndex so the container can participate in tab order', () => {
+    render(
+      <ResponsiveContainer tabIndex={0}>Focusable container</ResponsiveContainer>
+    );
+    const el = screen.getByTestId('responsive-container');
+    expect(el).toHaveAttribute('tabindex', '0');
+  });
+
+  it('tabIndex={-1} removes element from natural tab order', () => {
+    render(
+      <ResponsiveContainer tabIndex={-1}>Content</ResponsiveContainer>
+    );
+    expect(screen.getByTestId('responsive-container')).toHaveAttribute(
+      'tabindex',
+      '-1'
+    );
+  });
+
+  it('forwards onKeyDown handler for keyboard interactions', () => {
+    const onKeyDown = jest.fn();
+    render(
+      <ResponsiveContainer tabIndex={0} onKeyDown={onKeyDown}>
+        Content
+      </ResponsiveContainer>
+    );
+    fireEvent.keyDown(screen.getByTestId('responsive-container'), {
+      key: 'Enter',
+    });
+    expect(onKeyDown).toHaveBeenCalledTimes(1);
+  });
+
+  it('forwards onClick handler', () => {
+    const onClick = jest.fn();
+    render(
+      <ResponsiveContainer onClick={onClick}>Content</ResponsiveContainer>
+    );
+    fireEvent.click(screen.getByTestId('responsive-container'));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ResponsiveContainer — no console.log (issue #341 / production hygiene)
+// ---------------------------------------------------------------------------
+
+describe('ResponsiveContainer — no console.log in production code', () => {
+  beforeEach(() => {
+    mockUseViewport.mockReturnValue({ category: 'mobile' });
+  });
+
+  it('does not call console.log during render', () => {
+    const spy = jest.spyOn(console, 'log');
+    render(<ResponsiveContainer>Content</ResponsiveContainer>);
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+
+  it('does not call console.log on viewport category change', () => {
+    const spy = jest.spyOn(console, 'log');
+    const { rerender } = render(
+      <ResponsiveContainer>Content</ResponsiveContainer>
+    );
+    mockUseViewport.mockReturnValue({ category: 'desktop' });
+    rerender(<ResponsiveContainer>Content</ResponsiveContainer>);
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ResponsiveContainerFluid — rendering and accessibility
+// ---------------------------------------------------------------------------
+
+describe('ResponsiveContainerFluid — default rendering', () => {
+  it('renders children', () => {
+    render(<ResponsiveContainerFluid>Fluid content</ResponsiveContainerFluid>);
+    expect(screen.getByText('Fluid content')).toBeInTheDocument();
+  });
+
+  it('renders as a <div> by default', () => {
+    const { container } = render(
+      <ResponsiveContainerFluid>Content</ResponsiveContainerFluid>
+    );
+    expect(container.firstChild?.nodeName).toBe('DIV');
+  });
+
+  it('has data-testid="responsive-container-fluid" by default', () => {
+    render(<ResponsiveContainerFluid>Content</ResponsiveContainerFluid>);
+    expect(screen.getByTestId('responsive-container-fluid')).toBeInTheDocument();
+  });
+
+  it('accepts a custom data-testid', () => {
+    render(
+      <ResponsiveContainerFluid data-testid="fluid-custom">
+        Content
+      </ResponsiveContainerFluid>
+    );
+    expect(screen.getByTestId('fluid-custom')).toBeInTheDocument();
+  });
+
+  it('applies clamp() fluid padding', () => {
+    render(<ResponsiveContainerFluid>Content</ResponsiveContainerFluid>);
+    expect(screen.getByTestId('responsive-container-fluid')).toHaveStyle({
+      padding: 'clamp(16px, 4vw, 32px)',
+    });
+  });
+
+  it('sets maxWidth: 100% and boxSizing: border-box', () => {
+    render(<ResponsiveContainerFluid>Content</ResponsiveContainerFluid>);
+    expect(screen.getByTestId('responsive-container-fluid')).toHaveStyle({
+      maxWidth: '100%',
+      boxSizing: 'border-box',
+    });
+  });
+});
+
+describe('ResponsiveContainerFluid — polymorphic `as` prop', () => {
+  it('renders as <section> with aria-labelledby', () => {
+    render(
+      <ResponsiveContainerFluid as="section" aria-labelledby="fluid-title">
+        <h2 id="fluid-title">Fluid Section</h2>
+        <p>Content</p>
+      </ResponsiveContainerFluid>
+    );
+    expect(
+      screen.getByRole('region', { name: 'Fluid Section' })
+    ).toBeInTheDocument();
+  });
+
+  it('renders as <main> with aria-label', () => {
+    render(
+      <ResponsiveContainerFluid as="main" aria-label="Main fluid content">
+        Content
+      </ResponsiveContainerFluid>
+    );
+    expect(
+      screen.getByRole('main', { name: 'Main fluid content' })
+    ).toBeInTheDocument();
+  });
+
+  it('renders as <nav> with aria-label', () => {
+    render(
+      <ResponsiveContainerFluid as="nav" aria-label="Fluid nav">
+        <a href="/home">Home</a>
+      </ResponsiveContainerFluid>
+    );
+    expect(
+      screen.getByRole('navigation', { name: 'Fluid nav' })
+    ).toBeInTheDocument();
+  });
+});
+
+describe('ResponsiveContainerFluid — ARIA attributes', () => {
+  it('forwards aria-label', () => {
+    render(
+      <ResponsiveContainerFluid aria-label="Fluid region">
+        Content
+      </ResponsiveContainerFluid>
+    );
+    expect(screen.getByLabelText('Fluid region')).toBeInTheDocument();
+  });
+
+  it('forwards aria-describedby', () => {
+    render(
+      <>
+        <p id="fluid-desc">Description</p>
+        <ResponsiveContainerFluid aria-describedby="fluid-desc">
+          Content
+        </ResponsiveContainerFluid>
+      </>
+    );
+    expect(screen.getByTestId('responsive-container-fluid')).toHaveAttribute(
+      'aria-describedby',
+      'fluid-desc'
+    );
+  });
+
+  it('forwards tabIndex for keyboard navigation', () => {
+    render(
+      <ResponsiveContainerFluid tabIndex={0}>Content</ResponsiveContainerFluid>
+    );
+    expect(screen.getByTestId('responsive-container-fluid')).toHaveAttribute(
+      'tabindex',
+      '0'
+    );
+  });
+
+  it('does not call console.log during render', () => {
+    const spy = jest.spyOn(console, 'log');
+    render(<ResponsiveContainerFluid>Content</ResponsiveContainerFluid>);
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Edge cases
+// ---------------------------------------------------------------------------
+
+describe('ResponsiveContainer — edge cases', () => {
+  beforeEach(() => {
+    mockUseViewport.mockReturnValue({ category: 'mobile' });
+  });
+
+  it('renders without optional props', () => {
+    expect(() =>
+      render(<ResponsiveContainer>Minimal</ResponsiveContainer>)
+    ).not.toThrow();
+  });
+
+  it('renders deeply nested children', () => {
+    render(
+      <ResponsiveContainer>
+        <div>
+          <ul>
+            <li>Item 1</li>
+            <li>Item 2</li>
+          </ul>
+        </div>
+      </ResponsiveContainer>
+    );
+    expect(screen.getByText('Item 1')).toBeInTheDocument();
+    expect(screen.getByText('Item 2')).toBeInTheDocument();
+  });
+
+  it('renders multiple sibling containers independently', () => {
+    render(
+      <>
+        <ResponsiveContainer data-testid="container-a">A</ResponsiveContainer>
+        <ResponsiveContainer data-testid="container-b">B</ResponsiveContainer>
+      </>
+    );
+    expect(screen.getByTestId('container-a')).toBeInTheDocument();
+    expect(screen.getByTestId('container-b')).toBeInTheDocument();
+  });
+
+  it('forwards unknown HTML attributes to the root element', () => {
+    render(
+      <ResponsiveContainer data-custom="value">Content</ResponsiveContainer>
+    );
+    expect(screen.getByTestId('responsive-container')).toHaveAttribute(
+      'data-custom',
+      'value'
+    );
+  });
+});