Constraints-Driven Design

Treat constraints as a design tool, not as a limitation to work around, explicit constraints reduce ambiguity, guide decision-making, and prevent the gradual erosion of the system.

In the absence of clearly defined constraints, teams tend to:

improvise solutions,
stretch components beyond their intended purpose,
and introduce inconsistencies that are difficult to detect and even harder to remove.

A constraints-driven system makes boundaries visible.

It defines not only what is possible, but also what is intentionally unsupported, allowing teams to move faster and with greater confidence.

Constraints are most effective when they are:
explicit,
documented,
and enforced by the system itself.

Limited and intentional component APIs

Components were designed with intentionally constrained APIs to prevent misuse and uncontrolled variation.

mds-modal

Attrubutes API

animating

enum

(intro, none, outro)

none

Specifies if the component is animating itself or not

animation

enum

(3d, custom, slide)

slide

Specifies if the component is animating itself or not

backdrop

boolean

true

Specifies if the modal shows the backdrop

opened

boolean

false

Specifies if the modal is opened or not

overflow

enum

(auto, manual)

auto

Specifies if the component prevents the body from scrolling when modal window is opened

position

enum

(bottom, bottom-left, bottom-right, center, left, right, top, top-left, top-right)

center

Specifies the animation position of the modal window

mds-modal

Events API

mdsModalClose

void

true

Emits when a modal is closed

mdsModalHide

void

true

Emits when a modal is totally invisible, can be useful to detach the component when it's hidden and gain memory

mds-modal

CSS Custom Properties API

--mds-modal-custom-closed-transform

Sets the transform position of the custom window when it's outside the viewport, to it's default position

--mds-modal-custom-window-distance

Set the distance between the slotted modal window and the screen bounds

--mds-modal-overlay-color

Set the overlay color of the background when the component is opened, this property can be inherited from `globals.css` in `styles^8.0.0`.

--mds-modal-overlay-opacity

Set the overlay color opacity of the background when the component is opened, this property can be inherited from `globals.css` in `styles^8.0.0`.

--mds-modal-transition-duration

Sets the `transition-duration` of the modal elements

--mds-modal-transition-timing-funciton

Sets the `transition-timing-funciton` of the modal elements

--mds-modal-window-background

Set the background color of the window

--mds-modal-window-distance

Set the distance between the modal window and the screen bounds

--mds-modal-window-max-width

If the viewport is greather than mobile, max-width will be considered with this value;

--mds-modal-window-min-width

If the viewport is greather than mobile, min-width will be considered with this value;

--mds-modal-window-overflow

Set the overflow of the window

--mds-modal-window-radius

Set the border radius of the window

--mds-modal-window-shadow

Set the box shadow of the window

--mds-modal-z-index

Set the z-index of the window when the component is opened

Expose only properties that support known and validated use cases.

Add configuration options to solve isolated problems.

Treat every new prop as a design decision with long-term impact.

Turn components into generic containers with unlimited flexibility.

A list of tools and services related to this argument.

potentially outdated

Documentation tools

Kompendium

StencilJS documentation

Curated component APIs

ESLint

Robust API design

TypeScript

Design tokens as enforced boundaries

Design tokens were used to encode visual constraints directly into the system.

Use tokens to control spacing, color, typography, and motion.

Allow arbitrary values outside the token set.

Make tokens the only supported way to express system values.

Treat tokens as optional or decorative abstractions.

A list of tools and services related to this argument.

potentially outdated

Tokens documentation

Zeroheight

Supernova

Knapsack

Specify

Tokens tools

Style Dictionary

Composition rules instead of free assembly

Composable components were governed by explicit composition rules.

Documentation from codebase

typescript

        // StencilJS component documentation
/**
 * @slot default - Add `text string`, `HTML elements` or `components` to this slot.
 * @slot action - Add `HTML elements` or `components`, it is **recommended** to use `mds-button` element.
 */

Component composition

html

        <mds-modal>
  <mds-banner
    headline="Modal title"
    icon="mi/outline/info"
    slot="window"
    tone="weak"
    variant="primary"
  >
    <mds-text typography="caption">This is a modal text content.</mds-text>
    <mds-button
      icon="mi/outline/email"
      slot="action"
      tone="strong"
      variant="primary"
    >
      Proceed
    </mds-button>
  </mds-banner>
</mds-modal>

Define which components can be nested or combined.

Allow unrestricted component nesting.

Document supported compositions and known anti-patterns.

Rely on visual review to catch invalid compositions.

A list of tools and services related to this argument.

potentially outdated

Documentation tools

Kompendium

StencilJS documentation

Accessibility constraints as non-negotiable

Accessibility requirements were encoded as hard constraints rather than guidelines.

Use tab to navigate

Enforce color contrast, focus management, and keyboard navigation by default.

Allow opt-out accessibility features.

Prevent configurations that violate accessibility standards.

Treat accessibility as a downstream responsibility.

System-level defaults over local overrides

Defaults were treated as part of the system's contract.

allowed

Using component attributes as defaults

html

        <mds-modal
  headline="Modal title"
  icon="mi/outline/info"
  tone="weak"
  variant="primary"
>
  <mds-text typography="caption">This is a modal text content.</mds-text>
  <mds-button
    icon="mi/outline/email"
    slot="action"
    tone="strong"
    variant="primary"
  >
    Send email
  </mds-button>
</mds-modal>

not allowed

Skipping attributes for out of scope customization

html

        <mds-banner
  icon="mi/outline/info"
  class="bg-tone-neutral text-tone-neutral-01 fill-variant-primary-03"
>
  <mds-text typography="caption">This is a modal text content.</mds-text>
  <mds-button
    icon="mi/outline/email"
    slot="action"
    class="bg-variant-primary-03 fill-tone-neutral text-variant-primary-10"
  >
    Send email
  </mds-button>
</mds-banner>

Provide strong, opinionated defaults aligned with system goals.

Encourage local overrides for stylistic reasons.

Encourage teams to rely on defaults instead of customization.

Allow silent deviations from system behavior.

A list of tools and services related to this argument.

potentially outdated

Pratical documentation

Zeroheight

Docusaurus

Component testing

Storybook

Explicit "out of scope" decisions

Some use cases were intentionally excluded from the system.

Design system documentation

Clearly document what the system does not support.

Attempt to cover every possible scenario.

Use exclusions to protect system integrity.

Expand the system reactively without evaluating systemic impact.

A list of tools and services related to this argument.

potentially outdated

Issue templates

GitHub templates

Why this principle matters

Constraints are what make systems scalable and trustworthy, they reduce cognitive load, prevent entropy, and make correct usage the easiest path.

A design system without constraints is based on uncontrolled design freedom, it is fragile, establishing constraints intentionally enables creativity within safe and predictable boundaries.

Limited and intentional component APIs

Design tokens as enforced boundaries

Composition rules instead of free assembly

Accessibility constraints as non-negotiable

System-level defaults over local overrides

Explicit "out of scope" decisions

Why this principle matters

Alla Kholmatova — Design Systems

Brad Frost — Atomic Design

Don Norman — The Design of Everyday Things

Derek Niedringhaus — Rethinking design systems as scalable architecture

GOV.UK Design System — Accessibility Constraints

Jon Daiello — Unlocking Accessibility through Design Systems

Material Design — Design Tokens and Constraints

Matheus Cervo — Design systems and accessibility—a 2024 retrospective

Nathan Power — Composable component APIs

Pranay Kothapalli — The Three-Layer Rule for Design Systems