Prism

中文文档：README.zh-CN.md

An MCP server for design work. Give an AI agent the ability to generate design tokens, assemble a page from 38 component types, review it for accessibility and design quality, and export it as code or tokens.

• 42 tools, 4 resources, 3 prompts over stdio
• 38 component types with validated Zod prop schemas
• Export to HTML, React, Vue, React-TS, Svelte, CSS, presentation, Flutter, SwiftUI
• Tokens in DTCG, CSS custom properties, Style Dictionary, Figma Tokens, Tailwind v4 @theme, DESIGN.md
• Sessions are stateful and persisted: save/load a project as .prism.json
• Live preview: one stable artifact any viewer can follow (design_preview_sync), plus a self-contained DeepSeek Harness plugin (dsh-plugin-prism-design) whose panel opens from the sidebar rail or the right Sidebar
• No dashboard, no HTTP server, no external APIs. Exported pages are self-contained (pure CSS animation, no CDN runtime)

---

Quick start

npm install
npm run build
npm start            # speak MCP over stdio

Wire it into an MCP client

{
  "mcpServers": {
    "prism": {
      "command": "node",
      "args": ["/absolute/path/to/prism/dist/index.js"]
    }
  }
}

Any MCP-capable client works (Claude Desktop, Cursor, Claude Code, or your own). Once connected, ask the agent for something like:

Build a landing page for a coffee roastery, warm and editorial. Then audit it for accessibility and export the React version.

The agent will call design_init → design_add_component → design_audit_accessibility → design_export and can inspect its own work through design_get_state.

Verify the server

npm run smoke    # spawns dist/index.js, handshakes, lists tools/resources/prompts

---

Tools

Call design_list_capabilities for the machine-readable manifest. It lists exactly the registered tools — this is enforced by tests/tools.test.ts, so the manifest cannot drift from the registry.

Generation — stateless token and asset generators (10)

Tool	What it does
ui_generate_color_palette	Harmonious palettes from a base colour (6 harmony schemes)
ui_suggest_typography	Curated font pairings with Google Fonts links
ui_generate_type_scale	Modular type scales (golden ratio, perfect fourth, …)
ui_generate_spacing_scale	Spacing systems (linear, geometric, fibonacci)
ui_generate_shadow_system	Elevation shadow sets (subtle, medium, sharp)
ui_generate_border_radius_scale	Radius scales (sharp, subtle, rounded, pill)
ui_check_color_contrast	WCAG 2.1 contrast ratios with AA/AAA grading
ui_generate_gradient	CSS gradients with harmonious stops
ui_suggest_breakpoints	Responsive breakpoint systems (Tailwind, Bootstrap, Material)
ui_generate_design_tokens	A complete token system in one call

Session — build a design in the server's state (18 + 3 persistence)

Tool	What it does
design_init	Start a session (neutral default tokens + optional base colour)
design_add_component	Add a component by type, with validated props
design_update_component	Update props, layout, visibility, lock
design_rename_component	Rename a layer
design_remove_component	Remove a component
design_reorder_component	Reorder siblings
design_align_components	Align/distribute (single undo step)
design_z_order_component	Stacking: front/back/forward/backward
design_set_token	Set one token
design_set_theme	Light/dark
design_apply_template	One of 5 page templates
design_add_page / design_switch_page / design_remove_page	Multi-page sessions
design_get_state	Read the whole session (tokens, pages, components, activity)
design_get_conflicts	Token contrast conflicts
design_undo / design_redo	History (50 snapshots)
design_save_project / design_load_project / design_list_projects	Persist and restore a session as .prism.json

Review, delivery and meta (11)

