Dezine Zync

Technical Design Specification: High-Fidelity macOS Web Migration

This document outlines the technical architecture and design principles used to migrate a Jekyll/Eleventy blog from a remote theme (e.g., LaunchKit) to a custom, high-fidelity SCSS framework inspired by modern and classic Macintosh Human Interface Guidelines (HIG), specifically modeled after Mario Guzman’s design language.

1. Architectural Strategy

The migration follows a “decoupled” approach, moving all styling logic from external dependencies to a local, modular SCSS structure.

SCSS Directory Structure

• _sass/variables.scss: Centralized design tokens (colors, fonts, sizing).
• _sass/_base.scss: Reset, layout primitives, and typography defaults.
• _sass/layouts/: Component-specific styles (e.g., blog.scss, apps.scss).
• assets/css/style.scss: Entry point and import orchestration.

2. Design Principles

The design adheres to the following core tenets:

• System Fidelity: Utilizing platform-native typography and interaction patterns.
• Minimalist Structure: High signal-to-noise ratio with clear vertical rhythm.
• Macintosh Metrics: Strict adherence to 20px (20pt) standard margins and specific spacing rules.

3. Layout Primitives

.container

The foundational wrapper for content alignment.

• Margin: Centered via margin: 0 auto.
• Padding: 20px horizontal padding to match Macintosh window margins.
• Scaling: Uses max-width breakpoints (720px, 960px, 1140px) to maintain balance on larger displays.

.readable

A specialized modifier for long-form text content.

• Max-Width: Strictly capped at 680px (approximately 65-75 characters per line) to optimize reading speed and reduce eye strain.

.grid

A flexible flexbox-based utility for horizontal alignment.

• Gap: Standardized 1rem (16px) or 1.5rem (24px) spacing between elements.

4. Typography System

Font Stack

Prioritizes Apple’s system fonts for a “native” feel.

font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", "SF Pro Icons", "Helvetica Neue", Helvetica, Arial, sans-serif;

Hierarchy & Weights

• Headers (h1-h6): Bold (font-weight: 700 or 800) with a tight line-height: 1.2.
• Body Text: font-size: 1.05rem with a comfortable line-height: 1.6.
• Post Titles: 1.4rem to 1.5rem for prominent entry points.
• Meta Info: 0.85rem using --dz-subtitle-color for secondary information.

5. Component Specifications

Header & Navigation

• Architecture: Flexbox-based (row on desktop, column on mobile).
• Navigation: Clean list-based links with 1.5rem gap and subtle hover states.
• Vertical Alignment: Baseline alignment for the logo and navigation to maintain a structured horizon.

Article Content (.article-content)

• Spacing: 1.25rem bottom margin on paragraphs.
• Blockquotes: 4px left border using the brand color, with a subtle var(--dz-grouped-background-color) background.
• Images: Rounded corners (4px to 8px) with automatic centering and responsive max-width: 100%.

Horizontal Rules (hr)

• Styling: 1px solid border using var(--dz-border-color).
• Spacing: Large 2rem vertical margins to provide clear thematic breaks between sections.

6. Color System (CSS Variables)

Utilizes semantic CSS variables for effortless Light and Dark mode transitions.

Token	Light Mode	Dark Mode	Purpose
--dz-brand-color	#007aff	#0a84ff	Links, accents, borders
--dz-background-color	#ffffff	#1c1c1e	Primary page background
--dz-title-color	#1c1c1e	#f2f2f7	Headers and primary text
--dz-subtitle-color	#8e8e93	#8e8e93	Meta text and descriptions
--dz-border-color	#d1d1d6	#3a3a3c	Separators and input borders

7. Migration Checklist for LLM Agents

When performing a similar migration for a new site:

1. Audit Layouts: Identify where .container, .readable, and .no-style classes are used.
2. Define Variables: Establish the core color palette and font stacks in variables.scss.
3. Bootstrap Base: Implement the .container and .readable primitives in _base.scss.
4. Refactor Components: Move component-specific logic (e.g., navigation, post lists) into dedicated layout files.
5. Remove Dependencies: Deactivate the legacy theme (e.g., remove remote_theme from config).
6. Surgical Cleanup: Remove legacy classes like no-style from HTML layouts to allow the new SCSS to propagate.
7. Validate: Verify the vertical rhythm, responsive breakpoints, and Dark Mode switching.