Markdown Converter
Agent skill for markdown-converter
This document outlines the design system and guidelines for constructing a modern UX portfolio based on the established style guide.
Sign in to like and favorite skills
This document outlines the design system and guidelines for constructing a modern UX portfolio based on the established style guide.
Primary Font: IBM Plex Sans (Google Fonts)
-apple-system, BlinkMacSystemFont, sans-serif'SF Mono', Monaco, monospace (for code/technical content)Typography System - CSS Variables:
All typography is standardized using CSS custom properties in
_variables.css. Each element has variables for size, weight, letter-spacing, and line-height.
/* Hero Title */ --typo-hero-title-size: clamp(48px, 8vw, 96px) --typo-hero-title-weight: 300 (Light) --typo-hero-title-spacing: -0.02em --typo-hero-title-line-height: 0.9 /* Subtitle */ --typo-subtitle-size: clamp(18px, 2.5vw, 32px) --typo-subtitle-weight: 400 (Regular) --typo-subtitle-line-height: 1.5 /* Section Title */ --typo-section-title-size: clamp(36px, 5vw, 48px) --typo-section-title-weight: 300 (Light) --typo-section-title-spacing: -0.02em --typo-section-title-line-height: 1.2 /* Section Subtitle */ --typo-section-subtitle-size: 16px --typo-section-subtitle-weight: 400 (Regular) --typo-section-subtitle-line-height: 1.7 /* Heading 1 */ --typo-h1-size: clamp(32px, 5vw, 48px) --typo-h1-weight: 300 (Light) --typo-h1-spacing: -0.02em --typo-h1-line-height: 1.2 /* Heading 2 */ --typo-h2-size: clamp(24px, 4vw, 32px) --typo-h2-weight: 400 (Regular) --typo-h2-spacing: -0.01em --typo-h2-line-height: 1.3 /* Heading 3 */ --typo-h3-size: clamp(20px, 3vw, 24px) --typo-h3-weight: 500 (Medium) --typo-h3-line-height: 1.4 /* Heading 4 */ --typo-h4-size: clamp(18px, 2.5vw, 20px) --typo-h4-weight: 500 (Medium) --typo-h4-line-height: 1.4 /* Heading 5 */ --typo-h5-size: clamp(16px, 2vw, 18px) --typo-h5-weight: 600 (Semi-Bold) --typo-h5-line-height: 1.5 /* Heading 6 */ --typo-h6-size: clamp(14px, 1.5vw, 16px) --typo-h6-weight: 600 (Semi-Bold) --typo-h6-line-height: 1.5 /* Body Text */ --typo-body-size: 16px (desktop), 12px (mobile) --typo-body-weight: 400 (Regular) --typo-body-line-height: 1.7 /* Small Text */ --typo-small-size: 14px --typo-small-weight: 400 (Regular) --typo-small-line-height: 1.6 /* Type Label */ --typo-label-size: 14px --typo-label-weight: 500 (Medium) --typo-label-spacing: 0.05em
Usage: All typography elements use these variables for consistency. To apply typography styles:
.my-heading { font-size: var(--typo-h2-size); font-weight: var(--typo-h2-weight); letter-spacing: var(--typo-h2-spacing); line-height: var(--typo-h2-line-height); }
Link System - CSS Variables:
All link styles are standardized using CSS custom properties in
_variables.css:
/* Link Styles */ --link-color: var(--color-accent) --link-hover-opacity: 0.5 --link-underline-height: 2px --link-underline-offset: -2px --link-transition: 0.3s ease --link-font-weight: 500 (Medium)
Standard Link Components:
Accent Link (
) - Standard link with animated underline.accent-link
color-mix()Accent Link with Arrow (
) - Navigation link with right arrow.accent-link-arrow
External Link (
) - For external resources opening in new tab.external-link
Usage:
<!-- Accent Link --> <a href="#section" class="accent-link">Internal link</a> <!-- Accent Link with Arrow --> <a href="/case-study" class="accent-link-arrow">Read the case study →</a> <!-- External Link --> <a href="https://example.com" target="_blank" class="external-link">View documentation ↗</a>
Primary Colors:
#0f0f0f (darker than neutral 900)#525252#737373Accent Colors (Temperature-based theming):
#15B5FF (cool blue for light mode)#ea580c (warm orange for dark mode)Color Theory & Theming Strategy:
The accent color system employs temperature-based theming to optimize visual comfort and hierarchy across both light and dark modes. This approach is grounded in color psychology and perceptual contrast principles:
Cool Accents for Light Mode:
#15B5FF) provides strong chromatic contrast against warm white backgroundsWarm Accents for Dark Mode:
#ea580c) creates vibrant contrast against cool dark backgrounds without harsh glareThis complementary temperature approach ensures:
By inverting color temperature relative to the background, each theme maintains optimal legibility, emotional resonance, and visual balance.
Neutral Scale:
#ffffff#fafafa#f5f5f5#e5e5e5#d4d4d4#a3a3a3#737373#525252#404040#262626#171717Container:
Modular Spacing Scale:
Spacing Utilities:
Available margin utilities (replace inline styles with these):
.m-0 - margin: 0.mb-3 - margin-bottom: 12px.mb-4 - margin-bottom: 16px.mb-6 - margin-bottom: 24px.mb-8 - margin-bottom: 32px.mb-12 - margin-bottom: 48px.mb-30 - margin-bottom: 120px.mt-6 - margin-top: 24px.mt-8 - margin-top: 32px.mt-12 - margin-top: 48pxLayout Utilities:
Flexbox utilities (replace inline flex styles with these):
.flex-center - Centers content horizontally with flexbox.flex-column-gap-6 - Vertical flex column with 24px gap, left-aligned.flex-wrap-gap-6 - Horizontal flex with 24px gap and wrappingGrid System:
.grid, .grid-cols-{n}, .col-span-{n}.gap-1 (4px) to .gap-16 (64px)Glassmorphism Design Language:
Transitions & Animations:
transition: all 0.3s easetransition: all 0.15s easetransition: all 0.5s easecubic-bezier(0.4, 0, 0.2, 1)Hover States:
.hover-lift: translateY(-2px) with enhanced shadow.hover-scale: scale(1.02).hover-fade: opacity(0.8)Light Mode:
#ffffff#1a1a1a#2563ebDark Mode:
#0a0a0a#e0e0e0#ea580cTheme Toggle:
/assets/icons/moon-outlined.svg (light mode), /assets/icons/sun-outlined.svg (dark mode)CRITICAL: Understanding Variable Cascading
CSS variables that reference other variables do NOT automatically re-evaluate when the referenced variable changes. This is crucial for theme switching.
Correct Implementation:
/* ❌ INCORRECT - Won't work for theme switching */ :root { --color-accent: var(--color-accent-cool); --link-color: var(--color-accent); /* This locks to the initial value */ } body[data-theme="dark"] { --color-accent: var(--color-accent-warm); /* Only updates accent, NOT link-color */ } /* ✅ CORRECT - Explicitly override dependent variables */ :root { --color-accent: var(--color-accent-cool); --link-color: var(--color-accent); } body[data-theme="dark"] { --color-accent: var(--color-accent-warm); --link-color: var(--color-accent-warm); /* Must explicitly override */ }
Theme Variable Override Locations:
Variables must be overridden in BOTH locations due to CSS cascade order:
(line ~222) - Base dark theme overrides_variables.css
body[data-theme="dark"] { --color-accent: var(--color-accent-warm); --link-color: var(--color-accent-warm); /* ... other overrides */ }
(line ~29) - Final dark theme overrides (loads last)_utilities.css
[data-theme="dark"] { --color-accent: var(--color-accent-warm); --link-color: var(--color-accent-warm); /* ... other overrides */ }
Why Both Locations?
_utilities.css loads LAST in the cascade (see main.css import order)_variables.css, hardcoded values elsewhere may overrideWhen Adding New Theme-Aware Colors:
:rootExample - Adding a New Themed Element:
/* Step 1: Define in :root (_variables.css) */ :root { --button-accent: var(--color-accent); } /* Step 2: Override in BOTH dark theme blocks */ body[data-theme="dark"] { /* _variables.css */ --button-accent: var(--color-accent-warm); } [data-theme="dark"] { /* _utilities.css */ --button-accent: var(--color-accent-warm); } /* Step 3: Use in components */ .my-button { background: var(--button-accent); /* ✅ Will switch with theme */ /* NOT: background: #15B5FF; ❌ Won't switch with theme */ }
Common Pitfalls to Avoid:
❌ Never use hardcoded hex colors in components
.link { color: #15B5FF; }.link { color: var(--link-color); }❌ Don't use
with hardcoded RGB valuesrgba()
.element { color: rgba(21, 181, 255, 0.5); }.element { color: color-mix(in srgb, var(--link-color) 50%, transparent); }❌ Don't create theme-specific selectors for colors
body[data-theme="dark"] .link { color: #ea580c; }.link { color: var(--link-color); }✅ Always use CSS variables for any color that should respond to theme
✅ The lab page (
) is the source of truthlab.html
Buttons:
.btn-primary: Dark glass with white text (light), light glass (dark) .btn-secondary: Light glass with dark text (light), subtle glass (dark) Border-radius: 50px (pill-shaped) Padding: 16px 32px
Cards:
.card: Standard card with glass effect .glass-card: Enhanced glass card with more blur .interactive-card: Card with hover lift effect Border-radius: 16-20px Backdrop-filter: blur(10-20px)
Interactive Text:
.interactive-text: Underline animation on hover Color: Theme-appropriate accent color Transition: width 0.3s ease
Lab Page Components:
.wave-slider-container: Centers slider with 120px bottom margin (80px mobile) .wave-slider: Responsive slider with width: min(500px, 100%) .interactive-checkbox-label: Checkbox label with 12px gap and left alignment
Page Structure:
Project Cards:
.glass-card with hover effectsNavigation:
Performance Considerations:
Content Guidelines:
Avoid Inline Styles:
style="" attributes in HTML_utilities.css for spacing, layout, and common patterns_components.css for reusable patternsUse CSS Variables:
var(--color-accent-cool) instead of #15B5FFvar(--color-accent-warm) instead of #ea580c_variables.cssResponsive Patterns:
min() function for responsive sizing: width: min(500px, 100%)clamp() for responsive typography (already defined in variables)Component Reusability:
_components.css-webkit- prefixesprefers-reduced-motion for accessibility/assets/ /css/ # Modular CSS architecture main.css # Main import file _variables.css # CSS custom properties _base.css # Reset & base styles _navigation.css # Header & navigation _hero.css # Hero section _particles.css # Particle system _components.css # Reusable components _carousels.css # Carousel implementations _sections.css # Page sections _project-pages.css # Project detail pages _charts.css # Data visualizations _utilities.css # Helper classes & dark mode /js/ # Interactive features main.js # Core functionality particles.js # Particle system theme.js # Theme switching /images/ # Image assets /data/ projects.json # Project data /work/ # Case study pages design-system.html product-suite.html ai-strategy.html research-strategy.html /.claude/ # Claude Code configuration /commands/ # Slash commands settings.local.json index.html # Main portfolio page lab.html # Interactive experiments resume.html # Resume page CLAUDE.md # This file - AI context README.md # Public documentation
The stylesheet is organized as a series of CSS modules imported into
main.css:
--container-max-width, colors, fonts)CSS and JavaScript files use query parameter versioning for browser cache control:
<link rel="stylesheet" href="assets/css/main.css?v=1760841100"> <script src="assets/js/main.js?v=1760840700"></script>
Update version numbers after CSS/JS changes to force browser refresh.
Max-width containers prevent content from becoming excessively wide on large displays:
--container-max-width: 1200px (defined in _variables.css)Viewport Scaling on Large Displays: CSS cannot replicate browser zoom behavior when using
vh (viewport height) units. Attempts to use transform: scale() or CSS zoom property will break layouts that depend on viewport units because:
vh-based elementsRecommended Approaches for Large Displays:
transform: scale() or zoom property with vh layoutsFuture Considerations: If elements feel too small on ultra-high-resolution displays, consider:
--container-max-width to 1400-1600pxSlash commands available via
.claude/commands/:
/quick-commit - Commit changes on current branch/deploy - Commit, merge to main, push both branches/status - Show git status and recent commitsThis design system provides a comprehensive foundation for building a modern, professional UX portfolio that stands out with sophisticated glassmorphism effects and intelligent theming.