workbuddy_skills/open-design/design-systems/tom-modern/DESIGN.md

Tom Modern Design

Category: Starter Editorial-technical design system. Neutral canvas, single vermillion accent, sharp corners, Geist typography, hard shadows, structured composition.

1. Visual Theme & Atmosphere

Tom Modern Design is an editorial-technical design family: structured, sharp, restrained, premium, intentional, anti-generic. It reads like a deliberate design — not a mass-generated startup template.

The system sits on a near-white neutral canvas (#fafafa) with deep ink text (#27272a). One primary accent — vermillion (#ff5a00) — carries all interactive emphasis. Typography is Geist Sans for body and Geist Mono for labels, metadata, and technical notes. Every corner is sharp (0px radius). Shadows are hard-offset, never soft.

Atmosphere comes from a subtle 30px grid overlay on the page background, structural lines, and the contrast between quiet white zones and dense information bands. The design avoids decorative noise — no blobs, no gradients, no glow effects.

Key signals:

• Neutral near-white canvas with strong ink contrast
• Single vermillion accent reserved for CTAs, links, and highlights
• Sharp 0px corners throughout — rectangular silhouette is the brand
• Hard offset shadows (8px 8px 0) for elevation
• Geist Sans/Mono typography with strong hierarchy
• Editorial split layouts with asymmetric composition
• Uppercase compact labels for eyebrows and metadata

Anti-patterns to avoid:

• Generic centered startup heroes
• Purple gradients by default
• Rounded cards and buttons
• Beige or cream backgrounds
• Blob-based decorative elements
• Repetitive identical card grids

2. Color Palette & Roles

Primary

Token	Hex	Role
--accent	#ff5a00	Primary accent — CTAs, links, interactive highlights, accent words

Surfaces

Token	Hex	Role
--bg	#fafafa	Page background — neutral near-white, never warm
--surface	#ffffff	Card and panel surfaces
--surface-warm	var(--surface)	Alternate surface for section rhythm (aliases to surface)

Text

Token	Hex	Role
--fg	#27272a	Primary text — headlines, body, buttons
--fg-2	#52525b	Secondary text — descriptions, lead paragraphs
--muted	#71717a	Muted text — captions, labels, metadata

Borders

Token	Hex	Role
--border	#969696	Primary borders — card outlines, structural lines
--border-soft	#d4d4d8	Muted borders — subtle separators

Shadows (brand-specific)

Token	Value	Role
--tm-shadow-hard	8px 8px 0 rgba(150,150,150,0.12)	Hard offset shadow — hover states, emphasis
--tm-shadow-soft	4px 4px 0 rgba(150,150,150,0.1)	Soft offset shadow — default card state

Code Window (brand-specific)

Token	Hex	Role
--tm-code-bg	#111517	Code window background
--tm-code-panel	#151a1d	Code window header
--tm-code-text	#d8dee9	Code text

Background Pattern

The page background uses a 30px grid:

background-image:
    linear-gradient(rgba(150, 150, 150, 0.04) 1px, transparent 1px),
    linear-gradient(90deg, rgba(150, 150, 150, 0.04) 1px, transparent 1px);
background-size: 30px 30px;

3. Typography Rules

Font Families

• Primary: Geist Sans — body, headlines, buttons, navigation
• Mono: Geist Mono — labels, metadata, code, technical notes

Hierarchy

Token	Size	Weight	Line Height	Letter Spacing	Use
Display	clamp(2.3rem, 5vw, 4.8rem)	700	0.96	-0.04em	Hero headlines
Section	clamp(21px, 2vw, 25px)	700	1.15	-0.03em	Section titles
Card	18px	700	1.38	-0.03em	Card titles
Body	14px	400	1.6	0	Body text
Caption	12px	400	1.4	0	Captions, fine print
Eyebrow	12px	700	1	0.14em	Uppercase labels
Button	13px	700	1	0.08em	Button labels
Mono	12px	700	1	0.14em	Technical labels

Principles

• Geist Sans runs across every surface — display, body, UI, buttons
• Geist Mono is reserved for labels, metadata, code, and technical microcopy
• Display headlines use weight 700 with tight line-height (0.96–1.15)
• Body text uses weight 400 with generous line-height (1.6)
• Uppercase labels use 0.14em letter-spacing for the "machined" feel
• One accent word per headline: <span class="title-highlight">word</span>

Font Substitutes

If Geist is unavailable:

• Inter at weights 400/500/600/700 — slightly narrower; bump font-size by ~3%
• Manrope at weights 400/500/600/700 — closer proportion, gentler curves
• IBM Plex Sans at weights 400/500/600/700 — wider, more mechanical feel

4. Component Stylings

Buttons

• Primary: Dark fill (--fg), white text, 0px radius, hard shadow on hover
• Secondary: Transparent, dark text, 1px border, white fill on hover
• Block: Full-width variant of any button

Cards

• Frame: White surface, 1px border, soft shadow
• Panel: White surface, 1px border, hard shadow, accent top-border (4px)
• Feature card: 2-column grid with optional full-width variant
• Feature 3-card: 3-column grid with icon headers

Navigation

• Header: Sticky, blurred background (rgba(250,250,250,0.88)), 1px bottom border
• Nav links: Geist Sans, secondary text color
• CTA button: Dark fill, same as primary button

Forms

• Input: White background, 1px border, 44px height, accent border on focus
• Textarea: Same as input, resizable
• Label: Mono font, uppercase, muted color

Premium Components

• Token Card: Dark gradient (#14192B → #1B2A3D → #11393A), holographic sheen animation, mono typography, perforation line with circular cutouts
• Code Window: Dark background (#111517), macOS-style traffic light dots, atmospheric gradient overlay, 7 syntax highlighting tokens

Tabs

• Tab nav: Horizontal, mono font, uppercase, accent bottom-border on active
• Tab panel: Hidden by default, shown with .is-active class

FAQ

• Item: Frame with expandable answer
• Question: Full-width button, plus/minus icon
• Answer: Hidden by default, shown when .is-open

5. Layout Principles

Container

• Max width: 1240px
• Padding: min(100% - 40px, 1240px)
• Centered with margin: 0 auto

Section

• Vertical padding: 96px
• Alternate sections use rgba(255,255,255,0.72) background with 1px borders

Grid System

• Hero: 2-column split (0.92fr / 1.08fr) with 42px gap
• Feature grid: 2-column with optional full-width cards
• Feature 3-col: 3-column with icon headers
• Updates/Pain: 3-column grid
• Pricing/Contact: 2-column split
• Footer: 3-column (2fr / 1fr / 1fr)

Section Rhythm

Sections alternate between:

1. White background (--bg)
2. Alternate surface (rgba(255,255,255,0.72) with borders)

This creates visual rhythm without color changes.

6. Depth & Elevation

Level	Treatment	Use
0 — Flat	No shadow, no border	Body text, section backgrounds
1 — Border	1px --border border	Cards, panels, inputs
2 — Soft shadow	4px 4px 0 rgba(150,150,150,0.1)	Default card state
3 — Hard shadow	8px 8px 0 rgba(150,150,150,0.12)	Hover states, emphasis
4 — Code shadow	0 28px 90px rgba(22,22,22,0.14)	Code window only

The system uses color contrast (surface vs. background) rather than shadow depth for hierarchy. Shadows are reserved for interactive feedback and premium components.

7. Do's and Don'ts

Do

• Use {colors.primary} for CTAs, links, and interactive highlights — keep it reserved
• Set display headlines in Geist Sans at weight 700 with tight line-height
• Keep body copy at weight 400 — the contrast between heavy display and light body is the typographic signature
• Use {rounded.none} (0px) by default — the sharp rectangular silhouette IS the brand
• Align spacing to {spacing.section} (96px) between major bands
• Frame product photography inside {rounded.xl} containers
• Set button labels in uppercase with 0.08em letter-spacing
• Use hard shadows for hover effects, soft shadows for default state
• Use {typography.button} for all button labels

Don't

• Don't introduce accent colors outside the detected palette — the system is closed by design
• Don't bold body type — body stays at weight 400
• Don't add soft drop-shadows or atmospheric gradients — the brand uses hard borders and flat fills
• Don't round buttons above {rounded.sm} — a soft button reads as a different brand
• Don't use beige or cream backgrounds — the canvas must be neutral (#fafafa)
• Don't use decorative motion everywhere — animation must be purposeful
• Don't drop ink text opacity to create hierarchy — switch surface or shift to {colors.muted}
• Don't use multiple accent words in one heading — one per section maximum

8. Responsive Behavior

Breakpoints

Name	Width	Key Changes
Mobile	< 560px	Single column, compact padding (24px), smaller type
Tablet	560–980px	2-column grids, stacked hero
Desktop	> 980px	Full layout, 1240px max-width

Touch Targets

• Minimum 44×44px for all interactive elements
• Buttons: 44px height + 24px horizontal padding
• Nav links: extend tap area to full row height

Collapsing Strategy

• Hero: Stacks to single column below 980px
• Feature grids: 2-col → 1-col below 980px
• 3-col grids: 3-col → 2-col → 1-col
• Footer: 3-col → 2-col → 1-col
• Navigation: Hamburger menu on mobile (not included in CSS — implement per project)

Image Behavior

• Hero photography fills full width
• Product thumbnails maintain aspect ratio
• Lifestyle photography uses horizontal cropping on mobile

9. Agent Prompt Guide

Quick Color Reference

Background:  #fafafa (neutral near-white)
Surface:     #ffffff (pure white)
Text:        #27272a (near-black)
Secondary:   #52525b
Muted:       #71717a
Accent:      #ff5a00 (vermillion)
Border:      #969696
Border-muted: #d4d4d8

Ready-to-Use Prompt

Create a landing page in Tom Modern Design style:

- Background: #fafafa with 30px grid overlay
- Typography: Geist Sans for body, Geist Mono for labels
- Colors: #27272a text, #ff5a00 accent, #ffffff surfaces
- Corners: 0px (sharp, never rounded)
- Shadows: 8px 8px 0 rgba(150,150,150,0.12) on hover
- Layout: split hero, 2-col feature grid, structured sections
- Buttons: uppercase, 0.08em letter-spacing, dark fill primary
- Cards: white surface, 1px border, soft shadow
- Sections: alternate between white and rgba(255,255,255,0.72)
- One accent word per headline using <span class="title-highlight">
- Eyebrows: uppercase mono labels above section titles

Required Font Loading

When generating HTML with Tom Modern, load Geist explicitly. tokens.css declares the Geist Sans and Geist Mono family names, but generated artifacts do not automatically inherit the @font-face block from components.html.

Use this loader before any generated CSS that references --font-display, --font-body, or --font-mono:

@font-face {
    font-family: 'Geist Sans';
    src: url('https://cdn.jsdelivr.net/npm/[email protected]/dist/fonts/geist-sans/Geist-Variable.woff2') format('woff2');
    font-weight: 100 900;
    font-display: swap;
}

@font-face {
    font-family: 'Geist Mono';
    src: url('https://cdn.jsdelivr.net/npm/[email protected]/dist/fonts/geist-mono/GeistMono-Variable.woff2') format('woff2');
    font-weight: 100 900;
    font-display: swap;
}

If the host project can self-serve fonts, prefer bundling equivalent local woff2 files under fonts/ while keeping the same family names.

Component Classes

/* Layout */
.container          /* max-width 1240px, centered */
.section            /* 96px vertical padding */
.section-alt        /* alternate background */
.frame              /* card with border + shadow */

/* Typography */
.eyebrow            /* uppercase mono label */
.title-highlight    /* accent-colored text */
.section-head       /* section header */

/* Buttons */
.button             /* base button */
.button-primary     /* dark filled */
.button-secondary   /* transparent outlined */
.button-block       /* full-width */

/* Hero */
.hero-grid          /* 2-col layout */
.hero-lead          /* lead paragraph */
.hero-actions       /* button group */

/* Features */
.feature-grid       /* 2-col with wide cards */
.feature-3col       /* 3-col with icons */

/* Interactive */
.tab-shell          /* tab container */
.faq-item           /* accordion item */

/* Premium */
.key-card           /* dark gradient with sheen */
.tm-code-window     /* code editor display */