guizang-ppt-skill/CONTRIBUTING.md

Contributing

Thanks for helping improve guizang-ppt-skill.

This project is a Skill for AI agents that generate polished HTML slide decks. The most useful contributions are specific, reproducible, and tied to real deck output.

Before Opening an Issue

Please check whether the problem belongs to one of these buckets:

• Layout fidelity: a page drifts away from the registered template.
• Content overflow: text, images, charts, or footers overlap.
• Image workflow: generated images do not match the target slot ratio or deck style.
• Runtime behavior: navigation, ESC overview, low-power mode, map interaction, or animations fail.
• Documentation: installation, prompt usage, layout selection, or examples are unclear.

Screenshots are much more useful than descriptions alone. If possible, include:

• The prompt or source content used to generate the deck.
• The generated index.html.
• A screenshot of the broken slide.
• Browser and OS information.

Pull Request Guidelines

Keep PRs focused. A small fix with a screenshot is easier to review than a large rewrite.

For Swiss theme changes:

• Do not invent new default body layouts unless the change is explicitly discussed.
• Keep the registered layout system intact.

• Run the Swiss validator:

  node scripts/validate-swiss-deck.mjs path/to/index.html
  

For template changes:

• Verify at least one dense text slide.
• Verify at least one image slide.
• Verify navigation, ESC overview, and low-power mode.

Good PRs Usually Include

• A short summary of the problem.
• The exact files changed.
• Before / after screenshots when visual behavior changes.
• Validation or manual QA notes.

Style Notes

This Skill is opinionated by design. It prefers constrained layout systems over unlimited customization, because constraints make AI-generated decks more reliable.

When in doubt, preserve the existing visual rules and improve the workflow around them.