@digo-labs/common

The foundation of every @digo-labs/* package: shared utilities, types, Zod schemas, the AWS RE26 brand constants, the curated icon set, React hooks (@digo-labs/common/hooks), and the global CSS (tokens, fonts, typo-* and cs-* utilities).

How to read this. This guide ships with the package, so it matches the version you have installed; the site describes the latest release. The types in node_modules/@digo-labs/common/dist/*.d.ts are exact and win if they disagree with it. Deeper pages: https://design.digo-labs.com/docs/guide/package-common.

npm install @digo-labs/common

Utilities

import { cn, tryCatch, CommonHelpers } from '@digo-labs/common';

const [data, error] = await tryCatch(fetch(url).then(r => r.json()));
if (error) return;

<div className={cn('typo-label typo-3 text-neutral-11', isActive && 'text-accent-11', className)} />

• tryCatch<T, E = Error>(promise): Promise<Result<T, E>>: turns a promise into a [data, null] | [null, error] tuple. It takes a promise, not a function.
• cn(...inputs): clsx plus tailwind-merge, extended so typo-1…typo-18, typo-weight-* and typo-header|label|body|code merge correctly. Use it for every className.
• Static helper classes (call as CommonHelpers.method()):
  • CommonHelpers: numbers (clamp, lerp, lerpArray, getRandomInteger, createRandom(seed), formatNumberTwoDigits), colour (hexToRgb, hexToRgbArray, rgbArrayToHex, getLuminance), CSS variables (getCssVariable, setCssVariable), files and images (getImagePayloadFromFile, getImagePayloadFromUrl, getFileFromImagePayload, getFileFromUrl, compressImage, preloadImage(s), removeBackground, openFileSelector, downloadURI, downloadCsvFromUrl), clipboard (copyToClipboard, getTextFromClipboard), misc (generateUUID, getTimeFormatted, getLastUpdated, getUniqueIdInList, setTabName, scrollToBottom).
  • StringHelpers (lz-string compress*/decompress*, blobToBase64, base64ToBlob, hashCode, getFirstLetter).
  • LocalStorage / SessionStorage: setValue<T>(key, value) and loadValue<T>(key, defaultValue), JSON in and out.
  • IconHelpers (getIcon, getCategories, getByCategory) over the curated icon set; CuratedIcons is the union of icon names.
  • Platform helpers used by @digo-labs/services and the backend: AppConfigHelpers, AuthTierHelpers, StorageAccessHelpers, RealtimeHelpers. Apps rarely call these directly.

Types and schemas

• Shared types: Result, Time, Size, Position, Bounds, Vector3, Side, Align, Alignment, Orientation, Breakpoint, GradientStop, Random.
• Auth and access: AuthTier ('public' | 'user' | 'org' | 'admin'), AUTH_PROJECTS, AuthProject, TableAccessRule, StorageRules, ChannelRules.
• Common tables: StyleRecord (the shared styles table).
• Zod schemas shared with the backend, each with its inferred type: primitives (filePayloadSchema / FilePayload, imagePayloadSchema / ImagePayload, …), AI (textBodySchema, imageGenerateBodySchema, videoGenerateBodySchema, audioSpeechBodySchema, …), AI jobs (aiJobCreateBodySchema, AiJobStatus, …), devices, instances (InstanceRecord, instanceCreateBodySchema, …), storage, websocket, DMX. Search the .d.ts files for the exact name.
• Instances: InstanceHelpers (getScope, parseScope, getStoragePrefix, toStoragePath, fromStoragePath, isSlug), DEFAULT_INSTANCE ('main'), DIGO_INSTANCE_HEADER. AppConfigHelpers.getInstanceFromHost('jon.tattoo-studio.digo-labs.com') is 'jon'.
• Websocket types: WebsocketHubMessage, WebsocketConnectionConfig, WebsocketClientEvent, WebSocketHubEvent.
• Constants: BREAKPOINTS, BACKEND_URL, WS_URL, FILES_URL, AWS_DEFAULT_REGION. CDN asset URLs: IMAGES, VIDEOS, MODELS, FONT_FACES.

React hooks: @digo-labs/common/hooks

A separate entry, so servers that import @digo-labs/common never load React or motion.

