返回资讯中心
外部精选
软件工程
#开发者实时流

Replacing Design.md with DESIGN.html

Build an interactive HTML reference. Preserve its markup and CSS when you wire it into your app. Check what actually changed in the browser.

Hacker News 最新giminycricket02026/10/17 · 2026/10/1715 分钟阅读

以下正文同步自 Hacker News 最新,版权归原站所有,已转换为易读排版。

Keep the UI you designed.

Build an interactive HTML reference. Preserve its markup and CSS when you wire it into your app. Check what actually changed in the browser.

HTML-first design · Explicit UI states · DOM, style and geometry checks · Actionable drift reports

Try the examples · How it works · Agent skill · Verification guide · Scorecrowd lessons

The comparison playground puts Reference, Corrected, and Intentional drift together. Switch between checkout and a sports interface, then choose a phone, tablet or desktop viewport.

Open examples/compare.html locally after cloning. Each preview has its own real layout viewport and a full-size link. GitHub shows the HTML source; it does not run the playground.

The sports example uses fictional clubs, scores and times. It demonstrates lessons from Scorecrowd; it is not a screenshot or verification of the production app.

A working HTML design can drift when an agent replaces exact spacing with nearby utility sizes, adds a wrapper, drops an icon or forgets a loading attribute. A successful build does not catch those changes.

Transplant the presentation; bind the behavior; verify the result. Preserve DOM hierarchy, CSS values, tokens and assets. Let the framework own state and events without also redesigning the interface.

Direct transplantation reduces opportunities for drift. Host styles, fonts, content, viewport constraints and lifecycle behavior can still change the result, so verification remains part of the workflow.

Use a current Node.js LTS release and npm. Clone this repository; these instructions do not depend on an npm registry release.

git clone https://github.com/giminycricket0-blip/design-html.git cd design-html npm ci npx playwright install chromium --only-shell

Open examples/compare.html in your browser for all three versions. No server, API key or external font is needed for the examples.

npm run demo:verify

It succeeds only when the underlying verifier fails for the expected reasons and catches all four seeded defects. The report is saved as .design-html-drift.json.

For responsive layouts, refresh behavior and dialog closure:

npm run demo:scorecrowd npm test

The sports demo checks 390×844, 768×1024 and 1440×900, plus focused refresh, closing-dialog, focus-restoration and reduced-motion journeys. The corrected examples must pass against the unchanged reference.

In another project, use the absolute path to this cloned CLI.

node /path/to/design-html/bin/cli.mjs init node /path/to/design-html/bin/cli.mjs open node /path/to/design-html/bin/cli.mjs extract checkout-card --viewport 390x844 node /path/to/design-html/bin/cli.mjs verify http://localhost:3000/checkout --viewport 390x844

init preserves an existing reference and installs the teaching skill. It adds or refreshes its marked rule block in AGENTS.md, CLAUDE.md and an existing .cursorrules, keeping surrounding instructions intact.

The app must supply matching fixtures; the CLI does not manufacture backend or authentication states.

The bundled Prototype to App skill teaches the work around the verifier: how to design the reference, transplant its presentation, wire behavior and check the result.

Run init from your app's root. It copies the self-contained skill to .agents/skills/prototype-to-app/ and points the agent instructions there. No personal skill folder or Scorecrowd checkout is needed.

In a harness that discovers this skill, invoke $prototype-to-app. Otherwise, ask the agent to read the file directly:

Read .agents/skills/prototype-to-app/SKILL.md. Transplant the approved checkout from DESIGN.html into the existing app. Preserve its DOM, CSS, state identities and assets; bind real behavior, then verify the agreed states and viewports.

The existing DESIGN.html template is the starting reference; checkout and sports examples teach the static and interactive checks. The skill adds instructions, not a second UI framework or an automatic converter.

Repeated init calls preserve any installed skill, including local edits. It updates only its own delimited instruction block. An incomplete block or a conflicting skill path stops initialization for manual resolution.

Check Examples

DOM and text Missing icons, changed tags, child order, SVG paths and altered copy.

Semantics Missing disabled, aria-busy, roles, labels or link attributes.

Computed styles Changed typography, padding, borders, colors, shadows or overflow.

Geometry Width, height and child position relative to the parent.

Token guidance Matching root CSS variables for the expected value; ambiguity stays explicit.

Incomplete checks Missing states, duplicate targets and empty selections fail.

Each failure records the element path, expected and actual values, selected viewport and reference HTML hash. See the verification guide for the JSON format, command options and report lifecycle.

This is an early CLI and HTML playground. The examples are HTML-to-HTML. Automatic React conversion, durable annotations and direct coding-harness integrations are future work.

The generic verifier uses Chromium, a defined property list and a 1px geometry tolerance. It does not inspect every CSS property, image pixel, pseudo-element, shadow tree or interaction.

Behavior needs explicit journeys, as the sports demo illustrates. A pass describes the checked states and viewport; it is not a guarantee of universal visual, behavioral or native-app parity.

Verification guide: commands, contracts, reports and limitations.

Scorecrowd case study: concrete failures, executable checks and next increments.

Agent skill and repository rules: authoring, transplantation, verification and evidence requirements.

Open an issue: include a minimal reference, app fixture, viewport and drift report. Remove private data first.

The next useful increments are a real React transplant example, durable annotations and visual/temporal comparison. Contributions should preserve the reference and add a focused failing-and-passing case.

正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。

打开原文
去社区讨论 →