101.4K+Download
Geospatial Tools · New Resource

Esri Calcite Design System.

A practical Calcite reference for focused spatial tools: semantic surfaces and blue actions, compact inspection panels, real input APIs, and a complete local site-review specimen.

Download OpenDesign Download DESIGN.md
OpenDesign Guide8 Chapters48 Reference EntriesOriginal Application Guide
01

Esri Calcite Design System Interface Preview

Select a site from the list or schematic, filter review states, and validate a note that persists per site until reload.

Inspect fictional sites and keep local notesOpen Full Example
Original HTML/CSS/JavaScript interpretation using documented visual references. The illustration is not an ArcGIS map; no Esri runtime or font is bundled. · Implementation reference
02

Esri Calcite Design System Design Reference

Calcite design tokens 4.1.0 and current component API, checked alongside Components 5.1.2. Token package and component package have separate version numbers. The embedded specimen is an original HTML/CSS interpretation; it does not redistribute the Calcite runtime or claim native behavior.

Light theme surfaces, text and interaction

Source
Name / RuleValue / ConfigurationUse
--calcite-color-surface-1#f7f7f7 Semantic reference for the role named by the token; selection and field borders need different contrast.
--calcite-color-surface-2#ffffff Semantic reference for the role named by the token; selection and field borders need different contrast.
--calcite-color-surface-3#f2f2f2 Semantic reference for the role named by the token; selection and field borders need different contrast.
--calcite-color-surface-4#ebebeb Semantic reference for the role named by the token; selection and field borders need different contrast.
--calcite-color-surface-highlight#d6efff Semantic reference for the role named by the token; selection and field borders need different contrast.
--calcite-color-text-1#141414 Semantic reference for the role named by the token; selection and field borders need different contrast.
--calcite-color-text-2#4a4a4a Semantic reference for the role named by the token; selection and field borders need different contrast.
--calcite-color-text-3#6b6b6b Semantic reference for the role named by the token; selection and field borders need different contrast.
--calcite-color-text-inverse#ffffff Semantic reference for the role named by the token; selection and field borders need different contrast.
--calcite-color-text-link#00619b Semantic reference for the role named by the token; selection and field borders need different contrast.
--calcite-color-border-1#d4d4d4 Semantic reference for the role named by the token; selection and field borders need different contrast.
--calcite-color-border-2#dedede Semantic reference for the role named by the token; selection and field borders need different contrast.
--calcite-color-border-3#ebebeb Semantic reference for the role named by the token; selection and field borders need different contrast.
--calcite-color-border-input#949494 Semantic reference for the role named by the token; selection and field borders need different contrast.
--calcite-color-brand#007ac2 Semantic reference for the role named by the token; selection and field borders need different contrast.
--calcite-color-brand-hover#00619b Semantic reference for the role named by the token; selection and field borders need different contrast.
--calcite-color-brand-press#004874 Semantic reference for the role named by the token; selection and field borders need different contrast.

Current spacing scale

Source
Name / RuleValue / ConfigurationUse
--calcite-space-none0Current space token family. Rem-based steps follow the root size; avoid mixing it with deprecated spacing aliases.
--calcite-space-px1pxCurrent space token family. Rem-based steps follow the root size; avoid mixing it with deprecated spacing aliases.
--calcite-space-base2pxCurrent space token family. Rem-based steps follow the root size; avoid mixing it with deprecated spacing aliases.
--calcite-space-2xs0.25remCurrent space token family. Rem-based steps follow the root size; avoid mixing it with deprecated spacing aliases.
--calcite-space-xs0.375remCurrent space token family. Rem-based steps follow the root size; avoid mixing it with deprecated spacing aliases.
--calcite-space-sm0.5remCurrent space token family. Rem-based steps follow the root size; avoid mixing it with deprecated spacing aliases.
--calcite-space-sm-plus0.625remCurrent space token family. Rem-based steps follow the root size; avoid mixing it with deprecated spacing aliases.
--calcite-space-md0.75remCurrent space token family. Rem-based steps follow the root size; avoid mixing it with deprecated spacing aliases.
--calcite-space-md-plus0.875remCurrent space token family. Rem-based steps follow the root size; avoid mixing it with deprecated spacing aliases.
--calcite-space-lg1remCurrent space token family. Rem-based steps follow the root size; avoid mixing it with deprecated spacing aliases.
--calcite-space-xl1.25remCurrent space token family. Rem-based steps follow the root size; avoid mixing it with deprecated spacing aliases.
--calcite-space-2xl1.5remCurrent space token family. Rem-based steps follow the root size; avoid mixing it with deprecated spacing aliases.
--calcite-space-3xl2remCurrent space token family. Rem-based steps follow the root size; avoid mixing it with deprecated spacing aliases.
--calcite-space-4xl2.75remCurrent space token family. Rem-based steps follow the root size; avoid mixing it with deprecated spacing aliases.

