🇧🇷 Português (pt-BR)

About • Quality Gates • SEO • Performance • Accessibility • Testing • Stack • Structure • Getting Started • Documentation • Deploy • License

Technical boilerplate for static landing pages — SEO, performance, accessibility, and automated testing from day one.

The engineering base behind my future products and client sites: I copy this repository, customize content and visuals, and keep the same quality standards.

Decision priority: SEO → performance → accessibility → aesthetics

---

📌 About

baseCO is a copyable template — a single Astro app at the repo root, duplicated per project or client, with quality pipelines already wired in.

Principle	Description
Copyable template	One repository per client — duplicate and customize
Content × visual separation	Copy in Content Collections (Zod); styling via CSS hooks
Progressive enhancement	Works without JS; islands only when needed
Zero regression	Every delivery runs through bun run quality
AI-ready	AGENTS.md + docs/guidelines/ for consistency across projects

This README documents how the base enforces technical quality — not layout showcases, routes, APIs, or UI design.

---

🎯 Quality Gates

Mandatory targets for every project built from this base:

Gate	Target	Tool
Lighthouse Performance	≥ 95	Lighthouse CI
Lighthouse Accessibility	≥ 95	Lighthouse CI + axe-core
Lighthouse Best Practices	≥ 95	Lighthouse CI
Lighthouse SEO	≥ 95	Lighthouse CI + e2e
LCP (lab)	≤ 1.8s	Lighthouse CI
CLS	≤ 0.02	Lighthouse CI
INP	≤ 150ms	Budget + minimal islands
axe-core (e2e)	0 WCAG 2.2 AA violations	Playwright
pa11y-ci	0 errors	post-build
ESLint + jsx-a11y	0 errors	pre-commit + CI
astro check	0 errors	CI

Unified pipeline:

bun run quality   # lint + check + build + e2e + a11y + lighthouse

CI: .github/workflows/quality.yml (GitHub Actions + Bun).

---

🔍 SEO

Ready for local SEO and indexing:

• Dynamic JSON-LD LocalBusiness (src/seo/LocalBusinessJsonLd.astro)
• Meta tags in Layout.astro — title, description, canonical, Open Graph, Twitter Card
• robots.txt + automatic sitemap.xml (@astrojs/sitemap)
• Raster OG image 1200×630 (public/og-default.jpg)
• Automatic route discovery — new static pages are picked up by tests and Lighthouse without manual config

Automated checks in e2e/seo/ (meta tags, canonical, JSON-LD, robots.txt, 4xx/5xx smoke).

---

⚡ Performance

Core Web Vitals optimizations and guardrails:

• Fully static build (output: 'static') + compressHTML
• LCP image with loading="eager", fetchpriority="high", astro:assets + Sharp (WebP)
• LazySection for below-the-fold content
• Islands on demand (client:media for mobile menu — no JS on desktop)
• Performance budget in testing/lighthouse-budget.json (JS ≤ 80 KB gzip, etc.)
• Lighthouse CI — 3 runs, assertions on every route in dist/

---

♿ Accessibility

Target: WCAG 2.2 Level AA, enforced in CI.

Feature	Implementation
Skip link	SkipLink.astro → #main-content
Landmarks	Semantic header, nav, main, footer
Mobile menu	aria-expanded, focus trap, Escape
aria-current	Hash-based anchor navigation
Focus visible	src/styles/a11y.css (:focus-visible)
Reduced motion	prefers-reduced-motion in global CSS
Forms	Labels, aria-required, focus order tested
Primitives	Button, Dialog (native <dialog>), VisuallyHidden

Tools: eslint-plugin-jsx-a11y, @axe-core/playwright, pa11y-ci, keyboard tests in e2e/a11y/keyboard-nav.spec.ts.

---

🧪 Testing

E2E suite with automatic route discovery (testing/discover-routes.ts):

e2e/
├── a11y/       # axe-core on all routes + keyboard
├── seo/        # meta tags, JSON-LD, robots.txt
├── flows/      # anchor navigation, aria-current
├── visual/     # visual regression (chromium)
└── helpers/    # axe-setup, seo-assertions

Command	Purpose
bun run test:e2e	Playwright (desktop + mobile)
bun run a11y	pa11y-ci post-build
bun run lighthouse	Lighthouse CI
bun run lint	ESLint + jsx-a11y
bun run check	astro check (types)

Pre-commit: Husky + lint-staged (ESLint + Prettier on staged files).

Adding a static page under src/pages/ automatically extends a11y, SEO, Lighthouse, and pa11y coverage.

---

💻 Stack

Layer	Technologies
Framework	Astro 5 (static)
Language	TypeScript
Styling	Tailwind CSS 3
Images	Sharp (astro:assets)
Content	Content Collections + Zod
CMS	Decap CMS (/admin)
Package manager	Bun
E2E	Playwright + @axe-core/playwright
Performance	@lhci/cli
A11y scan	pa11y-ci
Lint	ESLint 9 + eslint-plugin-astro + jsx-a11y
CI	GitHub Actions

---

📁 Structure

baseCO/                     # copy for each new product or client
├── src/
│   ├── components/         # sections + primitives/ + islands/
│   ├── seo/                # JSON-LD, types
│   ├── content/            # Zod-validated JSON
│   ├── layouts/            # Layout.astro (head, SEO)
│   └── pages/              # static routes
├── e2e/                    # Playwright + quality helpers
├── scripts/                # lighthouse, validate-a11y
├── testing/                # discover-routes, lighthouse-budget
├── docs/guidelines/        # standards (performance, a11y, SEO…)
├── AGENTS.md               # AI entry point
└── package.json            # quality scripts

---

🚀 Getting Started

Clone

git clone https://github.com/MarlonVictor/baseCO.git
cd baseCO

Install

bun install
# or: npm install

Development

bun run dev

Open http://localhost:4321 · CMS at http://localhost:4321/admin.

Run quality checks

bun run quality

Production build

bun run build    # output → dist/
bun run preview  # serve dist/ locally

New project from this base

1. Duplicate the repository (GitHub “Use this template” or local copy)
2. Follow docs/NEW-LANDING-GUIDE.md
3. Run bun run quality before delivery

---

📚 Documentation

Resource	Content
AGENTS.md	AI entry point — stack, goals, conventions
docs/guidelines/	Standards by area (performance, a11y, SEO, testing)
docs/guidelines/70-new-page-component.md	Checklist for new pages/components
docs/NEW-LANDING-GUIDE.md	Step-by-step for a new client
docs/PLANO-BOILERPLATE-CORPORATIVO.md	Technical roadmap and phases
docs/GUIA-DOS-ARQUIVOS.md	Documentation index
docs/templates/	Copyable templates (components, pages, tests)

---

🌐 Deploy

Netlify, Cloudflare Pages, and Vercel — cache headers and optional RUM snippet:

→ docs/DEPLOY.md

---

📃 License

Internal use for development and freelance projects. Restricted distribution at the author's discretion.