§00

Changelog

What changed, when, and where to look. Newest at the top. The full per-commit history lives in README.md; this is the designer-facing summary.

Pre-v4.0 history (v3.6.1 onwards) lives in README.md. The book itself starts its narrative at v4.0.0 because that’s the version this chapter numbering became canonical.

§01

Brand Constitution & Positioning

正補 is a decision rule, not just a name: doing things the right way while nourishing people. It allows Herbal Care to modernise without abandoning tradition.

The name 正補

Vision & Mission

Vision. To be the trusted brand for safe, high-quality, and ethical health foods.

CARE values

Personality sliders

The calibration tool: when a draft feels off, name which slider is being violated. Each axis is a continuum; the tick marks Herbal Care’s actual position.

Five promises

Positioning one-pager

How positioning translates differently for households and operators. Use this when briefing copy, sales decks or onboarding.

Competitive differentiation

What other players sell against, and where we sit. We do not compete on lowest price or loudest health promise; we compete on standards, documentation and food-first honesty.

§02

Brand Architecture & Sub-brands

A hierarchy map and a decision tree are not the same artefact. The map explains relationships; the tree tells the designer what to choose.

Hierarchy map

Decision tree

Role definitions

Every brand and sub-brand has a status, a role and a specific surface where it appears. The hierarchy says how they relate; this table says what each one is for.

Naming & endorsement rules

For every situation, lead with one brand and add an endorsement string only when it earns trust. Designers may select from this lookup; they may not invent new strings.

9.1 Medic Point — Active Legacy

9.2 PlainFoods — Strategy Parking Lot

9.3 HerbsMart — Utility Sub-brand

HerbsMart status label vocabulary

Status colours and meanings are defined in §04 Semantic status tokens. HerbsMart uses six approved label words on top of those tokens:

Rejected Claim is internal copy-validation only — never shown to customers.

§03

Brand Modes — Operating System

Modes let Herbal Care 正補 behave appropriately by context without turning into five different brands. Same foundation, different emphasis.

§04

Colour System

The colour system stands out without sacrificing premium calmness. Lime is signature, not wallpaper — a recognition CTA when paired correctly, never a background.

Core swatches

Click any swatch to copy its CSS token name.

Neutrals

Ink — text & dark surfaces

Brand accents

Quarantined sub-brand colours

These belong to specific sub-brand or seasonal contexts only — never as Herbal Care master expression.

Colour usage ratios by mode

Each ratio is a design target, not a rigid mathematical law. The principle is more important than exact arithmetic.

CTA rules

Hard pairing rules

Each tile is the actual foreground / background pair. Banned tiles render with their contrast failure visible — White-on-Lime is unreadable because it is unreadable. The diagonal hatching marks banned; everything else is approved. Use this as the lookup for “can I put X on Y?”.

Approved pairings

Banned pairings

Semantic status tokens

Functional UI tokens — not brand-expression colours. Pending uses Muted Umber to keep the warning slot clear of brand Honey.

Paper / Stone / Card visibility rule

The brand uses three close-tone neutrals (Paper 50, Paper 100, Stone 300) for warmth. The rule exists because designers naturally reach for tone-on-tone and produce cards that disappear. Below: same content, same Paper 50 background, with and without the visibility anchor.

§05

Typography

Font stack

Type scale

English–Chinese co-setting

Pairing examples

Co-setting — rendered good vs bad

The four rules above are easy to read and easy to ignore. The two stages below show the same paragraph, set wrong (left) and right (right). Toggle your eye between them — the wrong version looks broken in a way that's hard to articulate without seeing it.

§06

Logo System

The logo system is production-ready. Pull lockups from the Figma library or request exports via the brief in §06.5. Do not redraw the logo or invent new variants.

Approved lockup variants

Horizontal lockup

Default. Website header, footer, corporate documents.

Stacked lockup

Packaging, social avatar, square spaces.

Monochrome Ink

Single-colour Ink 900. Documents, invoices, low-cost print.

Reversed on Ink

