Everything you want to know about your design system

You can browse every information about a design system managed by Dilla, with the read-only Describe API.

Function call

Some popular languages examples:

        <?php

declare(strict_types=1);

require 'vendor/autoload.php';

use Extism\Plugin;
use Extism\Manifest;
use Extism\PathWasmSource;
use Extism\UrlWasmSource;

$request = "component::card";

$url = "https://data.dilla.io/extism/bootstrap_5/bootstrap_5_dev.wasm";
$wasm = new UrlWasmSource($url);
// Or local file
// $path = "bootstrap_5_dev.wasm";
// $wasm = new PathWasmSource($path);

$manifest = new Manifest($wasm);
$plugin = new Plugin($manifest, true);

$result = $plugin->call("describe", $request);

print $result;
      


              
            


              
            

Definitions

A design system is modeled as a tree of definitions:

Design system #

The top level of the definition hierarchy.

Property Type Description
id id Identifier Machine name, unique and persistent (Universal metadata).
label string Label Human-friendly, preferably short, name (Universal metadata).
description string Description Human-friendly, more lengthy explanation (Universal metadata).
status string Status Its stage in a lifecycle: Incomplete, Draft, Published, Obsolete... No processing is made on this value. (Universal metadata)
group string Group A category. Used in catalogs and preview.
license string License An SDPX identifier or an URL. Used in catalogs and preview. See https://spdx.org/licenses/
homepage uri Homepage An URL to identify the defined object, or where to find more information or documentation. Used in catalogs and preview.
extends uri A design system URL Every components, styles, themes, variables, examples and libraries from this parent design system will be duplicated in the current design system, if their ID are not overriden.
dateModified string The date on which the design system was most recently modified, according to upstream.
version string The current version of the design system according to upstream. Can be a git ref, a date, a tag... A major upstream version will generate a new Dilla design system.
components object A collection of components definitions, keyed by ID.
styles object A collection of styles definitions, keyed by ID.
themes object A collection of themes definitions, keyed by ID.
variables object A collection of variables definitions, keyed by ID.
examples object A collection of examples definitions, keyed by ID.
libraries object A collection of assets libraries definitions, keyed by ID.
                
                  {
    "id": "swing_1",
    "label": "Dilla Swing",
    "status": "wip",
    "description": "The design of dilla.io, based on Bootstrap 5.",
    "group": "internal",
    "extends": "bootstrap:5",
    "components": {
        "list": [],
        "preview": []
    }
}
                
              

Component #

Reusable, repeatable and nestable building blocks of the design system. Each component meets a specific UI need. The are rendered by the engine attached to the design system.

Property Type Description
id id Identifier Machine name, unique and persistent (Universal metadata).
label string Label Human-friendly, preferably short, name (Universal metadata).
description string Description Human-friendly, more lengthy explanation (Universal metadata).
status string Status Its stage in a lifecycle: Incomplete, Draft, Published, Obsolete... No processing is made on this value. (Universal metadata)
group string Group A category. Used in catalogs and preview.
license string License An SDPX identifier or an URL. Used in catalogs and preview. See https://spdx.org/licenses/
homepage uri Homepage An URL to identify the defined object, or where to find more information or documentation. Used in catalogs and preview.
variants object A collection of component variants definitions, keyed by ID.
slots object A collection of component slots definitions, keyed by ID.
props object A collection of component props definitions, keyed by ID.
examples object A collection of examples definitions, keyed by ID.
library library A single assets library definition, which will be loaded if the component is called in a render request.
                
                  {
    "id": "button",
    "label": "Button",
    "group": "Interaction",
    "slots": {
        "label": {
            "id": "label",
            "label": "Label"
        }
    },
    "props": {
        "url": {
            "id": "url",
            "label": "URL",
            "$ref": "#/$defs/uri"
        }
    },
    "variants": {
        "default": {
            "id": "default",
            "label": "Default"
        },
        "primary": {
            "id": "primary",
            "label": "Primary"
        }
    }
}
                
              

Component variant #

Different visual versions of the component

Property Type Description
id id Identifier Machine name, unique and persistent (Universal metadata).
label string Label Human-friendly, preferably short, name (Universal metadata).
description string Description Human-friendly, more lengthy explanation (Universal metadata).
status string Status Its stage in a lifecycle: Incomplete, Draft, Published, Obsolete... No processing is made on this value. (Universal metadata)
                
                  {
    "id": "flush",
    "label": "Flush",
    "description": "Remove the default background color"
}
                
              

Component slot #

Non typed. Can host any renderable value

Property Type Description
id id Identifier Machine name, unique and persistent (Universal metadata).
label string Label Human-friendly, preferably short, name (Universal metadata).
description string Description Human-friendly, more lengthy explanation (Universal metadata).
status string Status Its stage in a lifecycle: Incomplete, Draft, Published, Obsolete... No processing is made on this value. (Universal metadata)
                
                  {
    "id": "navigation",
    "label": "Navigation",
    "description": "Navigation elements (brand, text, etc.)."
}
                
              

Component prop #

Typed value. Can be used for calculation inside the template. Can be printed.

Property Type Description
id id Identifier Machine name, unique and persistent (Universal metadata).
label string Label Human-friendly, preferably short, name (Universal metadata).
description string Description Human-friendly, more lengthy explanation (Universal metadata).
status string Status Its stage in a lifecycle: Incomplete, Draft, Published, Obsolete... No processing is made on this value. (Universal metadata)
schema object A JSON schema object to describe the prop data type. May be used for payload validation.
                
                  {
    "id": "with_container",
    "label": "With container?",
    "description": "Containers provide a means to center and horizontally pad contents.",
    "schema": {
        "type": "boolean"
    }
}
                
              

Style #

A collection of mutually exclusive, self-descriptive, single-purpose CSS classes. Examples: Typography, Borders, Background colors, Spacing.... Also known as helpers, utilities, fundamentals...

Property Type Description
id id Identifier Machine name, unique and persistent (Universal metadata).
label string Label Human-friendly, preferably short, name (Universal metadata).
description string Description Human-friendly, more lengthy explanation (Universal metadata).
status string Status Its stage in a lifecycle: Incomplete, Draft, Published, Obsolete... No processing is made on this value. (Universal metadata)
group string Group A category. Used in catalogs and preview.
homepage uri Homepage An URL to identify the defined object, or where to find more information or documentation. Used in catalogs and preview.
options object A collection of styles options definitions, keyed by ID.
previewed_with array A list of styles ID. Used for previews.
                
                  {
    "id": "borders_border",
    "label": "Border",
    "options": {
        "border-all": {
            "id": "border-all",
            "label": "All"
        },
        "border-none": {
            "id": "border-all",
            "label": "None"
        }
    },
    "previewedWith": [
        "p-2",
        "bg-light"
    ]
}
                
              

Style option #

A simple HTML class typically scoped to a single CSS property. Options from the same style are mutually exclusive

Property Type Description
id id Identifier Machine name, unique and persistent (Universal metadata).
label string Label Human-friendly, preferably short, name (Universal metadata).
description string Description Human-friendly, more lengthy explanation (Universal metadata).
status string Status Its stage in a lifecycle: Incomplete, Draft, Published, Obsolete... No processing is made on this value. (Universal metadata)
previewed_with array A list of styles ID. Used for previews, after being merged with parent previewed_with property.
                
                  {
    "id": "fw-bolder",
    "label": "Bolder (relative to the parent element)",
    "previewed_with": [
        "border",
        "m-3"
    ]
}
                
              

Theme #

A themeable design system enables organizations to reuse a single design system for multiple products or purposes. Examples: branding, accessibility, modes...

Property Type Description
id id Identifier Machine name, unique and persistent (Universal metadata).
label string Label Human-friendly, preferably short, name (Universal metadata).
description string Description Human-friendly, more lengthy explanation (Universal metadata).
status string Status Its stage in a lifecycle: Incomplete, Draft, Published, Obsolete... No processing is made on this value. (Universal metadata)
group string Group A category. Used in catalogs and preview.
homepage uri Homepage An URL to identify the defined object, or where to find more information or documentation. Used in catalogs and preview.
target string Target Bubble the theme (as an HTML class or attribute) to the html or body element. Or add it as an HTML meta element. If empty, the theme is scopable and will not bubble.
key string Key The HTML attribute name or meta element name attribute. If empty, the vallue will be added to the HTML class attributes.
value string Value The theme value to add as a class or attribute value, if different from ID.
library library A single assets library definition, which will be loaded if the theme is called in a render request.
                
                  {
    "id": "Dark",
    "label": "Dark",
    "description": "Dsplays dark surfaces across the majority of a UI.",
    "value": "mzp-t-dark",
    "key": "data-scheme"
}
                
              

Variable #

Also know as CSS custom property. Allows to override a default CSS value with custom value.

Property Type Description
id id Identifier Machine name, unique and persistent (Universal metadata).
label string Label Human-friendly, preferably short, name (Universal metadata).
description string Description Human-friendly, more lengthy explanation (Universal metadata).
status string Status Its stage in a lifecycle: Incomplete, Draft, Published, Obsolete... No processing is made on this value. (Universal metadata)
group string Group A category. Used in catalogs and preview.
type string CSS value type
default object Default value. Used in rendering to prevent the printing of a defaut value.
                
                  {
    "id": "bs-body-font-size",
    "label": "Font size",
    "group": "Body",
    "type": "length",
    "default": {
        ":root": "1rem"
    }
}
                
              

Example #

Provide example by defining renderable. Examples are useful to show what your design system or your component is capable of.

Property Type Description
id id Identifier Machine name, unique and persistent (Universal metadata).
label string Label Human-friendly, preferably short, name (Universal metadata).
description string Description Human-friendly, more lengthy explanation (Universal metadata).
status string Status Its stage in a lifecycle: Incomplete, Draft, Published, Obsolete... No processing is made on this value. (Universal metadata)
group string Group A category. Used in catalogs and preview.
license string License An SDPX identifier or an URL. Used in catalogs and preview. See https://spdx.org/licenses/
homepage uri Homepage An URL to identify the defined object, or where to find more information or documentation. Used in catalogs and preview.
renderable renderable Renderable A Dilla renderable, according to the Render API schema.
                
                  {
    "id": "hello_world",
    "label": "Hello world",
    "renderable": [
        "Hello",
        {
            "@element": "strong",
            "@content": "beautiful"
        },
        "world"
    ]
}
                
              

Asset library #

Can contain one or more CSS assets, one or more JS assets. Assets (CSS or JS) are only loaded if needed.

Property Type Description
id id Identifier Machine name, unique and persistent (Universal metadata).
label string Label Human-friendly, preferably short, name (Universal metadata).
description string Description Human-friendly, more lengthy explanation (Universal metadata).
status string Status Its stage in a lifecycle: Incomplete, Draft, Published, Obsolete... No processing is made on this value. (Universal metadata)
group string Group A category. Used in catalogs and preview.
license string License An SDPX identifier or an URL. Used in catalogs and preview. See https://spdx.org/licenses/
homepage uri Homepage An URL to identify the defined object, or where to find more information or documentation. Used in catalogs and preview.
default boolean If true: the library is always loaded and attached. If false: attached only if a dependency of an already loaded library.
css object Stylesheets Keys are URL. Values are HTML attributes which will be added to the attached element.
js object Scripts Keys are URL. Values are HTML attributes which will be added to the attached element.
dependencies array A list of libraries ID which will be attached before the current library.
                
                  {
    "id": "popperjs",
    "label": "Popper JS",
    "default": true,
    "js": {
        "https://unpkg.com/@popperjs/core@2.11.6/dist/umd/popper.min.js": []
    },
    "license": "MIT",
    "dependencies": []
}
                
              

Scalar types

Type Label Description Schema
id Identifier Machine name, unique and persistent. Only ASCII letters, digits, '_', and '-' should be used, and should start with a letter.
            
              {
    "type": "string",
    "pattern": "^[A-Za-z]+[\\w\\-]*$"
}
            
          
uri URI Absolute or relative URI.
            
              {
    "type": "string",
    "format": "uri-reference"
}