DSDS Principles Document Block

2 definitions in this file:

principles
principleEntry

Identifies this document block as a principles spec.

The guiding principles. Each item documents a single principle with a title and description. Ordering is significant, so tools SHOULD display principles in this order. Authors SHOULD order by importance or by the natural progression of the design philosophy.
Min items: 1

References:

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 for the principle (e.g., 'Functional first', 'Accessible by default', 'Use the scale', 'Density over decoration'). Should be concise enough to serve as a heading or reference label.

What this principle means and how it guides decisions. Explain the belief or constraint in concrete terms, not just restate the title. Good descriptions answer: 'What does this look like in practice?' and 'How would I use this to resolve 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." } ]