Portfolio Design System

Overview

A comprehensive design system demonstrating systematic design thinking through deliberate token architecture, reusable components, and accessibility-first patterns. Built with modern technologies while maintaining design system portability and scalability.

Design Philosophy

Systematic Token Architecture

OKLCH color space for perceptually uniform hues, 4px base unit for consistent spacing rhythm, and Major Third (1.250) typography scale create mathematical harmony across all components.

Applied in: 60+ color tokens, 8-step spacing scale, 9-level type hierarchy

Component Composition Patterns

Components built with functional composition—each accepts typed props, handles its own state, and composes with others. Astro Islands enable progressive enhancement while maintaining static-first performance.

Applied in: 20+ React components, layout patterns, composite widgets

Accessibility as Foundation

WCAG AA compliance through semantic HTML, ARIA patterns, keyboard navigation, and minimum 4.5:1 contrast ratios. Focus states use 2px outlines with 2px offset for visibility without compromising aesthetics.

Applied in: All interactive components, color system, navigation patterns

Performance-Driven Decisions

Lazy-loaded components, optimized GSAP animations, and Astro's partial hydration strategy deliver 94+ Lighthouse scores. Design decisions prioritize perceived performance through skeleton states and instant feedback.

Applied in: Animation system, image loading, component hydration strategy

Methodology

→ Component-driven development with Astro Islands architecture
→ Type-safe props and interfaces with TypeScript strict mode
→ Utility-first CSS with Tailwind CSS v4
→ Semantic component library with daisyUI v5
→ High-performance animations with GSAP ScrollTrigger
→ Git-based version control with conventional commits

Impact Metrics

Lighthouse Score

95+

Performance, Accessibility, Best Practices, SEO

Bundle Size

< 100KB

Initial JavaScript bundle (gzipped)

Components

20+

Reusable, documented components

Accessibility

WCAG AA

Keyboard nav, screen readers, ARIA

Design Tokens in Action

Design tokens translate design decisions into reusable values. These examples show how systematic tokens create consistency across the entire interface.

Semantic Color Architecture

Primary Palette

Primary

oklch(37.45% 0.189 325.02)

Secondary

oklch(53.92% 0.18 260)

Accent

oklch(75.98% 0.204 56.72)

Semantic Feedback

Success

Positive actions, confirmations

Warning

Caution, review required

Error

Critical issues, failed actions

4px Base Unit Spacing

All spacing follows a 4px base unit rhythm for visual harmony and consistency.

xs: 4px - Tight spacing, inline elements

sm: 8px - Related elements, compact layouts

md: 16px - Component padding, comfortable spacing

lg: 24px - Section spacing, content blocks

xl: 32px - Major section breaks

2xl: 48px - Page-level spacing

Major Third Typography Scale (1.250)

Display (48px)

Hero sections, landing pages

Heading 1 (30px)

Page titles

Heading 2 (24px)

Section headers

Heading 3 (20px)

Subsections

Body (16px)

Primary content, paragraphs

Small (14px)

Supporting text, captions

Implementation Stack

Built with modern web technologies that enable component-based architecture, progressive enhancement, and design token portability. Technology choices prioritize developer experience while maintaining design system principles.

Design Architecture

→ W3C Design Tokens: Framework-agnostic token format
→ OKLCH Color Space: Perceptually uniform colors
→ 4px Base Unit: Mathematical spacing harmony

Component System

→ React 19: Typed components with props
→ Astro Islands: Partial hydration strategy
→ TypeScript: Type-safe design system

Visual System

→ Tailwind CSS v4: Utility-first styling
→ daisyUI v5: Semantic component classes
→ GSAP: Performance-optimized animations

Architecture

The portfolio site follows a modern component-based architecture with clear separation of concerns.

File Structure

bash