Dark sections, footer. Maintain clear space; avoid busy photography.

Variants 1 & 2 above are SVG (vector); variants 3 & 4 are PNG (cleaner production cuts without the brushy textured edge). Vector source for all four plus the editable .ai masters live in the Source files block below.

Minimum sizes & clear space

Clear-space rule, visualised

The dashed Lime ghost shows the minimum keep-out zone around each lockup. For the horizontal & stacked lockups, clear space equals the height of 正補; for stacked, half that on all sides.

Horizontal lockup · clear space = height of 正補

Stacked lockup · clear space = ½ mark height all sides

Sub-brand lockups

Two active sub-brand lockups exist alongside the master Herbal Care 正補 system. Each retains its own legacy artwork and colour identity per §02 sub-brand quarantine; they never replace the master, only endorse it.

Medic Point 美麗寶

Active legacy. Old-trade SKUs, continuity packaging, brand history. Always endorsed by Herbal Care 正補.

HerbsMart — primary stacked

Utility trade. Portal, SKU database, quote / reorder workflow. Always carries “powered by Herbal Care 正補”.

HerbsMart — secondary horizontal

Wide surfaces: portal nav, footer strip, email header, B2B catalogue header.

HerbsMart — icon only

Favicon, app icon, square avatar, dense UI. Use only when the “HerbsMart” word appears nearby in context.

Sub-brand identity rules

Co-branding & endorsement

Do / Don't

Export brief

File-naming convention: HC_<variant>_<colour-mode>_<size>.<ext> · e.g. HC_horizontal_colour_4x.png, HC_stacked_mono-ink.svg.

Source files

The canonical artwork lives in assets/logo/source/ as Adobe Illustrator masters; SVG and PNG are derivatives. Designers who need to scale, reflow, recolour, or extract individual marks should pull from the .ai source.

§07

Photography & Visual Identity

Warm means real food, natural material, human kitchen context. Standards mean clean layout, true colour, visible texture, clear labels — no mysticism.

Visual world definition

Photography pillars (P01–P08)

Eight pillars cover every approved product, editorial and proof image. Each card carries the shot spec, intended use and the one rule it fails. Three principles govern every shoot, whether commissioned or AI-generated.

What we reject — and why

Four canonical reject patterns shown first; six photography traps below. The traps cover photography only — colour-pairing rules and sub-brand colour quarantine live elsewhere (cross-references at the foot of the table).

Six photography traps

Two related rules live elsewhere: White-on-Lime / Honey / Orange CTA contrast → ch.04 Hard pairing rules. Medic Red colour quarantine → ch.02 Sub-brand identity rules.

AI avatars & lab-coat rule

§08

Iconography & Patterns

Icons & patterns

The iconography rule is short — five disciplines, applied everywhere.

Iconography — numeric spec

The five rules above are the discipline. The numbers below are the spec. Every icon in a Herbal Care surface — corporate, consumer, utility or premium — must conform to these constants.

Pattern & motif rules

Surface treatments that sit alongside icons. Same disciplines apply: Ink default, restraint over decoration, never as wallpaper.

Sub-brand exceptions

Approved demonstration grid

Six icons rendered to spec — three line-default body icons, two filled status indicators, one container with corner-radius 8 px.

§09

Components

Five button variants, five card variants, status chips on the semantic palette only. These are surface-level expressions of §04 colour and §05 type.

Buttons

Five variants. Forest is the default serious CTA on light. Lime-on-Ink is the signature recognition CTA.

Button state matrix

Five variants × six states. Hover and active are interaction states (modifier classes .is-hover / .is-active simulate them for demonstration). Focus shows the universal 2 px Lime focus ring (§05 Accessibility). Loading is the skeleton-over-spinner pattern from §05 Motion.

Chip and card states

Hover / active / focus states above are simulated with .is-hover / .is-active / .is-focus modifier classes for demonstration. In production code, never set these classes by hand — let the browser handle :hover, :active and :focus-visible natively.

Status chips