Type and corner scale

Source
Name / RuleValue / ConfigurationUse
--calcite-corner-radius-none0Published values, not measurements inferred from a screenshot.
--calcite-corner-radius-xs2pxPublished values, not measurements inferred from a screenshot.
--calcite-corner-radius-sm4pxPublished values, not measurements inferred from a screenshot.
--calcite-corner-radius-pill9999pxPublished values, not measurements inferred from a screenshot.
--calcite-font-size-xs10pxPublished values, not measurements inferred from a screenshot.
--calcite-font-size-sm12pxPublished values, not measurements inferred from a screenshot.
--calcite-font-size14pxPublished values, not measurements inferred from a screenshot.
--calcite-font-size-md16pxPublished values, not measurements inferred from a screenshot.
--calcite-font-size-lg18pxPublished values, not measurements inferred from a screenshot.
--calcite-font-size-xl20pxPublished values, not measurements inferred from a screenshot.
--calcite-font-size-2xl24pxPublished values, not measurements inferred from a screenshot.

Input component API

Source
Name / RuleValue / ConfigurationUse
scales / m / l; default mChange component scale deliberately; not the same as changing page zoom.
statusidle / valid / invalidCommunicate field validity with a message, not only color.
labelTextstringVisible label text on the current input API.
validationMessagestringExplain the invalid entry beside the control.
calciteInputInputeventRead event.target.value as the user types.
setFocus()Promise<void>Move focus into the native component after an application validation error.
03

Esri Calcite Design System Complete Guide

A practical guide to choosing, applying, and reviewing this system for a real interface.

DESIGN-esri-calcite.md

Complete guidance, an implementation starting point, and source links.

Download Guide

Esri Calcite Design System Workspace and Panel Architecture

Keep the object context visible

A spatial task usually has at least two contexts: the area being inspected and the selected object. The example keeps a small site list next to an original schematic and an inspector. Selecting a list row or a pin sets the same stable site ID, so the name, status and note cannot accidentally refer to different objects.

From this OpenDesign guide

Separate the illustration from a real map

The SVG communicates the relationship between a list and a spatial surface. It has no projection, coordinates, layers, zoom, geocoding or routing. Its visible caption says schematic and not to scale. A production ArcGIS view needs its own SDK integration, data and accessibility work; a Calcite shell alone does not supply those capabilities.

Esri Calcite Design System Semantic Color Roles

Use surfaces to divide tools without heavy cards

The reference differentiates surface-1 through surface-4, with surface-highlight reserved for emphasis. The specimen uses a white inspector against a quiet off-white canvas and a pale blue selected row. Thin neutral borders identify panel boundaries without adding a floating card around every field.

Give blue a consistent interaction meaning

Brand, hover and press colors form a darker sequence from #007ac2 to #00619b and #004874. The selected pin and primary save action use that family for different interaction roles. Written review states and the note validation message remain legible without relying on their color alone.

Esri Calcite Design System Type and Information Density

Preserve the small information hierarchy

