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

1. Determine the appropriate tier based on scope
2. Create a Turtle file in data/{tier}/component/
3. Define required properties: name, description, tier
4. Link to applicable modifier families
5. 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:

1. Inconsistent terminology - Same component, different names across teams
2. Implicit relationships - Component composition undocumented
3. Lost design rationale - Why decisions were made
4. 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

1. 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:[email protected]
• 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:

1. 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> .

2. 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