What clean code means on a marketing site

Clean code on a marketing site means a later editor can find the headline, the sections, and the images without a treasure hunt. A maintainable marketing website is readable by the next person, modular enough to change one section, and boring to update on a Tuesday.

That is a founder-facing definition. It is also what Hanabi means by clean code: readable, modular builds that stay easy to improve. The compliment is not a clever abstraction. The compliment is that a teammate opened the project and knew where the sentence lived.

The headline has an address

On a messy marketing site, the first screen is assembled from a layout component, a hard-coded string, a CMS field nobody remembers, and a caption baked into an image. Changing "what we do" takes a search through the repo and a guess. Someone is afraid to delete the wrong duplicate.

On a clean site, the headline is a field or a single component prop with a name you would say out loud. The subhead sits next to it. The primary action sits next to that. A new teammate can be shown the file in a minute. The page still has to be designed. The design is simply stored where the words are.

This is the first test to ask for at handoff. "Where do I change the homepage headline?" The answer should be a place, not a story. If the answer is a story, the code is performing cleanliness and the editor is still hunting.

Name the fields the way the team talks. "Hero line" beats "text_01" because the person editing at 4 p.m. is not thinking in the order the component was built. A maintainable file uses the language of the page.

Sections are pieces, not a single long page

A marketing page is a sequence: an opening, proof, an explanation, a way to talk. In the code, those should be sections with their own files or their own content blocks. You should be able to remove one, reorder one, or rewrite one without unspooling the rest.

The failure mode is a single template where every campaign has been pasted underneath the last, with conditions for "if it is the spring page." The file becomes a diary of deadlines. The next person inherits the diary.

Modular does not mean a design system the size of a product company. A small site needs a handful of sections that match the brand: a hero, a project list, a simple split of text and image, a closing call. Hanabi's own marketing work is built this way, in React and TypeScript, with Tailwind for the styling. The stack is useful because the sections stay typed and the class names stay in the component. The founder-level result is that a new section looks related to the old ones without a one-off stylesheet named final-final.

When a section is used twice, it should be the same section. A second, slightly different copy is how spacing and type start to drift. Drift is a maintenance problem before it is a taste problem. Six months later the site looks like two teams worked on it, because two copies diverged.

Images are named, sized, and findable

Marketing pages live and die by images. Clean means each image has a source file you can replace, an alt string a human wrote, and dimensions that will not jump the layout when the file loads. The path should tell you what it is. A folder of hash names and a component that crops them by accident is how the next launch starts with the wrong photograph.

Keep the heavy decisions in one adapter. On this studio's site, public marketing images are addressed through a single helper rather than pasted bucket domains in every component. You do not need that exact setup. You do need one obvious way to point at an image, so a replaced file does not require a hunt through ten imports.

Alt text is part of the code review, not a later chore. If the pull request changes a picture and the description still talks about the old one, the change is incomplete. The next editor should not have to open the live page to learn what the file depicts.

Performance stays legible

web.dev's introduction to Web Vitals makes a point that belongs in this definition. Site owners should not have to be performance experts to understand the quality of experience they are delivering. Clean structure helps that. When the hero image is one image, the font loading is deliberate, and third-party scripts are few and named, a slow page has a short list of suspects.

The thresholds are still the ones web.dev publishes for Core Web Vitals. Largest contentful paint within 2.5 seconds, interaction to next paint at 200 milliseconds or less, cumulative layout shift at 0.1 or less. A maintainable site does not guarantee those numbers by being tidy. It makes a regression attributable. You can see which section started shipping a megabyte, because the section is a file.

Google's helpful-content guidance asks whether the page is produced well or looks sloppy and hastily assembled. Visitors feel that. So does the next developer. A file that hides the offer inside three nested conditions is the engineering version of a page that makes someone search again.

Prefer a static page where the content allows it. Motion, if you use it, should have a reduced-motion path so the craft includes the person who asked the system to be still. That is a feature with an address too, not a sprinkle of animation at the bottom of a global file.

What to ask for in the repository

You can review this without reading every line. Sit with the person who will own the site next and walk five checks:

• Change the homepage headline in one place and see it in a preview.
• Reorder two sections without copying a layout by hand.
• Replace one image and its alt text without breaking the spacing around it.
• Find the primary call to action as a component, not as three different buttons.
• Name the scripts the page loads, and say why each one is there.

If those checks pass, the code is clean in the sense that matters. If they fail, more abstraction will not save the project. The work is to put the words, the sections, and the images where a person can find them.

The same standard should be visible when the engagement ends. The repository, the accounts, and the content logins need to be yours. That ownership question is the subject of what you should own after a studio build.

Studios that treat clean code as part of the craft, rather than as a private habit, are set up for the kind of marketing sites and product front ends described in Hanabi's services.