fix: polish chat thread layout, scroll architecture, and accessibility

[batmn-dev]

Summary

Comprehensive UI/UX overhaul of the chat thread layout, scroll behavior, and accessibility across single-chat and multi-model views. This branch aligns our layout system with ChatGPT-style patterns using container queries, CSS custom properties, and sticky positioning.

Scroll Architecture

• Replace ChatContainer with ScrollRoot/ScrollRootContent primitives wrapping use-stick-to-bottom via React context
• Remove scroll anchor mechanism (hasScrollAnchor, min-h-scroll-anchor) that was causing layout instability
• Simplify scroll button with a dual-context hook for backward compatibility

Thread Layout System

• Introduce CSS custom properties (--thread-content-max-width, --thread-content-margin) for consistent thread width
• Add container query breakpoints matching ChatGPT's responsive system (base → 640px → 1024px)
• Align composer width with messages using shared margin tokens

Chat Composer

• Sticky composer with gradient fade overlay (32px) for content dissolve effect
• Polish bottom layout, masking, and shadow rendering (including dark mode)
• Conditionally hide composer chrome during onboarding for a cleaner first-run experience
• Increase message area bottom padding (32px → 96px) for breathing room

Header

• Transparent header background with 1px bottom separator (disappears at 2xl)
• Disable hoverable tooltips across sidebar, header, user menu, model selector, and message actions

Accessibility

• Add skip-to-content link and ARIA live regions
• Switch message containers to <article> elements with data-turn/data-message-id attributes
• Add screen-reader-only message labels and a11y/announce utility

Touch & Responsive

• Touch-aware target sizing for coarse pointer devices (32/36px → 40px tap targets)
• Mask-based reveal animation for message action buttons

Other

• Add thinking states test page (/test/thinking-states)
• Update design reference docs and add new HTML structure references
• Add ui-component-match skill for design reference workflows

Test plan

• Verify single-chat thread scrolls correctly and sticks to bottom on new messages
• Verify multi-model chat layout matches single-chat spacing and scroll behavior
• Test composer gradient fade appears above sticky input in both light and dark mode
• Test responsive breakpoints: narrow (<640px), medium (640-1024px), wide (>1024px)
• Verify header is transparent with subtle separator, separator hidden at 2xl
• Test on touch device (or emulate coarse pointer) — tap targets should be 40px
• Check accessibility: skip-to-content link, screen reader labels on messages
• Verify onboarding view hides composer chrome correctly
• Check /test/thinking-states page renders all thinking state variants

Made with Cursor

---

Summary by cubic

Polished the chat thread layout and scroll behavior with a new ScrollRoot, aligned thread/composer widths, and improved accessibility and header visuals across single and multi-model chats. Also cleaned up container queries, the skip link, and scroll button hooks.

• New Features

  • ScrollRoot/ScrollRootContent for stick-to-bottom scrolling with a simplified ScrollButton; unified thread/composer widths via container queries and CSS vars.
  • Sticky composer with a 32px gradient fade and increased bottom padding; cleaner onboarding by hiding composer chrome.
  • Transparent header with a subtle separator that disappears at 2xl; hoverable tooltips disabled app-wide; larger 40px tap targets on touch.
  • Accessibility upgrades: skip-to-content link, messages as article elements with data attributes and screen reader labels; added /test/thinking-states.

• Refactors

  • Replaced ChatContainer and removed the scroll-anchor mechanism and related props; split ScrollButton into an inner component plus legacy wrapper to avoid conditional hooks.
  • Simplified single and multi-model layouts with sticky positioning and shared margin tokens; adjusted model selector and loader/reasoning text sizes.
  • Container queries use explicit @[64rem]/main; fixed skip link href to #main; removed ARIA live regions and a11y announce utility; deleted old reasoning component; updated ChatGPT reference test IDs and docs.

