DEV Community: Howard Shaw

Why Single-Model "Cartoonify" Prompts Fail in Production (And How I Fixed It with a 2-Stage Pipeline)

Howard Shaw — Tue, 20 Oct 2026 04:06:32 +0000

If you have ever built an image-to-image (I2I) consumer feature, you already know the dirty secret of prompt engineering: what works in a Cherry-Picked Twitter thread rarely survives contact with real user uploads.

A few weeks ago, I started building an AI Cartoonify effect. The goal seemed straightforward—let users upload a selfie or pet photo and transform it into a stylized 3D/2D cartoon while keeping the person recognizable.

At first, I tried throwing the reference image and a carefully crafted style prompt into a single generation pass. It was a disaster.

The "Identity vs. Stylization" Trap

Take a typical torture-test upload: a guy with a thick beard, wearing thin wire-rimmed glasses, standing under harsh side-lighting, holding up a peace sign.

When I ran this through a standard single-model I2I workflow, I kept hitting a brick wall:

Failure Mode A (High Style Strength): The output looked like a gorgeous Pixar frame, except the wire-rimmed glasses melted into his eyebrows, his peace sign grew a sixth finger, and he looked like a generic stock character instead of the person in the photo.
Failure Mode B (High Reference Conditioning): His face and glasses stayed intact, but the model refused to actually cartoonify the geometry. It just slapped a plasticky, airbrushed skin shader over a photorealistic face—straight into the depths of the uncanny valley.

The root cause? A single pass forces the model to figure out what is in the image and how to deform it artistically at the exact same time.

To ship this to production, I had to decouple semantic understanding from spatial rendering. Here is how I rebuilt the pipeline by pairing ChatGPT Image 2.5 with Nano Banana 2.1.

The Solution: A Two-Stage "Lock & Render" Pipeline

Instead of asking a single model to guess which pixels matter, I split the workload between two engines based on what they actually do best:

Stage 1: The Semantic Lock (ChatGPT Image 2.5) — Used strictly as a visual parser and dynamic prompt compiler. Its job is to spot fragile details (like those wire-rimmed glasses or specific hand gestures) and convert them into hard text tokens.
Stage 2: The Spatial Renderer (Nano Banana 2.1) — Used as the fast conditioning engine. It takes the original image as a structural blueprint alongside the dynamic tokens generated in Stage 1 to execute the actual style transfer.

How the Data Flows in Code

Rather than relying on static prompt templates, the backend builds a custom conditioning payload for every single upload. Here is a simplified look at the TypeScript structure driving the orchestration:

interface CartoonifyJob {
  sourceImageUrl: string;
  targetAesthetic: '3d-animation' | 'cel-shaded' | 'flat-illustration';
}

interface ConditioningPayload {
  spatialReference: {
    imageUrl: string;
    edgeFidelity: 'strict' | 'balanced' | 'loose';
    compositionLock: number; // 0.0 to 1.0
  };
  semanticTokens: {
    identityLocks: string[];   // Extracted via ChatGPT Image 2.5
    lightingCues: string[];    // Preserves mood without keeping raw photo noise
    styleModifiers: string[];  // Drives the Nano Banana 2.1 shader
    guardrails: string[];      // Anti-uncanny-valley negative tokens
  };
}

async function buildCartoonPipeline(job: CartoonifyJob): Promise<ConditioningPayload> {
  // Step 1: Extract fragile micro-features using ChatGPT Image 2.5
  const analysis = await extractVisualAnchors(job.sourceImageUrl, {
    model: 'chatgpt-image-2.5',
    focusAreas: ['eyewear', 'facial_hair', 'hand_pose', 'garment_necklines']
  });

  // Step 2: Assemble the hybrid payload for Nano Banana 2.1
  return {
    spatialReference: {
      imageUrl: job.sourceImageUrl,
      edgeFidelity: 'balanced',
      compositionLock: 0.70 // Enough room to exaggerate eyes/proportions
    },
    semanticTokens: {
      identityLocks: analysis.detectedFeatures, 
      // e.g., ["thin gold wire-rimmed glasses", "trimmed full beard", "two-finger peace sign"]
      lightingCues: [analysis.primaryLightingDirection, "soft rim light"],
      styleModifiers: [
        "stylized 3D character render",
        "expressive stylized proportions",
        "clean subsurface scattering"
      ],
      guardrails: [
        "photorealistic pores",
        "hyper-detailed skin wrinkles",
        "melted eyeglass frames",
        "asymmetrical pupils"
      ]
    }
  };
}

3 Lessons Learned While Tuning the Models

Moving to a dual-model setup solved the macro architecture, but getting consistent outputs across thousands of edge cases took some serious trial and error.

1. Let the Reference Image Handle Macro, Let Keywords Handle Micro

Nano Banana 2.1 is fantastic at keeping macro composition intact—head tilt, shoulder angle, and background silhouettes stay rock solid when using a reference image. However, when you relax the reference lock enough to allow cartoon exaggeration (like slightly larger eyes or smoother jawlines), micro-details vanish. By having ChatGPT Image 2.5 explicitly inject tokens like "thin gold wire-rimmed glasses" into the prompt stream, Nano Banana 2.1 is forced to redraw those micro-details cleanly in the new cartoon style rather than blurring them away.

2. Strip Out Real-World Lighting Noise

