KDF Specification

# Colours & Gradients

This page explores how colours and gradients can be used in KDF documents.

NOTE

Always use the spelling color when representing colours in a technical setting for the sake of consistency.

# Document Palette

The colours.json file allows document authors to create their own custom colour palette. It contains an ordered list of shades, where each shade has a unique identifier, a human readable name, and a valid colour. Authors may reuse these shades throughout their document, such that any modifications to a shade will immediately propagate throughout the document.

[
  {
    "id": "cosmic-blue-500",
    "name": "Cosmic Blue 500",
    "value": "#3647E2"
  },
  {
    "id": "cosmic-blue-400",
    "name": "Cosmic Blue 400",
    "value": "#4857E4"
  },
  {
    "id": "cosmic-blue-300",
    "name": "Cosmic Blue 300",
    "value": "#5A68E7"
  },
  ...
]

FOR APPLICATION DEVELOPERS

If you're writing an editor for KDF, we suggest you also include an application level colour palette for users. Shades defined at this level would then be accessible across all documents.

TIP

See Custom Shades for a description of how to include these colours in documents.

# Colours

There are several ways to define colours in KDF, with each format providing different levels of control over the final colour. For example, HSL is the perfect format for thinking logically about colours, whilst hexadecimal is a highly shareable and recognisable format.

Throughout this section you will see the use of context free grammars, like the one below. These grammars formally define the structure of a colour string.

<color> ::= <hex>|<rgb()>|<rgba()>|<hsl()>|<hsla()>|<custom-shade>

# Hexadecimal

TODO introduce and describe hexadecimal notation.

      <hex> ::= "#"<hex-token>{3,4}
<hex-token> ::= <hex-char>{2}
 <hex-char> ::= 0-9, a-f, or A-F

# RGB Function

TODO introduce and describe RGB functional notation

    <rgb()> ::= "rgb("<rgb-token><delimiter><rgb-token><delimiter><rgb-token>")"
<rgb-token> ::= <percentage>|
<delimiter> ::= ","|" "

# HSL Function

TODO introduce and describe HSL functional notation

<hsl()> ::=

# Author Defined Shades

Shades can be referenced anywhere that normal colours can, be prefixing their unique id with a $. For example:

{
  "type": "span",
  "styles": { "color": "$cosmic-blue-500" },
  "children": ["Look, I'm Cosmic Blue 500!"]
}

# Gradients

KDF also supports a number of formats for gradients.

# Linear

TODO

# Radial

TODO

# Conical

TODO

← Dictionary →