src/
├── components/          # React components
│   ├── home/           # Home page components
│   ├── about/          # About page components
│   ├── case-studies/   # Case study components
│   ├── ui-design/      # UI design showcase components
│   ├── layout/         # Layout components (Header, Footer)
│   └── shared/         # Shared/reusable components
├── layouts/            # Astro layouts
│   ├── BaseLayout.astro
│   ├── DSLayout.astro
│   └── UIShowcaseLayout.astro
├── pages/              # Astro pages (file-based routing)
│   ├── index.astro
│   ├── about.astro
│   ├── design-systems/
│   └── ui-design/
├── styles/             # Global styles
│   └── global.css
└── design-systems/     # Design system documentation
    ├── _showcase/      # Showcase components
    ├── _template/      # Template design system
    └── portfolio-site/ # This design system

Component Patterns

Astro Islands

Static HTML by default, hydrate React components only where needed with client:load, client:idle, or client:visible directives.

html

<Header />
<HeroScroll client:load />
<WorkCards client:idle />
<Footer client:load />

Typed Props

All React components use TypeScript interfaces for type-safe props.

tsx

interface DesignCalloutProps {
  number: number;
  title: string;
  explanation: string;
  children?: React.ReactNode;
}

export function DesignCallout({ number, title, explanation, children }: DesignCalloutProps) {
  // Implementation
}

GSAP Animations

ScrollTrigger for scroll-based animations with proper cleanup in useEffect.

tsx

useEffect(() => {
  const ctx = gsap.context(() => {
    gsap.fromTo(
      elements,
      { opacity: 0, y: 20 },
      {
        opacity: 1,
        y: 0,
        stagger: 0.1,
        scrollTrigger: {
          trigger: containerRef.current,
          start: "top 95%",
          end: "top 25%",
          scrub: true,
        },
      }
    );
  }, containerRef);

  return () => ctx.revert();
}, []);

Token Browser

Search, filter, and copy design tokens used throughout the portfolio site.

Showing 74 of 74 tokens

light-primary

oklch(37.45% 0.189 325.02)

Primary brand color

colors

light-primary-content

oklch(96% 0.001 286.375)

Text on primary

colors

light-secondary

oklch(53.92% 0.18 260)

Secondary brand color

colors

light-secondary-content

oklch(90.784% 0.032 241.36)

Text on secondary

colors

light-accent

oklch(75.98% 0.204 56.72)

Accent color

colors

light-accent-content

oklch(15.196% 0.04 56.72)

Text on accent

colors

light-neutral

oklch(65% 0.18 145)

Neutral color

colors

light-neutral-content

oklch(96% 0.001 286.375)

Text on neutral

colors

light-base-100

oklch(96% 0.001 286.375)

Primary background

colors

light-base-200

oklch(98% 0 0)

Secondary background

colors

light-base-300

oklch(100% 0 0)

Tertiary background

colors

light-base-content

oklch(14% 0.005 285.823)

Primary text

colors

light-success

oklch(64.8% 0.15 160)

Success state

colors

light-success-content

oklch(14% 0.005 285.823)

Text on success

colors

light-warning

oklch(84.71% 0.199 83.87)

Warning state

colors

light-warning-content

oklch(14% 0.005 285.823)

Text on warning

colors

light-error

oklch(71.76% 0.221 22.18)

Error state

colors

light-error-content

oklch(14% 0.005 285.823)

Text on error

colors

light-info

oklch(72.06% 0.191 231.6)

Info state

colors

light-info-content

oklch(14% 0.005 285.823)

Text on info

colors

dark-primary

oklch(55% 0.18 325.02)

Primary brand color (lighter for dark)

colors

dark-primary-content

oklch(96% 0.001 286.375)

Text on primary

colors

dark-secondary

oklch(68% 0.16 260)

Secondary brand color (lighter for dark)

colors

dark-secondary-content

oklch(14% 0.005 285.823)

Text on secondary

colors

dark-accent

oklch(78% 0.16 56.72)

Accent color (lighter for dark)

colors

dark-accent-content

oklch(14% 0.005 285.823)

