Skip to content

After applying reflow, the Docs page navigation overlaps the main navigation: A11y_TypeSpec_Reflow”. Drop trailing period. #10795

New issue
New issue
Closed
Closed
After applying reflow, the Docs page navigation overlaps the main navigation: A11y_TypeSpec_Reflow”. Drop trailing period.#10795
Assignees
markcowl
Labels
bugSomething isn't workingmeta:websiteTypeSpec.io updatestriaged:core
Milestone
[2026] August

Description

@kupatkar99
kupatkar99
opened on May 26, 2026

Please do not close this bug. This bug should only be closed by TCS, C+AI Accessibility tester after bug verification.
"Check out Accessibility Insights! - Identify accessibility bugs before check-in and make bug fixing faster and easier."

GitHub Tags:

#A11yTCS; A11yMAS; #A11ySev2; #DesktopWeb; #Win11; #Chrome; #E2E_TypeSpec_Web_May2026; #WCAG1.4.10; #TypeSpec; #Reflow; #A11yWCAG2.1;

Issue Subcategory:

Content hidden at narrow widths.

User Experience:

Critical content or functionality disappears when zoomed in, leaving users without needed information or controls. There is no fallback to access the hidden content.

Pre Requisites:

Open DevTools using Ctrl+Shift+I and set it to undocked window → Minimize DevTools → Apply reflow by either setting viewport to 320px width at 200% zoom OR set OS resolution to 1280×1024 with 100% scaling and zoom browser to 400% in full screen.

Repro Steps:

Launch url https://typespec.io/docs/>Get started.

Actual Result:

When reflow is applied (e.g., zoom or reduced viewport width), the Docs page navigation controls overlap the main navigation controls. This causes layout issues and prevents proper interaction with the main navigation.

Expected Result:

Navigation elements should reflow properly without overlapping, ensuring all controls remain visible and usable.

How to Fix:

Ensure all content reflows rather than hiding. Use a mobile-first design approach where content stacks vertically. If collapsing navigation, provide a hamburger menu or equivalent.

Environment details:

Application Name: TypeSpec
URL: typespec.io
Edition Windows 11 Enterprise
Version 25H2 OS build 26200.8390
Chrome Version 148.0.7778.168 (Official Build) (64-bit)

Attachment:

A11y_Typespec_Reflow.mp4

Activity

  1. microsoft-github-policy-service
    added
    needs-area
    on May 26, 2026
  2. github-actions
    added
    bugSomething isn't working
    meta:websiteTypeSpec.io updates
    on May 26, 2026

  3. github-actions commented on May 26, 2026

    @github-actions
    github-actionsBot
    on May 26, 2026 – with GitHub Actions
    Contributor

    🎯 Issue Triage

    A WCAG 1.4.10 (Reflow) accessibility bug on typespec.io/docs: when the viewport is narrowed to 320px (or the browser is zoomed to 400%), the sidebar/docs page navigation overlaps the main navigation bar, breaking layout and usability.

    Category: Bug

    Area: meta:website

    🔍 Analysis
    • WCAG criterion: 1.4.10 Reflow — content must be available without horizontal scrolling at 320px width.
    • Affected page: (typespec.io/redacted) started (docs section)
    • Root cause: The docs sidebar and main nav likely use fixed or absolute positioning without proper z-index/stacking context or lack a responsive breakpoint that hides/collapses one of the navs at narrow widths.
    • Severity: Accessibility Severity 2 (A11ySev2) per the reporter — blocks keyboard/screen reader navigation in reflow mode.
    • Fix direction: Ensure navigation components use mobile-first responsive CSS; add a hamburger/drawer pattern for the sidebar at narrow viewports; verify no overflow: hidden clips are hiding the conflict.
    📝 Suggested next steps
    • Reproduce locally by setting viewport to 320px in DevTools on /docs/
    • Audit the docs layout CSS for fixed-width or absolute positioning on the sidebar nav
    • Add a responsive breakpoint that collapses the sidebar into a drawer/hamburger at ≤320px
    • Verify fix with Accessibility Insights or browser DevTools reflow simulation

    Generated by Agentic Triage

  4. microsoft-github-policy-service
    removed
    needs-area
    on May 26, 2026
  5. Mark Cowlishaw (markcowl)
    self-assigned this
    on Jun 1, 2026
  6. kupatkar99
    changed the title [-]After applying the reflow, Docs page navigation controls overlap the main navigation controls: A11y_Typespec_Reflow.[/-] [+]After applying reflow, the Docs page navigation overlaps the main navigation: A11y_TypeSpec_Reflow”. Drop trailing period.[/+] on Jun 5, 2026
  7. Mark Cowlishaw (markcowl)
    added this to the [2026] July milestone on Jun 8, 2026
  8. Mark Cowlishaw (markcowl)
    added
    triaged:core
    on Jun 8, 2026
  9. Mark Cowlishaw (markcowl)
    modified the milestones: [2026] July, [2026] August on Jul 14, 2026
  10. Timothee Guerin (timotheeguerin)
    added a commit that references this issue on Jul 21, 2026

    fix(website): resolve typespec.io accessibility issues (#11292)

    ae2ef77

  11. kupatkar99 commented on Jul 27, 2026

    @kupatkar99
    kupatkar99
    on Jul 27, 2026
    Author

    #Closed; #A11yFixed;
    Verified the issue in below environment:
    https://typespec.io/
    Chrome: Version 150.0.7871.182 (Official Build) (64-bit)
    issue is fixed. hence closing the bug. Please find added attachment for reference.

    Recording.2026-07-27.171547.mp4
  12. kupatkar99
    closed this as completedon Jul 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingmeta:websiteTypeSpec.io updatestriaged:core

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions