/polished-web-prototype

name: polished-web-prototype
description: 'Use when /polished-web-prototype runs or a user builds an artifact from a mockup, design plan, or brief. Not for variant galleries: use design-variants. Not for live audits: use web-design-review.'

Polished web prototype

Contract

| Field | Bound contract | |---|---| | Trigger | The user runs `/polished-web-prototype` or asks to convert an approved mockup, design plan, or freeform description into a polished responsive HTML artifact. | | Authority | Reversible local: writes only the named HTML artifact file and its finalized.json metadata under the project design directory, and (for framework-native output) the package manifest and lockfile at the project root; rollback is undo. No remote mutation. When framework-native output is chosen, the only permitted mutation beyond the artifact and metadata is adding the Pretext dependency using the detected package manager. | | Side effect | The HTML artifact, finalized.json, and, for framework output, the manifest and lockfile dependency addition. A local HTTP preview server runs during refinement and is stopped at finalization. | | Done | The user accepted the artifact or chose to finalize at the 10-iteration gate; finalized.json is written with every listed field; the preview server is stopped. |

Inputs

• A design source: an approved mockup image (PNG), a written product or design plan, or a freeform user description. At least one must be supplied; if none exists, ask the user which source to start from.
• Optional: a repo-root DESIGN.md carrying design tokens (brand colors, font family, spacing scale). Its values override any extracted defaults for system-level properties.
• Optional: the target frontend framework (React, Svelte, Vue, Solid, Preact). If a package.json declares one, ask whether output should be a self-contained vanilla HTML file or a framework-native component.

Procedure

1. Detect the design source and extract the implementation spec. Look for an approved mockup image, a product or design plan, and a repo-root DESIGN.md. If none are found, ask the user to supply a freeform description or a PNG path. Record the mode: approved-mockup, plan-driven, freeform, or evolve (a prior finalized HTML exists and the user chooses to iterate on it). Build the spec: colors (hex), fonts (family and weights), spacing scale, component list, and layout type, extracted from the mockup image, the plan prose, or the freeform description. DESIGN.md tokens override extracted system-level values. Generate real content from the source; never use lorem ipsum or placeholder text. Apply the UX doctrine below to every layout and visual decision before generating any markup. The doctrine is observed user behavior, not preference:

• Every page is self-evident; if a user must think "what do I click," the design failed.
• Three mindless clicks beat one thoughtful one; each step is an obvious choice.
• Omit half the words, then half of what remains; happy talk and instructions must die.
• Users scan, satisfice, and muddle through; design for scanning with visual hierarchy, grouped related items, and the right choice made most visible.
• Use web conventions (logo top-left, nav top/left, search icon) unless a known better idea exists.
• Visual hierarchy is everything: more important is more prominent; if everything shouts, nothing is heard.
• Make clickable things obviously clickable without hover (shape, location, color, underlining); mobile has no hover.
• Eliminate noise by removal, not addition.
• Clarity trumps consistency.
• Persistent navigation answers: what site, what page, what sections, what options, where am I, how to search.
• Every friction point depletes a finite goodwill reservoir; replenish by making the user's goal obvious and recovery easy.
• Mobile raises the stakes: 44px minimum touch targets, visible affordances, ruthless prioritization.

Done when: exactly one source mode is recorded (or the user has been asked for one), the spec lists colors, fonts, spacing, components, and layout with every value sourced from the input, and each layout and visual decision traces to a named doctrine line.

2. Generate the artifact with the appropriate Pretext tier. Classify the design into a tier and state the chosen APIs:

• Simple layout or card/grid: prepare() + layout() for resize-aware heights and self-sizing cards.
• Chat/messaging: prepareWithSegments() + walkLineRanges() for tight-fit bubbles and minimum width.
• Content-heavy editorial: prepareWithSegments() + layoutNextLine() for text around obstacles.
• Complex editorial: full engine + layoutWithLines() for manual line rendering.

The Pretext API:

• prepare(text, font) returns a handle; call once after document.fonts.ready. Font is a CSS shorthand like '16px Inter'.
• layout(handle, maxWidth, lineHeight) returns { height, lineCount }; call on every resize; sub-millisecond.
• prepareWithSegments(text, font) enables line-level APIs.
• layoutWithLines(segs, maxWidth, lineHeight) returns { lines: [{text, width, x, y}], height } for Canvas/SVG rendering.
• walkLineRanges(segs, maxWidth, onLine) calls back per layout to find the minimum width for a line count (tight-fit containers).
• layoutNextLine(segs, state, maxWidth, lineHeight) iterates lines with per-line width (text around obstacles); pass null initially; returns null when exhausted.
• clearCache() clears measurement caches; setLocale(locale?) retargets the word segmenter.

The basic pattern: prepare all [data-pretext] elements after fonts load, store handles in a Map, run layout to set element heights, observe resize with ResizeObserver to relayout, and re-prepare on contenteditable changes with a MutationObserver.

If a framework was detected and the user chose framework output, add @chenglou/pretext to the project dependencies using the detected package manager (this edits the package manifest an