♿️(frontend) improve BoxButton a11y and native button semantics

Add type="button", aria-disabled, and align refs with HTMLButtonElement.

CHANGELOG.md

@@ -13,6 +13,8 @@ and this project adheres to
 ### Changed
 
 - 💄(frontend) improve comments highlights #1961
+- ♿️(frontend) improve BoxButton a11y and native button semantics
+  #2103
 
 ## [v4.8.3] - 2026-03-23
 

src/frontend/apps/impress/src/components/BoxButton.tsx

@@ -1,17 +1,17 @@
-import { forwardRef } from 'react';
+import { Ref, forwardRef } from 'react';
 import { css } from 'styled-components';
 
 import { Box, BoxType } from './Box';
 
-export type BoxButtonType = BoxType & {
+export type BoxButtonType = Omit<BoxType, 'ref'> & {
   disabled?: boolean;
+  ref?: Ref<HTMLButtonElement>;
 };
 
-/**
-
 /**
  * Styleless button that extends the Box component.
  * Good to wrap around SVGs or other elements that need to be clickable.
+ * Uses aria-disabled instead of native disabled to preserve keyboard focusability.
  * @param props - @see BoxType props
  * @param ref
  * @see Box
@@ -22,8 +22,8 @@ export type BoxButtonType = BoxType & {
  *  </BoxButton>
  * ```
  */
-const BoxButton = forwardRef<HTMLDivElement, BoxButtonType>(
-  ({ $css, ...props }, ref) => {
+const BoxButton = forwardRef<HTMLButtonElement, BoxButtonType>(
+  ({ $css, disabled, ...props }, ref) => {
     const theme = props.$theme || 'gray';
     const variation = props.$variation || 'primary';
 
@@ -31,16 +31,18 @@ const BoxButton = forwardRef<HTMLDivElement, BoxButtonType>(
       <Box
         ref={ref}
         as="button"
+        type="button"
         $background="none"
         $margin="none"
         $padding="none"
         $hasTransition
+        aria-disabled={disabled || undefined}
         $css={css`
-          cursor: ${props.disabled ? 'not-allowed' : 'pointer'};
+          cursor: ${disabled ? 'not-allowed' : 'pointer'};
           border: none;
           outline: none;
           font-family: inherit;
-          color: ${props.disabled &&
+          color: ${disabled &&
           `var(--c--contextuals--content--semantic--disabled--primary)`};
           &:focus-visible {
             transition: none;
@@ -53,11 +55,11 @@ const BoxButton = forwardRef<HTMLDivElement, BoxButtonType>(
         `}
         {...props}
         className={`--docs--box-button ${props.className || ''}`}
-        onClick={(event: React.MouseEvent<HTMLDivElement>) => {
-          if (props.disabled) {
+        onClick={(event: React.MouseEvent<HTMLButtonElement>) => {
+          if (disabled) {
             return;
           }
-          props.onClick?.(event);
+          props.onClick?.(event as unknown as React.MouseEvent<HTMLDivElement>);
         }}
       />
     );

src/frontend/apps/impress/src/components/dropdown-menu/DropdownMenu.tsx

@@ -69,7 +69,7 @@ export const DropdownMenu = ({
   const [isOpen, setIsOpen] = useState(opened ?? false);
   const [focusedIndex, setFocusedIndex] = useState(-1);
   const blockButtonRef = useRef<HTMLDivElement>(null);
-  const menuItemRefs = useRef<(HTMLDivElement | null)[]>([]);
+  const menuItemRefs = useRef<(HTMLButtonElement | null)[]>([]);
 
   const onOpenChange = useCallback(
     (isOpen: boolean) => {

src/frontend/apps/impress/src/components/dropdown-menu/hook/useDropdownKeyboardNav.ts

@@ -6,7 +6,7 @@ type UseDropdownKeyboardNavProps = {
   isOpen: boolean;
   focusedIndex: number;
   options: DropdownMenuOption[];
-  menuItemRefs: RefObject<(HTMLDivElement | null)[]>;
+  menuItemRefs: RefObject<(HTMLButtonElement | null)[]>;
   setFocusedIndex: (index: number) => void;
   onOpenChange: (isOpen: boolean) => void;
 };

src/frontend/apps/impress/src/features/docs/doc-management/components/DocIcon.tsx

@@ -44,7 +44,7 @@ export const DocIcon = ({
   const { t } = useTranslation();
   const { addLastFocus, restoreFocus } = useFocusStore();
 
-  const iconRef = useRef<HTMLDivElement>(null);
+  const iconRef = useRef<HTMLButtonElement>(null);
 
   const [openEmojiPicker, setOpenEmojiPicker] = useState<boolean>(false);
   const [pickerPosition, setPickerPosition] = useState<{

src/frontend/apps/impress/src/features/docs/doc-tree/components/DocSubPageItem.tsx

@@ -96,7 +96,7 @@ export const DocSubPageItem = (props: TreeViewNodeProps<Doc>) => {
   const ariaLabel = docTitle;
   const isDisabled = !!doc.deleted_at;
   const actionsRef = useRef<HTMLDivElement>(null);
-  const buttonOptionRef = useRef<HTMLDivElement | null>(null);
+  const buttonOptionRef = useRef<HTMLButtonElement | null>(null);
 
   const handleKeyDown = (e: React.KeyboardEvent) => {
     const target = e.target as HTMLElement | null;

src/frontend/apps/impress/src/features/docs/doc-tree/components/DocTree.tsx

@@ -44,7 +44,7 @@ export const DocTree = ({ currentDoc }: DocTreeProps) => {
     treeContext?.treeData.selectedNode?.id === treeContext.root.id;
   const rootItemRef = useRef<HTMLDivElement>(null);
   const rootActionsRef = useRef<HTMLDivElement>(null);
-  const rootButtonOptionRef = useRef<HTMLDivElement | null>(null);
+  const rootButtonOptionRef = useRef<HTMLButtonElement | null>(null);
 
   const { t } = useTranslation();
 

src/frontend/apps/impress/src/features/docs/doc-tree/components/DocTreeItemActions.tsx

@@ -33,7 +33,7 @@ type DocTreeItemActionsProps = {
   onOpenChange?: (isOpen: boolean) => void;
   parentId?: string | null;
   actionsRef?: React.RefObject<HTMLDivElement | null>;
-  buttonOptionRef?: React.RefObject<HTMLDivElement | null>;
+  buttonOptionRef?: React.RefObject<HTMLButtonElement | null>;
 };
 
 export const DocTreeItemActions = ({
@@ -48,7 +48,7 @@ export const DocTreeItemActions = ({
 }: DocTreeItemActionsProps) => {
   const internalActionsRef = useRef<HTMLDivElement | null>(null);
   const targetActionsRef = actionsRef ?? internalActionsRef;
-  const internalButtonRef = useRef<HTMLDivElement | null>(null);
+  const internalButtonRef = useRef<HTMLButtonElement | null>(null);
   const targetButtonRef = buttonOptionRef ?? internalButtonRef;
   const router = useRouter();
   const { t } = useTranslation();