{ "version": "0.2.0-preview.1", "content_digest": "70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721", "status": "preview", "authority": { "repository": "cloakedinc/design", "path": "packages/design-system", "catalog": "packages/design-system/catalog.json", "status": "preview" }, "provenance": { "repo": "cloakedinc/automation", "commit": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "path": "packages/design-system", "imported_spec_status": "approved" }, "adaptations": [ { "id": "button-content-gap", "status": "preview", "description": "Use the specification's 4px content gap instead of the inherited 8px implementation gap." }, { "id": "keyboard-focus", "status": "preview", "description": "Add visible Button and Input keyboard focus and an overridable inset focus default for shared button resets, including FAQ cards and ListItem rows." }, { "id": "supporting-text-contrast", "status": "preview", "description": "Map light secondary text to the existing grey-04-strong primitive for readable helper text on white and cream." }, { "id": "danger-text-contrast", "status": "preview", "description": "Separate readable danger text/borders from destructive fills; preserve the primary danger-button fill and label pair." }, { "id": "preview-status", "status": "preview", "description": "Local components, specs and token adaptations await human sign-off; upstream approved status is provenance only." }, { "id": "motion-comparison-accessibility", "status": "preview", "description": "Preserve the original MotionShowcase comparisons while requiring explicit replay, responding to live reduced-motion changes, and keeping duration tracks usable on small screens." }, { "id": "list-item-ownership", "status": "preview", "description": "List owns listitem wrappers for its content rows, while section labels stay outside the row count and standalone rows retain their existing semantics." }, { "id": "card-delta-text-contrast", "status": "preview", "description": "Mix Card.Delta foregrounds from 60% existing tone solid and 40% primary text for readable contrast in both themes; preserve the four original tone fills." }, { "id": "carousel-keyboard-access", "status": "preview", "description": "Keep all native-scrolling carousel slide controls exposed to assistive technology and keyboard navigation; pause autoplay while focus is inside the carousel." } ], "id": "globe", "name": "Globe", "category": "Visualizations", "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.", "documentation": { "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." }, "source": { "path": "packages/design-system/src/components/visualizations/Globe/Globe.tsx", "code": "import React from 'react';\nimport type { GlobeProps } from './GlobeProps';\nimport { runGlobeAnimation } from '../runGlobeAnimation';\nimport { useReducedMotion } from '../useReducedMotion';\nimport styles from './Globe.module.scss';\n\nconst DEFAULT_ACCENT_COLOR = 'var(--cds-brand)';\nconst DEFAULT_BASE_COLOR = 'var(--cds-text-primary)';\n\n/** Faces the Americas, matching where the VPN designs rest the sphere. */\nconst DEFAULT_CENTER_LATITUDE = 18;\nconst DEFAULT_CENTER_LONGITUDE = -70;\n\nconst NO_MARKERS: readonly [] = [];\n\n/**\n * An orthographic globe drawn as a land-dot field or a coastline wireframe, with optional location\n * markers and a slow idle drift — decorative geography behind a headline, not a readable map.\n *\n * The canvas is square at `size`; wrap it in a smaller overflow-hidden box to crop the sphere.\n */\nexport function Globe({\n mode,\n size,\n zoom = 1,\n intensity = 1,\n markers = NO_MARKERS,\n accentColor = DEFAULT_ACCENT_COLOR,\n baseColor = DEFAULT_BASE_COLOR,\n centerLatitude = DEFAULT_CENTER_LATITUDE,\n centerLongitude = DEFAULT_CENTER_LONGITUDE,\n spin = true,\n ariaLabel,\n testId,\n}: GlobeProps) {\n const canvasRef = React.useRef(null);\n const reducedMotion = useReducedMotion();\n\n // Markers are a new array literal on most renders, so depend on their values rather than the\n // array identity — otherwise every parent render restarts the animation from longitude zero.\n const markerKey = markers\n .map(marker => `${marker.latitude},${marker.longitude},${marker.active ?? false}`)\n .join(';');\n\n React.useEffect(() => {\n const canvas = canvasRef.current;\n if (!canvas) return undefined;\n\n return runGlobeAnimation({\n canvas,\n mode,\n size,\n zoom,\n intensity,\n markers: markers.map(marker => ({ ...marker })),\n accentColor,\n baseColor,\n centerLatitude,\n centerLongitude,\n spin,\n reducedMotion,\n });\n // eslint-disable-next-line react-hooks/exhaustive-deps -- markerKey stands in for markers by value\n }, [\n mode,\n size,\n zoom,\n intensity,\n markerKey,\n accentColor,\n baseColor,\n centerLatitude,\n centerLongitude,\n spin,\n reducedMotion,\n ]);\n\n return (\n \n );\n}\n" }, "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": [] }, "spec_source": "packages/design-system/src/components/visualizations/Globe/Globe.spec.json", "guidance_source": { "path": "packages/design-system/src/components/visualizations/Globe/Globe.mdx", "code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec } from '../../../../.storybook/blocks';\nimport * as Stories from './Globe.stories';\nimport globeSpec from './Globe.spec.json';\n\n\n\n# Globe\n\nAn 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.\n\n\n\n## When to use\n\nUse 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.\n\n## Crop with `zoom`, not with a wrapper\n\nThe 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.\n\n\n\n## Geometry and cost\n\nGeography 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}`.\n\n## Design Guidelines\n\n\n\n## Props\n\n\n" }, "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": {}, "examples": [], "tokens": [ { "name": "--cds-text-primary", "light": "#141410", "dark": "#f3f1ed" }, { "name": "--cds-brand", "light": "#ff550c", "dark": "#ff550c" } ], "visual_reference": { "stories": [ { "id": "cloaked-design-system-visualizations-globe--default", "name": "Default", "title": "Cloaked Design System/Visualizations/Globe", "exportName": "Default", "source_path": "packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx", "source_digest": "1ed865efbedc81593c93d3fc204e837b5fd6345d80ba4621e831a9bdcfcc5c4a", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--default&viewMode=story" }, { "id": "cloaked-design-system-visualizations-globe--wireframe", "name": "Wireframe", "title": "Cloaked Design System/Visualizations/Globe", "exportName": "Wireframe", "source_path": "packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx", "source_digest": "1ed865efbedc81593c93d3fc204e837b5fd6345d80ba4621e831a9bdcfcc5c4a", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--wireframe&viewMode=story" }, { "id": "cloaked-design-system-visualizations-globe--cropped", "name": "Cropped", "title": "Cloaked Design System/Visualizations/Globe", "exportName": "Cropped", "source_path": "packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx", "source_digest": "1ed865efbedc81593c93d3fc204e837b5fd6345d80ba4621e831a9bdcfcc5c4a", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--cropped&viewMode=story" }, { "id": "cloaked-design-system-visualizations-globe--dimmed", "name": "Dimmed", "title": "Cloaked Design System/Visualizations/Globe", "exportName": "Dimmed", "source_path": "packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx", "source_digest": "1ed865efbedc81593c93d3fc204e837b5fd6345d80ba4621e831a9bdcfcc5c4a", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--dimmed&viewMode=story" }, { "id": "cloaked-design-system-visualizations-globe--unmarked", "name": "Unmarked", "title": "Cloaked Design System/Visualizations/Globe", "exportName": "Unmarked", "source_path": "packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx", "source_digest": "1ed865efbedc81593c93d3fc204e837b5fd6345d80ba4621e831a9bdcfcc5c4a", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--unmarked&viewMode=story" }, { "id": "cloaked-design-system-visualizations-globe--static", "name": "Static", "title": "Cloaked Design System/Visualizations/Globe", "exportName": "Static", "source_path": "packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx", "source_digest": "1ed865efbedc81593c93d3fc204e837b5fd6345d80ba4621e831a9bdcfcc5c4a", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--static&viewMode=story" }, { "id": "cloaked-design-system-visualizations-globe--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Visualizations/Globe", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx", "source_digest": "1ed865efbedc81593c93d3fc204e837b5fd6345d80ba4621e831a9bdcfcc5c4a", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--dark-theme&viewMode=story" } ], "name": "Globe", "id": "globe", "category": "Visualizations" }, "stories": [ { "id": "cloaked-design-system-visualizations-globe--default", "name": "Default", "title": "Cloaked Design System/Visualizations/Globe", "exportName": "Default", "source_path": "packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx", "source_digest": "1ed865efbedc81593c93d3fc204e837b5fd6345d80ba4621e831a9bdcfcc5c4a", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--default&viewMode=story" }, { "id": "cloaked-design-system-visualizations-globe--wireframe", "name": "Wireframe", "title": "Cloaked Design System/Visualizations/Globe", "exportName": "Wireframe", "source_path": "packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx", "source_digest": "1ed865efbedc81593c93d3fc204e837b5fd6345d80ba4621e831a9bdcfcc5c4a", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--wireframe&viewMode=story" }, { "id": "cloaked-design-system-visualizations-globe--cropped", "name": "Cropped", "title": "Cloaked Design System/Visualizations/Globe", "exportName": "Cropped", "source_path": "packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx", "source_digest": "1ed865efbedc81593c93d3fc204e837b5fd6345d80ba4621e831a9bdcfcc5c4a", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--cropped&viewMode=story" }, { "id": "cloaked-design-system-visualizations-globe--dimmed", "name": "Dimmed", "title": "Cloaked Design System/Visualizations/Globe", "exportName": "Dimmed", "source_path": "packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx", "source_digest": "1ed865efbedc81593c93d3fc204e837b5fd6345d80ba4621e831a9bdcfcc5c4a", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--dimmed&viewMode=story" }, { "id": "cloaked-design-system-visualizations-globe--unmarked", "name": "Unmarked", "title": "Cloaked Design System/Visualizations/Globe", "exportName": "Unmarked", "source_path": "packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx", "source_digest": "1ed865efbedc81593c93d3fc204e837b5fd6345d80ba4621e831a9bdcfcc5c4a", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--unmarked&viewMode=story" }, { "id": "cloaked-design-system-visualizations-globe--static", "name": "Static", "title": "Cloaked Design System/Visualizations/Globe", "exportName": "Static", "source_path": "packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx", "source_digest": "1ed865efbedc81593c93d3fc204e837b5fd6345d80ba4621e831a9bdcfcc5c4a", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--static&viewMode=story" }, { "id": "cloaked-design-system-visualizations-globe--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Visualizations/Globe", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx", "source_digest": "1ed865efbedc81593c93d3fc204e837b5fd6345d80ba4621e831a9bdcfcc5c4a", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-visualizations-globe--dark-theme&viewMode=story" } ], "stories_source": { "path": "packages/design-system/src/components/visualizations/Globe/Globe.stories.tsx", "code": "import type { Meta, StoryObj } from '@storybook/react-vite';\nimport { disabledControl } from '../../../storybook/controlOptions';\nimport { Globe } from './Globe';\n\n/** A handful of real VPN exit cities, so the marker spread looks like a server list. */\nconst markers = [\n { latitude: 40.7128, longitude: -74.006, active: true },\n { latitude: 37.7749, longitude: -122.4194 },\n { latitude: 51.5074, longitude: -0.1278 },\n { latitude: -23.5505, longitude: -46.6333 },\n { latitude: 52.3676, longitude: 4.9041 },\n];\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Visualizations/Globe',\n component: Globe,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'An orthographic globe drawn on a canvas, as either a field of land dots ' +\n \"(`mode='dots'`) or coastline outlines with a limb ring (`mode='wireframe'`). Use it \" +\n 'as decorative geography — to say \"somewhere in the world\", or to give a connection ' +\n 'state a sense of place — and state the actual location in surrounding copy. It is ' +\n 'not a map: there is no scale, graticule, or labelling, and a position cannot be read ' +\n 'off it. The canvas is always square at `size`; crop the sphere by wrapping it in a ' +\n 'smaller overflow-hidden box.',\n },\n },\n },\n argTypes: {\n mode: {\n control: 'inline-radio',\n options: ['dots', 'wireframe'],\n description: 'Which look to draw: a land-dot field, or coastline outlines with a limb ring.',\n },\n size: { control: { type: 'range', min: 120, max: 480, step: 4 }, description: 'Square canvas edge in px.' },\n zoom: {\n control: { type: 'range', min: 0.5, max: 3, step: 0.05 },\n description: 'How much of the canvas the sphere fills; above 1 the canvas crops it.',\n },\n intensity: {\n control: { type: 'range', min: 0.1, max: 1, step: 0.05 },\n description: \"Scales the geography's opacity, so one globe can serve an active and an idle state.\",\n },\n markers: { ...disabledControl, description: 'Locations to plot; the `active` one gets the breathing glow.' },\n accentColor: { control: 'color', description: 'Marker and glow color. Defaults to the brand accent.' },\n baseColor: { control: 'color', description: 'Dot and coastline color. Defaults to primary text.' },\n centerLatitude: {\n control: { type: 'range', min: -80, max: 80, step: 1 },\n description: 'Latitude faced at rest.',\n },\n centerLongitude: {\n control: { type: 'range', min: -180, max: 180, step: 1 },\n description: 'Longitude faced at rest.',\n },\n spin: { control: 'boolean', description: 'Idle drift; ignored under `prefers-reduced-motion`.' },\n ariaLabel: { control: 'text', description: 'Accessible label; sets `role=\"img\"`.' },\n testId: { control: 'text', description: 'Test selector on the canvas.' },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Default: Story = {\n args: { mode: 'dots', size: 320, markers, ariaLabel: 'Globe showing VPN locations' },\n};\n\nexport const Wireframe: Story = {\n parameters: {\n docs: {\n description: {\n story: 'The quiet look: coastline outlines and the sphere limb, for an inactive or disconnected reading.',\n },\n },\n },\n args: { mode: 'wireframe', size: 320, markers, ariaLabel: 'Globe showing available VPN locations' },\n};\n\nexport const Cropped: Story = {\n parameters: {\n docs: {\n description: {\n story:\n 'How this ships on a dashboard card: `zoom` draws the sphere larger than its canvas so ' +\n 'the canvas crops it and the silhouette stays out of frame. Prefer this over an ' +\n 'oversized canvas in an overflow-hidden wrapper — a canvas wider than its container ' +\n 'still reports an overflowing layout box even when a parent clips it visually, which ' +\n 'reads as a layout defect and trips UI audits.',\n },\n },\n },\n args: { mode: 'dots', size: 150, zoom: 1.75, markers, ariaLabel: 'Globe showing VPN locations' },\n};\n\nexport const Dimmed: Story = {\n parameters: {\n docs: {\n description: {\n story:\n 'A reduced `intensity` for an idle state — the same globe dimmed rather than a different ' +\n 'look, so the change reads as one object receding. Do not go much below this: dot ' +\n 'density compresses toward the limb, so a fainter field leaves only the limb visible and ' +\n 'the sphere starts reading as an arc.',\n },\n },\n },\n args: { mode: 'dots', size: 320, intensity: 0.55, markers, ariaLabel: 'Globe showing VPN locations' },\n};\n\nexport const Unmarked: Story = {\n parameters: { docs: { description: { story: 'Geography only, with no locations plotted.' } } },\n args: { mode: 'dots', size: 320, ariaLabel: 'Globe' },\n};\n\nexport const Static: Story = {\n parameters: {\n docs: { description: { story: '`spin={false}` draws one posed frame and schedules nothing further.' } },\n },\n args: { mode: 'dots', size: 320, markers, spin: false, ariaLabel: 'Globe showing VPN locations' },\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n args: { mode: 'dots', size: 320, markers, ariaLabel: 'Globe showing VPN locations' },\n};\n" }, "links": { "human": "/component-globe", "json": "/data/components/globe.json", "markdown": "/data/components/globe.md", "storybook": "/storybook/?path=/story/cloaked-design-system-visualizations-globe--default" }, "contract_status": "preview", "contract_kind": "source-derived", "approval": "required", "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." }, "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" } }, "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." } ], "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." } }