HIF / Documentation / System architecture

Design Systems Engineering

Status: engineering reference

Version: 0.1

This document defines how HIF knowledge becomes a maintained design system without reducing interface design to a component library. It combines lessons from major public systems with HIF's semantic and human-centred foundation.

1. Purpose

A design system is successful when it makes correct, coherent and accessible product decisions easier to produce and maintain at scale. It is not successful merely because:

many components exist;
screenshots look consistent;
a package has many downloads;
teams use the same design tool;
a token file contains every visual value;
adoption is mandated.

The system MUST preserve a traceable chain from human need to production behaviour:

eed → task → object → command → state → pattern → component → token → implementation → evidence`

Breaking this chain creates characteristic failures:

components without a stable problem;
tokens without semantic roles;
patterns without research;
code that differs from design assets;
accessible primitives assembled into inaccessible journeys;
brand consistency masking unreliable behaviour.

2. System architecture

HIF uses the following layers. Higher layers give meaning to lower layers; lower layers implement but MUST NOT redefine higher-layer semantics.

2.1 Constitution

The Constitution defines universal obligations: purpose, object identity, commands, state, feedback, errors, reversibility, accessibility, autonomy, privacy and evaluation.

2.2 Product Profile

The Product Profile records audience, context, risk, platforms, input methods, languages, density, accessibility target, performance budgets, adopted external conventions and justified exceptions.

2.3 Domain model and content vocabulary

This layer defines:

object types and identity;
relationships and permissions;
commands, preconditions and consequences;
state machines and persistence;
canonical names, verbs and messages;
sensitive and consequential concepts.

The vocabulary is a shared API for design, engineering, support, analytics and documentation. Synonyms SHOULD NOT be introduced for stylistic variety where they can obscure object or command identity.

2.4 Experience principles

Principles guide decisions where no exact pattern applies. Each principle MUST include:

the intended human outcome;
scope and known counterexamples;
observable evidence;
a review question;
conflicts and precedence.

Words such as “simple”, “delightful”, “intuitive” or “calm” are not acceptance criteria by themselves.

2.5 Patterns

A pattern coordinates several components and content rules to solve a recurring task, such as:

authentication;
search and filtering;
create, edit and save;
destructive action;
permission request;
upload and long-running processing;
empty, loading, error and partial states;
undo and recovery;
onboarding and disclosure;
settings and preferences;
collaboration and concurrent editing.

Patterns own workflow semantics and MUST document alternatives, entry and exit conditions, failure, interruption, recovery and measurement.

2.6 Components

A component implements one recurring interface responsibility with a stable semantic contract. It includes design, behaviour, code, content guidance, accessibility, tests and documentation.

2.7 Foundations and tokens

Foundations express system-wide roles for colour, type, space, size, shape, border, elevation, motion, opacity, sound and other media. Tokens distribute those decisions to tools and implementations.

2.8 Implementations and adapters

Implementations realise the contract for web, Android, Apple platforms, Windows, embedded environments or other targets. Platform adapters MAY render different controls while preserving semantics and outcomes.

2.9 Quality evidence

Evidence links requirements to automated checks, manual verification, user research, field data, support findings and incident history.

3. Source-of-truth model

There MUST be one normative owner for each kind of decision:

Decision	Normative source	Generated or aligned representations
Interface obligation	HIF Constitution	Review rules, test criteria
Product scope and exception	Product Profile	Backlog constraints, audit report
Object and command meaning	Domain model	API schema, UI copy, analytics taxonomy
Pattern behaviour	Pattern specification	Prototypes, journey tests
Component API	Component specification	Framework implementations, design assets
Foundation role and value	Token source	CSS, Swift, Kotlin, design-tool variables
Accessibility support	Test evidence	Status dashboard, documentation
Release maturity	Registry and changelog	Package tags, documentation labels

“Single source of truth” does not mean one application must own everything. It means two files cannot silently claim authority over the same decision.

Generated artefacts MUST carry source version and generation metadata. Hand-editing generated outputs MUST fail validation or be overwritten deterministically.

4. Design tokens

4.1 Token purpose

A token is a named design decision, not a convenient alias for every literal. Tokens SHOULD:

create a shared vocabulary across design and code;
separate semantic use from a current value;
enable controlled themes, modes, brands and platforms;
make change reviewable and distributable;
support validation and migration.

The stable Design Tokens Community Group format (2025.10) provides a vendor-neutral JSON interchange model. It is a W3C Community Group Final Report, not a W3C Recommendation. HIF SHOULD use it for interchange when tool support is adequate and MUST record extensions and transformations.

4.2 Required token layers

HIF recommends three layers:

Primitive tokens store raw scales and assets, such as a colour value, duration or space increment. Product code MUST NOT normally consume them.
Semantic tokens name purpose, such as text.primary, surface.raised, border.danger or motion.feedback. These are the default consumer API.
Component tokens express a component-specific decision only when no semantic token accurately represents it. They MUST NOT be reused outside that component.

Aliases MUST form an acyclic, resolvable graph. A build MUST fail on missing references, cycles, incompatible types or an unresolved mode.

4.3 Naming

Names SHOULD proceed from stable meaning to variable detail:

category.property.role.state.emphasis

Examples:

colour.text.primary
colour.border.danger.focused
space.container.inline
motion.duration.feedback

Do not encode a current value into a semantic name:

avoid grey-quiet-text;
prefer colour.text.secondary.

Names MUST use one documented dialect. Translations MAY describe tokens, but token identifiers MUST remain language-neutral and stable.

4.4 Modes, themes and brands

The system MUST distinguish:

mode — a user or environmental condition, such as light, dark, high-contrast, reduced-motion or compact;
theme — a coherent mapping of token roles to values;
brand — identity rules, assets and expression;
platform — conventions and technical capabilities;
density — spatial and target-size policy.

These dimensions MUST NOT be collapsed into a single “theme” switch. A dark brand is not dark mode; compact density is not reduced size; a high-contrast mode is not a colourway.

Every supported mapping MUST be validated for:

contrast and non-colour cues;
text and interface scaling;
forced colours or platform overrides;
state distinguishability;
charts and data visualisation;
images, illustrations and logos;
motion and transparency preferences.

4.5 Token governance

Every public token requires:

identifier and type;
description and permitted use;
owner;
maturity;
fallback or unsupported-platform policy;
mode and theme coverage;
deprecation metadata where applicable.

New primitive tokens require proof that an existing scale cannot support the need. New semantic tokens require a meaning that recurs across contexts. Component tokens require a documented component constraint.

Raw values in product code SHOULD be detected by linting. Exceptions MUST be explicit, narrow and reviewable.

5. Component contract

A stable component specification MUST contain the following sections.

5.1 Purpose and non-purpose

problem solved;
intended contexts;
when not to use it;
related and alternative components;
evidence of recurrence.

5.2 Anatomy

named parts and slots;
required and optional elements;
semantic ownership of labels and descriptions;
allowed composition;
constraints on nesting.

5.3 State model

At minimum, consider:

enabled and disabled;
rest, hover, focus and pressed;
selected and unselected;
checked, mixed and unchecked;
expanded and collapsed;
empty and populated;
valid, warning and invalid;
loading, pending, success and failure;
read-only and editable;
offline, stale and conflicted.

Only applicable states are implemented, but omissions MUST be intentional. Visual state, accessible state and domain state MUST agree.

5.4 Behaviour

commands and emitted events;
keyboard, pointer, touch, pen, voice and assistive-input behaviour;
focus entry, movement, trapping, restoration and visibility;
timing, repetition and cancellation;
scrolling and overflow;
responsive transformation;
drag-and-drop alternative;
interruption and recovery.

5.5 Content

label grammar;
length constraints that remain localisation-safe;
helper, empty, warning and error text;
numbers, dates, currencies and units;
truncation and full-value access;
bidirectionality and mixed-direction content;
accessible names and descriptions.

Placeholder text MUST NOT substitute for a persistent label. Icon-only actions require an accessible name and SHOULD have a discoverable visible explanation where meaning is not universally established.

5.6 Accessibility

semantic element or platform role;
accessible name, description, value and state;
keyboard model;
focus rules;
target-size policy;
contrast and non-colour indicators;
text resize and reflow;
reduced motion and other preferences;
screen-reader expectations;
known limitations and tested combinations.

ARIA MUST NOT replace a native HTML element that already provides the required semantics and behaviour. A component's accessibility support MUST be stated as test evidence, not claimed from intent.

5.7 Visual specification

semantic tokens for every public visual decision;
layout and intrinsic sizing;
minimum, maximum and content-driven dimensions;
typography and icon alignment;
states in every supported mode;
density and platform variants;
animation purpose and interruption;
high-contrast and forced-colour behaviour.

5.8 API and extension

properties, attributes, slots, events and methods;
controlled and uncontrolled state where applicable;
supported customisation points;
private implementation boundaries;
versioning and deprecation guarantees;
server rendering, hydration or native lifecycle constraints;
analytics hooks that do not expose private data.

Consumers MUST NOT be required to depend on private DOM, selectors, layers or undocumented timing.

5.9 Documentation and examples

Every stable component MUST provide:

a minimal correct example;
realistic compositions;
all important states and variants;
accessibility and keyboard guidance;
content guidance;
do and do-not-use guidance;
platform and browser support;
migration notes;
copyable examples that pass system quality gates.

6. Patterns

6.1 When a pattern is justified

A shared pattern requires:

the same user problem in at least two credible contexts;
stable objects, commands and consequences;
evidence that reuse reduces cognitive or delivery cost;
no adequate existing pattern;
an accountable maintainer.

Visual similarity alone is insufficient.

6.2 Pattern specification

A pattern MUST document:

user need and context;
entry conditions and prerequisites;
canonical sequence and allowed alternatives;
object, command and state model;
components and content;
permissions and privacy;
loading, empty, error and partial states;
interruption, cancellation, undo and recovery;
responsive and cross-platform transformation;
accessibility and localisation;
success and harm measures;
evidence, known limits and open questions.

6.3 Whole-journey boundary

Patterns MUST include necessary transitions outside one screen: email, notifications, system permission surfaces, help, identity verification, offline steps, human support and return paths.

The design system MUST clearly distinguish:

component — a reusable interface responsibility;
pattern — a recurring task solution;
template — a layout arrangement;
service — an end-to-end capability producing an outcome.

7. Contribution and maturity lifecycle

7.1 Stages

HIF uses these maturity states:

State	Meaning	Consumer expectation
Proposal	Problem and evidence are under review	Do not implement as a system dependency
Experimental	A testable solution exists	Opt-in only; breaking change is expected
Candidate	Contract is substantially complete	Limited production use with named adopters
Stable	Definition of done is satisfied	Supported; breaking change requires a major release and migration
Deprecated	Replacement or removal is planned	No new adoption; warning and migration available
Retired	No longer supported or distributed	Historical documentation remains addressable

Maturity applies separately to design specification, code implementation, design asset, documentation and accessibility evidence. An aggregate label MUST not conceal a weaker dimension.

7.2 Proposal record

A proposal MUST include:

problem, affected users and contexts;
current workarounds and their costs;
research, usage or incident evidence;
why an existing asset cannot solve the problem;
proposed semantics and API;
accessibility, localisation, privacy and security risks;
at least two potential consuming contexts for shared assets;
owner and expected maintenance cost;
experiment and success plan;
alternatives and non-goals.

7.3 Decision rights

The governance model MUST assign:

a system product owner;
design, engineering, accessibility and content maintainers;
platform specialists;
token and release owners;
product representatives;
a final decision maker for deadlock;
security, privacy or safety review when applicable.

Contribution can be open while decision rights remain explicit. The central team MUST publish reasons for acceptance, deferral or rejection.

7.4 Definition of done

A stable asset MUST have:

approved problem and semantic contract;
design and implementation parity;
complete state and input model;
Product Profile compatibility;
tokenised supported visuals;
unit, interaction and visual tests;
automated and manual accessibility evidence;
localisation, bidirectionality and content review;
performance assessment;
documentation and production-safe examples;
supported-platform matrix;
owners, support route and service level;
changelog and migration from replaced assets;
at least one production validation where risk permits.

8. Quality engineering

8.1 Test portfolio

No single test proves interface quality. The system MUST combine:

Evidence	Finds	Does not prove
Type and schema checks	Invalid API and token structure	Usability or perceptibility
Unit tests	Local logic and state transitions	Correct composition
Interaction tests	Keyboard, pointer and event behaviour	Real assistive-technology output
Automated accessibility scans	Detectable rule violations	WCAG conformance or usability
Visual regression	Rendering drift	Semantic correctness
Screenshot matrix	Themes, locales, density and breakpoints	Behaviour
Screen-reader testing	Announced structure and operation	Experience for every screen-reader user
Keyboard-only testing	Focus order and operability	Touch or voice access
Zoom, reflow and forced-colour testing	Adaptation to preferences	Cognitive accessibility
Performance tests	Budget regression in controlled conditions	Real-user experience
Field telemetry	Real distributions and failure patterns	User intent or causality
Usability research	Task comprehension and observed difficulty	Population-wide incidence
Support and incident analysis	Serious lived failures	Complete prevalence

8.2 Required matrix

The Product Profile defines the exact matrix. At minimum, a web component system SHOULD cover:

supported engines and viewport ranges;
keyboard alone;
screen reader and browser combinations representative of support policy;
200% text size and 400% zoom/reflow where applicable;
light, dark, high-contrast and forced-colour modes;
reduced motion;
left-to-right, right-to-left and expansion-test locales;
pointer and touch where supported;
slow network, offline and delayed response for asynchronous patterns.

8.3 Accessibility status

Following Carbon's useful separation, HIF reports at least:

default render;
advanced and error states;
keyboard model;
screen-reader behaviour;
zoom and reflow;
forced colours and contrast;
touch targets;
human evaluation.

Allowed status values are:

not applicable;
not tested;
automated pass;
manually tested;
verified with users;
known limitation;
blocked.

The date, version, environment and evidence link MUST accompany the status.

8.4 Performance

Performance budgets MUST cover both system assets and composed pages:

package and style size;
rendering and update cost;
memory;
input latency;
layout stability;
loading behaviour;
font and icon delivery;
server rendering and hydration where applicable.

For web products, current Core Web Vitals SHOULD be measured in the field at the 75th percentile. System laboratory tests help prevent regression but MUST not be reported as field performance.

8.5 Quality gates

Quality gates SHOULD run in increasing cost:

formatting, schema and token validation;
type, lint and unit checks;
component interaction and automated accessibility;
visual, theme, locale and breakpoint matrix;
integration and journey tests;
manual accessibility and platform review;
production candidate evaluation and field monitoring.

Emergency changes MAY use a shortened gate only with explicit risk ownership and scheduled follow-up.

9. Documentation as a product

Documentation MUST support designers, engineers, content designers, product teams, quality specialists and auditors without assuming private institutional knowledge.

9.1 Information architecture

The documentation SHOULD expose:

foundations;
components;
patterns;
content;
accessibility;
platforms;
resources and packages;
contribution;
releases and migrations;
status and known limitations.

Search terms and synonyms SHOULD map to canonical objects. Deprecated pages remain addressable and link to replacements.

9.2 Documentation quality

Every published page MUST:

identify owner, status and applicable version;
distinguish requirements from heuristics;
show purpose before API;
use meaningful examples and content;
declare accessibility considerations;
link related and alternative solutions;
include update and deprecation information;
pass link, spelling, heading and example checks.

Screenshots MUST NOT be the only specification. Text and executable examples must communicate structure and behaviour.

9.3 Synchronisation

Design assets, code and documentation SHOULD be released from the same change record. Continuous checks SHOULD detect:

undocumented public APIs;
examples using deprecated APIs;
token names absent from source;
mismatched component status;
missing design variants;
dead links;
accessibility evidence older than the supported release.

10. Release, compatibility and migration

10.1 Versioning

The system MUST define its public API, including:

component properties and events;
token identifiers and types;
import paths;
CSS or styling hooks;
semantic behaviour;
documented keyboard interaction;
persisted data or configuration formats.

Semantic versioning MAY be used for packages, but visual or behavioural change can still be breaking even when a type signature is unchanged.

10.2 Change classes

Patch — compatible correction with no intentional consumer migration.
Minor — additive capability or opt-in future behaviour.
Major — removal, renamed contract, changed default semantics or required consumer work.
Policy update — guidance changes that may alter review outcomes without package code.

Every release note MUST state user impact, consumer impact, risk and action.

10.3 Deprecation

Deprecation requires:

reason and replacement;
first deprecated version;
intended removal window;
runtime, build-time or documentation warning where appropriate;
migration guide and preferably a codemod;
accessibility or security urgency;
telemetry that does not collect unnecessary personal data;
ownership of remaining consumers.

Silent removal is prohibited for stable assets.

10.4 Experimental delivery

Feature flags, prerelease packages and preview design libraries MAY expose future changes. They MUST declare:

instability and supported use;
isolation from stable defaults;
data and migration implications;
feedback channel;
graduation or removal criteria.

11. Adoption

11.1 Adoption levels

Following the useful distinction in USWDS, HIF measures:

Principle adoption — teams use HIF obligations and review questions.
Guidance adoption — teams use shared patterns and content rules.
Implementation adoption — teams use maintained tokens and components.
Outcome adoption — products demonstrate improved accessibility, usability, reliability and delivery.

Package usage alone is not adoption success.

11.2 Adoption strategy

Begin with high-risk, high-frequency and highly duplicated journeys.
Establish semantic foundations before migrating visual values.
Provide adapters and migration tooling.
Publish known gaps so local teams can make safe decisions.
Pair governance with support and office hours.
Collect reasons for exceptions; repeated exceptions indicate a system gap.
Measure time saved without rewarding superficial conformity.

11.3 Federated extensions

Domains MAY maintain extensions when core assets cannot represent specialised objects or workflows. An extension MUST:

use core foundations and quality gates;
name an owner and consumers;
avoid redefining core component semantics;
publish status and support;
contribute generalisable findings upstream;
define retirement when core support arrives.

12. Metrics

The design system scorecard SHOULD balance:

12.1 User outcomes

task success and time;
consequential error and recovery;
accessibility barriers;
support demand;
perceived trust and clarity;
performance and reliability in the field.

12.2 Product outcomes

consistency of object and command semantics;
coverage of high-priority journeys;
exception count and age;
migration completion;
duplicated local patterns;
defects caused or prevented by shared assets.

12.3 System health

stable assets meeting definition of done;
accessibility evidence freshness;
time from accepted need to stable release;
issue response and resolution;
documentation findability and success;
release lag across design and code;
active maintainers and ownership risk.

12.4 Delivery outcomes

time to implement a conforming journey;
change failure rate;
upgrade effort;
cross-platform parity of semantics;
amount of generated versus manually duplicated work.

Adoption percentage MUST NOT be the sole primary metric. It can incentivise forced use even where the system is incomplete or unsuitable.

13. Common failure modes

Component warehouse: many assets, no shared model of tasks and outcomes.
Screenshot governance: approval based on appearance without behaviour, content or state.
Token theatre: raw values renamed without semantic roles or change control.
Accessibility badge: automated scanning presented as end-to-end accessibility.
Universal component: excessive options combine unrelated semantics.
Private override economy: consumers depend on internal DOM and CSS because extension points are absent.
Design-code drift: design libraries and production packages release independently.
Premature centralisation: an unproven local pattern becomes a permanent system obligation.
Permanent experiment: preview assets gain production dependency without support guarantees.
Silent breakage: visual or behavioural defaults change under a minor version.
Brand over platform: signature styling removes familiar system behaviour.
Compliance substitution: use of an approved component is treated as proof of a successful service.
Translation after layout: fixed geometry makes other languages unusable.
Metrics without decisions: telemetry accumulates without owners, thresholds or action.

14. Minimum operating model

An organisation starting an HIF-based design system MUST establish:

a Constitution and Product Profile template;
a domain vocabulary and command model;
a token source with primitive and semantic separation;
a small stable component set covering native fundamentals;
patterns for errors, loading, destructive action and recovery;
content and accessibility guidance;
a contribution record and maturity lifecycle;
automated quality gates and a manual test matrix;
versioning, deprecation and migration policy;
documentation with ownership and status;
an exception register;
an outcome scorecard and review cadence.

The initial stable set SHOULD be small. Breadth is earned through evidence and maintenance capacity.

15. Stable component release checklist

Semantics

The user problem and non-purpose are explicit.
Object, command, state and consequence are defined.
Existing native, platform and system components were evaluated.
Focus, selection and activation are not conflated.

Design and content

Anatomy, variants and compositions are documented.
Every applicable state is designed.
Content rules and realistic examples are present.
Localisation, expansion and bidirectionality were reviewed.
All visual decisions use appropriate semantic tokens.

Accessibility

Native semantics are used where available.
Accessible name, role, value and state are correct.
Keyboard and focus behaviour are verified.
Zoom, reflow, target size and input alternatives are verified.
Colour, forced-colour and motion preferences are verified.
Screen-reader testing evidence is attached.
Known limitations are public.

Engineering

Public API and extension points are documented.
Unit, interaction, visual and integration tests pass.
Supported platforms and environments are declared.
Performance impact is within budget.
Design assets and code match.
Server, lifecycle and asynchronous behaviour are covered where relevant.

Operations

Owner, support route and maturity are recorded.
Production-safe examples are published.
Changelog and migration material are ready.
Telemetry is purposeful and privacy-preserving.
At least one appropriate production validation exists.

16. Sources

All sources are official English-language publications. Retrieval date: 30 July 2026.