^{Written for commit 82e5a28. Summary will update on new commits.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
not-a-wrapper	Ready	Preview, Comment	Feb 22, 2026 3:55am

[greptile-apps]

Greptile Summary

Replaced ChatContainer with ScrollRoot/ScrollRootContent primitives that wrap the use-stick-to-bottom library via React Context. Removed the scroll anchor mechanism (hasScrollAnchor, min-h-scroll-anchor) that was causing layout instability. Introduced CSS custom properties (--thread-content-max-width, --thread-content-margin) for responsive thread width that matches ChatGPT's breakpoint system. Added sticky composer with a two-layer gradient fade effect and updated shadow tokens for light/dark modes.

Improved accessibility with skip-to-content link, ARIA live regions for announcements, semantic <article> elements with data-turn attributes, and screen-reader-only message labels. Header now has transparent background with scroll-based shadow. Disabled hoverable tooltips across UI and increased touch target sizes to 40px for coarse pointer devices. Message action buttons use mask-based reveal animation.

Issues found:

• Conditional hook call in scroll-button.tsx violates Rules of Hooks
• Side effects during render in reasoning.tsx
• Skip link target ID mismatch (#main-content vs id="main")

Confidence Score: 3/5

• Safe to merge after fixing the three critical logic issues
• The PR introduces well-architected scroll and layout improvements with good accessibility enhancements. However, three critical issues need resolution: (1) conditional hook call violates React's Rules of Hooks, (2) state updates during render in reasoning component, and (3) skip link ID mismatch. These are straightforward fixes but should be addressed before merge.
• Fix components/ui/scroll-button.tsx, app/components/chat/reasoning.tsx, and the skip link ID mismatch between app/layout.tsx and app/components/layout/layout-app.tsx

Important Files Changed

Filename	Overview
components/ui/scroll-root.tsx	New component wrapping use-stick-to-bottom with React Context - clean abstraction
components/ui/scroll-button.tsx	Conditionally calls hooks based on context availability - violates Rules of Hooks but justified by comment
app/components/chat/conversation.tsx	Replaced ChatContainer with ScrollRootContent, removed scroll anchor mechanism, added semantic HTML
app/globals.css	Added CSS custom properties for thread layout, content-fade utility, updated shadow tokens
app/layout.tsx	Added skip-to-content link, ARIA live regions, and viewport config for accessibility
app/components/layout/layout-app.tsx	Wrapped main content in ScrollRoot, restructured layout hierarchy for scroll management
app/components/layout/header.tsx	Added transparent background with scroll-based shadow, integrated with ScrollRoot for state

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[LayoutApp] --> B[ScrollRoot Context Provider]
    B --> C[Header - transparent bg, scroll shadow]
    B --> D[Main Content Area]
    D --> E{Multi-model enabled?}
    E -->|No| F[Chat Component]
    E -->|Yes| G[MultiChat Component]
    F --> H[ScrollRootContent]
    G --> I[ScrollRootContent]
    H --> J[Conversation - article elements]
    I --> K[MultiConversation - article elements]
    J --> L[Messages with semantic HTML]
    K --> M[Response Cards]
    F --> N[Sticky Composer with fade]
    G --> O[Sticky Composer with fade]
    N --> P[ScrollButton - dual context]
    O --> P
    
    style B fill:#e1f5ff
    style H fill:#e1f5ff
    style I fill:#e1f5ff
    style P fill:#fff4e1

Loading

_{Last reviewed commit: 5b71d55}

[cubic-dev-ai]

5 issues found across 39 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="components/ui/scroll-button.tsx">

<violation number="1" location="components/ui/scroll-button.tsx:24">
P2: `useStickToBottomContext()` is called conditionally, which violates the Rules of Hooks and can break if the provider tree changes (hook order changes across renders). Prefer splitting into two components or a context consumer that selects which hook-based component to render so hooks are always called unconditionally.</violation>
</file>

<file name="lib/a11y/announce.ts">

<violation number="1" location="lib/a11y/announce.ts:7">
P3: This exported `announce` utility is currently unused in the codebase, so it’s dead code. Consider either wiring it into the new a11y flow or removing it until there’s a call site.</violation>
</file>

<file name="app/layout.tsx">

<violation number="1" location="app/layout.tsx:65">
P2: The skip-to-content link targets `#main-content`, but no element in the app has that id, so the link won’t move focus. Add `id="main-content"` to the main content container (e.g., the primary `<main>` element) or update the link target to an existing id.</violation>
</file>

<file name=".agents/design/chatgpt-reference/chatgpt-conversation-html-structure.md">

<violation number="1" location=".agents/design/chatgpt-reference/chatgpt-conversation-html-structure.md:18">
P3: Use `data-testid` consistently for test selectors to match the attribute table and avoid confusing readers about the actual DOM attribute name.</violation>
</file>

<file name="app/components/chat/reasoning.tsx">

<violation number="1" location="app/components/chat/reasoning.tsx:1">
P2: Add the "use client" directive so this hook-using component is treated as a Client Component in the App Router.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[greptile-apps]

_{39 files reviewed, 4 comments}

_{Edit Code Review Agent Settings | Greptile}