The published absolute type references include 12px small text, 14px base text, 16px medium and 20px extra-large. The sample pairs a 20px workspace title with 16px panel headings and 14px controls. Metadata is smaller but never the only place where the selected object is identified.

Distinguish a fallback from the branded font

This independent specimen uses Arial and system fallbacks. It does not bundle Esri branded fonts or label that fallback as Avenir. An authorized native integration should follow the assets and theme setup of its pinned Calcite release. Changing the font can affect line wraps and control widths, so test the actual deployed asset set.

Esri Calcite Design System Space Tokens and Responsive Panels

Choose current token names

The reference uses the current --calcite-space-* scale, which mixes pixel values for the smallest steps and rem values for larger spacing. Use these named roles consistently when implementing a native theme. The application layout in this specimen uses explicit CSS values so the interpretation can run without importing restricted packages.

Reflow the inspector before compressing the field

Esri Calcite Design System Selection and Filtering Behavior

Use one selected identifier

The list and schematic share selection through A-01, B-02 and C-03, not their current array position. Filtering to Checked selects the available matching site, and the inspector follows. Pressed states are exposed on both the list button and its corresponding pin.

Keep saved notes separate from unsaved drafts

A saved note is stored in a Map keyed by site ID. Returning to that site restores it; changing sites without saving replaces the unsaved text. The helper explicitly states the local lifetime. A production editor should add unsaved-change protection if losing a draft would have a material cost.

Esri Calcite Design System Input Validation and Recovery

Use the actual native input API when adopting Calcite

The native example uses labelText, value, status and validationMessage. The calciteInputInput event can clear a stale error while setFocus() returns attention to the component after a failed application rule. These are public API names, unlike reaching into a shadow root to find an internal input.

Do not confuse local confirmation with service persistence

The independent preview requires at least ten trimmed characters and limits the field to 240. Its confirmation identifies the site and explicitly says locally. Reloading clears notes. A network-backed version would need pending, failure, retry and conflict behavior; none is implied by the local saved message.

  1. Try saving an empty or short note and read the error.
  2. Enter a longer note, save, select another site, then return.
  3. Reload to confirm that the specimen makes no persistence promise.

Esri Calcite Design System Accessible Spatial Alternatives

Provide a list equivalent to each pin

Every actionable pin has a text button in the site list. The illustrated map is therefore not the only way to select an object. Its SVG receives a concise description, while controls have their own names and visible focus outlines. A real map requires more than copying the schematic alternative text.

Place validation next to its field

The textarea references both the helper and error through aria-describedby. On failure it receives aria-invalid and focus; editing removes the stale invalid state. Confirmation uses a status region. Keyboard users can select a site, enter a note and save it without interacting with a drawn geographic shape.

Esri Calcite Design System Version and Integration Boundaries

Pin packages and inspect the licensing requirements

Components 5.1.2 and design tokens 4.1.0 are distinct packages. The current licensing page describes availability with an ArcGIS Online, Enterprise or Location Platform account. Do not carry an assumption about an older open-source release into the current package. The native source below is for a project that has satisfied those requirements.

  • Components: 5.1.2.
  • Design-token reference: 4.1.0.
  • Preview: independent HTML, CSS and JavaScript; no Esri runtime.

Register only the components you use

Esri Calcite Design System Component Examples

Independent site inspection specimen

Complete standalone HTML, CSS and JavaScript used by this preview. Save it as index.html and open it in a browser.

