Skip to content
Charming Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Charming design guide: read before you write the UI

The ui field is one JavaScript program. Charming provides <div id="app"></div>, a Tailwind v3-compatible runtime, and a default theme. Your code fills #app.

Sandbox

  • Use inline UI instead of alert, confirm, or prompt. Those calls do nothing.
  • Prevent native form submission and handle it in JavaScript.
  • Do not add external scripts or CDN imports.
  • Call the app backend through window.charming.
  • Store lasting data through backend operations that use env.storage. Do not use browser storage for data that must work in chat clients or across devices.

Read https://charm.ing/docs/llms-full.txt before using browser capabilities, network access, or secrets.

Layout

  • Fill the viewport. Do not wrap the whole app in a narrow max-w-* container.
  • Limit line length only for long text.
  • Make the main action clear on first load.
  • Use a fitting layout and palette. Do not default every app to a heading, input, button, and empty list.
  • Avoid empty settings pages, generic “My App” headings, and fake account fields.

Use the vanilla DOM and Tailwind classes unless the task needs a small library. If you need one, inline its UMD or IIFE build.

Backend calls

window.charming.api(id) returns the operation value. It throws CharmingOperationError when an operation fails.

const api = window.charming.api("todo"); // pass manifest.id, not the UUID
const todos = await api.list();
await api.add({ text: "..." });

Credentials attach automatically. Do not manage tokens in the UI.

Access

Use window.charming.viewer.can(op) to hide or disable actions a read-only viewer cannot run.

const { viewer } = window.charming;
if (!viewer.can("addTodo")) {
  addButton.disabled = true;
}

Treat viewer.can(op) as a UI hint, not an auth check. The server enforces access. Catch forbidden and forbidden_write errors and show a read-only state.

Use window.charming.user for optional display data. Never use it to authorize an action. Read https://charm.ing/docs/technical-reference/authentication.md for roles and sign-in behavior.

Was this page helpful?