GeoDaoyuGeoDaoyu/arcgis-maps-sdk-js-ai-context/skills/arcgis-widgets-ui/AGENTS.md

arcgis-maps-sdk-js-ai-context / arcgis-widgets-ui

AGENTS.md0 starsChanged 7 months agoMITView on GitHub

Quick-reference decisions, checklists, and tables for widgets and UI layout. Default: Always prefer Map Components. Esri has transitioned to web components as the primary approach. Slots available on <arcgis-map>, <arcgis-scene>, and <arcgis-video>: Ordering: Widgets in the same slot stack vertically in DOM order. Wrap any component in <arcgis-expand> for collapsible behavior: Use expanded attribute to start open. Use mode="floating" for floating panel style.

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,542 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository47 other files it gives its agents.
- AGENTS.mdAGENTS.md
- skills/arcgis-ai-components/AGENTS.mdAGENTS.md
- skills/arcgis-authentication/AGENTS.mdAGENTS.md
- skills/arcgis-charts/AGENTS.mdAGENTS.md
- skills/arcgis-coding-components/AGENTS.mdAGENTS.md
- skills/arcgis-core-maps/AGENTS.mdAGENTS.md
- skills/arcgis-editing/AGENTS.mdAGENTS.md
- skills/arcgis-embeddable-maps/AGENTS.mdAGENTS.md
- skills/arcgis-interaction/AGENTS.mdAGENTS.md
- skills/arcgis-layers/AGENTS.mdAGENTS.md
- skills/arcgis-starter-app/AGENTS.mdAGENTS.md
- skills/arcgis-visualization/AGENTS.mdAGENTS.md
- arcgis-3d-layersSkill
- arcgis-advanced-layersSkill
- arcgis-ai-componentsSkill
- arcgis-arcadeSkill
- arcgis-authenticationSkill
- arcgis-chartsSkill
- arcgis-cim-symbolsSkill
- arcgis-coding-componentsSkill
- arcgis-coordinates-projectionSkill
- arcgis-core-mapsSkill
- arcgis-core-utilitiesSkill
- arcgis-custom-renderingSkill
- arcgis-editingSkill
- arcgis-embeddable-mapsSkill
- arcgis-feature-effectsSkill
- arcgis-geometry-operationsSkill
- arcgis-imagerySkill
- arcgis-interactionSkill
- arcgis-knowledge-graphsSkill
- arcgis-layersSkill
- arcgis-map-toolsSkill
- arcgis-performanceSkill
- arcgis-popup-templatesSkill
- arcgis-portal-contentSkill
- arcgis-rest-servicesSkill
- arcgis-scene-environmentSkill
- arcgis-smart-mappingSkill
- arcgis-spatial-analysisSkill
- arcgis-starter-appSkill
- arcgis-tables-formsSkill
- arcgis-time-animationSkill
- arcgis-utility-networksSkill
- arcgis-visualizationSkill
- arcgis-widgets-advancedSkill
- arcgis-widgets-uiSkill

The file

We split this AGENTS.md into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
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:
Default: Always prefer Map Components.
line 19
Very specific:
Use expanded attribute to start open.
line 49

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md 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.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

Agent Guide: arcgis-widgets-ui

Quick-reference decisions, checklists, and tables for widgets and UI layout.

Component vs Widget Decision

Does a Map Component exist for this widget?
- Yes --> Use the component (e.g., <arcgis-legend> instead of new Legend())
- No (e.g., Histogram) --> Use the Core API widget
Is the widget placed inside the map view?
- Yes --> Use slot-based positioning: <arcgis-legend slot="bottom-left">
- No, in a side panel --> Use reference-element attribute on the component
Do you need to customize widget behavior with callbacks?
- Yes --> Core API widget gives more control
- No --> Component is simpler

Default: Always prefer Map Components. Esri has transitioned to web components as the primary approach.

Slot Reference Table

Slots available on <arcgis-map>, <arcgis-scene>, and <arcgis-video>:

Slot	Position	Typical widgets
`top-left`	Upper left corner	Zoom, Home, Compass, Locate
`top-right`	Upper right corner	Search, LayerList, BasemapGallery, Editor
`bottom-left`	Lower left corner	Legend, Attribution
`bottom-right`	Lower right corner	ScaleBar, TimeSlider
`top-start`	Upper left (LTR) / upper right (RTL)	Directional-aware placement
`top-end`	Upper right (LTR) / upper left (RTL)	Directional-aware placement
`bottom-start`	Lower left (LTR) / lower right (RTL)	Directional-aware placement
`bottom-end`	Lower right (LTR) / lower left (RTL)	Directional-aware placement
`popup`	Popup container	`<arcgis-popup>` only

Ordering: Widgets in the same slot stack vertically in DOM order.

Expand Pattern

Wrap any component in <arcgis-expand> for collapsible behavior:

<arcgis-expand slot="top-right" expand-tooltip="Legend">
  <arcgis-legend></arcgis-legend>
</arcgis-expand>

Use expanded attribute to start open. Use mode="floating" for floating panel style.

Calcite Integration Checklist

Add theme class to <body>: calcite-mode-light or calcite-mode-dark
Use <calcite-shell> as root layout container
Use <calcite-shell-panel slot="panel-start"> for left sidebar
Use <calcite-shell-panel slot="panel-end"> for right sidebar
Use <calcite-navigation slot="header"> for app header
Place <arcgis-map> directly inside <calcite-shell> (main content area)
For widgets in panels, add reference-element="mapId" to link to the map
Custom theme: override --calcite-color-brand CSS variable on :root

Common Layout: Shell + Action Bar + Panels

calcite-shell
  +-- calcite-navigation [slot="header"]
  +-- calcite-shell-panel [slot="panel-start"]
  |     +-- calcite-action-bar [slot="action-bar"]
  |     +-- calcite-panel (one per action)
  +-- arcgis-map
  |     +-- arcgis-zoom [slot="top-left"]
  +-- calcite-shell-panel [slot="panel-end"]
        +-- calcite-panel

Widget Placement Quick Reference

Approach	When to use
Slot on `<arcgis-map>`	Widget is part of the map UI (most common)
`reference-element` attribute	Widget is in a Calcite panel outside the map
`view.ui.add(widget, position)`	Core API widgets added programmatically
`container` property on widget	Core API widget rendered in a specific DOM element
CSS absolute positioning	Fully custom positioning outside the ArcGIS UI system

Download now (ZIP)

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

What did you use it for? e.g. Reviewing pull requests in a Rails app

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.

Check your setup, free