Proofcraft

> Portfolio sites, developer homepages, project case studies.
> Goal: being believed. The failure this prevents is a beautiful site full of claims nobody can verify.

Resources (load only when the phase needs them):
- references/style-library.md — 12 committable design directions with tokens
- references/evidence-workflow.md — locate → verify → extract → regenerate → complete
- scripts/capture.mjs — config-driven screenshot and video capture

0. THE CORE PRINCIPLE

A portfolio fails in two independent ways:

1. Looks templated — design skills solve this.
2. Reads as unverifiable — this skill solves this.

Most work over-invests in (1). But a reader who cannot verify one claim discounts every claim on the page. Evidence is not decoration; it is the product.

The rule: every number and outcome traces to something a stranger can open, or is explicitly marked unverified.

1. ASK WHEN UNCERTAIN (Read Before Acting)

Portfolio work runs on facts only the user holds: who did what, what may be published, whose name is on the archive. Guessing these produces confident, wrong, and sometimes professionally damaging output. A wrong guess costs more than a question.

1.A Must ask — never infer

These are not style preferences. Getting them wrong misrepresents the user or leaks something.

1.B Ask once, then proceed

When the brief genuinely diverges and both paths are defensible, ask one focused question with concrete options. Do not send a questionnaire.

Good: 「参考站的项目区其实是空模板，你的站有 8 个真实案例。你要我只取它缺的板块，还是整体照它重做？」

Bad: a five-question dump about fonts, colors, spacing, motion, and layout.

1.C Do NOT ask — decide and report

Asking about things you can determine yourself wastes the user's attention and reads as helplessness.

• Anything discoverable by reading a file, running git log, or fetching a URL → go look
• Reversible aesthetic choices (shadow depth, particle density) → pick a sane default, state it, offer to tune
• Which of two equivalent implementations → choose, explain in one line

The test: could I answer this myself in under two minutes with the tools I have? If yes, do that instead.

1.D When the user's premise is wrong

Do not silently comply and do not just refuse. State the finding, then offer the corrected path:

> 参考站的「玻璃质感」全站只有一处 backdrop-filter，它显高级靠的是深色底。你的站是暖纸白底，直接移植会糊。我可以只在导航栏用玻璃（那里前提成立），再用分层材质解决你说的「单调」。

Then ask which they want, if the choice is real.

1.E Flag uncertainty in the output itself

When shipping something built on an assumption you could not verify, say so in the delivery message, not silently:

> 注：煤矿项目材料里出现了另一位同学的名字，我按团队项目处理，只写了你负责的模块。如果分工不是这样告诉我。

2. ORDER OF WORK

Do not start with visuals. Evidence determines structure, and structure determines design.

1  Locate     where each project actually lives       → evidence-workflow.md §1
2  Triage     is it worth running? clone if needed    → §1.4-1.5
3  Boundary   what may be published                   → §3 below
4  Structure  which cases, ranked by evidence strength
5  Style      pick ONE direction                      → style-library.md
6  Run        bring it up, seed it (only if triaged)  → evidence-workflow.md §3.5
7  Capture    make screenshots regenerable            → scripts/capture.mjs
8  Build      implement
9  Gate       E2E tests that assert the promises      → §7 below
10 Verify     live URLs after deploy                  → §8 below

Skipping 1–4 produces a well-designed site that says nothing.

Where the material lives

Work is scattered, and each location has different rules:

Check before planning: git -C <repo> remote -v. An internal IP or corporate hostname means §3 boundaries apply and the UI must not be captured.

Run it, or honestly say you did not

Screenshotting a live system is the strongest evidence, but the cost varies enormously. Static prototype: minutes. Multi-service backend with DB, cache, and broker: hours, and often blocked by private dependencies.

Decide before starting, and timebox to ~20 minutes. When you choose not to run, that is a legitimate outcome — state it:

> 该平台需要 MySQL + Kafka 才能起来，本轮未实跑；页面使用结项材料中的真实截图，已标注来源。

Never run an unfamiliar project against a real database, and never capture real customer or classmate data as seed content.

3. PUBLICATION BOUNDARIES (Non-negotiable)

Never publish

