Cloaked Design SystemVisualizations

Globe

An orthographic globe drawn on a canvas, as either a land-dot field or a coastline wireframe, with optional location markers, for decorative geography.

Implementation preview

COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

7 stories

Default selectedOpen canvas

Example source

packages/design-system/src/components/visualizations/Globe/Globe.stories.tsxExport Default

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Stories + source JSON ↗

Local specification source status: preview. Implementation preview pending sign-off.

An orthographic globe drawn on a canvas, as either a land-dot field or a coastline wireframe, with optional location markers, for decorative geography.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off

Implementation API 1 entry point · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

import { Globe } from '@cloakedinc/design-system';

GlobeGlobeProps

packages/design-system/src/components/visualizations/Globe/Globe.tsx:22

Prop	Type	Presence	Notes
`mode`	`GlobeMode`	Required	Which look to draw.
`size`	`number`	Required	Square canvas edge in logical px.
`zoom`	`number \| undefined`	Optional	How much of the canvas the sphere fills. `1` fits it with a hair of margin; above `1` draws it larger than the canvas so the canvas crops it, which is how a globe reads as texture rather than as a globe in a box. Prefer this over an oversized canvas in a clipping wrapper — the canvas then stays inside its own layout box.Source default: `1`
`markers`	`readonly GlobeMarker[] \| undefined`	Optional	Locations to plot.Source default: `NO_MARKERS`
`accentColor`	`string \| undefined`	Optional	Marker and glow color. Defaults to the brand accent.Source default: `DEFAULT_ACCENT_COLOR`
`baseColor`	`string \| undefined`	Optional	Dot and coastline color. Defaults to primary text, so it reads on either theme.Source default: `DEFAULT_BASE_COLOR`
`intensity`	`number \| undefined`	Optional	Scales the geography's opacity, `0..1`. Lets one globe serve an active and an idle state by intensity rather than by swapping to a different look, so the change reads as the same object dimming instead of as two different graphics. Markers keep their own opacity.Source default: `1`
`centerLatitude`	`number \| undefined`	Optional	Latitude the sphere faces at rest.Source default: `DEFAULT_CENTER_LATITUDE`
`centerLongitude`	`number \| undefined`	Optional	Longitude the sphere faces at rest, and the point idle rotation starts from.Source default: `DEFAULT_CENTER_LONGITUDE`
`spin`	`boolean \| undefined`	Optional	Whether the sphere drifts. Ignored under `prefers-reduced-motion`.Source default: `true`
`ariaLabel`	`string \| undefined`	Optional	Accessible label; without one the globe is hidden from assistive tech as decoration.
`testId`	`string \| undefined`	Optional	Optional test selector.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

An orthographic globe on a canvas, in two looks: a field of land dots for an active reading, and coastline outlines with a limb ring for a quiet one.

When to use

Use Globe as decorative geography — to suggest global reach, or to give a connection state a sense of place — and put the actual location in surrounding copy. Switch mode to carry state: dots for connected or active, wireframe for idle or off.

Do not use it where a position has to be read. There is no scale, graticule, or labelling, and markers are placed for feel rather than for measurement.

Crop with `zoom`, not with a wrapper

The canvas is always square at size. To show only part of the sphere, raise zoom so the sphere is drawn larger than the canvas and the canvas crops it — the geography then reads as texture rather than as a globe floating in a box.

Do not crop by putting an oversized canvas inside an overflow: hidden wrapper. A canvas wider than its container still reports an overflowing layout box even though the parent clips it visually, which shows up as viewport overflow and as a collision with whatever it is layered over. Keeping the canvas inside its own box and cropping with zoom avoids both.

Geometry and cost

Geography is baked at build time by scripts/generateLandMask.ts into a packed land bitmask (~3 KB) plus simplified coastline rings (~23 KB), rather than shipping the 169 KB polygon set it came from. Both are decoded once per process and shared by every instance, so a second Globe on the same screen costs only its own draw loop. There is no WebGL and no three dependency: the sphere is projected in canvas 2D, which also lets --cds-* token colors apply directly and survive a theme flip.

Motion is a 3°/second drift capped at 24fps, and it stops entirely under prefers-reduced-motion or spin={false}.

Component specification

$schema

../../../specs/component-spec.schema.json

Parts

Id: canvas
Label: Canvas
Description: The square canvas the sphere is drawn onto.
Required: true

Id: dot
Label: Land dot
Description: One land sample in the dot field, tapering toward the limb.

Id: coastline
Label: Coastline
Description: A simplified coastline ring stroked in the wireframe look.

