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.

This API is only available in the dev builds, alongside verbose logs and debug mode.

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 overridden.
`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. It is not allowed to have only one variant.
`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 can be scoped and will not bubble.
`key`	string	Key The HTML attribute name or meta element name attribute. If empty, the value 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": "Displays 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 default 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" }`