design-system

name	design-system
description	Use when setting up a project's design system or modifying design constraints. Initialize design tokens, view active principles, add custom rules, update token values.
user-invocable	true

Design System Configuration

IBR's design system ties Calm Precision principles and project-specific design tokens to the scan pipeline. When .ibr/design-system.json exists in a project, every ibr scan run checks rendered output against those constraints and reports violations.

Initialize

Copy the template to the project's IBR config directory:

cp templates/design-system.json .ibr/design-system.json

Then customize tokens for the project — colors, type scale, spacing, radii. The template contains sensible defaults for a Calm Precision-compliant interface.

To manage config programmatically, use the design_system MCP tool.

Configuration Format

The JSON structure has three top-level sections:

{
  "version": "1.0.0",
  "name": "Project name",
  "principles": { ... },
  "tokens": { ... }
}

Principles

"principles": {
  "calmPrecision": {
    "core": {
      "gestalt": { "enabled": true, "severity": "error" },
      "signal-noise": { "enabled": true, "severity": "error" },
      "content-chrome": { "enabled": true, "severity": "warn" },
      "cognitive-load": { "enabled": true, "severity": "warn" }
    },
    "stylistic": {
      "fitts": { "enabled": true, "severity": "warn" },
      "hick": { "enabled": true, "severity": "warn" }
    }
  },
  "custom": []
}

Tokens

"tokens": {
  "colors": {
    "primary": "#...",
    "secondary": "#...",
    "text": { "primary": "#...", "secondary": "#...", "muted": "#..." },
    "background": { "default": "#...", "surface": "#...", "elevated": "#..." },
    "status": { "error": "#...", "warn": "#...", "success": "#...", "info": "#..." }
  },
  "typography": {
    "fontSizes": { "xs": "11px", "sm": "12px", "base": "14px", "lg": "16px", "xl": "20px", "2xl": "24px" },
    "fontWeights": { "regular": "400", "medium": "500", "semibold": "600", "bold": "700" },
    "fontFamily": { "sans": "...", "mono": "..." }
  },
  "spacing": ["4px", "8px", "12px", "16px", "24px", "32px", "48px", "64px"],
  "borderRadius": { "sm": "4px", "md": "8px", "lg": "12px", "full": "9999px" },
  "shadows": { "sm": "...", "md": "...", "lg": "..." },
  "transitions": { "fast": "100ms ease", "base": "200ms ease", "slow": "300ms ease" },
  "touchTargets": { "min": "44px", "recommended": "48px" }
}

Core vs Stylistic Principles

Core principles — default to "error" severity. These reflect structural and perceptual correctness that is rarely acceptable to relax:

ID	Principle	What it enforces
gestalt	Grouping	Single border for groups; no individual borders on list items
signal-noise	Status display	Text color only for status; no background badges
content-chrome	Content ratio	Content area >= 70% of viewport
cognitive-load	Complexity	Max 7 interactive elements per visual group

Stylistic principles — default to "warn" severity. These are strong conventions that may have intentional exceptions:

ID	Principle	What it enforces
fitts	Target sizing	Primary action buttons >= 120px width
hick	Progressive disclosure	Max 5 visible choices before disclosure required

Any principle can be overridden. Set "severity": "off" to disable entirely.

Custom Principles

Add brand-specific or project-specific rules in the principles.custom array:

"custom": [
  {
    "id": "brand-font-only",
    "name": "Brand font enforcement",
    "description": "All text must use the approved brand font family",
    "category": "typography",
    "severity": "error",
    "checks": [
      {
        "property": "fontFamily",
        "operator": "includes",
        "values": ["Inter", "Inter var"]
      }
    ]
  }
]

Check format:

Field	Type	Description
property	string	Computed CSS property name (camelCase)
operator	string	"equals", "includes", "matches", "minValue", "maxValue"
values	array	Accepted values for this property

Token Categories

Each token category maps to what the scan validates:

Token	Validates against
colors	Computed color, backgroundColor on all elements
typography.fontSizes	Computed fontSize on text elements
typography.fontWeights	Computed fontWeight on text elements
typography.fontFamily	Computed fontFamily on text elements
spacing	Computed gap, padding, margin values
borderRadius	Computed borderRadius on containers and interactive elements
touchTargets.min	bounds.width and bounds.height on interactive elements

Values are compared as computed pixel values. Set tokens to the exact resolved values you expect (e.g. "14px" not "0.875rem" — the scan reads computed values post-resolution).

MCP Tool

Use the design_system MCP tool to manage config without editing JSON directly:

Action	Description
get	Return the active design system config
init	Copy template to .ibr/design-system.json
set_token	Update a specific token value
add_principle	Add a custom principle rule
set_severity	Change severity for a built-in principle
validate	Check the config file for structural errors

Viewing the Active System

To see what design system is currently configured for a project:

# CLI
cat .ibr/design-system.json

# MCP tool
design_system action: "get"

The scan output's designSystem field always reports which config was used, including the config version and name. If no config is present, designSystem will be null and no principle or token checks will run.

ibr — design system