gh-mhattingpete-claude-skills-marketplace-visual-documentation-plugin/skills/timeline-creator/references/design_patterns.md

Design Patterns Reference

Complete design system guidelines for creating visually stunning HTML documentation.

Color System

Primary Palette

Gradient Background:

background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);

• Use for: Body background, primary branding elements
• Creates depth and visual interest

Accent Colors:

• Primary Purple-Blue: #667eea
• Secondary Purple: #764ba2
• Use for: Headings, borders, key UI elements

Semantic Color Scales

Success / Confirmed / Positive

• Base: #48bb78 (green)
• Dark: #2f855a (darker green, for strokes)
• Light: #e6f4ea (pale green, for backgrounds)
• Use for: Completed tasks, success messages, positive metrics

Warning / Uncertain / Attention

• Base: #f59e0b (amber)
• Dark: #d97706 (darker amber, for strokes)
• Light: #fffbeb (pale amber, for backgrounds)
• Use for: In-progress items, warnings, items needing attention

Info / Primary / Standard

• Base: #4299e1 (blue)
• Dark: #2b6cb0 (darker blue, for strokes)
• Light: #e6f2ff (pale blue, for backgrounds)
• Use for: Standard information, primary actions, neutral states

Error / Critical / Negative

• Base: #f56565 (red)
• Dark: #c53030 (darker red, for strokes)
• Light: #fff5f5 (pale red, for backgrounds)
• Use for: Errors, critical issues, failed states

Process / Action / Secondary

• Base: #ed8936 (orange)
• Dark: #c05621 (darker orange, for strokes)
• Light: #fff5e6 (pale orange, for backgrounds)
• Use for: Processing states, secondary actions

Special / Highlight / Tertiary

• Base: #9f7aea (purple)
• Dark: #6b46c1 (darker purple, for strokes)
• Light: #f3e6ff (pale purple, for backgrounds)
• Use for: Special features, highlights, premium items

Neutral Palette

Text Colors:

• Dark (Primary text): #2d3748 - Headings, important content
• Medium (Secondary text): #718096 - Body text, labels
• Light (Tertiary text): #a0aec0 - Captions, metadata

UI Elements:

• Dark border: #cbd5e0
• Light border: #e2e8f0
• Dark background: #edf2f7
• Light background: #f7fafc
• White: #ffffff

Color Contrast Guidelines

WCAG AA Compliance:

