Specs · v0.1 — for review

The WDS Object Framework

One model for naming, categorising and cataloguing every object in the design system — so the team that builds the components and the people who assemble pages share one language.

Status: v0.1 · for reviewReconciles: the build taxonomyScope: Taxonomy · naming · metadataAudience: design + build

Building & Authoring

Core model

The system is described two ways. They describe the same objects — and meet at the catalogue.

Building

Coding the system. Define Components, Elements, Foundations and Partials so they're reusable and re-skinnable per client.

Audience · the build team

Authoring

Assembling pages. Pick Blocks and Components from the catalogue and arrange them into a page.

Audience · page-builders

The full stack, top to bottom. Everything above the assembly line is assembled into pages; everything below is the build layer that supports it.

PageThe published output. What a visitor sees — assembled from Blocks.Result

BlockA drop-in page section you place and configure — "Event Grid", "Featured Banner", "Agenda". The unit of page-building.Author picks ★

ComponentA complete, self-contained object — Event Card, Replayer, Channel Card. Arrives inside a Block.Author · via Block

assembly line

ElementA reusable sub-piece shared across objects — Time Row, Date Stack, Speaker Row, Button. Built once, composed in.Build team

FoundationsThe Brand Pack: colour, type, spacing, icons. Shared once; never duplicated per object.Build team

PartialA core build primitive — the Blade mechanism objects are assembled from. As important as any other tier; the build team's day-to-day.Build team

Two surfaces, not one

Authoring catalogue (above the line): Blocks and Components — what a page-builder assembles.
Brand Pack (our public design system): Foundations, plus selected Elements — buttons, icons — plus Components, published as brand decisions. This site is it.
Surfacing is its own axis: tier is what an object is; Surface is where it's published (§04).
Partials are foundational — a critical build primitive and the build team's focus. They aren't shown in the authoring catalogue, but that's a question of surface, not importance.

Element, Component & Block

Three objects make up every page, and they nest — a piece, a whole object made of pieces, a page section made of objects.

ElementBuild team

The smallest reusable piece — one job, one slot, used across several objects. Built once; authors never place it directly.

ComponentAuthor · via Block

A complete, self-contained object with its own shell — built from Elements, and themeable on its own.

Page BlockAuthor picks ★

A page section — one or more Components arranged and configured for a slot. This is what an author drops onto a page.

Element⊂ Component⊂ Page Block→ Page — each is built from the one before it.

Note

Some Elements are published in the Brand Pack — our public design system. A Button (Element) and icons (Foundation) appear there as brand references, even though authors never place them on a page. That's the Surface axis (§04), not the tier.

Naming

Convention

Family → Concept → Variant — the convention the design file already half-uses, made explicit.

Tier| Family/ Concept/ Variant/ Mode

the object group·the named object in it·skin / size / state·LM / DM

Component| Event Card/ Featured/ —/ LM

One object = one identity across design, code and catalogue.

Every object is named once, and the name is agreed between Build and Authoring. The canonical name is the contract between the two systems; no object ships until both sides sign off on it.

Drift is already here

The design file says Event Card/Featured; the build code says event_featured_card — same object, two names.
Fix: family-first canonical naming, agreed jointly. Everything is named; every other form (code id, design path) derives from the one canonical name.

The design → build package

Template

Every object carries the same package, grouped along four axes — how it's catalogued, what content it carries, how it's styled, and how it's built. Define all four and the object slots cleanly into the catalogue, its content, the Brand Pack and the build. Examples below are for Event Card / Featured.

Cataloguinghow it's identified, organised & offered
Tier	Block / Component / Element.	Component
Family / Concept / Variant	The naming triad (§03).	Events / Featured / — (LM + DM)
Canonical name + IDs	Name · design path · catalogue id · code id.	Events/Featured/LM · event-card-featured · event_featured_card
Status	Live · Planned · Potential · Gap-spec.	Live · LM + DM
Surface	Where it's published — Authoring · Brand Pack · Build-only.	Authoring + Brand Pack
Purpose	One plain-English line.	An event card with a full-bleed image behind a legibility tint.
Where used	Which page slots / page types.	Event listings · featured rails · channel highlights.
Configurable options	What the author can set.	Image · title · venue · time · badge state · footnote link

Content · Datawhat it binds, and how it behaves on it
Source entity	The content object it draws from.	Event (+ Speaker)
Data points	Fields it binds — required (•) / optional (○).	title • · secondary ○ · time ○ · footnote ○ · image ○ · live flag •
Data rules	Behaviour on presence / absence / count.	No image → Basic surface · no time → hide Time Row (showTimeRow) · multi-day → date range

Design System · Brand Packthe styling decisions
Styling tokens	Text · colour · geometry tokens consumed (never raw hex).	Headline / md · Callout / lg · Primary 1 · Accent · card radius · bottom-flush bar
Interaction states	Hover / active visual states.	Resting · Rollover (surface lift) · Active link

Buildinghow it's assembled in code
Composed of	Child Elements it instances.	Date Stack · Time Row · Copy Stack · Footnote · Overlay Link · Live Badge · Featured Image
Partials	The build primitives it's rendered from.	Orchestrator blade + element partials + tracking-attrs
Dev reference	Bridge · Blade · SCSS · preview fixture.	Bridge: yes · wds-components/event-featured-card/ · preview fixture

Why four axes

These are the principles every object must answer: how it's catalogued, what content it carries, how it's styled, and how it's built. Miss one and the object can't be found, fed, themed, or shipped — defining all four is what makes the system scale.

How it maps to the build

Reconciliation

The authoring tiers line up against the build taxonomy — so neither side has to translate.

Authoring tier	Build tier	Assembled?	Surfaced in	Note
Page	Route / view	No	—	The assembled output.
Block	Placed component(s)	Yes — primary	Authoring catalogue	The new top tier — an arrangement, not a new code object.
Component	Component	Yes	Authoring + Brand Pack	Own theme namespace + preview fixture.
Element	Element	No	Build · selected → Brand Pack	Buttons, icons surface as brand references.
Foundations	Platform	No	Brand Pack	Colour, type, icons, logo.
—	Partial	No	Build layer	A core build primitive — the build team's focus.

What's next

Three moves turn this model into a working catalogue.

Sequence

Agree the model — Block as the top authoring tier, the Surface axis, and family-first naming agreed jointly between Build and Authoring.
Lock the four axes — finalise the package fields so every object is described the same way: Cataloguing · Content · Brand Pack · Building.
Seed the catalogue — re-cast the existing objects (Cards, Replayer, Elements) into the package, flag which Elements surface in the Brand Pack (buttons, icons), and name the first Blocks.

WDS Object Framework — Spec v0.1
Adds the authoring layer (Blocks, the catalogue, naming, the design package) on top of the build taxonomy and reconciles the two into one model with a single source of truth. Draft — scope is taxonomy, naming and metadata; spacing, shadows and radii are out of scope for now.