User photos usually have terrible lighting—fluorescent office bulbs, harsh bathroom shadows, or blown-out window backlighting. If you rely purely on image conditioning, the cartoon output inherits those muddy color casts. By extracting only the directional intent of the lighting (e.g., "warm side-lighting") via keywords and letting Nano Banana 2.1 re-render the actual color palette from scratch, the output looks like it came out of an animation studio rather than a dark bedroom.

3. Kill Skin Texture Early

The #1 reason AI cartoons look creepy is leftover high-frequency skin texture. When a model puts stylized cartoon eyes on a face that still has realistic pores and nasolabial folds, the human brain immediately rejects it. Hard-coding anti-realism guardrails (photorealistic pores, raw skin texture) into the Nano Banana 2.1 conditioning step was the single biggest quality unlock.

Test It Out in the Wild

I have shipped this exact two-stage pipeline (ChatGPT Image 2.5 + Nano Banana 2.1) into production.

If you want to see how it handles tricky portraits, pets, or weird lighting—or if you just want to try breaking the semantic lock with your own photos—you can play with the live implementation here:

👉 Try the Live Tool: AI Cartoonify on VioEvo

Wrapping Up

As image models get faster and more specialized, chaining them together is becoming much more practical than waiting for one "god model" to do everything perfectly in a single shot. Using a heavy semantic model to write dynamic conditioning instructions for a fast spatial renderer has completely changed how I approach I2I features.

How are you all handling identity retention vs. style strength in your own generative pipelines? Drop a comment below if you've found other workarounds!

I Integrated 20+ AI Models. The Hard Part Wasn't the AI.

Howard Shaw — Sun, 04 Oct 2026 07:33:49 +0000

When I integrated my first AI model, the whole thing felt almost ridiculously simple.

There was an API, a prompt, a request, and eventually a result. I wrapped the API call in my application, handled the response, stored the output, and moved on to the next feature. It was one of those tasks where you could spend more time reading the documentation than actually writing the code.

That impression did not last very long.

Over the following months, I ended up integrating more than 20 image and video models into a single product. At first, I thought this would mostly be a matter of writing a few provider adapters and keeping a common interface. In reality, the adapters were probably the easy part. The difficult work was figuring out what "the same feature" even meant when every model had slightly different assumptions, capabilities, input requirements, behavior, pricing, and failure modes.

This was one of those projects where the deeper I got into it, the less I believed the simple version of the problem.

My original plan was much cleaner

I started with a fairly conventional idea.

The application would have a common generation interface, and each provider would sit behind an adapter. Something roughly like this:

type GenerateInput = {
  prompt?: string
  imageUrl?: string
  videoUrl?: string
  duration?: number
  aspectRatio?: string
}

type GenerateResult = {
  jobId: string
}

interface ModelAdapter {
  generate(input: GenerateInput): Promise<GenerateResult>
  getStatus(jobId: string): Promise<JobStatus>
}

The idea was to keep the rest of the application ignorant of provider-specific details. If I wanted to add another model later, I would just implement another adapter.

This worked pretty well with the first couple of models. By the third one, I started adding exceptions. Then more exceptions appeared.

One provider wanted a publicly accessible image URL. Another worked better with uploaded assets. Another had a separate asset creation step before a generation request could even be made. Some models supported reference images, but the meaning of a reference image was not necessarily the same from one model to another. One provider offered a webhook while another expected the application to poll for status. Some exposed durations as arbitrary values, while others only allowed a short list of predefined options.

None of these differences were particularly difficult on their own. The problem was that they accumulated.

Eventually, the common interface started filling up with optional fields and special cases. At that point, I had to admit that I had built an abstraction that was trying too hard to make different things look identical.

A universal API sounds better than it actually is

This is probably the part of the project where I learned the most.

When you're designing an abstraction, there is a natural temptation to define the ideal interface first and then force every implementation to fit it. That can work very well when the implementations are variations of the same underlying system. AI models are often not.

Take something that sounds simple, like "image to video."

You might assume that the application sends an image and a prompt, and the model creates a video. Technically, that's often true. In practice, the differences are substantial. Some models treat the image primarily as the starting frame. Others use it more as visual guidance. Some preserve the subject and composition extremely well but are less reliable when the requested motion becomes complicated. Others are much better at camera movement. Some handle faces and people reasonably well, while another may behave very differently with the exact same source image.

From the outside, all of these can be presented as "image to video."

From an engineering and product perspective, they are not the same capability.

That distinction matters once users start selecting models based on what they are actually trying to create. If the application hides all of those differences behind one generic form, you can end up with a UI that looks beautifully consistent but gives users very little information about what will actually happen.

So I gradually stopped trying to make every model behave identically.

The goal became much more modest: provide a common foundation for the things that really are common, while allowing each provider to expose the capabilities that make it different.

That turned out to be a much healthier abstraction.

The model itself is only one part of the job

This was the other thing I seriously underestimated.

When I first started working with image and video generation, I naturally focused on the model call. That's the interesting part, after all. You send the input, something impressive comes back, and that's the part people usually see in demos.

In a real product, the model call is only a small section of the flow.

A user uploads an image. The application has to validate the file, store it somewhere, and make sure the provider can access it. The request has to be converted into the format that particular provider expects. A generation job needs to be created and associated with the user. The application needs to know whether the job is queued, processing, completed, or failed. If the provider reports an error, the application needs to decide whether that error is recoverable. When the generation finishes, the output needs to be stored and made available to the user.

