personal-website

Personal Website

Core Rules

Do not start writing code right away. Treat the website as a phased project guided by reference images:

Content and style lock
Reference image lock
Asset breakdown checklist
Asset generation review
High-fidelity reproduction and QA

The user-facing process has four default blocking confirmation points:

Confirm the full content and style brief, including site form, section planning, content sufficiency, and the selected or user-provided visual direction
After consistency and monotonicity review, confirm the reference image set
Before any new asset generation or asset collection begins, confirm the asset breakdown checklist
Before page code implementation begins, confirm the generated/collected assets and the reproduction brief

After the reference image set is confirmed, do not go straight into implementation. First review each accepted reference image one by one, produce a user-facing asset breakdown checklist, and wait for confirmation. After the checklist is confirmed, only generate, collect, or prepare the approved assets. Then report the generated/collected assets with final paths and a brief reproduction brief; wait for the user to accept, request regeneration, or modify the checklist. Only after that can high-fidelity reproduction begin.

The original lightweight "pre-build design notes" have been merged into the asset review handoff as a concise reproduction brief. It is not an extra separate gate: before writing code, the user confirms both the asset results and the reproduction brief.

Do not collapse the later stages into a generic front-end build. Accepted reference images are not a moodboard. Before writing code, every accepted reference image must be broken down into the code layer, background asset layer, foreground asset layer, visual anchors that must be preserved, and a final asset/source decision that must be followed during implementation.

Hard stop: until the asset breakdown checklist is confirmed, the approved assets are generated or organized, and the asset review plus reproduction brief is accepted, no HTML, CSS, JS, React, routing, or component files may be created or edited. Saying "I will map the reference images" in a progress update is not enough.

If the user has only partial materials, first audit what is missing, and before asking the user to hand-write all content, suggest less effortful ways to provide the materials. If the user already has confirmed content, reference images, and assets, go directly to the corresponding review, asset review, or reproduction stage, but still maintain the same confirmation boundaries before writing code.

Execution Discipline

Before moving between stages, state the current assumptions, the next verifiable goal, and the check that proves it is complete. If the requirements have multiple interpretations, lay out the options and ask clearly before deciding the direction.

Keep the process surgically precise:

Do not add sections, interactions, content, routing, asset types, or configurations that the user has not requested or approved
When editing an existing project, only change the files needed for the approved scope, and stay consistent with the project's current style
Only delete code, assets, or imports newly created by this process that are unused; for unrelated dead code, only mention it, do not delete it
Prefer the smallest and most durable design notes, manifest, prompt set, or implementation changes that make the next stage reliable
For multi-step work, write the success criteria to a level where they can be verified without guessing
When redoing a failed build attempt, start from a fresh session and bring only the surviving artifacts (reference images, accepted assets); do not resume on top of the context of the failed attempt—the old plan and code will anchor the redo in the wrong direction

Language

Make user-facing output match the user's primary language. If the user communicates in Chinese, use Chinese for progress prompts, stage transitions, confirmation requests, and option labels, using labels such as 第一步 / 内容与风格锁定 and 接下来进入第二步 . If the user communicates in English, use English labels, for example Step One / Content and style lock. If the conversation is in mixed languages, follow the user's most recent explicit language preference, or the language used in the most recent substantive request.

Do not throw the template text in a certain language directly at the user just because the template examples below this document are written in that language. Naturally translate the form of the prompt while preserving all the information required in it. Stage names should also be translated.

Built-in companion references

This skill has several built-in companion references so the process does not depend on the user installing other skills:

references/imagegen-frontend-web.md: used for the reference image direction in step two
references/frontend-app-builder.md: used for high-fidelity frontend implementation and QA after asset review
references/reference-asset-splitter/: used for asset boundary and granularity decisions in step three

references/frontend-app-builder.md is the Chinese translation of the official builder skill (v0.1.2);references/imagegen-frontend-web.md is an adapted version;references/reference-asset-splitter/ is the built-in asset splitting skill. If the standalone imagegen-frontend-web skill, Build Web Apps' frontend-app-builder plugin, or the reference-asset-splitter skill is already installed, the installed version takes precedence, and the built-in copy serves only as an offline fallback.

