diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 5cb887c..e04be34 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -5,6 +5,7 @@ Run locally before opening the PR: ```bash sit validate sit test +sit test --run sit pr-summary origin/main..HEAD ``` @@ -12,5 +13,6 @@ sit pr-summary origin/main..HEAD - [ ] `sit validate` passes - [ ] `sit test` passes +- [ ] `sit test --run` passes - [ ] Generated webpage assets were link-checked when relevant - [ ] Breaking schema or output-contract changes are explained diff --git a/.github/workflows/sit-ci.yaml b/.github/workflows/sit-ci.yaml index 1ef8c96..d43d4cb 100644 --- a/.github/workflows/sit-ci.yaml +++ b/.github/workflows/sit-ci.yaml @@ -16,8 +16,16 @@ jobs: fetch-depth: 0 - name: Install sit run: python -m pip install git+https://github.com/OpenRaiser/SitHub.git - - run: sit validate "$SIT_PACKAGE_DIR" - - run: sit test "$SIT_PACKAGE_DIR" + - name: Validate Skill package + run: sit validate "$SIT_PACKAGE_DIR" + - name: Run static golden tests + run: sit test "$SIT_PACKAGE_DIR" + - name: Run behavior regression tests + shell: bash + run: | + set -o pipefail + mkdir -p "$SIT_ARTIFACT_DIR" + sit test "$SIT_PACKAGE_DIR" --run | tee "$SIT_ARTIFACT_DIR/sit-test-run.txt" - name: Write SitHub summary if: always() run: | diff --git a/SKILL.md b/SKILL.md index 684258b..df1f2df 100644 --- a/SKILL.md +++ b/SKILL.md @@ -11,40 +11,65 @@ Use this skill to turn a paper project folder into a web-ready project page. It Do not mechanically clone an existing webpage. Use prior pages only as references for interaction patterns and content completeness. The final design must follow the target paper's topic, figures, color palette, density, and audience. +Two failure modes to actively avoid: + +- Do not reuse a background system from another paper page by default. Grids, coordinate paper, dark sections, gradients, or canvas textures are allowed only when they are supported by the target paper's own figures, domain, or visual language. +- Do not summarize away central evidence. If the paper's main claim depends on a main experiment table, benchmark comparison table, dataset statistics table, or ablation table, the webpage must include that table in full or provide a clearly equivalent full presentation. + ## Workflow 1. Inspect inputs before editing. - Locate paper source, PDF, figures, logos, existing `template.html`, and target `index.html`. - - Run `scripts/scan_paper.py ` when a TeX source exists. - - Identify important tables as well as figures; main results, dataset statistics, and ablations usually belong on the page. + - Run `scripts/scan_paper.py ` when a TeX source exists. Multi-file projects are followed via `\input`/`\include` automatically. + - Run `scripts/scan_pdf.py ` when only a PDF is available; it produces the same shape of inventory (title, authors, abstract, sections, figure/table captions, links). + - Run `scripts/extract_tables.py ` to dump every table (caption, label, header rows, data rows) as JSON. Use this to seed the table ledger instead of eyeballing the .tex. + - Build a table ledger before designing: caption, label, section, whether it is main evidence, and whether it must appear fully on the page. + - Identify important tables as well as figures; main results, benchmark comparisons, dataset statistics, and ablations usually belong on the page. 2. Build a content map. - Extract title, authors, affiliations, abstract claim, contributions, links, dataset stats, method description, main results, case studies, citation. + - Map every central table to a page module. If a central table is too large, plan a scrollable/grouped table rather than dropping rows. - Decide modules before writing. Typical modules: Hero, Motivation, Method, Dataset/Benchmark, Results, Case Study, Citation. - Read `references/module_patterns.md` when choosing sections or table placement. 3. Prepare assets. - Prefer paper-provided figures over generic visuals. - - Convert PDF figures to PNG/SVG-friendly web assets. Use `scripts/convert_figures.sh ` when applicable. + - Convert figures to web assets with `scripts/convert_figures.py ` (the legacy `convert_figures.sh` is now a shim around it). The script handles multi-page PDFs, `.eps`, `.svg` passthrough, raster passthrough, and writes a `figures.manifest.json` that records source→output mapping plus an empty `alt` field per asset for the LLM to fill. - Copy logos and paper PDF into the webpage output folder when useful. - - Rename web assets to stable ASCII filenames. - -4. Design the page around the paper. - - Derive colors from the paper's key figures and domain. For geometry/GUI papers, grids, coordinate-paper textures, and precise callouts are often appropriate. + - Filenames coming out of the manifest are already slug+hash safe; do not rename them again. + +4. Generate the citation block. + - Run `scripts/extract_citation.py [--pdf paper.pdf]` and embed the produced BibTeX as the page's citation default. + - Preserve the leading `% NOTE:` comments verbatim; they document fields that were inferred or guessed (year, venue, authors). When any note is present, surface a "verify before publishing" hint near the citation block on the page rather than silently displaying the draft. + +5. Design the page around the paper. + - Derive colors, background, spacing, figure framing, and motifs from the paper's key figures and domain. + - First list the paper-specific visual cues, then choose the background. A plain surface, soft paper tone, lab-notebook grid, dark canvas, figure-derived gradient, or no visible texture are all valid; none is the default. + - Plan figure layout from the actual converted image ratios in `figures.manifest.json`. Wide pipeline/heatmap/table figures, tall case figures, and compact charts should not be forced into one equal-height grid. + - Avoid fixed-height or fixed-aspect figure cards with `object-fit: contain` for paper figures. Use natural image height (`width: 100%; height: auto`) by default; reserve fixed boxes for icons, logos, thumbnails, or zoom modals. + - Put figures side-by-side only when their aspect ratios are compatible, or when one side is balanced by text/table content instead of another image. If max/min ratio is above about 1.25, stack them or use a main-figure-plus-notes composition. - Keep background transitions coherent across sections. Avoid abrupt dark-to-light jumps unless the entire page system intentionally supports that contrast. - - Read `references/design_principles.md` when deciding visual style or revising design feedback. + - Read `references/design_principles.md` when deciding visual style or revising design feedback. The "Measurable Criteria" section there names the thresholds the design-drift check enforces. -5. Implement the webpage. +6. Implement the webpage. + - Start from `assets/single-page-template.html`. It includes semantic landmarks (`header`/`nav`/`main`/`footer`), a skip-link, a `prefers-reduced-motion` fallback, a CJK-friendly font stack, and the `{{LANG}} {{TITLE}} {{DESCRIPTION}} {{CANONICAL_URL}} {{OG_IMAGE}} {{JSONLD}}` placeholders. Fill them with `scripts/render_template.py` (or `scripts/inject_metadata.py --inplace` if you only need to refresh the head block of an existing page). + - Set `` to the paper's language (BCP-47: `en`, `zh-CN`, `ja`, `ko`, etc.); the scan scripts do not auto-detect this. For CJK papers keep the bundled font stack and add `lang` attributes around any embedded English titles so browsers pick the right glyphs. + - Generate the head metadata once via `scripts/inject_metadata.py --title ... --description ... --canonical ... --og-image ... --author ...` and pipe its `render-values` JSON into `render_template.py`. Use `--arxiv` / `--doi` when known so the ScholarlyArticle JSON-LD includes a stable identifier. - Produce a self-contained single-page `index.html` unless the repo already has a framework. - Include responsive navigation, resource buttons, figure zoom/modal behavior, and readable tables. + - For primary paper figures, do not use equal-ratio card grids unless all figures in that grid share a close aspect ratio. If a layout needs equal rhythm, align captions/text, not the image boxes. + - Use compact/narrow table treatments for two- or three-column tables. Do not stretch low-density tables across the full page just because wide result tables need full-width scroll containers, and do not leave narrow tables isolated with a large blank area to the right; pair them with related notes, metrics, or figures. + - Include full central tables with horizontal scroll on mobile, sticky headers when useful, grouped rows when needed, and highlights for the proposed method or best values. Tag each rendered `` (or its wrapping `
`) with `data-tex-label="