Design tokens

Explore the foundations, roles and relationships behind HES component styling.

How tokens work

Tokens give design decisions reusable names and values. Primitives define a value, semantic tokens explain its purpose, and component tokens assign that role to a particular component.

1. Primitiveprimitives.colour.orange.600Raw colour value
2. Semanticsemantic.colour.action.primary.filled.backgroundMeaning within an interface
3. Componentcomponents.button.primary.filled.backgroundWhere the Button uses it

A change to the primitive travels through validated aliases. The current Button uses that chain through Bootstrap's native .btn-primary class.

Colour primitives

The F+ working palette contains 67 colours: seven graded families, standalone White and Warm neutral 100. Grades identify positions within a family; they do not guarantee contrast between colours.

Recorded maturity and scope: Accepted for the Design System working baseline. This is not HES-wide brand or production approval.

Swatches are for reference, not evidence that overlaid text or controls meet contrast requirements.

Semantic colour roles

Semantic tokens describe why a colour is used. Select an appropriate role rather than reusing an attractive primitive directly. The current mapping includes 26 action roles and 2 focus roles. Recorded scope: Accepted for the Button working baseline.

Outline Buttons use a transparent base as a CSS treatment, not as an invented colour token. Their interaction and focus-visible behaviour is also defined in component CSS.

Component tokens

Component tokens connect shared roles to the component that consumes them. The Button is our first implemented example; this is a relationship reference, not another Button playground.

Button type and geometry also use generated aliases, rather than literal values maintained in its Sass:

At 18px, a line-height ratio of 1.5 gives the accepted 27px Button label treatment. See Button guidance for live variants and HTML. In Figma, Button colours already bind to shared semantic variables; identical component-alias names aren't required there.

Other foundations

Typography

The source currently contains 10 candidate typography roles using three manually selected contexts. Their values are generated, but the responsive thresholds, Display role and HES-wide adoption remain experimental. Review specimens on the Typography page.

Spacing, border and opacity

Current reusable measurements are scoped to Button. They are not a complete approved spacing or sizing scale for HES. New foundations should be documented when they have real consumers and decisions behind them.

Using and changing tokens

GitHub is the authoritative source for these DTCG values. The build generates CSS variables and applies them through Bootstrap where appropriate. The names on this page are working implementation references, not yet a published stable API for HES services.

/* Generated token, consumed by native Bootstrap styling */
.btn-primary {
  --bs-btn-bg: var(--hes-components-button-primary-filled-background);
}

Maturity matters: Experimental values are candidates; Pilot values are implementation references under review; Accepted values apply only to their recorded scope; Deprecated aliases are retained for compatibility. A canonical value is not necessarily a HES-wide design standard.

The coded Design System owns the token source. Figma variables represent those values for design work, but a token-to-Figma identity should only be claimed after checking that binding.

Explore canonical token files or the F+ Button working decision.