Back to Details

landing-site

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Landing site — purpose, UX, and design bar

着陆页——设计目标、用户体验与设计标准

The front door is 
site/
(Vite + React + Tailwind, dark-only), deployed to vigiles.sh. This skill is the standard every change is held to. The recurring failure it exists to stop: adding elements instead of removing them, which makes the page feel crowded and template-y ("tilda-like") instead of modern.
The one rule under all the others: when in doubt, REMOVE. Design by subtraction. If deleting an element loses no meaning, delete it. A change that adds a box, a caption, a second button, or a reassurance line is suspect until proven necessary.
着陆页对应代码目录为
site/
（基于Vite + React + Tailwind构建，仅支持深色模式），部署在vigiles.sh。本规范是所有变更需遵循的标准。它旨在避免反复出现的问题：盲目添加元素而非做减法，这种行为会让页面显得拥挤、模板化（类似Tilda风格），缺乏现代感。
所有规则之上的核心原则：存疑即删，以减法做设计。 如果删除某个元素不会丢失信息，那就删掉它。任何新增框体、说明文字、第二个按钮或安抚性语句的变更，在被证明必要前都应受到质疑。

Purpose (what the site is for)

设计目标（着陆页的用途）

  • Audience: developers who already live in agentic-coding tools (Claude Code, Codex, Cursor). They are skeptical and skim on a phone.
  • The one job: get them to run 
    npx vigiles audit
    (or adopt vigiles). The wow is the graded report — show the result, don't explain the mechanism.
  • Front-door promise: "Lighthouse for your agent harness" — a one-command, zero-config, nothing-uploaded grade of your skills/hooks/subagents/references.
  • 目标受众： 日常使用智能编码工具（Claude Code、Codex、Cursor）的开发者。他们持怀疑态度，且习惯在手机上快速浏览。
  • 核心任务： 引导他们执行
    npx vigiles audit
    命令（或采用vigiles工具）。核心亮点是分级报告——直接展示结果，无需解释实现机制。
  • 首页承诺： "Agent工具集的Lighthouse"——只需一条命令，零配置，无需上传任何内容，即可为你的skill/hooks/subagents/references生成评分。

UX requirements

用户体验要求

  • Command-first. 
    npx vigiles audit
    is the universal action (works on every OS, every terminal). It is THE primary CTA. Everything else is secondary.
  • The Claude Code deeplink (
    claude-cli://
    ) is a DESKTOP-ONLY enhancement    , never the primary path — it silently dead-ends on mobile / CC Web / desktop-without-CC. Render it only where it can work; never ship a button that does nothing.
  • Be honest on mobile. No dead buttons. Where a desktop-only action can't run, say so plainly and give the real action (the command) instead.
  • One primary action per screen. Secondary actions are quiet — a text link or a light pill, never a second heavy full-width button competing with the primary.
  • Harness-neutral. Say "Claude Code or Codex," don't lead with Claude Code — it's an implementation detail, not the headline. Don't over-explain internals.
  • Low-friction + welcoming. A skimmer should understand what it is and how to try it within one screen, without reading a wall.
  • 命令优先。 
    npx vigiles audit
    是通用操作（适用于所有操作系统、所有终端），是唯一的主要CTA。其他所有操作均为次要。
  • Claude Code深度链接(
    claude-cli://
    )仅为桌面端增强功能    ，绝不能作为主要路径——它在移动端、Claude Code网页版、未安装Claude Code的桌面端会静默失效。仅在能正常运行的环境中渲染该链接；绝不发布无功能的按钮。
  • 移动端如实展示。 无失效按钮。当桌面端专属操作无法在移动端执行时，需清晰说明并提供替代操作（即命令）。
  • 每屏仅一个主要操作。 次要操作需低调呈现——采用文本链接或轻量化胶囊按钮，绝不能使用第二个醒目的全宽按钮与主要CTA竞争。
  • 工具集中立。 表述为"Claude Code或Codex"，而非以Claude Code为核心——这只是实现细节，并非核心卖点。无需过度解释内部机制。
  • 低门槛+友好性。 快速浏览者应能在一屏内理解产品用途及试用方式，无需阅读大段文字。

Design bar — modern & minimal (the anti-crowding rules)

设计标准——现代极简（反拥挤规则）

