SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsprd-grade-fe

prd-grade-fe

Frontend & websites

View repository

Updated 10-16 01:08

About this skill

prd-grade-fe

$SKILL below = Base directory of this skill (the line "Base directory for this skill" when the skill is loaded; in the framework repo it is skills/prd-grade-fe). Every script and reference ships with the skill directory, independent of the repo.

Thin hub. Does not own design rules: aesthetics belong to hallmark (skills/hallmark/SKILL.md), deterministic rules belong to impeccable (npx -y impeccable@3.6.1 detect, hard pin). The hub owns order and contracts between phases, plus two scripts with --self-test:

File Role
scripts/design-sync.py design.md is the source of truth: block css :root{} → frontmatter YAML (impeccable reads) + tokens.css. --check rc 1 on drift.
scripts/fe-gate.sh Gate before delivery: assert target exists → detect --json → rc 0/1/2 with correct meaning → viewport-check.mjs 320/375/414/768. Exit 0 green · 1 impeccable error · 2 red finding/viewport · 3 skipped (missing node/network) · 4 missing target.
scripts/badge-consistency.py A deterministic rule impeccable does not have (GH#164): within ONE file, status badges (render*Badge/*Status*/*Pill*/span pill) must share the same icon-or-dot signature · rounded-* · token constant (STATUS_GLASS); badges deviating from the majority (≥2) → file:line, fe-gate counts it as finding rc 2.
references/presets/macos-glass.design.md The default preset has passed detect rc 0; evidence in macos-glass.evidence.md.
references/intake.md Route A/B/C → design.md.
references/impeccable-audit.md Audit rubric (5 axes /20) · harden · polish, distill with sources.

WHAT

Purpose and context

  • Purpose: to produce a production-grade frontend page/screen with a GUARD GATE — theme locked to ONE design.md, built token-only per hallmark, not delivered while fe-gate.sh is not green and P0 is not = 0.
  • Trigger (when to use) — item ## When to use old:
    • User wants a frontend page/screen brought into production, not a quick mockup (quick mockup → /br or bare hallmark).
    • User gives the theme as "just use the default", "here is the design doc", or "make it look like this page: ".
    • Project already has design.md and needs more screens in the same system with a check gate.
  • Non-goals: not a quick mockup (→ /br or bare hallmark); does not own design rules (aesthetics = hallmark, deterministic rules = impeccable); does not handle the BR→frame pipeline.

Mental model

nguồn theme (A preset · B tài liệu · C URL) → design.md (nguồn chân lý) → design-sync.py → tokens.css + frontmatter → build token-only (hallmark) → fe-gate.sh (impeccable detect + badge-consistency + 4 viewport) → audit/harden/polish → report. The hub owns order and contracts between phases; the rules live in hallmark/impeccable.

Input and output contract

Field Required? Meaning
In brief page/screen yes thing to build
In theme source A/B/C, audience, use case, tone no "go ahead"/empty → A + infer 2–4 words from brief, announce one sentence
In design.md available no yes + --check rc 0 → reuse, jump to Phase 3
Out design.md + tokens.css synced yes design-sync.py --check rc 0
Out token-only HTML output with design stamp + critique yes light/dark toggle, relative path footer
Out fe-gate.report.json + report 8 items (Phase 5) yes "production ready" only when fe-gate exit 0 and P0 = 0

Rules and capabilities

  • RULE-01 (MUST): Do not copy hallmark rubric here; to change a rule, change it in hallmark or references/impeccable-audit.md (with source + sha).
  • RULE-02 (MUST): Never call npx impeccable install (version 3.6.1 does not have --help for install, it actually installs into $HOME). --scope always write stuck together (--scope=type). Trust JSON on stdout, do not trust stderr (npx merges streams).
  • RULE-03 (MUST): If fix loop exceeds 3 and findings remain → deliver with residual table and say it straight; or waiver with reason in .impeccable/config.json ({"ignores":[...]}) stated in the report. Do not silently ignore.
  • RULE-04 (MUST): Missing node/network → report notes skipped: <lý do>, exit gate ≠ 0. No "probably fine" exception.
  • RULE-05 (MUST): design.md already exists → do not overwrite; to change system, AMEND ## Variants (no-overwrite policy of hallmark design-md).
  • RULE-06 (MUST): Self-check when editing skill: python3 $SKILL/scripts/design-sync.py --self-test && python3 $SKILL/scripts/badge-consistency.py --self-test && bash $SKILL/scripts/fe-gate.sh --self-test, then bash fdk/tools/sync-skill.sh prd-grade-fe.
  • Capabilities: read/write design files + output in project; run token sync script and deterministic antipattern detection gate (pin version); control headless browser to measure 4 viewports; read URLs/design documents as theme source.

Failure boundaries

  • Missing node/network → skipped: <lý do>, gate exit ≠ 0, report does NOT say clean (partial).
  • fe-gate rc 1 / 3 / 4 → blocked, stop, record cause; there is no path from 1/3/4 to "clean".
  • rc 2 after 3 fix loops → partial: deliver with residual findings table or waiver with reason stated in report.
  • design-sync.py --check rc 1 (drift) → do not proceed to Phase 3.
  • User demands theme change when design.md already exists → AMEND ## Variants, do not overwrite.

HOW

Main workflow

Step Type Inputs Action Outputs/exit Failure/next
W01 deterministic project Phase 0 pre-flight: ls design.md …, command -v node, design-sync.py --check whether the system is already locked, whether a node exists locked → B01; no node → B02
W02 judgment brief Phase 1 interview ONE message (source theme · audience · use case · tone) answer or published inference —
W03 effect source theme Phase 2 lock variables A/B/C → design.md → design-sync.py && --check rc 0 rc 1 → fix drift
W04 effect design.md Phase 3 build according to hallmark, token-only, stamp at top of file HTML output critique axis < 3 → fix before W05
W05 deterministic output Phase 4 gate: fe-gate.sh (≤ 3 rounds) → audit /20 → harden/polish → slop-test → fe-gate final time exit 0 + P0 = 0 rc 1/3/4 → blocked; rc 2 after 3 rounds → partial
W06 judgment result Phase 5 deliver + report 8 sections report —

Details of each step (source of truth for W01–W06) — section ## Steps old, verbatim:

Phase 0 — Pre-flight (do not ask what the machine can see for itself)

ls design.md DESIGN.md tokens.css 2>/dev/null; command -v node && echo node-ok
python3 $SKILL/scripts/design-sync.py --check 2>/dev/null; echo sync-rc=$?
  • Has design.md and --check rc 0 → say "system is already locked, reuse it" and skip to Phase 3 (unless the user demands a theme change → references/intake.md § "When the project already has design.md").
  • No node → still do Phases 1–3, but Phase 4 will record skipped and the report must NOT say clean.

Phase 1 — Interview ONE message (combine hallmark questions, do not ask follow-ups)

Before building, 4 things are needed. Answer whichever parts you like, or say "go ahead":

  1. Theme source — [A] default macOS glass · [B] design document path (file/folder) · [C] target page URL
  2. Audience — who uses it, what do they already know?
  3. Use case — one action this page must lead to?
  4. Tone — choose one pole: editorial · brutalist · soft · utilitarian · luxury · playful · technical · austere

"go ahead" or left blank → choose A, infer 2–4 from the brief, publish the inference in one sentence at the top of the reply (hallmark Step 1 opt-out protocol). There is no exception for "the brief is already clear enough": still ask, the user waves it through in two seconds.

Phase 2 — Lock variables (references/intake.md)

  • A: cp $SKILL/references/presets/macos-glass.design.md ./design.md, rename the project on the first line.
  • B: read the document → schema table with source file:line → ONE follow-up question → write design.md + § Provenance.
  • C: hallmark study <URL> (URL mode, refuse list + attestation) → "lock the DNA" → design.md has § Provenance + § Notes (rhythm blind spot, anti-pattern not carried along).
  • Then: python3 $SKILL/scripts/design-sync.py && python3 $SKILL/scripts/design-sync.py --check → only rc 0 proceeds.
  • Announce Genre / Macrostructure / Theme out loud (hallmark Step 2.5).

Phase 3 — Build according to hallmark, system locked

  • Run the hallmark default flow (Step 2 macrostructure → 3 ruleset → 5 preview → 6 build) with design.md locked: diversification reversed (screens must SHARE the system).
  • All colors, fonts, radius, motion via var(--…) from tokens.css (hallmark discipline 3). No inline hex/oklch; if a token is missing, add it to the :root block of design.md then run design-sync.py again.
  • HTML output for viewers: light/dark toggle with a labeled switch + html[data-theme] + localStorage + anti-FOUC; compact 13″ type scale; footer records the relative path of the file itself.
  • Stamp at the top of the file: <!-- design: macrostructure=<M> theme=<T> --> and /* Hallmark · pre-emit critique: P? H? E? S? R? V? */ (6 axes, any axis < 3 must be fixed before moving to Phase 4).

Phase 4 — Gate (machine first, human after)

  1. bash $SKILL/scripts/fe-gate.sh <output.html …>; read the table antipattern | file:line | snippet and fe-gate.report.json.
    • Line badge lệch pattern so với N badge anh em = badge-consistency: fix badges that deviate to match their siblings (the majority), do not fix in reverse.
    • rc 2 → fix exactly the finding (change the token in design.md → sync again, or fix the markup) → run again. Maximum 3 rounds. Record the number of findings per round for the report.
    • rc 1 / 3 / 4 → stop, record the cause. There is no path from 1/3/4 to "clean".
  2. Load references/impeccable-audit.md: score 5 axes /20, list P0–P3; do the Harden checklist then Polish. P0 must = 0.
  3. Run hallmark slop-test (skills/hallmark/references/slop-test.md) on the output; whichever gate is red, fix it.
  4. Run fe-gate.sh one final time after all edits (harden/polish fixes can regenerate findings).

Phase 5 — Deliver + report

Report includes, in order: (1) Phase 1 reasoning/answer; (2) Genre/Macrostructure/Theme + theme source; (3) 6 critique points; (4) findings table rounds 1..n and final rc; (5) audit score /20 + P0 count; (6) 4 viewports; (7) relative output path; (8) skipped if any. The sentence "production ready" may only be written when fe-gate exits 0 and P0 = 0.

Branches

ID Kind Guard Behavior Skip / failure Rejoin
B01 conditional_required has design.md and --check rc 0 say "system already locked, reuse it", skip W02–W03 user demands a theme change → references/intake.md § "When the project already has design.md" W04
B02 recovery no node / network still do Phases 1–3; Phase 4 records skipped report MUST NOT claim clean W06
B03 user_optional theme source = B (documentation) schema table has source file:line → ONE follow-up question → design.md + § Provenance — W03 (sync)
B04 user_optional theme source = C (URL) hallmark study <URL> → "lock the DNA" → design.md + § Provenance + § Notes — W03 (sync)
B05 recovery fe-gate rc 2 fix the exact finding (token in design.md → sync, or markup) → rerun, at most 3 rounds over 3 rounds → deliver with a leftover table or a reasoned waiver W05

Validation and stopping

Machine gate: fe-gate.sh exit 0 (impeccable detect rc 0 + badge-consistency + 4 viewports 320/375/414/768) and design-sync.py --check rc 0. Human/rubric gate: 5-axis audit /20 with P0 = 0, slop-test not red. Gate fix rounds capped at 3; fe-gate reruns one final time after all edits.

Examples

  • Positive: /prd-grade-fe dựng trang danh sách đơn hàng cho app quản lý kho, mặc định theme → choose A, cp preset macos-glass to design.md, sync rc 0, token-only build, fe-gate round 1 rc 2 (2 findings) → fix → round 2 exit 0, P0 = 0 → 8-item report, allowed to write "production-ready".
  • Boundary/failure: machine has no node → Phases 1–3 still done, fe-gate exit 3 → report records skipped: thiếu node, do NOT write "production-ready".

Call examples

/prd-grade-fe dựng trang danh sách đơn hàng cho app quản lý kho, mặc định theme
/prd-grade-fe trang pricing, theme lấy từ docs/brand/ (folder)
/prd-grade-fe landing cho sản phẩm X, làm giống https://example.com