@symbo.ls/scratch

Scratch framework

Design system factory for Symbols. Receives a configuration and outputs resolved design tokens (colors, themes, fonts, spacing, media queries). In v3.14, Scratch feeds into the atomic CSS engine (@symbo.ls/css) for class generation.

Receives a configuration and outputs the system of design related properties. It also applies reset by default and receives a few options:

option	default	description
verbose	false	Output the warning logs in console (only in dev, test enviroment)
useReset	true	Apply CSS reset to the document
useVariable	true	Output CSS variables in properties
globalTheme	'auto'	Theme mode: 'auto' (system preference), 'dark', 'light', or any custom theme name
useThemeSuffixedVars	false	Also generate suffixed vars like --theme-document-dark-background

A design system configuration of the following systems:

import { set } from '@symbo.ls/scratch'

set({
  color: {},
  theme: {},
  typography: {},
  space: {},
  media: {},
  icons:{},
  font: {},
  font_family: {},
  timing: {},
  reset: {},
  vars: {}
}, {
  // options
})

Theme System

Themes with @dark/@light (or custom @ocean, @sunset, etc.) variants automatically generate non-suffixed CSS variables that switch via CSS — no JavaScript re-renders needed.

set({
  theme: {
    document: {
      '@dark': { color: 'white', background: 'black' },
      '@light': { color: 'black', background: 'white' },
      '@ocean': { color: 'white', background: '#0a2e4e' }
    }
  }
})

Generated CSS:

/* System theme auto-switching (when no data-theme attribute is set) */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme]) { --theme-document-background: #000; --theme-document-color: #fff; }
}
@media (prefers-color-scheme: light) {
  :root:not([data-theme]) { --theme-document-background: #fff; --theme-document-color: #000; }
}

/* Explicit theme forcing via data-theme attribute */
[data-theme="dark"]  { --theme-document-background: #000; --theme-document-color: #fff; }
[data-theme="light"] { --theme-document-background: #fff; --theme-document-color: #000; }
[data-theme="ocean"] { --theme-document-background: #0a2e4e; --theme-document-color: #fff; }

Theme switching

• Auto (default): system prefers-color-scheme drives dark/light switching
• Force a theme: set data-theme attribute on the root element — instant CSS switch, zero re-renders
• Custom themes: add any @name variant to your theme config, activate with data-theme="name"
• Per-component override: use themeModifier prop to force a specific scheme on individual components

globalTheme option

Value	Behavior
'auto' (default)	@dark/@light use prefers-color-scheme media queries. Custom themes use [data-theme] selectors.
'dark' / 'light' / 'custom'	Non-suffixed vars are set directly in :root with the forced theme's values.

useThemeSuffixedVars option

When true, also generates suffixed variables like --theme-document-dark-background alongside the non-suffixed --theme-document-background. Disabled by default to reduce CSS variable count.

CSS Custom Properties (vars)

Define initial CSS custom properties in the design system:

set({
  vars: {
    '--header-height': '60px',
    'sidebar-width': '280px',   // auto-prefixed to --sidebar-width
    'gap': '1rem'               // becomes --gap
  }
})

Each entry is written to :root CSS custom properties. Keys without -- prefix get it added automatically. Values can be referenced in component props: padding: '--gap' → var(--gap).

Font — Array URL Support

Font definitions support array URLs for multiple format fallbacks:

set({
  font: {
    Exo2: [
      {
        url: ['Exo2-Medium.woff2', 'Exo2-Medium.woff'],
        fontWeight: '500',
        fontStyle: 'normal',
        fontDisplay: 'swap'
      }
    ]
  }
})

Generates comma-separated src with auto-detected formats:

@font-face {
  font-family: 'Exo2';
  font-style: normal;
  font-weight: 500;
  font-display: swap;
  src: url('Exo2-Medium.woff2') format('woff2'),
       url('Exo2-Medium.woff') format('woff');
}

Read more at docs

TODO:

• Accessibility (WCAG) automated tests
• Scratch on node