Visual rendering of the §04 Semantic status tokens. The chip styling here; the token definitions, hex values and usage rules live in §04.

Badges

Small inline labels for grade, origin, certification, gift mode.

Cards — five variants

All cards must respect the Paper / Stone / Card visibility rule (§04.6).

§10

Layout & Responsive

Document layout

This brand book documents itself: the same layout tokens specified here apply to every standards-led document Herbal Care publishes — internal specs, customer-facing PDFs, web pages, and the brand book you are reading.

Responsive breakpoints

Four breakpoints, applied as a max-width cascade. Every page in this book — and every Herbal Care web surface that adopts these tokens — must work cleanly at all four.

Three layout rules, applied throughout this book.

§11

Motion

Motion

Motion is signature, not decoration. It exists to confirm action, soften state changes and guide attention — never to entertain. Three duration tokens, two easing tokens, four interaction patterns, three explicit don'ts.

Duration & easing tokens

Interaction patterns

Reduced motion

The user's OS-level prefers-reduced-motion: reduce setting is honoured globally. Animation and transition durations shorten to 0.01 ms — the motion still occurs, but at single-frame speed so it is perceived as an instant state change. Cross-reference: §05 Accessibility.

Three explicit don'ts

Live demonstrations

The brand book is HTML; it can show its own motion rules in motion. Hover, click and replay the four demos below to feel each token. All animations honour prefers-reduced-motion: reduce — toggle that OS preference and the demos collapse to single-frame.

Implementation note. The state-change drawer uses grid-template-rows: 0fr → 1fr (modern browsers from 2023+); older fallbacks degrade to instant open. The reveal animation uses animation-delay staggered at 60 ms increments. Skeleton shimmer uses a moving linear-gradient on background-position. No JavaScript framework — vanilla event listeners only.

§12

Accessibility

Accessibility

Five rules govern accessibility across every Herbal Care surface. The brand book itself meets WCAG 2.2 AA for body text and large text using the approved token combinations below.

Approved token-pair contrast

Every approved foreground / background combination, with the measured WCAG ratio and an actual text-on-swatch sample. Banned pairings are shown so the failure is visible — if you can't read the sample, the pair fails contrast.

Minimum type sizes

Type minimums — rendered samples

Same string at each documented size, in both Latin and Chinese, so the floor is felt rather than told. The 11 px Latin row is reserved for legal disclaimers; the 12 px CJK row is the absolute floor for product information.

Interaction rules

§13

Voice & Messaging

Core voice attributes

The five words above carry weight only when each one is paired with what it is not. The contrast column is the calibration tool — when a draft feels off, name the attribute being violated.

Tone by channel

Language & script — locked rule

Keith personal brand vs Herbal Care corporate voice

Herbal Care's official channels speak as the company. Keith's Lark, tech, training and personal thought-leadership are separate, and may reference Herbal Care only as a lived case study. The firewall protects both reputations.

Tone-of-voice library — 30 contexts

Every recurring writing situation Herbal Care faces, paired with the weak / risky version a draft tends to default to and the Herbal Care rewrite. Use this as a copy-paste reference for marketing, sales, customer service and HR.

Crisis comms guardrails

Crisis statement skeletons

Drafted opening statements for the six scenarios above. Treat as starters, not finals — every actual statement requires sign-off by Brand Lead + Management before release. The skeletons exist so the first 30 minutes of a crisis go to investigation, not drafting.

Customer journey — ToV by stage

Five customer-journey stages, each mapped to the §13.5 ToV library rows that fit. When a writer is unsure which row to reach for, the journey stage tells them.

§14

Claims & Compliance

Functional and traditional-use categories are allowed, but must be claim-controlled, country-checked and context-aware. The rule is not to hide function — it is to avoid diagnosis, treatment, cure, prevention or guaranteed outcomes.

Claims ladder

Chinese wording control

Functional category system

The taxonomy used for product navigation, marketplace structure and customer-facing “Shop by need” surfaces. Three layers — primary categories, secondary needs, and the words we never put on a product page as a sales claim.

