Design Briefs

A design brief is a bundle of reference HTML and CSS files you upload so theme-generation tooling (Claude via MCP, or any assistant you hand the brief to) can see exactly the look you want. Briefs are read-only: they don’t touch your site until a generated theme uses them.

The workflow

1. Upload the brief (from the Themes screen’s Generate Theme panel or from the shared Themes upload panel).
2. Create a theme scaffold: name the theme, attach the brief (and optionally a short “design intent” sentence), and Chinaski produces both the cloned starter files and a copy-ready prompt.
3. Hand the prompt to your assistant: the prompt names the brief’s ID and tells the reader exactly which tool calls fetch each brief file, so Claude (or another MCP client) can read your reference design before writing theme files.
4. Iterate: re-upload or delete briefs anytime; briefs have no effect on the live site.

Uploading a brief

From the Themes screen’s Generate panel, or from the dedicated Design Briefs screen, you upload:

• a single .html or .css file, or
• a .zip archive of such files (kept flat; files in subdirectories are skipped)

Rules the upload enforces:

• Size: 3 MB per upload maximum (browser-side check avoids surprises up front).
• File types: .html, .css, and .zip only. Inside a zip, only .html/.css files are kept; other formats and unknown extensions are ignored.
• Count: at most 20 files per zip.
• One HTML at least: a brief must contain at least one .html file; uploads without one are rejected with an error.
• Filename pattern: lowercase letters, digits, underscore, dash, dot, with an .html or .css extension. Directory entries in a zip are discarded (flattened) so no path-traversal content is extracted.

Label your brief first (for example “Kitchen Sink”) so the list and the Generate dropdown are easy to use. Briefs without labels display as “(untitled)”.

Where briefs live

• Each brief gets a UUID and its own directory: uploads/design-briefs/<uuid>/.
• The screens list briefs with Label, Files count, Uploaded (UTC), and a Delete button on each row (with an irreversible-delete confirmation).
• Both the Design Briefs page and the file picker on Themes enforce the same 3 MB limit before upload.

Where briefs are read from

The reference files are read back through three channels:

• MCP tools for Claude and every other MCP client: list_design_briefs (id, label, uploaded-at timestamp, file count), list_design_brief_files, and read_design_brief_file (consuming the brief’s raw HTML/CSS as plain text).
• The REST API (read-permission API keys): /api/themes/design-briefs for the list, the brief’s file list, and raw oneofile content.
• The Generate-panel prompt: the theme-creation prompt tells your AI to call the listed helper tool with the brief ID to read all reference files before writing template code.

Deleting

Deleting a brief removes both the metadata row and its files, after an explicit confirmation (“Delete this design brief and its files? This cannot be undone.”).

What briefs can’t do

Briefs are pure reference material: Chinaski never calls an AI itself. The Generate panel returns a copy-ready prompt for you to run in your own assistant; that prompt points to brief files via their IDs, and your assistant fetches them through the MCP tools or the read-only API.