• useElementSize<T>(): { ref, width, height } of an element, kept current with a ResizeObserver.
• useMediaQuery(query): whether a media query matches. Takes a breakpoint ('md', 'max-md', 'sm:max-lg'), { min, max, pointer } or a raw query. useIsMobile() is useMediaQuery('max-md').
• useMotionReduced(): true when the system asks for reduced motion or a <MotionConfig reducedMotion="always"> from motion/react wraps the component.

AWS RE26 brand constants

For AWS event apps only. In those apps the brand is strict: these values are the reference, never redraw or re-pick them. The components that use them are in @digo-labs/aws.

• AWS_PALETTE: the brand colours (orange, yellow, pink, purple, blue, green, each with Light, Muted, Dark variants). Type AwsPaletteColor.
• AWS_DURATIONS (enter, beat, hold, hop, in seconds) and AWS_EASINGS (expo, circle, as cubic-bezier tuples), AWS_TRANSITIONS (enter on circle, move and shift on expo) and AWS_INSTANT (a zero-duration transition, for reduced motion).
• Glyphs: AWS_GLYPHS (SVG paths), AWS_GLYPH_VIEWBOX, AWS_GLYPH_FAMILIES (scale, connect, spark, pivot, stages 1 to 3), AWS_GLYPH_FAMILY_NAMES and AWS_GLYPH_STAGES (the families and stages as lists).
• AWS_SHAPE_ANIMATIONS: the Lottie file of each glyph family on the CDN.
• Layout and motion data: AWS_UNIT (base block size, 48), AWS_BLOCK_GROUPS, AWS_PATTERNS, AWS_PATTERN_DEFAULTS, AWS_TEXTURE_DEFAULTS, AWS_TEXTURE_MOTION.
• AwsHelpers.shape | block | group | pattern | texture: the maths behind the components (for example AwsHelpers.pattern.compile(data, loop)).

Brand rules and visuals: https://design.digo-labs.com/library/aws/aws-foundations

CSS: @digo-labs/common/index.css

A Tailwind v4 stylesheet. It defines:

• Default tokens, so the utilities work without a theme preset: colour scales neutral, accent, error, success, warning, info (steps 1 to 12, plus alpha *A-1…*A-12), shadows-*, --radius and rounded-* steps, shadow-xs|s|m|l|xl, and the typography variables (--typo-header-font, --typo-body-weight, …, --typo-scale-factor).
• Font families as font-* utilities (font-geist, font-geist-mono, font-ember-display, …) with @font-face rules loading from cdn.digo-labs.com. The AWS Ember Modern faces sit in @digo-labs/common/aws-fonts.css, which this file imports and @digo-labs/aws/styles.css imports too.
• Typography utilities: typo-header, typo-label, typo-body, typo-code (family, weight, tracking, leading), typo-1…typo-18 (size, scaled by --typo-scale-factor), typo-weight-100…typo-weight-900.
• Layout and state utilities: flex-col-center, flex-row-center, cs-focus, cs-disabled, cs-invalid, cs-transition, cs-page-container, cs-page-grid, cs-dots, cs-stripes, no-scrollbar, and more (search @utility in the file).
• Icons through @iconify/tailwind4 (icon-[set--name] classes) and tailwindcss-animate.

If the app also uses @digo-labs/ui, import @digo-labs/ui/styles.css instead: it already includes this file.

@import 'tailwindcss';
@import '@digo-labs/common/index.css';

Gotchas

• Import tailwindcss before this file: it uses @theme and @utility, which only work inside a Tailwind v4 build.
• The default tokens are a dark scale (neutral-1 is #111111, neutral-12 is #eeeeee) and the base layer paints body with them. Without a preset the app is dark; a light mode needs a preset from @digo-labs/ui.
• The base layer puts transition-colors duration-200 on every element (*). Colour changes you drive yourself (canvas overlays, frame-accurate animations) can lag by 200 ms; override with transition-none where it matters.
• Icon names that are not in the curated set pass straight through as a class. A raw icon-[mdi--home] must appear literally in the app source so Tailwind generates it.
• CommonHelpers.removeBackground loads @imgly/background-removal (ONNX models) on first call; it is heavy, so call it only on demand.