html
<!doctype html>
<html lang="en">
  <meta charset="utf-8" /><meta
    name="viewport"
    content="width=device-width,initial-scale=1"
  /><title>Site inspection panel</title
  ><style>
    * {
      box-sizing: border-box;
    }
    body {
      margin: 0;
      font:
        14px/1.5 Arial,
        sans-serif;
      color: #141414;
      background: #f7f7f7;
    }
    button,
    input,
    select,
    textarea {
      font: inherit;
    }
    button {
      cursor: pointer;
    }
    button:focus-visible,
    input:focus-visible,
    select:focus-visible,
    textarea:focus-visible {
      outline: 2px solid #007ac2;
      outline-offset: 3px;
    }
    header {
      padding: 20px 24px;
      background: #fff;
      border-bottom: 1px solid #d4d4d4;
      display: flex;
      justify-content: space-between;
      gap: 16px;
      align-items: center;
    }
    h1 {
      font-size: 20px;
      margin: 0;
    }
    header p {
      margin: 2px 0 0;
      color: #6b6b6b;
      font-size: 12px;
    }
    .badge {
      background: #d6efff;
      color: #004874;
      padding: 4px 8px;
      font-size: 12px;
    }
    .layout {
      display: grid;
      grid-template-columns: 240px minmax(0, 1fr) 280px;
      min-height: 510px;
    }
    .sites,
    .inspector {
      background: #fff;
      padding: 20px;
      border-right: 1px solid #d4d4d4;
    }
    .inspector {
      border-right: 0;
      border-left: 1px solid #d4d4d4;
    }
    h2 {
      font-size: 16px;
      margin: 0 0 16px;
    }
    label {
      display: block;
      font-weight: 600;
      margin: 12px 0 6px;
    }
    select,
    textarea {
      width: 100%;
      border: 1px solid #949494;
      background: #fff;
      padding: 8px;
      color: inherit;
    }
    textarea {
      resize: vertical;
      min-height: 96px;
    }
    .site {
      display: block;
      width: 100%;
      text-align: left;
      background: #fff;
      border: 1px solid #dedede;
      padding: 12px;
      margin-top: 8px;
    }
    .site[aria-pressed="true"] {
      border-left: 4px solid #007ac2;
      background: #d6efff;
    }
    .site small {
      display: block;
      color: #4a4a4a;
      margin-top: 3px;
    }
    .map {
      position: relative;
      overflow: hidden;
      min-height: 360px;
      background: #ebebe5;
    }
    .map svg {
      width: 100%;
      height: 100%;
      position: absolute;
      inset: 0;
    }
    .map-caption {
      position: absolute;
      bottom: 12px;
      left: 12px;
      padding: 4px 8px;
      background: #fff;
      font-size: 12px;
    }
    .pin {
      position: absolute;
      width: 36px;
      height: 36px;
      border-radius: 50%;
      border: 3px solid #fff;
      background: #007ac2;
      color: #fff;
      font-weight: bold;
      box-shadow: 0 2px 8px #0004;
    }
    .pin[aria-pressed="true"] {
      background: #004874;
      outline: 3px solid #007ac2;
      outline-offset: 3px;
    }
    .pin[hidden] {
      display: none;
    }
    dl {
      display: grid;
      grid-template-columns: 1fr 1fr;
      gap: 8px;
      font-size: 12px;
    }
    dt {
      color: #6b6b6b;
    }
    dd {
      margin: 0;
      text-align: right;
    }
    .primary {
      background: #007ac2;
      color: white;
      border: 0;
      width: 100%;
      padding: 10px;
      margin-top: 12px;
    }
    .primary:hover {
      background: #00619b;
    }
    .error {
      color: #a11b1b;
      font-size: 12px;
    }
    .saved {
      color: #237000;
      font-size: 12px;
    }
    footer {
      padding: 16px 24px;
      border-top: 1px solid #d4d4d4;
      color: #6b6b6b;
      font-size: 12px;
      background: #fff;
    }
    @media (max-width: 1000px) {
      .layout {
        grid-template-columns: 210px minmax(0, 1fr);
      }
      .inspector {
        grid-column: 1/-1;
        border-left: 0;
        border-top: 1px solid #d4d4d4;
      }
      .inspector form {
        max-width: 640px;
      }
    }
    @media (max-width: 550px) {
      header {
        align-items: flex-start;
        flex-direction: column;
      }
      .layout {
        display: flex;
        flex-direction: column;
      }
      .sites {
        border-right: 0;
      }
      .map {
        height: 300px;
        min-height: 300px;
      }
      .inspector {
        padding: 20px;
      }
      .site {
        display: inline-block;
        width: 100%;
      }
    }
  </style>
  <body>
    <header>
      <div>
        <h1>Field inspection workspace</h1>
        <p>Original Calcite-inspired layout study · fictional site data</p>
      </div>
      <span class="badge">Local notes only</span>
    </header>
    <main class="layout">
      <aside class="sites">
        <h2>Inspection sites</h2>
        <label for="filter">Show sites</label
        ><select id="filter">
          <option value="all">All sites</option>
          <option value="review">Needs review</option>
          <option value="checked">Checked</option>
        </select>
        <div id="site-list"></div>
        <p id="count" aria-live="polite"></p>
      </aside>
      <section class="map" aria-label="Illustrated site plan">
        <svg
          viewBox="0 0 700 510"
          preserveAspectRatio="xMidYMid slice"
          role="img"
          aria-label="Original schematic with a river, roads and three inspection sites; not a geographic map"
        >
          <rect width="700" height="510" fill="#e4e8db" />
          <path
            d="M480 -50Q230 110 440 260T360 570"
            fill="none"
            stroke="#b6dbe9"
            stroke-width="100"
          />
          <path
            d="M-20 150L720 280M160 -20L290 530M-20 400L720 80"
            stroke="#fff"
            stroke-width="22"
          />
          <path
            d="M-20 150L720 280M160 -20L290 530M-20 400L720 80"
            stroke="#c8c8bf"
            stroke-width="2"
          />
          <g fill="#c4cfb5">
            <rect x="50" y="50" width="100" height="70" />
            <rect x="510" y="340" width="130" height="80" />
            <rect x="80" y="260" width="70" height="60" />
          </g>
        </svg>
        <div id="pins"></div>
        <span class="map-caption">Schematic illustration · not to scale</span>
      </section>
      <aside class="inspector">
        <h2 id="site-title">North access</h2>
        <dl>
          <dt>Site ID</dt>
          <dd id="site-id"></dd>
          <dt>Review state</dt>
          <dd id="site-state"></dd>
        </dl>
        <form id="note-form" novalidate>
          <label for="note">Inspection note</label
          ><textarea
            id="note"
            aria-describedby="note-help error"
            maxlength="240"
          ></textarea>
          <p id="note-help">
            Add 10–240 characters. Notes stay in this page until reload.
          </p>
          <p id="error" class="error" hidden>
            Write at least 10 characters before saving.
          </p>
          <button class="primary" type="submit">Save local note</button>
          <p id="saved" class="saved" role="status"></p>
        </form>
      </aside>
    </main>
    <footer>
      Independent HTML/CSS interpretation by OpenDesign. No Calcite runtime,
      Esri fonts, ArcGIS map or service is loaded.
    </footer>
    <script>
      const sites = [
        { id: "A-01", name: "North access", state: "review", x: 29, y: 24 },
        { id: "B-02", name: "River crossing", state: "review", x: 62, y: 48 },
        { id: "C-03", name: "South garden", state: "checked", x: 34, y: 76 },
      ];
      let selected = "A-01";
      const notes = new Map(),
        list = document.querySelector("#site-list"),
        pins = document.querySelector("#pins"),
        filter = document.querySelector("#filter"),
        note = document.querySelector("#note"),
        error = document.querySelector("#error"),
        saved = document.querySelector("#saved");
      function render() {
        const visible = sites.filter(
          (s) => filter.value === "all" || s.state === filter.value,
        );
        if (!visible.some((s) => s.id === selected)) selected = visible[0]?.id;
        list.replaceChildren();
        pins.replaceChildren();
        for (const s of visible) {
          const b = document.createElement("button");
          b.type = "button";
          b.className = "site";
          b.setAttribute("aria-pressed", String(s.id === selected));
          b.textContent = s.name;
          const small = document.createElement("small");
          small.textContent =
            s.id + " · " + (s.state === "review" ? "Needs review" : "Checked");
          b.append(small);
          b.onclick = () => {
            selected = s.id;
            render();
          };
          list.append(b);
          const pin = document.createElement("button");
          pin.type = "button";
          pin.className = "pin";
          pin.style.left = s.x + "%";
          pin.style.top = s.y + "%";
          pin.textContent = s.id[0];
          pin.setAttribute("aria-label", "Select " + s.name);
          pin.setAttribute("aria-pressed", String(s.id === selected));
          pin.onclick = b.onclick;
          pins.append(pin);
        }
        const s = sites.find((s) => s.id === selected);
        document.querySelector("#count").textContent =
          visible.length + " sites shown";
        document.querySelector("#site-title").textContent = s.name;
        document.querySelector("#site-id").textContent = s.id;
        document.querySelector("#site-state").textContent =
          s.state === "review" ? "Needs review" : "Checked";
        note.value = notes.get(s.id) || "";
        error.hidden = true;
        note.removeAttribute("aria-invalid");
        saved.textContent = "";
      }
      filter.onchange = render;
      note.oninput = () => {
        error.hidden = true;
        note.removeAttribute("aria-invalid");
        saved.textContent = "";
      };
      document.querySelector("#note-form").onsubmit = (e) => {
        e.preventDefault();
        const value = note.value.trim();
        if (value.length < 10) {
          error.hidden = false;
          note.setAttribute("aria-invalid", "true");
          note.focus();
          return;
        }
        notes.set(selected, value);
        saved.textContent = "Note saved locally for " + selected + ".";
      };
      render();
    </script>
  </body>
