DEV Community: Corpable

Build an Interactive, Printable Client Document Checklist with Plain HTML, localStorage and Print CSS

Corpable — Sun, 11 Oct 2026 02:07:56 +0000

Onboarding a B2B client almost always starts with a document list: certificates, IDs, bank letters, proof of address, product photos. Agencies and consultancies usually send this as a PDF or a Word file, and the client prints it, loses it, and emails back asking which items are still missing.

A better option, and one that takes an afternoon to build, is a single static HTML page that works as an interactive checklist on screen, remembers progress between visits, and prints cleanly as a paper form. No framework, no backend, no login.

This post walks through the pattern: semantic markup, localStorage persistence, a progress bar, and print CSS.

Why a static page beats a PDF

It can be linked, updated and versioned. When requirements change, every client sees the new list immediately instead of working from last year's PDF.
Progress survives. The client can tick off items over several days on the same device.
It's indexable. A public checklist page answers the exact questions prospects search for before they contact you.
It still prints. Some clients (and some compliance teams) want paper. Print CSS handles that.

A nice live example is the Alibaba.com Hong Kong onboarding document checklist published by a Hong Kong agency: it groups the documents a company needs, lets visitors tick items off with progress saved in the browser, and has a print button for a paper copy. The rest of this post shows how to build the same kind of page yourself.

1. Markup: plain checkboxes with stable IDs

The single most important decision is giving every item a stable ID that doesn't depend on its position. If you key saved state by index and later insert an item in the middle, every saved tick shifts by one.

<main class="checklist">
  <h1>Client onboarding documents</h1>

  <div class="progress" aria-live="polite">
    <div class="progress-bar"><span id="bar"></span></div>
    <p id="progress-text">0 of 0 completed</p>
  </div>

  <section>
    <h2>Company documents</h2>
    <label><input type="checkbox" data-id="br-cert"> Business Registration Certificate</label>
    <label><input type="checkbox" data-id="ci-cert"> Certificate of Incorporation</label>
    <label><input type="checkbox" data-id="nar1"> Latest annual return (NAR1)</label>
  </section>

  <section>
    <h2>Director and shareholder</h2>
    <label><input type="checkbox" data-id="dir-id"> Director passport or ID card</label>
    <label><input type="checkbox" data-id="dir-addr"> Director proof of address (within 3 months)</label>
  </section>

  <div class="actions">
    <button type="button" id="print">Print</button>
    <button type="button" id="reset">Reset</button>
  </div>
</main>

Wrapping each checkbox in a <label> gives you a large click target and correct screen-reader behaviour for free. The aria-live region announces progress changes.

2. Persisting state with localStorage

Store an object keyed by data-id, and namespace the storage key with a version so you can invalidate old state if the list changes fundamentally.

const STORAGE_KEY = "onboarding-checklist:v1";

document.addEventListener("DOMContentLoaded", () => {
  const boxes = [...document.querySelectorAll('input[type="checkbox"][data-id]')];
  const bar = document.getElementById("bar");
  const text = document.getElementById("progress-text");

  function load() {
    try {
      const saved = JSON.parse(localStorage.getItem(STORAGE_KEY) || "{}");
      boxes.forEach(cb => { cb.checked = Boolean(saved[cb.dataset.id]); });
    } catch {
      // Corrupt or blocked storage: start fresh rather than crash.
    }
  }

  function save() {
    const state = Object.fromEntries(boxes.map(cb => [cb.dataset.id, cb.checked]));
    try {
      localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
    } catch {
      // Private mode or quota exceeded: the page still works, it just won't remember.
    }
  }

  function render() {
    const done = boxes.filter(cb => cb.checked).length;
    const pct = boxes.length ? Math.round((done / boxes.length) * 100) : 0;
    bar.style.width = pct + "%";
    text.textContent = `${done} of ${boxes.length} completed (${pct}%)`;
  }

  boxes.forEach(cb => cb.addEventListener("change", () => { save(); render(); }));

  document.getElementById("print").addEventListener("click", () => window.print());
  document.getElementById("reset").addEventListener("click", () => {
    if (!confirm("Clear all ticked items?")) return;
    boxes.forEach(cb => { cb.checked = false; });
    save();
    render();
  });

  load();
  render();
});

