@smoothie-framework/ui

JSX-first UI framework for Smoothie with fine-grained reactivity and a patch-based DOM renderer.

What this package provides

• Signals and reactive collections (signal, computed, effect, signalArray, signalObject, ...)
• Built-in UI components (layout, typography, interactive, form, feedback)
• Patch pipeline renderer (createPatchEmitter + createDOMPatchApplier)
• Theme integration powered by @smoothie-framework/ui-core
• Custom component authoring (extendComponent, defineComponent)
• Legacy compatibility authoring (defineRecipe, deprecated for new usage)

Contract authority

docs/decisions/adr-006-ui-styling-architecture-execution.md is the normative decision source for FW16 styling and authoring contracts.

Documentation model note:

• Final architecture docs live under docs/architecture/.
• Requirement and objective specs live under docs/spec/.
• Execution plans and closed records live under docs/PRDs/.
• Docs taxonomy and lifecycle rules are defined in docs/documentation-model.md.
• Canonical UI toolkit strategic docs live in docs/spec/ui-toolkit/.
• Canonical implementation-aware UI docs live in docs/architecture/ui-toolkit/.

Quick start

import { render, Stack, Text, Button, signal, Memo } from '@smoothie-framework/ui';

function Counter() {
  const count = signal(0);

  return (
    <Stack gap={4} align="center">
      <Text>Count: <Memo>{() => count()}</Memo></Text>
      <Button onClick={() => count.update(v => v + 1)}>Increment</Button>
    </Stack>
  );
}

render(Counter, document.getElementById('app')!);

Theme usage

import { ThemeProvider, createTheme } from '@smoothie-framework/ui';

const theme = createTheme({
  tokens: {
    'button.primary.bg': '{colors.blue.600}',
    'button.primary.hover.bg': '{colors.blue.700}',
  },
});

<ThemeProvider theme={theme}>
  <App />
</ThemeProvider>

Theme compilation

Theme customization is class-first and compile-oriented:

• createTheme(...) (internally backed by extendTheme in @smoothie-framework/ui-core) produces a normalized theme object.
• Theme CSS assets are generated from that theme:
  • styles/variables.css
  • styles/component-variables.css
• Component classes in styles/components.css consume those variables.
• Scope selectors (:root, data-smth-theme, data-smth-brand) remain the durable theming contract, but the current standalone ui runtime still performs CSS-variable sync for the createColorMode(...) path.

For the canonical UI docs split, start with docs/architecture/ui-toolkit/readme.md.

Canonical theme docs:

• docs/spec/ui-toolkit/styling-contract.md
• docs/architecture/ui-toolkit/theme-compilation.md
• docs/architecture/ui-toolkit/theming-guide.md

Component management model

@smoothie-framework/ui component creation has two perspectives:

• framework-owned core and compound primitives
• app-level extension and full custom authoring

Authoring model:

• extendComponent for extending existing framework components
• defineComponent for fully custom component contracts

Legacy compatibility note:

• defineRecipe remains available for compatibility only and should not be used for new authoring work.

Canonical component-model docs:

• docs/architecture/ui-toolkit/component-model.md
• docs/architecture/ui-toolkit/component-authoring-guide.md
• docs/architecture/ui-toolkit/packages/ui.md

Import strategy

• @smoothie-framework/ui: ergonomic main entrypoint
• @smoothie-framework/ui/state: state/reactivity primitives
• @smoothie-framework/ui/components: component-only imports
• @smoothie-framework/ui/control: control flow primitives (Show, For, Switch, Match, Memo)
• @smoothie-framework/ui/render: render and patch internals for advanced integrations
• @smoothie-framework/ui/authoring: component authoring helpers
• @smoothie-framework/ui/vite: Vite dev plugin for automatic stylesheet regeneration
• @smoothie-framework/ui/scanner: build-time manifest scanner (Node environment)
• @smoothie-framework/ui/compiler: build-time JIT class compiler for components.css
• @smoothie-framework/ui/pipeline: style pipeline orchestration primitives
• @smoothie-framework/ui/theme: theme helpers and ThemeProvider

API Matrix