Tool	What it does
design_audit_accessibility	WCAG-oriented audit with a 0–100 score
design_suggest_improvements	Heuristic review: structure, density, motion, a11y, tokens
design_render_preview	Standalone HTML preview (PNG when Playwright is installed)
design_preview_sync	Write the live-preview file so a watching viewer shows the latest design
design_export	html / react / vue / react-ts / svelte / css / presentation / flutter / swiftui
design_export_tokens	DTCG / CSS / Style Dictionary / Figma Tokens / DESIGN.md / Tailwind v4
design_import_tokens	Import DTCG tokens (replace / merge-overwrite / merge-keep)
design_import_webpage	Import a URL or pasted HTML as components
design_import_design_md	Import tokens from a Google DESIGN.md document
design_semantic_style	Map adjectives ("warm", "温暖") onto measurable token deltas
design_list_capabilities	The manifest

Resources and prompts

• Resources: prism://tokens/active, prism://components/registry, prism://patterns, prism://audit/checklist
• Prompts: build_page, design_review, import_project

Live preview

design_preview_sync renders the current page to one stable file (PRISM_PREVIEW_FILE, default <cwd>/.prism-preview/design.html), stamped with a revision. Because it is a single path that is overwritten in place, any watcher can follow it — see DeepSeek Harness integration, whose bundle also adds a Prism Preview panel (left sidebar rail, or a right-Sidebar tab) that re-renders whenever the revision changes. That bundle is self-contained — it packages the MCP server it launches, derives every path from where it is installed, and declares no machine-specific configuration.

---

Component types

38 types the exporter can render. Values are validated by src/component-schemas.ts (unknown keys pass through, missing keys are tolerant); a test asserts the schema map and the catalog list the same types.

accordion · alert · avatar · badge · bento_grid · breadcrumb · button · card · card_grid · carousel · container · cta · faq · feature_grid · feature_list · footer · form · glass_card · grid · hero · html_fragment · image · input · marquee · navbar · pagination · pricing · progress · sidebar · skeleton · stats · table · tabs · testimonial · text · text_section · timeline · tooltip

Two of them are produced by the store rather than typed by hand: text comes from promoteElementToComponent, and container from groupComponents. items is the canonical list prop for every list-bearing type (links / plans / tabs / slides are accepted aliases), and design_add_component warns instead of silently rendering an empty component when the list is missing or is not an array.

html_fragment is how imported HTML is represented: an imported page becomes faithful regions (header / nav / main / footer / section-N / content) that keep the original CSS, and edits are written back through applyHtmlFragmentsToDocument with head and scripts preserved.

---

Configuration

Variable	Default	Effect
PRISM_PROJECT_DIR	~/.prism/projects	Where design_save_project / autosave write
PRISM_AUTOSAVE	on (set off to disable)	Rolling autosave of the session
PRISM_AUTOLOAD	on (set off to disable)	Restore the autosave checkpoint on start
PRISM_PREVIEW_FILE	<cwd>/.prism-preview/design.html	The live-preview artifact design_preview_sync writes
PRISM_PREVIEWS_DIR	<cwd>/.prism-previews	Where design_render_preview writes PNG screenshots

The LLM API key is never involved: Prism has no built-in AI channel — the agent driving the MCP server is the intelligence. Nothing leaves your machine except the exported files you ask for.

---

Architecture

┌──────────────┐   stdio (MCP)   ┌────────────────────────────────────────┐
│  MCP client  │ ◄─────────────► │  src/index.ts                          │
│  (agent)     │                 │   ├─ McpServer: 42 tools               │
└──────────────┘                 │   ├─ 4 resources · 3 prompts           │
                                 │   └─ DesignStateStore (in-memory + disk)│
                                 └────────────────────────────────────────┘

One mutation path: every tool calls design-service, which calls DesignStateStore. Undo/redo, activity logging, conflict detection and the export pipeline all hang off that single store, so no two tools can disagree about state. This is enforced: tests/mutation-path.test.ts fails if a tool reaches past the service to a store mutator, which is what keeps the component type allowlist, the prop schemas and the token-category check from being bypassed.

