# Val Town · Design system migration spec

> Source: https://www.val.town  ·  Curated by OpenDesign  ·  en

> A great example of a modern developer tool that balances technical capability with a warm, approachable, and non-intimidating visual design.

## 1. Identity DNA

Val Town's design system is built on the analogy of a welcoming local cafe for developers—a place where complexity is stripped away in favor of instant, friendly utility. The visual identity translates this into a system of clean surfaces, clear type, and a single, vibrant accent that signals action without noise.

**One-liner:** A friendly serverless platform for writing and deploying JavaScript instantly.
**Keywords:** developer · platform · serverless · javascript · simple
**Analogy:** A welcoming local cafe for developers to quickly deploy scripts

## 2. Color

The palette operates on a high-contrast foundation of crisp white and deep black, ensuring readability and focus. A single, vibrant cyan (#2EC4FF) is reserved for primary actions, creating a clear and energetic focal point against the monochrome field.

| Token | Value | Use |
|---|---|---|
| `--bg` | `#FFFFFF` | main background |
| `--bg-soft` | `#F7F9FC` | card background |
| `--bg-quiet` | `#1C2433` | quiet area |
| `--ink` | `#000000` | body text |
| `--ink-soft` | `#4B5563` | secondary text |
| `--muted` | `#6B7280` | placeholder |
| `--muted-soft` | `#9CA3AF` | weak hint |
| `--accent` | `#2EC4FF` | single accent |
| `--line` | `rgba(0,0,0,0.1)` | divider |

**Color principle:** High-contrast dark-on-light foundation with a single vibrant cyan accent for primary actions.

The guiding principle is restraint: a single accent color on a neutral stage keeps the interface calm and the developer's focus on their code.

## 3. Typography

Typography follows a three-tier hierarchy: a geometric sans-serif for bold, structural headings; a humanist sans-serif for clear body copy; and a slab-mono for code snippets. This combination establishes a voice that is technically competent yet approachable, avoiding both sterility and jargon.

- **Display:** geometric-sans
- **Body:** humanist-sans
- **Mono:** slab-mono

| Token | Size | Line-height | Weight | Letter-spacing | Use |
|---|---|---|---|---|---|
| display | 48px | 1.0 | 700 | -0.02em | Main page titles and hero headings |
| headline | 36px | 1.1 | 700 | -0.01em | Section headings and testimonials |
| body | 16px | 1.5 | 400 | 0em | General reading text |
| caption | 14px | 1.4 | 400 | 0em | Secondary text and descriptions |
| code | 16px | 1.5 | 400 | 0em | Code snippets and terminal output |

## 4. Spacing

A base-4 rhythm underpins the layout, with generous vertical padding—typically 96px—creating clear, breathable separation between content sections.

- **Base unit:** 4px
- **Scale:** 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96 px
- **Rhythm:** A base-4 system with generous vertical padding between sections, typically 96px, ensuring clear visual separation.

## 5. Surfaces

Depth is communicated through subtle shadows on floating elements like cards and composite images, not through heavy, pervasive effects. Borders are kept minimal and transparent, using a light rgba stroke to define edges without visual weight.

- **Radius:** sm 4px · md 8px · lg 16px · pill 999px
- **Shadows:**
  - 0 20px 25px -5px rgba(0,0,0,0.1)
  - 0 10px 15px -3px rgba(0,0,0,0.1)
  - 0 8px 10px -6px rgba(0,0,0,0.1)
- **Borders:** 1px solid rgba(0,0,0,0.1)

## 6. Layout

The structural skeleton begins with a centered hero section, split between left-aligned copy and a right-aligned composite image of the product. Subsequent content sections are stacked vertically, using the generous spacing rhythm to maintain clarity and hierarchy.

- **Container max:** 1280px
- **Paragraph max:** 680px
- **Grid:** 12 columns, gutter 24px
- **Breakpoints:** 768 / 1024 px

**Skeleton:** A centered hero section with text on the left and a complex overlapping composite image on the right, followed by stacked content sections.

## 7. Motion & Interaction

Motion is utilitarian and lightweight, confined to standard 150-200ms transitions for interactive feedback. The philosophy is functional polish: animations confirm user actions (hover, focus, click) without introducing narrative or delay.

- **Durations:** micro 150ms · small 200ms · medium 400ms
- **Easing:** `cubic-bezier(0.4, 0, 0.2, 1)`
- **Patterns:**
  - Standard color and background-color transitions for interactive elements
  - Smooth hover and focus state changes for buttons and links

- **Hover:** Subtle background color shift or opacity change on buttons and links.
- **Click:** Immediate visual feedback with background color transition.
- **Transition:** All interactive properties transition smoothly over 150ms to 200ms using a standard ease-out curve.
- **Keyboard:** Standard focus rings or outlines for keyboard navigation.

## 8. Voice & Don'ts

The editorial voice is direct, benefit-oriented, and casually welcoming, using simple action verbs like 'Start' and 'Copy' for CTAs. It deliberately avoids aggressive sales language, formal corporate phrasing, and overly complex technical jargon.

- **Tone:** Friendly, approachable, and slightly playful, yet technically competent.
- **Headline style:** Direct, benefit-oriented, and written in a casual, welcoming tone.
- **CTA style:** Action-oriented, using simple verbs like 'Start' or 'Copy' to encourage immediate engagement.
- **Avoid:** Overly complex or jargon-heavy technical language / Aggressive or urgent sales-driven copy / Formal, stiff, or corporate-sounding phrasing

### Don'ts
- ❌ Don't use serif typography for headlines — the screenshot shows bold, geometric sans-serif typefaces throughout.
- ❌ Don't use a dark theme as the default — the primary background is a clean, bright white.
- ❌ Don't use harsh, saturated accent colors — the primary accent is a bright but approachable cyan (#2EC4FF).
- ❌ Don't use sharp, square corners — the UI features rounded corners, often with a pill shape (999px) for buttons.
- ❌ Don't use heavy drop shadows everywhere — shadows are subtle, used primarily on floating cards and composite images.
- ❌ Don't make the layout dense — the design uses generous whitespace and padding, especially between major sections.

What is deliberately absent is a dark mode default, sharp corners, dense layouts, and any visual language that prioritizes intimidation over invitation.

## System Prompt (paste into AI tool)

```
Val Town is a friendly developer tool for instantly deploying JavaScript, characterized by a clean, approachable aesthetic. Key colors include a crisp white background (#FFFFFF), deep black text (#000000), and a vibrant cyan accent (#2EC4FF) for primary calls to action. The typography uses a geometric sans-serif for bold headings, a humanist sans-serif for body text, and a slab-mono for code. Critical design rules include: Don't use dark mode as the primary layout; the screenshot shows a bright, white-dominant interface. Don't use sharp, square corners; the UI uses rounded corners and pill-shaped buttons extensively. Don't use dense layouts; generous whitespace and clear visual hierarchy are essential. The tone is casual and welcoming, avoiding overly technical jargon.
```
