General Standards

Overview

Every project I ship follows these baseline standards — web apps, browser extensions, mobile apps, desktop tools, games, and open source. They ensure consistency, maintainability, and professional quality regardless of the tech stack.

Start here before any new project. Category-specific pages (Web Development, Browser Extensions, etc.) build on this foundation with stack-specific guidance.

Core philosophy:

• Production-grade from day one — tests, CI, monitoring, and accessibility are not afterthoughts
• Minimalism where it improves UX or performance — zero-JS defaults, no unused dependencies
• Privacy and accessibility as non-negotiable architecture decisions, not policies
• Every decision documented so future-me (and collaborators) understand the rationale

File & Directory Structures

Universal Principles

• Feature-based over type-based for anything beyond a small script. Group by domain, not by file type.
• Colocation — keep related code together (component with its styles, tests, and hooks).
• Consistent naming:
  • kebab-case for files and directories
  • PascalCase for components and classes
  • camelCase for variables, functions, and instances
  • UPPER_CASE for environment variables and constants
• Flat until it hurts — don’t nest prematurely. Add structure only when a directory has 7+ entries.

Recommended Base Structure (Medium+ Projects)

project-root/
├── src/
│   ├── app/                  # App shell, layouts, providers
│   ├── components/           # Shared UI components
│   ├── features/             # Domain/feature modules
│   │   └── [feature-name]/
│   │       ├── components/
│   │       ├── hooks/
│   │       ├── utils/
│   │       └── index.ts
│   ├── lib/                  # API clients, utilities, shared logic
│   ├── styles/               # Global CSS, design tokens, theme
│   ├── types/                # Shared TypeScript types/interfaces
│   └── utils/                # Pure utility functions
├── public/                   # Static assets (favicons, images, fonts)
├── tests/                    # E2E and integration tests
├── docs/                     # ADRs, architecture decisions, setup guides
├── .env.example
├── package.json
├── tsconfig.json
└── README.md

For small projects (single-file scripts, tiny tools): Flat structure with an index.ts and utils.ts is acceptable.

.gitignore Standards

Every project must ignore:

• .env, .env.local, .env.*.local
• node_modules/
• Build output: dist/, .astro/, .next/, build/, out/
• OS files: .DS_Store, Thumbs.db, desktop.ini
• IDE: .vscode/, .idea/, *.swp, *.swo
• Logs: *.log, npm-debug.log*

Git Workflow & Version Control

Branching Model

main ─── production-ready, protected, deploys automatically
  │
  ├── feat/feature-name ── new features (branch from main)
  ├── fix/bug-description ── bug fixes (branch from main)
  ├── hotfix/critical-fix ── urgent production fixes (branch from main)
  └── chore/task ── tooling, config, dependencies

Conventional Commits

Every commit message follows the Conventional Commits specification:

<type>: <imperative description>

[optional body]

[optional footer]

Examples from this codebase:

feat: add dashboard export to VibeBranding analytics
fix: resolve scroll reveal deadzone on mobile Safari
docs: update general standards for 2026 trends
chore: upgrade Astro to 6.3.7
perf: replace React with Preact for island components

Commit Hygiene

• Atomic commits — one logical change per commit
• Write commits in present tense (“add feature” not “added feature”)
• Reference issues/PRs in footer when applicable: Closes #42
• No WIP commits on main — use feature branches with draft PRs

Pull Request Standards

Even on solo projects, use PRs for significant changes:

• Forces structured commit messages
• Allows review before merge (even self-review after a day away)
• Creates a clear history of intent
• Draft PRs for work-in-progress

PR template (minimal):

## What
Brief description of the change.

## Why
Motivation and context.

## Testing
How did you verify this works?

## Checklist
- [ ] Tests pass
- [ ] Lighthouse 100 target met
- [ ] Accessibility checked
- [ ] Privacy impact reviewed

Accessibility Standards

Target: WCAG 2.2 Level AA (AAA where feasible).

Mandatory Practices

Testing Tools

• Lighthouse CI — automated in deployment pipeline
• axe DevTools — browser extension for manual audit
• Playwright accessibility tests — @axe-core/playwright for critical flows
• Screen reader testing: VoiceOver (macOS), NVDA (Windows), TalkBack (Android)
• Keyboard-only walkthrough — tab through every interactive element before shipping

Color & Theme

All projects should support dark and light mode using the data-theme attribute pattern (see this site’s theme implementation). Never hardcode colors — use semantic CSS variables:

--text-primary
--text-secondary
--text-tertiary
--bg-page
--bg-surface
--border-default
--border-strong
--accent-primary

Performance Standards

Core Web Vitals Targets (2026)