src/
├── index.ts              # MCP registration + stdio bootstrap
├── state.ts              # DesignStateStore: state, undo/redo, mutators
├── service/design-service.ts  # the only mutation path + input validation
├── component-schemas.ts  # per-type Zod prop schemas + the list-prop contract
├── tools/                # one module per area (design-tools, design-preview, …)
├── tokens.ts + tokens/dtcgi.ts # token generation and interop
├── layout/snap.ts        # grid snapping used by snapComponentsToGrid
├── import-project.ts     # HTML → html_fragment regions → back again
├── semantics.ts          # adjective → token deltas
├── project-store.ts      # .prism.json persistence + autosave
└── resources/, prompts/  # MCP context surfaces

dsh-plugin/               # DeepSeek Harness bundle (MCP connection + preview panel)

The geometry layer (a layout engine, a tidy-up pass, and an auto-layout pass) was removed: exports are CSS flow layout and never read layout coordinates, so nothing consumed it.

---

Development

npm run dev      # tsx watch src/index.ts
npm run build    # tsc
npm test         # build + compile tests + node --test (glob over .test-build/tests)
npm run lint     # eslint
npm run check    # lint + test

The test suite is 166 tests over 18 suites, covering the state store, the service layer, all 42 tool contracts, component schemas, the export formats, token interop, and HTML import fidelity. Three contract tests are worth knowing about:

• tests/tools.test.ts — the registered tool set must equal the design_list_capabilities manifest, every tool must accept its documented parameters and respond.
• tests/mutation-path.test.ts — no tool may call a DesignStateStore mutator directly; the service's validation must not be bypassable.
• tests/component-schemas.test.ts — the prop-schema map and the component catalog must list exactly the same types.

.githooks/pre-push runs npm run lint && npm test && npm run smoke; install it with npm run hooks:install. CI runs the same plus a dependency audit.

Reproducible audits

These scripts check properties that unit tests cannot, and each regenerates what it needs:

Script	What it proves
npm run smoke	The server starts over real stdio, handshakes, and registers the expected surface
node verify-dsh-bundle.mjs	The Harness bundle is well formed: manifest and exported paths, patch rows, JS syntax, and the client-half contracts (guide thunks, the Remote result envelope, the iframe sandbox, the service inject list)
node verify-preview.mjs	The live-preview artifact is written, self-contained (no remote references) and revision-stamped
node audit-rendered-css.mjs	Every variant class an export emits actually has a CSS rule that takes effect in a browser
node verify-components.mjs	The reworked components behave (tabs switch, tooltip hides until hover, marquee animates, carousel scrolls)

verify-dsh-bundle.mjs and npm run smoke run anywhere; the CSS and component audits need playwright (a devDependency) and a cached Chromium.

Examples

examples/ holds exported pages next to their screenshots: saas-landing, ecommerce-home and dark-dashboard, plus the DSH-era apple-style and coffee-demo. node showcase.mjs builds the first three through the real MCP server over stdio and re-shoots them.

---

History

This repository previously contained a much larger product: an Electron desktop app, a vanilla-JS dashboard, a React 19 client, Yjs real-time collaboration, JSX bidirectional sync, a scraped design-library catalog, and a built-in LLM channel — 82 tools in total. That surface was removed in the route B refactor because it was not reachable from the MCP server, not verifiable, or actively drifted from the code (much of the documentation described features that had been deleted, and the capability manifest advertised tools that were never registered).

Everything that described that removed product was deleted rather than left to mislead: DESIGN.md, PRD.md, prism-product-definition-v2.md, docs/archive/*, the dated V2.0 plans, and — for the same reason — the refactor plan itself, which tracked a target surface (22 tools) the implementation never had and quoted numbers that every later change invalidated.

Two later cleanups followed the refactor: the component catalog was trimmed from 45 to 38 types (removing entries that could not do anything meaningful in a static export, or duplicated another type), and the dead layout geometry layer was deleted. Then came the DeepSeek Harness integration — an MCP connection plus its preview panel, and the only part of this repository that talks to another application.

What remains is this README, its Chinese translation, and the integration guide with its Chinese translation. src/ is the source of truth.

License

MIT.