Enforce web interface guidelines: a11y, motion & theming fixes + eslint gate

.eslintrc.js

@@ -184,6 +184,27 @@ module.exports = {
     ],
     "no-sparse-arrays": "error",
     "no-template-curly-in-string": "error",
+    // Web interface guidelines — mechanical design rules enforced inside
+    // styled-components template literals.
+    // See docs/design/web-interface-guidelines.md
+    "no-restricted-syntax": [
+      "error",
+      {
+        selector: "TemplateElement[value.raw=/transition:\\s*all/]",
+        message:
+          "Avoid `transition: all` — list only the properties you animate (web interface guidelines).",
+      },
+      {
+        selector: "TemplateElement[value.raw=/[^-\\w]:focus(?![-\\w])/]",
+        message:
+          "Prefer `:focus-visible` over `:focus` for focus styling (web interface guidelines).",
+      },
+      {
+        selector: "TemplateElement[value.raw=/outline:\\s*(none|0)\\b/]",
+        message:
+          "Don't remove `outline` without a visible focus replacement (web interface guidelines).",
+      },
+    ],
     "no-throw-literal": "error",
     "no-trailing-spaces": "off",
     "no-undef-init": "error",

src/ThemeProvider.tsx

@@ -1,4 +1,5 @@
 import React, { createContext, FC, useMemo } from "react"
+import { Helmet } from "react-helmet"
 import { ThemeProvider as BaseThemeProvider } from "styled-components"
 
 import { darkTheme, lightTheme } from "./design/themes"
