# 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. Version: 0.2.0-preview.1 (preview) Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721 Contract kind: source-derived Source: packages/design-system/src/components/visualizations/Globe/Globe.tsx ## Guidance { "summary": "An orthographic globe drawn on a canvas, as either a land-dot field or a coastline wireframe, with optional location markers, for decorative geography.", "guidance": [ { "heading": "Overview", "body": "An orthographic globe on a canvas, in two looks: a field of land dots for an active reading, and\ncoastline outlines with a limb ring for a quiet one." }, { "heading": "When to use", "body": "Use Globe as decorative geography — to suggest global reach, or to give a connection state a\nsense of place — and put the actual location in surrounding copy. Switch `mode` to carry state:\n`dots` for connected or active, `wireframe` for idle or off.\n\nDo not use it where a position has to be read. There is no scale, graticule, or labelling, and\nmarkers are placed for feel rather than for measurement." }, { "heading": "Crop with `zoom`, not with a wrapper", "body": "The canvas is always square at `size`. To show only part of the sphere, raise `zoom` so the sphere\nis drawn larger than the canvas and the canvas crops it — the geography then reads as texture\nrather than as a globe floating in a box.\n\nDo **not** crop by putting an oversized canvas inside an `overflow: hidden` wrapper. A canvas wider\nthan its container still reports an overflowing layout box even though the parent clips it\nvisually, which shows up as viewport overflow and as a collision with whatever it is layered over.\nKeeping the canvas inside its own box and cropping with `zoom` avoids both." }, { "heading": "Geometry and cost", "body": "Geography is baked at build time by `scripts/generateLandMask.ts` into a packed land bitmask\n(~3 KB) plus simplified coastline rings (~23 KB), rather than shipping the 169 KB polygon set it\ncame from. Both are decoded once per process and shared by every instance, so a second Globe on\nthe same screen costs only its own draw loop. There is no WebGL and no `three` dependency: the\nsphere is projected in canvas 2D, which also lets `--cds-*` token colors apply directly and\nsurvive a theme flip.\n\nMotion is a 3°/second drift capped at 24fps, and it stops entirely under\n`prefers-reduced-motion` or `spin={false}`." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/visualizations/Globe/Globe.mdx", "status": "local-preview", "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification." } ## Contract and public API ```json { "props": [ { "name": "mode", "type": "GlobeMode", "declared_type": "GlobeMode", "required": true, "description": "Which look to draw.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 34 }, "values": [ "dots", "wireframe" ], "values_complete": true }, { "name": "size", "type": "number", "declared_type": "number", "required": true, "description": "Square canvas edge in logical px.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 36 } }, { "name": "zoom", "type": "number | undefined", "declared_type": "number", "required": false, "description": "How much of the canvas the sphere fills. `1` fits it with a hair of margin; above `1` draws it\nlarger than the canvas so the canvas crops it, which is how a globe reads as texture rather\nthan as a globe in a box. Prefer this over an oversized canvas in a clipping wrapper — the\ncanvas then stays inside its own layout box.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 43 }, "default": "1", "default_kind": "source-expression" }, { "name": "markers", "type": "readonly GlobeMarker[] | undefined", "declared_type": "readonly GlobeMarker[]", "required": false, "description": "Locations to plot.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 45 }, "default": "NO_MARKERS", "default_kind": "source-expression" }, { "name": "accentColor", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Marker and glow color. Defaults to the brand accent.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 47 }, "default": "DEFAULT_ACCENT_COLOR", "default_kind": "source-expression" }, { "name": "baseColor", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Dot and coastline color. Defaults to primary text, so it reads on either theme.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 49 }, "default": "DEFAULT_BASE_COLOR", "default_kind": "source-expression" }, { "name": "intensity", "type": "number | undefined", "declared_type": "number", "required": false, "description": "Scales the geography's opacity, `0..1`. Lets one globe serve an active and an idle state by\nintensity rather than by swapping to a different look, so the change reads as the same object\ndimming instead of as two different graphics. Markers keep their own opacity.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 55 }, "default": "1", "default_kind": "source-expression" }, { "name": "centerLatitude", "type": "number | undefined", "declared_type": "number", "required": false, "description": "Latitude the sphere faces at rest.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 57 }, "default": "DEFAULT_CENTER_LATITUDE", "default_kind": "source-expression" }, { "name": "centerLongitude", "type": "number | undefined", "declared_type": "number", "required": false, "description": "Longitude the sphere faces at rest, and the point idle rotation starts from.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 59 }, "default": "DEFAULT_CENTER_LONGITUDE", "default_kind": "source-expression" }, { "name": "spin", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Whether the sphere drifts. Ignored under `prefers-reduced-motion`.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 61 }, "values": [ false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label; without one the globe is hidden from assistive tech as decoration.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 63 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional test selector.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 65 } } ], "prop_shapes": {}, "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "Globe", "public_path": "Globe", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "Globe", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/visualizations/Globe/Globe.tsx", "line": 22 }, "props_type": "GlobeProps", "props": [ { "name": "mode", "type": "GlobeMode", "declared_type": "GlobeMode", "required": true, "description": "Which look to draw.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 34 }, "values": [ "dots", "wireframe" ], "values_complete": true }, { "name": "size", "type": "number", "declared_type": "number", "required": true, "description": "Square canvas edge in logical px.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 36 } }, { "name": "zoom", "type": "number | undefined", "declared_type": "number", "required": false, "description": "How much of the canvas the sphere fills. `1` fits it with a hair of margin; above `1` draws it\nlarger than the canvas so the canvas crops it, which is how a globe reads as texture rather\nthan as a globe in a box. Prefer this over an oversized canvas in a clipping wrapper — the\ncanvas then stays inside its own layout box.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 43 }, "default": "1", "default_kind": "source-expression" }, { "name": "markers", "type": "readonly GlobeMarker[] | undefined", "declared_type": "readonly GlobeMarker[]", "required": false, "description": "Locations to plot.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 45 }, "default": "NO_MARKERS", "default_kind": "source-expression" }, { "name": "accentColor", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Marker and glow color. Defaults to the brand accent.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 47 }, "default": "DEFAULT_ACCENT_COLOR", "default_kind": "source-expression" }, { "name": "baseColor", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Dot and coastline color. Defaults to primary text, so it reads on either theme.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 49 }, "default": "DEFAULT_BASE_COLOR", "default_kind": "source-expression" }, { "name": "intensity", "type": "number | undefined", "declared_type": "number", "required": false, "description": "Scales the geography's opacity, `0..1`. Lets one globe serve an active and an idle state by\nintensity rather than by swapping to a different look, so the change reads as the same object\ndimming instead of as two different graphics. Markers keep their own opacity.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 55 }, "default": "1", "default_kind": "source-expression" }, { "name": "centerLatitude", "type": "number | undefined", "declared_type": "number", "required": false, "description": "Latitude the sphere faces at rest.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 57 }, "default": "DEFAULT_CENTER_LATITUDE", "default_kind": "source-expression" }, { "name": "centerLongitude", "type": "number | undefined", "declared_type": "number", "required": false, "description": "Longitude the sphere faces at rest, and the point idle rotation starts from.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 59 }, "default": "DEFAULT_CENTER_LONGITUDE", "default_kind": "source-expression" }, { "name": "spin", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Whether the sphere drifts. Ignored under `prefers-reduced-motion`.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 61 }, "values": [ false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label; without one the globe is hidden from assistive tech as decoration.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 63 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional test selector.", "source": { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 65 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 10, "name": "GlobeMode", "code": "export type GlobeMode = 'dots' | 'wireframe';" }, { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 16, "name": "GlobeMarker", "code": "export interface GlobeMarker {\n /** Latitude in degrees, -90..90. */\n latitude: number;\n /** Longitude in degrees, -180..180. */\n longitude: number;\n /** Enlarges the marker and gives it the breathing glow. Intended for a single marker. */\n active?: boolean;\n}" }, { "path": "packages/design-system/src/components/visualizations/Globe/GlobeProps.ts", "line": 32, "name": "GlobeProps", "code": "export interface GlobeProps {\n /** Which look to draw. */\n mode: GlobeMode;\n /** Square canvas edge in logical px. */\n size: number;\n /**\n * How much of the canvas the sphere fills. `1` fits it with a hair of margin; above `1` draws it\n * larger than the canvas so the canvas crops it, which is how a globe reads as texture rather\n * than as a globe in a box. Prefer this over an oversized canvas in a clipping wrapper — the\n * canvas then stays inside its own layout box.\n */\n zoom?: number;\n /** Locations to plot. */\n markers?: readonly GlobeMarker[];\n /** Marker and glow color. Defaults to the brand accent. */\n accentColor?: string;\n /** Dot and coastline color. Defaults to primary text, so it reads on either theme. */\n baseColor?: string;\n /**\n * Scales the geography's opacity, `0..1`. Lets one globe serve an active and an idle state by\n * intensity rather than by swapping to a different look, so the change reads as the same object\n * dimming instead of as two different graphics. Markers keep their own opacity.\n */\n intensity?: number;\n /** Latitude the sphere faces at rest. */\n centerLatitude?: number;\n /** Longitude the sphere faces at rest, and the point idle rotation starts from. */\n centerLongitude?: number;\n /** Whether the sphere drifts. Ignored under `prefers-reduced-motion`. */\n spin?: boolean;\n /** Accessible label; without one the globe is hidden from assistive tech as decoration. */\n ariaLabel?: string;\n /** Optional test selector. */\n testId?: string;\n}" } ], "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source." }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "Globe", "status": "preview", "version": "1.0.0", "summary": "An orthographic globe drawn on a canvas, as either a land-dot field or a coastline wireframe, with optional location markers, for decorative geography." }, "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." } ], "allowedDesignChoices": { "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": [], "measurements": [ { "id": "radius-fraction", "label": "Sphere radius", "kind": "example-only", "value": 48, "unit": "%", "appliesTo": [ "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", "appliesTo": [ "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", "appliesTo": [ "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." ] }, "typographyAndColor": { "typography": [], "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." } ], "contentAdaptation": [ { "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." } ], "motionHaptics": { "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." } ] }, "platformDifferences": [] }, "platforms": { "implemented": [ "web" ], "native": "Imported design guidance only; no native implementation or parity verification in this preview.", "react": { "implementation": "local", "status": "preview", "parity": "web-reference" }, "vue": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "swift": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "kotlin": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" } }, "tokens": [ { "name": "--cds-text-primary", "light": "#141410", "dark": "#f3f1ed" }, { "name": "--cds-brand", "light": "#ff550c", "dark": "#ff550c" } ], "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": "approved", "spec_origin": "imported-adapted", "local_spec_source_status": "approved", "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract." }, "missing_facts": [ { "code": "human-review-pending", "detail": "This local preview has no recorded human design or engineering sign-off." }, { "code": "platform-parity-unverified", "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified." }, { "code": "figma-mapping-unverified", "detail": "No current component-level Figma node and immutable revision have been verified for this contract." } ] } ``` ## Visual states - [Default](/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--default&viewMode=story) | export: Default | source: packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx - [Wireframe](/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--wireframe&viewMode=story) | export: Wireframe | source: packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx - [Cropped](/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--cropped&viewMode=story) | export: Cropped | source: packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx - [Dimmed](/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--dimmed&viewMode=story) | export: Dimmed | source: packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx - [Unmarked](/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--unmarked&viewMode=story) | export: Unmarked | source: packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx - [Static](/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--static&viewMode=story) | export: Static | source: packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx - [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.