UJG / Editor's Draft /
W3C Community Group Draft Report

Design System

draft

Status of this Document

This report was published by the User Journal Graph Community Group . It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups .

Last Update
2026-07-13
Editors
  • Seva Dolgopolov
Group
User Journal Graph Community Group
Repository
View Source
License
W3C-Software-and-Document

1. Overview

This optional module defines a graph-native vocabulary for describing how design-system artifacts realize Surface resources.

The module is intentionally second-level. It depends on the Surface layer as the bridge between Graph topology and user-facing materialization. Graph nodes do not point to design-system artifacts, and Surface resources remain design-system-agnostic.

The DesignSystem module introduces SurfaceRealization as the design-system-side bridge. A SurfaceRealization references exactly one Surface and then identifies either a Component or a Template as the primary realization. When a template is used, the realization may reference SlotBinding nodes that fill template-declared Slot nodes.

This module is optional. It annotates the shared graph with interoperable design-system realization resources, but it does not change graph topology, traversal rules, Surface attachment rules, import resolution, rendering behavior, or runtime semantics.

2. Terminology

  • DesignSystem: A graph-native catalog or scope for design-system artifacts available to realize surfaces.

  • TokenSource: An addressable token source, package, manifest, or token set. The internal token format is external to UJG.

  • Component: An addressable design-system artifact that can realize a surface or fill a slot.

  • Template: A reusable design-system artifact that declares slots.

  • Slot: An addressable slot declaration owned by or referenced from a template.

  • SurfaceRealization: A design-system-side node that references one surface and describes its primary component or template realization.

  • SlotBinding: A realization-local binding from a template slot to one presentation target.

3. TokenSource

A TokenSource identifies a token source, token package, token manifest, or token set. The internal token format is external to UJG.

classDiagram
  class TokenSource {
    id
  }

Example JSON node:

json 
{
  "@type": "TokenSource",
  "@id": "urn:ujg:tokens:brand"
}
{
  "@type": "TokenSource",
  "@id": "urn:ujg:tokens:brand"
}

4. Component

A Component is an addressable design-system artifact that can directly realize a Surface or fill a template slot.

classDiagram
  class Component {
    id
  }

Example JSON node:

json 
{
  "@type": "Component",
  "@id": "urn:ujg:component:CheckoutForm"
}
{
  "@type": "Component",
  "@id": "urn:ujg:component:CheckoutForm"
}

5. Slot

A Slot is an addressable slot declaration used by a Template.

classDiagram
  class Slot {
    id
  }

Example JSON node:

json 
{
  "@type": "Slot",
  "@id": "urn:ujg:slot:checkout-main"
}
{
  "@type": "Slot",
  "@id": "urn:ujg:slot:checkout-main"
}

6. Template

A Template is a reusable design-system artifact that declares zero or more Slots.

classDiagram
  class Slot
  class Template {
    id
    slotRefs
  }
  Template --> "0..*" Slot : slotRefs

Example JSON node:

json 
{
  "@type": "Template",
  "@id": "urn:ujg:template:checkout-layout",
  "slotRefs": ["urn:ujg:slot:checkout-main"]
}
{
  "@type": "Template",
  "@id": "urn:ujg:template:checkout-layout",
  "slotRefs": ["urn:ujg:slot:checkout-main"]
}

7. SlotBinding

A SlotBinding fills one declared Slot with exactly one target: either a Surface or a Component.

classDiagram
  class Slot
  class Surface
  class Component
  class SlotBinding {
    id
    slotRef
    targetSurfaceRef
    targetComponentRef
  }
  SlotBinding --> Slot : slotRef
  SlotBinding --> Surface : targetSurfaceRef
  SlotBinding --> Component : targetComponentRef

Example JSON node:

json 
{
  "@type": "SlotBinding",
  "@id": "urn:ujg:slot-binding:checkout-main",
  "slotRef": "urn:ujg:slot:checkout-main",
  "targetSurfaceRef": "urn:ujg:surface:checkout-form"
}
{
  "@type": "SlotBinding",
  "@id": "urn:ujg:slot-binding:checkout-main",
  "slotRef": "urn:ujg:slot:checkout-main",
  "targetSurfaceRef": "urn:ujg:surface:checkout-form"
}

8. SurfaceRealization

A SurfaceRealization links one Surface to its primary design-system realization, either a Component or a Template. Template-backed realizations may also reference SlotBindings.

