Sculpted

Sculpted is a development-only inspector for editing supported Panda CSS styles in the browser and writing those edits back to source.

It is useful when you want to validate the inspect -> preview -> save loop in a Vite + React or Preact + Panda CSS app. Source shapes that cannot be written safely are shown as read-only or rejected instead of guessed.

Supported Scope

Use Sculpted only in a project you have under version control. The dev server can write source files when you click Save.

Sculpted supports:

• Vite development server only;
• React and Preact applications using Panda CSS;
• static local Panda css({ ... }) object literals;
• existing literal primitive values such as strings, numbers, booleans, and null;
• nested literal paths when the source object remains directly patchable;
• set edits to existing source paths;
• opt-in TSRX support for the same existing-literal css({ ... }) source shape.

Sculpted does not edit:

• production inspection or writeback;
• recipes, patterns, JSX style props, or cva();
• variable style object resolution;
• adding, deleting, or renaming style properties;
• converting computed CSS values back to design tokens;
• broad property-specific editors;
• inline source creation for TSRX.

Batched saves are prepared before writing. When a multi-file batch write fails after an earlier file was written, Sculpted attempts to restore the earlier file before reporting the save failure.

Install

pnpm add -D sculpted

Sculpted is intended as a dev dependency. It injects no inspector runtime during production builds.

Vite Setup

Use the sculpted Vite plugin from the sculpted/vite subpath:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { sculpted } from 'sculpted/vite'

export default defineConfig({
  plugins: [sculpted(), react()],
})

Preact projects use the same plugin:

// vite.config.ts
import { defineConfig } from 'vite'
import preact from '@preact/preset-vite'
import { sculpted } from 'sculpted/vite'

export default defineConfig({
  plugins: [sculpted(), preact()],
})

In development, the plugin instruments supported Panda css({ ... }) calls, injects the browser runtime and inspector panel, serves inspector metadata endpoints, and exposes source writeback routes for supported saves.

In production builds, the plugin is dark: no runtime script is injected, no inspector metadata is added, and no manifest or writeback route is registered.

React Router 7 framework-mode apps need one extra development-only runtime script in the root document because React Router renders HTML outside Vite's index.html transform. See React Router 7 framework mode.

See Vite plugin options for the full option surface, defaults, and endpoint configuration.

Try A Supported Edit

Start your Vite dev server, open the app in a browser, and inspect an element whose class comes from a static local Panda css({ ... }) call:

import { css } from '../styled-system/css'

export function Card() {
  return (
    <section
      className={css({
        backgroundColor: 'white',
        color: 'gray.900',
        padding: '24px',
      })}
    >
      Body
    </section>
  )
}

Preact projects can use the same supported css({ ... }) authoring shape with class.

The inspector can preview and save changes to existing literal values such as color: 'gray.900' or padding: '24px'. It will not add a new property, delete a property, or resolve styles hidden behind variables or spreads.

If an element has supported and unsupported Panda contributors, Sculpted should surface that state instead of pretending the full cascade can be edited safely.

Documentation

• Vite plugin options covers setup, defaults, and dev/prod behavior.
• Source writeback covers the safety model, supported edit shapes, and common failure modes.
• Source syntax adapters covers opt-in TSRX support.

Troubleshooting

No editable entries appear:

• Confirm the app is running through the Vite dev server, not a production build.
• Confirm the file is included by the plugin include patterns.
• Confirm the element uses a local static css({ ... }) object literal imported from your Panda styled-system/css path.
• In React Router 7 framework mode, confirm the root document includes the development-only /@sculpted/runtime script.
• Open /@sculpted/manifest while the dev server is running and check whether entries exist.

The inspector shows a target as read-only:

• Check for variable style objects, object spreads, computed keys, dynamic values, recipes, patterns, cva(), or JSX style props.
• For TSRX, check that the file uses supported TSRX component syntax and that sourceSyntax from sculpted/tsrx is configured.

Save fails:

• Check whether the source changed after the manifest was generated. Restarting or waiting for Vite to refresh the manifest may clear stale-source failures.
• Check for duplicate keys or unsupported parent object shapes around the edited path.
• For parser errors, fix the source syntax first; Sculpted will not write into a file it cannot parse safely.

Production build has no inspector:

• This is expected. Sculpted is development-only and should be dark in production output.