@primer/doctocat-nextjs 0.7.0 → 0.7.1-rc.bf9f37a

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @primer/doctocat-nextjs
 
+## 0.7.1
+
+### Patch Changes
+
+- [#68](https://github.com/primer/doctocat-nextjs/pull/68) [`b75584e`](https://github.com/primer/doctocat-nextjs/commit/b75584edb6936a70ea94925fc743989422cc3d9a) Thanks [@janmaarten-a11y](https://github.com/janmaarten-a11y)! - Improve screen reader accessibility by updating sidebar navigation heading hierarchy. The sidebar title now uses a semantic `<Heading>` component with visually hidden text to clarify it's a navigation area, and is properly connected to the `<NavList>` via `aria-labelledby`.
+
 ## 0.7.0
 
 ### Minor Changes

package/components/content/caption/Caption.module.css

@@ -0,0 +1,6 @@
+.Caption {
+  margin-top: var(--base-size-8);
+  margin-bottom: var(--base-size-12);
+  font-size: var(--brand-text-size-100);
+  color: var(--brand-color-text-default);
+}

package/components/content/caption/Caption.tsx

@@ -1,6 +1,11 @@
 import React, {PropsWithChildren} from 'react'
-import {Text} from '@primer/react'
+import styles from './Caption.module.css'
 
 export function Caption(props: PropsWithChildren) {
-  return <Text as="span" {...props} sx={{mt: 2, mb: 3, fontSize: 1, color: 'var(--brand-color-text-default)'}} />
+  const {children, ...rest} = props
+  return (
+    <span className={styles.Caption} {...rest}>
+      {children}
+    </span>
+  )
 }

package/components/content/dos-and-donts/DosAndDonts.module.css

@@ -39,6 +39,10 @@
   color: var(--base-color-scale-white-0);
 }
 
+.header {
+  color: var(--fgColor-onEmphasis, var(--color-fg-on-emphasis));
+}
+
 .content {
   display: flex;
   flex-direction: column;
@@ -55,6 +59,6 @@
 
 .indentedContent {
   margin: 0;
-  border-left: 4px solid;
+  border-left: 4px solid var(--brand-color-border-default);
   padding-left: 1rem;
 }

package/components/content/dos-and-donts/DosAndDonts.tsx

@@ -1,5 +1,4 @@
 import React from 'react'
-import {Box} from '@primer/react'
 import clsx from 'clsx'
 import styles from './DosAndDonts.module.css'
 
@@ -39,22 +38,11 @@ type DoDontBaseProps = {
 export function DoDontBase({children, title, indented, className, ...rest}: React.PropsWithChildren<DoDontBaseProps>) {
   return (
     <div className={clsx(`exclude-from-prose`, styles.doDontBase, className)} {...rest}>
-      <Box
-        className={styles.header}
-        sx={{
-          color: 'var(--fgColor-onEmphasis, var(--color-fg-on-emphasis))',
-        }}
-      >
+      <div className={styles.header}>
         <span className={styles.headerText}>{title}</span>
-      </Box>
+      </div>
       <div className={styles.content}>
-        {indented ? (
-          <blockquote className={styles.indentedContent} style={{borderLeftColor: 'var(--brand-color-border-default)'}}>
-            {children}
-          </blockquote>
-        ) : (
-          children
-        )}
+        {indented ? <blockquote className={styles.indentedContent}>{children}</blockquote> : children}
       </div>
     </div>
   )

package/components/layout/nav-drawer/Drawer.module.css

@@ -0,0 +1,19 @@
+.DrawerOverlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.5);
+  z-index: 1;
+}
+
+.DrawerPanel {
+  position: fixed;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: 300px;
+  background: var(--brand-color-canvas-default, var(--color-canvas-default));
+  z-index: 1;
+  display: flex;
+  flex-direction: column;
+}
+

package/components/layout/nav-drawer/Drawer.tsx

@@ -1,7 +1,7 @@
 import React, {PropsWithChildren} from 'react'
-import {Box} from '@primer/react'
 import {AnimatePresence, motion} from 'framer-motion'
 import {FocusOn} from 'react-focus-on'
+import styles from './Drawer.module.css'
 
 type Drawer = {
   isOpen: boolean
@@ -22,29 +22,26 @@ export function Drawer({isOpen, onDismiss, children}: PropsWithChildren<Drawer>)
           tabIndex={0}
         >
           <FocusOn returnFocus={true} onEscapeKey={() => onDismiss()}>
-            <Box
+            <motion.div
               key="overlay"
-              as={motion.div}
+              className={styles.DrawerOverlay}
               initial={{opacity: 0}}
               animate={{opacity: 1}}
               exit={{opacity: 0}}
               transition={{type: 'tween'}}
               onClick={() => onDismiss()}
-              sx={{top: 0, right: 0, bottom: 0, left: 0, bg: 'rgba(0, 0, 0, 0.5)', position: 'fixed', zIndex: 1}}
             />
 
-            <Box
+            <motion.div
               key="drawer"
-              as={motion.div}
+              className={styles.DrawerPanel}
               initial={{x: '100%'}}
               animate={{x: 0}}
               exit={{x: '100%'}}
               transition={{type: 'tween', duration: 0.2}}
-              style={{zIndex: 1}}
-              sx={{width: 300, top: 0, right: 0, bottom: 0, bg: 'gray.0', position: 'fixed'}}
             >
               {children}
-            </Box>
+            </motion.div>
           </FocusOn>
         </div>
       ) : null}

