Product specification / draft for review
Second Copy — Product Specification
A tip calculator that reads the check first. It rates the service, subtracts what the restaurant already charged you, and tells you what is actually left to decide.
The bet
Written honestly, because the honest version is the one worth arguing with.
Every tip calculator on the market answers a question nobody struggles with. Multiplying by 0.2 is not a problem. The actual problem, specifically in cities that have adopted service-charge models, is that the guest cannot tell how much they have already paid toward staff compensation before the tip line is even presented.
A San Francisco check routinely carries a health-mandate surcharge, sometimes a separate equity or kitchen fee, sometimes a credit-card surcharge, occasionally an auto-gratuity. These land at the bottom of the check in small type, and then the payment terminal presents 20, 22, 25 percent computed on a total that already includes them. The guest has no way to reason about it in the eight seconds they have while the server stands there.
The product is a translator for that moment. Rating the service is the interaction that makes it feel worth opening. Parsing the fees is the thing that makes it worth opening twice.
What this is not
This is not a venture business on its own, and the spec should not pretend otherwise. Consumer tip calculators have near-zero willingness to pay and brutal retention. The only asset worth building toward is the fee taxonomy described below, and even that is a dataset in search of a buyer. Ship it, learn from it, and hold it to the kill criteria at the end of this document.
Two modes, weighted correctly
The scanning feature is the interesting one. It is not the common one.
Assume roughly 85 percent of sessions are someone who wants a number in under five seconds. If the camera is the front door, the product dies. Scanning has to be an offer, never a gate.
Mode A — Quick
Opens directly to a numeric keypad and an amount field. Everything below it is pre-filled at the neutral assumption of 20 percent and can be left alone. The service rating is optional and collapsed. Result is visible before any input beyond the amount.
Fees are entered manually here, as a single percentage field, with a one-line hint about where to look on the check.
Mode B — Scan
A secondary action on the same screen. Camera opens, guest photographs the check, the parse populates subtotal, tax, and every fee line with its printed label. The guest confirms or corrects the parse before it is used. Scanning replaces data entry; it never replaces judgment.
The rating model
Five factors, weighted. The interaction matters more than the math.
Dragging five sliders at a restaurant table is too much work, and it also anchors the guest on a numeric scale they will second-guess. Better interaction: everything starts at "as expected" and the guest taps only what deviated. Most people tap zero or one thing. The tap targets are three-state, not five: below, as expected, above.
| Factor | What it captures | Weight |
|---|---|---|
| Attentiveness | Refills, check-ins, ease of flagging down | 30% |
| Warmth | Patience, tone, absence of rush | 25% |
| Accuracy | Order correct, modifications handled | 20% |
| Pacing | Food and check arrived sensibly | 15% |
| Above and beyond | Recommendations, comps, small extras | 10% |
Neutral maps to 20 percent. Each factor shifts the result by its weight multiplied by a fixed step, producing a practical range of roughly 14 to 25 percent before any fee adjustment.
The floor is a values decision, not a detail
The model will produce single-digit suggestions if every factor is marked down. Two defensible positions exist and the choice should be made deliberately rather than discovered in production:
- Hard floor at 15 percent. Matches what most apps do, avoids becoming a tool for stiffing workers, sidesteps a press cycle. Costs honesty.
- No floor, with friction. Below 15 percent the app shows a single line noting that in most states tips make up a large share of the server's wage, and requires a second tap. Honest, defensible, and slower.
Recommendation: no floor, with friction. A calculator that refuses to represent bad service is not a rating product, it is a guilt product, and guilt products do not get reopened.
The fee taxonomy
This is the only genuinely proprietary thing in the product.
Not all fees are the same, and the correct tip adjustment depends entirely on which kind you are looking at. Classifying the printed label into one of four buckets is the core logic.
| Bucket | Typical labels | Tip treatment |
|---|---|---|
| Auto-gratuity | Service charge for parties of six or more, mandatory gratuity, banquet service | Treat as the tip. Suggest zero additional, with an option to add. |
| Staff compensation | SF Mandate, health surcharge, employee benefits, kitchen appreciation, living wage, equity fee | Partial offset. Reduces the suggestion, does not eliminate it. |
| Cost pass-through | Credit card surcharge, non-cash adjustment, inflation fee | No offset. This goes to the processor, not to staff. |
| Unclassified | Anything the parser cannot place | Surface it verbatim and ask the guest. Never guess silently. |
The finding that reframes this
Under the final Treasury and IRS regulations for the federal tip deduction, a qualified tip must be voluntary, set solely by the customer, and reducible to zero without consequence. Mandatory service charges and automatic gratuities are explicitly excluded and are treated as wages, not tips.
That is not a technicality. It means a mandatory fee is legally a different instrument from a tip even when the restaurant routes it to staff. The app is not making a moral argument when it offsets against a service charge; it is applying a distinction the tax code already draws. That is the strongest available basis for the offset logic, and it should be the one-line explanation shown to the guest.
Why the labels are readable at all
California's honest-pricing law originally swept restaurant surcharges into a general ban on hidden fees. An urgency amendment carved restaurants out, but on the condition that any mandatory fee be clearly and conspicuously displayed with an explanation of its purpose on any menu or display showing prices, meeting a statutory definition of conspicuous as of mid-2025.
The practical consequence for this product: in California the fee label is legally required to be meaningful and legible. That is a real tailwind for an OCR-based classifier and a real reason to start here rather than in a state with no disclosure requirement.
Receipt data model
What the parser extracts, what it derives, and what it must destroy.
Extract — required for the calculation
| Field | Notes |
|---|---|
| Subtotal | Pre-tax. The denominator for every percentage in the app. |
| Tax amount | Derive the effective rate rather than assuming a jurisdiction default. |
| Total | Reconciliation check. If the lines do not sum, flag the parse as low confidence. |
| Fee lines | Verbatim label string, amount, and computed percentage of subtotal. The label string is the input to the classifier and must be preserved exactly. |
| Currency | Guard against parsing a non-USD check. |
Extract — context and confidence
| Field | Why it earns its place |
|---|---|
| Merchant name and street address | Keys the establishment record. Address is more reliable than name for matching. |
| Date and time | Distinguishes lunch from dinner service; fee structures sometimes differ. |
| POS vendor fingerprint | Footer strings identify Toast, Square, Clover, Aloha. Parser accuracy is meaningfully higher when the layout family is known. |
| Guest count and table number | Guest count triggers the auto-gratuity threshold check. Table number is discarded after that. |
| Printed suggested-tip grid | The percentages offered and whether they are computed on the pre-tax or post-tax figure. This is quietly the most interesting field on the receipt and nobody is collecting it. |
Never store — strip on device before anything leaves it
| Field | Reason |
|---|---|
| Card number, including last four | Brings PCI scope into a product that has no business being in it. |
| Cardholder name and signature | Directly identifying, and serves no product function. |
| Server name and employee ID | See the constraint below. This is the single most consequential line in the document. |
| Auth code, merchant ID, terminal ID | Payment-network identifiers with no product use. |
| The raw image | Deleted after parse. Never uploaded in a retained form. Say this plainly in the interface, not only in a policy. |
Hard product constraint: no per-server data, ever
Receipts carry the server's first name and often an employee number. Joining service ratings to that identifier would produce per-worker performance data assembled by strangers without consent. Restaurants would buy it. That is precisely the problem.
It would make the company an involuntary employment-surveillance vendor, create records it does not want to hold under California employment and privacy law, and hand any reporter an easy story. Ratings key to the establishment and the visit. Nothing finer. Build the schema so that attaching a worker identifier later is not merely disallowed by policy but structurally impossible.
Contribution model
Aggregate fee data leaves the device only on explicit opt-in, presented after the first successful scan rather than buried at install. What ships when the guest opts in: establishment, date, subtotal band rather than exact amount, fee labels and percentages, tax rate, POS family, and the service rating. Nothing else.
Jurisdiction layer
Yes, the rules vary by state. The interesting part is deciding how little the product should let that matter.
Tipped-wage law sorts into three tiers plus one special case, verified for 2026:
| Tier | Jurisdictions | What it means |
|---|---|---|
| No tip credit | Alaska, California, Minnesota, Montana, Nevada, Oregon, Washington | Employer pays full state minimum wage in cash. Tips are entirely additional and cannot offset the wage obligation. |
| Federal floor | Roughly sixteen states including Texas, Georgia, Tennessee, North Carolina, Virginia | Cash wage as low as $2.13 with a tip credit up to $5.12. Tips carry most of the server's earnings. |
| Middle | Everyone else | Tip credit permitted but cash wage well above the federal floor, varying by state, locality, industry, and sometimes employer size. |
| District of Columbia | Special case | Initiative 82 was partially repealed in the 2026 budget. The tipped wage held at $10 through June 2026, moves to 56 percent of the full minimum wage on 1 July 2026, and steps every two years to a cap of 75 percent in 2034. |
What this should and should not change
It should not change the suggested percentage. Tipping norms in the United States are cultural and national, not indexed to local wage statute. A server in Seattle expects the same 20 percent as one in Nashville. An app that quietly suggests less in no-tip-credit states has taken a political position its users did not ask for, and will be covered as such.
It should change the explanation. One line, shown behind a "why this number" tap, stating the wage structure where the guest is standing. In federal-floor states that line is genuinely material information. In no-tip-credit states it is useful context. Neither moves the number.
Maintenance is the real cost
Minimum wages change on 1 January in roughly nineteen states, with additional July changes in Alaska and DC, and localities layer on top. A wage table is a standing obligation of at least two verified updates a year, sourced from state labor departments rather than aggregators. Every displayed figure carries a visible "verified as of" date.
If that obligation cannot be committed to, cut the jurisdiction layer entirely. Stale wage data is worse than no wage data. Nothing in the app is tax or legal advice and the interface should not imply otherwise.
Design direction
Working name: carbon copy. This document is set in it.
The subject world is the restaurant check, and the specific artifact worth borrowing from is the carbonless duplicate slip: the two-part form where the top copy goes to the merchant and the bottom copy goes to you. That structure is not decoration here, it is the information architecture. What the restaurant charged sits above the tear. What you are choosing to add sits below it.
Palette
Carbon is a purple-black, the color of impact-printer ribbon, not pure black. Ballpoint blue is the accent and appears only on things the guest controls. Stamp red appears only on the total and on warnings. Canary is the second copy.
Type
The inversion that carries the whole identity: monospace is the display face, not the utility face. Martian Mono at large sizes with tight negative tracking for headings, section labels, and every number. Instrument Sans for body copy. Most products use monospace only for code; here it is the native typography of the artifact the product is about, and tabular figures are functionally required because receipts align on the decimal.
Signature elements
- The tear line. Sections are separated by a perforated edge with notched corners, as seen throughout this document. It is the one piece of skeuomorphism in the system and it earns its place by encoding the above-the-line and below-the-line split.
- Leader dots. Every label-to-value pair uses dotted leaders. Small, consistent, unmistakably a check, and requires no texture or imagery.
- The stamp. The final tip percentage does not fade in. It stamps, with a slight rotation off-axis, once, when the rating settles.
Motion
One orchestrated moment rather than scattered effects. When the guest finishes adjusting, the summary rows print downward in sequence at impact-printer speed, roughly forty milliseconds per row, then the percentage stamps. Nothing else in the app animates. Reduced-motion preference disables the sequence and renders the block directly.
Explicitly avoided
- Paper textures, drop shadows simulating physical depth, curled page corners. The system is typographic, not illustrative.
- Emoji or star ratings. Stars are the visual language of Yelp and would frame this as a review product, which it is not.
- The three-large-preset-buttons layout used by every payment terminal. Designing against that screen is half the point.
- Cream backgrounds with a high-contrast serif and a terracotta accent. That combination has become the house style of generated design and would undercut the claim to a point of view.
Requirements
Must have
- P0Amount entry with live result, no account, no onboarding.
- P0Five-factor three-state rating, defaulted to neutral, fully skippable.
- P0Manual fee percentage entry with offset applied by bucket.
- P0Split by party size on the final total.
- P0Pre-tax versus post-tax toggle for the tip basis, defaulting to pre-tax.
- P0"Why this number" explanation, one screen, plain language.
Should have
- P1Receipt scan with on-device PII stripping before any network call.
- P1Fee label classifier across the four buckets, with confidence surfaced to the guest.
- P1Parse confirmation screen. Nothing computed from an unconfirmed parse.
- P1Local visit history, device-only, no sync.
Later, but do not architect against
- P2Jurisdiction wage-context layer with verified-as-of dating.
- P2Establishment fee profiles built from opted-in contributions.
- P2Aggregate fee-prevalence reporting, which is the only plausible commercial artifact here.
Not building
- Per-server ratings or any worker-level identifier. Permanent.
- Payments, bill splitting between people, or anything touching money movement.
- Restaurant reviews, social features, or a feed.
- Non-US jurisdictions, where tipping norms differ enough to be a separate product.
Metrics and kill criteria
Leading, first thirty days
Lagging, ninety days
Kill criteria, written before there is anything to defend
- If fewer than 25 percent of users return within 30 days, the rating layer is not creating a reason to reopen, and no amount of feature work will fix that. Stop.
- If fee-line recall on real San Francisco checks stays below 85 percent after two parser iterations, the differentiating feature does not work, and what remains is a commodity calculator. Stop.
Evaluate both at day 90. Not later.
Open questions
- Floor. Hard 15 percent or friction-gated honesty. Values call, needs deciding before any interface work.
- Parse location. Fully on-device is the stronger privacy claim and the weaker accuracy story. Requires a spike on real checks before committing.
- Whether the wage-context layer ships at all, given the twice-yearly maintenance obligation attached to it.
- What the offset ratio is for staff-compensation fees. The prototype uses 0.6, which is a guess with no basis. Needs either a defensible rationale or a stated arbitrary default that says so.
- Distribution. A mobile web app is faster to ship and worse at camera access. An install is a real barrier for a utility this small.