</html>

Code reference

  • Original schematic and application behavior. No map SDK, remote data or Esri runtime is included.

Native Calcite input alternative

Replace src/main.js in a Vite vanilla project whose index.html contains <div id="app"></div>.

js
import "@esri/calcite-components/components/calcite-input";
import "@esri/calcite-components/components/calcite-button";

document.querySelector("#app").innerHTML = `
  <calcite-input id="inspection-note" label-text="Inspection note"
    validation-message="Enter at least ten characters"></calcite-input>
  <calcite-button id="save-note">Validate note</calcite-button>
  <p id="result" role="status"></p>`;
const field = document.querySelector("#inspection-note");
const result = document.querySelector("#result");
field.addEventListener("calciteInputInput", () => {
  field.status = "idle";
  result.textContent = "";
});
document.querySelector("#save-note").addEventListener("click", async () => {
  if (field.value.trim().length < 10) {
    field.status = "invalid";
    await field.setFocus();
    return;
  }
  field.status = "valid";
  result.textContent = "The note passes the local rule. Nothing was sent.";
});

Code reference

  • Install @esri/[email protected] after reviewing the current licensing requirements. This alternative was API-checked; the independent preview above is the browser-tested specimen.
04

Esri Calcite Design System Agent Setup

Implementation Starting Point

The native component package requires an eligible ArcGIS account under the current licensing terms. Review asset-path requirements when self-hosting component assets.

sh
# Independent specimen: save the complete HTML example as index.html.
# Native alternative for an appropriately licensed project:
npm create vite@latest calcite-note -- --template vanilla
cd calcite-note
npm install
npm install @esri/[email protected]
# Replace src/main.js with the native input example.
npm run dev

A Prompt for Your Project

Agent Prompt
Build a focused spatial inspection workspace using the Calcite references. Keep the selected object ID consistent between list and inspector, expose written states, and distinguish local notes from service persistence. Use the standalone interpretation as the starting point or deliberately choose the licensed native component path. Do not describe the original schematic as an ArcGIS map.
05

Esri Calcite Design System Sources and Scope

OpenDesign application guide. The illustrated example is independently implemented and uses fictional data. Current Calcite use is governed by Esri licensing and requires an eligible ArcGIS account; the native integration example is an alternative for appropriately licensed projects, not the runtime of this preview.