package/components/layout/root-layout/Theme.module.css

@@ -0,0 +1,35 @@
+.StickyHeader {
+  position: sticky;
+  top: 0;
+  z-index: 99;
+}
+
+.ContentContainer {
+  max-width: 1200px;
+  width: 100%;
+  margin: 0 auto;
+}
+
+.BreadcrumbRoot,
+.BreadcrumbItem {
+  color: var(--brand-InlineLink-color-rest);
+}
+
+.BreadcrumbItem {
+  text-transform: capitalize;
+}
+
+.HeroImageWrapper {
+  padding-block-start: var(--base-size-16);
+  width: 100%;
+}
+
+
+.ActionsWrapper {
+  padding-block-start: var(--base-size-16);
+}
+
+
+.RelatedLinks {
+  padding-top: var(--base-size-20);
+}

package/components/layout/root-layout/Theme.tsx

@@ -4,13 +4,12 @@ import NextLink from 'next/link'
 import Head from 'next/head'
 import type {Folder, MdxFile, PageMapItem} from 'nextra'
 import {useFSRoute} from 'nextra/hooks'
-import {BaseStyles, Box as PRCBox, Breadcrumbs, PageLayout, ThemeProvider} from '@primer/react'
+import {BaseStyles, Breadcrumbs, PageLayout, ThemeProvider} from '@primer/react'
 import '@primer/primitives/dist/css/functional/themes/light.css'
 import '@primer/primitives/dist/css/functional/themes/dark.css'
 import {
   Animate,
   AnimationProvider,
-  Box,
   ButtonGroup,
   ThemeProvider as BrandThemeProvider,
   Button,
@@ -38,6 +37,7 @@ import {RelatedContentLinks} from '../related-content-links/RelatedContentLinks'
 import {getRelatedPages} from '../related-content-links/getRelatedPages'
 import {hasChildren} from '../../../helpers/hasChildren'
 import {Footer} from '../footer/Footer'
+import styles from './Theme.module.css'
 
 const repoSrcPath = process.env.NEXT_PUBLIC_REPO_SRC_PATH || ''
 const repoURL = process.env.NEXT_PUBLIC_REPO || ''
@@ -119,16 +119,10 @@ export function Theme({pageMap, children}: ThemeProps) {
             </Head>
 
             <ContentWrapper disableAnimations={disablePageAnimation}>
-              <PRCBox
-                sx={{
-                  position: 'sticky',
-                  top: 0,
-                  zIndex: 99,
-                }}
-              >
+              <div className={styles.StickyHeader}>
                 <SkipToMainContent href="#main">Skip to main content</SkipToMainContent>
                 <Header flatDocsDirectories={flatDocsDirectories} siteTitle={siteTitle} pageMap={pageMap} />
-              </PRCBox>
+              </div>
               <PageLayout rowGap="none" columnGap="none" padding="none" containerWidth="full">
                 <PageLayout.Pane
                   width="small"
@@ -145,20 +139,14 @@ export function Theme({pageMap, children}: ThemeProps) {
                 </PageLayout.Pane>
                 <PageLayout.Content padding="normal">
                   <div id="main">
-                    <PRCBox sx={!isHomePage && {maxWidth: 1200, width: '100%', margin: '0 auto'}}>
+                    <div style={!isHomePage ? {maxWidth: 1200, width: '100%', margin: '0 auto'} : undefined}>
                       <Stack direction="vertical" padding="none" gap="spacious">
                         {!isHomePage && (
                           <>
                             {activePath.length > 0 && (
-                              <Breadcrumbs>
+                              <Breadcrumbs className={styles.BreadcrumbRoot}>
                                 {(activeHeaderLink || siteTitle) && (
-                                  <Breadcrumbs.Item
-                                    as={NextLink}
-                                    href="/"
-                                    sx={{
-                                      color: 'var(--brand-InlineLink-color-rest)',
-                                    }}
-                                  >
+                                  <Breadcrumbs.Item as={NextLink} href="/">
                                     {activeHeaderLink ? activeHeaderLink.title : siteTitle}
                                   </Breadcrumbs.Item>
                                 )}
@@ -192,10 +180,7 @@ export function Theme({pageMap, children}: ThemeProps) {
                                         key={item.name}
                                         href={item.route}
                                         selected={isLastItem}
-                                        sx={{
-                                          textTransform: 'capitalize',
-                                          color: 'var(--brand-InlineLink-color-rest)',
-                                        }}
+                                        className={styles.BreadcrumbItem}
                                       >
                                         {itemTitle.replace(/-/g, ' ')}
                                       </Breadcrumbs.Item>
@@ -204,7 +189,7 @@ export function Theme({pageMap, children}: ThemeProps) {
                               </Breadcrumbs>
                             )}
 
-                            <Box>
+                            <div>
                               <Stack direction="vertical" padding="none" gap={12} alignItems="flex-start">
                                 {activeMetadata.title && (
                                   <Heading as="h1" size="3">
@@ -217,12 +202,12 @@ export function Theme({pageMap, children}: ThemeProps) {
                                   </Text>
                                 )}
                                 {activeMetadata.image && (
-                                  <Box paddingBlockStart={16} style={{width: '100%'}}>
+                                  <div className={styles.HeroImageWrapper}>
                                     <Hero.Image src={activeMetadata.image} alt={activeMetadata['image-alt']} />
-                                  </Box>
+                                  </div>
                                 )}
                                 {activeMetadata['action-1-text'] && (
-                                  <Box paddingBlockStart={16}>
+                                  <div className={styles.ActionsWrapper}>
                                     <ButtonGroup>
                                       <Button as="a" href={activeMetadata['action-1-link']}>
                                         {activeMetadata['action-1-text']}
@@ -233,10 +218,10 @@ export function Theme({pageMap, children}: ThemeProps) {
                                         </Button>
                                       )}
                                     </ButtonGroup>
-                                  </Box>
+                                  </div>
                                 )}
                               </Stack>
-                            </Box>
+                            </div>
                             {activeMetadata['show-tabs'] && <UnderlineNav tabData={filteredTabData} />}
                           </>
                         )}
@@ -248,16 +233,16 @@ export function Theme({pageMap, children}: ThemeProps) {
                               <>{children}</>
 
                               {relatedLinks.length > 0 && (
-                                <PRCBox sx={{pt: 5}}>
+                                <div className={styles.RelatedLinks}>
                                   <RelatedContentLinks links={relatedLinks} />
-                                </PRCBox>
+                                </div>
                               )}
                             </>
                           )}
                         </article>
                         <Footer filePath={filePath} repoURL={repoURL} repoSrcPath={repoSrcPath} />
                       </Stack>
-                    </PRCBox>
+                    </div>
                   </div>
                 </PageLayout.Content>
               </PageLayout>

package/components/layout/sidebar/Sidebar.module.css

@@ -19,6 +19,14 @@
   font-size: var(--brand-text-size-100);
 }
 
+.NavListGroup {
+  margin-bottom: var(--base-size-24);
+}
+
+.NavListItemCapitalize {
+  text-transform: capitalize;
+}
+
 .NavList__Container li a,
 .NavList__Container li button {
   font-size: var(--brand-text-size-200);

package/components/layout/sidebar/Sidebar.tsx

@@ -1,7 +1,7 @@
 import React, {useMemo} from 'react'
 import NextLink from 'next/link'
 import {NavList} from '@primer/react'
-import {Text} from '@primer/react-brand'
+import {Heading} from '@primer/react-brand'
 import type {Folder, MdxFile, PageMapItem} from 'nextra'
 
 import styles from './Sidebar.module.css'
@@ -49,12 +49,12 @@ export function Sidebar({pageMap}: SidebarProps) {
   return (
     <div className={styles.Sidebar}>
       {activeHeaderLink && (
-        <Text size="400" weight="semibold" className={styles.Sidebar__title}>
+        <Heading as="h2" size="6" className={styles.Sidebar__title} id="nav-list-heading">
           {activeHeaderLink.title}
-        </Text>
+          <span className="visually-hidden"> navigation</span>
+        </Heading>
       )}
-
-      <NavList className={styles.NavList} aria-label="Menu links">
+      <NavList className={styles.NavList} aria-labelledby="nav-list-heading">
         {reorderedPageMap.map(item => {
           if (item.hasOwnProperty('data')) return null
 
@@ -77,7 +77,7 @@ export function Sidebar({pageMap}: SidebarProps) {
           }
 
           return (
-            <NavList.Group title={subNavName} key={item.name} sx={{mb: 24}}>
+            <NavList.Group title={subNavName} key={item.name} className={styles.NavListGroup}>
               <NavList.GroupHeading as="h3">
                 <NextLink href={item.route}>{subNavName}</NextLink>
               </NavList.GroupHeading>
@@ -142,9 +142,8 @@ export function Sidebar({pageMap}: SidebarProps) {
                         as={NextLink}
                         key={landingPageItem.route}
                         href={landingPageItem.route}
-                        sx={{textTransform: 'capitalize'}}
                         aria-current={isCurrentOrChild ? 'page' : undefined}
-                        className={styles.NavListItem}
+                        className={`${styles.NavListItem} ${styles.NavListItemCapitalize}`}
                       >
                         {landingPageItem.frontMatter?.title || item.name}
                       </NavList.Item>
@@ -155,7 +154,7 @@ export function Sidebar({pageMap}: SidebarProps) {
           )
         })}
         {sidebarLinks.length > 0 && (
-          <NavList.Group title="" sx={{mb: 24}}>
+          <NavList.Group title="" className={styles.NavListGroup}>
             {sidebarLinks.map(link => {
               return (
                 <NavList.Item

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@primer/doctocat-nextjs",
-  "version": "0.7.0",
+  "version": "0.7.1-rc.bf9f37a",
   "description": "A Next.js theme for building Primer documentation sites",
   "main": "index.js",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/primer/doctocat-nextjs.git"
+  },
   "scripts": {
     "check": "tsc --noEmit",
     "lint": "eslint '**/*.{js,ts,tsx,md,mdx}' --max-warnings=0 --config ./.eslintrc.cjs",
@@ -23,7 +27,7 @@
   "dependencies": {
     "@next/mdx": "15.5.2",
     "@primer/octicons-react": "19.15.1",
-    "@primer/react": "^37.11.0",
+    "@primer/react": "^38.0.0",
     "@types/lodash.debounce": "^4.0.9",
     "framer-motion": "12.4.0",
     "lodash.debounce": "^4.0.8",