If a companion skill is not installed, do not block because of it, do not pretend that a @skill call can take effect, and do not require the user to install it just to continue. Read the built-in companion reference and execute it as the local minimum contract.

If no image generation tool is available, write prompts that can be copied and pasted directly, so the user can paste them into GPT web Image 2 or another image tool, or ask the user to provide reference images themselves. If the user completely gives up on reference images, treat the build as low-fidelity and state that visual QA can only be checked against the written brief, not against accepted reference images.

Transition prompt protocol

At the end of each user-facing stage, give a clear progress prompt:

Current progress:第一步 / 阶段名称
Completed: the specific artifact just produced
Missing or at risk: list only true blockers
What the user can do now: confirm, modify a specified part, provide missing materials, or choose an option
Next step: state the name of the next stage and what will happen

Do not leave the user at a vague stopping point. If the process is continuing without a blocking confirmation, state that it is continuing and why.

Step one: content and style lock-in

First determine which content route applies. Do not make users manually retype information that can be read from the provided files, links, resumes, profiles, notes, writing samples, project docs, screenshots, or existing websites.

Material intake routes

Use one of the following routes:

Material-sufficient route: The user has provided a resume, CV, LinkedIn profile, personal site, portfolio, project links, Notion/Markdown documents, bio, media kit, social profiles, writing archive, or similar materials. Read the accessible content, extract confirmed facts, content units that can be directly turned into sections, links, assets, and gaps. Ask only targeted follow-up questions that will affect the website.
Incomplete-brief route: The user gave a goal or identity, but there is little supporting material. First invite lower-effort inputs, such as a resume, existing self-introduction, project links, writing links, photos, reference images, or screenshots. If the user is unwilling to provide files, then use the guided questions below.
From-scratch route: The user has no materials or wants to start from zero. Ask the guided questions together, rather than conducting a lengthy interview one question at a time.
Quick-demo route: The user explicitly prioritizes speed or a rough prototype. Lightweight mock content is allowed, but mark every fictional fact, project, quote, metric, link, or biographical detail as placeholder content that must be replaced before the formal build.

In the guided-question route, ask concisely:

Goal: resume, job search, portfolio, creator/personal IP, consulting, founder/executive profile, speaking/media page, or another purpose
Audience: who will visit, and what they should do after reading
Positioning: identity label, one-sentence memorable hook, tone boundaries
Evidence: experience, projects, writing, products, clients, media coverage, speaking, awards, or other proof
Project details: for each important project, collect the problem, role/actions, results, links/media, and the point most worth remembering
Assets and boundaries: avatar, logo, screenshots, documents, links, content that cannot be used or is sensitive, and anything that must not be generated or exaggerated
User preferences: preferred information density, instinctive preference for single-page vs. multi-page (if any), liked references, disliked styles, and willingness to maintain

Content and site-shape document

For a polished personal website, personal IP site, portfolio, Awwwards-level direction, or any scenario where design quality matters, produce a content and site-shape document before moving into visual output. For a quick demo, keep the same structure but make it shorter.

The document should include:

Source coverage: which files, links, notes, or answers were used
Confirmed facts: only facts provided by the user or supported by sources
Unconfirmed draft content: clearly mark agent-drafted copy, examples, placeholders, inferred claims, or missing links
Site goals and audience: what the website should achieve and whom it is for
Visitor takeaway: the one to three things visitors should remember
Site-shape recommendation: single page, one-page resume, homepage plus case studies, multi-page portfolio, creator hub, consulting landing page, or another form
Rationale: why this form fits the user's goals, content volume, depth of evidence, and willingness to maintain
Optional alternatives: leaner or richer structures that are viable but less recommended
Section plan: each section's purpose, required content, content units, links/assets, and status (ready、needs detail、placeholder or cut）
Content-sufficiency risks: hollow, generic, fake, padded, unsupported, or not worth keeping sections