Text on accent

colors

dark-neutral

oklch(70% 0.16 145)

Neutral color (lighter for dark)

colors

dark-neutral-content

oklch(14% 0.005 285.823)

Text on neutral

colors

dark-base-100

oklch(14% 0.005 285.823)

Primary background (dark)

colors

dark-base-200

oklch(21% 0.006 285.885)

Secondary background (dark)

colors

dark-base-300

oklch(27% 0.006 286.033)

Tertiary background (dark)

colors

dark-base-content

oklch(96% 0.001 286.375)

Primary text (light on dark)

colors

dark-success

oklch(68% 0.14 160)

Success state

colors

dark-success-content

oklch(14% 0.005 285.823)

Text on success

colors

dark-warning

oklch(82% 0.16 83.87)

Warning state

colors

dark-warning-content

oklch(14% 0.005 285.823)

Text on warning

colors

dark-error

oklch(72% 0.18 22.18)

Error state

colors

dark-error-content

oklch(14% 0.005 285.823)

Text on error

colors

dark-info

oklch(72% 0.15 231.6)

Info state

colors

dark-info-content

oklch(14% 0.005 285.823)

Text on info

colors

The quick brown fox

fontFamily-body

'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif

Primary typeface for body text

typography

The quick brown fox

fontFamily-brand

'Playfair Display', serif

Brand typeface for logo and special headings

typography

The quick brown fox

fontFamily-mono

'IBM Plex Mono', monospace

Monospace font for code and technical content

typography

Aa

fontSize-xs

0.75rem

12px

typography

Aa

fontSize-sm

0.875rem

14px

typography

Aa

fontSize-base

1rem

16px

typography

Aa

fontSize-lg

1.125rem

18px

typography

Aa

fontSize-xl

1.25rem

20px

typography

Aa

fontSize-2xl

1.5rem

24px

typography

Aa

fontSize-3xl

1.875rem

30px

typography

Aa

fontSize-4xl

2.25rem

36px

typography

Aa

fontSize-5xl

3rem

48px

typography

Aa

fontSize-display

clamp(3rem, 10vw, 10rem)

Responsive display size

typography

1.25

lineHeight-tight

1.25

Tight line height for headings

typography

1.5

lineHeight-normal

1.5

Normal line height for body

typography

1.75

lineHeight-relaxed

1.75

Relaxed line height

typography

Font Weight 300

fontWeight-light

300

Light weight

typography

Font Weight 400

fontWeight-normal

400

Normal weight

typography

Font Weight 500

fontWeight-medium

500

Medium weight

typography

Font Weight 700

fontWeight-bold

700

Bold weight

typography

Font Weight 900

fontWeight-black

900

Black weight

typography

0.25rem

xs

0.25rem

4px

spacing

0.5rem

sm

0.5rem

8px

spacing

1rem

md

1rem

16px

spacing

1.5rem

lg

1.5rem

24px

spacing

2rem

xl

2rem

32px

spacing

3rem

2xl

3rem

48px

spacing

4rem

3xl

4rem

64px

spacing

6rem

4xl

6rem

96px

spacing

150ms

duration-fast

150ms

Quick transitions

animations

300ms

duration-normal

300ms

Standard transitions

animations

500ms

duration-slow

500ms

Slower transitions

animations

cubic-bezier(0.22, 0.9, 0.35, 1)

easing-default

cubic-bezier(0.22, 0.9, 0.35, 1)

Default easing curve

animations

cubic-bezier(0.16, 0.84, 0.26, 1)

easing-smooth

cubic-bezier(0.16, 0.84, 0.26, 1)

Smooth easing for complex animations

animations

Color System

OKLCH color palette designed for perceptual uniformity and accessibility. This site has both light and dark themes with optimized colors for each mode.

Why OKLCH?