And then there are all the things that don't happen on the happy path.

The user closes the browser while the generation is still running. A provider takes much longer than usual to respond. The request succeeds, but the output never becomes available. A retry creates a second generation when you didn't intend to create one. Two jobs finish at different times and arrive out of order.

None of this is particularly glamorous. It also has almost nothing to do with the intelligence of the model.

But these are the things that determine whether a user feels that the product works.

Eventually I started treating generation as a state machine

I spent quite a bit of time trying to make the generation lifecycle elegant. In the end, the simplest mental model turned out to be the most useful.

A generation is a job with a state.

queued
  ↓
processing
  ↓
completed

Or:

queued
  ↓
processing
  ↓
failed

The internal details vary by provider, but the application usually doesn't need to know every provider-specific status. The adapter can deal with polling, webhooks, provider response formats, retries, and all the other unpleasant details. The rest of the application just needs a reliable representation of the job.

For example:

type JobStatus =
  | "queued"
  | "processing"
  | "completed"
  | "failed"

That sounds almost too basic, but it made a big difference.

Once I treated the generation itself as a first-class job rather than just an API request, several other design decisions became easier. It became much clearer where retries belonged, what the frontend should display, and how to handle a job that finishes after the user has left the page.

The nice thing about this approach is that it isn't really an "AI architecture." It's just good asynchronous application design. The AI part happens to be what creates the jobs.

Costs turned out to be part of the architecture

There is another complication you don't notice when testing models one at a time.

Different models don't just produce different results. They can have very different costs and generation times.

When you offer several models in one product, the user isn't really choosing only between Model A and Model B. They are also choosing between a faster and slower generation, a cheaper and more expensive generation, and sometimes a more predictable and less predictable one.

That has consequences for product design.

For example, the model with the best benchmark or the most impressive demo is not necessarily the model I want as the default for every task. If it costs several times as much and takes substantially longer, asking every user to start there may not actually produce a better experience.

This is one reason why I now think about model selection as a product problem, not just an engineering problem.

The cheapest model is not always right. The most expensive model is not always right either. What matters is whether the model is a good fit for the task the user is trying to accomplish.

That sounds obvious when written down. It was much less obvious when I was in the middle of integrating them.

Most of the bugs live in the edge cases

The happy path is still easy.

You upload something, send a request, wait, and get a result.

The real application starts when that sequence breaks.

I have had plenty of cases where a model worked perfectly with the test inputs I used during integration, and then behaved differently once I started trying a wider variety of real-world inputs. Resolution, aspect ratio, image composition, faces, source quality, motion requirements, and other details can all change the outcome.

The tricky part is that a failure isn't always an explicit failure.

Sometimes the API returns a normal success response and the result is simply not very good.

That makes AI integration different from many traditional API integrations. With a payment API, you usually know whether the operation succeeded. With a generation model, "success" can mean that a video was technically produced even though it doesn't satisfy what the user actually asked for.

So there are really two types of reliability to think about.

There is infrastructure reliability, where the job completes and the system correctly handles the result. Then there is model reliability, where the output is actually useful for the requested task.

You need both.

Adding the 20th model was easier than adding the second

This was one of the more surprising things I learned.

The first model is difficult because everything is new. The second is often harder than expected because it exposes the differences you didn't account for. By the time you've integrated several providers and rewritten the abstraction a couple of times, you start to understand where the real boundaries should be.

Once that foundation is reasonably stable, adding another model is often much more mechanical.

That became a useful test for me. If integrating one more model requires changes all over the application, something is probably wrong with the architecture. The same is true if the adapter has become so complicated that nobody really understands what it is doing.

A good abstraction does not eliminate differences between systems. It gives those differences a sensible place to live.

That may be one of the most useful lessons I took from this entire project.

I stopped chasing feature parity

At some point, I realized I was asking the wrong question.

I had been thinking, "How can I make every model support the same set of options?"

The better question was, "What are the capabilities that actually make sense to expose across these models?"

Those are not the same thing.

Some models have capabilities that others simply don't have. Trying to hide that fact usually makes the product more confusing, not less.

So instead of forcing everything into one giant shared set of controls, I started thinking in terms of common capabilities and model-specific capabilities. The common parts should feel consistent. The differences should be visible when they matter.

That also changed how I think about model selection.

I don't care as much about saying that a product supports 20 or 30 models. The number sounds good in a headline, but it doesn't tell the user very much.

What is much more useful is knowing why you might choose one model over another.

One may be better for preserving a character. Another may be better for motion. Another may be faster. Another may be more affordable. Another may support a type of input that the others don't.

The differences are the useful information.

Documentation is only the beginning

I've also become much less willing to consider a model "integrated" just because the API call works according to the documentation.

Documentation tells you how a provider expects the API to behave. It does not always tell you what it feels like to use that API as part of a product.

You discover the rest through testing.

A particular aspect ratio may produce unexpectedly poor results. A reference image may work very well in one scenario and poorly in another. A capability may exist on paper but have practical limitations that aren't obvious until you put it into a real workflow.

So my integration process has changed.

I still read the documentation first. But I don't consider the job finished when the request returns a successful response. I want to see the model behave with the kinds of inputs and workflows that the actual product supports.

That takes more time up front, but it saves a lot of confusion later.

This changed how I look at new models

