Introduction

A visual-design decision usually dies in a document. Someone writes "warm, editorial, not corporate," three people picture three different things, and the build pass guesses. Loupe replaces that paragraph with something you can click.

You describe the decision as a typed config. Loupe turns each choice — an image crop, a color palette, a type specimen, a motion feel, a layout mock — into a real, rendered option tile. Locking a tile recomposes a sticky live preview and keeps a deterministic export brief in sync. That brief, markdown and JSON, is the ground truth the next build pass consumes — whether the builder is a person or an agent.

typed config  →  rendered option tiles  →  lock picks  →  deterministic export brief

Lock a tile below and watch the preview and the brief move with it. This is the real React adapter, themed with the Night Atlas tokens — nothing is mocked.

The wedge

Most "design decision" tooling makes you choose between two bad options: a Figma board nobody can diff, or a text log nobody can see. Loupe sits exactly between them.

• It is seen, not described. Every option renders the actual thing — a real crop of a real board, a real type family at a real weight. The decision-maker sees what they are choosing.
• It is the contract, not a screenshot of one. The export brief is derived from the same selections that drive the preview, so the preview and the brief can never drift. Hand the brief to a build pass and it is exact.
• It is agent-native. The config is a Zod schema; toJsonSchema() emits the exact contract an agent fills. An agent can author a decision-lock, screenshot-verify it, and export the brief without a human writing TypeScript.
• It is portable. The generator produces one self-contained index.html — JS and CSS inlined, assets copied beside it — that runs under file:// or any static host with zero runtime dependency on these packages.

Install and use

There are two ways to consume Loupe, and they cost very differently. Default to the first.

# from the monorepo, in a dir that can resolve @lucentive-labs/loupe-generator
tsx generate.ts          # → dist/index.html + dist/assets/* (portable)

pnpm add @lucentive-labs/loupe-react @lucentive-labs/loupe-dom @lucentive-labs/loupe-schema

import { Loupe } from "@lucentive-labs/loupe-react";
import "@lucentive-labs/loupe-dom/styles.css"; // import once, app-wide
import { config } from "./loupe.config";

export default function Page() {
  return <Loupe config={config} />;
}

The packages

Loupe is a small set of layers. The headless core holds all the logic; everything above it is a thin renderer.

Where to go next