Site form must be derived from the user's goals and material density, not by applying a default five-section or six-section template. Resume or job-seeking scenarios often need only a single page or one to two pages. A deep portfolio may need case-study routes. Creator, founder, or consulting sites need a stronger narrative or conversion path only when the content can support it.

All content used for reference images must be provided by the user or explicitly approved by the user. The agent may draft to fill gaps, but drafted content is a draft, not approved content. Do not treat a draft as confirmed just because it is reasonable or polished.

Style recommendations

Once the content and site form are clear enough, recommend up to three visual directions based on the content, user preferences, audience, site purpose, and provided references. The user may choose one, mix them, or provide their own visual direction or references.

Style options must be visual concepts, not just positioning labels. Do not give options that differ only in audience or occupation framing, such as "international student resume," "fintech product researcher," or "AI + finance portfolio." These labels can explain why an option fits, but the option itself must let the user imagine what the design looks like before images are generated.

Each style option should briefly cover:

Visual concept name: a short label that describes the look (not just the persona)
Mood and fit with the positioning
Color direction: 3-5 specific colors or color roles, with hex values when useful
Typography mood: the personality and weight contrast of heading/body fonts
First-screen composition: where the name, large headline, avatar/media, CTA, and proof cues each appear
Layout density and section rhythm: restrained single page, editorial rhythm, bento proof blocks, case-study depth, or another specific rhythm
Image or asset treatment: avatar cropping, project screenshots, document cards, data visualization, editorial photos, abstract backgrounds, or code-rendered graphics
UI frame and navigation feel: header density, wordmark, CTA shape, borders, corner radius, icon style, active state
Motion personality
What the user will see: a one-sentence description of the overall visual impression
Why it fits this person and this site form
Main risks or trade-offs

If a style option cannot be described as a visible website image, rewrite it before presenting it. If the user's goal is career positioning, translate that positioning into visual decisions instead of letting the option title carry everything.

Use this compact style option shape when needed:

选项 A —— 编辑式简历 / 墨黑 + 纸白
配色：暖白 #F7F3EC，墨黑 #171717，哑光钢灰 #6B7280，强调蓝 #2563EB。
字体：克制的衬线标题 + 干净的无衬线正文；自信但不花哨。
首屏：姓名与一句话定位左对齐，铺在充裕的纸感留白上，头像或 LinkedIn 风格证件照置于右侧安静的裁切里，下方两个佐证链接。
节奏：单页简历式流动，分区平静，配小型项目佐证卡。
它的感觉：一份精致的国际候选人档案，更接近编辑式 CV 而非创业公司落地页。
风险：如果用户想要更大胆的个人品牌，这个方向会不够有辨识度。

Do not generate reference images until the user confirms the full content and style brief. If the user selects a style option and does not object to the content document, treat that response as the first blocking confirmation only if the prompt has clearly stated that "this step locks both content and style."

Use this shape for the step-one closing prompt:

当前进度：第一步 / 内容与风格锁定
我已准备好：来源摘要、确认的事实、站点形态建议、分区规划、内容风险、以及风格选项。
请确认或修改：
1. 站点形态与分区规划
2. 任何被标注为未确认的内容
3. 视觉方向：选一个选项、混搭选项、修改配色/布局，或提供你自己的参考
确认后，我将进入第二步，生成或准备各分区的参考图。

Step 2: Reference image lock

Use section-level reference images as the sole visual standard.

Prompts for reference images must be based on confirmed content and a style brief: approved content, approved site form, the chosen or user-provided visual direction, global outer-frame rules, and the content units specific to each section. When the user expects a high-quality personal website, do not produce reference images based on a thin brief or an unapproved agent draft.

If imagegen-frontend-web is available, use it at this stage. If it is not available, read references/imagegen-frontend-web.md and apply the built-in companion rules. Either way, the reference image set must achieve: one landscape image per section, strong composition, consistent color palette, and website-style reference images that are easy to implement.

