@canonical/design-system

Design System Ontology

An OWL ontology for modeling UI design systems as structured, queryable knowledge graphs. Built to bridge the gap between design specifications and implementation by establishing a shared semantic vocabulary for components, patterns, layouts, and their relationships.

Core Philosophy: A design system is more than a component library - it's a formal language. By modeling UI elements ontologically, we enable machine-readable specifications, automated consistency checking, and intelligent tooling that understands design intent.

Quick Start

1. Core Concepts

The ontology organizes UI elements into a hierarchy:

UIElement (root)
└── UIBlock (visual/abstract entity for composing UIs)
    ├── Component  - Implementable UI piece (Button, Badge, Card...)
    ├── Pattern    - Reusable solution to UX problems
    ├── Layout     - Opinionated space division for navigation
    └── Subcomponent - Part of a parent component

Components are organized by Tiers (scope/applicability) and can be customized through ModifierFamilies (variant axes).

2. Defining a Component

@prefix dso: <https://ds.canonical.com/ontology#> .
@prefix ds:  <https://ds.canonical.com/data/> .

ds:global.component.button a dso:Component ;
    dso:name "Button" ;
    dso:description "Buttons trigger actions within an interface" ;
    dso:tier ds:global ;
    dso:hasModifierFamily ds:global.modifier_family.importance ;
    dso:whenToUse "For primary actions that transform or submit data" ;
    dso:whenNotToUse "For navigation - use links instead" .

3. Tiered Organization

Components belong to tiers that define their scope:

Tier	Description	Example Components
global	Universal components	Button, Badge, Card, Accordion
global_form	Form-specific	Input, Select, Checkbox
apps	Application UI	Navigation, Toolbar, FileTree
apps_wpe	WordPress-specific	WPE variants
site	Marketing/website	Hero, Footer
stores	E-commerce	Product card, Cart
documentation	Docs-specific	Code block, API reference

4. Modifier System

Modifiers provide systematic variation through ModifierFamilies:

ds:global.modifier_family.importance a dso:ModifierFamily ;
    dso:name "Importance" ;
    dso:hasModifier ds:global.modifier.primary,
                    ds:global.modifier.secondary,
                    ds:global.modifier.tertiary .

ds:global.component.button
    dso:hasModifierFamily ds:global.modifier_family.importance .

Available modifier families:

• Importance - Visual hierarchy (primary, secondary, tertiary)
• Criticality - Severity levels (success, warning, error)
• Density - Spacing variants (compact, default, comfortable)
• Lifecycle - State (draft, active, deprecated)
• Anticipation - Expected interaction type

How-To Guides

How to Add a New Component

• Determine the appropriate tier based on scope
• Create a Turtle file in data/{tier}/component/
• Define required properties: name, description, tier
• Link to applicable modifier families
• Add usage guidelines (whenToUse, whenNotToUse)

@prefix dso: <https://ds.canonical.com/ontology#> .
@prefix ds:  <https://ds.canonical.com/data/> .

ds:apps.component.file_tree a dso:Component ;
    dso:name "FileTree" ;
    dso:description "Hierarchical file browser for navigating directory structures" ;
    dso:tier ds:apps ;
    dso:whenToUse "When users need to navigate nested file hierarchies" ;
    dso:figmaLink <https://figma.com/file/...> .

How to Define a Layout

Layouts define how space is divided for a domain of information:

ds:apps.layout.sidebar a dso:Layout ;
    dso:name "Sidebar Layout" ;
    dso:domain "Application navigation" ;
    dso:grid "1fr 4fr" ;
    dso:gridAreas "sidebar main" ;
    dso:targetDevices "desktop, tablet" .

How to Create a Pattern

Patterns are reusable solutions to UX problems:

ds:global.pattern.empty_state a dso:Pattern ;
    dso:name "Empty State" ;
    dso:description "Guidance shown when a container has no content" ;
    dso:tier ds:global ;
    dso:whenToUse "When a list, table, or container is empty" ;
    dso:guidelines "Include illustration, message, and action" .

How to Model Component Composition

