ujg-ed-design-system-modeling

name	ujg-ed-design-system-modeling
description	Generate, review, correct, and reason about Design System Modeling in User Journey Graph JSON-LD for the Editor's Draft. Use when the task is scoped to Design System module semantics and its relationship to Graph and Surface or when whole-document modeling crosses this module boundary.

UJG ED Design System Modeling

Skill tree context

Target: Editor's Draft Public spec URL: https://ujg.specs.openuji.org/ed Scope: Design System module semantics and its relationship to Graph and Surface Module scope: modules/design-system

Related generated skills:

• ujg-ed-modeling: whole UJG document modeling across Core, Graph, Surface and Experience, Runtime, Mapping, Metrics, Localization, Observability, Experience Annotation, and optional modules
• ujg-ed-core-modeling: Core module document containers, imports, top-level nodes, and extensions
• ujg-ed-graph-modeling: Graph module topology, journeys, states, transitions, exits, outgoing navigation, and indexes

When the task crosses module boundaries, read references/related-skills.md and references/skill-tree.json before continuing.

Source of truth

Use the active Editor's Draft unless the user explicitly asks for a dated snapshot:

https://ujg.specs.openuji.org/ed/modules/design-system

Generate only terms defined by the active ED Design System and Surface contexts unless the user explicitly requests an extension.

Scope

Design System describes how design-system artifacts realize Surface resources.

Correct layer order:

Surface -> graphNodeRef -> supported Graph node
SurfaceRealization -> surfaceRef + componentRef/templateRef
DesignSystem -> componentRefs/templateRefs/tokenSourceRefs/surfaceRealizationRefs

Graph defines topology. Surface defines materialization boundaries and points back to supported Graph nodes. Design System realizes surfaces.

Required contexts

When using Design System terms, include the Surface and Design System contexts:

[
  "https://ujg.specs.openuji.org/ed/ns/context.jsonld",
  "https://ujg.specs.openuji.org/ed/ns/surface.context.jsonld",
  "https://ujg.specs.openuji.org/ed/ns/design-system.context.jsonld"
]

Vocabulary

Use only these Design System classes:

DesignSystem
TokenSource
Component
Template
Slot
SurfaceRealization
SlotBinding

Use only these common Design System properties:

tokenSourceRefs
componentRefs
templateRefs
surfaceRealizationRefs
surfaceRef
componentRef
templateRef
slotRefs
slotBindingRefs
slotRef
targetSurfaceRef
targetComponentRef

When modeling Surface nodes themselves, use Surface graphNodeRef to point to the Graph node the surface exposes. Design System surfaceRef belongs to SurfaceRealization and points to stable Surface; Surface also uses surfaceRef on SurfaceInstance for runtime occurrences.

Do not invent:

UIView
viewRef
themeRef
variant
slots
tokenRefs
props
componentName
cssClass
route
url
action
transitionRef
outgoingTransitionRef

Binding rule

Graph nodes must not point directly to components, templates, token sources, design-system variants, props, or registry items.

Correct:

{
  "@type": "State",
  "@id": "urn:example:state:registration-form",
  "label": "Registration form"
}

Then assign and realize the surface:

{
  "@type": "Surface",
  "@id": "urn:example:surface:registration-form",
  "graphNodeRef": "urn:example:state:registration-form"
},
{
  "@type": "Component",
  "@id": "urn:example:component:RegistrationForm"
},
{
  "@type": "SurfaceRealization",
  "@id": "urn:example:realization:registration-form",
  "surfaceRef": "urn:example:surface:registration-form",
  "componentRef": "urn:example:component:RegistrationForm"
}

SurfaceRealization

A SurfaceRealization must have:

surfaceRef
componentRef OR templateRef

Use componentRef for direct component realization.

Use templateRef for composed layouts.

Do not use both componentRef and templateRef.

Use slotBindingRefs only with templateRef.

Template, Slot, SlotBinding

Use Template for reusable layout structure.

A Template declares slots with slotRefs.

A SlotBinding connects one declared slot to exactly one target:

slotRef + targetSurfaceRef
or
slotRef + targetComponentRef

Use targetSurfaceRef when the slotted content corresponds to a modeled surface.

Use targetComponentRef when the slotted content is only a design-system component.

Slot bindings are presentation composition only. They do not imply traversal, state order, nesting, runtime lifecycle, or form behavior.

TokenSource

Use TokenSource only to reference a token source, package, manifest, or token set.

Do not encode token values, CSS variables, aliases, themes, or style calculations unless the user explicitly asks for a project extension.

Navigation and forms

Keep navigation in Graph.

Use Graph Transition, OutgoingTransition, and OutgoingTransitionGroup for journey topology, links, CTAs, header/footer navigation, and locale switchers.

Use Design System only to realize the surfaces that display those affordances.

Keep form states and outcomes in Graph. Use Design System only to say which component or template realizes each form/result surface.

Checks before answering

• Did Graph bind to Surface, not directly to Design System?
• Are all Design System terms defined by ED?
• Is every SurfaceRealization attached to a Surface?
• Does every realization use exactly one of componentRef or templateRef?
• Are slots declared by Template and filled through SlotBinding?
• Did I avoid invented props, variants, class names, routes, URLs, CSS, runtime events, and business logic?
• Did Design System avoid changing Graph traversal?