• Company source code, even a snippet, without explicit authorization
• Internal Git URLs, hostnames, IPs, ticket text
• Customer data, production config, credentials
• ID documents, student cards, anything with an ID number
• Teammates' names without consent

Safe enterprise pattern

Publish instead: real commit hash + date + subject, sanitized minimal diff, change statistics (4 files, +6254/-6250), redrawn diagrams.

Then state the boundary on the page:

> 这是企业项目，页面上只写可授权公开的产品方向、技术栈与工作方法，不涉及公司源代码、内网仓库、客户信息、工单原文与生产环境配置。

This paragraph increases credibility. It shows the author knows where the lines are.

Team projects

If a directory or archive carries another person's name, do not present the project as solely the user's. Ask who did what, or scope the claim to a specific module.

4. THE EVIDENCE LADDER

Tier D is where credibility is won. Do not silently delete and do not inflate:

> 评测以原始数据集、指标口径与运行记录为准。完整对比结果将随原始评测报告一并公开。

Numbers discipline

Never publish a precise metric without script, environment, sample size, and original report. Report the honest figure: if 61 commits become 47 after removing merges and packaging, write 47. The smaller true number outperforms the bigger soft one.

This applies to incoming claims too. A forwarded statistic ("67 UI styles, 161 palettes") is marketing copy until verified — the real figures for that project are 79 styles / 192 product types.

5. STYLE SELECTION

Load references/style-library.md. Pick one direction by audience, not taste.

Fast path for a developer portfolio: 01 Warm Paper Editorial, 02 Swiss Technical, or 05 Quiet Luxe Mono.

Then lock three things globally and audit every component against them:
- Accent — one only, used identically everywhere
- Radius — one scale (all-sharp, all-soft, or all-pill)
- Shadow — one language (hard-offset or soft-blur, never mixed)

Universal bans

AI-purple #7C3AED; violet→blue gradients; Inter as default display face; three equal feature cards; glassmorphism over flat light backgrounds; mixed radii.

Texture before effects

The most common cause of "looks cheap" is a large flat color field. Add grid, grain, and tonal banding between sections before reaching for animation.

Capture, do not hand-make

Screenshots taken by hand rot: the UI changes, the images do not. Copy scripts/capture.mjs into the project, describe the shots in capture.config.json, and wire npm run capture. The config becomes the written statement of what each image shows.

Verify selectors against the live DOM before writing the config — class names drift across redesigns, and a stale waitFor is the most common failure. The script isolates failures per shot and exits non-zero, so one bad selector never costs the whole batch.

6. ADOPTING A REFERENCE SITE

Users send a link and say "make mine like this." Do not copy. Diagnose.

5.1 Inspect, do not infer

Fetch its CSS/JS and read the live DOM. For canvas effects, sample rendered pixels for colour and density, and diff the alpha sum after a pointer move to confirm interactivity.

5.2 Separate the effect from its precondition

An effect usually depends on a property the user's site lacks. Worked example:

• Request: "add the glass texture from this site"
• Reality: the reference had exactly one backdrop-filter, on its scrolled header
• It read premium because of dark base + soft shadows + 16px radius, not glass
• The user's site was warm paper + hard shadows + zero radius
• blur() over a flat light background refracts nothing → the port fails

Correct move: apply the effect only where its precondition holds (a sticky header genuinely has content scrolling behind it), and solve the user's actual complaint (a monotonous flat background) with the right tool (layered gradients, grain, tonal banding).

5.3 Check the reference is actually better

Reference sites are often templates with unfilled placeholders (项目一, 你的下一个项目). If the user's site has real content and the reference does not, adopting its structure is a downgrade. Say so, and take only the genuinely missing sections.

7. QUALITY GATE

Portfolios get edited across many sessions; without a gate, earlier guarantees silently vanish.

Test the build output, not the dev server

webServer: {
  command: 'npm run preview -- --host 127.0.0.1 --port 4322',
  url: 'http://127.0.0.1:4322',
  reuseExistingServer: !process.env.CI
}

Do not import framework page-data modules into tests. In Astro, a data module pulls in astro:assets image imports and the runner tries to parse .webp as JavaScript. Derive routes from dist/ — which also guarantees you test what deploys:

function routesUnder(dir: string, prefix: string): string[] {
  const full = join(process.cwd(), 'dist', dir);
  if (!existsSync(full)) return [];
  return readdirSync(full, { withFileTypes: true })
    .filter((e) => e.isDirectory()).map((e) => `${prefix}${e.name}/`);
}

What to assert

Assert substance, not wording

expect(body).toContain('披露之界');                       // brittle: breaks on rename
expect(body).toMatch(/公开范围|披露|不涉及公司源代码/);      // durable: the promise must survive

A test pinned to exact copy produces false alarms that look like content regressions.

Gate the deploy

Run tests before uploading the artifact so failures block publication.

- run: npm run build
- run: npx playwright install --with-deps chromium
- run: npm test
- uses: actions/upload-artifact@v4
  if: failure()
  with: { name: playwright-report, path: playwright-report/ }
- uses: actions/upload-pages-artifact@v3

8. VERIFY LIVE

A green local build is not a shipped feature. After deploy check the real URL:

• Each new route returns 200
• New media returns correct Content-Type and non-trivial size
• New content strings appear in the served HTML
• CSS tokens live in hashed chunks. A token may sit in a shared chunk, not the page-named one. Extract the <link> hrefs and check the right file before concluding a change did not ship.

Environment traps that fake failures: in PowerShell $home is read-only, so $home = Invoke-WebRequest ... silently leaves it empty and every check returns False. Use another variable name.

9. LONG-LIVED REPOS

Portfolio repos get touched between sessions.

git log --oneline -5
git status --short --branch

If commits landed that you did not make, read the current file before editing. Edits based on remembered content conflict or silently overwrite. When your earlier change has already been superseded by better work, say so and keep the better version.

Before committing, scan git status for stray artifacts: inspection scripts, reference screenshots, test-results/, temp PNGs. Gitignore generated output:

test-results/
playwright-report/
.capture-raw/

10. HONESTY WHEN SOURCES ARE WRONG

Users forward video and article summaries containing install commands and statistics. Two obligations in tension:

1. Do not run unverified install commands or repeat unverifiable numbers as fact.
2. Do not dismiss an entire source because part of it is unverified.

Verify before doubting. Packages dismissed as fictional have turned out to be real repositories while their precise statistics remained unverifiable. When you over-doubt, correct yourself explicitly.

Then extract the actionable core. If a suggested tool does not fit the stack (a React-specific skill on an Astro zero-JS site), explain why and deliver the capability it promised by a route that does fit.

11. PRE-FLIGHT CHECK

• [ ] Every must-ask trigger (§1.A) either asked, or genuinely absent?
• [ ] Any unverified assumption flagged in the delivery message, not left silent?
• [ ] Each project resolved to a location (public / local / internal / archive) before planning evidence?
• [ ] Scratch clones gitignored and removed; no containers left running?
• [ ] Seed data invented, never real customer or classmate records?
• [ ] Where a project was not run, is that stated with the fallback source named?
• [ ] Every metric traces to a script/report, or is marked unverified?
• [ ] Every screenshot's provenance known and labeled (real / prototype / mock)?
• [ ] No company source, internal URLs, customer data, or ID documents?
• [ ] Team projects scoped to the user's actual contribution?
• [ ] Enterprise cases carry an on-page boundary note?
• [ ] Screenshots regenerable via capture config, not hand-made one-offs?
• [ ] Videos ≤ 60s, MP4+WebM, poster, transcript, < 1MB?
• [ ] Images WebP with explicit dimensions, lazy below the fold?
• [ ] Exactly one style direction; accent/radius/shadow locked?
• [ ] Accent is not AI-purple; no gradient-blob background?
• [ ] Texture present — no large flat untreated color fields?
• [ ] No empty placeholder sections?
• [ ] Inward-facing coding rules removed or rewritten outward?
• [ ] E2E asserts substance, runs against dist/, gates the deploy?
• [ ] Live URLs verified after deploy, including media Content-Type?
• [ ] Repo clean of inspection scripts and temp artifacts?

If a box cannot be honestly ticked, the work is not done.