Token Families
Every token in this system belongs to exactly one family — a
pillar / layer / family grouping, e.g.
paper / semantic / financial-report-layout. This page names the taxonomy so
a producer archive can find the right family before guessing a token name, instead of
drafting a near-duplicate because the real one wasn't easy to find.
Shape: pillar / layer / family
A token's canonical id is its pillar and its full DTCG
path, joined verbatim — no translation layer between the id, the CSS custom property,
and what get_token matches on (see
MCP & machine API). A family is the
grouping one level up: every token that shares the same pillar, layer, and top-level
name.
Pillar
The top-level tier: primitive, theme, paper,
writing.
Layer
Only paper and writing genuinely nest under a
primitive/semantic wrapper before their real groups start — so
only those two pillars carry a layer. Every other pillar's layer is null;
its first path segment is the family directly.
Family
The named group itself — a document family like
financial-report-layout, a craft group like rhythm, or a
primitive category like color. Every leaf token in a family shares the
same id prefix.
Worked example: the token
--ps-paper-semantic-financial-report-layout-header-rule has pillar
paper, layer semantic, family
financial-report-layout — readable directly off the id string, since the
id is the pillar/layer/family path with no re-casing or re-delimiting.
Four pillars
Each row is a real pillar in the current export, not an aspirational list — counts are live, same source as the stat panel above.
| Pillar | Layer | What it holds | Example families |
|---|---|---|---|
primitive | — | Raw, tenant-neutral values: color, spacing, typography, motion, borders, viewport, focus, duration. | color (60), typography (14), size (13) |
theme | — | PointSav's own default/reference theme — semantic-role mappings onto primitives, plus a dark-mode variant. The vendor's reference theme, not a tenant fork (see the pillar note below). | semantic (53), dark (28), accessibility (5) |
paper | primitive / semantic | Print/document-formatting substrate — page geometry, rule weights, type scales, and one semantic family per document register (legal agreements, financial reports, PDF-binder navigation, Mexico FIBRA trust/prospectus, org-chart print diagrams, …). | mx-fibra-prospectus (49), legal-subscription-agreement (30), financial-report-layout (25) |
writing | primitive / semantic | Prose-governance tokens — voice, rhythm, casing, register scale, disclaimer templates, and named content patterns for a specific document family. | register (7), rhythm (7), pattern (4) |
theme pillar holds PointSav's own reference theme only — it is not
a multi-tenant fork target. An adopting tenant's own brand-specific token values (e.g.
Woodfine's palette) live in that tenant's own media-assets repo, layered on top via CSS
custom-property override, not inside this pillar. See
.agent/rules/design-tokens.md in the project-design archive for the full
rationale.
paper.primitive.color.org-chart-role-
warm-gray-* / paper.semantic.org-chart.role-warm-gray-*, alongside
the rest of the org-chart document family's tokens. The retired pillars' names embedded
a third-party product's brand directly into shipped CSS custom-property names, which
this registry no longer does anywhere.
Finding the right family before drafting a new one
The failure mode this taxonomy exists to prevent: a producer archive can't find an existing family, assumes one doesn't exist, and drafts a near-duplicate under a new name. Two checks, in order:
1. Is it a document-family variation?
A new compliance document, print register, or legal instrument almost always composes
existing paper.primitive.* and adds one new
paper.semantic.<family>.* group — it very rarely needs new primitives.
Check the Paper families table above and on Tokens — Paper
tier before assuming none of the ten existing document families are close
enough to extend from.
2. Is it a genuinely new value, or a tenant's brand fork?
A literal color/size/type value that's reusable across any adopting tenant belongs in
primitive or a Paper/Writing family. A value that encodes one specific
tenant's brand identity does not belong in this repository at all — see the pillar note
above.
list_token_families(pillar?)
The machine-readable form of this page. Returns every
family — the same rows as the table above — as JSON, optionally filtered to one pillar,
sourced from the same generated token-families.json registry
get_token and this page both read. See
MCP & machine API for the full tool list and
call shape.
[
{ "pillar": "paper", "layer": "semantic", "family": "financial-report-layout", "member_count": 25 }
// … 44 more
]Important Information
Design System disclosure
This site provides open-source design tokens, documentation, and self-hostable software published by Woodfine Capital Projects Inc. Information here is for general reference only and does not constitute an offer, warranty, or a guarantee of fitness for any particular purpose. Statements regarding planned, intended, or targeted future features are forward-looking and subject to change without notice; they are not undertaken to be updated except as required by law.