Disclaimer library

Before / After rewrites

Claims validator checklist

Run every piece of customer-facing copy through this six-step walkthrough before publishing. Stop at any step that returns Red.

Two-level certification wording

Certification claim sheet — Lark Base template

§15

Bilingual & International

English and Simplified Chinese are the working scripts. Traditional Chinese is locked to the master brand word 正補 and to the Medic Point legacy artwork 美麗寶. Bahasa Melayu and Traditional Chinese for HK / TW are starter scope — they will mature when first campaigns brief.

Chinese script — canonical rules

The brand handles three Chinese-script contexts. These are the rules a designer or copywriter follows, in order.

Bahasa Melayu — starter rules

Herbal Care does not ship Bahasa Melayu copy today, but Malaysian SME compliance and marketplace expectations make it inevitable. The rules below are starters: codify what is non-negotiable now, refine when the first BM-led campaign is briefed.

When BM appears

Brand-name preservation

Tone register

Bilingual co-setting examples

Status. Starter rules — refine when the first BM-led campaign is briefed. Owner: Brand Lead + designated BM editor (TBC).

§16

Reference Layouts by Mode

Fifteen compositions across the five modes. Each defines what leads, what supports and where proof sits — at near-final fidelity using the brand's actual type, colour and components.

8.1 Corporate / Standards

8.2 Consumer / Commerce

8.3 Legacy Trade

8.4 Utility Trade · HerbsMart

8.5 Luxury / Gift

§17

Web & UI

Web & UI

§18

Marketplace & E-commerce

Marketplace text rules

Per-area discipline for Shopee / Lazada / TikTok Shop product surfaces. Photography templates follow below; text wording leads.

Marketplace photography templates