• Perceptually uniform: Equal numeric changes produce equal visual changes
• Wide gamut: Access to more vibrant colors than RGB/HSL
• Predictable: Adjusting lightness doesn't shift hue
• Future-proof: Native browser support in modern browsers

primary

var(--portfolio-site-light-color-primary)

oklch(37.45% 0.189 325.02)

On white:AAA

On black:AA

brand

primary-content

var(--portfolio-site-light-color-primary-content)

oklch(96% 0.001 286.375)

On white:Fail

On black:AAA

brand

secondary

var(--portfolio-site-light-color-secondary)

oklch(53.92% 0.18 260)

On white:AAA

On black:Fail

brand

secondary-content

var(--portfolio-site-light-color-secondary-content)

oklch(90.784% 0.032 241.36)

On white:Fail

On black:AAA

brand

accent

var(--portfolio-site-light-color-accent)

oklch(75.98% 0.204 56.72)

On white:AA

On black:AAA

brand

accent-content

var(--portfolio-site-light-color-accent-content)

oklch(15.196% 0.04 56.72)

On white:AAA

On black:Fail

brand

neutral

var(--portfolio-site-light-color-neutral)

oklch(65% 0.18 145)

On white:AA

On black:AAA

brand

neutral-content

var(--portfolio-site-light-color-neutral-content)

oklch(96% 0.001 286.375)

On white:Fail

On black:AAA

brand

base-100

var(--portfolio-site-light-color-base-100)

oklch(96% 0.001 286.375)

On white:Fail

On black:AAA

neutral

base-200

var(--portfolio-site-light-color-base-200)

oklch(98% 0 0)

On white:Fail

On black:AAA

neutral

base-300

var(--portfolio-site-light-color-base-300)

oklch(100% 0 0)

On white:Fail

On black:AAA

neutral

base-content

var(--portfolio-site-light-color-base-content)

oklch(14% 0.005 285.823)

On white:AAA

On black:Fail

neutral

success

var(--portfolio-site-light-color-success)

oklch(64.8% 0.15 160)

On white:AA

On black:AAA

semantic

success-content

var(--portfolio-site-light-color-success-content)

oklch(14% 0.005 285.823)

On white:AAA

On black:Fail

semantic

warning

var(--portfolio-site-light-color-warning)

oklch(84.71% 0.199 83.87)

On white:AA

On black:AAA

semantic

warning-content

var(--portfolio-site-light-color-warning-content)

oklch(14% 0.005 285.823)

On white:AAA

On black:Fail

semantic

error

var(--portfolio-site-light-color-error)

oklch(71.76% 0.221 22.18)

On white:AA

On black:AAA

semantic

error-content

var(--portfolio-site-light-color-error-content)

oklch(14% 0.005 285.823)

On white:AAA

On black:Fail

semantic

info

var(--portfolio-site-light-color-info)

oklch(72.06% 0.191 231.6)

On white:AA

On black:AAA

semantic

info-content

var(--portfolio-site-light-color-info-content)

oklch(14% 0.005 285.823)

On white:AAA

On black:Fail

semantic

WCAG Color Contrast Guidelines

WCAG AA (Minimum): 4.5:1 for normal text, 3:1 for large text (18pt+)

WCAG AAA (Enhanced): 7:1 for normal text, 4.5:1 for large text

✓ = Meets WCAG AA standard for normal text

Showing 20 of 20 colors

Typography Scale

Three typeface system: Inter for body, Playfair Display for brand, IBM Plex Mono for code.

Inter

Body text and UI elements. Optimized for readability at all sizes.

Playfair Display

Logo and brand identity. Adds elegance and personality.

IBM Plex Mono

Code examples and technical content. Clear at small sizes.

Preview Text

Display

Large hero text with responsive scaling

var(--portfolio-site-font-Display)

The quick brown fox jumps over the lazy dog

Font Size

clamp(3rem, 10vw, 10rem)

Line Height

1.25

Weight

700

Letter Spacing

Normal

Font Family

'IBM Plex Mono', monospace

5xl