When another impressive model gets announced now, my first reaction is no longer just, "How good is it?"

I'm more interested in what it does differently.

Does it solve a problem that the existing models don't solve well? Is it noticeably better for a particular type of input? Is it fast enough to be practical? Is the API reliable enough to build around? Is the output quality consistent enough that users won't feel like they are rolling the dice?

Those questions are less exciting than benchmark screenshots, but they are much more useful when you're actually running a product.

At some point, adding another model just because it exists stops being meaningful.

Twenty models that behave roughly the same way are not necessarily better than five models with clearly different strengths.

That was not how I thought about multi-model products when I started.

I'm still figuring it out

I don't want to turn this into one of those "here are the lessons I learned and now everything makes sense" posts.

It doesn't.

I'm still integrating models. I'm still finding strange edge cases. I'm still changing parts of the architecture that seemed perfectly reasonable a few months earlier. That's probably not going to stop anytime soon, because the models themselves keep changing.

But after working through enough integrations, I do have a much clearer idea of where the real engineering work is.

It isn't the API call.

The interesting part is everything around it: normalizing inputs without pretending providers are identical, managing asynchronous jobs, handling failures, dealing with cost and latency, understanding what each model is actually good at, and turning all of that into something a normal user can interact with without needing to know any of it.

That is the part I didn't really understand when I integrated my first model.

And that's probably the biggest difference between adding an AI API to a web application and actually building a product around AI.

A small side project that turned into a much bigger lesson

The project that pushed me into all of this is VioEvo AI, an independent AI image and video creation platform where I've been experimenting with multiple generation models in the same product.

I originally thought the interesting part would be the models themselves.

After 20+ integrations, I'm much more interested in the engineering problems that appear when you try to make all of those very different systems feel like one product.

I Added Open Graph Preview Images to DocBeacon Share Links

Howard Shaw — Tue, 07 Apr 2026 09:29:55 +0000

Recently, I added Open Graph preview images to DocBeacon share links.

The problem was simple: when a DocBeacon link was shared in Slack or an email client, it often looked like a plain URL. For proposals, pitch decks, contracts, and other important documents, that is not a great first impression.

So I used OG images to make shared links more informative before the document is even opened.

Now, when a DocBeacon share link is posted in supported environments, the preview can include basic document context instead of showing only the raw link. That makes the link easier to recognize and helps it feel more legitimate at a glance.

While building this, one thing became clearer to me: a lot of document-sharing friction happens before the click.

A link appears in an inbox or a Slack thread. It looks unfamiliar. It provides little context. That alone can create hesitation.

This update is meant to reduce that.

It also works nicely with Shared Document Branding. When branding is enabled, the preview image can reflect the user's own branding and logo, which makes the experience feel more polished and consistent from the first touchpoint.

From an implementation standpoint, this is a fairly small feature.

From a product and trust standpoint, it feels much bigger.

Sometimes people do not judge the document first. They judge the preview first.

I would be curious to hear how other builders think about this. Have small details like OG metadata, preview images, or branding had a noticeable impact on trust or click-through in your product?

Reducing a Homepage Demo Video from 11.6 MB to Under 1 MB

Howard Shaw — Mon, 30 Mar 2026 07:27:07 +0000

Yesterda I worked on a small homepage improvement that turned out to be more technical than expected.

I wanted to add an autoplay product video to the "how it works" section of my SaaS homepage. The goal was simple: make the product flow easier to understand without adding too much friction or weight to the page.

The problem was file size.

My screen recording tool had already compressed the video, but the result was still too large for the web. One clip was only about 13 seconds long at 1280x720, H.264, and still came out to 11.6 MB. That felt far too heavy for a short homepage demo.

At first I thought the issue was just resolution, but it turned out the bigger problem was delivery format. Even after the recording software compressed the file, it was still not really optimized for web use.

So instead of relying on the recording tool's export alone, I treated that file as an intermediate version and ran it through ffmpeg.

This is the command that gave me a very good result:

ffmpeg -i "upload and configure.mp4" -vf "scale=-2:720" -r 24 -c:v libx264 -crf 27 -preset medium -pix_fmt yuv420p -an -movflags +faststart "output-720p1.mp4"

A few settings mattered most here:

-r 24 reduced frame rate to something more reasonable for a UI demo
-crf 27 gave me a good balance between size and clarity
-an removed audio I did not need
-movflags +faststart made the file better suited for web playback

The result was much better than I expected: the final file dropped to around 800 KB, while still looking good enough in the actual page section.

One useful takeaway from this: even if your screen recording software already outputs a compressed video, that does not mean it is truly web-optimized. For homepage demos, especially UI-heavy ones, a separate ffmpeg pass can make a huge difference.

My current workflow is simple:

export from the recording tool
compress with ffmpeg for web delivery
adjust resolution depending on the role of the video

For one larger file, I also went down to 540p, and that was fine too.

Small change, but definitely worth it.

Also launching on Product Hunt today:
https://www.producthunt.com/products/docbeacon
If you check it out, would love to hear what you think.

How I Built White-Label Document Sharing for Client-Facing Docs

Howard Shaw — Thu, 26 Mar 2026 12:39:11 +0000

When people send proposals, pitch decks, NDAs, and other client-facing documents, they usually want the recipient focused on their brand, not the software powering the experience.