Slot-to-pillar mapping. Pillar specs (lighting, crop, props, don'ts) live in §07 Photography pillars (P01–P08); this table says which pillar belongs in which marketplace slot.

Interim packaging guidance

§19

Email & Transactional

Email & transactional templates

The four highest-volume customer touchpoints — order confirmation, B2B quote, legacy receipt, dispatch notification. Each sits in its brand mode and reuses the existing voice and component vocabulary; designers build them, not improvise them.

Anatomy — applies to all four templates

Template 01 — B2C order confirmation

Mode. Consumer / Commerce. Voice row. §13.5 “Shopee description” + “Customer service delay.” CTA. Forest. Claim risk. Green.

Template 02 — OEM / B2B quote response

Mode. Corporate / Standards. Voice row. §13.5 “B2B quote intro” + “Supplier onboarding.” CTA. Forest. Claim risk. Green.

Template 03 — Medic Point legacy receipt

Mode. Legacy Trade. Voice row. §13.5 “Medic Point legacy note.” Visual. Minimal modernisation; Medic Red allowed in header rule but not in body. Claim risk. Green.

Template 04 — HerbsMart dispatch notification

Mode. Utility Trade. Voice row. §13.5 “HerbsMart email.” Visual. Tables, status chips, no decorative copy. Claim risk. Green.

§20

Data Visualisation

Data visualisation

B2B sells on spec sheets and trust. Charts, dense tables and certificate strips carry that trust visually. The palette, density and layout patterns below apply across PDF, web and printed catalogue.

Chart palette

Five tokens cover every chart Herbal Care produces — from a single-series line to a four-series small-multiple. No chart should reach for a sixth colour; if you need more than four series, switch to small multiples.

Table density

Three density tiers, picked by the surface and the reader's intent. A dashboard table is not a spec table; a spec table is not a hero stat.

Density tiers, side by side

Same dataset (four SKUs) rendered at all three densities. Pick the tier that matches the reader's intent — not the one that looks “cleanest” in isolation.

Certificate display pattern

Same layout for GMP, HACCP, MeSTI, Halal across PDF, web and packaging — a horizontal strip with logo, scope wording and validity. Consistency builds trust faster than embellishment.

Badge strip — rendered

The strip below is the canonical Herbal Care certification display. Same proportions, dividers and typography across PDF, web and packaging back panel. Below the md breakpoint the strip stacks vertically.

The mark blocks above stand in for the official certifier logos. In production, replace each <div class="cert-mark"> with the actual SVG logo from the certifier's brand kit, sized at 32 px tall on web. Never recolour or reflow the official mark.

Batch & spec data presentation

Numerical data in a Herbal Care document — batch numbers, weights, percentages, dates — must be readable as a column. The rules below apply to every spec sheet, COA, dispatch note and audit record.

Live chart — palette demonstration

A demonstration grouped bar chart using the §17 chart palette. Three series: Forest 700 (primary), Lime 500 (highlight), Honey 500 (premium / third only). Axis Ink 700; grid Stone 300.

SVG inline so it inherits brand tokens via currentColor / CSS variables. For interactive dashboards or PDFs with hundreds of charts, render through a charting library (Chart.js / D3) that accepts these tokens — never hard-code hex values.

§21

Pricing & Promotion

Pricing & promotional voice

The brand sells health foods at fair quality-driven prices. Promotional voice protects that positioning under discount pressure. Three rules govern every sale, festive promo and BNPL line.

Three rules

Approved promotional copy patterns

Mode-by-mode

Status. Starter rules drafted from §13.5 ToV library and §16.5 festive social poster. Refine after the next two festive campaigns ship.

§22

Brand Story & Philosophy

§22 governs the words behind the system: name etymology, canonical narrative, story pillars and the moodboard the brand commissions against.

Canonical narrative

Herbal Care began as a family trade built on supplying trusted traditional ingredients. Over decades, we learned that the real value is not in selling mystery and promises. It is in protecting quality, helping customers choose, and making standards visible.

The health food market has become louder, more confusing, and more claim-heavy. Herbal Care takes a different path: food-first, standards-led, and evidence-informed. We respect tradition, but we do not hide behind vague claims. We preserve legacy, but we improve the system.

We are building a long-term health food brand where families, operators, and buyers can understand what they are buying, why it matters, and how to use it responsibly.

Story pillars

Moodboard keywords

§23

Governance & Process

Brand request form

Every internal brand-asset request enters the workflow through this twelve-field form. It exists to capture context the SLA table needs to make a fast, correct call.

Approval workflow with SLAs

Vendor approval — what designers may & may not change

Designer / agency onboarding pack — 8 pages

The minimum-viable kit handed to any external designer or agency on day one. Each page is a single A4 / letter spread; together they cover everything an external partner needs to ship Herbal Care work without escalating every decision.

Exportable onboarding summary

The block below is the actual one-page condensed onboarding artefact — printable directly from this page using the Print onboarding pack control. Vendor receives this plus the .ai source link from §06.5; everything else is reachable from here.

Print onboarding pack  →   Reset print mode

§24

Templates & Checklists

Three checklists for the surfaces that ship most often. Use them as the floor for every design, marketplace and packaging release.

The two checklists below are interactive. Tick items as you audit a release; progress saves to this browser via localStorage so you can leave and return without losing state. Each checklist has its own slot; clearing one does not affect the other.

Pre-publish QA checklist

Marketplace product page checklist

§25

AI Knowledge Base & Productisation

The brand system is built to be retrieved by AI agents, not just read by humans. §25 documents the 57-chunk map, the deployable QA prompt and the live Dify deployment.

RAG chunk map (excerpt of 57)

Deployable AI Brand QA prompt — non-negotiable facts

JSON output schema

The deployed agent returns this literal structure. AI agents follow literal JSON skeletons more reliably than table descriptions; retrieved_chunks supports an audit trail of which chunks the agent used for each verdict.

{
  "overall_status": "GREEN | YELLOW | RED",
  "recommended_mode": "Corporate | Consumer | Legacy | Utility | Luxury | Mixed | Unknown",
  "issues": [
    {
      "severity": "low | medium | high",
      "category": "claim | colour | logo | typography | language | mode | certification | other",
      "original": "<exact phrase from input>",
      "problem": "<what's wrong and which chunk it violates, e.g. HC-CLAIM-001>",
      "recommended_fix": "<suggested replacement>"
    }
  ],
  "approved_elements": ["<what is already on-brand>"],
  "revised_copy": "<rewritten copy if applicable, else null>",
  "human_review_required": true,
  "review_owner": "Brand Lead | Claims Checker | Certification Owner | Management | None",
  "retrieved_chunks": ["HC-XXX-NNN"]
}

Few-shot examples

Auto-flag rules

Hard rules cost less inference and are more deterministic than few-shot pattern-matching. The deployed agent applies these before reasoning.

Stable principles for AI systems

Five principles that apply to every AI agent consuming Herbal Care content — chatbots, claims validators, copy generators, search agents. Unlike the non-negotiable facts above (which are brand specifics), these are interpretive instructions. They keep agents from drifting in tone, claim or scope.

Claims Validator — Deployed Dify Configuration

Live since 2026-04-30. Documents the as-built configuration so anyone reproducing or migrating the deployment has the full spec.

Future upgrade path (when budget allows)

• Switch index method from Economical to High Quality (semantic embedding) — requires OpenAI / Cohere / Voyage API key, ~$0.0005 initial embedding cost. Chunks file unchanged. One-click switch via Knowledge Base settings.
• Add Cloudflare Worker frontend if marketplace listing teams want a non-Dify UI.

Operational notes

Deployment Validation Log

The validation log doubles as a regression test fixture. If a future model change breaks brand QA accuracy, the log records the last known-good state. Re-run the §25 few-shot tests and confirm all pass before promoting any change to live (system prompt, model, knowledge base).

Initial validation: 2026-04-30

Notable: Test 3 went beyond the spelling-only fix and additionally surfaced Luxury-mode language improvements ("Premium Selection" phrasing per HC-BRAND-006) plus a Simplified Chinese localised variant ("Herbal Care 正補 尊享礼盒"). Higher-order brand reasoning beyond rote rule application.

Retraining SOP

The brand book changes faster than the AI agent's knowledge base. Without a retraining ritual, the agent's answers go stale silently — it confidently cites rules from an old version. The procedure below is the maintenance contract.

Retraining triggers

Procedure

Drift signals to watch

Owner. Retraining ritual sits with Brand Lead + AI Operations. The pair runs the procedure together; neither role alone is sufficient.

§26

House Style & Documentation Discipline

House style is the editorial discipline that keeps the brand book consistent across versions and authors. Versioning records what changed; modularisation plans how this single file scales; the eight house-style rules govern how every chapter is written.

Versioning discipline

Modularisation plan

The brand book lives as a single index.html + brand.css today. That is intentional: one source, no build step, instant browser open. It will not stay that way forever — size will eventually force a split. The criteria and approach below are the plan; do not split before the criteria fire.

Split triggers

Approach when triggered

Anti-patterns to avoid

House style — editorial discipline for this book

Eight rules govern the brand book itself. They mirror §13.1 Core voice attributes applied to internal documentation. Future authors and AI assistants editing this book follow them.

§27

Polish & Longevity

A brand system is only as alive as the rituals around it. §27 governs the annual review cadence and the employee primer that keep the discipline current.

Employee brand primer — eight rules

1. Herbal Care 正補 is a health food and botanicals brand, not a medicine brand.
2. We explain clearly: what the product is, how to use it, how it is graded and what it cannot promise.
3. Use Simplified Chinese for normal copy, but always write 正補 in Traditional Chinese.
4. Do not make disease, cure, treatment or guaranteed health claims.
5. If you mention GMP / HACCP / Halal / MeSTI / ISO, use approved wording only.
6. Use the approved brand colours, logo and fonts. Do not invent your own style.
7. When unsure, ask before publishing. It is cheaper to check than to correct a mistake.
8. Our standard is: no hype, no fear, no shortcuts.

Annual review cadence