Web Development Toolkit
Best Practices for World-Class Web Presence - a living reference that demonstrates the very standards it documents.
Performance & Core Web Vitals
Google's Core Web Vitals are the definitive metrics for user experience. They directly influence search rankings and, more importantly, whether users stay on your site. Every millisecond counts.
Image Optimization
Images are typically the largest content on any page and the primary driver of LCP. Use modern formats, responsive sizing, and lazy loading for everything below the fold.
<picture>
<source srcset="hero.avif" type="image/avif" />
<source srcset="hero.webp" type="image/webp" />
<img
src="hero.jpg"
alt="Project architecture diagram"
width="1200"
height="630"
loading="lazy"
decoding="async"
fetchpriority="high"
/>
</picture>- Use
fetchpriority="high"on LCP images,loading="lazy"on everything else - Always set explicit
widthandheightattributes to prevent CLS - Serve AVIF → WebP → JPEG/PNG fallback chain
- Use
sizesattribute to tell the browser the rendered size at each breakpoint
fetchpriority="high".
Font Loading Strategy
Custom fonts cause invisible text (FOIT) or layout shift (FOUT). Control this with font-display and preloading.
@font-face {
font-family: 'Inter';
src: url('/fonts/inter-var.woff2') format('woff2');
font-display: swap; /* Show fallback immediately, swap when loaded */
font-weight: 100 900; /* Variable font - single file for all weights */
unicode-range: U+0000-00FF; /* Latin subset - reduces file size */
}<link rel="preload" as="font" type="font/woff2"
href="/fonts/inter-var.woff2" crossorigin />
<link rel="preconnect" href="https://fonts.googleapis.com" />- Self-host fonts for performance and privacy (no third-party requests)
- Use variable fonts to serve all weights in a single file
- Subset to Latin characters unless multilingual support is needed
- Preload the most critical font file in
<head>
Code Splitting & Preloading
Ship only the JavaScript needed for the current page. Defer heavy components and prefetch likely next navigations.
// Only load the heavy charting library when the user opens the dashboard
const loadDashboard = async () => {
const { renderCharts } = await import('./dashboard.js');
renderCharts(document.getElementById('charts'));
};
document.getElementById('dashboardTab')
.addEventListener('click', loadDashboard, { once: true });<!-- Preload critical above-fold resources -->
<link rel="preload" as="image" href="/hero.webp" />
<link rel="preload" as="style" href="/styles/main.css" />
<!-- Prefetch likely next pages -->
<link rel="prefetch" href="/compliance" />
<!-- DNS prefetch for third-party origins -->
<link rel="dns-prefetch" href="https://gc.zgo.at" />Accessibility
Accessibility is not a feature - it's a fundamental quality attribute. WCAG 2.2 AA is the legal baseline. We aim higher.
WCAG 2.2 New Success Criteria
WCAG 2.2 added several criteria addressing focus visibility, dragging alternatives, target sizing, consistent help, and accessible authentication.
- 2.4.11 Focus Not Obscured (AA): Focused elements must not be fully hidden by sticky headers, banners, or overlays
- 2.4.13 Focus Appearance (AAA): Focus indicators must have sufficient size (≥2px outline) and contrast
- 2.5.7 Dragging Movements (AA): Any drag interaction must have a non-dragging alternative (click/tap)
- 2.5.8 Target Size Minimum (AA): Interactive targets at least 24×24 CSS pixels, or 44×44 for AAA
- 3.2.6 Consistent Help (A): Help mechanisms appear in the same relative location across pages
- 3.3.7 Redundant Entry (A): Don't ask users to re-enter information already provided in the same session
- 3.3.8 Accessible Authentication (AA): No cognitive function tests (CAPTCHA puzzles) required for login
POUR Principles & Section 508
The four principles of accessibility form the foundation of all WCAG guidelines and Section 508 requirements:
Perceivable
Information must be presentable in ways all users can perceive. Alt text, captions, sufficient contrast, resize support.
Operable
Interface must be navigable via keyboard, screen reader, switch, and voice. No keyboard traps. Enough time for all interactions.
Understandable
Content and UI behavior must be understandable. Plain language, predictable navigation, input assistance, error prevention.
Robust
Content must work with current and future assistive technologies. Valid HTML, ARIA used correctly, progressive enhancement.
Section 508 (29 U.S.C. § 794d) requires federal agencies to make electronic and information technology accessible. It incorporates WCAG 2.0 AA by reference, with WCAG 2.2 adoption underway.
Cognitive Accessibility & Reduced Motion
- Body text ≥ 16px, line-height ≥ 1.5, max line length ~75 characters
- Consistent navigation location and order across all pages
- Plain language in UI copy; technical language reserved for content where appropriate
- Progress indicators for multi-step processes
- Confirmation before destructive actions
@media (prefers-reduced-motion: reduce) {
*,
*::before,
*::after {
animation-duration: 0.01ms !important;
animation-iteration-count: 1 !important;
transition-duration: 0.01ms !important;
scroll-behavior: auto !important;
}
}prefers-reduced-motion: reduce is active. Skip links, landmark roles, live regions, and axe-core automated testing are built in. The accessibility dashboard tracks WCAG conformance and generates VPAT/ACR data.
PDF/UA Compliance
Downloadable documents (resumes, case studies, reports) must be accessible too. PDF/UA (ISO 14289-1) is the standard.
- Tagged PDF structure with proper heading hierarchy
- Alt text on all images; decorative images marked as artifacts
- Logical reading order (not just visual layout)
- Bookmarks for documents longer than 20 pages
- Document language tag set
- All fonts fully embedded
Semantic HTML & ARIA Patterns
<!-- Skip link - first focusable element -->
<a href="#main-content" class="skip-link">Skip to content</a>
<!-- Live region for dynamic updates -->
<div id="liveAnnouncer" class="sr-only"
aria-live="polite" aria-atomic="true"></div>
<header role="banner">…</header>
<nav aria-label="Main navigation">…</nav>
<main id="main-content">
<article>…</article>
</main>
<aside aria-label="Related content">…</aside>
<footer role="contentinfo">…</footer>
<!-- Accessible icon button -->
<button aria-label="View source on GitHub">
<svg aria-hidden="true">…</svg>
</button>Security
Defense in depth. Every layer - headers, input validation, dependencies, authentication - must assume the others have failed. Zero Trust is the model.
Security Headers
HTTP security headers are the first line of defense. They instruct browsers to enforce security policies that prevent entire classes of attacks.
# Content Security Policy - strict, nonce-based
Content-Security-Policy:
default-src 'self';
script-src 'self' 'nonce-{random}';
style-src 'self' 'unsafe-inline';
img-src 'self' data: https:;
font-src 'self';
connect-src 'self';
frame-src 'none';
object-src 'none';
base-uri 'self';
form-action 'self';
frame-ancestors 'none';
upgrade-insecure-requests;
# HSTS - enforce HTTPS (2 years + preload)
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
# Prevent MIME sniffing
X-Content-Type-Options: nosniff
# Prevent clickjacking
X-Frame-Options: DENY
# Restrict browser features
Permissions-Policy:
camera=(), microphone=(), geolocation=(),
payment=(), usb=(), interest-cohort=()
# Referrer control
Referrer-Policy: strict-origin-when-cross-origin
# Cross-origin isolation
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Resource-Policy: same-originOWASP Top 10 (2021)
A01: Broken Access Control
Enforce least-privilege. Server-side authorization on every request. CORS restrictions. Deny by default.
A02: Cryptographic Failures
TLS 1.3 everywhere. Bcrypt/argon2 for passwords. No secrets in client bundles or version control.
A03: Injection
Parameterized queries. Input validation. CSP to prevent XSS. Output encoding on all user-generated content.
A04: Insecure Design
Threat modeling during design. Secure design patterns. Abuse case testing. Rate limiting.
A05: Security Misconfiguration
Hardened defaults. Remove unused features/frameworks. Automated configuration scanning. Security headers.
A06: Vulnerable Components
npm audit in CI. SBOM generation (CycloneDX). Dependabot/Renovate automated updates.
A07: Auth Failures
MFA. Rate limiting on login. Session management. No credential stuffing attack surface.
A08: Data Integrity Failures
SRI on external scripts. Signed commits. Verified CI/CD pipeline. SBOM verification.
A09: Logging & Monitoring
Structured logging (Winston). Request ID tracking. Audit trails. Alerting on anomalies.
A10: SSRF
Validate/sanitize all URLs. Allowlist outbound connections. Block internal network access from user inputs.
Subresource Integrity (SRI)
When loading scripts or styles from CDNs, SRI ensures the file hasn't been tampered with. The browser checks the cryptographic hash before execution.
<script
src="https://cdn.example.com/lib.js"
integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxAh..."
crossorigin="anonymous"
></script>Zero Trust Architecture (NIST SP 800-207)
Zero Trust assumes no implicit trust based on network location. Every request is authenticated, authorized, and continuously validated.
- Trust scoring engine - evaluate device posture, session risk, and behavior
- Dynamic access policies - adjust permissions based on real-time risk
- Micro-segmentation - isolate resources; no lateral movement
- Continuous verification - never "trust then forget"
- Least-privilege access - minimum permissions for every operation
Input Validation & Rate Limiting
import { z } from 'zod';
const ContactSchema = z.object({
name: z.string().min(1).max(100).trim(),
email: z.string().email().max(254),
message: z.string().min(10).max(5000).trim(),
honeypot: z.string().max(0), // Bot trap - must be empty
});
// Validate on server - never trust client-side validation alone
const result = ContactSchema.safeParse(req.body);
if (!result.success) {
return res.status(400).json({
type: 'https://httpstatuses.io/400',
title: 'Validation Error',
errors: result.error.flatten().fieldErrors,
});
}import rateLimit from 'express-rate-limit';
const contactLimiter = rateLimit({
windowMs: 15 * 60 * 1000, // 15 minutes
max: 5, // 5 requests per window
standardHeaders: true,
legacyHeaders: false,
message: { type: 'https://httpstatuses.io/429', title: 'Too Many Requests' },
});
app.post('/api/contact', contactLimiter, handleContact);Modern CSS
CSS has evolved dramatically. Container queries, subgrid, :has(), scroll-driven animations, cascade layers, and perceptually uniform color spaces are production-ready today.
Container Queries
Component-responsive design. Instead of styling based on the viewport, style based on the container a component lives in - enabling truly reusable components.
.card-container {
container-type: inline-size;
container-name: card;
}
@container card (min-width: 400px) {
.card {
flex-direction: row;
gap: var(--space-4);
}
.card-image { width: 40%; }
}
@container card (min-width: 700px) {
.card { grid-template-columns: 300px 1fr; }
}CSS Subgrid
Align nested grid children to the parent's track definitions. No more misaligned card content.
.project-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
gap: 2rem;
}
.project-card {
display: grid;
grid-template-rows: subgrid;
grid-row: span 3; /* title, description, meta - all aligned across cards */
}:has() Selector
The "parent selector" CSS never had - until now. Select elements based on their descendants without JavaScript.
/* Style a form group when its input is focused */
.form-group:has(input:focus) {
border-color: var(--color-primary);
box-shadow: var(--shadow-glow);
}
/* Card layout changes when it contains an image */
.card:has(img) {
grid-template-rows: 200px 1fr;
}
/* Hide a label when its input is empty */
.field:has(input:placeholder-shown) .field-label {
opacity: 0;
}Scroll-Driven Animations
Performant, GPU-accelerated scroll effects with zero JavaScript. Tied to scroll position or element visibility.
@keyframes fade-in {
from { opacity: 0; transform: translateY(20px); }
to { opacity: 1; transform: translateY(0); }
}
.section {
animation: fade-in linear both;
animation-timeline: view();
animation-range: entry 0% entry 100%;
}
/* Respect user preferences */
@media (prefers-reduced-motion: reduce) {
.section { animation: none; }
}Cascade Layers & Design Tokens
Cascade layers (@layer) solve specificity wars at scale. Combined with custom properties as design tokens, you get a maintainable, themeable system.
/* Define layer order - later layers win */
@layer reset, base, tokens, components, utilities;
@layer tokens {
:root {
--color-primary: oklch(0.6 0.2 260);
--space-md: clamp(1rem, 2vw, 2rem);
--text-base: clamp(1rem, 0.9rem + 0.35vw, 1.125rem);
--radius-md: 0.5rem;
}
}
@layer components {
.card {
background: var(--surface-card);
border-radius: var(--radius-md);
padding: var(--space-md);
}
}
@layer utilities {
.visually-hidden {
clip: rect(0 0 0 0);
clip-path: inset(50%);
height: 1px;
width: 1px;
overflow: hidden;
position: absolute;
white-space: nowrap;
}
}tokens.css - colors, spacing scale, typography scale, radii, shadows, transitions, layout breakpoints, and z-index scale. Light/dark themes swap only semantic token values.
oklch() Colors & clamp() Typography
oklch() provides perceptually uniform colors - adjusting lightness by the same amount always looks like the same visual change. clamp() enables fluid typography without media queries.
:root {
/* oklch(Lightness Chroma Hue) - perceptually uniform */
--color-primary: oklch(0.6 0.2 155); /* Forest green */
--color-primary-light: oklch(0.8 0.15 155);
--color-primary-dark: oklch(0.35 0.2 155);
/* Fluid type scale - no breakpoints needed */
--text-sm: clamp(0.875rem, 0.8rem + 0.25vw, 1rem);
--text-base: clamp(1rem, 0.9rem + 0.35vw, 1.125rem);
--text-lg: clamp(1.25rem, 1rem + 0.75vw, 1.5rem);
--text-xl: clamp(1.5rem, 1.2rem + 1vw, 2rem);
--text-2xl: clamp(2rem, 1.5rem + 1.5vw, 3rem);
/* Fluid spacing */
--space-md: clamp(1rem, 2vw, 1.5rem);
--space-lg: clamp(1.5rem, 3vw, 2.5rem);
}SEO & Discoverability
Technical SEO ensures search engines can crawl, understand, and rank your content. Structured data, semantic HTML, and Core Web Vitals are the foundations.
Structured Data (JSON-LD)
JSON-LD enables rich search results - knowledge panels, article cards, FAQ accordions. Embed structured data in every page's <head>.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "WebSite",
"name": "Structured For Growth",
"url": "https://structured-for-growth.onrender.com",
"description": "Agentic solutions that scale."
},
{
"@type": "Organization",
"name": "Structured For Growth",
"url": "https://structured-for-growth.onrender.com",
"knowsAbout": [
"FedRAMP", "CMMC", "NIST 800-53", "OSCAL",
"WCAG 2.2", "Section 508",
"Zero Trust Architecture", "React", "Node.js"
]
}
]
}
</script>TechArticle schema. The compliance page uses WebSite + Organization schemas.
Technical SEO Checklist
- Canonical URLs -
<link rel="canonical">on every page to prevent duplicate content - Open Graph meta -
og:title,og:description,og:image(1200×630px) for rich social sharing - Twitter Cards -
twitter:card,twitter:titlefor X/Twitter previews - Sitemap.xml - Auto-generated, submitted to Google Search Console
- robots.txt - Allow all crawlers, reference sitemap location
- Semantic HTML - Single
<h1>per page, logical heading hierarchy - Mobile-first - Google uses mobile-first indexing
- Core Web Vitals - LCP, INP, CLS directly affect ranking
- Internal linking - Cross-link between related pages for crawl depth
- Descriptive alt text - On all images (not keyword-stuffed)
Open Graph & Twitter Cards
<!-- Open Graph -->
<meta property="og:title" content="Page Title - Site Name">
<meta property="og:description" content="Concise, compelling description under 155 chars.">
<meta property="og:type" content="article">
<meta property="og:url" content="https://example.com/page">
<meta property="og:image" content="https://example.com/og-image.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<!-- Twitter -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Page Title">
<meta name="twitter:description" content="Description for Twitter previews.">Progressive Enhancement
Build so content works without JavaScript, then layer on interactivity. The site should be resilient - offline-capable, format-adaptive, and gracefully degradable.
Offline-First PWA & Service Workers
Service workers intercept network requests and serve cached content when offline. Choose caching strategies based on content type:
Cache-First
Static assets (CSS, JS, fonts, images). Serve from cache immediately; update in background.
Stale-While-Revalidate
HTML pages. Serve cached version instantly, fetch fresh version for next visit.
Network-First
API calls and dynamic data. Try network; fall back to cache if offline.
{
"name": "Structured For Growth",
"short_name": "SFG",
"start_url": "/",
"display": "standalone",
"theme_color": "#0a1f14",
"background_color": "#0a1f14",
"icons": [
{ "src": "/assets/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
{ "src": "/assets/icons/icon-512.png", "sizes": "512x512", "type": "image/png" }
]
}sw.js) is registered on all pages with update detection and user-prompted refresh. The site includes a manifest.json for PWA installation.
No-JS Fallbacks
The core content and navigation must work with JavaScript completely disabled:
- All navigation links are standard
<a>elements (no JS-only routing) - Content is server-rendered HTML (not client-side rendered)
- Forms degrade to standard POST submissions
- Interactive features (tabs, accordions) use
<details>/<summary>as baseline - CSS handles layout, animation, and state where possible (no JS required)
Responsive Images
<picture>
<!-- Art-directed crop for mobile -->
<source
media="(max-width: 640px)"
srcset="hero-mobile.avif"
type="image/avif" />
<source
media="(max-width: 640px)"
srcset="hero-mobile.webp"
type="image/webp" />
<!-- Default desktop -->
<source srcset="hero.avif" type="image/avif" />
<source srcset="hero.webp" type="image/webp" />
<!-- Ultimate fallback -->
<img src="hero.jpg" alt="Descriptive alt text"
width="1200" height="630"
loading="lazy" decoding="async" />
</picture>Federal Digital Standards
Federal websites operate under specific legislative and policy mandates. These standards define minimum requirements for design, accessibility, security, and user experience across all federal digital properties.
21st Century IDEA Act
The 21st Century Integrated Digital Experience Act (Pub.L. 115-336) requires federal agencies to modernize their websites. Key requirements:
- Accessible - WCAG 2.0 AA compliant (WCAG 2.2 adoption in progress)
- Consistent - Follow USWDS design system for visual and UX consistency
- Searchable - Site search functionality on all public-facing sites
- Secure - HTTPS enforced, security headers, HSTS preload
- Mobile-friendly - Responsive design for all device sizes
- Customer-driven - User research and usability testing
- Digitize paper forms - Electronic alternatives for paper-based processes
OMB M-23-22 - Delivering a Digital-First Public Experience
OMB Memorandum M-23-22 builds on the IDEA Act with specific implementation requirements:
- Required banner: Official U.S. government website banner at the top of every page
- Unique page titles: Every page must have a descriptive, unique
<title> - Meta descriptions: Accurate
<meta name="description">on every page - Contact page: A publicly accessible contact page
- Timeliness indicators: "Last updated" dates on content pages
- Search: Site-wide search functionality
- Analytics: DAP (Digital Analytics Program) participation
USWDS Design System
The U.S. Web Design System provides a library of accessible, mobile-friendly components and design tokens used across federal agencies. Key principles:
Start with real user needs
Research-driven design. Test with real users, including those with disabilities.
Earn trust
Consistent, professional UI signals legitimacy. The .gov banner, HTTPS indicator, and accessible design build confidence.
Embrace accessibility
WCAG 2.2 AA as a floor, not a ceiling. Automated testing + manual testing + assistive technology testing.
Promote continuity
Design tokens and component patterns ensure visual and functional consistency across agencies.
digital.gov Standards
digital.gov publishes implementation guidance for the IDEA Act and M-23-22. Key standards beyond those already covered:
- Plain language: Content must be written clearly per the Plain Writing Act of 2010
- Multilingual support: Content in languages appropriate to the audience
- Performance budgets: Target page load times and resource sizes
- Third-party services: Assess privacy impact of analytics, chat, social media integrations
- Decommissioning: Redirect old pages (301) rather than showing 404s
Architecture
Good architecture makes change easy and safe. Component-based design, modular structure, automated testing, and CI/CD pipelines form the backbone of maintainable systems.
Component-Based Design
Decompose the UI into isolated, reusable components. Each component owns its markup, styles, and behavior. Benefits: testability, reuse, parallel development.
- Single Responsibility: Each component does one thing well
- Props-driven: Configuration via inputs, not internal assumptions
- Composable: Combine small components into larger features
- Documented: Each component has usage examples and prop documentation
Module Structure & Code Splitting
project/
├── client/ # Frontend assets
│ ├── styles/ # CSS (tokens → base → components → pages)
│ ├── js/ # JavaScript modules (page-specific entry points)
│ └── assets/ # Static files (images, fonts, icons)
├── server/
│ ├── middleware/ # Auth, CSRF, rate-limit, ZTA, logging
│ ├── routes/ # API route handlers (one file per domain)
│ ├── services/ # Business logic (separated from HTTP layer)
│ └── utils/ # Shared utilities
├── tests/
│ ├── unit/ # Fast, isolated tests (Vitest)
│ ├── e2e/ # Browser-level tests (Playwright)
│ └── a11y/ # Accessibility tests (axe-core)
├── .github/workflows/ # CI/CD pipeline definitions
└── docs/ # ADRs, API docs, architecture diagramsTesting Strategy
The testing pyramid: many fast unit tests, fewer integration tests, a handful of E2E tests. Each layer catches different types of bugs.
Unit Tests (Vitest)
Test individual functions and modules in isolation. Fast (<5s total). Run on every commit. Target: >80% coverage.
Integration Tests
Test API routes with real middleware stack (supertest). Verify request→response contracts. Cover auth, validation, error handling.
E2E Tests (Playwright)
Test critical user flows in a real browser. Navigation, form submission, interactive features. Run in CI, not on every commit.
Accessibility Tests (axe-core)
Automated a11y scanning catches ~57% of WCAG violations. Complements manual testing with screen readers and keyboard navigation.
CI/CD Pipeline (SAST / DAST / SBOM)
A mature CI/CD pipeline automates quality gates: lint, test, scan, build, release. Nothing ships without passing every gate.
# Stage 1: CI - lint, format, test (coverage), a11y, matrix build
# Stage 2: SAST - CodeQL static analysis (weekly + push)
# Stage 3: DAST - OWASP ZAP dynamic scan (weekly + push)
# Stage 4: Release - SBOM generation, license check, GitHub Release
# Key practices:
- name: Security Audit
run: npm audit --audit-level=moderate
- name: SBOM Generation
uses: CycloneDX/gh-node-module-generatebom@v1
- name: License Compliance
run: npx license-checker --onlyAllow 'MIT;ISC;BSD-2-Clause;BSD-3-Clause;Apache-2.0'- SAST (Static): CodeQL finds vulnerabilities in source code without running it
- DAST (Dynamic): OWASP ZAP tests the running application for runtime vulnerabilities
- SBOM: CycloneDX Bill of Materials tracks every dependency for supply chain security
- License compliance: Automated checks ensure no copyleft contamination
Environment Management
- Environment variables: Never commit secrets. Use
.envlocally, CI secrets in production - Configuration layers:
.env.defaults→.env.local→ CI environment → runtime overrides - Feature flags: Toggle features per environment without code changes
- Docker: Containerize for reproducible dev/test/prod environments
- EditorConfig + Prettier: Consistent formatting across all contributors
Documentation
Code without documentation is a liability. Good documentation multiplies a team's effectiveness and proves the thinking behind decisions - not just the decisions themselves.
Architecture Decision Records (ADRs)
ADRs capture the why behind technical decisions. When someone asks "why did we choose X over Y?", the ADR answers definitively.
# ADR-001: Use Express.js over Fastify for API Server
## Status
Accepted (2026-01-15)
## Context
We need an HTTP server framework for the portfolio API.
Key requirements: middleware ecosystem, security headers
(Helmet), rate limiting, and CSRF protection.
## Decision
Use Express.js with Helmet, express-rate-limit, and csrf-csrf.
## Rationale
- Helmet provides 15+ security headers out of the box
- express-rate-limit supports sliding window and token bucket
- Mature middleware ecosystem for PIV/CAC, TOTP, ZTA
- Team familiarity reduces onboarding time
## Consequences
- Slightly lower raw throughput than Fastify (~15%)
- Accepted tradeoff: security middleware ecosystem > raw speed
- Will revisit if/when throughput becomes a bottleneckAPI Documentation
API docs should be interactive, auto-generated from source, and always up to date. OpenAPI/Swagger is the standard.
import swaggerJsdoc from 'swagger-jsdoc';
import swaggerUi from 'swagger-ui-express';
const spec = swaggerJsdoc({
definition: {
openapi: '3.0.0',
info: {
title: 'Structured For Growth API',
version: '1.0.0',
description: 'Portfolio site API with compliance, accessibility, and security endpoints.',
},
servers: [{ url: '/api/v1' }],
},
apis: ['./server/routes/*.js'],
});
app.use('/docs', swaggerUi.serve, swaggerUi.setup(spec));/docs. API errors follow RFC 7807 Problem Details format.
Case Study Format
A well-structured case study tells the story of a project in a way that demonstrates thinking, not just output:
## Overview
One-paragraph summary: what, why, and measurable impact.
## Context & Challenge
What problem existed? What constraints (timeline, budget, tech, regulatory)?
## Approach
Technical decisions with rationale. Architecture diagrams (C4 model).
Why this stack? What alternatives were considered?
## Implementation
Key code patterns, interesting solutions. What worked, what didn't.
Show real code - sanitized but authentic.
## Results
Metrics: before/after comparisons. Performance gains.
Client feedback. User impact numbers.
## Lessons Learned
What would you do differently? What surprised you?
What did this project teach you?CONTRIBUTING.md & Project Documentation
Every project should have documentation that enables a new contributor to be productive within an hour:
- README.md: What this is, how to run it, how to deploy it
- CONTRIBUTING.md: Code style, branch strategy, PR process, testing requirements
- SECURITY.md: How to report vulnerabilities, supported versions
- CHANGELOG.md: What changed, when, why (auto-generated from conventional commits)
- LICENSE: Clear licensing terms
- .editorconfig: Consistent formatting without tool-specific config
Technical Writing Best Practices
- Lead with the conclusion: Tell readers the answer first, then explain
- One idea per paragraph: Dense paragraphs lose readers
- Use concrete examples: Show, don't just tell
- Include reading time estimates: Respect the reader's time
- Add "Last updated" dates: Build credibility through freshness
- Syntax-highlighted code: With clear language labels
- Table of contents: For anything longer than 3 screens
- RSS feed: Let readers subscribe for updates
Ready to Build World-Class?
Structured For Growth doesn't just know these practices - we implement them. Every standard documented here is demonstrated in our own infrastructure. Let's apply them to yours.
Get in Touch