That was the motivation behind a feature I recently shipped in DocBeacon: white-label document sharing for Pro users.

The idea sounds simple:

Let users attach a custom brand name, logo, and website URL to shared documents.

But once I got into implementation, it turned into an interesting mix of product design, access control, storage, validation, and fallback behavior.

This post is a short breakdown of how I approached it.

The problem

Before this feature, a shared document was still visually branded as DocBeacon throughout the viewing flow.

That was fine for some use cases, but not ideal for teams sending:

consulting proposals
investor decks
sales documents
sensitive client materials

In those workflows, brand consistency matters. If someone is sharing a high-value proposal, they usually want the experience to reinforce their credibility, not mine.

So the requirement became:

Let eligible users show their own branding across the document viewing experience, while keeping the system safe and predictable.

What the feature needed to support

At a high level, I wanted users to be able to configure:

a display name
a logo
a website URL
an on/off toggle for branding

And once enabled, that branding should appear in places like:

the document viewer header
attribution text
shared document metadata
other client-facing viewer touchpoints

I also wanted a clean fallback path. If branding data was incomplete, invalid, or the user’s plan didn’t allow the feature, the system should quietly fall back to the default DocBeacon brand.

The core design decision: resolve branding once

One of the first decisions I made was to avoid scattering branding logic across multiple rendering layers.

Instead of asking every page or component to figure out branding on its own, I used a single resolution step:

Check whether the user is allowed to use the feature
Check whether branding is enabled
Check whether enough valid branding data exists
Return either:
the user’s brand config, or
the default platform brand

In pseudocode:

**function resolveBranding(user):
    canBrand = planAllowsBranding(user.plan)
    hasIdentity = user.displayName OR user.logoPath
    enabled = user.brandingEnabled AND canBrand AND hasIdentity

    if enabled:
        return {
            name: user.displayName,
            logoUrl: buildAssetUrl(user.logoPath),
            websiteUrl: normalizeUrl(user.websiteUrl)
        }

    return defaultBrand**

This helped keep the rest of the system simple. Viewer pages didn’t need to know all the rules. They just consumed a resolved branding object.

Access control

This feature is only available on Pro+ plans, so access control had to be built into the feature itself, not just the UI.

That means even if someone somehow submits branding settings through an API call or stale client state, the backend still needs to enforce eligibility.

The check is conceptually simple:

canUseBranding(user):
    return user.plan in ["pro", "business", "enterprise"]

I treated this as a server-side rule first, and a UI rule second.

That’s important because frontend gating alone is never enough for plan-restricted features.

Asset storage for logos

For logo uploads, I wanted a storage layer that was simple, cheap, and fast to serve publicly.

I used Cloudflare R2 for uploaded branding assets.

The flow looks roughly like this:

User uploads a PNG or JPG
Backend validates file type and size
File is stored under a user-scoped path
The app stores only the storage path in the user record
A helper builds the public asset URL when needed

In pseudocode:

uploadLogo(file, user):
    assert file.type in ["image/png", "image/jpeg"]
    assert file.size <= MAX_LOGO_SIZE

    path = "branding/" + user.id + "/" + generateFileName(file)
    storage.put(path, file)

    saveUserBranding(user.id, { logoPath: path })

And later:

buildAssetUrl(path):
    return CDN_BASE_URL + "/" + path

I preferred storing the path rather than a fully expanded URL in the database, because it keeps storage concerns separate from delivery concerns.

URL validation was the trickiest part

The hardest part of this feature was not rendering a logo.

It was letting users attach a website URL safely.

On the surface, “enter your website” sounds trivial. In practice, it needs guardrails.

I did not want to allow:

localhost
private network IPs
credential-based URLs like user:pass@example.com
unsafe schemes like javascript: or file:

So I treated URL handling as a normalization + validation pipeline.

The job of that pipeline is:

parse the input
normalize format
require http or https
reject unsafe hosts
reject credentials
return either a safe URL or null

In pseudocode:

normalizeUrl(input):
    if input is empty:
        return null

    parsed = parseUrl(input)

    if parsed.scheme not in ["http", "https"]:
        return null

    if parsed.hasCredentials:
        return null

    if isLocalhost(parsed.host) or isPrivateIp(parsed.host):
        return null

    return parsed.normalizedHref

This kind of defensive validation matters because branding fields are user-controlled input, and user-controlled input always deserves scrutiny.

Fallback behavior matters more than people think

A lot of polish in a feature like this comes from handling invalid states well.

For example:

branding is toggled on, but no logo is uploaded yet
the user entered an invalid URL
the user downgraded from Pro to Free
an asset was deleted or unavailable
branding data is partially filled out

In all of those cases, I wanted the document experience to remain stable.

So instead of letting the UI break or showing half-configured branding, I default to the platform brand whenever the custom brand can’t be resolved safely.

That gives the system a predictable contract:

Either show a fully valid custom brand, or show the default brand.

No broken middle state.

Why I like this implementation

What I like about this feature is that it makes the product less visible in the right places.

For this use case, that’s the goal.

The product should support the sender’s identity, not compete with it.

From an engineering point of view, I also like that the system is built around a few clear principles:

central branding resolution
server-side plan enforcement
explicit URL normalization
safe asset handling
reliable fallback behavior

The final result feels simple to the user, which usually means the internal rules are doing their job.

What I’d improve next

A few things I’d likely add next:

custom domains for shared links
better branding previews in settings
image processing for uploaded logos
audit logging for branding changes
more granular per-document branding controls

That would take it from “account-level branding” to a more flexible identity layer.

Final thought

This started as a branding feature, but it ended up being a good reminder that “simple UX” often sits on top of a lot of backend discipline.

If you’re building anything user-configurable and client-facing, the hard part usually isn’t just rendering the settings.

It’s defining the rules for what’s allowed, what’s safe, and what happens when the input is incomplete.

If you’re curious, the product is DocBeacon: https://docbeacon.io

Stop over-engineering your Waitlist. Here is a 5-minute "No-DB" solution.

Howard Shaw — Sat, 07 Mar 2026 09:26:11 +0000

As developers, we have a bad habit of building a full-blown CRUD app just to collect early-access emails.

I’m currently building my new SaaS, and I wanted a waitlist that:

Costs zero dollars.

Gives me 100% control over the UI (no "Powered by" watermarks).

Requires no database maintenance.

Here is the "stupidly simple" stack I used: Vanilla JS + Google Apps Script + Google Sheets.

The "Backend" (Google Apps Script) Create a Google Sheet, go to Extensions > Apps Script, and paste this. It acts as a serverless function that appends data to your sheet.

function doPost(e) {
  try {
    const data = JSON.parse(e.postData.contents);
    const ss = SpreadsheetApp.openById("YOUR_SHEET_ID_HERE");
    const sheet = ss.getSheets()[0];

    // Custom fields for my SaaS waitlist
    sheet.appendRow([
      new Date(), 
      data.email, 
      data.name, 
      data.company, 
      data.pressure, // My specific niche field
      data.city, 
      data.country
    ]);

    return ContentService.createTextOutput(JSON.stringify({ result: "success" }))
      .setMimeType(ContentService.MimeType.JSON);
  } catch (err) {
    return ContentService.createTextOutput(JSON.stringify({ result: "error", error: err.toString() }))
      .setMimeType(ContentService.MimeType.JSON);
  }
}

The Frontend (Native Fetch) No heavy libraries. Just a clean async function to talk to your new API.

const submitWaitlist = async (formData) => {
  const SCRIPT_URL = 'https://script.google.com/macros/s/XXXXX/exec';

  try {
    // We use 'no-cors' because GAS redirects can be tricky with standard CORS
    await fetch(SCRIPT_URL, {
      method: 'POST',
      mode: 'no-cors', 
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(formData)
    });
    console.log('Early access secured!');
  } catch (error) {
    console.error('Submission failed', error);
  }
};

Why do it this way?
Zero Technical Debt: When the project scales, I can migrate to a real DB in 10 minutes.

Privacy: My data isn't sitting in a third-party startup's database. It's in my own Google Drive.

Speed: I spent 5 minutes on the backend and 2 hours perfecting the CSS (priorities, right?).

If you’re in the validation stage, don't let the "perfect stack" slow you down. Just get the emails and get back to building the actual product.

Rate Limiting Access Codes: The Delicate Balance Between Security and UX

Howard Shaw — Tue, 20 Jan 2026 10:24:54 +0000

Rate Limiting Access Codes: The Delicate Balance Between Security and UX

When building DocBeacon, we faced a common but tricky engineering challenge: how to protect resources secured by short access codes without frustrating legitimate users.

The Strategic Choice: When to Increment?

The core of rate limiting lies in deciding which events trigger the counter.

Strict Enforcement (Count Every Request): Every attempt, valid or not, consumes the limit. While secure, this often leads to "false positives"—locking out users due to flaky connections, page refreshes, or shared IP environments.
Adaptive Enforcement (Count Only Failures): We opted for this approach. By only incrementing the counter on incorrect guesses, we ensure that a user with the correct code is never blocked by the security layer.

The Security Math

Is "counting only failures" risky? Let's look at the entropy. For a code of length L using a character set of size S, the total combinations C is:

C = S^L

If we allow n attempts per window, the probability P of a successful brute-force attack is:

P = n / C

By choosing an appropriate L and S, even with a generous n, the risk remains statistically negligible (often < 0.001%), making the UX gain far outweigh the marginal security risk.

Implementation Pattern: The Verification Flow

Instead of sharing our production code, here is the high-level logic pattern. Note how the rate limit is checked and incremented only after a failed validation:

// A generalized pattern for secure verification
async function verifyAccessWithLimit(inputCode, context) {
  const { shareId, clientIp } = context;
  const identifier = `limit:${shareId}:${clientIp}`;

  // 1. Check if the user is already blocked
  const isBlocked = await rateLimiter.isLimitReached(identifier);
  if (isBlocked) {
    throw new Error("Too many attempts. Please try again later.");
  }

  // 2. Validate the code
  const isValid = await validateCode(inputCode);

  if (isValid) {
    return { success: true }; // Valid users are never penalized
  }

  // 3. Increment counter ONLY on failure
  await rateLimiter.recordFailure(identifier);
  return { success: false, error: "Invalid code" };
}

Key Design: Composite Identifiers

To prevent one attacker from affecting the entire system, we use composite keys. This ensures that rate limits are isolated:

// Abstracting the key generation to ensure isolation
function generateRateLimitKey(resourceId, userIp) {
  // Combining resource and IP ensures that an attack on 
  // Resource A doesn't block legitimate access to Resource B.
  return `ratelimit:res_${resourceId}:ip_${userIp}`;
}