@@ -62,6 +63,11 @@ const ThemeProvider: FC<IScopedDownChildren> = ({ children }) => {
   return (
     <ThemeContext.Provider value={contextValue}>
       <BaseThemeProvider theme={themeObject}>
+        <Helmet
+          meta={[
+            { name: "theme-color", content: themeObject.main.background },
+          ]}
+        />
         {isBrowser ? children : undefined}
       </BaseThemeProvider>
     </ThemeContext.Provider>

src/components/Footer/styles.tsx

@@ -22,7 +22,7 @@ export const FooterWrapper = styled.footer`
     }
 
     &:hover,
-    &:focus {
+    &:focus-visible {
       background: linear-gradient(92.97deg, #feaf6d 0%, #ff70a5 100%);
       background-clip: text;
       -webkit-background-clip: text;

src/components/FourZeroFourHint/styles.tsx

@@ -9,7 +9,7 @@ export const StyledLink = styled(Link)`
   transition: color 0.3s;
 
   &:hover,
-  &:focus {
+  &:focus-visible {
     color: #5dbbea;
     transition: none;
   }

src/components/Home/styles.tsx

@@ -111,7 +111,8 @@ export const MenuItemLine = styled.div`
   margin-top: -3px;
   bottom: 0;
   background: ${(props) => props.theme.main.foreground};
-  transition: all 0.3s;
+  transition: padding 0.3s, height 0.3s, background 0.3s, box-shadow 0.3s,
+    margin 0.3s, border-radius 0.3s;
   left: 0;
 `
 

src/components/Link/styles.tsx

@@ -23,7 +23,7 @@ const linkStyle = css`
   }
 
   &:hover,
-  &:focus {
+  &:focus-visible {
     background: linear-gradient(92.97deg, #feaf6d 0%, #ff70a5 100%);
     background-clip: text;
     -webkit-background-clip: text;

src/components/Markdown/styles.tsx

@@ -42,6 +42,7 @@ export const MarkdownWrapper = styled.div`
     overflow-wrap: break-word;
     margin-top: ${BASE_LINE_HEIGHT * 2}px;
     margin-bottom: ${BASE_LINE_HEIGHT}px;
+    scroll-margin-top: 80px;
   }
 
   h1 {
@@ -178,7 +179,7 @@ export const MarkdownWrapper = styled.div`
     background-repeat: no-repeat;
     background-size: 100% 3px;
     background-position: 0 100%;
-    transition: all 0.125s ease-in;
+    transition: color 0.125s ease-in, background-size 0.125s ease-in;
     font-weight: 700;
     word-break: break-all;
     &:hover {

src/components/PageNavigation/styles.tsx

@@ -22,7 +22,7 @@ export const NavLink = styled(Link)`
   text-decoration: none;
 
   &:hover,
-  &:focus {
+  &:focus-visible {
     color: ${(props) => props.theme.main.foreground};
     text-decoration: underline;
   }

src/components/PageSidebarLink/styles.tsx

@@ -7,7 +7,7 @@ const extraLink = css`
   word-break: break-word;
 
   &:hover,
-  &:focus {
+  &:focus-visible {
     text-decoration: underline;
   }
 `

src/components/ThemeToggler/index.tsx

@@ -6,7 +6,7 @@ export const ThemeToggler: FC = () => {
   const { theme, toggleTheme } = useTheme()
 
   return (
-    <SC.ThemeTogglerWrapper onClick={toggleTheme}>
+    <SC.ThemeTogglerWrapper type="button" onClick={toggleTheme}>
       <SC.Link>Switch to {theme === "dark" ? "light" : "dark"} mode</SC.Link>
     </SC.ThemeTogglerWrapper>
   )

src/components/ThemeToggler/styles.tsx

@@ -1,7 +1,17 @@
 import { transparentize } from "polished"
 import styled from "styled-components"
 
-export const ThemeTogglerWrapper = styled.div``
+export const ThemeTogglerWrapper = styled.button`
+  display: block;
+  width: 100%;
+  padding: 0;
+  border: none;
+  background: none;
+  font: inherit;
+  color: inherit;
+  text-align: left;
+  cursor: pointer;
+`
 
 export const Link = styled.span`
   display: inline-block;

src/globalStyles.tsx

@@ -8,6 +8,7 @@ import {
 export const GlobalStyles = createGlobalStyle`
   html {
     font-family: ${fontFamily.body};
+    color-scheme: ${(props) => props.theme.name};
     -ms-text-size-adjust: 100%;
     -webkit-text-size-adjust: 100%;
   }
@@ -19,4 +20,23 @@ export const GlobalStyles = createGlobalStyle`
     -webkit-font-smoothing: antialiased;
     -moz-osx-font-smoothing: grayscale;
   }
+
+  a,
+  button,
+  label,
+  summary,
+  [role="button"] {
+    touch-action: manipulation;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+      scroll-behavior: auto !important;
+    }
+  }
 `

src/layouts/ColumnLayout/index.tsx

@@ -35,10 +35,11 @@ const InnerColumnLayout: FC<IColumnLayoutProps> = ({
   return (
     <Fragment>
       <GlobalStyles />
+      <SC.SkipLink href="#main-content">Skip to content</SC.SkipLink>
       <SC.Main>
         <MobileHeader openMenu={openMenu}>{title}</MobileHeader>
         {sidebar({ className: openOnMobile ? "is-open" : "" })}
-        <SC.MainContent>{content}</SC.MainContent>
+        <SC.MainContent id="main-content">{content}</SC.MainContent>
       </SC.Main>
       <SC.Overlay
         className={openOnMobile ? "is-open" : ""}

src/layouts/ColumnLayout/styles.tsx

@@ -1,5 +1,24 @@
 import styled from "styled-components"
 
+export const SkipLink = styled.a`
+  position: fixed;
+  left: 8px;
+  top: -56px;
+  z-index: 200;
+  padding: 8px 16px;
+  border-radius: 4px;
+  background: ${(props) => props.theme.main.background};
+  color: ${(props) => props.theme.main.foreground};
+  font-weight: 700;
+  text-decoration: none;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.25);
+  transition: top 0.15s ease-in;
+
+  &:focus-visible {
+    top: 8px;
+  }
+`
+
 export const Main = styled.div`
   display: flex;
   width: 100%;

src/layouts/HomeLayout/styles.tsx

@@ -29,7 +29,7 @@ export const MainContent = styled.main`
     transition: color 0.3s;
 
     &:hover,
-    &:focus {
+    &:focus-visible {
       color: #5dbbea;
       transition: none;
     }