Beginner Steps. Advanced AI.
Published guideUpdated
Chapter 17 of 20Build & check
Make the site faster and clearer
Improve loading, page titles, and the final details. Check the result again after each change.
Fix the things visitors notice first. A useful improvement matters more than a perfect score.
Follow the pictures
Illustrated examples. Your app may look different. Tap an image to enlarge it.
-
Run a page audit
Open the built preview in Chrome. Run a mobile Lighthouse audit and save its report.
Illustrated example - In Chrome
- Inspect → Lighthouse → Mobile → Run audit
Look for: You have a report for the latest built page, with its test conditions recorded.
More help with this action
Build the latest version and start its production preview. Follow the Chrome Lighthouse instructions to open Developer Tools, select Lighthouse, and run a mobile audit. Save the report and record the tested page and conditions.
Audit the version you intend to publish
- Ask Codex for a fresh build and production preview, then open its reported address in Chrome.
- Right-click part of the page and choose Inspect to open Developer Tools. Select Lighthouse, choose Mobile, and run the page-load audit; button wording can vary.
- Save the report or record its findings. Note the page and conditions so later comparisons are useful.
You should now see: You have a report for the latest built page, with its test conditions recorded.
-
Choose what to fix
Give Codex the report and the polish prompt. Ask for the three most useful improvements.
Illustrated example - In Codex
- Share report → Ask for priorities → Review the plan
Look for: The next fixes have clear benefits for visitors.
More help with this action
Use the visitor-focused polish prompt to have Codex explain the largest practical issues in plain language. Prioritise slow main images, unnecessary browser scripts, inaccessible text, and content shifts over cosmetic score changes.
Choose useful improvements
- Give Codex the saved report or its important findings. Use the linked prompt with your current preview and approved design.
- Ask it to explain three practical priorities in everyday language: for example, a slow main image, unnecessary browser code, unreadable text, or content that moves while loading.
- Agree on focused fixes. Lighthouse is a lab measurement whose score can vary; do not treat one score as a guarantee or change the design merely to chase it.
You should now see: The next fixes have clear benefits for visitors.
-
Improve the images
Ask Codex to optimise images with Astro’s image tools. Compare the page before and after.
Illustrated example - Compare
- Original image → Optimised file → Inspect the page
Look for: Images load appropriately and keep their intended subject and space.
More help with this action
Have Codex use Astro image tools to optimise sizes and formats, reserve space for images, and keep the important first image from being delayed unnecessarily. Compare the page before and after.
Keep image quality and layout in view
- Have Codex choose suitable image sizes and formats for where each image is displayed.
- Reserve space for images so the layout does not jump. Avoid delaying the important first image unnecessarily.
- Inspect the result at phone and desktop sizes. Compare loading evidence and appearance, then rerun the affected checks.
You should now see: Images load appropriately and keep their intended subject and space.
-
Name each page clearly
Use the SEO guide to give every page an accurate title, description, and headings.
Illustrated example - For every page
- Accurate title → Useful description → Clear headings
Look for: Page information matches its actual content.
More help with this action
Use the Google SEO starter guide to give each page a distinct, accurate title and description. Review headings, descriptive links, image descriptions, and social sharing information against the real content.
Help people and search systems understand pages
- Ask Codex to review Home, About, Services, and Contact. Each should have a distinct title and an accurate description.
- Check heading order, descriptive links, meaningful image descriptions, and social-sharing information against the real content.
- Read the words yourself. Technical SEO supports understanding but cannot promise rankings or visitor numbers.
You should now see: Page information matches its actual content.
-
Use the real public address
Once you know the public address, ask Codex to use it in the sitemap and canonical URLs.
Illustrated example - When known
- Your public address → Page URLs → Sitemap
Look for: Public page addresses use the chosen domain, or remain an explicit task until it is known.
More help with this action
Ask Codex to prepare the sitemap and canonical URLs using the intended public address once it is known, following the search-visibility guidance. Keep unfinished or private draft content out of public output; search exclusion is not access protection.
Do not invent the final address
- Give Codex the intended public website address when it is confirmed. If it is still unknown, keep this as a recorded launch task.
- Ask it to set the sitemap and canonical URLs to that address. Check for localhost, invented domains, or old addresses.
- Keep private or unfinished content out of the published output. Search exclusion does not provide access protection.
You should now see: Public page addresses use the chosen domain, or remain an explicit task until it is known.
-
Review the finished pages
Follow the visitor checklist once more. Fix final problems and save the checked milestone.
Illustrated example - Final pass
- Check four pages → Fix details → Rerun checks → Save
Look for: The polished site still passes its visitor checks and has a saved milestone.
More help with this action
Use the visitor-testing checklist to inspect Home, About, Services, and Contact at phone and desktop widths. Remove placeholder copy, verify business details and image permissions, then rerun affected checks and save the polished milestone.
Finish the practical details
- Inspect all four pages at phone and desktop widths. Remove placeholder copy, verify business details, and confirm image permissions.
- Look for distorted images, cropped content, unreadable controls, and unexpected sideways scrolling.
- Ask Codex to rerun the checks affected by the polish work. Review the latest built preview and save the checked version in Git.
You should now see: The polished site still passes its visitor checks and has a saved milestone.
Why this step matters
Large images and unnecessary scripts can make an otherwise simple website slow. Astro provides image tools, but Codex still needs to choose appropriate dimensions, loading behaviour, and descriptions for each image.
Search engine optimisation helps search systems interpret useful pages. Clear titles, descriptive links, and accurate content are a sensible starting point. A technical checklist cannot promise rankings or visitors. Lighthouse offers lab measurements and suggestions; its score can vary with test conditions.
Basics, explained
SEO
Search engine optimisation: making useful content and page structure easier for search engines to discover and understand.
Canonical URL
The preferred public address of a page, used to clarify which version should represent that content.
Layout shift
Content unexpectedly moving while a page loads, for example when an image appears without space reserved for it.
Ask your agent
PromptFix the issues that matter to visitors
Review the latest Fieldnotes Studio production preview and this Lighthouse report. Explain the three most useful improvements for visitors, then implement focused fixes for image loading, unnecessary JavaScript, layout stability, and readable content. Review each page's title, description, headings, links, and sharing metadata. Prepare sitemap and canonical settings using the public URL I supply; flag any unknown address instead of inventing one. Rerun relevant checks and compare evidence. Keep the approved visual direction and report remaining limitations.If something goes wrong
- The preview still shows the old content.
- Stop the preview, run a fresh build, and start the preview again. It serves the last generated output, while the development server updates during editing.
- A performance score changes between runs.
- Compare tests under similar conditions and inspect the specific reported issues. Use repeated measurements to evaluate a meaningful change rather than treating one score as a guarantee.
Official links & further reading
Personal notes
Add questions, decisions or ideas for your website. Saved in this browser when available; export your notes to keep a copy. Never enter secrets.
Downloads & saved progressGuide, notes and personal checks
Download the complete guide or export your notes from every chapter. Instructions last reviewed: .
Checks and notes stay in this browser, separately for each language. Export your notes to preserve them. Never enter API keys or other secrets here.
NotesNotes as Markdown
Clipboard access is unavailable. Copy the visible, selected text below using your keyboard or browser menu.
0 of 65 checks marked across the guide
These are your saved personal checkmarks. They do not run tests or verify security, and are separate from the chapter position bar above.
Starter filesWorking instructions and four skills
These templates give your agent a starting set of working instructions. Review them, adapt them to your website, and save each file at the exact path shown, relative to your project folder.
A downloaded skill is an instruction file. It does not install a test runner, run a security scan, or prove your site is safe. The guide shows how to set up and check that work.
Download the instruction files in the language of this guide. Keep the technical filenames and paths as shown.
Download all starter filesFileAGENTS.md
# Website working agreements
This project follows the website brief and acceptance criteria we have agreed with its owner. Use the existing technology choices unless a concrete requirement calls for a change.
## How to work
- For a substantial feature, explain the proposed changes and verification plan before implementing it. Complete authorized local work in small, reviewable stages.
- Read the files relevant to the task. Keep unrelated pages and configuration intact.
- Explain new technical terms in plain language when reporting to the owner.
- Use the repository's website-design, clean-code, website-testing and website-security skills when their workflows apply.
- Record important decisions and unresolved content in the project's notes. Do not invent business facts, endorsements or publishing rights.
## Verification
- Inspect package.json to find the actual build, type-check and test commands. Do not invent a successful check or create a meaningless test just to make a command pass.
- Run checks appropriate to the change. Local tests use disposable fixtures and have no production access; run them and repair failures caused by the requested change without asking at every step.
- Verify visitor interactions in a browser when browser tools are available. Report checks that remain unavailable or incomplete.
- Show the owner a working local preview and summarise changed behaviour, evidence and remaining limitations.
## Credentials and publication
- Keep API keys and other secrets out of browser code, prompts, logs and Git. Store local secrets in ignored files or the chosen secret store.
- Local build and test work is authorized. Publishing the site, sending a real message, processing a payment or changing production data requires the owner's authorization for that action.
- Preserve a recoverable working version before release. Describe how to restore it.
These are starter agreements for a new tutorial project. Adapt them to the owner's actual requirements and existing authorization.
File.agents/skills/website-design/SKILL.md
---
name: website-design
description: Develop or refine a website's visual direction and responsive interface from its brief, content and existing design. Use for page design or visual implementation.
---
Read the website brief and any existing design notes relevant to the requested page. Work within the user's brand, content and technology choices.
When establishing a new direction, propose typography, a small colour palette, a spacing rhythm and a sample page. Explain how these choices support the audience and main visitor action. Use real content to judge hierarchy and line lengths.
Implement reusable elements for navigation, headings, buttons and repeated content. Give primary actions a clear visual hierarchy. Preserve visible keyboard focus, readable contrast and usable labels. Design narrow screens alongside desktop screens; check long headings, navigation and tap targets in a browser.
Use semantic HTML before adding custom interaction. Keep motion optional and respect reduced-motion preferences. Use assets with known permission to publish; record their sources. Do not invent client testimonials, achievements or business facts.
Before expanding a design across all pages, show the first complete page at desktop and mobile widths. Describe the main design decisions and any unresolved content. When a browser tool is unavailable, report that visual verification is still pending.
File.agents/skills/clean-code/SKILL.md
---
name: clean-code
description: Implement or refactor website code into understandable components using the project's existing stack and conventions. Use for website implementation or maintainability work.
---
Read the relevant files and package scripts before choosing an implementation. Preserve working behaviour outside the requested change. Prefer the existing stack and dependencies when they meet the need.
Keep page content separate from repeated layout where that makes editing easier. Name components, variables and functions for their purpose. Use shared components for repeated navigation and page elements; avoid abstraction for a single trivial use.
Handle empty, invalid, loading and error states for interactions that need them. Use native browser controls and semantic HTML when they serve the interaction. Avoid fake form submission, simulated success messages and dead links.
Use type checking and the project's formatting or lint rules where configured. When adding a package, explain its purpose and any new maintenance or runtime requirements. Keep generated build output, dependencies and local environment files out of version control.
Run the existing checks relevant to the change, including a production build when output can change. Summarise changed behaviour, verification results and remaining limits. Explain the main files in plain language so a beginner can find and edit their content.
File.agents/skills/website-testing/SKILL.md
---
name: website-testing
description: Verify website changes through visitor journeys, appropriate automated tests and browser checks. Use when testing a website, investigating a failure or preparing a release.
---
Start from the brief and observable acceptance criteria. Inspect existing test and build commands; do not assume that a script exists. Choose checks based on the changed behaviour and the cost of failure.
Exercise the main visitor journey and affected links, navigation and forms. Include invalid input and relevant error states. For a contact form, verify actual delivery in the agreed test destination before reporting that it works. For an email link, explain that it opens the visitor's configured email app and does not send a message automatically.
Check narrow and wide screens in a browser. Include keyboard navigation, visible focus, accessible names, zoom and horizontal overflow. Automated accessibility results complement these manual checks and do not establish complete accessibility conformance.
Add automated tests for important behaviour or demonstrated regressions. Test observable outcomes and meaningful failure cases; avoid tests that merely repeat the implementation or match incidental wording. Use disposable test data and local fixtures. Never send real messages, charge payments or alter production data without the user's authorization.
Reproduce a failure, fix its cause and rerun affected checks. Report commands run, results, browser checks performed and anything not checked. A successful build shows that the site can be generated; verify visitor behaviour separately. Never report a check as passed when it was skipped or unavailable.
File.agents/skills/website-security/SKILL.md
---
name: website-security
description: Review a website's secrets, dependencies, inputs, permissions and deployment configuration, and repair scoped security findings. Use for requested security review or release preparation.
---
Identify the site's relevant surfaces: static pages, forms, backend routes, authentication, third-party scripts and stored data. Scope review to the actual architecture and authorized environment.
Keep credentials out of browser code, logs, prompts and Git. Distinguish build-time public configuration from server secrets. If a key was committed or exposed, stop using it, explain that deleting the file does not revoke the key, and have the owner revoke or rotate it before further use. Do not print the credential in your report.
Inspect applicable dependency advisories and assess whether the affected package and vulnerable behaviour are used. Repair within the project's compatible versions and rerun affected checks. Avoid automatic forced upgrades that may break the website.
For backend interactions, validate inputs on the server, encode output appropriately, and check authentication and authorization separately. Consider abuse controls for public forms or AI endpoints. An OpenAI API key belongs on the server; publishing a static site does not provide a secret server environment.
Check HTTPS and applicable security headers at the actual hosting layer. Collect only the data the feature needs, and explain its destination and retention. Do not claim legal compliance from a code scan.
Report each finding with its location, plausible impact, fix and verification. State review scope, tools used, unresolved findings and inaccessible surfaces. A clean scan is evidence about that scan's scope, not a guarantee that the website has no vulnerabilities. Do not scan third-party systems or deploy changes outside the authorized task.