Universal Tactics

1. Ship minimal JavaScript — Use React islands pattern with Preact where possible (see this site’s Preact migration). Only hydrate components that need interactivity.
2. Optimize images — Use modern formats (AVIF, WebP), responsive srcsets, lazy loading with proper loading="lazy" and decoding="async".
3. CSS optimization — Tailwind with purge, avoid runtime CSS-in-JS, use semantic utility classes.
4. Font loading — Self-host fonts, use font-display: swap, subset where possible.
5. View transitions — Use Astro’s built-in view transitions for smooth page navigation without client-side routing overhead.
6. Lazy hydration — Defer non-critical JavaScript with client:visible or client:idle.
7. Bundle analysis — Run a bundle analyzer before major releases to catch regressions.

Privacy & Security Standards

Data Handling Principles

• Collect only what’s strictly necessary — no speculative data collection
• No telemetry without consent — never ship analytics, crash reporters, or tracking without explicit opt-in
• Local-first where possible — process data on-device, not on servers (see Arc Optimizer — zero network calls)
• COPPA/GDPR-K compliance by architecture — if children might use it, design for zero data collection from the start (see Murmur app)
• Privacy consent on first run — for desktop tools that modify local files, explicit dialog before any action

Security Checklist

• Dependency audit on every major update: npm audit
• Principle of least privilege for permissions (especially browser extensions)
• Input validation on all user-supplied data
• HTTPS everywhere — no mixed content
• Never commit secrets — .env is in .gitignore, use environment variables in CI
• CSP headers where feasible (browser extensions, web apps)
• Rate limiting on API endpoints and login forms

SEO & GEO Standards

Traditional SEO

Generative Engine Optimization (GEO) — 2026+

AI models (ChatGPT, Gemini, Claude) increasingly influence how users discover information. Optimize for AI context windows:

1. Clear document structure — Well-defined sections with explicit headings
2. First-hand experience — Write from real shipped work, not theory
3. Direct answers — Put key information early; don’t bury it in fluff
4. Lists and tables — AI models parse structured content more reliably than dense prose
5. “Last updated” dates — Signal freshness and reliability
6. Internal cross-links — Link to related standards and blog posts to create context clusters
7. Authoritative specificity — Name exact versions, tools, libraries, and configurations

Development Workflow

AI-Assisted SDLC

AI tools accelerate development but never replace judgment. Follow this workflow:

1. Scaffolding — Let AI generate boilerplate, file structures, and initial config
2. Implementation — Use AI pair programming for implementation, but review every line
3. Testing — AI generates test cases; you verify edge cases and assertions
4. Refactoring — AI suggests improvements; you evaluate trade-offs
5. Documentation — AI drafts docs; you ensure accuracy and completeness

Always:

• Understand AI-generated code before committing
• Verify AI-suggested dependencies are legitimate and maintained
• Test AI-generated solutions with actual edge cases

Testing Philosophy

• Unit tests for pure logic, utilities, and data transformations
• Integration tests for API routes, database operations, and service boundaries
• E2E tests (Playwright) for critical user flows
• Accessibility tests (axe-core) as part of the CI pipeline
• Visual regression tests for UI components (when applicable)
• Not 100% coverage — meaningful coverage is better than meaningless line coverage
• Tests run in CI on every PR and before every deployment

Local Development

• Fast feedback loop via Vite HMR or Astro’s dev server
• Consistent environment via .env.example + setup script
• Pre-commit hooks (Husky) run: npm run check → npm test → npm run build
• Linting runs on save (VS Code + ESLint + Prettier)

Trends to Watch (2026+)

• Server-first rendering — Move toward edge rendering and partial hydration
• AI-native development — LLM-assisted coding becoming standard workflow
• Real-user monitoring — Beyond synthetic testing (INP, interaction tracking)
• Platform convergence — Web apps gaining native-like capabilities (WebGPU, File System API, Bluetooth)
• Privacy-first products — Users increasingly choose minimal-data alternatives
• Performance as UX — Core Web Vitals directly impact search ranking and conversion

Project Templates & Quick Starts

• Astro Starter Kit — Project scaffold, Tailwind tokens, AI workflow cheatsheet
• General Project README template — Consistent documentation boilerplate
• Shipping checklist component — Interactive checklists on every category page

References

• Replacing React with Preact — Bundle size wins and island architecture
• Astro 6 Performance: Zero-JS Defaults — How this site achieves Lighthouse 100
• Securing AI Developer Workflows — Security practices for AI-assisted development
• Privacy-First Analytics Architecture — Minimal data collection strategies
• External: Web.dev Performance, WCAG 2.2, MDN Accessibility