A few things worth calling out:

Wrap storage access in try/catch. Safari private mode and some corporate browser policies throw on setItem. The checklist should degrade to "works, doesn't remember", never to "broken".
Ignore unknown keys. Because we only read IDs that exist in the DOM, removing an item from the list leaves harmless stale data rather than errors.
Confirm destructive actions. A reset button next to a print button will get clicked by accident.

3. Print CSS that produces a real form

On paper, the progress bar and buttons are noise, and the browser's default checkbox rendering is tiny. A short print stylesheet fixes both:

@media print {
  .actions,
  .progress { display: none; }

  body { font-size: 11pt; color: #000; }

  section { break-inside: avoid; }
  h2 { break-after: avoid; }

  label {
    display: block;
    padding: 4pt 0;
    border-bottom: 0.5pt solid #ccc;
  }

  input[type="checkbox"] {
    appearance: none;
    width: 11pt;
    height: 11pt;
    border: 1pt solid #000;
    vertical-align: middle;
    margin-right: 6pt;
  }
  input[type="checkbox"]:checked {
    background: #000;
  }

  @page { margin: 15mm; }
}

break-inside: avoid on each section stops a category heading from ending up alone at the bottom of a page. Drawing checkboxes as bordered squares means clients who print a blank copy get boxes they can tick with a pen, while anyone who already ticked items online gets them printed filled in.

4. Small touches that matter

Deep-linkable sections. Give each <section> an id so you can email a client a link straight to "Director and shareholder" when that's the only thing missing.

A "last updated" date. Requirements for bank accounts, platform onboarding and compliance change. Showing the revision date on the page (and in print) prevents disputes about which version a client followed.

Structured data, carefully. If the page is genuinely a step-by-step process, HowTo markup can describe it; for a plain list of documents, an ItemList or simply good headings is more honest. Don't mark up content that isn't visible.

Bilingual versions. If your clients split between languages, publish one page per language with matching data-ids. Since the IDs are language-neutral, you could even share the storage key so a client who switches language keeps their progress.

When to add a backend

This pattern intentionally stores nothing server-side, which is a feature: no personal data leaves the client's browser. Move to a backend only when you actually need one — for example, if your team needs to see which documents a specific client has ticked, or files need to be uploaded against each item. At that point the same stable IDs become your database keys, so the static version isn't wasted work.

Wrap-up

A static, interactive, printable checklist is one of the highest-leverage pages a service business can publish. It reduces back-and-forth email, answers pre-sales questions, and ranks for the exact "what documents do I need" searches prospects make. The whole thing is about 60 lines of JavaScript and 30 lines of CSS. Build one for whatever your clients most often ask you to send them a list of.

hreflang and JSON-LD for Bilingual Service Websites: Three Failure Modes and a Python Audit Script

Corpable — Sun, 11 Oct 2026 02:07:51 +0000

Most small B2B service companies in Hong Kong end up with a bilingual website: Traditional or Simplified Chinese for one audience, English for another. The content usually gets translated with care. The technical SEO layer underneath — hreflang annotations and structured data — usually does not, and it breaks quietly.

This post walks through the three things I check on every bilingual service site, plus a small Python script that audits them automatically so the checks don't depend on someone remembering.

The three failure modes

1. Non-reciprocal hreflang. Google only trusts an hreflang pair when both pages point at each other. If /en/pricing declares a zh-HK alternate but the Chinese page doesn't declare the English one back, the annotation is ignored. This happens constantly when one language version gets a redesign and the other doesn't.

2. Canonical fights hreflang. A common mistake is setting the canonical of the English page to the Chinese page ("because it's the original"). That tells search engines the English page is a duplicate, and it drops out of the index — the opposite of what you wanted. Each language version should be self-canonical.

3. Structured data drift. The Chinese page says the company offers four services; the English JSON-LD still lists two from last year. Or the telephone field was updated in one language only. Structured data is copy too, and it rots like copy.

What the markup should look like

For a page that exists in English and Hong Kong Chinese, the <head> of both versions should contain the same set of alternates:

<link rel="canonical" href="https://example.hk/en/services" />
<link rel="alternate" hreflang="en" href="https://example.hk/en/services" />
<link rel="alternate" hreflang="zh-HK" href="https://example.hk/services" />
<link rel="alternate" hreflang="x-default" href="https://example.hk/en/services" />

(On the Chinese page the canonical points at itself, https://example.hk/services; the alternates block is identical.)

Two details people miss: language codes use ISO 639-1 plus an optional ISO 3166-1 region (zh-HK, not zh-hk-traditional or cn), and every URL must be absolute.

For structured data, a professional service business usually needs an Organization (or ProfessionalService) node and one Service node per offering. Keep it honest — only mark up what's visible on the page:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "ProfessionalService",
      "@id": "https://example.hk/#org",
      "name": "Example Consulting Limited",
      "url": "https://example.hk/",
      "areaServed": "HK",
      "address": {
        "@type": "PostalAddress",
        "addressLocality": "Hong Kong",
        "addressCountry": "HK"
      }
    },
    {
      "@type": "Service",
      "name": "Company registration",
      "provider": { "@id": "https://example.hk/#org" },
      "areaServed": "HK"
    }
  ]
}