classDiagram
  class Surface
  class Component
  class Template
  class SlotBinding
  class SurfaceRealization {
    id
    surfaceRef
    componentRef
    templateRef
    slotBindingRefs
  }
  SurfaceRealization --> Surface : surfaceRef
  SurfaceRealization --> Component : componentRef
  SurfaceRealization --> Template : templateRef
  SurfaceRealization --> "0..*" SlotBinding : slotBindingRefs

Example JSON node:

json 
{
  "@type": "SurfaceRealization",
  "@id": "urn:ujg:realization:checkout-form",
  "surfaceRef": "urn:ujg:surface:checkout-form",
  "componentRef": "urn:ujg:component:CheckoutForm"
}
{
  "@type": "SurfaceRealization",
  "@id": "urn:ujg:realization:checkout-form",
  "surfaceRef": "urn:ujg:surface:checkout-form",
  "componentRef": "urn:ujg:component:CheckoutForm"
}

9. DesignSystem

A DesignSystem is a catalog or scope for token sources, components, templates, and surface realizations.

classDiagram
  class TokenSource
  class Component
  class Template
  class SurfaceRealization
  class DesignSystem {
    id
    tokenSourceRefs
    componentRefs
    templateRefs
    surfaceRealizationRefs
  }
  DesignSystem --> "0..*" TokenSource : tokenSourceRefs
  DesignSystem --> "0..*" Component : componentRefs
  DesignSystem --> "0..*" Template : templateRefs
  DesignSystem --> "0..*" SurfaceRealization : surfaceRealizationRefs

Example JSON node:

json 
{
  "@type": "DesignSystem",
  "@id": "urn:ujg:design-system:shop",
  "tokenSourceRefs": ["urn:ujg:tokens:brand"],
  "componentRefs": ["urn:ujg:component:CheckoutForm"],
  "templateRefs": ["urn:ujg:template:checkout-layout"],
  "surfaceRealizationRefs": ["urn:ujg:realization:checkout-form"]
}
{
  "@type": "DesignSystem",
  "@id": "urn:ujg:design-system:shop",
  "tokenSourceRefs": ["urn:ujg:tokens:brand"],
  "componentRefs": ["urn:ujg:component:CheckoutForm"],
  "templateRefs": ["urn:ujg:template:checkout-layout"],
  "surfaceRealizationRefs": ["urn:ujg:realization:checkout-form"]
}

10. Realization Model

A Surface is a design-system-agnostic materialized boundary for exactly one supported Graph node. Surface defines the relation from Surface to that supported Graph node. Graph nodes do not point to design-system artifacts or depend on Surface. This module does not add properties to Surface and does not make Surface depend on design-system artifacts.

Design-system realization is expressed by SurfaceRealization nodes:

  • A DesignSystem MAY reference SurfaceRealization nodes through surfaceRealizationRefs.

  • A SurfaceRealization MUST reference exactly one Surface.

  • A SurfaceRealization MUST reference exactly one primary realization, either componentRef or templateRef.

  • A Template MAY declare Slot nodes through slotRefs.

  • A template-backed SurfaceRealization MAY reference SlotBinding nodes through slotBindingRefs.

  • A SlotBinding MUST reference exactly one Slot and exactly one target.

This shape allows multiple design systems to realize the same surface independently without changing the surface or assigning multiple surfaces to the same supported Graph node.

11. DesignSystem Catalog

A DesignSystem groups design-system artifacts and realizations available in a design-system context. It is not a renderer and does not define component internals, layout rules, or token syntax.

The catalog properties are:

  • tokenSourceRefs: references zero or more TokenSource nodes.

  • componentRefs: references zero or more Component nodes.

  • templateRefs: references zero or more Template nodes.

  • surfaceRealizationRefs: references zero or more SurfaceRealization nodes.

TokenSource identifies a token source, token package, token manifest, or token set. Individual token names, token paths, token groups, token values, aliases, and inheritance rules are outside this module.

12. Templates And Slots

A Template declares reusable slots with slotRefs. A template MUST NOT hard-code concrete surfaces, components, transitions, or outgoing transitions into those slots.

A SurfaceRealization that uses a Template references SlotBinding nodes. Each SlotBinding references one declared slot and one target.

Allowed slot binding targets are:

  • targetSurfaceRef

  • targetComponentRef

When a SlotBinding targets a Surface, the target surface is composed into the slot for presentation purposes only. The binding MUST NOT imply graph traversal, state activation, transition validity, composite-state containment, execution order, or lifecycle semantics. A renderer, MCP server, skill, or design-system resolver MAY resolve the graph-level subject associated with a target surface through the Surface layer.

If a transition, outgoing transition, or outgoing-transition group affordance belongs in a slot, model a Surface that references that Graph node through the Surface layer and target that surface with targetSurfaceRef.

