Key Principles for Building Web Application UIs

Introduction

User experience is shaped by a series of small decisions. This document serves as an implementation memo for creating screens that are easy for anyone to understand and resistant to operational errors.
While there are few issues when professional designers collaborate on UI design for Web applications, there are times when Web engineers who are not necessarily professionals end up handling UI design as well.

Objectives:

• Present standards for UI implementation that allow even non-designers to ensure minimal operability, readability, and consistency.

Target Audience:

• Web engineers, UI implementers, and design/review staff.

Prerequisites:

• Implementation guidelines based on Fluent 2 Design System and WCAG 2.2. Focus is placed on understanding and operations that do not rely on visual information. References: https://fluent2.microsoft.design/ / https://www.w3.org/TR/WCAG22/

Overall Layout

Initial strategic decisions reduce later confusion. Choices regarding navigation, pane counts, and breakpoints directly impact information architecture and implementation costs.
First, consider the layout structure of the application. Is it a 2-pane or 3-pane configuration for desktop? Above all, are you prioritizing desktop, or considering mobile first?

Decisions to Make First:

• Target priority: Desktop-first or mobile-first (mobile-first is recommended).
• Pane configuration: Choose between 1/2/3 panes (define changes at breakpoints).
• Navigation: Key patterns such as side, top, tabs, or breadcrumbs.
• Responsive strategy: Major breakpoints, maximum width, and spacing scale.

Based on these decisions, align the division of responsibilities (frontend/backend) for information design and implementation.

Key Accessibility Considerations:

• Define landmarks: Use header / nav / main / aside / footer, and limit to one main per page.
• Assume keyboard-only navigation: All operations must be possible via keyboard, and the tab order must match the DOM order. Do not use tabindex > 0 as a rule.
• Visible focus: Always display a high-contrast focus ring using :focus-visible or similar.
• Skip links: Provide a "Skip to main content" link at the top of the page, visible upon focusing.
• Responsive: Maintain reading order in a mobile-first single-column layout; do not disrupt the DOM order even when changing visual order via CSS.
• Tap/click areas: Aim for interactive elements to be at least 44x44px.
• Heading structure: Use only one h1, and maintain a logical hierarchy for h2 and below without skipping levels.

Main Content

Wrap the main content in a layout container to manage margins, width, maximum width, and centering in one place.
The internal structure should be composed of grids and stacks to maintain readable reading order and repeatable spacing.

Key Accessibility Considerations:

• Matching DOM order and visual order: Even when swapping columns in the layout, prioritize DOM order so that screen reading and tab navigation remain natural.
• Grouping: Group related elements using appropriate semantics such as section, fieldset, or ul, and separate them with headings.
• Live updates: Notify dynamic updates using aria-live="polite". Avoid frequent announcements; keep them to the minimum necessary.
• Loading: Use role="progressbar" or similar for progress status, providing name, value, and range. Avoid using only a simple spinner.

Content Placement

Principles of placement:

• Arrange from left to right, and top to bottom following the reading order (align visual order with DOM order).
• Place related items close together; separate unrelated items with spacing.
• Avoid excessive use of dividing lines; use margins and heading structures to indicate sections.

Checklist:

• Use elements such as headings, lists, and tables according to their meaning; avoid excessive use of div for purely visual purposes.
• Provide alternative text such as aria-label for icon-only buttons.
• Communicate errors and states using text in addition to color (e.g., display error messages directly under the element).
• Ensure sufficient margins and size for clickable areas (to prevent accidental taps).
• Use readable intervals for line and paragraph spacing (e.g., line height 1.4–1.8, consistent margins before and after headings).

Color

Color is powerful, but its misuse is equally potent. Design to ensure states and meanings are communicated clearly without relying solely on color.

Semantic Colors

Purpose:

• Instantly convey states in line with real-world conventions (warnings, success, etc.).

Usage:

• Strengthen with text, icons, or shapes; do not rely on color alone.

Prohibited:

• Use for decorative purposes only.

Brand Colors

Usage:

• Select a base color representing the product and map it to role-based (foreground/background/border/state) tokens.
• Define shades/states according to the purpose and ensure compatibility with Light, Dark, and High Contrast modes.

Notes on Color