Use subcomponents for parts that belong to a parent:

ds:global.subcomponent.button_icon a dso:Subcomponent ;
    dso:name "Button Icon" ;
    dso:parentComponent ds:global.component.button ;
    dso:standalone false .

How to Query the Design System

Using sem tools:

# Find all global components
sem lookup dso:Component --filter 'tier=ds:global'

# Get context for a specific component
sem context ds:global.component.button

# Find components using a modifier family
sem sparql "SELECT ?c WHERE { ?c dso:hasModifierFamily ds:global.modifier_family.criticality }"

Reference

Classes

Class	Description	Instances
UIElement	Root class for all design system entities	-
UIBlock	Visual/abstract entity for composing UIs	-
Component	Implementable UI piece	50
Pattern	Reusable UX solution	21
Layout	Space division for navigation	9
Subcomponent	Part of a component	13
Modifier	Variant option	31
ModifierFamily	Grouping of related modifiers	9
Tier	Scope/applicability level	7
Property	Configurable component property	2
Token	Design token reference	-
ImplementationObject	Platform-specific implementation	-
ImplementationLibrary	Implementation library	-

UIBlock Properties

Property	Range	Description
name	string	Display name
description	string	What this block is/does
tier	Tier	Scope classification
whenToUse	string	Usage guidance
whenNotToUse	string	Anti-patterns
guidelines	string	Design guidelines
variants	string	Available variants
figmaLink	anyURI	Link to Figma designs
wireframeLink	anyURI	Link to wireframes
anatomy	anyURI	Link to anatomy diagram
hasModifierFamily	ModifierFamily	Applicable variant axes
hasProperty	Property	Configurable properties
usesToken	Token	Design tokens used

Layout-Specific Properties

Property	Range	Description
domain	string	Information domain
grid	string	CSS grid definition
gridAreas	string	Named grid areas
targetDevices	string	Supported devices

Component Relationships

Property	Domain	Range	Description
hasSubcomponent	Component	Subcomponent	Composition
parentComponent	Subcomponent	Component	Inverse of above
hasModifierFamily	UIBlock	ModifierFamily	Variant axes
hasModifier	ModifierFamily	Modifier	Variant options

Implementation Bridge

Property	Domain	Range	Description
implementsBlock	ImplementationObject	UIBlock	Links code to spec
library	ImplementationObject	ImplementationLibrary	Source library
libraryTier	ImplementationLibrary	Tier	Library's tier

Explanation

Why an Ontology?

After a decade using Vanilla Framework (CSS library), Canonical observed that visual consistency worked well but led to challenges:

• Inconsistent terminology - Same component, different names across teams
• Implicit relationships - Component composition undocumented
• Lost design rationale - Why decisions were made
• Fragmented specifications - Figma, docs, code out of sync

An ontology addresses these by:

• Establishing shared vocabulary - One name, one meaning
• Explicit relationships - Queryable component graph
• Structured metadata - Guidelines, rationale, links preserved
• Machine-readable specs - Enables tooling and validation

Design Principles

1. Separation of Concept and Implementation

The ontology separates the what (UIBlock) from the how (ImplementationObject). A Button concept can have multiple implementations across React, Web Components, or Flutter while maintaining semantic identity.

2. Tiered Scoping

Not all components belong everywhere. Tiers make scope explicit - global components are universal, while apps-tier components may not make sense on marketing sites.

3. Systematic Variation

ModifierFamilies provide principled variation. Instead of ad-hoc props like isImportant, isPrimary, variant="critical", the ontology models Importance and Criticality as distinct axes that components can opt into.

4. Documentation as Data

Usage guidelines, when-to-use patterns, and design rationale are first-class properties - queryable, versionable, and programmatically accessible.

Architecture

design-system/
├── definitions/
│   └── ontology.ttl          # TBox: Classes, properties
├── data/
│   ├── global/               # Global tier instances
│   │   ├── component/        # Button, Badge, Card...
│   │   ├── pattern/          # Empty state, Loading...
│   │   ├── layout/           # Grid layouts
│   │   ├── modifier/         # Primary, Secondary...
│   │   └── modifier_family/  # Importance, Criticality...
│   ├── apps/                 # Apps tier
│   ├── site/                 # Site tier
│   └── ...                   # Other tiers
├── sem.toml                  # Package manifest
└── README.md                 # This file