Id: limb
Label: Limb
Description: The circle tracing the sphere silhouette in the wireframe look.

Id: marker
Label: Marker
Description: A plotted location on the near side of the sphere.

Id: glow
Label: Active glow
Description: The breathing radial glow behind the active marker.

Allowed Design Choices

Variants

Dots

Label: Dots
Description: Land rendered as a field of dots, for an active or connected reading.

Wireframe

Label: Wireframe
Description: Land rendered as coastline outlines with a limb ring, for a quiet or inactive reading.

Sizes

Variants

Id: dots
Label: Dots
Description: A filled field of land dots on the near hemisphere.
Platforms: ios
android
web

Id: wireframe
Label: Wireframe
Description: Coastline outlines plus the sphere's limb circle.
Platforms: ios
android
web

Sizes

None specified

Measurements

Id: radius-fraction
Label: Sphere radius
Kind: example-only
Value: 48
Unit: %
Applies To: canvas
Notes: The sphere radius is 48% of the canvas edge, leaving the limb a hair of margin. A canvas constant, not a CSS-token binding.

Id: zoom-default
Label: Zoom
Kind: example-only
Value: 1
Unit: ratio
Applies To: canvas
Notes: Multiplies the sphere radius. 1 fits the sphere in the canvas; above 1 the canvas crops it, which is the supported way to show a partial globe. A canvas constant, not a CSS-token binding.

Id: dot-size
Label: Land dot size
Kind: example-only
Value: 1.6
Unit: px
Applies To: dot
Notes: Dot edge at the sub-viewer point, scaling down to 55% of this at the limb so the sphere reads as curved. A canvas constant, not a CSS-token binding.

Layout

Alignment: The canvas is always square at the requested size, with the sphere centered in it.
Flow: Geography is projected orthographically; only the near hemisphere draws.
Notes: Consumers crop the sphere by raising zoom so the canvas clips it, keeping the canvas inside its own layout box. Cropping via an oversized canvas in an overflow-hidden wrapper reports an overflowing box and is not supported.
The globe is drawn on a canvas, so its geometry is expressed in canvas units, not CSS tokens.

Typography And Color

Typography

None specified

Colors

Label: Land and coastlines
Description: Land dots and coastline strokes, applied at reduced alpha by depth.
Token: --cds-text-primary

Label: Markers and glow
Description: Plotted locations and the active marker's glow.
Token: --cds-brand

States

Id: drifting
Label: Drifting
Description: With motion allowed the sphere rotates slowly and the active marker breathes.

Id: static
Label: Static
Description: Under reduced motion, or with spin off, a single frame is drawn at the resting longitude and no further frames are scheduled.

Id: dimmed
Label: Dimmed
Description: A reduced intensity scales the geography's opacity so one globe can serve an active and an idle state without swapping to a different look. Below roughly 0.4 the sphere stops reading as one: dot density compresses toward the limb, so only the limb survives and the shape reads as an arc.

Id: unmarked
Label: Unmarked
Description: With no markers only the geography draws.

Behavior

Label: Far-side culling
Description: Dots, coastline segments, and markers behind the limb are dropped rather than drawn through the sphere.

Label: Depth shading
Description: Land dots shrink and fade toward the limb, so curvature reads without any lighting model.

Label: Full-density rendering
Description: The canvas backing store scales to the device pixel ratio up to 3x, rather than the 2x the other canvas visualizations cap at: the dot field is hard-edged, so rendering below the screen's density upscales every dot and the sphere reads soft beside crisp text.

Label: Baked geometry
Description: Geography is decoded once per process from a packed land bitmask and simplified coastline set, and shared across instances.

Accessibility

Label: Meaningful globe
Description: Pass an accessible label so the globe is announced as a meaningful image.

Label: Decorative globe
Description: Omit the label to hide the canvas from assistive technology when nearby text carries the meaning.

Content Adaptation

Label: Decorative geography
Description: Use Globe to suggest global reach or a remote location; state the actual place in nearby copy.

Label: Not a map
Description: Do not use Globe where a position has to be read; it carries no scale, graticule, or labels.

Motion Haptics

Motion

Label: Idle drift
Description: The sphere rotates 3 degrees of longitude per second, capped at 24 frames per second so a decorative loop does not hold a 60fps frame budget.

Label: Marker breath
Description: The active marker's glow eases between 82% and 115% scale on a 2.6 second cycle.

Label: Reduced motion
Description: When reduced motion is set a single posed frame is drawn and no further frames are scheduled.

Haptics

Label: No feedback
Description: The globe is a display and requests no haptic feedback.

Platform Differences

None specified

Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1