Drift — the 47 blues
Each new screen, the model derives slightly different colours. bg-blue-500,
#3B82F6, blue-600, a custom variable — all in one codebase,
none of them agreeing. Components multiply the same way:
Button → CTAButton → PrimaryButton, near-identical,
because nothing searched for the existing one.
The fix is structural: a token file before the second screen, and prompts that name tokens semantically rather than by value.
Sameness — the slop default
A codebase can be perfectly token-disciplined and still look like every other AI-built app. That's a different failure: not drift, but the absence of a decision.
The fix is a choice: intentionality, not intensity. Bold maximalism and refined minimalism both work; what fails is defaulting. For a first build, minimalism done precisely beats maximalism done loosely — restraint hides fewer mistakes.
Spend the hours the AI just saved you on the 5% that's actually yours.
The brand, the voice, the one memorable thing. Banking the speed and shipping the mean is how "build faster" quietly becomes "build sameness."
three layers, not two
Tokens go primitives → semantic → component. Two layers is fragile under AI
generation: the model takes the easier path and hex codes escape. Three gives it a semantic
name to grab — color.action.primary, never indigo-600 — so the
system survives being generated against.
BOSS scaffolds this the moment your project grows real UI (/design-tokens-init),
not before. Style is the canonical case of Principle 3: nothing valuable gets locked
into code. The test is whether a prototype or a sibling project could reuse it
without copy-pasting.
the floors
- Five states on everything. Default, hover, active, disabled, focus — plus empty and loading wherever data lands. At least one is always missing by default, and it's usually empty or loading, which are the most user-facing failures there are.
- Accessibility is a floor, not a trade-off. Contrast measured rather than asserted, visible focus, real landmarks, and colour never the only signal.
- Performance counts as design. A page that jumps while a webfont loads is a design decision someone didn't make.
A design system you can actually look at
Most design systems are a document describing components, kept beside the code. That's the failure: a gallery authored next to the implementation starts drifting the moment either one moves, and nobody notices until a screen looks wrong.
/design-library generates the thing instead — a self-contained HTML gallery of
your foundations (colour, type, spacing) and every component in every variant and
all five states, rendered from the code and tokens. The code stays the
source of truth, so the library cannot disagree with the product. Re-run it any time; it's
idempotent.
--check makes it a gate.
Which closes the loop on the two failures above: tokens stop the 47 blues, the manifest stops pattern reinvention, and the gallery makes both visible instead of theoretical.
--check turns
drift into a gate.
Persuasion gives someone a reason and lets them decide. Manipulation exploits how they decide.
That line is the whole of BOSS's conversion ethic, and it's testable. The say-it-out-loud test: would you say that decline sentence to the person's face, in a shop? If it exposes a sneer, cut it. The urgency-honesty rule: a real deadline is a fact you can state — the manipulation is only ever in the falsity.
This site failed its own test first
The first draft of BOSS's visual identity was warm cream, a serif display face, a terracotta
accent, hairline rules and a decorative 01 / 02 / 03 rail. That is, precisely, a
named 2026 AI-default cluster — BOSS walked straight into the failure its own practice
exists to prevent.
The lesson is the transferable part, and it's the opposite of what you'd guess: you
can't escape a cluster by swapping the palette. You break it by deriving the choices from the
subject. The ground and accent stayed. The display face became the mono stack, because
BOSS is a terminal and its headlines should come from the same world as its proof. The
numbered rail became the ▸ the CLI actually prints, because the sections were
never a sequence.
It also exposed something worse than a bad page: the practice that warns about AI-default still named the 2025 tell — purple gradient, Inter, centred card — while reporting itself fresh. A practice naming last year's default is worse than no practice, because it certifies the current one as safe.
Design system — style never locked into code
learned from Brad Frost — Atomic Design Nathan Curtis — design tokens W3C Design Tokens Community Group
where this came from
Generalized from a dogfooded design system — design tokens as the single source of truth, central badge and pill style utilities, an enforcement hook that rejects raw framework colors, and a prototype registry — then stripped of everything product-specific so it would transfer. The AI-failure-mode catalog was written in the same pass.
AI-native interface patterns (2026)
learned from Shape of AI Microsoft HAX guidelines Google PAIR Nielsen Norman Group (2026) Apple HIG — generative AI CDT — Dark Patterns in AI Chatbots (2026) Vaccaro et al., CHI'26
where this came from
Distilled from an AI-UX scan across Shape of AI, Microsoft HAX, Google PAIR, IBM Carbon, LangChain HITL, NN/g 2026 and Apple's HIG for generative AI. The dark-pattern checklist and its humane alternatives come from CDT's Dark Patterns in AI Chatbots (2026, CC-BY); the classic web pattern families and their regulatory teeth (effect-not-intent, symmetry-in-choice) from the first humane sweep; the cohort and frontier patterns — accessibility, minors, agentic, algorithmic management — plus junk-fee teeth from the second. Later additions: generated code injects dark patterns (Vaccaro, CHI'26) and the dev-tool metering surface. The dark-pattern catalog has since moved to its own practice and data file so it can grow without growing what any one founder reads.