@hua-labs/dot

v0.1.0

Local

Cross-platform

Pre-release

Cross-platform style protocol from utility tokens to web CSSProperties and React Native styles.

1501tests passing

3platform targets

90%+Tailwind parity

Waves 0–3 are complete. The package is dogfooded across HUA apps and docs. The API is stable enough for dependent packages to converge on the same style contract. Public release is gated on AOT extraction tooling (Wave 4).

Key capabilities

One token language

Use one utility-style vocabulary and resolve it to web CSSProperties or React Native style objects. 90%+ Tailwind parity out of the box.

State-aware style maps

Use dotMap() for hover, focus, active, and breakpoint-aware state buckets without string juggling. Responsive cascade is mobile-first.

Web + React Native + Flutter

Three platform targets from a single token string. Import from @hua-labs/dot/native for RN, or pass target: 'flutter' for structured Flutter recipes.

Gradient & shadow composition

from-*/via-*/to-* stops compose into linear-gradient(). shadow-* and ring-* layers compose into a single boxShadow value with correct ordering.

Config + variants

Override tokens with createDotConfig(), merge class-like input with dotCx(), and define typed recipe-style variants with dotVariants().

Capability introspection

dotExplain() returns both resolved styles and a capability report — listing which properties are dropped, approximated, or unsupported on the target.

Implementation waves

✓

Wave 0— Foundation

Complete

Parser, resolver, cache, config, web adapter, dark mode, responsive cascade, !important, arbitrary values

✓

Wave 1— Flutter adapter

Complete

Full Flutter recipe output: layout, flexbox, sizing, color, typography, border, shadow, transform, gradient

✓

Wave 2— Extended families

Complete

Grid, filter, backdrop-filter, animation, transition, object-fit, scroll, table, list, word-break, divide, isolation

✓

Wave 3— Config & variants hardening

Complete

dotVariants(), dotExplain(), capability matrix, value-level overrides, warnUnknown, remBase

○

Wave 4— AOT extraction

Planned

Static extraction companion package (@hua-labs/dot-extract) — build-time token analysis, zero-runtime path

○

Wave 5— Advanced

Planned

Custom breakpoints, element filters, drop-shadow, CSS @layer, server-component SSR path

빠른 시작

1. Web usage

tsx

import { dot, dotCx } from '@hua-labs/dot';

function Card() {
  return (
    <div
      style={dot('rounded-xl border border-border bg-card p-6 shadow-sm')}
      className={dotCx('transition-colors', 'hover:bg-secondary/40')}
    >
      HUA card
    </div>
  );
}

2. State maps

typescript

import { dotMap } from '@hua-labs/dot';

const button = dotMap(
  'rounded-lg px-4 py-2 bg-primary-500 text-white hover:bg-primary-600 focus:ring-2'
);

// Apply in JSX via event handlers
<button
  style={isHovered ? { ...button.base, ...button.hover } : button.base}
  onMouseEnter={() => setIsHovered(true)}
  onMouseLeave={() => setIsHovered(false)}
/>

3. React Native entrypoint

typescript

import { dot, dotMap } from '@hua-labs/dot/native';

const cardStyle = dot('rounded-xl bg-white p-4 shadow-sm');
const pressableStyles = dotMap('bg-primary-500 active:bg-primary-600');

// Or rely on the react-native export condition:
// import { dot } from '@hua-labs/dot';

4. Flutter adapter

typescript

import { dot } from '@hua-labs/dot';

// Returns a structured FlutterRecipe object — not CSSProperties
const recipe = dot('p-4 rounded-xl bg-primary-500 shadow-md', { target: 'flutter' });
// → {
//   decoration: { color: 0xFF3b82f6, borderRadius: BorderRadius.circular(12), ... },
//   padding: EdgeInsets.all(16),
//   boxShadows: [BoxShadow(...)],
// }

5. Gradient & shadow composition

typescript

import { dot } from '@hua-labs/dot';

// Gradient stops compose into backgroundImage
const gradient = dot('bg-gradient-to-r from-sky-500 to-indigo-500');
// → { backgroundImage: 'linear-gradient(to right, #0ea5e9, #6366f1)' }

// Ring + shadow layers compose in order (ring first, Tailwind convention)
const elevated = dot('ring-2 ring-sky-500 shadow-lg');
// → { boxShadow: '0 0 0 2px #0ea5e9, 0 10px 15px -3px ...' }

6. Capability introspection

typescript

import { dotExplain } from '@hua-labs/dot';

const { styles, report } = dotExplain('p-4 blur-md grid grid-cols-3', { target: 'native' });
// report → {
//   _dropped: ['filter', 'gridTemplateColumns'],
//   _approximated: [],
//   _capabilities: { filter: 'unsupported', grid: 'unsupported' }
// }

7. Config + variants

typescript

import { createDotConfig, dotVariants } from '@hua-labs/dot';

createDotConfig({
  theme: {
    colors: {
      brand: { 500: '#1F6FEB' },
    },
  },
});

const badge = dotVariants({
  base: 'inline-flex rounded-full px-2 py-1 text-xs font-medium',
  variants: {
    tone: {
      neutral: 'bg-gray-100 text-gray-900',
      brand: 'bg-brand-500 text-white',
    },
  },
});

badge({ tone: 'brand' });

Core API surface

dot(input, options?)

Resolve utility tokens into a flat style object. Overloaded for web (CSSProperties), native (RNStyleObject), and Flutter (FlutterRecipe) targets.

dotMap(input, options?)

Resolve the same token string into base plus state-specific buckets (hover, focus, active, focus-visible, focus-within, disabled).

dotExplain(input, options?)

Returns resolved styles plus a capability report listing dropped, approximated, and limited properties for the target platform.

createDotConfig(config)

Override tokens, breakpoints, rem base, runtime target, cache size, and warnUnknown. Applies globally (module-level singleton).

clearDotCache()

Reset token and input caches when theme or config changes at runtime.

dotCx(...inputs)

Compose multiple utility strings into one, filtering falsy values. Useful for conditional class merging before passing to dot().

dotVariants(config)

Define typed recipe-style variants on top of the same dot vocabulary. A CVA-compatible API that resolves to style objects instead of class strings.

adaptFlutter / adaptNative / adaptWeb

Low-level platform adapters exposed for direct usage. Usually consumed via the target option on dot() rather than directly.

Platform capability matrix

Family	Web	React Native	Flutter
spacing / color / typography	native	native	native
flexbox / border / borderRadius	native	native	native
shadow	native	approximate	native
gradient	native	unsupported	recipe-only
grid	native	unsupported	recipe-only
filter / backdrop-filter	native	unsupported	plugin-backed
transition / animation	native	unsupported	unsupported
transform	native	native	native
positioning	native	native	recipe-only

@hua-labs/dot

Key capabilities

One token language

State-aware style maps

Web + React Native + Flutter

Gradient & shadow composition

Config + variants

Capability introspection

Implementation waves

빠른 시작

1. Web usage

2. State maps

3. React Native entrypoint

4. Flutter adapter

5. Gradient & shadow composition

6. Capability introspection

7. Config + variants

Core API surface

Platform capability matrix

관련 패키지