Building a Personal Website in Swift

Introduction#

I recently started building my personal website using Swift.

Not JavaScript. Not Hugo. Not a typical static site generator.

Instead, I chose a Swift-based SSG called Raptor. The idea was simple: if I already write Swift every day, why not use it for my website too?

At first, everything felt surprisingly smooth. Writing layouts in Swift felt expressive, type-safe, and honestly… kind of fun.

But then I ran into a problem I didn’t expect.

And that problem turned out to be much deeper than I thought.

What is Raptor?#

Before going further, a quick explanation.

Raptor is a static site generator written in Swift. Instead of writing HTML templates or JSX, you describe your site using Swift code:

1
VStack {
2
    Text("Hello, world!")
3
    Text("Welcome to my site")
4
}

It also has a built-in theme system, where you can define typography and colors:

1
.font(.title1)
2
.fontSize(36, for: .title1)

So far, so good.

The Problem: Real-World Themes Are Messy#

When you build a real website (not just a demo), you quickly realize something:

Not all text is just “title” or “body”.

You also have things like:

post metadata (dates, authors)
navigation labels
tags and categories
small UI text like buttons or links

In traditional static site generators (like Hugo or Hexo), this is trivial:

1
<span class="post-meta">April 20</span>
2
<a class="nav-label">Archive</a>

And then in CSS:

1
.post-meta {
2
  font-size: 12px;
3
  color: gray;
4
}
5
.nav-label {
6
  font-weight: bold;
7
}

You just invent class names and move on.

Why This Felt Hard in Swift#

In Raptor, typography is built around a fixed set of roles:

body
title1 … title6
codeBlock

But there’s no built-in way to express:

1
.postMeta
2
.navLabel

So I started thinking:

“Why can’t I define my own text roles?”

My First Idea: Extend the Theme System#

I tried adding a custom concept like this:

1
Text("April 20").textRole(.postMeta)

And in the theme:

1
.fontSize(12, for: .postMeta)
2
.fontWeight(.medium, for: .postMeta)

Then generate CSS like:

1
.text-role-post-meta {
2
  font-size: 12px;
3
  font-weight: 500;
4
}

And attach it to HTML:

1
<p class="text-role-post-meta">April 20</p>

It Worked… Technically#

After quite a bit of digging into the framework:

modifying theme configuration
updating CSS generation
patching rendering logic

I actually got it working.

Custom text roles could:

go through the theme system
support light/dark mode
generate CSS automatically
appear in HTML

So… problem solved?

Not really.

Something Felt Off#

Even though it worked, the system started to feel… weird.

Here’s why.

Two Competing Systems

Now I had:
```
1
.font(.title1)        // built-in
2
.textRole(.postMeta)  // custom
```
Two ways to describe text.

That’s already a smell.
Tag vs Style Confusion

In Raptor:
```
1
.font(.title1)
```
does two things:
- decides the HTML tag (<h1>)
- applies styling
But in my system:
```
1
.textRole(.navLabel)
```
only affects styling.

That made me realize:

HTML tag and text style are actually two different things.

But the framework treats them as one.
It Started to Feel Like Writing HTML Anyway

At some point I found myself writing things like:
```
1
.tag(.h1)
2
.textRole(.navLabel)
```
Which is basically:
```
1
<h1 class="nav-label"></h1>
```
At that moment I had a thought:

“Wait… am I just reinventing HTML with extra steps?”

Looking at Other Tools#

I checked how other SSGs handle this.

Hugo, for example (written in Go), does not solve this problem at the framework level.

It simply lets you write:

1
<p class="post-meta"></p>

and handle everything in CSS.

No type system. No abstraction. Just freedom.

So… What’s the Real Problem?#

The problem is not “we need a unified role system”.

The real problem is:

I was trying to solve this in the wrong layer.

After digging deeper into Raptor’s design (and even its source code), I realized something important:

Theme is designed for global design tokens (typography, colors, spacing)
But semantic styles are not meant to live in Theme

Instead, Raptor already provides a dedicated abstraction for this:

Style

And I had completely overlooked it.

The Actual Solution (That I Missed)#

It turns out Raptor already has the right abstraction for this problem.

Not textRole.

Not extending Theme.

But this:

1
struct PostMetaStyle: Style {
2
    func style(content: Content, environment: EnvironmentConditions) -> Content {
3
        content
4
            .font(.caption)
5
            .foregroundStyle(.secondary)
6
    }
7
}

And then:

1
Text("April 20")
2
    .style(PostMetaStyle())

That’s it.

This is effectively:

1
<p class="post-meta">April 20</p>

But expressed in a reusable, composable, and type-safe way.

Even better, Style can access environment conditions:

light / dark mode
active theme
contrast settings
layout conditions

Which means you can write:

1
struct PostMetaStyle: Style {
2
    func style(content: Content, environment: EnvironmentConditions) -> Content {
3
        if environment.colorScheme == .dark {
4
            content.foregroundStyle(.gray)
5
        } else {
6
            content.foregroundStyle(.secondary)
7
        }
8
    }
9
}

So instead of:

trying to extend Theme
or inventing a new role system

The intended model is:

Theme → defines global tokens
Style → defines reusable semantic styles

In other words, Raptor already supports exactly what I wanted — just not in the place I was looking.

What I Learned#

This little experiment taught me a few things:

“Elegant” abstractions can be misleading

A unified system looks great on paper, but may not fit the existing architecture.
Not everything needs to be in the type system

Traditional SSGs work fine by leaving some flexibility to CSS.

Trying to encode everything in Swift may not always be worth it.
The real challenge is understanding the abstraction boundary

The key isn’t:

“How do I define more roles?”

But:

“Which layer should own semantic styles?”

In Raptor’s case, the answer is:
- Theme → tokens
- Style → semantics

Closing Thoughts#

I started this thinking:

“I just need a way to define custom text styles.”

And ended up questioning:

The most surprising part?

The framework already had the answer.

I just didn’t understand it yet.

how theme systems should be designed
how much abstraction is too much
and where Swift should (and shouldn’t) replace CSS

I’m still building my site in Swift — and I still like it.

But now I have a much clearer idea of where the real complexity lies.