• Keep the colors used to a necessary minimum (limit to role-based color sets).
• Do not use color alone to present states or meanings (always communicate via multiple means).
• Designing with a minimum contrast ratio of 4.5:1 is verified at the design stage, assuming Dark Mode/High Contrast.

Contrast Standards

• Normal text must have a contrast ratio of at least 4.5:1; large text (18.66px/bold or larger, or 24px or larger) must have at least 3:1.
• UI components (button borders, icons, etc.) and important graphics must have at least 3:1.
• Focus indicators must have at least 3:1 against the background.

State Colors and Feedback

• Prepare states for Hover, Focus, Pressed, and Disabled, ensuring visible and contrast-compliant appearances even between states.
• Communicate semantics like errors, warnings, and success via multiple means, such as text, icons, or patterns, in addition to color.

Themes and Dark Mode

• Design using role-based color tokens (e.g., background/foreground/border/state) to apply Light, Dark, and High Contrast themes consistently.
• Respect prefers-color-scheme and OS high-contrast settings.

Verification

• Intentions in design can only be verified through operation. Quick self-checks minimize oversights.
• Measure major text, states, and focus using a contrast checker.
• Confirm readability and conveyance of meaning using Dark Mode or color blindness simulations.

Accordion

Guidelines:

• Use a button element for the heading, linked with aria-expanded and aria-controls, and ensure the panel side has an id.
• Keyboard: Tab to header, Enter/Space to open/close, arrow keys to move to adjacent headers, Home/End to go to first/last.
• Clearly define the initial state and collapse rules (single-only/multiple allowed), ensuring they are communicated to screen readers.
• Provide clear text labels rather than relying solely on visual triangular icons.

Usage:

• Use when you want to disclose secondary information or detailed descriptions in stages. Essential information for major tasks should be open by default.
• Name section headings with meaningful, concise phrases so the content can be anticipated.
• Do not use as a substitute for page navigation (consider a table of contents or side navigation instead).
• Avoid multi-level nesting; limit to one level. For large amounts of accordions, consider search or filtering.

Layout:

• Make the heading button the entire hit area, with consistent horizontal padding (e.g., 12–16px).
• Align expansion icons (e.g., chevrons) to the right edge with sufficient spacing from the text.
• Standardize spacing between sections to 8–16px. Avoid significant content jumps when opening/closing.
• Indent the content area one level relative to the heading; match list/paragraph margins to the global scale (8px increments).
• For long text, consider a separate page or detail panel instead of an accordion to minimize eye movement.

Color:

• Heading text must have equivalent contrast to the body text (at least 4.5:1).
• Hover/Pressed backgrounds must differ by at least 3:1 from the surroundings. The Focus ring must be visible with at least 3:1 contrast.
• Indicate expanded states using icon rotation or aria-expanded and wording, not just color.
• Dividers can have lower contrast, but rely on text or structure to convey information.

Prohibited:

• Hiding important, required information inside an accordion.
• Pseudo-implementing headings with div elements, lacking buttons, keyboard interaction, or aria attributes.
• Using only icons for headings (without text labels).
• Moving focus unnaturally during open/close, causing loss of reading position.

Dialog

Guidelines:

• Use the native <dialog> element if possible. If using div for compatibility, set role="dialog" and aria-modal="true".
• Assign an id to the heading and associate the title and description using aria-labelledby and aria-describedby.
• Move initial focus to an appropriate element when opening, and return focus to the trigger upon closing (focus trapping).
• Handle the Esc key to close, and be consistent with background clicking; provide confirmation if necessary to prevent accidental operations.
• Prevent background scrolling in the backdrop and ensure screen readers do not focus on background elements.

Usage:

• Use only when interrupting the flow to request a decision (confirmations, short form tasks, critical warnings).
• Do not use for minor explanations or information sufficient for a toast notification. Keep most forms within the page.
• Arrange actions with Primary/Neutral buttons in the bottom right consistently (e.g., Primary = Execute, Neutral = Cancel).
• Accompany destructive actions with clear wording (e.g., Delete), a confirmation request, and guidance on alternatives.

Layout:

• Display in the center of the screen; max-width should be approximately 480–640px depending on usage (forms can be slightly wider). Width should be responsive.
• Clearly separate header, body, and footer; unify inner padding to 16–24px. Increase margins on mobile.
• If the body is long, scroll only the body while fixing the header/footer. Indicate layers with shadows or borders.
• Align footer buttons to the right (LTR) with 8–12px spacing between them. Consider full-width vertical stacking for mobile.
• Fix background scrolling and prevent content misalignment behind the modal (handle scrollbar width).

Color:

• Surface background and body text must have at least 4.5:1 contrast. Higher contrast is recommended for headings.
• The backdrop should indicate a layer through contrast with the background, and clarify the distinction from the modal body (shadow/border + color).
• Use semantic colors for warnings/danger, but rely on icons and wording as well, not just color.
• Focus rings must have at least 3:1 contrast against the background. State colors for buttons (default/hover/pressed/disabled) must be consistent.

Prohibited:

• Multiple or nested modals.
• Inadequate focus trapping (focus returns to the background or does not return to the caller after closing).
• Closing operations available only via background click; keyboard/Esc does not work.
• Lack of title/description association (aria-labelledby/aria-describedby).

Button

Guidelines:

• Distinguish roles by using button for actions and a (links) for navigation.
• Keep labels concise as Verb + Object (e.g., Save, Submit). For icon-only buttons, provide an aria-label.
• During loading, update the label in addition to the spinner (e.g., Saving...). Maintain the same width to prevent layout shifts.
• For disabled states, provide the reason/alternative in text, not just disabled. Use aria-disabled as needed to align focusability with design intent.
• Ensure visual/auditory feedback for button presses so that keyboard/screen reader users can recognize the action.

Usage:

• Generally, place only one Primary button per screen. Use Neutral for other actions.
• For destructive actions, use Primary with the Danger (semantic) color, and ensure spacing and confirmation are provided to prevent accidental presses.
• On mobile, increase width and stack vertically to prioritize ease of interaction.
• Group multiple related actions into button groups or menus to organize visual priority.

Layout:

• In forms, place action groups at the end/bottom-right to follow the flow of the eye. Follow the order: "Primary → Neutral."
• Maintain 8–12px spacing between buttons. Avoid wrapping to multiple lines; if they overflow, store them in a menu.
• Ensure consistent spacing between icons and labels in buttons with icons; target a height of about 44px (touch target).
• In toolbars, align buttons using a button group and place related operations close together.

Color:

• Standardize on two types: Primary and Neutral. Maintain a contrast ratio of at least 4.5:1 with the body text.
• Provide consistent colors for background/border/icons for each state (Hover/Pressed/Focus/Disabled). UI elements must maintain at least 3:1 contrast.
• Use a red variant of the Primary semantic color for Danger (destructive) actions and clearly state the danger in the text.
• Text-only neutral buttons must show at least a 3:1 contrast difference against the background during Hover to indicate pressability.

Prohibited:

• Implementing buttons with div or span and missing the role, button behavior, or keyboard events.
• Using button for navigation (use a elements for links).
• Placing multiple Primary buttons on a page, creating ambiguity in priority.
• Icons only with no labels (and no aria-label).

Select Box

Guidelines:

• Use native <select> whenever possible and associate it with a label using label for.
• For many options, consider grouping (<optgroup>) or introducing search/filtering.
• Keyboard: Follow platform expectations, such as Alt+↓ to expand, ↑↓ to select, and Enter/Esc to confirm/close.
• For errors, display an explanation directly below the field and correctly set aria-invalid and aria-describedby.

Usage:

• Ideal when choosing from a fixed set of options is sufficient. Suitable when freedom of input is not required and the number of options is small to moderate.
• If a default value is not mandatory, provide a dummy first item like "Please select" and set it to disabled so it cannot be selected.
• Maintain a consistent sort order (alphabetical, kana, category) and consider placing frequent items at the top.
• If there are a vast number of options, consider using a combobox or search.

Layout:

• Align field width with other inputs in the form and ensure a minimum width (e.g., 200px). Label placement above is standard.
• Dropdown width should match the trigger or expand to fit content, folding inward if near screen edges.
• Set a maximum height for the list (e.g., 320px) and display a scrollbar. Target a row height of 40–48px.
• Place error messages/helper text directly below with 4–8px spacing.

Color:

• Provide consistent colors for field borders/backgrounds across Default/Hover/Focus/Disabled/Error states.
• Ensure placeholder text also has a readable contrast (at least 4.5:1) and do not use it as a substitute for a label.
• Indicate the selected row with a background/check icon; reinforce with bold text or check symbols, not just color. Maintain at least a 3:1 contrast difference for the row background.
• Use red tones for error states consistently across borders, icons, and description text; ensure explanation text has at least 4.5:1 contrast.

Prohibited:

• Implementing a custom select using div elements, which loses native accessibility/mobile picker capabilities.
• Using placeholder as a label substitute, or indicating mandatory fields/errors only via color.
• Displaying hundreds of options as-is (without search/categorization).

Combobox

Guidelines:

• Follow the WAI-ARIA Combobox pattern and set aria-autocomplete (list/both) on the input field.
• The candidate list should have role="listbox", each item should have role="option", and the selection should be indicated with aria-selected.
• Associate the active item with aria-activedescendant and enable navigation using arrow keys.
• Briefly notify the user of the number of candidates or selection results using aria-live="polite", avoiding excessive announcements.

Usage:

• Use for searching/narrowing down choices when there are many options, or in cases where new values are permitted.
• For asynchronous fetching, implement a delay (debounce) for input and briefly guide the user on the number of results.
• For auto-completion, avoid forcing a selection of a candidate, as this hinders the user's free input. Provide a clear button.
• On mobile, ensure sufficient candidate height/tap areas, and consider transitioning to a dedicated screen if the candidate list occupies a large portion of the screen.

Layout:

• Align the input field width with the form, and keep consistent inner spacing for prefix/suffix icons.
• Base the dropdown width on the input width, adjusting inward if near screen edges. Ensure positioning stays within the viewport.
• Set a maximum height for the candidate list (e.g., 320–480px), and consider virtual scrolling for a large number of items.
• Provide rows for empty states/loading/errors, and keep row heights stable even when content changes.

Color:

• Input text must have contrast equivalent to the body text (at least 4.5:1). For match highlighting, combine color with emphasis (bold/underline).
• Ensure the background for Hover/Selected candidates has at least a 3:1 contrast difference from the surroundings. Reinforce selection with a checkmark/icon.
• Ensure clear/expand icons have at least a 3:1 contrast difference from the background. Keep them subtle when disabled while maintaining label readability.
• Indicate loading/error rows using color + icons + text, avoiding dependency on color alone.

Prohibited:

• Over-engineering by using a combobox for a small number of candidates.
• Pseudo-implementations lacking proper ARIA roles/attributes (combobox, listbox, option, activedescendant, etc.).
• Taking control away from the user with excessive live region notifications or forced selections for every input.
• Excessively hijacking key events, which interferes with standard text editing operations.

Difference Between Select Box and Combobox

Definitions:

• Select Box: Uses native <select> to choose from pre-defined options. Free input is not allowed. Single selection is standard (multiple selection is possible with the multiple attribute).
• Combobox: A composite control of an input field and a candidate list. Allows searching/filtering or free input. Implemented using the WAI-ARIA Combobox pattern.

Selection Criteria:

• Few options (roughly 10–20) and fixed, no free input required → Select Box.
• Many options (over 20) that require searching/filtering, or allowing new input → Combobox.

Accessibility Perspective:

• Select Box: Native browser/OS-provided reading and keyboard operation are the most robust. Prioritize whenever possible.
• Combobox: Difficult to use unless role="combobox", aria-expanded, aria-controls, aria-autocomplete, listbox/option, and aria-activedescendant are correctly implemented.

Keyboard Operation (Overview):

• Select Box: Tab to focus, Alt+↓ to expand, ↑↓ to move, Enter/Esc to confirm/close, type-ahead to jump to items.
• Combobox: Tab to input, type to filter, ↓ to expand candidates, ↑↓ to move, Enter to confirm, Esc to close/clear input, Home/End to go to start/end.

Screen Reader Expectations:

• Select Box: The label and current value are read aloud, conforming to platform defaults (may be referred to as "combobox" depending on the environment).
• Combobox: Briefly announce the role=combobox, number of candidates, selection status, and expansion/collapse state. Avoid excessive aria-live.

Mobile Characteristics:

• Select Box: Can use OS-provided picker UI, making operation easy.
• Combobox: Requires ensuring candidate height, scrolling, and tap areas (approx. 44px) because screens are narrower.