Conclusion

True security is about proportional response. By focusing our defenses on failure patterns rather than total traffic, we created a system for DocBeacon that feels invisible to the user but remains an impenetrable wall for brute-force scripts.

I Finally Added Dark Mode, and It Forced Me to Fix More Than Colors

Howard Shaw — Mon, 15 Dec 2025 13:16:04 +0000

Dark mode is one of those features that sounds like "just swap a palette" until you actually ship it. I recently added dark mode to DocBeacon (a document sharing and analytics SaaS), and the implementation turned into an unexpected UI quality audit: charts, heatmaps, skeleton loaders, and even my spacing decisions were suddenly on trial.

This post is a technical walkthrough of what broke, what I changed, and the patterns I'd reuse next time.

Why dark mode is not a theme toggle

Users do not ask for dark mode because they love dark gray. They ask for it because they spend time in your product: reading analytics, reviewing dashboards, working late, switching between tabs. Dark mode is a comfort feature, but it is also a trust signal. If the UI looks inconsistent or unreadable in dark mode, the product feels less mature.

That is why I treated this as a system change, not a CSS tweak.

My implementation approach: token first, components second

The fastest path is usually to add a .dark class and override colors. That works until it does not.

What scaled for me was to define a small set of design tokens and refactor the UI to use them consistently.

I used a token approach roughly like this:

Background layers: bg.canvas, bg.surface, bg.elevated
Text: text.primary, text.secondary, text.muted
Borders: border.subtle, border.strong
Accents: accent, accent.contrast
Semantic states: success, warning, danger, info

Then I mapped tokens to actual colors for light and dark themes.

If you already use Tailwind, this maps nicely to CSS variables:

:root {
  --bg-canvas: 255 255 255;
  --bg-surface: 248 250 252;
  --text-primary: 15 23 42;
  --text-secondary: 51 65 85;
  --border-subtle: 226 232 240;
  --accent: 37 99 235;
}

.dark {
  --bg-canvas: 2 6 23;
  --bg-surface: 15 23 42;
  --text-primary: 226 232 240;
  --text-secondary: 148 163 184;
  --border-subtle: 51 65 85;
  --accent: 96 165 250;
}

And in Tailwind you reference them as:

.bg-canvas { background-color: rgb(var(--bg-canvas)); }
.text-primary { color: rgb(var(--text-primary)); }
.border-subtle { border-color: rgb(var(--border-subtle)); }

The point is not the exact colors. The point is that every component uses tokens, not hard-coded colors.

What broke first: visual hierarchy

In light mode, a lot of UIs get away with weak hierarchy because white backgrounds create contrast for free. In dark mode, everything compresses.

These were my main fixes:

Reduce the number of background layers. Too many surfaces make the UI look muddy.
Use stronger typographic hierarchy. Dark mode needs clearer separation through font weight and size, not just color.
Avoid pure black backgrounds. Near-black works better and keeps shadows, borders, and elevations readable.

Practical rule I adopted: if a component needs a border to be visible, the surface layers are too similar.

Skeleton loaders and empty states: "invisible UI"

This surprised me. Many of my skeleton loaders were built with subtle grays that were fine in light mode, but in dark mode they basically disappeared.

Fixes:

Use opacity-based tokens, not fixed grays.
Ensure skeletons have enough contrast to indicate shape, not just shimmer.

A better skeleton pattern is:

Use background based on bg.surface
Use a slightly lighter overlay for shimmer
Keep corners consistent with the real component

Charts: your default palette will betray you

I have charts in DocBeacon, and they were the first place dark mode exposed problems:

Axis labels became low-contrast
Grid lines either vanished or became too prominent
Tooltips looked like random floating boxes

What I changed:

Set chart text and grid colors from the same tokens as the rest of the UI.
Make tooltips use the same surface tokens as dropdown menus.

If you use a chart library, do not accept defaults. Route all chart styling through your theme tokens, otherwise charts look like a separate product embedded inside your product.

Heatmaps and highlights: loud colors become painful

Heatmaps were the hardest part. In light mode you can use aggressive colors and still keep things readable. In dark mode, the same colors become harsh and distracting.

I ended up doing two things:

1) Rebalanced the heatmap scale in dark mode

Instead of using the same color intensity, I reduced intensity and relied more on opacity.

2) Separated background heat from selection highlight

A common issue: your heat layer and your highlight layer compete. In dark mode, that competition is amplified.

Rule that helped: heat uses opacity, highlight uses hue. Do not let both fight at the same time.

Icons, badges, and "fine until it was not"

Dark mode is where sloppy UI decisions get exposed:

Icons that were PNGs instead of SVGs looked wrong
Badges had hard-coded backgrounds that clashed with everything
Focus rings were invisible

Fixes:

Make icons inherit currentColor where possible
Tokenize badge backgrounds and text
Tokenize focus rings (do not rely on browser defaults)

Testing strategy: how I avoided shipping a broken theme

If you only toggle the theme and click around, you will miss issues.

I did a boring but effective checklist:

Go through every major page and state: loading, empty, error, success
Check forms: focus, hover, disabled, validation errors
Check charts with real data (not demo data)
Check at least one mobile viewport and one desktop viewport
Screenshot key pages in both themes and compare side by side

If I were doing this again, I would also add visual regression tests (Playwright screenshots), because dark mode is a perfect candidate for snapshot diffs.