13. Normative Artifacts

This module is published through the following artifacts:

  • design-system.ttl: ontology, published at https://ujg.specs.openuji.org/ed/ns/design-system

  • design-system.context.jsonld: JSON-LD term mappings, published at https://ujg.specs.openuji.org/ed/ns/design-system.context.jsonld

  • design-system.shape.ttl: SHACL validation rules, published at https://ujg.specs.openuji.org/ed/ns/design-system.shape

Examples in this page compose the Core, Graph, Surface, and Design System contexts explicitly.

Non-goals:

  • This module does not define component implementation APIs, component props, component variants, or component lifecycle.

  • This module does not define layout algorithms, rendering engines, framework adapters, responsive behavior, hydration behavior, or platform-specific UI behavior.

  • This module does not define design-token syntax, token inheritance, token value resolution, or token path semantics.

  • This module does not define accessibility implementation rules.

  • This module does not introduce graph traversal, state activation, transition validity, composite-state containment, execution order, or lifecycle semantics.

13.1. Ontology

The normative DesignSystem ontology is defined below and is published at https://ujg.specs.openuji.org/ed/ns/design-system. It is the authoritative structural definition for the classes and properties declared by this module.

13.2. JSON-LD Context

The normative DesignSystem JSON-LD context is defined below and is published at https://ujg.specs.openuji.org/ed/ns/design-system.context.jsonld. It provides compact JSON-LD term mappings and coercions for DesignSystem-specific properties and classes.

Surface uses graphNodeRef for graph-node attachment. This module keeps a separate, type-scoped surfaceRef on SurfaceRealization, where it means realization-to-Surface. Surface also defines surfaceRef on SurfaceInstance, where it means surface-instance-to-Surface. Design System realization and slot-binding references continue to target stable Surface nodes, not SurfaceInstance nodes.

13.3. Validation

The normative DesignSystem SHACL shape is defined below and is published at https://ujg.specs.openuji.org/ed/ns/design-system.shape. It is the authoritative validation artifact for DesignSystem structural constraints.

The rules below define the remaining module semantics beyond the structural constraints captured by the SHACL shape.

  1. Surface purity: DesignSystem properties MUST NOT change Surface attachment semantics or make a Surface depend on design-system artifacts.

  2. Realization bridge: A SurfaceRealization MUST reference exactly one Surface.

  3. Primary realization: A SurfaceRealization MUST reference exactly one primary realization, either a Component or a Template.

  4. Template-only bindings: slotBindingRefs MUST be used only by a SurfaceRealization that references a Template.

  5. Slot declaration vs binding: Template slot references are declarations. SurfaceRealization slot bindings are concrete assembly for that realization.

  6. Single binding target: A SlotBinding MUST reference exactly one target, either a Surface or a Component.

  7. Presentation only: A slot binding to a surface MUST NOT imply graph traversal, state activation, transition validity, composite-state containment, execution order, or lifecycle semantics.

  8. Graceful degradation: A consumer that does not implement this module MAY ignore DesignSystem semantics, but it SHOULD preserve recognized JSON-LD data during read-transform-write when possible.

  9. Private details: Component internals, token syntax, framework adapters, render plans, and platform-specific behavior SHOULD remain outside this module unless a future module defines them as interoperable vocabulary.

14. MCP And Tooling Resolution

MCP servers, skills, AI tooling, design-system resolvers, and renderers MAY use referenced node IDs plus active graph context to fetch implementation details. Those details can include framework components, source files, Storybook entries, token files, runtime render plans, or platform adapters.

This module intentionally standardizes only the graph-native references needed for interoperability. It does not duplicate design-system implementation catalogs or renderer configuration.

15. Relationship To Core Extensions

Core extensions remains available for vendor-private, non-interoperable payloads. Component, template, slot, slot-binding, surface-realization, and token-source relationships intended for interoperability SHOULD use this module instead of opaque extension payloads.

16. Examples

16.1. Example A: Surface Without Realization

This example assigns a state to a surface. It does not declare any design-system realization.

16.2. Example B: Component Realization

The surface remains unchanged. The design system owns the realization node that points to the surface.

16.3. Example C: Template Realization

The template declares slots. The realization binds those slots for this surface.

16.4. Example D: Composite Surface With Child Surfaces

The composite state's surface is realized as a shell. Child containment comes from the subjourney referenced by subjourneyId. The child surfaces are placed into slots for presentation only; Graph remains the source of containment and traversal semantics.

16.5. Example E: Multiple Design Systems

The same surface can be realized by several design systems. The surface identity remains stable.