The Raptor Dilemma

Why Raptor felt good at first#

Raptor is more than a static site generator. It provides a Swift-first model for pages, layouts, themes, styles, and components. Instead of writing this:

1
<article class="post-card">
2
  <h2>Title</h2>
3
</article>

I could write:

1
VStack {
2
    Text(post.title)
3
}
4
.style(PostCardStyle())

The appeal is easy to understand: type safety, composability, one implementation language, and a developer experience that resembles SwiftUI. In theory, the same ideas that made SwiftUI productive on Apple platforms can make a website pleasant to build.

For simple pages, they do. These components are concise:

1
Text("Hello")
2
Button("Read more")

Landing pages, documentation sites, and basic blogs fit the model well. If most of the interface can be described as:

1
Text + Button + Grid + Card

Raptor is expressive and fast.

A custom theme exposes the boundary#

The trouble started with ordinary theme details rather than an exotic browser feature.

1
.meta {
2
  display: flex;
3
  justify-content: space-between;
4
}
5
.meta time {
6
  float: right;
7
}

1
HStack {
2
    categories
3
    Spacer().axis(.horizontal)
4
    time
5
}
6
.style(Property.width(.percent(100)))

1
.recent-info::after {
2
  content: '';
3
  width: 13%;
4
  height: 5px;
5
  background: var(--accent);
6
  position: relative;
7
  bottom: -6px;
8
}

1
RecentInfoAccentBar()

1
.card:hover .read-more {
2
  background-color: var(--bg-hover);
3
}

1
.read-more {
2
  margin-top: -21px;
3
}

1
.style(Property.marginTop(.px(-21)))

1
They think in Swift,
2
but debug in CSS.
3

4
They write components,
5
but fight layout at the DOM level.
6

7
They define styles,
8
but still rely on raw CSS properties.

The theme ended up with two mental models#

A typical card began as a useful Swift component:

1
PostListItem {
2
    PostMeta(...)
3
    PostTitle(...)
4
    PostExcerpt(...)
5
    PostReadMore(...)
6
}

Reusable styles kept the first layer tidy:

1
.style(PostCardStyle())

Then the visual adjustments accumulated:

1
.style(Property.marginTop(.px(12)))
2
.style(Property.paddingLeft(.px(8)))
3
.style(Property.fontSize(.px(14)))

The generated page still runs on HTML, CSS, and JavaScript, so browser behavior remains the source of truth. The working model became:

1
Structure → Swift
2
Styling → CSS concepts
3
Layout debugging → Browser DevTools

The daily experience was therefore:

1
Half SwiftUI
2
Half traditional Web

Raptor had moved the complexity, not removed it. I wrote components in Swift, inspected the resulting DOM, and fixed layout using knowledge of CSS.

Saga keeps the Web boundary visible#

Saga takes a different approach. A template can still use Swift for composition while leaving the generated HTML and its classes obvious:

1
article(class: "mx-auto max-w-3xl px-6 py-12") {
2
  h1(class: "text-4xl font-bold tracking-tight") {
3
    item.title
4
  }
5
  div(class: "prose") {
6
    raw(item.body)
7
  }
8
}

The division of responsibility is explicit:

1
Swift → structure + composition
2
HTML → structure
3
CSS → styling

There is less translation between the code I author and the page I debug. For a visually demanding site, I find this easier to reason about than a SwiftUI-style layer over the browser.

Where I would use Raptor#

Swift can express a Web UI; the question is how much distance from the rendering platform is useful.

For a generic interface:

1
Abstraction helps

For a highly customized interface:

1
Abstraction fights the platform

Raptor is strongest in the first case: structured pages made from familiar components, where its type safety and composition do real work. It becomes less comfortable in the second, precisely when selectors, pseudo-elements, and small layout adjustments matter most.

The broader stack still has two layers:

1
Rendering layer → HTML / CSS / JS
2
Authoring layer → Swift / React / Astro

React and Astro stay relatively close to the rendering layer. Raptor deliberately moves farther away, which gives it a distinctive SwiftUI-like experience but also creates the mismatch I hit while building the theme.

My practical boundary after this project is:

1
Swift for logic → great
2
Swift for UI abstraction → situational
3
HTML/CSS/JS → still the source of truth

I would still choose Raptor for a simple, structured Swift site. For a visual-heavy theme, I would rather use a Saga-style approach and keep the browser’s own UI model visible.