# Domphy

> The AI-friendly UI framework. `@domphy/core` is the runtime (reactivity, rendering, CSS-in-JS, SSR). `@domphy/theme` provides design tokens. `@domphy/ui` ships 74 patches that customize native HTML tags — no components, no JSX, no virtual DOM. Built to be **learnable by AI in-context** (this file) and **self-correcting** via `@domphy/doctor`, so agents write correct Domphy despite little training data.

A **patch** is a function returning a `PartialElement`: a stateless descriptor applied to a host element via the `$` property. Patches carry no rendering lifecycle, own no state, and create no DOM boundary. Compose by listing multiple patches; the runtime merges them on the native element.

## Why this is the AI-friendly framework

- **One spec, in context.** The whole API is learnable from this file (`llms.txt`) or `AGENTS.md` — no large training corpus needed.
- **Self-correcting.** `@domphy/doctor` (`diagnose`/`validate`) flags non-idiomatic output; feed the report back and the model fixes itself.
- **Machine-readable.** `manifest.json` indexes every package + patch (host tag, props schema, example); `tones.json` lists valid tones + theme colors; the `@domphy/mcp` server exposes patches, packages, rules, tones, the doctor (incl. `domphy_fix`), AND your app's own blocks as tools.
- **Scales to large codebases.** An app-block registry (`app-manifest.json`) + the MCP `domphy_list_app_blocks`/`domphy_get_app_block` tools let an agent discover the blocks an app already has instead of re-creating them.

## Rules for code generation

- Build UIs as plain objects keyed by HTML tag (e.g. `{ button: "Click", $: [button()] }`).
- Apply patches via `$`. Never wrap a native tag in a component abstraction.
- **Never inline typography styles** — `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFamily`, `textDecoration`, `color` in `style:` are ALL forbidden. Use patches instead:

  | You want | Use patch | Example |
  |---|---|---|
  | small / secondary / caption / label / helper text | `small()` | `{ span: "hint", $: [small()] }` |
  | body / paragraph text | `paragraph()` | `{ p: "body copy", $: [paragraph()] }` |
  | heading / title | `heading()` | `{ h2: "Title", $: [heading()] }` |
  | bold / emphasis | `strong()` | `{ strong: "bold", $: [strong()] }` |
  | inline code | `code()` | `{ code: "fn()", $: [code()] }` |
  | link | `link()` | `{ a: "click", href: "...", $: [link()] }` |
  | colored text (error/warn/etc) | patch `color` prop | `{ span: "err", $: [small({ color: "error" })] }` |
  | any literal hex/rgb color | `themeColor()` | `color: (l) => themeColor(l, "base", "error")` |

  Remove `fontFamily` entirely — the theme owns the font stack.
- **Forms use `@domphy/form`** — `createForm` from `@domphy/form/domphy`; bind inputs with `value: (l) => field.value(l)` + `onInput: (e) => field.handleChange(e.target.value)`. The old ui `form()`/`field()` patches and `FormState`/`FieldState` were REMOVED; only the layout patch `formGroup()` remains in `@domphy/ui`.
- Reactive content/attributes use `(listener) => state.get(listener)`. A controlled input (value bound to a state you also `.set()` in `onInput`) is safe. For derived values prefer `computed(fn)` (lazy + cached); side-effects use `effect(fn)`; group disposal with `effectScope()`; coalesce writes with `batch(fn)`. In tests/imperative code, `flushSync()` drains pending reactivity synchronously so the DOM reflects a `.set()` immediately.
- **Data/logic packages are 1-1 TanStack core ports + a Domphy adapter at the `/domphy` subpath** (`@domphy/core` is a peer dep): `createQuery`/`createMutation`/`createInfiniteQuery` (`@domphy/query/domphy`), `createDomphyTable` (`@domphy/table/domphy`), `createVirtualizer` (`@domphy/virtual/domphy`), `createForm` (`@domphy/form/domphy`), `createRouter`/`createRoute` (`@domphy/router`). Drag & drop: `dragDrop()` (`@domphy/dnd`). Animation: the `motion()` patch (`@domphy/ui`). Next-style app framework: `@domphy/app`.
- **Self-check generated code with `@domphy/doctor`**: `diagnose(app)` / `validate(app)` + `format(...)` reports `inline-typography` (fontSize/lineHeight/fontWeight/letterSpacing/fontFamily/textDecoration literals — use patches) / `raw-theme-value` (literal hex/rgb colors — hint gives nearest `themeColor()` via CIELAB/LCH match powered by `@domphy/palette`) / `raw-spacing-value` (literal rem/em/px spacing — use `themeSpacing(n)`) / `unknown-tone` / `void-content` / `missing-_key` / `duplicate-_key` / `unstable-_key` / `unknown-tag` — fix what it lists before finishing (`fix(app)` auto-applies the lossless ones).
- Read the per-patch / per-package doc before using one you haven't used before. Each has its own prop contract.

