@lua-ai-global/core
v0.2.0
Published
Shared Lua design tokens, themes, bot engine, and avatar data.
Keywords
Readme
@lua-ai-global/core
Shared design decisions for Lua web and native clients. ESM, tree-shakable, and zero runtime dependencies. No React, no DOM, no CSS files or browser globals. The TypeScript build excludes DOM libraries and ambient platform types.
The root entry exports all four modules. Prefer a subpath when using one module.
/bot/ink and /bot/frame-ticker avoid loading the geometry engine for ink or scheduling alone.
/avatar/cutout provides pure cutout geometry separately from avatar data.
| Export | Contents |
| --- | --- |
| @lua-ai-global/core/tokens | Exact token declarations, light/dark semantic colors, radius, spacing, typography, motion, elevation, and color conversion |
| @lua-ai-global/core/themes | Desktop palette catalog, hue generator, Mono/custom palettes, and Lua brand aurora |
| @lua-ai-global/core/bot | Shapes, expressions, states, frame sampling, identity, ink, and an injectable frame ticker |
| @lua-ai-global/core/avatar | Avatar value types, seed hues, sprite rows and timing, artwork selection, and Google probe URL normalization |
Tokens and themes
tokenDeclarations mirrors every design-token declaration in the @theme,
@theme inline, :root, .dark, and root/host fallback scopes of UI's
src/styles/globals.css. cssTokens.light and .dark merge those declarations
for web consumers. They preserve the original strings, including aliases.
tokens.light and .dark resolve aliases into typed groups. Colors are OKLCH
strings. nativeColorsForMode(mode) converts them to camelCase sRGB hex strings,
including alpha. colorToRgb returns { r, g, b, alpha }; RGB channels use
0–255 and alpha uses 0–1. Conversion clips out-of-gamut sRGB channels.
The stateHover and stateSelected colors mix the foreground into transparent
at 3% and 7%. sidebarStateHover and sidebarStateSelected use the sidebar
foreground at the same strengths. This keeps hover lighter than selection in
both color modes and gives native clients the same interaction colors as CSS.
Dimensions use a 16-unit rem by default. tokensForMode(mode, remSize) accepts
another scale. Typography provides absolute line heights and line-height ratios.
Font families are ordered names; the platform adapter selects and loads fonts.
Durations are milliseconds and easing curves are four-number tuples. Elevation
retains the exact shadow strings; the platform adapter maps them to its shadow API.
tokensForHue and tokensForPalette preserve the desktop { light, dark }
CSS-variable maps. nativeTokensForHue and nativeTokensForPalette return
matching camelCase hex override maps. For a complete native palette, use
nativeColorsForPalette(mode, palette, customHue). It applies overrides before
resolving aliases and tints, just as web variables do.
Unknown palette IDs return null; Mono only overrides dark neutral surfaces.
Color themes tint --border and --input with the palette hue at low chroma.
Light mode uses lightness 0.915 and chroma 0.016. Dark mode uses a 9% border and
a 15% input with chroma 0.05. The palette's chroma scale applies to both values.
Mono keeps zero-chroma borders and inputs.
import { tokens } from "@lua-ai-global/core/tokens";
import { nativeColorsForPalette } from "@lua-ai-global/core/themes";
const colors = nativeColorsForPalette("dark", "lua");
if (!colors) throw new Error("Unknown palette");
const cardStyle = {
backgroundColor: colors.card,
borderRadius: tokens.dark.radius.surface,
padding: tokens.dark.spacing.scale[4],
};Platform adapters
packages/ui imports core through a workspace dependency. It keeps the SVG/DOM
renderer, components, theme hooks, visibility handling, and canvas sampling.
Existing @lua-ai-global/ui/bot, /bot-ink, /frame-ticker, and avatar exports
remain available.
A future native package can sample BotEngine and render its paths with
react-native-svg. It supplies request and cancel functions to
createFrameTicker, and calls setPaused when the app is inactive.
resolveBotInk(colorId, dark) and resolveBotPaper(dark) take the host's theme.
Google photo classification still requires platform-specific image sampling;
googleProbeUrl only normalizes the probe URL.
Native icon renderers import the licensed arrays and IconSvgElement type from
@lua-ai-global/hugeicons/data. That entry has no React or UI imports, including
its declarations. Existing Hugeicons React exports remain unchanged.
Verification
Run pnpm check:tokens at the repository root. The Vitest parity test parses the actual
stylesheet with PostCSS and compares every declaration and key in both directions.
It runs during pnpm lint. Update the TypeScript declarations whenever the CSS
changes; the check never regenerates them automatically.
pnpm --filter @lua-ai-global/core test also checks theme, avatar, ticker, and
color-conversion behavior. The root pnpm build orders core before UI through
the workspace dependency. The package retains the UI package's UNLICENSED status. The vendored bot engine's MIT license is preserved in src/bot/LICENSE.
The package uses the workspace's existing tsup, TypeScript, Vitest, and PostCSS versions.
