Skip to content

Website improvement

You will produce a Website Improvement plan for the site described in $ARGUMENTS. This includes new homepage implementation and existing homepage refactoring. The target website source code does not live in design-ai; implementation happens later in the target website repository after explicit human approval.

Steps

  1. Read the workflow source:
  2. skills/website-improvement/PLAYBOOK.md
  3. skills/website-improvement/TEMPLATE.md
  4. knowledge/PRINCIPLES.md
  5. knowledge/patterns/ux-guidelines.md
  6. knowledge/a11y/contrast.md
  7. knowledge/a11y/keyboard-and-focus.md
  8. knowledge/layout/spacing-and-grid.md
  9. knowledge/patterns/report-design.md

  10. docs/MCP-INTEGRATION.md

  11. Build a Site Profile:

  12. site name
  13. live URL when a preview or deployed site exists
  14. repo URL or local path
  15. priority pages
  16. Figma URL
  17. brand/design notes
  18. deploy provider
  19. Sentry project
  20. CMS and database
  21. user flows

  22. desktop/tablet/mobile viewports

  23. Create an Audit Checklist across:

  24. Visual Design
  25. UX Flow
  26. Responsive QA
  27. Accessibility
  28. Performance
  29. SEO
  30. Technical Quality
  31. Runtime Issues

  32. Content Quality

  33. Create an MCP Readiness Matrix. Use only required, optional, unused, or unavailable. Do not claim live MCP access unless the current agent actually has it.

  34. Convert findings into Refactor Tasks. Each task must include:

  35. problem
  36. evidence
  37. impact
  38. effort
  39. priority
  40. pages
  41. recommended MCP
  42. Codex prompt
  43. verification

  44. risks

  45. Generate prompt templates for:

  46. Codex repo intake
  47. Codex implementation
  48. Codex visual QA
  49. Codex deployment verification
  50. Claude design review
  51. Claude competitor research
  52. Claude copy/UX critique

  53. final handoff report

  54. Draft the Handoff Report with target site information, diagnostic summary, priority recommendations, executed work placeholders, verification placeholders, remaining risks, and next actions.

  55. Prepare target-repo execution in two phases:

  56. Phase A is read-only: verify the local handoff bundle, call design_ai_site_bundle_handoff or run the equivalent design-ai site <bundle-dir> --bundle-handoff --strict --json, inspect the target repo, and present exact scope, risks, files, and verification commands.
  57. Phase B starts only after explicit human approval: implement in the target repo, preserve its architecture and design system, and collect browser, accessibility, responsive, lint, test, and build evidence.
  58. Request approval again before adding dependencies, widening scope, migrating data, deploying, committing, pushing, or performing another external write not covered by the original approval.

Output

Follow skills/website-improvement/TEMPLATE.md. Keep the report dense and operational. Cite checked knowledge files when making design, accessibility, UX, or report-structure recommendations.

Done when

  • The artifact can be checked with design-ai check output.md --route website-improvement --strict.
  • The MCP handoff returns a pending human-approval contract and does not mutate the target repo.
  • The MVP boundary is explicit: no automatic crawling, unapproved external writes, target repo mutation from design-ai, embeddings, fine-tuning, or backend sync.