Takeaways

Dark mode is not colors. It is a forcing function that reveals:

Inconsistent component styling
Weak hierarchy
Over-reliance on subtle borders
Chart defaults that do not match your UI system
Heatmap and highlight conflicts

If your product has analytics, dashboards, or any "stare at this for 10 minutes" workflow, dark mode is worth doing. Not because it is trendy, but because it raises the quality bar across the UI.

If you shipped dark mode, what was the most unexpected thing that broke in your UI?

I built a Sankey chart to map document reading paths

Howard Shaw — Mon, 08 Dec 2025 12:17:23 +0000

Last week I shipped one of the biggest upgrades to my analytics engine since launch.

I was chasing a simple question. How do people actually move through a document
Not just page views, but start points, re-reads, and drop-off points.

Most tools stop at views or reading time. Useful, but they miss attention flow.

So I added a Sankey chart in DocBeacon to map session-level page transitions.

What I can see now

users starting on page 3 instead of page 1
loops where a section gets re-read
exits right after pricing

Under the hood, this required bigger changes than the UI suggests

session stitching
transition graph building
path weighting
sanity checks for noisy sessions

The result feels closer to intent analytics than file tracking.

Next step is turning these paths into actionable signals
content ordering suggestions, confusion hotspots, and lightweight benchmarks for proposals and pitch decks.

Refactoring the Analytics Core in DocBeacon: The Hidden Cost of Aggregation

Howard Shaw — Mon, 01 Dec 2025 12:48:52 +0000

I’ve been deep inside one of the most complex parts of DocBeacon, the tracking and analytics engine.

We aggregate user behavior data on three levels:

Share-level (each document share link)

Document-level (per uploaded file)

User-level (overall engagement footprint)

The challenge:
Every time a new event is logged (a view, scroll, or dwell), DocBeacon performs a hierarchical aggregation to update summary stats across all three levels. For users with large historical data, this can become very expensive, both computationally and in terms of API overhead.

The logical solution seems simple: reduce the frequency of aggregation.
But that’s where things got tricky.

Months ago, I noticed rare cases where the aggregation would silently fail to trigger. That meant the top-level summaries occasionally drifted out of sync, sometimes off by just a few views, other times more dramatically. The bug was elusive: hard to reproduce, impossible to ignore.

During this refactor, I’ve been dissecting the entire chain of event handling, from event queue → aggregation trigger → rollup storage. The logic is being restructured to make trigger conditions more deterministic and fault-tolerant.

So far, progress has been solid, but reproducing the original edge case remains challenging. Debugging aggregation bugs is like chasing ghosts, you only see their footprints.

Once this refactor ships, the analytics engine will be leaner, more predictable, and less resource-hungry. It’s the kind of work no one sees on the surface, but it’s what makes real-time analytics trustworthy.

Still testing. Hoping to roll out next week.

Training a model to predict a persuasion score for documents, but hitting a wall

Howard Shaw — Mon, 24 Nov 2025 13:29:03 +0000

I’m building DocBeacon: secure document sharing and tracking platform. It shows exactly how readers interact with each page: scroll depth, dwell time, replays, and even heatmaps of attention.

Recently I’ve been thinking about going a step further. Instead of just showing behavior metrics, what if DocBeacon could estimate how emotionally or cognitively engaged a reader is with a document? Something like a persuasion score that reflects how much a sales proposal actually moved them, did they seem convinced, neutral, or totally uninterested?

The basic idea sounds simple: use past reading behavior data and train a model to predict the likelihood of acceptance. But here’s the problem: I have plenty of behavioral data (how people read), yet no solid labels on what happened after they read. Without knowing whether the reader ended up accepting the proposal, replying, or ghosting, the model can’t really learn meaningful correlations.

Has anyone here tackled a similar cold-start problem?
Would it make sense to infer pseudo labels using proxy signals such as follow-up activity or revisit patterns? Or maybe combine user feedback loops to build a semi-supervised system?

Curious to hear how others would approach building a persuasion predictor when you only have half the story.

The SEO grind no one talks about

Howard Shaw — Mon, 10 Nov 2025 12:41:01 +0000

For the past couple of weeks, I’ve been deep in SEO work for DocBeacon
, my product is a secure document sharing and document tracking software. I wanted the marketing pages to sound more natural for readers while still keeping Google happy.

Turns out that balance is way harder than I thought.

While doing keyword research, I realized both core terms, “secure document sharing” and “document tracking software,” are insanely competitive. The keyword difficulty is sky high, and CPCs start at over $10. Now I understand why big SaaS companies spend so much on ads in this space.

I’ve probably spent more than a month rewriting, restructuring, and trying to improve page quality. And honestly, progress feels slow. You stare at analytics every day, hoping for movement, but SEO has its own rhythm. It moves quietly.

I’ve also been reading about programmatic SEO, generating thousands of pages through code and AI. It sounds great on paper, but I’m a bit skeptical. I don’t want to get flagged for thin or repetitive content. So for now, I’m doing most of it manually, using a bit of AI to speed up research and formatting.

This whole process made me realize how much patience SEO really takes. It’s not just about keywords or backlinks. It’s about good writing, structure, and showing up consistently.

If you’re working on SEO for your SaaS too, how are you finding the balance between quality and speed? I’d love to hear what’s been working for you.