DSDS Scale Guideline

2 definitions in this file:

scaleStep
scale

The token name for this step. MUST reference a token defined in the token schema (e.g., 'space-4', 'font-size-300', 'elevation-low'). This is the single source of truth for the step's value — the optional `value` property is a display convenience only.

A human-readable label for this step (e.g., 'sm', 'md', 'lg', '2xl', 'body', 'heading-1'). Labels provide a shorthand vocabulary that designers and engineers use to communicate about scale positions without referring to raw values.

The resolved value for display (e.g., '16px', '1rem', '#1a1a1a', '400'). This is a docs convenience — the authoritative value lives in the referenced token. Tools MAY populate this from the token catalog.

Usage notes for this step — when to use it, what it pairs with, and any constraints (e.g., 'The base unit. Use for default internal component padding.', 'Reserved for page-level hero sections only.').

References:

richText

Identifies this guideline as a scale spec.

Machine-readable name of the scale (e.g., 'spacing-scale', 'type-scale', 'elevation-scale'). Used for cross-referencing and tooling.

What this scale is, how it was constructed (e.g., geometric progression, modular scale), and the rules for using it. Document the scale's rationale and constraints — why these values were chosen and when deviation is appropriate.

The ordered steps in the scale, from smallest/lowest to largest/highest. Ordering is significant — tools SHOULD preserve it for display. Consumers SHOULD treat adjacent steps as the natural next-smaller and next-larger options when adjusting a value.
Min items: 1

Human-readable name of the scale (e.g., 'Spacing Scale', 'Type Scale', 'Elevation Levels').

Agent-optimized context for this document block. Provides structured information for AI/LLM consumption — constraints, disambiguation, anti-patterns, examples, and keywords.

References: richText, scaleStep, agents