• Minimum contrast ratio: 4.5:1 for normal text
• Large text (18pt+ or 14pt+ bold): 3:1 minimum
• Safe combinations:
  • Dark text (#2d3748) on light backgrounds (#f7fafc, #ffffff)
  • White text on colored backgrounds (all semantic base colors pass)
  • Medium text (#718096) on white only

Typography

Font Families

Primary (Sans-serif):

font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;

• Use for: All body text, headings, UI elements
• Fallback chain ensures availability across platforms

Code (Monospace):

font-family: 'Courier New', monospace;

• Use for: Code blocks, technical data, fixed-width content

Type Scale

Display / Hero:

• Size: 2.5em (40px at 16px base)
• Weight: Bold (700)
• Use for: Page title (h1)
• Special effect: Gradient text clip

Section Heading:

• Size: 1.8em (28.8px)
• Weight: Bold (700)
• Color: #2d3748
• Use for: Major sections (h2)
• Decoration: Bottom border 3px solid #667eea

Subsection:

• Size: 1.4em (22.4px)
• Weight: Bold (700)
• Color: #2d3748
• Use for: Subsections (h3)

Body:

• Size: 1em (16px base)
• Weight: Normal (400)
• Line height: 1.6
• Color: #2d3748 or #4a5568
• Use for: Paragraphs, general content

Label / Caption:

• Size: 0.9-0.95em (14.4-15.2px)
• Weight: Normal (400) or Medium (500)
• Color: #718096
• Use for: Metric labels, chart labels, form labels

Small / Meta:

• Size: 0.85em (13.6px)
• Weight: Normal (400)
• Color: #a0aec0
• Use for: Footnotes, timestamps, metadata

SVG Text:

• Small labels: 11-12px
• Standard text: 13-14px
• Emphasis: 15-16px
• Large values: 18-24px
• Metric displays: 48px+

Text Effects

Gradient Text (for h1):

h1 {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    -webkit-background-clip: text;
    -webkit-text-fill-color: transparent;
    background-clip: text;
}

Code Highlighting:

.highlight {
    color: #fbbf24;  /* Amber highlight */
    font-weight: bold;
}

Spacing & Layout

Container Sizing

Max Width:

• Container: 1400px
• Comfortable reading: 800-1000px
• Full width sections: No max-width

Padding:

• Desktop container: 40px
• Mobile container: 20px
• Diagram containers: 30px
• Content boxes: 20px
• Metric cards: 25px

Margins:

• Section bottom: 60px
• Element groups: 30px
• Individual elements: 20px
• Small gaps: 10px

Grid Systems

Metric Grid:

display: grid;
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
gap: 20px;

• Automatically responsive
• Minimum card width: 200px
• Equal width distribution

Custom Grids:

• 2-column: grid-template-columns: 1fr 1fr;
• 3-column: grid-template-columns: repeat(3, 1fr);
• Sidebar layout: grid-template-columns: 300px 1fr;

Flexbox Patterns

Horizontal Center:

display: flex;
justify-content: center;
align-items: center;

Space Between:

display: flex;
justify-content: space-between;
align-items: center;

Wrapped Row:

display: flex;
flex-wrap: wrap;
gap: 20px;

Visual Effects

Shadows

Card Shadow:

box-shadow: 0 20px 60px rgba(0,0,0,0.3);

• Use for: Main container, elevated cards

Metric Card Shadow:

box-shadow: 0 4px 15px rgba(102, 126, 234, 0.3);

• Use for: Metric cards, smaller elevation

Subtle Shadow:

box-shadow: 0 2px 8px rgba(0,0,0,0.1);

• Use for: Buttons, small cards, hover states

Border Radius

Large (Containers):

• Container: 20px
• Diagram containers: 15px

Medium (Cards & Boxes):

• Metric cards: 15px
• Content boxes: 10px
• SVG shapes: 10px

Small (UI Elements):

• Buttons: 8px
• Small badges: 5px

Pills / Rounded:

• Full rounded: 50% (circles) or 9999px (pills)
• Timeline progress bars: 20px

Opacity

Overlays:

• Light overlay: 0.3
• Medium overlay: 0.5-0.6
• Strong overlay: 0.8-0.9

Hover States:

• Slight fade: 0.9
• Clear fade: 0.7-0.8

Disabled:

• 0.5-0.6

Responsive Breakpoints

Mobile First Strategy

Breakpoints:

/* Mobile: default styles, no media query needed */

/* Tablet */
@media (min-width: 768px) { ... }

/* Desktop */
@media (min-width: 1024px) { ... }

/* Large Desktop */
@media (min-width: 1440px) { ... }

Common Pattern (Desktop First):

@media (max-width: 768px) {
    .container { padding: 20px; }
    h1 { font-size: 1.8em; }
    .section-title { font-size: 1.4em; }
    .metric-grid { grid-template-columns: 1fr; }
}

Responsive Typography

Desktop:

• h1: 2.5em
• h2: 1.8em
• h3: 1.4em
• body: 1em

Mobile (max-width: 768px):

• h1: 1.8em
• h2: 1.4em
• h3: 1.2em
• body: 0.95em

SVG Text Scaling:

• Use viewBox for automatic scaling
• Font sizes in px remain constant
• Increase viewBox dimensions rather than reducing font sizes

Component Patterns

Metric Cards

Standard Pattern:

<div class="metric-card">
    <div class="metric-value">[LARGE NUMBER]</div>
    <div class="metric-label">[DESCRIPTION]</div>
</div>

With Custom Color:

<div class="metric-card" style="background: linear-gradient(135deg, #48bb78 0%, #38a169 100%);">
    <div class="metric-value">✓ [NUMBER]</div>
    <div class="metric-label">[DESCRIPTION]</div>
</div>

Code Blocks

Standard:

<div class="code-block">
<span class="highlight">Key term:</span> Regular code text
    Indented content
</div>

CSS:

.code-block {
    background: #2d3748;
    color: #e2e8f0;
    padding: 20px;
    border-radius: 10px;
    font-family: 'Courier New', monospace;
    font-size: 0.9em;
    overflow-x: auto;
    line-height: 1.6;
}

Example Boxes

Pattern:

<div class="example-box">
    <div class="example-title">[TITLE]</div>
    <p>[CONTENT]</p>
</div>

CSS:

.example-box {
    background: #fff;
    border: 2px solid #667eea;
    border-radius: 10px;
    padding: 20px;
    margin: 20px 0;
}

Legends

Pattern:

<div class="legend">
    <div class="legend-item">
        <div class="legend-box" style="background: #4299e1;"></div>
        <span>[DESCRIPTION]</span>
    </div>
    <!-- More items -->
</div>

CSS:

.legend {
    display: flex;
    flex-wrap: wrap;
    gap: 20px;
    padding: 20px;
    background: #edf2f7;
    border-radius: 10px;
}

SVG Styling

Default SVG Styles

Container:

svg {
    width: 100%;
    height: auto;
}

Text:

svg text {
    font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
}

Common Stroke/Fill Combinations

Primary Box:

• Fill: #4299e1
• Stroke: #2b6cb0
• Stroke-width: 3

Success Box:

• Fill: #48bb78
• Stroke: #2f855a
• Stroke-width: 3

Warning Box:

• Fill: #f59e0b
• Stroke: #d97706
• Stroke-width: 3

Neutral/Pending:

• Fill: #cbd5e0
• Stroke: #a0aec0
• Stroke-width: 2-3

ViewBox Guidelines

Common Aspect Ratios:

• Wide: viewBox="0 0 1200 400" (3:1)
• Standard: viewBox="0 0 1200 600" (2:1)
• Balanced: viewBox="0 0 1200 800" (3:2)
• Square: viewBox="0 0 600 600" (1:1)
• Portrait: viewBox="0 0 800 1000" (4:5)

Coordinate System:

• Origin: Top-left (0, 0)
• X increases rightward
• Y increases downward
• Units are relative to viewBox

Accessibility

Color Blindness

Safe Patterns:

• Don't rely on color alone (use icons, labels, patterns)
• Use both fill and stroke for differentiation
• Ensure shapes differ (circle vs square vs diamond)
• Add text labels to all visual elements

Color Combinations to Avoid:

• Red/green alone (common color blindness)
• Blue/purple alone (hard to distinguish)
• Low contrast combinations

Screen Readers

HTML Structure:

• Use semantic tags: <section>, <article>, <header>, <footer>
• Proper heading hierarchy: h1 → h2 → h3
• Descriptive text around SVG diagrams

ARIA (if needed):

<svg aria-labelledby="chart-title" role="img">
    <title id="chart-title">Process Flow Diagram</title>
    <!-- SVG content -->
</svg>

Keyboard Navigation

• Ensure all interactive elements are focusable
• Visible focus indicators
• Logical tab order

Animation (Optional)

Subtle Transitions

Hover Effects:

.metric-card {
    transition: transform 0.2s, box-shadow 0.2s;
}

.metric-card:hover {
    transform: translateY(-5px);
    box-shadow: 0 8px 25px rgba(102, 126, 234, 0.4);
}

Fade In:

@keyframes fadeIn {
    from { opacity: 0; }
    to { opacity: 1; }
}

.section {
    animation: fadeIn 0.5s ease-in;
}

Note: Keep animations subtle and optional - avoid distracting from content.