| Import | Stability | Use for | | --- | --- | --- | | @smoothie-framework/ui | Stable | Application code: components, state, render, theming | | @smoothie-framework/ui/state | Stable | Reactivity primitives in isolation (signal, computed, collections) | | @smoothie-framework/ui/components | Stable | Tree-shakable component-only imports | | @smoothie-framework/ui/control | Stable | Control-flow nodes (Show, For, Switch, Match, Memo) | | @smoothie-framework/ui/theme | Stable | Theme lifecycle (createTheme, ThemeProvider, setTheme) | | @smoothie-framework/ui/authoring | Stable | extendComponent, defineComponent, and legacy defineRecipe compatibility | | @smoothie-framework/ui/vite | Advanced | Compatibility wrapper over @smoothie-framework/ui-styles/vite | | @smoothie-framework/ui/render | Advanced | Low-level render and patch pipeline integration | | @smoothie-framework/ui/scanner | Advanced | Compatibility wrapper over @smoothie-framework/ui-styles/scanner | | @smoothie-framework/ui/compiler | Advanced | Compatibility wrapper over @smoothie-framework/ui-styles/compiler | | @smoothie-framework/ui/pipeline | Advanced | Compatibility wrapper over @smoothie-framework/ui-styles/pipeline | | @smoothie-framework/ui/styles | Stable asset | Canonical generated bundle (index.css) | | @smoothie-framework/ui/styles/variables | Stable asset | Primitive token variables (variables.css) | | @smoothie-framework/ui/styles/component-variables | Stable asset | Theme token aliases (component-variables.css) | | @smoothie-framework/ui/styles/components | Stable asset | Recipe classes (components.css) |

For practical end-to-end examples, use:

• examples/hello-ui-components/
• examples/hello-ui-reactive/
• examples/hello-fullstack/

@smoothie-framework/ui owns the standalone runtime surface: components, signals, rendering, theme application, and authoring ergonomics. Styling scanner/compiler/pipeline behavior now lives in @smoothie-framework/ui-styles, with the ui advanced styling entry points kept as compatibility wrappers during the convergence window.

Style tooling controls

Both wrapper entry points expose scanner gate controls and theme compilation minification so app teams can keep scenario behavior explicit.

Vite plugin (@smoothie-framework/ui/vite):

import { smoothieUiStylesPlugin } from '@smoothie-framework/ui/vite';

smoothieUiStylesPlugin({
  scenario: 'app-runtime',
  componentsMode: 'jit',
  scannerGateMode: 'strict',
  themeCompilation: {
    minify: false,
  },
});

Script wrapper (scripts/generate-styles.ts):

bun run scripts/generate-styles.ts \
  --scenario app-runtime \
  --mode jit \
  --scanner-gate-mode strict \
  --theme-minify true

Environment equivalents:

• SMTH_UI_STYLES_SCANNER_GATE_MODE=off|warn|strict
• SMTH_UI_STYLES_THEME_MINIFY=true|false

Wrapper parity matrix:

| Capability | Vite plugin | Script CLI | Script env | | --- | --- | --- | --- | | Scanner gate mode | scannerGateMode | --scanner-gate-mode off|warn|strict | SMTH_UI_STYLES_SCANNER_GATE_MODE | | Theme minify | themeCompilation.minify | --theme-minify true|false | SMTH_UI_STYLES_THEME_MINIFY |

Both wrapper entry points log an effective settings line (scenario, components-mode, scanner-gate) before writing artifacts so CI/local runs are traceable and deterministic.

Styling Strategy

@smoothie-framework/ui adopts a class-first styling policy:

• Finite semantic props use JIT-generated classes.
• Finite token props use JIT-generated atomic utility classes.
• Arbitrary values use JIT-generated utility classes with direct CSS values.
• Target architecture: responsive props use object syntax ({ base, sm, md, lg, xl, '2xl' }) and breakpoint-prefixed classes (md:smth-gap-4).
• Current status: responsive object props are not fully implemented across the current runtime and type surface.
• style remains an explicit escape hatch merged last.

This keeps production styling zero-runtime and predictable while preserving flexibility for open-ended values.

• Canonical UI docs map: docs/architecture/ui-toolkit/readme.md
• Styling contract: docs/spec/ui-toolkit/styling-contract.md
• Styling architecture: docs/architecture/ui-toolkit/styling-architecture.md
• Theme compilation: docs/architecture/ui-toolkit/theme-compilation.md
• Component model: docs/architecture/ui-toolkit/component-model.md