Using a stable @id for the organization lets every page reference the same entity instead of redefining it, which keeps the language versions consistent.

A real-world example

A good reference point is the English site of Corpable, a Hong Kong Alibaba.com onboarding agency, which runs parallel Chinese and English page trees for the same services. Sites like this are exactly where drift creeps in: pricing and service pages change frequently, and two language trees have to be updated in lockstep. View-source on any bilingual service site you maintain and check the three failure modes above — it takes five minutes and the results are often surprising.

Automating the audit

Manual checks don't survive a busy quarter. Here's a dependency-light script (requests + beautifulsoup4) that takes a list of URLs and reports problems:

import json
import sys
import requests
from bs4 import BeautifulSoup

def fetch(url):
    r = requests.get(url, timeout=20, headers={"User-Agent": "hreflang-audit/1.0"})
    r.raise_for_status()
    return BeautifulSoup(r.text, "html.parser")

def page_info(url):
    soup = fetch(url)
    canonical = soup.find("link", rel="canonical")
    alternates = {
        l["hreflang"]: l["href"]
        for l in soup.find_all("link", rel="alternate")
        if l.get("hreflang")
    }
    blocks = []
    for tag in soup.find_all("script", type="application/ld+json"):
        try:
            blocks.append(json.loads(tag.string or ""))
        except json.JSONDecodeError as e:
            blocks.append({"__error__": str(e)})
    return {
        "canonical": canonical["href"] if canonical else None,
        "alternates": alternates,
        "jsonld": blocks,
    }

def audit(urls):
    info = {u: page_info(u) for u in urls}
    problems = []
    for url, data in info.items():
        if data["canonical"] != url:
            problems.append(f"{url}: canonical is {data['canonical']!r}, expected self")
        if url not in data["alternates"].values():
            problems.append(f"{url}: missing self-referencing hreflang")
        for lang, alt in data["alternates"].items():
            if alt == url or lang == "x-default":
                continue
            other = info.get(alt) or page_info(alt)
            if url not in other["alternates"].values():
                problems.append(f"{url} -> {alt} ({lang}): not reciprocal")
        for block in data["jsonld"]:
            if "__error__" in block:
                problems.append(f"{url}: invalid JSON-LD ({block['__error__']})")
    return info, problems

if __name__ == "__main__":
    info, problems = audit(sys.argv[1:])
    for p in problems:
        print("FAIL", p)
    print(f"{len(problems)} problem(s) across {len(info)} page(s)")
    sys.exit(1 if problems else 0)

Run it against each language pair:

python audit.py https://example.hk/en/services https://example.hk/services

Because it exits non-zero on failure, you can drop it into a CI job or a nightly cron and get notified when someone ships a template change that breaks one side.

Comparing structured data across languages

Reciprocity is the easy part. The more valuable check is whether the facts in your JSON-LD agree across languages. Names and descriptions will legitimately differ, but phone numbers, addresses, prices, @ids and the number of Service nodes should not. A small extension:

LANG_NEUTRAL = ("telephone", "email", "@id", "url", "priceCurrency", "price")

def neutral_facts(blocks):
    facts = set()
    def walk(node):
        if isinstance(node, dict):
            for k, v in node.items():
                if k in LANG_NEUTRAL and isinstance(v, (str, int, float)):
                    facts.add((k, str(v)))
                walk(v)
        elif isinstance(node, list):
            for item in node:
                walk(item)
    walk(blocks)
    return facts

Diff neutral_facts() between the two versions of a page and print anything present on one side only. In my experience this catches more real bugs than the hreflang check — usually an outdated phone number or a price that was updated in one language.

A short checklist

Every language version is self-canonical.
Every page lists all alternates, including itself, with absolute URLs.
x-default points at the version you want for unmatched languages.
JSON-LD parses, uses a shared @id for the organization, and only describes visible content.
Language-neutral facts (phone, address, prices) match across versions.
The audit runs automatically, not when someone remembers.

None of this is glamorous, but for a service business whose leads come from search in two languages, it is the difference between both versions ranking and one of them silently disappearing.

Designing a Human-in-the-Loop Approval Matrix for an AI Agent That Drafts B2B Quote Replies

Corpable — Sun, 11 Oct 2026 01:52:21 +0000

If you let an LLM agent draft replies to inbound B2B quote requests (RFQs), the hard part is not the prompt. It is deciding, in code, which drafts may go out on their own, which need a human click, and which the agent must never write at all.

This post walks through the approval matrix pattern we use with small export sales desks: a declarative policy file, a field-level classifier, and a gate function that sits between the model and the outbox. The examples are in Python and YAML, but the pattern is tool-agnostic.

The failure mode we are designing against

An RFQ reply looks like prose, but it is really a bundle of commitments: a unit price, a quantity tier, a lead time, an Incoterm (FOB, CIF, DDP...), payment terms, maybe a certification claim. A model asked to "be helpful" will happily fill gaps. It will match the buyer's requested Incoterm, round a lead time down, or say "yes, we have CE" because that sounds like a good answer.

None of those are hallucinations in the classic sense. They are unauthorized commitments. So the control is not "make the model more accurate". It is "make sure the model can't commit to anything nobody approved".

Step 1: Classify the fields, not the message

Approving or rejecting a whole message is too coarse. A reply that confirms a catalogue link and asks two qualifying questions is low-risk. The same reply with one extra sentence ("we can do net-60") is not.

So we tag each commercial field with one of three tiers:

auto: the agent may draft and send, as long as the value comes from an approved source (catalogue, price book, FAQ).
review: the agent may draft, but a named human approves before sending.
human_only: the agent must not produce a value at all. It writes a holding reply and escalates.

Step 2: Put the matrix in a policy file

Keep the policy out of the prompt. Prompts drift; config files get code review.

# rfq_policy.yaml
version: 3
owners:
  sales_lead: "sales@desk.example"
  ops: "ops@desk.example"
  finance: "finance@desk.example"

fields:
  acknowledgement:   { tier: auto }
  catalogue_link:    { tier: auto }
  qualifying_question: { tier: auto }
  moq:               { tier: auto,   source: catalogue }
  lead_time_range:   { tier: auto,   source: catalogue }
  unit_price:        { tier: review, source: price_book, approver: sales_lead }
  quantity_tiers:    { tier: review, source: price_book, approver: sales_lead }
  incoterm:          { tier: review, source: sku_default, approver: ops,
                       allowed: [EXW, FOB, FCA] }
  sample_terms:      { tier: review, approver: sales_lead }
  certification:     { tier: review, source: cert_registry, approver: ops }
  payment_terms:     { tier: human_only, approver: finance }
  discount:          { tier: human_only, approver: sales_lead }
  exclusivity:       { tier: human_only, approver: sales_lead }
  complaint_or_claim: { tier: human_only, approver: sales_lead }

hard_stops:
  - off_platform_payment_request
  - bank_detail_change
  - ship_before_payment

Two details matter here. Every non-auto field has a named approver, so escalations don't land in a shared void. And source declares where an allowed value may come from. A value with no matching source record is treated as invented, even if it happens to be correct.