Page titles and major headings

var(--portfolio-site-font-5xl)

The quick brown fox jumps over the lazy dog

Font Size

3rem

Line Height

1.25

Weight

700

Letter Spacing

Normal

Font Family

'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif

4xl

Section headings

var(--portfolio-site-font-4xl)

The quick brown fox jumps over the lazy dog

Font Size

2.25rem

Line Height

1.25

Weight

700

Letter Spacing

Normal

Font Family

'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif

3xl

Subsection headings

var(--portfolio-site-font-3xl)

The quick brown fox jumps over the lazy dog

Font Size

1.875rem

Line Height

1.25

Weight

700

Letter Spacing

Normal

Font Family

'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif

2xl

Component titles

var(--portfolio-site-font-2xl)

The quick brown fox jumps over the lazy dog

Font Size

1.5rem

Line Height

1.5

Weight

500

Letter Spacing

Normal

Font Family

'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif

xl

Lead paragraphs

var(--portfolio-site-font-xl)

The quick brown fox jumps over the lazy dog

Font Size

1.25rem

Line Height

1.5

Weight

400

Letter Spacing

Normal

Font Family

'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif

lg

Large body text

var(--portfolio-site-font-lg)

The quick brown fox jumps over the lazy dog

Font Size

1.125rem

Line Height

1.5

Weight

400

Letter Spacing

Normal

Font Family

'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif

base

Default body text

var(--portfolio-site-font-base)

The quick brown fox jumps over the lazy dog

Font Size

1rem

Line Height

1.5

Weight

400

Letter Spacing

Normal

Font Family

'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif

sm

Small text, captions

var(--portfolio-site-font-sm)

The quick brown fox jumps over the lazy dog

Font Size

0.875rem

Line Height

1.5

Weight

400

Letter Spacing

Normal

Font Family

'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif

xs

Fine print, labels

var(--portfolio-site-font-xs)

The quick brown fox jumps over the lazy dog

Font Size

0.75rem

Line Height

1.5

Weight

400

Letter Spacing

Normal

Font Family

'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif

Showing 10 typography tokens

Spacing System

4px base unit spacing scale (inherited from Tailwind CSS defaults). Provides consistent rhythm across the interface.

Why a 4px Base Unit?

• Scalability: Creates harmonious spacing that scales across all screen sizes
• Consistency: Reduces decision-making with predictable increments (4, 8, 12, 16, 24...)
• Alignment: Ensures pixel-perfect alignment on all display densities
• Standards: Matches Tailwind CSS and modern design system conventions

Visual Spacing Scale

xs

4px0.25rem

Icon spacing, micro-adjustments

sm

8px0.5rem

Tight spacing, compact UIs

md

16px1rem

Default spacing, comfortable layouts

lg

24px1.5rem

Component padding, card spacing

xl

32px2rem

Section spacing, large gaps

2xl

48px3rem

Section spacing, large gaps

3xl

64px4rem

Hero spacing, major sections

4xl

96px6rem

Page-level spacing, dramatic separation

Layout & Grid

12-column responsive grid system with flexible layout primitives. Built with Tailwind CSS grid utilities and daisyUI container classes.

Breakpoints

Mobile-first responsive breakpoints for adaptive layouts

Mobile

Base

<640px

SM

640px

≥640px

MD

768px

≥768px

LG

1024px

≥1024px

XL

1280px

≥1280px

2XL

1536px

≥1536px

12-Column Grid System

Flexible grid with 24px gutters and responsive behavior

Full Width (12 columns)

12 columns

Half Width (6 + 6 columns)

6 columns

Thirds (4 + 4 + 4 columns)

4 columns

Asymmetric (8 + 4 columns)

8 columns (main content)

4 columns (sidebar)

Layout Primitives

Reusable layout patterns for common use cases

Grid (2D Layouts)

3 cols