If the user would rather use GPT web Image 2, write the prompts well so the user can paste them there, instead of generating the images directly.

Default output:

One landscape reference image per section
Do not use tall vertical full-page collages
Do not use multi-section boards so small they are illegible
All sections share a consistent personal IP worldview
Reference images should look like real website screenshots, not posters

Before accepting the reference image set, do a two-way review:

Consistency review—flag conflicts in global navigation, section order, repeated motifs, typography, spacing rhythm, brand/logo treatment, and mobile feasibility. If the reference images contradict each other, propose a design rule and ask the user to confirm or regenerate the conflicting sections before continuing.
Monotony review—the opposite failure. Determine each section's composition skeleton (for example, "left text column + right visual" is one skeleton, regardless of whether the right side is a photo, an image row, or a bento grid). If the same skeleton appears in more than 2 sections, or every frame has the same headline scale and position, reject the set. Then do a gray-box test: after replacing every photo with a plain gray rectangle, at least half of the sections should still look designed (type scale, text over images, asymmetric grids, color-blocked sections)—otherwise the design lives only in the photos and will evaporate when reproduced in code. Regenerate the weakest sections before continuing.

Passing consistency is necessary but not sufficient: a set can be completely consistent and completely monotonous at the same time.

When design quality matters, or the user asks for taste guidance, read references/taste-calibration.md。

End the second step with this prompt form:

当前进度：第二步 / 参考图锁定
我已准备好：各分区参考图，以及一致性/单调性审查。
请确认或修改：
1. 接受这些图作为构建目标
2. 重新生成指定的分区
3. 在构建前调整风格方向
参考图确认后，我将进入第三步并产出素材拆分清单：哪些留在代码里、哪些需要背景素材、哪些需要前景/透明素材、哪些应使用既有真实素材、哪些被阻塞或待替换。在生成或采集新素材之前，我会等你确认。

Step 3: Asset breakdown list

After the reference image set is confirmed, review the accepted reference images first, then generate assets or write code. At this stage, produce a user-facing asset breakdown list and pause for confirmation.

The boundary and granularity decisions at this stage are handled by the independent reference-asset-splitter skill. Before producing the breakdown list, read references/reference-asset-splitter/SKILL.md and its split-patterns.md, and follow its top-down decision process: first classify each area's purpose (static decoration static-decor / content card content-card / media slot media-slot / identity marker identity), then enumerate visible objects; by default take "the coarsest-grained asset that preserves fidelity," and split more finely only when a mandatory split condition is triggered (independent interaction, independent replacement, editable/factual text, responsive reflow); explain the interaction assumptions page by page; when "static vs interactive" is unclear, give one recommended default option plus one alternative. The rules below cover only the parts that personal-website additionally supplements on top of it (artifacts, geometric measurements, lists, confirmation gates); in case of any wording conflict, the splitter skill takes precedence.

The goal is pragmatic rather than over-specified: tell the user which visible parts should remain in code, which parts need separately generated or sourced assets, which assets should be transparent/foreground, which belong to the background, which real assets must not be faked, and which decisions, if guessed wrong, will damage the final replica.

At this stage, create or update one visible replica artifact. Acceptable forms:

docs/restoration-plan.md, combining the reference image mapping, asset checklist, and subsequent replica brief
docs/reference-to-build-map.md plus docs/asset-manifest.md
If the repository already has a docs convention, use the equivalent project-level documentation

This artifact must be written to disk before asset generation and before any page code editing. It must list every accepted reference image and every section/page. A one-sentence summary in chat, hidden reasoning, or a one-liner in a progress update does not satisfy this requirement.

The user-facing asset breakdown checklist should be shorter than the internal artifact. For each section, include:

Code-owned elements: editable text, navigation, buttons, layout, simple shapes, labels, and motion that should remain editable
Background assets: full-section scenes, textures, maps, photographic fields, or "none/native to code"
Foreground assets: avatars, product mocks, card/photo clusters, illustrations, transparent objects, screenshots, or "none/native to code"
Existing real assets: user-provided photos, logos, product screenshots, official assets, or source files to be copied
Generated assets: atmospheric images, decorative objects, abstract product mocks, backgrounds, or stand-ins that can be safely generated
Blocked or to-be-replaced assets: real people, official brand/logo/product images, fact-bearing screenshots that cannot be obtained, or any item that requires user input before fidelity can be achieved
Why it matters: what visual fidelity risk arises if the asset boundaries are judged incorrectly

Asset boundary rules

Use these rules when preparing the Step 3 asset breakdown checklist and the Step 4 asset generation review.

Once reference images exist, review them before writing code. Break each section down into exactly two asset layers plus code:

Code layer: layout, fonts, text, buttons, navigation, dividers, simple lines and shapes, coordinate labels, route lines, interactions, motion. Never bake them into images, and never leave them in background images.
Background layer: at most one full-width image per section. If the reference image has a complex background (scene, texture, gradient field, tonal band), generate it as a single image covering the entire section, including any dark or light bands that belong to the same composition. Do not split one continuous section background into multiple strips. If the background is just a solid color, a simple gradient, or simple lines, render it in code and do not generate an image.
Foreground assets: avatars, photos, hero illustrations, textured objects, handwritten cards, product screenshots, and other visual subjects that are difficult to implement in code. For each one, measure its geometry in the reference image: bounding box, aspect ratio, and approximate percentage of the section width. Generate the asset at that aspect ratio. Granularity follows the splitter skill: independent media slots each get their own asset—a portfolio section with three case product mocks needs three separately generated visuals, never one composite image—but a fused static decorative cluster (multiple cards sharing shadow, lighting, or texture continuity, with no independent interaction or replacement need) stays as one asset; do not cut it into one asset per card.

Use the splitter skill's principles to decide code-native vs. asset: the boundary is determined by interactivity and editability, not visual complexity.code-native(Code-native) is allowed only for parts composed entirely of the following elements: live text, solid-color fills, simple geometric strokes and borders, standard icons, and pure CSS gradients. If the reference image region shows a rendered device or screen mock, a photo, an illustration, handwriting or a sketch, a material texture, or a layered collage, then that region carries an asset — but beware the "panel trap": a colored container panel holding text cards is layout, not an image (the panel body and text cards stay in code; only the printed material, badges, or illustrations inside it that are truly difficult to implement with code become a small asset), and editable or factual text always returns to the code layer.

Keep the image layer minimal at the element level, rather than achieving it by deleting elements: text, navigation, buttons, and labels stay in code; the rendered visuals beneath and around them become assets. Do not turn an entire section into one image, and do not let the page become a full-page screenshot.

For each accepted reference image, record a reference-image-to-build mapping in the visible reproduction artifact:

参考图：01-hero.png
代码层：导航、大标题、副标题、CTA 组、头像框、佐证标签
背景素材：hero-finance-desk.png，16:9，全幅，允许深色叠加
前景素材：portrait.png 位于右侧 24% 宽；product-card-mock.png 位于下方中央 22% 宽
必须保留：深色书桌/照片氛围、左侧大标题尺度、右侧头像卡、绿色 CTA、顶部导航间距
允许偏差：生成的图表标签替换为代码渲染的确认文案
风险触发：真实公司标志或用户头像若尚未确认，需要明确批准

For each section, the mapping must include an asset decision table covering every meaningful visual element: element, role, code feasibility, fidelity risk if implemented in code, decision/status (ready、generate、find/copy、code-native、replace-later or blocked), source/action, and final path when known. If a section does not need any image assets, write 背景素材：无，代码原生 or 前景素材：无，代码原生 with a reason.

Record the result as an asset inventory (asset, layer, role, source, reference image bounding box, aspect ratio, relative size, code feasibility, fidelity risk if coded, status, final path), so that during reproduction each asset can be placed into a fixed-ratio container rather than letting the image's intrinsic size drive the layout.

Use this form for the step-three closing note:

当前进度：第三步 / 素材拆分清单
我已准备好：参考图到构建的映射、素材决策清单、以及初始素材清单。
请确认或修改：
1. 哪些元素保持代码原生
2. 哪些背景与前景素材应被生成、拷贝或稍后替换
3. 任何不得被生成的真实头像、logo、产品截图或官方素材
4. 我对模糊区域（静态装饰 vs 交互）所采取的交互假设，以及你是否更倾向于所列的备选拆分方案
确认后，我将进入第四步，只生成或整理已批准的素材。我还不会编辑页面代码。确认同时也授权我为已批准的素材生成分组启用并行子 agent；如果你更想串行，请说明。

Step 4: Asset Generation Review

After the asset split list is confirmed, only generate, copy, find, or organize approved assets. Then present the asset results and a concise reproduction brief for user review. Do not begin page code implementation until the user accepts this asset review.

The asset review should include:

The final path of each ready asset
The section and visible element each asset belongs to
Source: generated, user-provided, official/copied, code-native, or to be replaced
Check result: accepted, needs regeneration, weak but usable (with specified deviation), blocked, or placeholder to be replaced
Any prompt/source notes needed to reproduce the asset

Each image asset has only two legitimate sources:

Real assets already collected during the step-one intake, such as user photos, logos, product screenshots, or media. In step four, do not ask the user for new assets unless the user chooses to provide them; for anything still not provided by then, use a generated stand-in, a code-native placeholder, areplace-later marker, or, when fidelity would be misleading, a blocked status.
Fresh image generation anchored to the corresponding reference image region. Before writing any generation prompt, reopen the confirmed reference image and transcribe the target region into a visual inventory: scene type (paper-card collage / photographic scene / flat illustration / UI mock / texture field), each major object and its approximate position, the color scheme as hex values, lighting, materials, and the whitespace layout. The generation prompt must be written from this transcription—same scene type, same object inventory, same composition and color scheme—and must never be written from the asset name or a one-line summary in the breakdown list. If the image tool accepts an input image, also attach that reference image region as visual guidance. A prompt that only names the content category ("a creator at a desk with a notebook and cards") without a transcription is defective: it amounts to letting the model invent a different scene. For placeholder text inside the asset, ask for "abstract, unreadable placeholder blocks and scribbles"—do not use the word "greeked", as the image model may render it as literal Greek.

The accepted reference image is the build target and the QA baseline, never an asset source. Do not crop, screenshot, slice, or extract any region of the reference image into the build; cropping inherits low resolution, burned-in text, and broken edges. There is no extract state in the list. When a region of the reference image looks like an asset that is needed, regenerate that element from the reference image's visual description, or replace it with real source material.

Prepare all approved assets before the build of the corresponding section begins. Save them in the project asset directory under stable names, not raw generation IDs. Immediately after each asset is generated, check it side by side with its reference image region across five dimensions: scene type, object inventory (every major object from the transcription is present), composition and whitespace, color scheme and lighting, and the absence of any website text or navigation/button/UI frame burned in that must remain code-editable. A scene type mismatch (the reference image is a flat card collage but the generation is a photographic room scene), or two or more missing major objects, both trigger automatic regeneration—never present such an asset as ready. Regenerate other defects, or explicitly flag them in the asset review; do not use CSS blending, filters, or masks to cover up defects.

As long as any approved required asset is still in generate or find/copy, do not write page code. First resolve it to ready, change it with a reason and a user-visible note to code-native, mark it with an approved placeholder as replace-later, or pause on blocked .

When useful and authorized by the user, generate assets with parallel sub-agents, split by section or asset group. A sub-agent's output is not trustworthy until it has been checked in the parent session.

The replication brief replaces the earlier lightweight pre-build design note. Keep it short, and attach it in the asset review rather than setting up a separate standalone gate. It should lock down:

Current build owner and source: the installed frontend-app-builder skill path/name, or references/frontend-app-builder.md fallback
Key visual baseline and section order
Global frame: navigation, logo/wordmark treatment, header density, active states, mobile behavior
Font locks: heading, body, label, and navigation roles must remain consistent
Color lock: the exact hex tokens (primary, secondary, accent, neutral scale) sampled from accepted reference images and, where there are differences, from the actual pixels of the delivered assets — assets are burned in and expensive, code is cheap, so tokens follow the assets; the implementation must define these as design tokens and use only them, never re-eyeballing colors region by region
Required motion or interaction ideas: list only the effects that shape the experience
Final asset paths and the code/asset boundary
Allowed deviations: reference image conflicts, weak assets, mobile simplification, or intentional changes
QA targets: which reference image each rendered section must be checked against
Risk triggers: any item that requires a pause before code implementation

The Step 4 closing prompt uses this shape:

当前进度：第四步 / 素材生成评审
我已准备好：生成/采集的素材、最终素材路径、检查备注、以及复刻简报。
请确认或修改：
1. 接受这些素材和复刻简报，进入复刻
2. 重新生成或替换指定的素材
3. 在实现前改动任何代码/素材边界
确认后，我将进入第五步，用选定的 builder 契约开始高保真复刻。

Step 5: High-fidelity replication and QA

Implementation may begin only after the user accepts the asset review and the replication brief.

When entering Step 5, first select and declare the party responsible for the current build, then start implementing:

Preferred path: if the Build Web Apps frontend-app-builder skill is installed, read it and follow its Before Coding、Implementation、Verification、Final Response workflow to do a structured image-to-code replication; this skill supplies it with the content/style brief, accepted reference images, confirmed asset inventory, replication brief, and risk gates
Fallback path: if the installed builder is unavailable, read references/frontend-app-builder.md and follow that built-in replication contract

Do not let Step 5 turn into a generic hand-written page. The builder path must be visible in the replication brief and the final fidelity ledger.

Do not start implementation until every accepted reference image has a reference-to-build mapping, and every required visual asset is either ready, explicitly code-native, or marked replace-later with an approved placeholder. Do not let copied reference images sit idle as decorative evidence that "Step 2 happened"; either use them as comparison targets or break them down into real build inputs.

High-fidelity replication

Start implementation only after the reference images are accepted, the replication artifacts exist, all required assets are ready or explicitly approved as code-native/to-be-replaced, and the user has accepted the Step 4 asset review plus replication brief.

The build is governed by the builder contract, not this skill. When entering Step 5, read the installed Build Web Apps frontend-app-builder SKILL.md in full — if unavailable, read the Chinese translated version references/frontend-app-builder.md— and execute its Before Coding, Implementation, and Verification workflows as-is. The accepted reference images are its "accepted concept images"; this skill's replication artifacts, asset inventory, and replication brief are its inputs for design system extraction and implementation inventory. Where the two skills overlap, the stricter rule prevails. Do not re-derive a lighter build process from memory.

Before the first implementation edit, verify: the builder contract has been read in this session, the replication artifacts contain one reference-to-build mapping for each accepted reference image, every required asset is ready/code-native/with a named placeholder replace-later, and the target files and write scope have been specified.

On top of the builder contract, this skill adds only:

Place each asset in a container sized according to the aspect ratio and relative dimensions recorded in the inventory, and fit it with object-fit; never let the intrinsic dimensions of the image determine the layout
Set heading font sizes by measuring the reference image (heading height relative to section width), not by eyeballing
If a section's first render deviates noticeably from the reference image, stop and rebuild that section from the decomposition rather than doing surface-level patching

Sub-agent orchestration

For multi-section or multi-page builds, only parallelize bounded work after confirmation at the corresponding gate: reference image analysis after step two, asset generation after step three, implementation after step four. Use sub-agents for bounded work, not to let them each invent their own parallel design system.

Useful splits:

Reference image analysis agent: each handles one page or section group, producing the reference-to-build mapping and asset requirements
Asset generation agent: each handles one background/foreground asset group, producing stable filenames and prompt/source notes
Page or section replication agent: limited to non-overlapping write scopes, sharing design tokens and the reference images for that scope
Main integrator: responsible for the global frame, shared tokens, final assembly, browser QA, and the final fidelity ledger

