scroll-areas
Skill194 starsChanged 4 months agoMITView on GitHub
Avoid inner scroll containers; when unavoidable, one axis at a time. Use when a layout, table or panel might scroll inside the page.
In this repository44 other files it gives its agents.
- algorithmic-color-paletteSkill
- app-shellSkill
- authentic-product-representationSkill
- brand-visual-languageSkill
- button-statesSkill
- clone-websiteSkill
- color-mode-and-themeSkill
- component-family-consistencySkill
- coordinated-data-viewsSkill
- data-display-and-selectionSkill
- dembrandtSkill
- domain-expert-configurationSkill
- elevation-and-depthSkill
- extract-designSkill
- form-designSkill
- generate-ui-from-brandSkill
- gestalt-ui-organisationSkill
- global-toolbar-controlsSkill
- information-architectureSkill
- layout-paradigms-and-consistencySkill
- loading-states-and-perceived-performanceSkill
- marketing-vs-product-systemSkill
- micro-interactionsSkill
- modal-and-overlay-patternsSkill
- modular-scale-typographySkill
- motion-and-storytellingSkill
- nielsen-usability-heuristicsSkill
- notifications-and-recoverySkill
- operational-expert-tool-uiSkill
- performance-and-web-vitalsSkill
- real-world-metaphorsSkill
- repeated-component-alignmentSkill
- responsive-paradigmsSkill
- semantic-html-and-seoSkill
- sizing-unitsSkill
- status-colors-and-errorsSkill
- sticky-and-fixed-elementsSkill
- surface-separationSkill
- tab-navigationSkill
- ui-context-and-scopeSkill
- ui-densitySkill
- user-flows-and-guided-pathsSkill
- visual-emphasis-and-hierarchySkill
- wcag-accessibilitySkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 68
Never create a scroll container that scrolls on both axes simultaneously.
- Distinctive: line 83
If content requires both axes — e.g.
- Very specific: line 101
Use a subtle scrollbar (not scrollbar-width: none) so the track is visible
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Scroll Areas
Avoid Scroll Areas by Default
Scroll containers inside a layout — panels, drawers, tables, modals with inner overflow — create friction. Users must discover that a region scrolls, manage multiple independent scroll positions simultaneously, and context-switch between scroll areas on the same screen.
Default: let the page scroll. A single page-level scroll is universally understood and requires no discovery. Before introducing an inner scroll area, ask whether the layout can be restructured so the page itself handles the overflow.
Alternatives to inner scroll:
- Pagination or load-more for long lists
- Collapsible sections (accordion) for long detail panels
- A separate page or route for content that would otherwise fill a scroll area
- Progressive disclosure — show less by default, expand on demand
When a Scroll Area Is Justified
Some layouts genuinely require inner scroll:
- Fixed-height sidebars with navigation trees longer than the viewport
- Data tables where the header must remain visible while rows scroll
- Chat or log panels where the stream is continuous and the surrounding layout is fixed
- Code editors or terminal panes embedded in a larger application shell
In these cases, proceed — but apply the constraints below.
One Axis Only
Never create a scroll container that scrolls on both axes simultaneously. Two-axis scroll is disorienting, hard to control precisely, and nearly unusable on touch devices.
/* One axis: vertical */
overflow-y: auto;
overflow-x: hidden;
/* One axis: horizontal (e.g. wide table) */
overflow-x: auto;
overflow-y: hidden;
/* Never */
overflow: auto; /* allows both axes */If content requires both axes — e.g. a wide table inside a constrained panel — restructure the layout so the table's horizontal scroll is the only scroll in the view, with the page itself not scrolling at that point.
Always User-Controlled
Scroll must never happen automatically without user intent. Specifically:
- No auto-scrolling that moves the viewport without the user initiating it
- No scroll hijacking — do not intercept the native scroll event to animate or pace it artificially
- Scroll-to on load is acceptable only when restoring a previous scroll position (e.g. returning to a list after navigating away)
- Scroll-to for errors or anchors is acceptable as a response to a user action (submitting a form with errors, clicking a table-of-contents link)
Exception: chat and log panels may auto-scroll to the bottom on new content, but only if the user is already at the bottom. If the user has scrolled up to read, do not force them back down — show a "new messages" indicator instead.
Scroll Affordance
Users must be able to tell a region is scrollable before they attempt to scroll it.
- Clip content visually at the edge — a partially visible item signals "there is more"
- Use a subtle scrollbar (not
scrollbar-width: none) so the track is visible - On touch, a partial item at the edge is the primary affordance — ensure the container does not have
overflow: hiddenon the trailing edge
Neither cue is reliable: overlay scrollbars (macOS, touch) appear only while scrolling, and a clipped item signals more only when the cut lands mid-item. Give every nested scroll region an edge cue: a shadow or fade shown only at an edge with hidden content. Gradients with background-attachment: local over shadows with scroll do this in pure CSS, but opaque row backgrounds cover them; there, fade the content with mask-image.
Review Checklist
- Is every inner scroll area genuinely necessary, or can the layout be restructured to use page scroll?
- Does every scroll container scroll on one axis only?
- Is
overflow: auto(two-axis) avoided on all scroll containers? - Is scroll always user-initiated — no hijacking, no forced auto-scroll?
- Is the scrollable region visually apparent (partial content, visible scrollbar)?
- Does each nested scroll region show a shadow or fade at an edge only while content is hidden behind it?
- On touch devices, does scroll use native momentum, with no JS scroll emulation?
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

