{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://designsystemdocspec.org/v0.15.2/document-blocks/principles.schema.json",
"title": "Principles document block",
"description": "The beliefs behind a foundation's decisions — each a short title plus what it means in practice. Principles answer 'what do we believe?' and sit above individual `guidelines`, shaping the whole approach to a domain (ex: 'Functional first' for color, 'Use the scale' for spacing).",
"$defs": {
"principleEntry": {
"type": "object",
"description": "One principle: a short title and what it means in practice. Principles set direction, not specific rules — for actual rules, use `guidelines`; for whether to use something at all, use `use-cases`.",
"required": [
"title",
"description"
],
"properties": {
"title": {
"type": "string",
"description": "A short, memorable name (ex: 'Functional first', 'Use the scale') — short enough to work as a heading."
},
"description": {
"$ref": "../common/rich-text.schema.json#/$defs/richText",
"description": "What the principle means in practice — not just a restatement of the title. Answer: what does this look like day to day, and how would you use it to settle a disagreement?"
}
},
"additionalProperties": false
},
"principles": {
"type": "object",
"description": "The beliefs behind a foundation's decisions — what the system believes and which trade-offs it accepts. Sits above `guidelines`: principles set direction, guidelines encode the specific rules. E.g., a spacing foundation might have 'Use the scale'; a color foundation might have 'Functional first'.",
"required": [
"kind",
"items"
],
"properties": {
"kind": {
"type": "string",
"const": "principles",
"description": "Identifies this block as a principles spec."
},
"items": {
"type": "array",
"description": "The principles, in order. Tools SHOULD keep this order; authors SHOULD lead with the most important.",
"items": {
"$ref": "#/$defs/principleEntry"
},
"minItems": 1
}
},
"additionalProperties": false
}
}
}
Identifies this block as a principles spec.The principles, in order. Tools SHOULD keep this order; authors SHOULD lead with the most important. Min items: 1References:principleEntry{
"kind": "principles",
"items": [
{
"title": "Functional first",
"description": "Color carries meaning before it carries style. Choose a color for the role it plays — danger, success, emphasis — and let the palette follow from those roles rather than from brand decoration."
},
{
"title": "Accessible by default",
"description": "Every foreground and background pairing in the system meets WCAG 2.2 AA contrast. A color combination that fails contrast is not offered as an option, so teams cannot reach for an inaccessible pairing by accident."
},
{
"title": "Semantic, not literal",
"description": "Reference colors by their role ('color-text-danger'), never by their value ('red-600'). This lets the system retheme — including dark mode — without touching product code."
}
]
}A short, memorable name (ex: 'Functional first', 'Use the scale') — short enough to work as a heading.What the principle means in practice — not just a restatement of the title. Answer: what does this look like day to day, and how would you use it to settle a disagreement?References:richText[
{
"title": "Use the scale",
"description": "Every spacing value comes from the spacing scale. Reach for the nearest scale step rather than a custom value. When two adjacent steps both seem wrong, the layout — not the scale — usually needs rethinking."
},
{
"title": "Density over decoration",
"description": "Spacing exists to group and separate content, not to fill the canvas. Prefer the smallest spacing that still makes the grouping clear, so more content stays within reach without scrolling."
},
{
"title": "Consistent rhythm",
"description": "Related elements share the same spacing so the eye can predict where the next item begins. Vary spacing only to signal a change in relationship, never for visual variety alone."
}
]