Reference the feel of Linear / Vercel / Raycast: confident dark, generous space, few words, one clear focal point per section. NOT a feature-stuffed template.
  • Every element must earn its place. Remove anything that only restates another (a caption repeating the screenshot; a trust line said twice; a redundant subhead).
  • Cut any label another element already IMPLIES. A "free & open source" badge is redundant when a GitHub/star link is present; an "AUDIT A SPECIFIC REPO" badge above a "Grade a specific repo" heading restates it. If the context already tells the reader, the label is noise.
  • Every link/CTA is ACTIONABLE and specific. The reader must know exactly what happens on click. No vague or passive secondary links ("Have Claude Code?…"). If a secondary path isn't worth a clear, concrete action, cut it (or move it to the nav, where a persistent link beats a limp fold link).
  • One focal point per section. The eye should land on one thing first.
  • Whitespace + typography over boxes. Don't stack 3+ full-width bordered boxes; that repetition is what reads as crowded. Prefer type hierarchy and space to borders. But whitespace must be intentional — no near-empty viewport voids either.
  • Reassurance once, in one line. Trust copy ("nothing uploaded") appears once, compact — never a 3-line paragraph, never repeated per section.
  • Cohesion. The hero (badge + headline + subhead + visual) must read as ONE idea, each part adding new information. If the subhead just says what the screenshot already shows, cut or sharpen it.
  • Restraint in color/emphasis. One accent, semantic band colors that always mean something (grade bands). Bold one phrase per point, not every clause. No decorative emoji confetti.
  • Consistent spacing scale. Don't hand-tune one-off margins that fight the rhythm.
参考Linear / Vercel / Raycast的风格：自信的深色模式、充足留白、精简文字、每个板块有一个明确的视觉焦点。绝非堆砌功能的模板。
  • 每个元素都需证明自身存在的价值。 删除任何重复表述的内容（比如截图下方重复截图内容的说明文字、重复出现的信任声明、冗余的副标题）。
  • 删除已有元素可暗示的标签。 当存在GitHub/星标链接时，"免费开源"徽章是冗余的；在"为指定仓库评分"标题上方添加"AUDIT A SPECIFIC REPO"徽章属于重复表述。如果上下文已能让读者理解，该标签就是冗余信息。
  • 每个链接/CTA都需具备可操作性且明确。 读者必须清楚点击后会发生什么。禁止模糊或被动的次要链接（如"使用Claude Code？…"）。如果次要路径不值得设置清晰、具体的操作，就删掉它（或移至导航栏，持久化链接比折叠式弱链接效果更好）。
  • 每个板块一个视觉焦点。 用户的视线应首先落在一个核心元素上。
  • 用留白+排版替代框体。 不要堆叠3个以上全宽带边框的框体；这种重复会让页面显得拥挤。优先通过排版层级和留白区分内容，而非边框。但留白需有目的性——避免出现近乎空白的视窗区域。
  • 信任声明仅出现一次，且精简为一行。 信任文案（如"无内容上传"）需紧凑呈现，仅出现一次——绝不能写成3行段落，也不要在每个板块重复。
  • 内容连贯性。 首屏区块（徽章+标题+副标题+视觉元素）需表达一个完整的核心观点，每个部分都要补充新信息。如果副标题只是重复截图内容，就删掉或优化它。
  • 色彩/强调需克制。 仅使用一种主强调色，语义化色块需始终代表特定含义（如评分等级色块）。每个要点仅加粗一个短语，而非每个从句。禁止使用装饰性表情符号。
  • 间距规范一致。 不要手动调整孤立的边距，破坏整体布局节奏。

Anti-patterns (things that have gone wrong here)

反模式（曾出现过的错误）

  • Stacking input + big button + 3-line trust + divider + command + caption + another button on one fold. (Fix: keep ~3 elements, cut the rest.)
  • A caption under the product shot restating the product shot.
  • Adding a notice/button per problem instead of rethinking the flow.
  • Two competing primary CTAs (deeplink + command) with no hierarchy.
  • CC-first framing ("runs in your own Claude Code…") as the headline reassurance.
  • 在一屏内堆叠输入框+大按钮+3行信任声明+分隔线+命令+说明文字+另一个按钮。（修复方案：保留约3个元素，删除其余内容。）
  • 产品截图下方的说明文字重复截图内容。
  • 针对每个问题新增提示/按钮，而非重新梳理流程。
  • 两个相互竞争的主要CTA（深度链接+命令），无层级区分。
  • 以Claude Code为核心的表述（如"在你的Claude Code中运行…"）作为首屏信任声明。

Hosted / in-browser demo (direction, when built)