## Getting started

- Scaffold a project: `npm create domphy@latest <dir>` — a runnable Vite + TS starter (themeApply + sample patches + AGENTS.md).
- [5-minute quickstart](https://www.domphy.com/docs/quickstart): install, hello world, patches, reactive state, forms
- [Full docs index](https://www.domphy.com/docs/): every package
- [Building with AI](https://www.domphy.com/docs/ai): per-tool setup (Claude Code, Cursor, Copilot, …)

## Core runtime (`@domphy/core`)

- [Syntax](https://www.domphy.com/docs/core/syntax): object shape, `$`, content, event handlers, attribute keys
- [Reactivity](https://www.domphy.com/docs/core/reactivity): `toState`, `state.get(listener)`, `RecordState`, `computed`, `effect`, `effectScope`, `batch`, `untrack`, `flushSync`
- [Lifecycle](https://www.domphy.com/docs/core/lifecycle): `_onSchedule`, `_onInsert`, `_onMount`, `_onBeforeRemove`, `_onRemove`
- [Portal](https://www.domphy.com/docs/core/portal): render into arbitrary containers
- [SSR](https://www.domphy.com/docs/core/ssr): server rendering + hydration model

## Theme (`@domphy/theme`)

- [Setup](https://www.domphy.com/docs/theme/setup): install and mount the theme
- [Palette](https://www.domphy.com/docs/theme/palette): `themeColor`, shift scales
- [Size](https://www.domphy.com/docs/theme/size): `themeSize`, `themeSpacing`, density
- [Tone](https://www.domphy.com/docs/theme/tone): light/dark handling
- [API](https://www.domphy.com/docs/theme/api): full theme API reference

## Patches (`@domphy/ui`)

### Typography
- [small](https://www.domphy.com/docs/ui/patches/small), [paragraph](https://www.domphy.com/docs/ui/patches/paragraph), [heading](https://www.domphy.com/docs/ui/patches/heading), [blockquote](https://www.domphy.com/docs/ui/patches/blockquote), [strong](https://www.domphy.com/docs/ui/patches/strong), [emphasis](https://www.domphy.com/docs/ui/patches/emphasis), [mark](https://www.domphy.com/docs/ui/patches/mark), [code](https://www.domphy.com/docs/ui/patches/code), [keyboard](https://www.domphy.com/docs/ui/patches/keyboard), [preformated](https://www.domphy.com/docs/ui/patches/preformated), [link](https://www.domphy.com/docs/ui/patches/link), [abbreviation](https://www.domphy.com/docs/ui/patches/abbreviation), [subscript](https://www.domphy.com/docs/ui/patches/subscript), [superscript](https://www.domphy.com/docs/ui/patches/superscript), [label](https://www.domphy.com/docs/ui/patches/label)

### Controls
- [button](https://www.domphy.com/docs/ui/patches/button), [button-switch](https://www.domphy.com/docs/ui/patches/button-switch), [toggle](https://www.domphy.com/docs/ui/patches/toggle), [date-picker](https://www.domphy.com/docs/ui/patches/date-picker), [input-text](https://www.domphy.com/docs/ui/patches/input-text), [input-number](https://www.domphy.com/docs/ui/patches/input-number), [input-search](https://www.domphy.com/docs/ui/patches/input-search), [input-checkbox](https://www.domphy.com/docs/ui/patches/input-checkbox), [input-radio](https://www.domphy.com/docs/ui/patches/input-radio), [input-switch](https://www.domphy.com/docs/ui/patches/input-switch), [input-range](https://www.domphy.com/docs/ui/patches/input-range), [input-color](https://www.domphy.com/docs/ui/patches/input-color), [input-date-time](https://www.domphy.com/docs/ui/patches/input-date-time), [input-file](https://www.domphy.com/docs/ui/patches/input-file), [input-otp](https://www.domphy.com/docs/ui/patches/input-otp), [textarea](https://www.domphy.com/docs/ui/patches/textarea), [select](https://www.domphy.com/docs/ui/patches/select), [select-box](https://www.domphy.com/docs/ui/patches/select-box), [select-list](https://www.domphy.com/docs/ui/patches/select-list), [combobox](https://www.domphy.com/docs/ui/patches/combobox)

### Forms
- [form-group](https://www.domphy.com/docs/ui/patches/form-group) (layout only). Form state/validation lives in `@domphy/form` (see below), not in `@domphy/ui`.

### Animation
- [motion](https://www.domphy.com/docs/ui/patches/motion) (declarative `animate`/`initial`/`exit` via the Web Animations API), [transition-group](https://www.domphy.com/docs/ui/patches/transition-group) (reorder/FLIP)

### Feedback
- [alert](https://www.domphy.com/docs/ui/patches/alert), [toast](https://www.domphy.com/docs/ui/patches/toast), [badge](https://www.domphy.com/docs/ui/patches/badge), [tag](https://www.domphy.com/docs/ui/patches/tag), [progress](https://www.domphy.com/docs/ui/patches/progress), [spinner](https://www.domphy.com/docs/ui/patches/spinner), [skeleton](https://www.domphy.com/docs/ui/patches/skeleton), [tooltip](https://www.domphy.com/docs/ui/patches/tooltip)

### Overlays
- [dialog](https://www.domphy.com/docs/ui/patches/dialog), [drawer](https://www.domphy.com/docs/ui/patches/drawer), [popover](https://www.domphy.com/docs/ui/patches/popover), [popover-arrow](https://www.domphy.com/docs/ui/patches/popover-arrow), [menu](https://www.domphy.com/docs/ui/patches/menu), [command](https://www.domphy.com/docs/ui/patches/command)

### Layout
- [card](https://www.domphy.com/docs/ui/patches/card), [divider](https://www.domphy.com/docs/ui/patches/divider), [horizontal-rule](https://www.domphy.com/docs/ui/patches/horizontal-rule), [splitter](https://www.domphy.com/docs/ui/patches/splitter), [figure](https://www.domphy.com/docs/ui/patches/figure), [tabs](https://www.domphy.com/docs/ui/patches/tabs), [details](https://www.domphy.com/docs/ui/patches/details), [breadcrumb](https://www.domphy.com/docs/ui/patches/breadcrumb), [pagination](https://www.domphy.com/docs/ui/patches/pagination)

### Data
- [table](https://www.domphy.com/docs/ui/patches/table), [ordered-list](https://www.domphy.com/docs/ui/patches/ordered-list), [unordered-list](https://www.domphy.com/docs/ui/patches/unordered-list), [description-list](https://www.domphy.com/docs/ui/patches/description-list), [avatar](https://www.domphy.com/docs/ui/patches/avatar), [image](https://www.domphy.com/docs/ui/patches/image), [icon](https://www.domphy.com/docs/ui/patches/icon)

## Query (`@domphy/query`)

Async state management — a 1-1 port of `@tanstack/query-core` (identical API). Adapter `createQuery`/`createMutation`/`createInfiniteQuery` (`@domphy/query/domphy`).

- [Overview](https://www.domphy.com/docs/query/) · [Queries](https://www.domphy.com/docs/query/queries) · [Mutations](https://www.domphy.com/docs/query/mutations) · [Caching](https://www.domphy.com/docs/query/caching) · [Infinite Queries](https://www.domphy.com/docs/query/infinite-queries) · [SSR](https://www.domphy.com/docs/query/ssr) · [API](https://www.domphy.com/docs/query/api)

## Router (`@domphy/router`)

Type-safe routing — a 1-1 port of `@tanstack/router-core` (identical API) plus `createRouter`/`createRoute`/`createRootRoute`.

- [Overview](https://www.domphy.com/docs/router/) · [Routes](https://www.domphy.com/docs/router/routes) · [Navigation](https://www.domphy.com/docs/router/navigation) · [Search Params](https://www.domphy.com/docs/router/search-params) · [Data Loading](https://www.domphy.com/docs/router/data-loading) · [SSR](https://www.domphy.com/docs/router/ssr) · [API](https://www.domphy.com/docs/router/api)

## Table (`@domphy/table`)

Headless table logic — a 1-1 port of `@tanstack/table-core` v8 (identical API). Adapter `createDomphyTable` (`@domphy/table/domphy`).

- [Overview](https://www.domphy.com/docs/table/) · [Columns & Row Models](https://www.domphy.com/docs/table/columns) · [Sorting & Filtering](https://www.domphy.com/docs/table/sorting-filtering) · [Pagination & Selection](https://www.domphy.com/docs/table/pagination-selection) · [Advanced](https://www.domphy.com/docs/table/advanced) · [API](https://www.domphy.com/docs/table/api)

## Virtual (`@domphy/virtual`)

List/grid virtualization — a 1-1 port of `@tanstack/virtual-core` (identical API). Adapter `createVirtualizer` (`@domphy/virtual/domphy`).

- [Overview](https://www.domphy.com/docs/virtual/)

## Form (`@domphy/form`)

Headless form state/validation — a 1-1 port of `@tanstack/form-core` (identical API). Adapter `createForm` (`@domphy/form/domphy`); `form.field(name, opts)` returns a reactive field handle.

- [Overview](https://www.domphy.com/docs/form/)

## DnD (`@domphy/dnd`)

Drag & drop / sortable lists — wraps the framework-agnostic `@formkit/drag-and-drop` engine via `dragDrop(state, config?)`.

- [Overview](https://www.domphy.com/docs/dnd/)

## App (`@domphy/app`)

Next.js App Router-style framework — runtime (no compiler, no file-system routing): nested routes/layouts, loaders with stale-while-revalidate, metadata, middleware, parallel + intercepting routes, **lazy / code-split routes** (`lazy: () => import(...)`), SSR + streaming (`renderToString`/`renderToStream`), API routes. Routes are a plain object tree via `defineRoutes`; `createApp(routes)`. (This docs site is built on it — see Markdown below.)

- [Overview](https://www.domphy.com/docs/app/) · [Routing](https://www.domphy.com/docs/app/routing) · [Layouts & Boundaries](https://www.domphy.com/docs/app/layouts) · [Data Fetching](https://www.domphy.com/docs/app/data-fetching) · [Metadata](https://www.domphy.com/docs/app/metadata) · [SSR](https://www.domphy.com/docs/app/ssr) · [API Reference](https://www.domphy.com/docs/app/api)

## Markdown (`@domphy/markdown`)

Parse Markdown into Domphy element trees for SSR/SSG — `parseMarkdown(md, options)` → `{ frontmatter, body, toc }` (markdown-it under the hood; pluggable `highlight`, anchors, TOC). Lower-level `tokensToDomphy`/`walkTokens`/`splitFrontmatter` let you run your own markdown-it (extra plugins) and reuse the canonical token→Domphy walker. This documentation site is built on it.

- [Overview](https://www.domphy.com/docs/markdown/)

## Mermaid (`@domphy/mermaid`)

Render Mermaid diagrams for Domphy — build-time `renderMermaidToSvg` / `renderMermaidInTree` (replaces ```mermaid code blocks with inline SVG via mermaid-cli) and a client `mermaidClient()` patch.

- [Overview](https://www.domphy.com/docs/mermaid/)

## Palette (`@domphy/palette`)

Color-palette engine (design-time companion to `@domphy/theme`): generate accessible ramps (`generateRamp`) + measure palette quality (5 CIELAB metrics).

- [Overview](https://www.domphy.com/docs/palette/) · [Measuring quality](https://www.domphy.com/docs/palette/measuring) · [Generating palettes](https://www.domphy.com/docs/palette/generating)

## Doctor (`@domphy/doctor`)

Static analyzer for Domphy element trees — `diagnose(element)` returns `Diagnostic[]`; `validate(element)` returns `{ ok, issues, summary }`; `fix(element)` returns `{ tree, applied, report }`, applying lossless fixes (e.g. void-content) and listing the rest. Rules: inline-typography, raw-theme-value, raw-spacing-value, unknown-tone, void-content, missing-key, duplicate-key, unstable-key, unknown-tag. Run it on generated code and fix what it reports — the AI self-correction loop. Pairs with the app-block registry (`app-manifest.json`) for large codebases.

- [Overview](https://www.domphy.com/docs/doctor/)

## AI tooling

- [`manifest.json`](https://www.domphy.com/manifest.json): machine-readable index of every package + patch (name, host tag, signature, props schema, doc, example). Query this instead of parsing docs.
- [`tones.json`](https://www.domphy.com/tones.json): valid tone names + theme color names for `themeColor()` / `dataTone`.
- [`@domphy/mcp`](https://www.npmjs.com/package/@domphy/mcp): MCP server. Tools: `domphy_list_patches`, `domphy_get_patch`, `domphy_list_packages`, `domphy_rules`, `domphy_tones`, `domphy_diagnose`, `domphy_validate`, `domphy_fix`, `domphy_list_app_blocks`, `domphy_get_app_block`.
- [Full text dump for one-shot context](https://www.domphy.com/llms-full.txt): rules + quickstart + every core/theme/package doc + every patch source. Use when you need the whole framework in a single fetch.
- [Building with AI](https://www.domphy.com/docs/ai): per-tool setup.
- [Playground](https://www.domphy.com/docs/playground): interactive sandbox
- [GitHub](https://github.com/domphy/domphy): source, issues, releases