Use Codex's native sub-agent tool:spawn_agent、wait_agent、close_agent. This tool itself only allows spawning when the user explicitly authorizes delegation. When requesting step-three or step-four confirmation, state whether the next phase will use parallel sub-agents; if the user declines, run serially.

Spawn with fork_context: false and give a self-contained message: which skills/reference files to read, reference image paths, exact output filenames, target aspect ratio, color hex values, and the return contract. For bounded write tasks (asset generation groups) use agent_type worker, and for read-only analysis use explorer. Collect with wait_agent , then inspect each sub-agent's output with view_image before use—a sub-agent's work is untrusted until verified.

Default split: once the asset manifest is ready, asset generation is parallelized across workers (each worker handles one section or asset group). Parallel section replication is only for multi-page sites with non-overlapping files; single-page builds stay in the parent session to avoid write conflicts. Do not let any sub-agent invent its own color, font, navigation, or motion rules.

Visual QA

QA is the builder contract's Verification workflow, run section by section: view_image to look at each accepted reference image side by side with the rendered section (not a single whole-page pass), screenshot at the reference image's native size when feasible, write the fidelity ledger, and treat the builder's hard stop items—including placeholder boxes and code-drawn stand-ins for conceptual assets—as failures. The checks below are additions to that workflow for personal-website, not a replacement.

When you need a local preview URL, prefer portless with a project-specific hostname, e.g. personal-site.localhost, and when appropriate add a small reusable script or portless.json. Only use a bare localhost:<port>。

when portless is unavailable or the user asks for a bare port. Checks:

Layout proportions and section rhythm
Font scale, line breaks, and spacing
No clipped or overflowing text, no element overlaps that don't exist in the reference image
Color and contrast
The numbers in the checklist are a contract: measure the width proportion each checklist asset occupies in its section after rendering (browser evaluate / getBoundingClientRect) and the headline font size, and compare them against the values in the checklist and reference image—a difference of more than a few percentage points is a defect to fix, not a difference in taste. In CSS, set asset dimensions using the same basis as the checklist (the section), and never quietly break the recorded percentages with nested containers or pixel caps.
Compare visual density section by section against the reference image: where the reference image has rendered mockups, textures, photos, or collages, rendering them as flat placeholder blocks is a fidelity failure, not an allowable deviation
Buttons, navigation, hover, and motion behavior
Consistency between mobile and desktop

Before handoff, write a brief section-by-section fidelity ledger: section, reference image file, anchors that must be preserved, rendering evidence, measured geometry vs checklist numbers, mismatches, and fixes or intentional deviations. Store it in the replication artifact or docs/fidelity-ledger.md—a ledger that exists only in chat does not count. If obvious mismatches remain, do another round of correction.

If the implemented page mainly matches a written theme rather than the accepted reference image, then QA fails even if the page works, looks good, or is internally consistent.

User confirmation checkpoints

Stop and request confirmation only at these default checkpoints:

After the complete content and style brief, before reference image prompts or image generation
After the reference image set and reference image review, before asset breakdown enters generation
After the asset breakdown checklist, before generating, copying, finding, or organizing new assets
After the generated/collected assets and replication brief, before page code implementation

Do not add a separate default checkpoint for the earlier lightweight pre-build design notes. It has been merged into the replication brief in step four. Users can override these checkpoints by asking for more control or fewer pauses.

Taste handling

The built-in taste samples are calibration, not an enforced style.

Use them when the user asks for a high-quality personal website but gives limited visual direction. If the user provides their own reference images, prioritize the user's images, and use the built-in samples only to avoid low-quality AI default aesthetics.

Do not force a dark blue cinematic style when the brief does not support it. Instead, extract the underlying taste principles: clean composition, controlled color palette, strong typography, cinematic pacing, good whitespace, and no meaningless visual clutter.