托管/浏览器内演示（构建方向）

  • Deterministic-only compute. Run the model-free rings (Truthfulness / Structure / Safety-via-lethal-trifecta / description-overlap). Skip the model-gated trigger-rate — that's the part that needs an LLM + quota.
  • Prefer in-browser (runs in the visitor's browser → reinforces "nothing leaves your machine"; zero backend/cost). Fallback: cached serverless keyed by 
    repo@commit-SHA
    + per-IP rate-limit.
  • A real progress bar / streaming state while the audit runs — fetching files, running each ring — never a dead spinner. It should feel like work is happening.
  • TEASE the locked LLM part, don't just label it "limited." Render the trigger-rate / model-gated section in the result as blurred / locked (a gated-content pattern) with an "unlock by running it locally" affordance — make people curious to run 
    npx vigiles audit
    for the full report (trigger-rate, linter cross-ref, private repos). The deterministic rings show real numbers; the model-gated section is present but veiled.
  • Reuse the real report components (render from the 
    AuditReport
    JSON) — never a screenshot. This is why the report view must live in a SHARED package (see below).
  • 仅支持确定性计算。 运行无需模型的检测项（真实性/结构/三重安全机制/描述重叠）。跳过依赖模型的触发率检测——该部分需要LLM及配额支持。
  • 优先浏览器内运行（在访客浏览器中运行→强化"无内容离开你的设备"的信任点；零后端/成本）。备选方案：基于
    repo@commit-SHA
    缓存的无服务器方案+按IP限流。
  • 审计运行时展示真实进度条/流式状态——包括文件获取、每个检测项的运行过程——绝不使用静态加载动画。需让用户感受到正在处理任务。
  • 对受LLM限制的部分进行引导，而非仅标注"受限"。 在结果中，将触发率/依赖模型的部分渲染为模糊/锁定状态（ gated-content模式），并添加"通过本地运行解锁"的提示——激发用户的好奇心，促使他们执行
    npx vigiles audit
    获取完整报告（触发率、代码检查器交叉引用、私有仓库支持）。确定性检测项展示真实数据；依赖模型的部分需呈现但处于隐藏状态。
  • 复用真实报告组件（基于
    AuditReport
    JSON渲染）——绝不使用截图。这就是为什么报告视图必须放在共享包中（见下文）。

Repo structure for shared UI (no hacks)

共享UI的仓库结构（禁止临时方案）

The audit report (
report/
) and the landing site (
site/
) — and the future demo — share the same shadcn primitives, the 
AuditReport
schema, and the report view. These must be genuinely shared via a workspace package, not duplicated or cross-imported by relative path. Target: npm workspaces + a 
packages/
dir (e.g. a shared 
@vigiles/ui
primitives package and a 
@vigiles/report-view
package that renders an 
AuditReport
), consumed by 
report/
, 
site/
, and the demo. The root 
vigiles
published package + its CI gates (api-surface, coverage) must stay green — workspaces coexist, they don't replace the root package. Do this as its own reviewed change, not bolted onto a design pass.
审计报告（
report/
）、着陆页（
site/
）及未来的演示页面需共享相同的shadcn基础组件、
AuditReport
schema及报告视图。这些内容必须通过工作区包真正共享，而非复制或通过相对路径跨目录导入。目标：使用npm workspaces + 
packages/
目录（例如，共享的
@vigiles/ui
基础组件包和渲染
AuditReport
的
@vigiles/report-view
包），供
report/
、
site/
及演示页面使用。根目录下发布的
vigiles
包及其CI校验（API接口、覆盖率）需保持正常——工作区与根包共存，而非替代根包。需将此作为独立的审核变更，而非附加在设计优化中。

Process — before shipping any site change

发布着陆页变更前的流程

  1. Hold it against this bar. Ask "what can I remove?" before "what can I add?"
  2. Screenshot desktop AND mobile (390px) and actually look — most crowding shows up on the phone fold. (Global playwright + 
    vite preview
    ; or the 
    screenshot
    skill.)
  3. Run a Fable blind pass for anything nontrivial — fresh skeptical eyes catch crowding and incoherence the author is blind to. Act on the flagged cuts — a Fable P0/P1 "delete this" is not optional; don't just note it and move on.
  4. Verify build + Prettier clean; deterministic deploy via 
    pages.yml
    on push to main.
  1. 对照本规范校验。 在思考"可以添加什么"前，先问"可以删除什么"。
  2. 截取桌面端和移动端（390px）截图并仔细检查——大多数拥挤问题会在手机首屏显现。（可使用全局playwright + 
    vite preview
    ；或
    screenshot
    工具。）
  3. 对于重要变更，执行Fable盲审——新鲜的第三方视角能发现作者自身忽略的拥挤和不连贯问题。必须根据盲审建议删除内容——Fable标记为P0/P1的"删除此项"要求是强制性的，不能仅记录而不执行。
  4. 验证构建+Prettier格式化是否正常；通过
    pages.yml
    在推送到main分支时执行确定性部署。