Building a Personal Website in Swift

The roles missing from a real site#

Raptor’s typography system has a fixed set of roles:

• body
• title1 … title6
• codeBlock

A real site also has post metadata, navigation labels, tags, categories, buttons, and links. In Hugo, Hexo, or a hand-written template, I would give those elements class names and move on:

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

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

Raptor had no equivalent built-in roles for:

1
.postMeta
2
.navLabel

My first reaction was to add them.

Extending Theme#

I designed an API that looked like this:

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

The theme would configure each custom role:

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

Raptor would then generate:

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

and attach the class to the rendered HTML:

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

After digging through the framework, I modified the theme configuration, updated CSS generation, and patched the rendering logic. The implementation worked: custom roles went through the theme system, supported light and dark mode, generated CSS automatically, and appeared in the final HTML.

The code was functional, but the model still felt wrong.

First, it created two competing ways to describe text:

1
.font(.title1)        // built-in
2
.textRole(.postMeta)  // custom

Second, the two APIs did not carry the same meaning. In Raptor:

1
.font(.title1)

selects an HTML tag such as <h1> and applies its styling. My custom API:

1
.textRole(.navLabel)

only applied styling. HTML structure and visual style are separate concerns, but I had added another typography API without resolving that distinction.

Eventually I was writing:

1
.tag(.h1)
2
.textRole(.navLabel)

which was just a more elaborate way to express:

1
<h1 class="nav-label"></h1>

The type-safe API was no longer removing complexity. It was recreating HTML concepts with extra steps.

The abstraction was already there#

I checked other static site generators to see whether they modeled this problem at the framework level. Hugo, for example, simply allows:

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

and leaves the rest to CSS.

That comparison sent me back into Raptor’s design and source code. Theme is meant for global design tokens such as typography, colors, and spacing. A semantic style like “post metadata” does not need to become another global text role.

Raptor already has a separate abstraction for that: Style.

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

It can be applied directly to the content:

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

This serves the same purpose as:

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

but keeps the implementation reusable, composable, and type-safe.

Style also receives environment conditions, including the light or dark color scheme, active theme, contrast settings, and layout conditions. A semantic style can therefore adapt without becoming part of the theme’s role system:

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
}

The boundary I had missed was simple: Theme defines global tokens; Style packages reusable semantic styling. The framework already supported what I wanted—I had just started by changing its internals instead of using the abstraction intended for the job.