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.
Building & Authoring
Core modelThe system is described two ways. They describe the same objects — and meet at the catalogue.
Coding the system. Define Components, Elements, Foundations and Partials so they're reusable and re-skinnable per client.
Audience · the build teamAssembling pages. Pick Blocks and Components from the catalogue and arrange them into a page.
Audience · page-buildersThe full stack, top to bottom — the Page frame (Chrome), the content tiers that nest inside it, and the build layer beneath the assembly line.
- 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.
- 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.
Page chrome
Page-levelA Page is a frame around content. The frame is Chrome: the persistent shell (the App Bar and the Footer). What it wraps is Content, the nesting ladder (§03). Chrome sits alongside the content tiers; it is not a rung on the ladder.
Section, Block, Component & Element
The content tiers nest, largest to smallest — a Page breaks into titled Sections, a Section groups Blocks, a Block arranges Components, and a Component is built from Elements.
A page section — one or more Components arranged and configured for a slot. This is what an author drops onto a page.
A complete, self-contained object with its own shell — built from Elements, and themeable on its own.
The smallest reusable piece — one job, one slot, used across several objects. Built once; authors never place it directly.
- 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, not the tier.
Naming
ConventionA name is a path through the catalogue: Family → Bucket → Group → Variant. The component's id derives from that path, agreed jointly between Build and Authoring.
- Container spans abbreviate — 4c · 5050 · fw. The human path keeps the descriptive group label ("Foreseeable"); the id uses the code (4c).
- The base composition is spelled out — essentials, not ee.
- Embedded families are spelled out — speakers · sponsors · photos · video.
- Span is in the id; size is not. The Group segment carries the container span (4c · 5050 · fw — the footprint). Size (density · S/M/L) is a parameter on the component, like mode — addressable for overrides, never an id segment.
The axes the name does not carry — each lives on its own axis:
| Axis | What it is | Examples |
|---|---|---|
| Name | The path. Fixed — one per component; carries the span (Group). | Events → Cards → Foreseeable (4C) → Essentials + Media + Speakers |
| State | Facts the data carries. Select or modify rendering; never in the name. | live · replay |
| Setting | Configured per use, not built in. | feed · placement · layout · spotlight · field visibility |
| Parameter | Component inputs set per instance, addressable for overrides. | mode (LM/DM) · size (S/M/L density) |
- One object = one identity across design, code and catalogue. Every object is named once, and the path is the contract between Build and Authoring — no object ships until both sides sign off.
- The design file says Event Card/Featured; older build code says event_featured_card — same object, two names. Fix: one canonical path, the id derived from it (event-card-4c-essentials-media-speakers), so the two systems can't drift.
What's next
Three moves turn this model into a worked catalogue.
- Work the Events family as the template — five buckets (Heros · Banners · Cards · Listings · Backchannel), each declaring its one grouping axis; name the roster.
- Extend to the sibling families — Channels · Speakers · Sponsors · Themes get the same bucket page; confirm per family which buckets earn a place.
- Fill each component's contract in CoWork — catalogue id, content, Brand Pack tokens and build, per component, all derived from its path.
Splits Page chrome (App Bar · Footer) from the content nesting ladder (Section → Block → Component → Element), and names every object as a path — Family → Bucket → Group → Variant — from which the id derives. Each bucket declares one grouping axis. Draft — scope is page chrome, tiers and naming; spacing, shadows and radii are out of scope for now.