Namespaces

@prefix dso: <https://ds.canonical.com/ontology#> .  # Ontology (TBox)
@prefix ds:  <https://ds.canonical.com/data/> .      # Instances (ABox)

URI Convention

Instances follow the pattern: {tier}.{class}.{name}

ds:global.component.button
ds:apps.layout.sidebar
ds:global.modifier_family.importance

Dependencies

• sem_v1 - Semantic package infrastructure
• artifact - Artifact lifecycle management

Data Pipeline

The design system data is extracted from Coda and transformed to RDF:

bun install

# Create .env with Coda API key
echo "CODA_API_KEY=your-token" > .env

# Extract and transform
bun run ds:list        # List available tables
bun run ds:extract     # Extract to JSON
bun run ds:transform   # Transform to JSON-LD/Turtle

Implementation Collector

The collect-implementations script scans codebases for @implements annotations and generates RDF linking implementations to their design system specifications.

Setup

• Create a design-system.json config file in your project root:

{
  "name": "my-component-library",
  "platform": "react",
  "description": "React implementation of the design system",
  "link": "https://github.com/org/my-library",
  "documentation": "https://docs.example.com/components",
  "tier": "ds:global",
  "prefix": {
    "short": "ds",
    "namespace": "https://ds.canonical.com/"
  },
  "pattern": "src/**/*.tsx",
  "outputDir": "data"
}

Configuration Options

Field	Required	Description
name	Yes	Library identifier (e.g., "pragma-react")
platform	Yes	Framework/platform (react, vue, angular, etc.)
description	No	Human-readable library description
link	Yes	Main repository or package URL
documentation	No	Documentation URL if different from link
tier	No	Design system tier reference (e.g., "ds:global")
prefix.short	Yes	Namespace prefix used in annotations (e.g., "ds")
prefix.namespace	Yes	Full namespace URI
pattern	Yes	Glob pattern for files to scan
outputDir	No	Output directory for .ttl files (default: "data")

Annotating Components

Add @implements annotations as comments in your component files:

// @implements ds:global.component.button
export function Button({ children, ...props }) {
  return <button {...props}>{children}</button>;
}

Annotation formats:

• Basic: // @implements ds:global.component.button
• With version: // @implements ds:global.component.button@1.0.0
• Draft status: // @implements ds:global.component.button [draft]

Running the Collector

From within your project directory (where design-system.json is located):

# Using bun directly
bun /path/to/design-system/src/collect-implementations.ts

# Or if installed globally/linked
collect-implementations

Output

The collector generates two Turtle files in the configured output directory:

• implementationLibrary.ttl - Defines the implementation library:

  lib:my-component-library a dso:ImplementationLibrary ;
      dso:name "my-component-library" ;
      dso:platform "react" ;
      dso:link <https://github.com/org/my-library> .
  

• implementationObjects.ttl - Links each annotated file to its spec:

  lib:my-component-library.button a dso:ImplementationObject ;
      dso:implementsBlock ds:global.component.button ;
      dso:library lib:my-component-library ;
      dso:sourceFile "src/components/Button.tsx" .
  

Example Workflow

# 1. Navigate to your component library
cd my-react-library

# 2. Add annotations to components
echo '// @implements ds:global.component.button' >> src/Button.tsx

# 3. Run the collector
bun ~/code/cn/design-system/src/collect-implementations.ts

# Output:
# Scanning src/**/*.tsx for @implements annotations...
# Found 1 valid implementation(s):
#   - ds:global.component.button
# Written: data/implementationLibrary.ttl
# Written: data/implementationObjects.ttl
# Done!

Version

0.1.0 - Initial release with component/pattern/layout hierarchy, tier organization, and modifier system

References

• Canonical's Design System: Towards a Design System Ontology
• Vanilla Framework