shruggie-web

The official ShruggieTech website — a Next.js marketing and content site covering our services, case studies, blog, and open-source products.

Tech Stack

Layer	Technology
Framework	Next.js (App Router, React Server Components)
Language	TypeScript (strict mode)
Styling	Tailwind CSS 4.x
Motion	Framer Motion, GSAP, Lenis smooth scroll
Blog content	Firestore-authoritative Markdown via next-mdx-remote/rsc, syntax highlighting via Shiki
Contact form	Formspree + React Hook Form + Zod validation
Analytics	Google Analytics 4 + Google Tag Manager (consent-gated)
Deployment	Vercel

The full, authoritative specification for page structure, design tokens, and content requirements lives in ShruggieTech_Website_Specification.md.

The production editorial backend architecture is documented in docs/architecture/adr-001-firebase-editorial-backend.md, with production procedures in docs/operations/firebase-production.md. The versioned article, Markdown, asset, error, and export contracts are in docs/editorial/content-contract.md. Production dependency audit policy and the temporary Firebase advisory record are in docs/operations/dependency-security.md. Staff identity, session, authorization, mutation, and audit controls are in docs/operations/editorial-security.md. Migration, export, cutover, and recovery procedures are in docs/editorial/migration-and-cutover.md.

Getting Started

Prerequisites: Node.js 22 LTS or newer, npm. (Next.js 16 requires Node ≥20.9.0 at minimum per package-lock.json, but Node 20 has since reached end-of-life — use an actively maintained LTS release.)

# Install dependencies
npm install

# Copy environment variables and fill in the values you need
# (GA4/GTM IDs, Formspree form ID — see ShruggieTech_Website_Specification.md §10.2)
cp .env.example .env.local

# Start the dev server at http://localhost:3000
npm run dev

Available Scripts

Command	Description
npm run dev	Start the local development server
npm run build	Production build
npm run start	Serve the production build
npm run lint	Run ESLint
npm test	Run contrast and editorial contract tests
npm run test:contrast	Run light/dark accessibility contrast regression tests
npm run test:editorial	Run schema, adapter, asset, export, and repository MDX tests
npm run test:integration	Run Firebase adapters against local Firestore/Storage emulators
npm run test:all	Run both test layers
npm run cms:migrate	Dry-run or apply the reviewed repository blog migration
npm run cms:export	Export articles and verified asset bytes outside the repository

Before opening a PR, also confirm the build type-checks cleanly:

npx tsc --noEmit

Project Structure

app/            Route segments (App Router) — one folder per page, plus
                api/, sitemap.ts, robots.ts
components/     Shared React components, grouped by domain
                (ui/, shared/, layout/, about/, blog/, home/, products/)
content/        Recovery blog corpus and authored MDX work case studies
lib/            Data access and utilities (blog, case studies, schema, etc.)
public/         Static assets (images, fonts, favicons)
styles/         Global CSS and design tokens
.specify/       Spec-kit configuration, templates, and project constitution
specs/          Feature specs/plans/tasks generated by spec-kit (created as
                features go through the workflow below)

Content Authoring

• Blog posts are created, previewed, and published through the authorized /admin workspace. The frozen files in content/blog/ are migration and disaster-recovery inputs, not a production authoring path. See ShruggieTech_Website_Specification.md §7 and the migration runbook.
• Case studies are MDX files in content/work/.

Contributing

Feature-sized work follows spec-kit's Spec-Driven Development workflow, gated by the project constitution at .specify/memory/constitution.md (specification precedence, design-system reuse, WCAG 2.2 AA accessibility, and the Core Web Vitals performance budget):

/speckit-specify   → describe the feature
/speckit-clarify   → resolve ambiguity (if needed)
/speckit-plan      → generate the implementation plan
/speckit-tasks     → break the plan into tasks
/speckit-analyze   → check cross-artifact consistency (optional)
/speckit-implement → execute the tasks

Trivial one-commit changes (typos, copy fixes, dependency bumps) can skip the full workflow. For everything else:

• Match the existing design system — reuse tokens and components under components/ui/ and components/shared/ before adding new ones.
• Every interactive element must be keyboard-reachable, every image needs appropriate alt text, and every animation must respect prefers-reduced-motion.
• Run npm run build, npx tsc --noEmit, and npm run lint before opening a PR.
• Update CHANGELOG.md for user-facing changes.
• Commit messages follow <scope>: <imperative description> (e.g. web: add CTA to blog article template).

Pull requests are automatically reviewed by an AI code review bot in addition to human review — address its comments the same as any other reviewer's.

License

Apache License 2.0 — see LICENSE.