<div class="template-grid">
  <div class="template-col-12 template-col-md-3">...</div>
  <div class="template-col-12 template-col-md-3">...</div>
  <div class="template-col-12 template-col-md-3">...</div>
  <div class="template-col-12 template-col-md-3">...</div>
</div>

Container Max-Widths

Responsive containers that adapt to viewport size

SM

640px

MD

768px

LG

1024px

XL

1280px

2XL

1536px

Motion & Animation

GSAP-powered animations with ScrollTrigger for performant, scroll-based interactions. CSS transitions for simple state changes.

Animation Principles

• Purposeful: Animations guide attention and provide feedback
• Performant: GPU-accelerated transforms and opacity only
• Subtle: Don't distract from content or slow down interaction
• Accessible: Respects prefers-reduced-motion

Easing Functions

cubic-bezier(0.22, 0.9, 0.35, 1) Default easing

cubic-bezier(0.16, 0.84, 0.26, 1) Smooth complex animations

Duration Scale

Consistent timing creates predictable and comfortable interactions. Click the cards to see each duration in action.

Instant

100ms

Micro-interactions

Fast

200ms

Quick UI transitions

Normal

300ms

Standard duration

Slow

500ms

Emphasized transitions

Slower

800ms

Deliberate animations

Easing Functions

Easing creates natural, physics-based motion that feels organic. Click the cards to see how each easing curve affects motion.

Linear

cubic-bezier(0, 0, 1, 1)

Constant speed

Ease In

cubic-bezier(0.4, 0, 1, 1)

Slow start, fast end (exits)

Ease Out

cubic-bezier(0, 0, 0.2, 1)

Fast start, slow end (entrances)

Ease In Out

cubic-bezier(0.4, 0, 0.2, 1)

Slow start and end (movement)

Spring

cubic-bezier(0.34, 1.56, 0.64, 1)

Bouncy spring effect

Animation Examples

Click the cards to trigger animations (auto-animations play continuously)

Fade In

Smooth opacity transition from 0 to 1

Slide In Up

Element slides up from below with fade

Slide In Down

Element slides down from above with fade

Scale In

Element scales from 90% to 100% with fade

Spin

Auto

Continuous 360° rotation - use for loading states

Pulse

Auto

Opacity pulses between 100% and 50%

Bounce

Auto

Vertical bouncing motion

Shake

Horizontal shake - use for error feedback

Micro-interactions

Subtle feedback that makes interfaces feel responsive and alive

Button Hover

200ms ease-out on all properties

Card Elevation

Hover for elevation

300ms ease-in-out transform & shadow

Input Focus

200ms ease-out border & ring

Loading States

Animations that communicate progress and keep users informed

Spinner

Continuous rotation for loading

Dots

Pulsing dots with staggered delay

Progress Bar

Indeterminate progress indicator

Primitive Components

Foundation components built with daisyUI and custom styles. Live examples from the actual site.

Buttons

daisyUI button variants used throughout the site

Badges

Status indicators and labels

Primary Secondary Accent Neutral Success Warning Error Info

Small Normal Large

Outline Outline Outline

Cards

Container components for grouping content

Basic Card

A simple card with title and content.

Card with Shadow

Enhanced with shadow for depth.

Alerts

User feedback and system messages

Informational message for the user

Success! Your operation completed

Warning: Please review before proceeding

Error! Something went wrong

Composite Components

Complex components built from daisyUI primitives. These combine multiple elements for common UI patterns.

Modal

Dialog overlays for focused interactions

Dropdown

Contextual menus for actions and navigation

Tabs

Organize content into switchable sections

Content for Tab 1. This could be a form, data table, or any other content.

Content for Tab 2. Tabs help organize complex interfaces.

Content for Tab 3. Use tabs to reduce cognitive load.

Collapse/Accordion

Expandable content sections

Section 1

Content for the first section. Accordions progressively disclose information.

Section 2

Content for the second section. Only one section open at a time.

Section 3

Content for the third section. Reduces scrolling and information overload.