frontend/aria: page in general, lighthouse accessibility testing, ...

haraldschilly · haraldschilly · commit 8a47776c255c · 2025-11-13T15:32:26.000+01:00
diff --git a/src/dev/ARIA.md b/src/dev/ARIA.md
diff --git a/src/packages/frontend/account/avatar/avatar.tsx b/src/packages/frontend/account/avatar/avatar.tsx
@@ -234,7 +234,13 @@ const Avatar0: React.FC<Props> = (props) => {
 
   function render_inside() {
     if (image) {
-      return <img style={{ borderRadius: "50%", width: "100%" }} src={image} />;
+      return (
+        <img
+          alt={`User ${get_name()}`}
+          style={{ borderRadius: "50%", width: "100%" }}
+          src={image}
+        />
+      );
     } else {
       return render_letter();
     }
diff --git a/src/packages/frontend/app/i18n-banner.tsx b/src/packages/frontend/app/i18n-banner.tsx
@@ -52,7 +52,7 @@ export function useShowI18NBanner() {
   const i18n = other_settings?.get(OTHER_SETTINGS_LOCALE_KEY);
 
   return useMemo(() => {
-    // we show the banner, if the default locale is set and the browser langauge is not english
+    // we show the banner, if the default locale is set and the browser language is not english
     // user's can dismiss this, which sets the locale to "en-keep".
     if (i18n === DEFAULT_LOCALE) {
       if (!navigator.language.toLowerCase().startsWith("en")) {
diff --git a/src/packages/frontend/app/localize.tsx b/src/packages/frontend/app/localize.tsx
@@ -53,6 +53,11 @@ export function Localize({ children }: { children: React.ReactNode }) {
     setAntdLoc(await loadAntdLocale(locale));
   }, [locale]);
 
+  // Update HTML lang attribute for screen readers (WCAG AA)
+  useAsyncEffect(async () => {
+    document.documentElement.lang = locale;
+  }, [locale]);
+
   function renderApp() {
     // NOTE: the locale will be set from the other_settings, on the "page".
     // So, for the default (english) we always have to render it, and then, maybe, a locale is set...
diff --git a/src/packages/frontend/app/logo.tsx b/src/packages/frontend/app/logo.tsx
@@ -28,14 +28,15 @@ export const AppLogo: React.FC<Props> = React.memo((props: Props) => {
 
   const logo_square: string | undefined = useTypedRedux(
     "customize",
-    "logo_square"
+    "logo_square",
   );
 
   const backgroundImage = `url('${logo_square ? logo_square : APP_ICON}')`;
 
   return (
     <A
       href={appBasePath}
+      aria-label="CoCalc homepage"
       style={{
         height: dimension,
         width: dimension,
diff --git a/src/packages/frontend/app/page.tsx b/src/packages/frontend/app/page.tsx
@@ -230,6 +230,7 @@ export const Page: React.FC = () => {
           icon={"users"}
           active_top_tab={active_top_tab}
           hide_label={!show_label}
+          aria-label="Admin"
         />
       );
     }
diff --git a/src/packages/frontend/browser.ts b/src/packages/frontend/browser.ts
@@ -40,3 +40,31 @@ export function set_window_title(title?: string): void {
     document.title = site_name;
   }
 }
+
+// Set the meta description tag dynamically (WCAG AA)
+export function set_meta_description(): void {
+  const customize = redux.getStore("customize");
+  const site_name = customize.get("site_name");
+  const site_description = customize.get("site_description");
+
+  let description = "";
+  if (site_name && site_description) {
+    description = `${site_name}: ${site_description}`;
+  } else if (site_name) {
+    description = site_name;
+  } else if (site_description) {
+    description = site_description;
+  }
+
+  if (description.length > 0) {
+    let metaTag = document.querySelector(
+      'meta[name="description"]',
+    ) as HTMLMetaElement | null;
+    if (metaTag == null) {
+      metaTag = document.createElement("meta");
+      metaTag.name = "description";
+      document.head.appendChild(metaTag);
+    }
+    metaTag.content = description;
+  }
+}
diff --git a/src/packages/frontend/components/A.tsx b/src/packages/frontend/components/A.tsx
@@ -20,6 +20,7 @@ interface AProps {
   style?: CSSProperties;
   onClick?: (any) => void;
   onMouseDown?: (any) => void;
+  "aria-label"?: string;
 }
 
 export function A({
@@ -30,6 +31,7 @@ export function A({
   placement,
   onClick,
   onMouseDown,
+  "aria-label": ariaLabel,
 }: AProps) {
   if (title) {
     // use nicer antd tooltip.
@@ -40,6 +42,7 @@ export function A({
           target={"_blank"}
           rel={"noopener"}
           style={style}
+          aria-label={ariaLabel}
           onClick={onClick}
           onMouseDown={onMouseDown}
         >
@@ -55,6 +58,7 @@ export function A({
       rel={"noopener"}
       style={style}
       title={title}
+      aria-label={ariaLabel}
       onClick={onClick}
       onMouseDown={onMouseDown}
     >
diff --git a/src/packages/frontend/components/language-model-icon.tsx b/src/packages/frontend/components/language-model-icon.tsx
@@ -45,9 +45,10 @@ export function LanguageModelVendorAvatar(
     return fallback();
   }
 
-  function renderImgIcon(icon: string) {
+  function renderImgIcon(icon: string, vendorName: string) {
     return (
       <img
+        alt={`${vendorName} language model`}
         width={size}
         height={size}
         src={icon}
@@ -69,7 +70,7 @@ export function LanguageModelVendorAvatar(
           "icon",
         ]);
         if (useIcon && typeof icon === "string") {
-          return renderImgIcon(icon);
+          return renderImgIcon(icon, vendorName);
         } else {
           return <OpenAIAvatar size={size} style={style} />;
         }
@@ -92,7 +93,7 @@ export function LanguageModelVendorAvatar(
       case "ollama": {
         const icon = ollama?.getIn([fromOllamaModel(model), "icon"]);
         if (useIcon && typeof icon === "string") {
-          return renderImgIcon(icon);
+          return renderImgIcon(icon, vendorName);
         } else {
           return <OllamaAvatar size={size} style={style} />;
         }
diff --git a/src/packages/frontend/components/sortable-tabs.tsx b/src/packages/frontend/components/sortable-tabs.tsx
@@ -112,7 +112,7 @@ export function SortableTabs(props: Props) {
   }, [resize.width, items.length, divRef.current, isOver]);
 
   return (
-    <div style={{ width: "100%", ...style }} ref={divRef}>
+    <div role="tablist" style={{ width: "100%", ...style }} ref={divRef}>
       <ItemContext.Provider value={{ width: itemWidth }}>
         <DndContext
           onDragStart={onDragStart}
@@ -148,9 +148,13 @@ export function SortableTab({
   const { attributes, listeners, setNodeRef, transform, transition, active } =
     useSortable({ id });
 
+  // Extract role from attributes to avoid conflict with our role="tab"
+  const { role: _, ...restAttributes } = attributes;
+
   return (
     <div
       ref={setNodeRef}
+      role="tab"
       style={{
         ...style,
         transform: transform
@@ -159,7 +163,7 @@ export function SortableTab({
         transition,
         zIndex: active?.id == id ? 1 : undefined,
       }}
-      {...attributes}
+      {...restAttributes}
       {...listeners}
       onKeyDown={onKeyReturn ? ariaKeyDown(onKeyReturn, false) : undefined}
     >
diff --git a/src/packages/frontend/cspell.json b/src/packages/frontend/cspell.json
@@ -92,6 +92,7 @@
     "flyoutdragbar",
     "flyouts",
     "guttermarker",
+    "HiddenXSSM",
     "immutablejs",
     "ipynb",
     "isabs",
diff --git a/src/packages/frontend/customize.tsx b/src/packages/frontend/customize.tsx
@@ -33,6 +33,7 @@ import {
 } from "@cocalc/frontend/components";
 import { getGoogleCloudImages, getImages } from "@cocalc/frontend/compute/api";
 import { appBasePath } from "@cocalc/frontend/customize/app-base-path";
+import { set_meta_description } from "@cocalc/frontend/browser";
 import { labels, Locale } from "@cocalc/frontend/i18n";
 import { callback2, retry_until_success } from "@cocalc/util/async-utils";
 import {
@@ -261,7 +262,7 @@ export class CustomizeActions extends Actions<CustomizeState> {
       unlicensed_project_timetravel_limit: undefined,
     });
   };
-  
+
   reload = async () => {
     await loadCustomizeState();
   };
@@ -366,6 +367,15 @@ function set_customize(obj) {
 
   obj._is_configured = true;
   actions.setState(obj);
+
+  // Set meta description tag (WCAG AA)
+  // This must happen after setState to ensure customize store is updated
+  if (typeof window !== "undefined") {
+    // Only run in browser, not on server
+    setTimeout(() => {
+      set_meta_description();
+    }, 0);
+  }
 }
 
 function process_software(software, is_cocalc_com) {
diff --git a/src/packages/frontend/projects/project-avatar.tsx b/src/packages/frontend/projects/project-avatar.tsx
@@ -55,7 +55,8 @@ export function ProjectAvatarImage(props: ProjectAvatarImageProps) {
       <Avatar
         shape="square"
         size={size ?? 160}
-        icon={<img src={avatarImage} />}
+        src={avatarImage}
+        alt="Project avatar"
       />
     </div>
   ) : (
diff --git a/src/packages/frontend/projects/project-title.tsx b/src/packages/frontend/projects/project-title.tsx
@@ -55,7 +55,7 @@ export const ProjectTitle: React.FC<Props> = ({
   const body = (
     <>
       {avatar && (
-        <Avatar shape="circle" icon={<img src={avatar} />} size={20} />
+        <Avatar shape="circle" src={avatar} size={20} alt="Project avatar" />
       )}{" "}
       {html_to_text(trunc ? misc.trunc(title, trunc) : title)}
     </>
diff --git a/src/packages/frontend/projects/projects-nav.tsx b/src/packages/frontend/projects/projects-nav.tsx
@@ -186,7 +186,8 @@ function ProjectTab({ project_id }: ProjectTabProps) {
             border: color ? `2px solid ${color}` : undefined,
           }}
           shape="circle"
-          icon={<img src={project.get("avatar_image_tiny")} />}
+          src={project.get("avatar_image_tiny")}
+          alt="Project avatar"
           size={20}
         />
       );
diff --git a/src/packages/frontend/projects/projects-starred.tsx b/src/packages/frontend/projects/projects-starred.tsx
@@ -75,10 +75,13 @@ function DraggableProjectButton({
     <Button
       className="starred-project-button"
       style={buttonStyle}
-      aria-label={`${project.title}`}
       icon={
         project.avatar_image_tiny ? (
-          <Avatar src={project.avatar_image_tiny} size={20} />
+          <Avatar
+            src={project.avatar_image_tiny}
+            size={20}
+            alt="Project avatar"
+          />
         ) : (
           <Icon name="star-filled" style={{ color: COLORS.STAR }} />
         )
diff --git a/src/packages/frontend/projects/projects-table-columns.tsx b/src/packages/frontend/projects/projects-table-columns.tsx
@@ -213,7 +213,7 @@ export function getProjectTableColumns(
             {/* Avatar or placeholder */}
             <div style={{ flexShrink: 0, width: 40, height: 40 }}>
               {record.avatar ? (
-                <Avatar src={record.avatar} size={40} />
+                <Avatar src={record.avatar} size={40} alt="Project avatar" />
               ) : (
                 <div style={{ width: 40, height: 40 }} />
               )}
@@ -277,7 +277,7 @@ export function getProjectTableColumns(
                   }}
                 >
                   {cf.avatar ? (
-                    <Avatar src={cf.avatar} size={20} />
+                    <Avatar src={cf.avatar} size={20} alt={`User ${cf.text}`} />
                   ) : (
                     <Avatar size={20}>{cf.first_name[0]}</Avatar>
                   )}
diff --git a/src/packages/frontend/projects/projects-table-controls.tsx b/src/packages/frontend/projects/projects-table-controls.tsx
@@ -15,7 +15,7 @@ import type { SelectProps } from "antd";
 import { Button, Input, Select, Space, Switch } from "antd";
 import { Set } from "immutable";
 import { ReactNode, useMemo } from "react";
-import { useIntl } from "react-intl";
+import { defineMessage, useIntl } from "react-intl";
 
 import { useAutoFocusPreference } from "@cocalc/frontend/account";
 import { CSS, useActions, useTypedRedux } from "@cocalc/frontend/app-framework";
@@ -26,6 +26,17 @@ import { labels } from "@cocalc/frontend/i18n";
 
 import { get_visible_hashtags } from "./util";
 
+const messages = {
+  hidden: defineMessage({
+    id: "projects.table-controls.hidden.label",
+    defaultMessage: "Hidden",
+  }),
+  deleted: defineMessage({
+    id: "projects.table-controls.deleted.label",
+    defaultMessage: "Deleted",
+  }),
+};
+
 const CONTROLS_STYLE: CSS = {
   width: "100%",
   marginTop: "10px",
@@ -145,30 +156,16 @@ export function ProjectsTableControls({
         {!is_anonymous && (
           <Space ref={filtersRef}>
             <Switch
-              aria-label="Show hidden projects"
               checked={hidden}
               onChange={(checked) => actions.display_hidden_projects(checked)}
-              checkedChildren={intl.formatMessage({
-                id: "projects.table-controls.hidden.label",
-                defaultMessage: "Hidden",
-              })}
-              unCheckedChildren={intl.formatMessage({
-                id: "projects.table-controls.hidden.label",
-                defaultMessage: "Hidden",
-              })}
+              checkedChildren={intl.formatMessage(messages.hidden)}
+              unCheckedChildren={intl.formatMessage(messages.hidden)}
             />
             <Switch
-              aria-label="Show deleted projects"
               checked={deleted}
               onChange={(checked) => actions.display_deleted_projects(checked)}
-              checkedChildren={intl.formatMessage({
-                id: "projects.table-controls.deleted.label",
-                defaultMessage: "Deleted",
-              })}
-              unCheckedChildren={intl.formatMessage({
-                id: "projects.table-controls.deleted.label",
-                defaultMessage: "Deleted",
-              })}
+              checkedChildren={intl.formatMessage(messages.deleted)}
+              unCheckedChildren={intl.formatMessage(messages.deleted)}
             />
           </Space>
         )}
@@ -181,7 +178,6 @@ export function ProjectsTableControls({
           <Button
             ref={createNewRef}
             type="primary"
-            aria-label="Create a new project"
             onClick={onCreateProject}
             icon={<Icon name="plus-circle" />}
           >
diff --git a/src/packages/static/src/meta.tsx b/src/packages/static/src/meta.tsx
@@ -8,10 +8,7 @@ export default function Meta() {
       <meta name="apple-mobile-web-app-status-bar-style" content="black" />
       <meta name="apple-mobile-web-app-title" content="CoCalc" />
       <meta name="theme-color" content="#fbb635" />
-      <meta
-        name="viewport"
-        content="width=device-width,initial-scale=1,user-scalable=no"
-      />
+      <meta name="viewport" content="width=device-width,initial-scale=1" />
       <meta name="google" content="notranslate" />
     </>
   );

Original file line number	Diff line number	Diff line change
`@@ -230,6 +230,7 @@ export const Page: React.FC = () => {`
`230`	`230`	`icon={"users"}`
`231`	`231`	`active_top_tab={active_top_tab}`
`232`	`232`	`hide_label={!show_label}`
	`233`	`+ aria-label="Admin"`
`233`	`234`	`/>`
`234`	`235`	`);`
`235`	`236`	`}`