# @symbo.ls/scratch

> Φ / CSS framework and methodology.

Latest version **3.14.777** (published 2026-08-31) · 0 weekly downloads

## Install

```sh
npm install @symbo.ls/scratch
pnpm add @symbo.ls/scratch
yarn add @symbo.ls/scratch
bun add @symbo.ls/scratch
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 3.14.777 |
| Published | 2026-08-31 |
| First published | 2021-12-03 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 175 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | symbo.ls |
| Maintainers | elanor, nikoloza, bala-symbols, gallenjohnson, tiny, zajim, lberia, svinchy, chejuichen, tokoyoung, baronsilver, zacharybetzen, bsachdeva, tthomasagg, bneeli33 |

## Links

- npm: https://www.npmjs.com/package/@symbo.ls/scratch
- Repository: https://github.com/symbo-ls/smbls
- Homepage: https://github.com/symbo-ls/smbls#readme
- Issues: https://github.com/symbo-ls/smbls/issues
- npm.io page: https://npm.io/package/@symbo.ls/scratch

## Dependencies (3)

- [@symbo.ls/utils](https://npm.io/package/@symbo.ls/utils.md) ^3.14.707
- [@symbo.ls/signal](https://npm.io/package/@symbo.ls/signal.md) ^3.14.628
- [color-contrast-checker](https://npm.io/package/color-contrast-checker.md) ^1.5.0

## Recent versions

- 3.14.777 (latest) — 2026-08-31
- 3.14.776 — 2026-08-28
- 3.14.775 — 2026-08-26
- 3.14.774 — 2026-08-11
- 3.14.773 — 2026-08-11
- 3.14.771 — 2026-08-11
- 3.14.769 — 2026-08-11
- 3.14.766 — 2026-08-11
- 3.14.753 — 2026-08-09
- 3.14.752 — 2026-08-09
- 3.14.749 — 2026-08-09
- 3.14.707 — 2026-08-08
- 3.14.702 — 2026-08-07
- 3.14.700 — 2026-08-07
- 3.14.697 — 2026-08-07
- … 646 more at https://npm.io/package/@symbo.ls/scratch/versions

## README

# 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.

[![npm version](https://badge.fury.io/js/%40rackai%2Fscratch.svg)](https://badge.fury.io/js/%40rackai%2Fscratch)

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:

```javascript
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.

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

Generated CSS:

```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:

```javascript
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:

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

Generates comma-separated `src` with auto-detected formats:

```css
@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](https://www.symbols.app/developersdesign-system)

### TODO:
- [ ] Accessibility (WCAG) automated  tests
- [x] Scratch on `node`

---
_Source: https://npm.io/package/@symbo.ls/scratch · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._