ClearNight Native iOS App

THE PROBLEM

A weather app can't answer an astronomy question

"Partly cloudy" tells you nothing about whether the Milky Way core will be visible at 2am. Serious observers cross-reference a cloud forecast, a moon calendar, an astronomy seeing index, and a light-pollution map — then do mental math and drive an hour on a hunch. Casual stargazers don't even know those four factors exist; they just walk outside, see haze, and go back in.

The product bet: don't show people four datasets. Score the night for them. One number, one verdict, one best window — and a push notification when a saved dark-sky spot is about to have a great night. The app's positioning line came straight out of this bet: "ClearNight doesn't guess. It scores."

THE PROCESS

Design like a studio, ship like a team

The project ran in four deliberate phases. The unusual part: each phase produced a written artifact precise enough for the next phase to consume — which is what later made the AI collaboration work.

UX & design system

The gradient is the data

The core UX idea is that the app should feel like the night it's describing. Every screen's sky gradient, star density, and accent color are driven by the night's score — a dark, star-dense screen means a pristine night; a washed-out grey one means stay home. Users read the verdict before they read a single number.

That meant the verdict system couldn't be a styling detail — it's simultaneously the data model and the visual model, defined once and consumed by the score engine, every screen background, and the notification copy.

Plain language as a design principle

Astronomy is jargon-dense — Bortle classes, arcsecond seeing, transparency. Every factor in ClearNight gets a sentence a first-timer can act on: Bortle 5 isn't a number, it's "Suburban skies — bright Messier objects are visible, faint ones are tough." The factor sheets pair each stat with a where-this-falls scale, so the app teaches the domain while forecasting it.

Permission UX, deliberately sequenced

Notification permission is never requested at first launch — only at the moment a user turns on their first GO alert, when the benefit is obvious. Location permission is likewise tied to the "use my current location" action. Small sequencing decisions like these are invisible when done right and fatal to conversion when done wrong.

The engine

Four factors in. One honest number out.

The score is a weighted blend of the four things that actually decide a night, computed from live data per saved location: cloud cover from Open-Meteo, astronomical seeing from 7Timer!, moon illumination computed locally from ephemeris math, and a Bortle light-pollution estimate captured when the user saves a spot.

The weights encode a real observing opinion: cloud is nearly half the score because no other factor matters under an overcast sky. The whole model lives in scoreEngine.ts — one module, so the app and the alert backend can never disagree about what a good night is.

Beyond the score

The engine also finds the night's best window — the longest contiguous run of clear hours between dusk and dawn, tie-broken by lowest average cloud. Night bounds are computed in the location's timezone, not the phone's, so "tonight" means tonight at your dark-sky site even when you're checking from another state. Rise, set, and transit times for prime targets — the Milky Way core, planets, showers — come from astronomy-engine, computed on-device with no API at all.

The build

The handoff doc was the prompt

I wrote the developer handoff as if an outside team would build the app — token tables with exact hexes, screen-by-screen specs, freemium gating rules, a notification-backend architecture doc. Then the "outside team" turned out to be Claude Code, and that document became the standing prompt for the entire production build.

The method was disciplined and repetitive: one screen or one service per request, always anchored to the spec — "recreate the Home screen matching the verdict palette and thresholds in the README." Design rigor upstream is what made AI velocity downstream possible; a vague prototype would have produced a vague app.

System architecture

Source to subscriber

Everything involved in getting ClearNight from a design prototype to a working subscription on a physical iPhone.

Product strategy

Free tells you about tonight. Premium never lets you miss one.

The freemium line is drawn on a single principle: the free tier proves the score is real — one location, tonight's verdict — while everything about planning and never missing a night is Premium: the 7-night forecast, unlimited spots, prime-target timing, and GO alerts.

The 7-day trial grants full Premium, then drops to Free rather than hard-locking — lapsed users keep a working product and a daily reason to come back to the paywall. Alerts are the retention engine: the app re-engages users on exactly the nights the product is most valuable.

Going to market

The launch surface

Shipping meant more than the binary: a marketing site at clearnightapp.com, framed App Store screenshots that lead with the value proposition, store copy, privacy policy, and support pages — all in the app's own visual language.

By the numbers

One person. One system behind it all.

Numbers flatten a project, but they also make a point: none of this was outsourced. The same person who chose the mint accent chose the 45% cloud weighting, wrote the paywall copy, set the annual price, and debugged the push token registration. Five weeks covers the full arc — the prototype, the handoff documentation, eighteen production screens, the scoring engine, the Supabase backend, three App Store products, the marketing site, and the review submission.

The number I care most about is the last one: a single scoring module shared verbatim between the app and the alert backend. It's a small architectural decision with an outsized product consequence — the score a user sees on their home screen and the score that decides whether their phone buzzes at 6pm can never drift apart. Most forecast apps get this wrong quietly; ClearNight can't, by construction.

Takeaways

ClearNight started as a design exercise and ended as a business with an SKU sheet, a backend, and a review submission — and the through-line is that each discipline made the next one cheaper. The design system's precision made the AI build fast. The build's single-module architecture made the notification backend trustworthy. The freemium logic made the marketing site almost write itself, because the product's value proposition had already been argued through at the paywall level.

The honest lesson is about where the leverage actually lives now. The AI didn't shorten the thinking — the verdict palette, the scoring weights, the trial-drops-to-free decision all took as long as they ever would. What it shortened, dramatically, was the distance between deciding and shipping. For a designer, that changes the job description: the spec is no longer a request for someone else's roadmap. It's the roadmap.