Foundations

Foundations define the design tokens that form the visual foundation of your design system: colors, typography, spacing, and more.

File Location

my-design-system/
└── foundations/
    ├── colors.json
    ├── typography.json
    ├── spacing.json
    └── border-radius.json

Colors

Schema

{
  "colors": [
    {
      "id": "primary",
      "value": "hsl(222.2 47.4% 11.2%)",
      "semantic": "primary",
      "usage": "Primary brand color for CTAs"
    }
  ]
}

Fields

Field	Type	Required	Description
id	string	Yes	Unique token identifier
value	string	Yes	Color value (hex, hsl, rgb)
semantic	string	No	Semantic category
usage	string	No	Usage description

Example

{
  "colors": [
    {
      "id": "background",
      "value": "hsl(0 0% 100%)",
      "semantic": "background",
      "usage": "Primary page background"
    },
    {
      "id": "foreground",
      "value": "hsl(222.2 84% 4.9%)",
      "semantic": "foreground",
      "usage": "Primary text color"
    },
    {
      "id": "primary",
      "value": "hsl(222.2 47.4% 11.2%)",
      "semantic": "primary",
      "usage": "CTAs and key interactive elements"
    },
    {
      "id": "destructive",
      "value": "hsl(0 84.2% 60.2%)",
      "semantic": "destructive",
      "usage": "Error states and destructive actions"
    }
  ]
}

Typography

Schema

{
  "fontFamilies": [...],
  "fontSizes": [...],
  "fontWeights": [...],
  "lineHeights": [...],
  "typeScale": [...]
}

Font Families

{
  "fontFamilies": [
    {
      "id": "sans",
      "name": "Sans Serif",
      "stack": "ui-sans-serif, system-ui, sans-serif",
      "usage": "Primary UI text"
    },
    {
      "id": "mono",
      "name": "Monospace",
      "stack": "ui-monospace, SFMono-Regular, monospace",
      "usage": "Code and technical content"
    }
  ]
}

Font Sizes

{
  "fontSizes": [
    { "id": "xs", "value": "0.75rem" },
    { "id": "sm", "value": "0.875rem" },
    { "id": "base", "value": "1rem" },
    { "id": "lg", "value": "1.125rem" },
    { "id": "xl", "value": "1.25rem" },
    { "id": "2xl", "value": "1.5rem" },
    { "id": "3xl", "value": "1.875rem" },
    { "id": "4xl", "value": "2.25rem" }
  ]
}

Font Weights

{
  "fontWeights": [
    { "id": "normal", "value": 400 },
    { "id": "medium", "value": 500 },
    { "id": "semibold", "value": 600 },
    { "id": "bold", "value": 700 }
  ]
}

Spacing

Schema

{
  "baseUnit": "0.25rem",
  "scale": [...]
}

Example

{
  "baseUnit": "0.25rem",
  "scale": [
    { "id": "0", "value": "0" },
    { "id": "1", "value": "0.25rem" },
    { "id": "2", "value": "0.5rem" },
    { "id": "3", "value": "0.75rem" },
    { "id": "4", "value": "1rem" },
    { "id": "6", "value": "1.5rem" },
    { "id": "8", "value": "2rem" },
    { "id": "12", "value": "3rem" },
    { "id": "16", "value": "4rem" },
    { "id": "24", "value": "6rem" }
  ]
}

Border Radius

{
  "borderRadius": [
    { "id": "none", "value": "0" },
    { "id": "sm", "value": "0.125rem" },
    { "id": "md", "value": "0.375rem" },
    { "id": "lg", "value": "0.5rem" },
    { "id": "xl", "value": "0.75rem" },
    { "id": "full", "value": "9999px" }
  ]
}

Generated Output

When you run dss generate --css, foundations are converted to CSS custom properties:

@theme {
  --color-background: hsl(0 0% 100%);
  --color-foreground: hsl(222.2 84% 4.9%);
  --color-primary: hsl(222.2 47.4% 11.2%);

  --font-sans: ui-sans-serif, system-ui, sans-serif;
  --font-mono: ui-monospace, SFMono-Regular, monospace;

  --text-xs: 0.75rem;
  --text-sm: 0.875rem;
  --text-base: 1rem;

  --spacing-0: 0;
  --spacing-1: 0.25rem;
  --spacing-2: 0.5rem;

  --radius-sm: 0.125rem;
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
}