WCNGUIDELINES & DOCS MAP08 · GOVERNANCE → B
← 08 · GOVERNANCE
Guidelines & docs · B
One source
of truth.
of truth.
Documentation is how the brand scales past the people who made it. This cluster is the brand book itself, the component docs, and the discipline that keeps them current. Tap any card to open its spec.
BOOKCOMPONENTS
SSOTDO / DON’T
CHANGELOG70%
DOCS COVERAGE
3 shipped
2 in progress
0 planned
08B01
Brand book
DONE
This system is the brand book — not a PDF on a drive, but a living, navigable site. This page explains its scope, how it’s structured, and how to read it.
SCOPEWhole system
STRUCTURE11 chapters
FORMATWeb · living
READTop-down
“
B01.1 · SCOPE
Everything, in one place.
From strategy to digital to governance, the book covers the whole brand. If a decision about WCN exists, it lives here — there is no second source.
FROMStrategy
TOGovernance
ONESource
GAPSTracked openly
B01.2 · STRUCTURE
Eleven chapters.
Numbered 00–11, each chapter is a map of clusters, each cluster a set of detail pages. The numbering is the navigation — every page knows its address.
CHAPTERS00–11
MAPPer chapter
DETAILPer cluster
ADDRESSNumbered
B01.3 · LIVING FORMAT
Always current.
Because it’s a site, the book is never out of date the way a printed guide is. Changes ship continuously and are logged in the changelog.
MEDIUMWeb
UPDATESContinuous
STALENever
LOGChangelog
B01.4 · HOW TO READ
Start at the portal.
New readers start at the portal and follow the numbers. Returning readers jump straight to a chapter. Every page links up to its map and home to the index.
STARTPortal
FOLLOWThe numbers
JUMPBy chapter
HOMEAlways linked
DON'T
×
Don't export to PDF — A frozen copy is instantly stale.
×
Don't fork chapters — One home, no copies.
×
Don't skip the numbering — The address is the navigation.
×
Don't hide the gaps — Track what’s missing in the open.
“A brand book that can’t change is a brand book that won’t be read.”
08B02
Component docs
DONE
A component nobody understands gets rebuilt. This is the standard for documenting each one — its anatomy, props, states, and the examples that show it working.
PERComponent
INCLUDESProps · states
EXAMPLESLive
SOURCEDesign system
B02.1 · ANATOMY
Name the parts.
Each doc opens with the component’s anatomy — the named regions and what they’re for — so everyone uses the same words for the same parts.
REGIONSNamed
PURPOSEPer region
SHAREDVocabulary
DIAGRAMLabelled
B02.2 · PROPS & API
What you can change.
Every prop is listed with type, default and effect. If it can’t be changed, that’s documented too — constraints are as useful as options.
LISTAll props
EACHType · default
EFFECTDescribed
LIMITSStated
B02.3 · STATES
Every condition.
Default, hover, active, disabled, loading, error, empty. A component isn’t documented until every state it can reach is shown.
SHOWNAll states
INCLUDESEmpty · error
LOADINGYes
RULENo hidden states
B02.4 · LIVE EXAMPLES
Working, not pictured.
Examples are live and copyable, not screenshots. Seeing the real component — and lifting its code — is what makes documentation get used.
TYPELive
COPYCode shown
NOTScreenshots
HOMEDesign system
DON'T
×
Don't ship undocumented — No doc, no release.
×
Don't hide states — Empty and error count.
×
Don't use screenshots — Live, copyable examples only.
×
Don't let docs drift — Update with the component, not later.
“Undocumented is unfinished.”
08B03
Single source
DONE
When the same answer lives in three places, two of them are wrong. The single-source rule names one canonical home for every brand decision and forbids the copies.
HOMEOne URL
MIRRORSRead-only
FORKSNone
SYNCAutomated
B03.1 · THE HOME
One address.
Each kind of truth — tokens, components, copy — has exactly one canonical location. That location is linked everywhere; it is never reproduced.
EACHOne location
LINKEDEverywhere
REPRODUCEDNever
KNOWNPublished
B03.2 · MIRRORS
Read, don’t edit.
Where a copy must exist — a slide, a partner doc — it is clearly a read-only mirror with a link back, never an editable second master.
MIRRORRead-only
MARKEDAs copy
LINKBack to home
EDITAt source only
B03.3 · NO FORKS
Resist the copy.
Forking feels faster and costs more later. The rule is blunt: no forks. If the source doesn’t fit, fix the source — don’t branch around it.
FORKSForbidden
INSTEADFix source
WHYDrift compounds
ENFORCEIn review
B03.4 · SYNC
Push, don’t paste.
Where systems need the same value — code and design tokens — it’s synced automatically from the source, not hand-copied. Manual sync is where truth diverges.
METHODAutomated
FROMThe source
MANUALAvoided
VALUESAlways match
DON'T
×
Don't keep two masters — One home, the rest mirror.
×
Don't hand-copy tokens — Sync from source.
×
Don't fork to move fast — Fix the source instead.
×
Don't leave mirrors unmarked — Label copies, link back.
“Two sources of truth means none.”
08B04
Do / don’t library
WIP
Rules are abstract; examples are not. The do/don’t library pairs the correct use with the common mistake, side by side, so the right call is obvious at a glance.
FORMATDo / don’t pairs
COVERAGEAll systems
SEARCHTagged
GROWSPer issue
A
B
C
D
B04.1 · THE FORMAT
Two panels.
Each entry is a pair: the do on the left, the don’t on the right, with one line of why. No long prose — the contrast carries the lesson.
LEFTDo
RIGHTDon’t
WHYOne line
PROSEMinimal
B04.2 · COVERAGE
Across the system.
Logo, colour, type, voice, motion — every system contributes pairs. The library is the fast index into the rules people get wrong most.
SYSTEMSAll
SOURCEFrom detail pages
FOCUSCommon errors
INDEXFast
B04.3 · SEARCH
Find it fast.
Every pair is tagged by system and topic so a contributor can find the relevant rule in seconds, mid-task, without reading a chapter.
TAGSSystem · topic
SPEEDSeconds
CONTEXTMid-task
NOChapter reading
B04.4 · IT GROWS
Learns from mistakes.
When the same error recurs in review, it becomes a new pair. The library is a record of what the brand has learned to get wrong less often.
TRIGGERRecurring error
ADDSA pair
OWNERSteward
RESULTFewer repeats
DON'T
×
Don't write essays — Show the pair, one line of why.
×
Don't skip the don’t — The wrong example is the lesson.
×
Don't leave it untagged — Unsearchable is unused.
×
Don't freeze it — Add a pair when errors recur.
“People copy examples long after they forget rules.”
08B05
Changelog
WIP
A living system changes — and people need to trust those changes. The changelog records every update; release notes explain the ones that matter and how to adopt them.
LOGEvery change
NOTESPer release
MIGRATIONTips included
FEEDSubscribable
B05.1 · THE CHANGELOG
Every change.
A dated, append-only list of what changed — token, component, rule. Terse by design; the changelog is the system’s memory, not its marketing.
ENTRIESDated
SCOPEAll changes
STYLETerse
ORDERAppend-only
B05.2 · RELEASE NOTES
The ones that matter.
Release notes summarise meaningful changes in plain language — what’s new, what’s different, what to do about it. One note per release, written for humans.
WHENPer release
VOICEPlain
COVERSNew · changed
AUDIENCEEveryone
B05.3 · VERSIONING
Semantic, predictable.
The system uses major.minor.patch. Breaking changes bump major and never ship quietly — predictability is what lets teams depend on the system.
SCHEMEmajor.minor.patch
BREAKINGMajor only
QUIETNever
DEPENDSafely
B05.4 · MIGRATION
How to move.
When something breaks, the notes include a migration path — before, after, and the steps between. A breaking change without a migration is a defect.
INCLUDESBefore · after
STEPSListed
NO PATHA defect
SUPPORTWindow given
DON'T
×
Don't ship silent breaks — Breaking changes are announced.
×
Don't skip migration — Before, after, steps.
×
Don't market in the log — Terse and factual.
×
Don't version randomly — Semantic, predictable.
“People adopt change they can see coming.”
Near complete
The brand, written down.
The book, component docs and single-source rule are shipped. The do/don’t library and changelog are filling in — the strongest-documented cluster after the visual system.
WCN Guidelines & Docs Map · 5 topics · B01–B0508 · GOVERNANCE · B · v1.0