← Vault Index
business / marketing / skills / calculator-tool-SKILL.md
Source: business/marketing/skills/calculator-tool-SKILL.md

Calculator Tool Skill

What This Is

A Calculator Tool takes someone's real numbers and computes a result they couldn't see without doing the math. The person provides 3–5 inputs. The tool does the arithmetic and shows them what their numbers mean.

This is NOT a diagnostic (which sorts into categories) or a revelation tool (which surfaces hidden quantity). A calculator says "given YOUR specific numbers, here's what's actually happening in your practice."

The value is in the computation. The person walks in with scattered numbers they've never put side by side. They walk out with a ratio, a gap, or a projection they couldn't have computed on their own — using their own data.

When to Use This Tool Type

Use a Calculator Tool when:

Do NOT use when:

Architecture

INTRO SCREEN (frames what the numbers will reveal)
    ↓
CALCULATOR SCREEN (3–5 inputs with labels + hints, all visible at once)
    ↓
RESULTS PAGE
    → Hero number (primary computed metric — big, colored by severity)
    → Ratio insight line (standalone callout — the sentence they'll remember)
    → Ratio/comparison visualization (bar showing the relationship)
    → Stat grid (supporting computed numbers)
    → Equation visual (before → after transformation)
    → Insight box (severity-tiered interpretation)
    → Context box (scale-appropriate framing)
    → Bridge to companion content
    → CTA
    → Disclaimer
    → Recalculate button

The Critical Pattern: Computed Insight

Every result is arithmetic on the user's inputs. No preset categories. No scoring. The same tool produces entirely different numbers, visualizations, and contextual copy depending on what the person enters.

Why This Works

A diagnostic tells someone "you're in category B." A calculator tells someone "your dead list is worth 3.2× your entire marketing budget — that's $156,000 a year sitting in conversations you already had." The second uses THEIR numbers, which makes it undeniable. They can't dismiss it as generic advice because the math came from their own inputs.

The Insight Line

Every calculator needs one sentence that captures the entire computed relationship. This sentence gets its own visual moment on the results page — an insight box with a severity-colored left border and a label like "The ratio."

Good insight lines reference both sides of the relationship:

Bad insight lines state only one number:

Input Design

Input Rules

Input Anti-Patterns

Bad InputWhy It FailsBetter Version
Full-width text field with placeholder "e.g. 30"Looks like a text field, not a number entry. Placeholder text disappears on focus, removing the guidance.Narrow (100–120px) number field with em-dash placeholder and unit label beside it: [—] contacts
border-radius: 6px on inputs and buttonsRounded corners soften the brand's sharp geometric identity. Doesn't match any shipping AOS tool.Sharp corners (no border-radius) on inputs, buttons, insight boxes, ratio bars
No section labels between input groupsAll inputs feel like one undifferentiated listGold uppercase eyebrow labels group inputs: "Your Practice" / "The Recovery Question"
No form divider when context shiftsMissing visual signal that inputs serve different parts of the computation
 with 1px border-top between input groups

Number Field Spec

<div class="input-group">
    <div class="input-label">People who went quiet in the last quarter</div>
    <div class="input-hint">No-shows, ghosted proposals, past clients who drifted. Count all of them.</div>
    <div class="input-row">
        <input type="number" class="input-field" id="input-contacts" placeholder="—" min="1" max="500" oninput="checkReady()">
        <span class="input-unit">contacts</span>
    </div>
</div>

Slider Spec

<div class="slider-value" id="slider-display">20%</div>
<input type="range" class="slider" id="input-recovery" min="10" max="40" value="20" step="5" oninput="updateSlider()">
<div class="slider-labels">
    <span>Conservative (10%)</span>
    <span>Aggressive (40%)</span>
</div>

Hint Design

Calculator hints tell the person WHAT TO COUNT. They're more specific than diagnostic/revelation hints because the person is providing actual numbers, not selecting from options.

Good hints:

Bad hints:

Validation

function checkReady() {
    var c = document.getElementById('input-contacts').value;
    var v = document.getElementById('input-value').value;
    var m = document.getElementById('input-marketing').value;
    document.getElementById('btn-calculate').disabled = !(c > 0 && v > 0 && m !== '');
}

Calculate button stays disabled until all required fields have valid values. No partial results. No "we'll estimate the rest."

Edge case: $0 inputs. Some inputs legitimately accept zero (e.g., marketing spend — they might spend nothing). Allow zero where it's a real answer, but handle it in the computation: if marketing is $0, skip the ratio bar and reframe the insight around "this is your only growth channel."

Computation Logic

Pure arithmetic. No scoring, no categories. The calculator computes derived values from raw inputs and determines severity thresholds for contextual copy.

Deriving Everything From Their Inputs

This is a hard rule. Every number on the results page must trace back to what the person entered. No smuggled assumptions. No made-up benchmarks.

GoodBad
recoveredClients = Math.round(contacts * recoveryRate) — both values from their inputsnewClients = Math.round(marketingSpend / 3000) — the $3,000 acquisition cost is a number you invented, not something they entered
ratio = quarterlyRecoverable / marketingSpend — both from their inputscostPerAcquired = marketingSpend / estimatedNewClients — estimatedNewClients is a guess

If a derived metric requires an assumption, either make it an input (let them enter it via slider) or don't show the metric.

Severity Thresholds

The primary computed metric determines which tier of contextual copy to display. Three tiers:

Each tier gets different insight copy, different color treatment, and different framing — but the NUMBERS are always the person's real numbers. Only the interpretation changes.

Severity Background Consistency

All three severity tiers use the same opacity for background fills: rgba(r, g, b, 0.1). This keeps the visual weight consistent across tiers.

Note: the brand kit's canonical gold-dim value is rgba(183, 157, 100, 0.3) — that's for borders and tints, not background fills on insight boxes. At 0.3 the gold panel is noticeably more opaque than red or green panels at 0.1, creating inconsistent visual weight.

Division by Zero

Handle every case where a denominator could be zero. If marketing spend is $0, the ratio is undefined — don't compute it, don't display the ratio bar, and write the insight line to address the $0 case directly.

Results Page Structure

The results page does eight things in order. Some are conditional based on the tool's specific computation.

1. Hero Number

The single most important computed metric, displayed enormous. This is the moment of impact.

The hero number must be severity-colored, not always gold. If the hero is always gold regardless of the result, it undermines the severity system — a "good" result and a "bad" result look identical at the moment of impact.

2. Ratio Insight Line

The one sentence that captures the computed relationship. Gets its own insight box with severity-colored left border.

If the denominator is zero (e.g., $0 marketing), write a different insight line that doesn't reference the ratio. Don't show "infinity" or "$0" in a ratio sentence.

3. Ratio/Comparison Visualization

Shows the relationship between two computed values visually. Conditional — skip if one side is zero.

4. Stat Grid

Supporting numbers in a 2-column grid of cards.

5. Equation Visual

Shows the before → after transformation.

The equation must use only their inputs. Don't introduce made-up numbers in the equation (see Computation Logic).

6. Insight Box (Severity-Tiered)

Interpretation of their specific numbers. Neutral styling (subtle background + 1px border, no severity color).

7. Context Box (Scale-Tiered)

What the recovered/changed numbers mean in practical terms. Same neutral styling.

8. Bridge + CTA

Bridge to companion content: Links to the campaign's thought leadership article. Copy should connect their specific numbers to why the deeper content matters.

Bridge copy quality rule: Name the specific mechanisms from the article, not generic teasers.

Good BridgeBad Bridge
"Each of those 30 silent contacts went quiet for a different reason. A no-show needs permission to come back without shame. A stalled proposal needs a smaller entry point.""The full breakdown shows how practices make the shift."

The good version names wound types and barriers. The bad version could describe any article about anything.

CTA: Connects calculator output to the service. The copy should name what the calculator showed AND what the service provides.

Below CTA:

UX Rules

Navigation

Transitions

Visual Design

Brand Compliance

All colors use hardcoded hex values in output files. Never use CSS custom properties (var()). The brand kit skill is explicit: canonical names (charcoal, gold, cream) are documentation labels, not CSS variable names.

Page Layout

Full-page screens. No tool-container wrapper (unlike revelation/diagnostic tools which use a container with gold border).

Core Palette (Hardcoded)

NameHexRole
charcoal#1a1a1aBackground, nav, footer
deep-charcoal#2a2a2aGradient depth
gold#b79d64Accent — labels, CTAs, slider, scrollbar
gold-light#c4aa74Hover states
cream#f5f4f0Primary text
stone#8a8680Secondary text, hints, units
red#c45a4aHigh severity, "bad" numbers
green#5a9a6aLow severity, "good" numbers

No ad hoc colors. Every hex in the file must appear in this table.

Typography

ElementFontSizeWeight
Intro titleCormorant Garamondclamp(2rem, 5vw, 2.75rem)400
Input labelsInter14px400
Input hintsInter12px300
Input fieldsInter18px400
Input unitsInter13px300
Section/eyebrow labelsInter0.625rem (10px)600, 0.25em tracking, uppercase
Slider valueCormorant Garamond2rem—
Hero numberCormorant Garamondclamp(4rem, 12vw, 7rem)300
Stat card numbersCormorant Garamond2.5rem300
Equation numbersCormorant Garamond1.75rem300
Insight box titleInter15px500
Insight box bodyInter15px300

Cormorant Garamond is never set below 18px. Never set to Bold (700). Inter is never used for headlines.

Signature Elements

Gold appears on max 2 elements per viewport. Count: intro screen has gold in the time label + button = 2. Calculator screen has section labels + slider value + button = 3 — acceptable because section labels are small and scanner-level, not competing with the CTA.

Sharp Geometry

No border-radius on structural elements — inputs, buttons, insight boxes, ratio bars, equation boxes. Only exceptions: scrollbar thumb (5px), slider thumb (50% / circle), legend dots (50% / circle).

Technical Specs

JavaScript Architecture

showScreen(id)        → Toggle active screen, scroll to top
updateSlider()        → Live-update slider value display
checkReady()          → Enable/disable calculate button based on input validity
calculate()           → Read inputs, compute all values, determine severity,
                        build full results HTML, show results screen
insightTitle(ratio)   → Return severity-tiered title string
insightBody(ratio, …) → Return severity-tiered body with computed numbers embedded
recoveryContext(…)    → Return scale-tiered context paragraph

QC Checklist

Brand Compliance

Inputs

Computation

Scoring Validation

Results

UX

Technical

Copy Quality

Reference Implementations

Subtract/Add Calculator (calculator-micro-tool-golden-example.html)

Dead List Calculator (dead-list-calculator.html)

Skill file reverse-engineered from the Subtract/Add Calculator and the Dead List Calculator, February 2026 v2: Scoring Validation section added from recurring QC gap identified during System Readiness Assessment build