Step 3: Have the model emit structure, then render prose

Instead of asking the model for a finished email, ask for a JSON object: the fields it wants to assert plus the prose around them. Most current LLM APIs support schema-constrained output, which makes this reliable.

{
  "fields": {
    "moq": {"value": "500 pcs", "source_ref": "catalogue:SKU-1182"},
    "incoterm": {"value": "CIF Hamburg", "source_ref": null}
  },
  "body_template": "Thanks for your RFQ for SKU-1182. MOQ is {moq}. ..."
}

Now the gate can reason about exactly what is being promised.

Step 4: The gate

from dataclasses import dataclass, field

TIER_ORDER = {"auto": 0, "review": 1, "human_only": 2}

@dataclass
class Decision:
    action: str                 # "send" | "queue_review" | "escalate" | "block"
    reasons: list = field(default_factory=list)
    approvers: set = field(default_factory=set)

def gate(draft: dict, policy: dict, signals: set) -> Decision:
    stops = signals & set(policy["hard_stops"])
    if stops:
        return Decision("block", [f"hard stop: {s}" for s in sorted(stops)])

    worst, d = "auto", Decision("send")
    for name, f in draft["fields"].items():
        rule = policy["fields"].get(name)
        if rule is None:
            # unknown field = the model invented a commitment type
            rule = {"tier": "human_only", "approver": "sales_lead"}
            d.reasons.append(f"unknown field {name}")
        tier = rule["tier"]
        if rule.get("source") and not f.get("source_ref"):
            tier = max(tier, "review", key=TIER_ORDER.get)
            d.reasons.append(f"{name}: no source record")
        allowed = rule.get("allowed")
        if allowed and f["value"].split()[0] not in allowed:
            tier = "human_only"
            d.reasons.append(f"{name}: {f['value']} not in approved menu")
        if tier != "auto":
            d.approvers.add(rule["approver"])
        worst = max(worst, tier, key=TIER_ORDER.get)

    d.action = {"auto": "send", "review": "queue_review",
                "human_only": "escalate"}[worst]
    return d

With the sample draft above, incoterm has no source and CIF isn't in the approved menu, so the decision is escalate with ops as approver. The agent then sends only a holding reply: acknowledge, confirm MOQ, say the shipping terms will follow from a colleague.

A few design choices worth copying:

Unknown fields fail closed. If the model starts asserting something your schema doesn't know about, that's a policy gap, not a pass.
Missing provenance escalates one tier. That one rule catches most "confident but made-up" values.
Hard stops run first and are driven by a separate classifier (or plain rules) on the inbound message, not by the drafting model.

Step 5: Log decisions, measure the right things

Store every gate decision with the policy version, the draft, the approver, and the edit diff if a human changed something. After a few weeks you can answer useful questions:

Which review fields are approved unchanged 95%+ of the time? Those are candidates to promote to auto.
Which fields get edited most? That usually means the source data (price book, lead times) is stale, not the model.
What is the median first-reply time for qualified RFQs? Reply volume on its own tells you almost nothing.

Promotion between tiers should be a reviewed change to rfq_policy.yaml, never a prompt tweak.

Where this fits with off-the-shelf agents

Packaged agents for marketplace sellers increasingly ship with their own approval settings. For example, Alibaba.com's Accio Work agent can handle first-draft reception for a store, and we've written up how teams configure Accio Work with human approval steps. Even then, I'd keep an explicit matrix like the one above as the source of truth and map the vendor settings onto it, so the policy survives a tool change.

If you're building this from scratch, start with the data before the model. A short pre-launch checklist for RFQ desks (SKU defaults, Incoterm menu, cert registry, named approvers) will save you more incidents than any prompt engineering.

TL;DR

Classify fields, not messages: auto, review, or human_only.
Keep the matrix in a versioned config file with named approvers and required sources.
Make the model emit structured fields, and gate them before rendering prose.
Fail closed on unknown fields and missing provenance.
Promote fields to auto based on logged approval data, through code review.

How are you gating agent output in your workflows? I'd be curious whether others use field-level policies or something coarser.