Performance/Implementation Cost:

• Select Box: Easy to implement and robust, but with constraints on visual customization.
• Combobox: Flexible, but high implementation/maintenance cost. Virtualization and ARIA consistency during asynchronous fetching are critical.

Anti-patterns:

• Using a combobox when there are few options.
• Re-implementing a select box using div elements, losing native accessibility.
• Indicating selection status using only color or icons (must also use text/attributes to indicate state).

Minimum Requirements:

• Select Box: Associate with label/for, and use aria-invalid and description (aria-describedby) for errors.
• Combobox: Clear labels, appropriate roles/ARIA attributes, focus management, consistency in confirmation/cancellation, and complete keyboard operation.

Radio Button

Guidelines:

• Use input type="radio" for mutually exclusive selections, and use fieldset + legend to provide grouping and headings.
• Select one by default (if no selection is a valid requirement, clearly state the reason and the default behavior).
• Keyboard: Tab to the group, use arrow keys to move the selection.

Usage:

• Suitable for 2–7 mutually exclusive options. Intended for settings where the result is applied upon submission.
• Use switches for immediate application of Yes/No, and radio buttons for settings confirmed upon submission.
• Ensure each option is mutually exclusive and uses non-overlapping text. Provide a "None" option if necessary.

Layout:

• Use horizontal alignment for short labels/few items, and vertical alignment for long text/many items. Aim for 2–3 items per row.
• Set item spacing to 8–16px, and outer group spacing to 16–24px. Place the legend at the top as the group heading.
• Align radio dots with the baseline of the first line of the label, and arrange them so they remain legible even if wrapped across multiple lines.

Color:

• The selected dot and border must have at least 3:1 contrast against the background. Labels should follow the body text standard (at least 4.5:1).
• Use consistent colors for Hover/Focus/Disabled states. Focus rings must be at least 3:1.
• In case of errors, unify the group heading/helper text in a red hue, and communicate issues through text as well as color.

Prohibited:

• Using radio buttons for scenarios requiring multiple selections.
• Omitting fieldset/legend grouping, causing a loss of context.
• Making a selection mandatory without providing an error message if left unselected.

Checkbox and Switch

Guidelines:

• Checkbox: For independent true/false or multiple selection. Switch: For on/off settings that apply immediately.
• Labels should always be visible, and the state should be indicated in text (e.g., Notification: On).
• Use fieldset + legend for groups, and associate related descriptions with aria-describedby.

Usage:

• Checkbox: For consent, selecting multiple conditions, or batch selection in lists (including indeterminate states).
• Switch: For toggling settings that reflect immediately on the screen. For processes with delays, use a spinner or toast to inform of the result.
• Do not use switches for destructive or irreversible actions.

Layout:

• Checkboxes are generally stacked vertically with 8–12px spacing between items. Place the label to the right and make the entire row the hit area.
• For batch selection, place the parent checkbox in the header or at the start of the list, ensuring sufficient distance from child items.
• Switches are easiest to understand when placed at the end of the row; keep a consistent distance from the label. Aim for a row height of approximately 44px.
• Place supplementary text in a smaller font on the next line, aligning it with the label.

Color:

• The check (✔) or indeterminate (—) indicator must have at least 3:1 contrast against the background. Labels must be at least 4.5:1.
• The switch track and thumb should have a color scheme that makes the state distinguishable; do not rely on color alone (use text or state indicators as well).
• Use a subtle color scheme for Disabled states while maintaining label readability.
• Focus rings must be at least 3:1. Use red hues for errors and accompany them with helper text.

Prohibited:

• Applying destructive operations or long-running processes immediately via a switch.
• Using three states (indeterminate) without explanation, making the meaning ambiguous.
• Hiding checkbox labels and relying solely on icons or color to convey meaning.

Text Box

Guidelines:

• Associate label and input using for/id attributes; do not use placeholder as a replacement for a label.
• Indicate mandatory fields with text like "Required," not just color. Place error messages directly below the field and configure aria-invalid and aria-describedby.
• Input assistance: Use appropriate type (e.g., email, url, number), autocomplete attributes, and provide examples in helper text.
• Use real-time validation sparingly; provide clear messages upon focus-out or submission.

Usage:

• Use single-line inputs for short entries, and multiple lines (textarea) for longer text such as descriptions or comments.
• Display guidance beforehand if there are character count or format restrictions, and associate the remaining character count using aria-describedby.
• For masks (phone numbers, credit cards), prioritize readability during input and provide a toggle to show/hide (e.g., for passwords).
• Avoid conflicts between IME input and validation; suppress error displays while composing.

Layout:

• Labels are generally placed above. Align widths across the form, making inputs full-width whenever possible.
• Place helper text or error messages directly below, ensuring 4–8px of vertical margin. The order for multiple elements should be "Label → Input → Helper → Error".
• For multi-column forms, collapse to a single column at smaller breakpoints to maintain reading order.
• Ensure consistent inner padding for prefixes/suffixes (icons/units) and maintain clickable areas.

Color:

• Provide consistent colors for borders/backgrounds across Default, Hover, Focus, Disabled, Error, and Success states. Focus indicators must have at least 3:1 contrast.
• Ensure all placeholder, helper text, and error text have at least 4.5:1 contrast.
• Required asterisks may be highlighted with color, but must always be accompanied by "Required" text (color alone is prohibited).
• Keep disabled states at a lower contrast, but maintain enough visibility to read the input content.

Prohibited:

• Using placeholder as a replacement for a label.
• Reading out warnings continuously with every keystroke (overuse of live regions).
• Disabling autocomplete without intent, depriving users of assistance.
• Removing focus rings via CSS.

Data Grid

Guidelines:

• Use table for simple tables, adding scope (col/row) to th. Provide an overall description using caption.
• For sortable columns, use aria-sort and allow toggling via keyboard interaction (Enter/Space).
• For interactive grids (e.g., row selection), consider role="grid" and provide focus movement between cells/rows (arrow keys).
• In horizontal/vertical scrolling, ensure focus does not escape the visible area and maintain context by fixing headers.
• Provide pagination and count adjustments via form controls, and concisely notify update results using aria-live.

Usage:

• Use for displaying/comparing/manipulating multi-column, multi-row data. For simple lists, lists or cards are often more appropriate.
• Consolidate basic operations (sort/filter/pagination/column display toggle) in consistent locations and clearly show the current applied state.
• Provide clear paths for save/cancel for inline editing; consider separate screens or dialogs for bulk editing.
• Combine virtualization/lazy loading for large datasets, ensuring focus movement and screen reader accessibility are maintained.

Layout:

• Fix (sticky) headers to maintain column meaning during vertical scrolling. Standardize row height around 40–48px.
• Set min/max widths for columns, prioritizing key columns. For narrower screens, consider hiding, collapsing, or using card views.
• Group operational columns (actions) on the right with consistent spacing; place selection checkboxes on the left.
• Group pagination/count toggle/total count at the bottom-right (LTR) with a consistent order.

Color:

• Maintain readability while keeping background differences between headers and body rows subtle. Text must have at least 4.5:1 contrast.
• Indicate Hover/Selected rows/Focused cells with background/border differences of at least 3:1 contrast against surroundings. Reinforce selection with checkboxes or icons.
• Indicate sorted columns with icons/text; do not rely on color alone.
• Unify link/error/success state colors semantically and use them alongside descriptive text.

Prohibited:

• Implementing tables using layouts without table/grid semantics.
• Omitting header th or scope attributes, leaving column meaning ambiguous.
• Using infinite scrolling in a way that causes users to lose their place or focus (lack of pagination).
• Expressing sorting/filtering through icons or color alone, without corresponding text and attributes.

---

Test and Verification

Quick self-check:

• Key flows can be completed using keyboard only (Tab/Shift+Tab/Enter/Space/Arrow Keys/Esc).
• Focus is always visible. Tab order follows the logical order.
• Contrast meets standards (4.5:1 for body text, 3:1 for large text, 3:1 for UI).
• Information is not lost at 200%/400% zoom, and horizontal scrolling is minimized.
• Motion is suppressed via prefers-reduced-motion without hindering content understanding.
• Labels, roles, states, and values are announced correctly by major screen readers (NVDA/Windows Narrator, etc.).

Reference Links:

• Fluent 2 Design System: https://fluent2.microsoft.design/
• Microsoft Inclusive Design: https://inclusive.microsoft.design/
• WCAG 2.2: https://www.w3.org/TR/WCAG22/