Constraints-Driven Design

When I design a design system, I 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.

Documentation tools

Kompendium

StencilJS documentation

Curated component APIs

ESLint

Robust API design

TypeScript

it may be outdated

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.

Tokens documentation

Zeroheight

Supernova

Knapsack

Specify

Tokens tools

Style Dictionary

it may be outdated

Composition rules instead of free assembly

Composable components were governed by explicit composition rules.

Documentation from codebase

html

// 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.

Documentation tools

Kompendium

StencilJS documentation

it may be outdated

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>