feat: enhance responsive design and accessibility in documentation layout and styles

LabEG · LabEG · commit 6c3e9678ff9d · 2026-04-29T22:55:19.000+03:00
diff --git a/packages/reca-docs/app/globals.css b/packages/reca-docs/app/globals.css
@@ -8,6 +8,8 @@ html,
 body {
     max-width: 100vw;
     overflow-x: hidden;
+    /* Prevent content overflow from breaking sticky AppBar on mobile */
+    -webkit-text-size-adjust: 100%;
 }
 
 a {
diff --git a/packages/reca-docs/app/layout.tsx b/packages/reca-docs/app/layout.tsx
@@ -1,8 +1,13 @@
-import type {Metadata} from "next";
+import type {Metadata, Viewport} from "next";
 import "./globals.css";
 import {type JSX} from "react";
 import {ThemeRegistry} from "../src/components/theme-registry/theme-registry.js";
 
+export const viewport: Viewport = {
+    width: "device-width",
+    initialScale: 1
+};
+
 export const metadata: Metadata = {
     title: "ReCA Documentation",
     description: "Documentation for ReCA — React Clean Architecture state manager"
diff --git a/packages/reca-docs/src/components/doc-content/doc-content.styles.ts b/packages/reca-docs/src/components/doc-content/doc-content.styles.ts
@@ -4,6 +4,7 @@ export const DocArticle = styled("article")`
     line-height: 1.8;
     color: #333;
     max-width: 820px;
+    width: 100%;
 
     h1 {
         font-size: 2rem;
@@ -30,8 +31,25 @@ export const DocArticle = styled("article")`
         color: #333;
     }
 
+    /* Tablet: 600px – 899px */
+    @media (max-width: 899px) {
+        h1 { font-size: 1.65rem; }
+        h2 { font-size: 1.25rem; margin-top: 32px; }
+        h3 { font-size: 1.05rem; margin-top: 22px; }
+    }
+
+    /* Mobile: < 600px */
+    @media (max-width: 599px) {
+        line-height: 1.7;
+        h1 { font-size: 1.4rem; }
+        h2 { font-size: 1.15rem; margin-top: 24px; }
+        h3 { font-size: 1rem; margin-top: 18px; }
+    }
+
     p {
         margin-bottom: 16px;
+        overflow-wrap: break-word;
+        word-break: break-word;
     }
 
     code {
@@ -40,6 +58,8 @@ export const DocArticle = styled("article")`
         border-radius: 4px;
         font-size: 0.88em;
         font-family: 'Fira Code', 'Consolas', 'Monaco', monospace;
+        overflow-wrap: break-word;
+        word-break: break-all;
     }
 
     pre {
@@ -48,10 +68,17 @@ export const DocArticle = styled("article")`
         padding: 20px 24px;
         border-radius: 8px;
         overflow-x: auto;
+        max-width: 100%;
         margin-bottom: 24px;
         font-size: 0.88rem;
         line-height: 1.6;
 
+        @media (max-width: 599px) {
+            padding: 14px 16px;
+            font-size: 0.82rem;
+            border-radius: 6px;
+        }
+
         code {
             background: none;
             padding: 0;
@@ -148,8 +175,17 @@ export const DocArticle = styled("article")`
         }
     }
 
+    /* Wrap tables for horizontal scroll on small screens */
+    .table-wrapper,
+    table {
+        display: block;
+        overflow-x: auto;
+        -webkit-overflow-scrolling: touch;
+    }
+
     table {
         width: 100%;
+        min-width: 480px;
         border-collapse: collapse;
         margin-bottom: 24px;
         font-size: 0.9rem;
@@ -166,7 +202,25 @@ export const DocArticle = styled("article")`
         font-weight: 600;
     }
 
+    @media (max-width: 599px) {
+        th, td {
+            padding: 8px 10px;
+            font-size: 0.82rem;
+        }
+    }
+
     strong {
         font-weight: 600;
     }
+
+    img {
+        max-width: 100%;
+        height: auto;
+    }
+
+    /* Long URLs and identifiers in paragraphs should wrap */
+    a {
+        overflow-wrap: break-word;
+        word-break: break-word;
+    }
 `;
diff --git a/packages/reca-docs/src/components/shell/shell.styles.ts b/packages/reca-docs/src/components/shell/shell.styles.ts
@@ -2,20 +2,38 @@ import styled from "@emotion/styled";
 
 export const DRAWER_WIDTH = 280;
 
+/* AppBar (Toolbar) height: 56px on xs, 64px on sm+ */
+export const TOOLBAR_HEIGHT_MOBILE = 56;
+export const TOOLBAR_HEIGHT_DESKTOP = 64;
+
 export const MainContent = styled("main", {
     shouldForwardProp: (prop) => prop !== "drawerWidth"
 })<{drawerWidth: number}>`
     flex-grow: 1;
+    /* min-width: 0 prevents flex child from overflowing its container */
+    min-width: 0;
+    max-width: 100%;
+    overflow-x: hidden;
     padding: 40px 48px;
-    margin-top: 64px;
-    min-height: calc(100vh - 64px);
+    margin-top: ${TOOLBAR_HEIGHT_DESKTOP}px;
+    min-height: calc(100vh - ${TOOLBAR_HEIGHT_DESKTOP}px);
 
     @media (min-width: 900px) {
         margin-left: ${({drawerWidth}) => drawerWidth}px;
     }
 
-    @media (max-width: 600px) {
-        padding: 24px 16px;
+    /* Tablet: 600px – 899px */
+    @media (min-width: 600px) and (max-width: 899px) {
+        padding: 28px 32px;
+        margin-top: ${TOOLBAR_HEIGHT_DESKTOP}px;
+        min-height: calc(100vh - ${TOOLBAR_HEIGHT_DESKTOP}px);
+    }
+
+    /* Mobile: < 600px */
+    @media (max-width: 599px) {
+        padding: 20px 16px;
+        margin-top: ${TOOLBAR_HEIGHT_MOBILE}px;
+        min-height: calc(100vh - ${TOOLBAR_HEIGHT_MOBILE}px);
     }
 `;
 
diff --git a/packages/reca-docs/src/components/shell/shell.tsx b/packages/reca-docs/src/components/shell/shell.tsx
@@ -12,7 +12,6 @@ import {
     ListItemText,
     Toolbar,
     Typography,
-    useMediaQuery,
     useTheme
 } from "@mui/material";
 import MenuIcon from "@mui/icons-material/Menu";
@@ -22,7 +21,7 @@ import GitHubIcon from "@mui/icons-material/GitHub";
 import Link from "next/link";
 import {usePathname} from "next/navigation";
 import {type INavGroup, navigation} from "../../navigation.js";
-import {DRAWER_WIDTH, LogoWrapper, MainContent} from "./shell.styles.js";
+import {DRAWER_WIDTH, TOOLBAR_HEIGHT_DESKTOP, TOOLBAR_HEIGHT_MOBILE, LogoWrapper, MainContent} from "./shell.styles.js";
 
 interface IShellProps {
     readonly children: ReactNode;
@@ -31,14 +30,12 @@ interface IShellProps {
 export const Shell = ({children}: IShellProps): JSX.Element => {
     const muiTheme = useTheme();
     const pathname = usePathname();
-    const isMobile = useMediaQuery(muiTheme.breakpoints.down("md"));
     const [mobileOpen, setMobileOpen] = useState(false);
     const [openSections, setOpenSections] = useState<Record<string, boolean>>(() => {
         const initial: Record<string, boolean> = {};
         for (const group of navigation) {
             initial[group.label] = true;
         }
-
         return initial;
     });
 
@@ -50,69 +47,30 @@ export const Shell = ({children}: IShellProps): JSX.Element => {
         setOpenSections((prev) => ({...prev, [label]: !prev[label]}));
     };
 
-    const handleMobileClose = (): void => {
-        if (isMobile) {
-            setMobileOpen(false);
-        }
-    };
-
     const isActive = (path: string): boolean => pathname === path || pathname === `${path}/`;
 
     const drawerContent = (
-        <Box sx={{mt: "64px", overflowY: "auto", py: 1}}>
+        <Box sx={{mt: {xs: `${TOOLBAR_HEIGHT_MOBILE}px`, sm: `${TOOLBAR_HEIGHT_DESKTOP}px`}, overflowY: "auto", py: 1}}>
             <List component="nav" disablePadding>
                 {navigation.map((group: INavGroup) => (
                     <Box key={group.label}>
-                        <ListItemButton
-                            onClick={() => handleSectionToggle(group.label)}
-                            sx={{py: 0.8, px: 2.5}}
-                        >
+                        <ListItemButton onClick={() => handleSectionToggle(group.label)} sx={{py: 0.8, px: 2.5}}>
                             <ListItemText
                                 primary={group.label}
-                                slotProps={{
-                                    primary: {
-                                        sx: {
-                                            fontWeight: 700,
-                                            fontSize: "0.75rem",
-                                            textTransform: "uppercase",
-                                            letterSpacing: "0.08em",
-                                            color: "text.secondary"
-                                        }
-                                    }
-                                }}
+                                slotProps={{primary: {sx: {fontWeight: 700, fontSize: "0.75rem", textTransform: "uppercase", letterSpacing: "0.08em", color: "text.secondary"}}}}
                             />
-                            {openSections[group.label]
-                                ? <ExpandLess fontSize="small" />
-                                : <ExpandMore fontSize="small" />}
+                            {openSections[group.label] ? <ExpandLess fontSize="small" /> : <ExpandMore fontSize="small" />}
                         </ListItemButton>
                         <Collapse in={openSections[group.label]} timeout="auto" unmountOnExit>
                             <List component="div" disablePadding>
                                 {group.items.map((item) => (
                                     <Link key={item.path} href={item.path} style={{textDecoration: "none", color: "inherit"}}>
                                         <ListItemButton
-                                            onClick={handleMobileClose}
+                                            onClick={() => setMobileOpen(false)}
                                             selected={isActive(item.path)}
-                                            sx={{
-                                                pl: 4,
-                                                py: 0.5,
-                                                "&.Mui-selected": {
-                                                    backgroundColor: "rgba(25, 118, 210, 0.08)",
-                                                    borderRight: "3px solid #1976d2",
-                                                    "& .MuiListItemText-primary": {
-                                                        color: "#1976d2",
-                                                        fontWeight: 600
-                                                    }
-                                                }
-                                            }}
+                                            sx={{pl: 4, py: 0.5, "&.Mui-selected": {backgroundColor: "rgba(25, 118, 210, 0.08)", borderRight: "3px solid #1976d2", "& .MuiListItemText-primary": {color: "#1976d2", fontWeight: 600}}}}
                                         >
-                                            <ListItemText
-                                                primary={item.label}
-                                                slotProps={{
-                                                    primary: {
-                                                        sx: {fontSize: "0.9rem"}
-                                                    }
-                                                }}
-                                            />
+                                            <ListItemText primary={item.label} slotProps={{primary: {sx: {fontSize: "0.9rem"}}}} />
                                         </ListItemButton>
                                     </Link>
                                 ))}
@@ -125,91 +83,44 @@ export const Shell = ({children}: IShellProps): JSX.Element => {
     );
 
     return (
-        <Box sx={{display: "flex"}}>
-            <AppBar
-                position="fixed"
-                sx={{
-                    zIndex: muiTheme.zIndex.drawer + 1,
-                    backgroundColor: "#fff",
-                    color: "#333",
-                    boxShadow: "0 1px 3px rgba(0, 0, 0, 0.08)"
-                }}
-            >
+        <Box sx={{display: "flex", overflow: "hidden"}}>
+            <AppBar position="fixed" sx={{zIndex: muiTheme.zIndex.drawer + 1, backgroundColor: "#fff", color: "#333", boxShadow: "0 1px 3px rgba(0, 0, 0, 0.08)"}}>
                 <Toolbar>
-                    {isMobile && (
-                        <IconButton
-                            edge="start"
-                            onClick={handleDrawerToggle}
-                            sx={{mr: 1}}
-                        >
-                            <MenuIcon />
-                        </IconButton>
-                    )}
+                    <IconButton edge="start" onClick={handleDrawerToggle} sx={{mr: 1, display: {md: "none"}}}>
+                        <MenuIcon />
+                    </IconButton>
                     <LogoWrapper>
                         <Link href="/" style={{display: "flex", alignItems: "center", gap: 10, textDecoration: "none"}}>
-                            <Typography
-                                variant="h6"
-                                noWrap
-                                sx={{fontWeight: 800, color: "#1976d2"}}
-                            >
-                                ReCA
-                            </Typography>
-                            <Typography
-                                variant="body2"
-                                noWrap
-                                sx={{color: "#999", fontWeight: 400}}
-                            >
-                                Documentation
-                            </Typography>
+                            <Typography variant="h6" noWrap sx={{fontWeight: 800, color: "#1976d2"}}>ReCA</Typography>
+                            <Typography variant="body2" noWrap sx={{color: "#999", fontWeight: 400}}>Documentation</Typography>
                         </Link>
                     </LogoWrapper>
                     <Box sx={{flexGrow: 1}} />
-                    <IconButton
-                        component="a"
-                        href="https://github.com/LabEG/reca"
-                        target="_blank"
-                        rel="noopener noreferrer"
-                        sx={{color: "#555"}}
-                    >
+                    <IconButton component="a" href="https://github.com/LabEG/reca" target="_blank" rel="noopener noreferrer" sx={{color: "#555"}}>
                         <GitHubIcon />
                     </IconButton>
                 </Toolbar>
             </AppBar>
 
-            {isMobile
-                ? (
-                    <Drawer
-                        variant="temporary"
-                        open={mobileOpen}
-                        onClose={handleDrawerToggle}
-                        ModalProps={{keepMounted: true}}
-                        sx={{
-                            "& .MuiDrawer-paper": {
-                                width: DRAWER_WIDTH,
-                                boxSizing: "border-box"
-                            }
-                        }}
-                    >
-                        {drawerContent}
-                    </Drawer>
-                )
-                : (
-                    <Drawer
-                        variant="permanent"
-                        sx={{
-                            width: DRAWER_WIDTH,
-                            flexShrink: 0,
-                            "& .MuiDrawer-paper": {
-                                width: DRAWER_WIDTH,
-                                boxSizing: "border-box",
-                                borderRight: "1px solid #f0f0f0"
-                            }
-                        }}
-                        open
-                    >
-                        {drawerContent}
-                    </Drawer>
-                )}
+            <Box component="nav" sx={{display: {md: "none"}}}>
+                <Drawer
+                    variant="temporary"
+                    open={mobileOpen}
+                    onClose={handleDrawerToggle}
+                    ModalProps={{keepMounted: true}}
+                    sx={{"& .MuiDrawer-paper": {width: DRAWER_WIDTH, boxSizing: "border-box"}}}
+                >
+                    {drawerContent}
+                </Drawer>
+            </Box>
+
+            <Drawer
+                variant="permanent"
+                sx={{display: {xs: "none", md: "block"}, width: DRAWER_WIDTH, flexShrink: 0, "& .MuiDrawer-paper": {width: DRAWER_WIDTH, boxSizing: "border-box", borderRight: "1px solid #f0f0f0"}}}
+                open
+            >
+                {drawerContent}
+            </Drawer>
 
             <MainContent drawerWidth={DRAWER_WIDTH}>
                 {children}

Original file line number	Diff line number	Diff line change
`@@ -8,6 +8,8 @@ html,`
`8`	`8`	`body {`
`9`	`9`	`max-width: 100vw;`
`10`	`10`	`overflow-x: hidden;`
	`11`	`+ /* Prevent content overflow from breaking sticky AppBar on mobile */`
	`12`	`+ -webkit-text-size-adjust: 100%;`
`11`	`13`	`}`
`12`	`14`
`13`	`15`	`a {`