npm package: @smoothie-framework/ui
Description: Smoothie UI runtime package - JSX components, signals, rendering, and standalone theme integration
Author: Smoothie Framework
Latest version: 0.0.2

# @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

```tsx
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

```tsx
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`):

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

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

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

```bash
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`