Hi, I’m Kei.
In an earlier post I mentioned I’d write about the custom theme design improvement process. This is that post. Here’s a look back at what I was thinking and what I changed to get from the post-migration state to where the site is now.
The Theme Right After Migration: “Good Enough to Function”
The custom theme I built during the WordPress migration was built with functionality first, appearance second.
Specifically:
- Default fonts, unchanged
- Card layout using a provisional grid implementation that broke easily
- No settled color palette — color codes scattered throughout the CSS
- Insufficient mobile review, with navigation partially breaking on smartphones
Rough around the edges as a live site, but I deliberately prioritized getting things working. The migration itself was already a substantial project, so I’d made peace with “clean up the design after it’s live.”
Where Improvement Started: Writing Down What Felt Off
The trigger for improvement was looking at the site on my phone and thinking “something’s not right.” I couldn’t immediately put it into words, but I brought it to Claude Code — “I want to figure out what’s bothering me” — and worked through a list of issues by having observations surfaced for me.
The rough summary of what came out:
- Readability: text too small, line spacing too tight
- Consistency: font sizes and spacing varying page to page
- Responsive: layout breaking at certain tablet widths
- Color: no unified palette, multiple competing accent colors
None of these were individually critical, but layered together they made the site feel scattered.
Establishing a Color Palette
The first thing I tackled was color. I decided to manage colors centrally with CSS variables.
I described the direction I wanted: “something composed, with a technical feel that suits a home server site, but still readable as a long-form site.” Claude Code generated some candidates, I compared them in HTML preview, and gradually narrowed down the combination of accent color and base color.
I landed on a dark navy as the base with an orange-ish accent. I went with a cool-toned base — common for tech sites — partly because of personal experience: it’s easier on the eyes for extended reading. It also creates good contrast with the white content area, which I think helps readability.
Once the palette was in CSS variables, changing a color anywhere meant updating one variable. Future adjustments became dramatically easier.
Typography Cleanup
Next: fonts and text sizes.
For the Japanese font I chose “Noto Sans JP” from Google Fonts. System fonts would have been fine, but the appearance varying by environment bothered me — a web font keeps it consistent.
Text sizes were organized around a root font-size, with headings, body, and captions set in rems. The inconsistency across pages had come from using px values inline in various places, so I consolidated everything through variables.
Line height went to 1.8. For Japanese text, that kind of generous spacing — closer to how vertical text reads — makes long-form content easier to follow.
Rebuilding the Card Layout
The top page card grid had been problematic since the migration. Fixed column counts in the CSS meant cards went extremely tall at tablet widths, and the layout broke on smaller phones.
Rewriting with auto-fill and minmax let the column count adapt automatically to screen width:
.card-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
gap: 1.5rem;
}That alone gave natural behavior: one column on phones, two on tablets, three on desktop. Simpler than writing multiple media query breakpoints, and easier to maintain.
What “Making Design Decisions” Actually Looks Like
What design improvement taught me: the choices take longer than the code.
There’s no single right answer for color or typography. Even with Claude Code generating options, the decision of which one to pick is mine. “This orange feels too bright.” “I want the saturation down a bit.” Iterating back and forth on exchanges like that is how the site gradually got to where it is now.
Having a local preview HTML file where I could check color and font combinations in the browser in real time turned out to be an efficiency win. An interactive loop — adjust, check in browser, adjust again — fits design work well.
What’s Still on the List
There are things I haven’t gotten to yet:
- Dark mode (CSS variables are ready, but the toggle UI isn’t implemented)
- Accessibility (contrast ratio checks aren’t complete in some areas)
- Animations (page transitions and card hover states could be more polished)
All of these have been sitting in the “someday” pile without rising in priority. The site functions adequately at minimum, so more important improvements keep getting scheduled ahead of them.
Wrapping Up
Improving the custom theme wasn’t a single big refactor — it was the accumulation of “notice something → fix it → check it.”
What worked well about working with Claude Code: when you describe a direction, it goes from language to code revision in one move. Design is hard to put into words, but if you can communicate the direction, it generates options — which beats sitting alone and wondering. I’ll keep making small improvements.
Feel free to leave a comment if anything comes to mind.
— Kei