Keeping Technical Debt Deliberate

Technical debt is not simply old code or a large file. It is the extra cost of changing a system when its structure, tests, or tools no longer make that change easy to understand and verify.

The goal for this site is not to eliminate debt. That would turn maintenance into an endless rewrite. The goal is to keep debt visible, bounded, and proportional to what the site needs.

Reduce the Cost of Change#

Several parts of the site grew by doing more than one job. The shared layout mixed metadata with navigation and footer markup. Search mixed Pagefind loading, URL state, timers, and rendering. The portfolio gallery mixed presentation, modal behavior, carousel state, autoplay, and visibility.

Those areas were split along behavior boundaries. Static structure stayed in Astro, stateful interfaces stayed in small Vue islands, and reusable behavior moved into focused functions and composables. The result is not fewer files for its own sake. It is a smaller area to reason about when one behavior changes.

The same principle applies to build tooling. Open Graph images are deterministic. Sitemap dates have one tested resolver. Content security policy hashes synchronize from the built HTML. Shared validators traverse generated pages consistently. These changes replace recurring manual memory with repeatable work.

Test the Boundaries#

Unit tests cover request races, timer cleanup, observers, URL synchronization, image rendering helpers, and date resolution. Browser journeys cover the behavior a reader actually encounters: keyboard navigation, dialog focus restoration, search results, topic filters, autoplay, view transitions, theme controls, and cleanup after navigation.

The build remains the final contract. It checks types, generated images, static output, metadata, performance budgets, security policy, links, Pagefind, and machine-readable indexes. Tests do not prove that the site has no debt, but they make refactoring less speculative.

Would Webflow Create More Debt?#

For this site, a feature-for-feature migration to Webflow would probably incur technical debt before it removed any. The current system already has typed content, versioned source, deterministic assets, custom validation, local search, focused interactive components, and a static deployment model. Rebuilding those guarantees in another platform would create migration work and new integration boundaries.

Webflow could still reduce debt if the objective changed. Its visual editing and managed CMS may be a better operating model when non-developers need to publish and reshape pages frequently. That benefit would need to outweigh the loss of the current code-level workflow.

Portability is also conditional. Webflow can export HTML, CSS, JavaScript, and assets on eligible Workspace plans, but its code export does not include working CMS content, site search, forms, localized content, or code components. CMS items can be exported separately as CSV, while media in those exports can remain tied to Webflow-hosted URLs.

So the platform is not the debt by itself. Debt appears when the chosen platform and the desired operating model disagree. Moving this site to Webflow while demanding exact parity would likely add debt. Moving it to embrace a simpler, Webflow-native publishing model could reduce debt, but that would be a product decision rather than a technical cleanup.

Keep It Deliberate#

Some complexity is justified. A rich animation playground will be larger than a plain article. Search needs asynchronous state. A portfolio carousel needs lifecycle handling. The useful question is whether that complexity is isolated, tested, and worth maintaining.

Technical debt stays manageable when every exception has a boundary, every recurring task becomes a command, and every platform choice reflects how the site is actually maintained.