docs: require fidelity-first Astro migration
This commit is contained in:
@@ -1,5 +1,16 @@
|
||||
# AGENTS.md
|
||||
|
||||
## Instruction precedence
|
||||
|
||||
This file is the authoritative project policy for all editors and AI agents.
|
||||
`MIGRATION_BRIEF.md` supplies detailed implementation guidance and must be read
|
||||
with this file. If the two files appear to conflict, follow `AGENTS.md` and
|
||||
update the conflicting documentation before continuing.
|
||||
|
||||
The `migration-foundation` branch is a reference and recovery point only. It is
|
||||
not the visual or architectural source of truth. Reuse its nonvisual tooling or
|
||||
content only after verifying it against the live public site.
|
||||
|
||||
## Project
|
||||
|
||||
This repository contains a mirrored copy of the Arizona Institute for Autism website.
|
||||
@@ -26,9 +37,29 @@ Do not modify, move, rename, or delete `./www.azinstitute4autism.com`.
|
||||
|
||||
Treat the mirror as read-only raw source material.
|
||||
|
||||
The live public website is the single source of truth:
|
||||
|
||||
```txt
|
||||
https://www.azinstitute4autism.com
|
||||
```
|
||||
|
||||
Use the mirror as a convenient local extraction and inspection aid only. The
|
||||
mirror may contain stale, missing, rewritten, or incorrectly downloaded
|
||||
content and assets. Verify content, design, URLs, metadata, assets, and
|
||||
responsive behavior against the live public site before treating them as
|
||||
authoritative. When the live site and mirror disagree, follow the live site and
|
||||
document material discrepancies.
|
||||
|
||||
## Primary goal
|
||||
|
||||
Create a clean, maintainable Astro + TypeScript site in `./www` that reproduces the current public site as faithfully as practical while replacing HubSpot-generated structure with a future-friendly static site architecture.
|
||||
Create a clean, maintainable Astro + TypeScript site in `./www` that faithfully
|
||||
reproduces the current public site's content, visual design, page structure, and
|
||||
responsive behavior while replacing HubSpot-generated implementation details
|
||||
with a future-friendly static site architecture.
|
||||
|
||||
This is a fidelity-first migration, not a redesign. The live public site is the
|
||||
source of truth for both content and presentation. Maintainability must improve
|
||||
the implementation without materially changing what visitors see.
|
||||
|
||||
The new site should be suitable for:
|
||||
|
||||
@@ -149,13 +180,31 @@ Do not invent large Arabic or Spanish translations unless source content is avai
|
||||
|
||||
## Design rules
|
||||
|
||||
The new design should be mostly faithful to the current site while becoming more maintainable.
|
||||
The new site must remain visually faithful to the live public site. Do not
|
||||
reinterpret, modernize, simplify, or genericize the design unless a specific
|
||||
change is required for accessibility or reliable responsive behavior.
|
||||
|
||||
Preserve each source page's:
|
||||
|
||||
- section order and visible content
|
||||
- typography, font weights, and text hierarchy
|
||||
- colors, backgrounds, and decorative treatments
|
||||
- container widths, spacing, alignment, and proportions
|
||||
- imagery, crops, icons, borders, radii, and shadows
|
||||
- header, navigation, footer, calls to action, and forms
|
||||
- desktop and mobile responsive behavior
|
||||
|
||||
Reuse exact source assets and locally available fonts wherever practical.
|
||||
Do not replace distinctive source sections with generic cards, generic heroes,
|
||||
or a new site-wide layout merely to make component reuse easier.
|
||||
|
||||
Use plain CSS with design tokens.
|
||||
|
||||
Create reusable Astro components for repeated layout sections.
|
||||
|
||||
Do not create a messy page-by-page clone of HubSpot output.
|
||||
Component boundaries must follow genuinely repeated source patterns. Distinctive
|
||||
pages and sections may retain page-specific markup and CSS when abstraction
|
||||
would reduce fidelity. Do not copy HubSpot's generated DOM or CSS wholesale.
|
||||
|
||||
Favor:
|
||||
|
||||
@@ -163,10 +212,31 @@ Favor:
|
||||
- reusable components
|
||||
- organized CSS
|
||||
- clear data files
|
||||
- consistent spacing
|
||||
- source-faithful spacing
|
||||
- accessible markup
|
||||
- predictable file structure
|
||||
|
||||
### Visual validation
|
||||
|
||||
Before implementing a page family or shared component:
|
||||
|
||||
1. Inspect the live page and its HTML, CSS, assets, and responsive behavior.
|
||||
2. Use the mirror to accelerate local extraction and inspection.
|
||||
3. Resolve any discrepancy in favor of the live public site.
|
||||
4. Record the source structure and important visual details.
|
||||
5. Identify which patterns are truly shared and which are page-specific.
|
||||
|
||||
After implementation, compare the Astro output with the live public site at
|
||||
representative desktop and mobile viewport widths. Check the full page, not
|
||||
only the header or first viewport. Fix material differences before treating the
|
||||
page as complete.
|
||||
|
||||
Document intentional visual deviations and their reasons in:
|
||||
|
||||
```txt
|
||||
reports/migration-summary.md
|
||||
```
|
||||
|
||||
## URL and SEO rules
|
||||
|
||||
Preserve existing public URL paths whenever possible.
|
||||
@@ -294,9 +364,11 @@ reports/migration-summary.md
|
||||
|
||||
Before large filesystem changes:
|
||||
|
||||
1. Inspect the mirror.
|
||||
2. Summarize the implementation plan.
|
||||
3. Proceed methodically.
|
||||
1. Inspect the live public site.
|
||||
2. Inspect the mirror and identify relevant discrepancies.
|
||||
3. Inspect the relevant source HTML, CSS, and assets in detail.
|
||||
4. Summarize the implementation and visual-validation plan.
|
||||
5. Proceed methodically.
|
||||
|
||||
At the end of a task, summarize:
|
||||
|
||||
@@ -307,4 +379,7 @@ At the end of a task, summarize:
|
||||
- audit results
|
||||
- unresolved issues
|
||||
|
||||
Prioritize a clean, maintainable foundation over a pixel-perfect but messy clone.
|
||||
Prioritize visual fidelity and content correctness while implementing them with
|
||||
clean, maintainable Astro code. Do not trade away visible source design for a
|
||||
generic foundation, and do not copy HubSpot-generated implementation merely to
|
||||
obtain fidelity.
|
||||
|
||||
@@ -36,19 +36,24 @@ For the migration task:
|
||||
|
||||
1. Read `AGENTS.md`.
|
||||
2. Read `MIGRATION_BRIEF.md`.
|
||||
3. Inspect the local mirror.
|
||||
4. Provide a concise implementation plan.
|
||||
5. Scaffold or update the Astro project in `./www`.
|
||||
6. Build extraction, crawl, audit, sitemap, and redirect tools.
|
||||
7. Extract content, media, metadata, navigation, and forms.
|
||||
8. Refactor into reusable Astro components.
|
||||
9. Configure Astro content collections and Front Matter CMS.
|
||||
10. Add English, Arabic, and Spanish structure.
|
||||
11. Add RTL CSS for Arabic.
|
||||
12. Add SEO, sitemap, robots, redirects, and reports.
|
||||
13. Run build and audits.
|
||||
14. Fix practical errors.
|
||||
15. Document incomplete items in `reports/migration-summary.md`.
|
||||
3. Inspect the live public site as the single source of truth.
|
||||
4. Inspect the local mirror as a convenient extraction aid and identify
|
||||
relevant discrepancies.
|
||||
5. Inspect the relevant live HTML, CSS, assets, and responsive behavior.
|
||||
6. Provide a concise implementation and visual-validation plan.
|
||||
7. Scaffold or update the Astro project in `./www`.
|
||||
8. Build extraction, crawl, audit, sitemap, and redirect tools.
|
||||
9. Extract content, media, metadata, navigation, and forms.
|
||||
10. Refactor genuinely repeated patterns into reusable Astro components.
|
||||
11. Compare rendered pages with the live site at desktop and mobile widths.
|
||||
12. Configure Astro content collections and Front Matter CMS.
|
||||
13. Add English, Arabic, and Spanish structure.
|
||||
14. Add RTL CSS for Arabic.
|
||||
15. Add SEO, sitemap, robots, redirects, and reports.
|
||||
16. Run build and audits.
|
||||
17. Fix practical errors.
|
||||
18. Document incomplete items and intentional visual deviations in
|
||||
`reports/migration-summary.md`.
|
||||
|
||||
## Important Claude-specific behavior
|
||||
|
||||
@@ -60,6 +65,15 @@ When asked to begin migration, first read the relevant project files, then work
|
||||
|
||||
Treat `./www.azinstitute4autism.com` as read-only source material.
|
||||
|
||||
Treat the live public site as the single content and visual source of truth.
|
||||
Use the mirror only as a convenient local extraction and inspection aid. When
|
||||
the live site and mirror disagree, follow the live site and document material
|
||||
discrepancies. This migration is not a redesign. Do not substitute a generic
|
||||
visual system for the live design.
|
||||
|
||||
Treat the `migration-foundation` branch as reference-only. Do not use it as the
|
||||
visual baseline.
|
||||
|
||||
Do not delete or overwrite raw source assets.
|
||||
|
||||
Do not remove files unless you are certain they are generated output in `./www`.
|
||||
|
||||
+76
-23
@@ -1,5 +1,18 @@
|
||||
# MIGRATION_BRIEF.md
|
||||
|
||||
## Authority and interpretation
|
||||
|
||||
Read and follow `AGENTS.md` first. It is the authoritative project policy; this
|
||||
brief provides detailed implementation guidance. If any wording here appears
|
||||
to conflict with `AGENTS.md`, follow `AGENTS.md` and correct this brief before
|
||||
continuing.
|
||||
|
||||
This is a fidelity-first migration, not a redesign. The raw mirror is a
|
||||
convenient local extraction and inspection aid, but the live public site is the
|
||||
single content and visual source of truth. The `migration-foundation` branch
|
||||
may be consulted for nonvisual tooling and recovered content, but it must not
|
||||
be used as the visual baseline.
|
||||
|
||||
## Task
|
||||
|
||||
Migrate the public Arizona Institute for Autism website from a mirrored HubSpot-generated static copy into a clean, maintainable Astro + TypeScript site.
|
||||
@@ -24,15 +37,21 @@ wget --mirror --page-requisites --adjust-extension --convert-links --no-parent h
|
||||
|
||||
There is no HubSpot export, no HubSpot CLI access, and no HubSpot API access.
|
||||
|
||||
Use the local mirror as the primary source.
|
||||
|
||||
If internet access is available, also crawl the live public website to catch missing URLs or assets:
|
||||
Use the live public website as the single source of truth:
|
||||
|
||||
```txt
|
||||
https://www.azinstitute4autism.com
|
||||
```
|
||||
|
||||
The live crawl is only for comparison and gap-filling. The local mirror remains the source of truth.
|
||||
Use the local mirror as a convenient extraction and inspection aid. It may
|
||||
contain stale, missing, rewritten, or incorrectly downloaded content and
|
||||
assets. Verify content, design, URLs, metadata, assets, and responsive behavior
|
||||
against the live site. When the live site and mirror disagree, follow the live
|
||||
site and document material discrepancies.
|
||||
|
||||
If the live site is temporarily unavailable, work that depends on its authority
|
||||
must remain explicitly unverified rather than silently treating the mirror as
|
||||
authoritative.
|
||||
|
||||
## High-level goal
|
||||
|
||||
@@ -49,7 +68,7 @@ Create a new Astro site in `./www` that is:
|
||||
- SEO-conscious
|
||||
- accessible
|
||||
- maintainable
|
||||
- mostly faithful to the current design
|
||||
- faithful to the current design, layout, and responsive behavior
|
||||
- free of unnecessary HubSpot-generated structure
|
||||
- prepared for future development and publishing
|
||||
|
||||
@@ -238,11 +257,20 @@ Do not invent extensive translations.
|
||||
|
||||
### Design direction
|
||||
|
||||
The new site should be more maintainable while remaining mostly faithful to the current design.
|
||||
The new site must faithfully reproduce the live public site's visible design,
|
||||
layout, content hierarchy, and responsive behavior. Do not redesign,
|
||||
reinterpret, modernize, simplify, or genericize source pages.
|
||||
|
||||
Do not create a messy clone of HubSpot output.
|
||||
Preserve typography, colors, backgrounds, spacing, proportions, imagery,
|
||||
section order, decorative treatments, navigation, calls to action, forms, and
|
||||
page-specific distinctions. Reuse exact source assets and fonts wherever
|
||||
practical.
|
||||
|
||||
Refactor repeated sections into reusable components.
|
||||
Do not copy HubSpot-generated DOM or CSS wholesale.
|
||||
|
||||
Refactor genuinely repeated sections into reusable components. Do not force
|
||||
distinctive source sections into generic components when doing so changes their
|
||||
appearance or structure.
|
||||
|
||||
Use semantic markup.
|
||||
|
||||
@@ -250,6 +278,22 @@ Use plain CSS with design tokens.
|
||||
|
||||
Do not use Tailwind.
|
||||
|
||||
### Fidelity workflow
|
||||
|
||||
For each page family or shared component:
|
||||
|
||||
1. Inspect the live page, HTML, CSS, assets, and responsive behavior.
|
||||
2. Use the mirror to accelerate local extraction and inspection.
|
||||
3. Resolve discrepancies in favor of the live public site.
|
||||
4. Record important visual details and identify genuine shared patterns.
|
||||
5. Implement the page or component in maintainable Astro code.
|
||||
6. Compare the complete rendered page with the live public site at representative
|
||||
desktop and mobile viewport widths.
|
||||
7. Fix material visual differences before marking it complete.
|
||||
|
||||
Document intentional visual deviations and their reasons in
|
||||
`reports/migration-summary.md`.
|
||||
|
||||
## Required target structure
|
||||
|
||||
Create this project structure in `./www`:
|
||||
@@ -643,7 +687,10 @@ src/styles/rtl.css
|
||||
src/styles/global.css
|
||||
```
|
||||
|
||||
Infer the current site’s visual language from the mirrored CSS and HTML.
|
||||
Extract the current site's visual language from the live public site, using the
|
||||
mirrored CSS and HTML as a convenient local aid after checking for discrepancies.
|
||||
Tokens must encode source values; they must not introduce a replacement visual
|
||||
system.
|
||||
|
||||
Use design tokens such as:
|
||||
|
||||
@@ -1168,6 +1215,8 @@ The migration is successful when:
|
||||
- `./www` contains a working Astro project
|
||||
- `npm run build` succeeds or unresolved build issues are clearly documented
|
||||
- main public pages render locally
|
||||
- main public pages have been compared with the live site at desktop and mobile
|
||||
widths and have no undocumented material visual differences
|
||||
- blog posts are migrated into file-based Markdown where feasible
|
||||
- Markdown files work with Front Matter CMS
|
||||
- MDX is available but not overused
|
||||
@@ -1191,18 +1240,22 @@ Proceed methodically:
|
||||
1. Read `AGENTS.md`.
|
||||
2. Read `CLAUDE.md`, if using Claude Code.
|
||||
3. Read this `MIGRATION_BRIEF.md`.
|
||||
4. Inspect `./www.azinstitute4autism.com`.
|
||||
5. Summarize a concise implementation plan.
|
||||
6. Scaffold Astro in `./www`.
|
||||
7. Build extraction/reporting scripts.
|
||||
8. Extract pages, blog posts, assets, metadata, navigation, and forms.
|
||||
9. Refactor repeated sections into Astro components.
|
||||
10. Configure content collections and Front Matter CMS.
|
||||
11. Add multilingual structure.
|
||||
12. Add SEO, sitemap, robots, and redirects.
|
||||
13. Add reports.
|
||||
14. Run build and audits.
|
||||
15. Fix errors.
|
||||
16. Summarize what changed and what still needs manual review.
|
||||
4. Inspect the live public site.
|
||||
5. Inspect `./www.azinstitute4autism.com` and identify relevant discrepancies.
|
||||
6. Summarize a concise implementation plan.
|
||||
7. Scaffold Astro in `./www`.
|
||||
8. Build extraction/reporting scripts.
|
||||
9. Extract pages, blog posts, assets, metadata, navigation, and forms.
|
||||
10. Refactor repeated sections into Astro components.
|
||||
11. Configure content collections and Front Matter CMS.
|
||||
12. Add multilingual structure.
|
||||
13. Add SEO, sitemap, robots, and redirects.
|
||||
14. Add reports.
|
||||
15. Run build and audits.
|
||||
16. Fix errors.
|
||||
17. Summarize what changed and what still needs manual review.
|
||||
|
||||
Prioritize a clean, maintainable foundation over a messy pixel-perfect clone.
|
||||
Prioritize visual fidelity and content correctness while implementing them with
|
||||
clean, maintainable Astro code. Do not trade away visible source design for a
|
||||
generic foundation, and do not copy HubSpot-generated implementation merely to
|
||||
obtain fidelity.
|
||||
|
||||
Reference in New Issue
Block a user