{ "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", "contract_status": "preview", "contract_kind": "source-derived", "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." }, "approval": "required", "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_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" }, "specification": { "$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": [] }, "specification_source": "packages/design-system/src/components/visualizations/Globe/Globe.spec.json", "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." }, "links": { "human": "/component-globe", "json": "/data/visual/components/globe.json", "storybook": "/storybook/?path=/story/cloaked-design-system-visualizations-globe--default" } }