Initial commit

2025-11-30 08:40:19 +08:00
commit 87a970c077
26 changed files with 9131 additions and 0 deletions
--- a/skills/technical-doc-creator/references/design_patterns.md
+++ b/skills/technical-doc-creator/references/design_patterns.md
@@ -0,0 +1,541 @@
+# Design Patterns Reference
+
+Complete design system guidelines for creating visually stunning HTML documentation.
+
+## Color System
+
+### Primary Palette
+
+**Gradient Background:**
+```css
+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):**
+```css
+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):**
+```css
+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):**
+```css
+h1 {
+    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+}
+```
+
+**Code Highlighting:**
+```css
+.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:**
+```css
+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:**
+```css
+display: flex;
+justify-content: center;
+align-items: center;
+```
+
+**Space Between:**
+```css
+display: flex;
+justify-content: space-between;
+align-items: center;
+```
+
+**Wrapped Row:**
+```css
+display: flex;
+flex-wrap: wrap;
+gap: 20px;
+```
+
+## Visual Effects
+
+### Shadows
+
+**Card Shadow:**
+```css
+box-shadow: 0 20px 60px rgba(0,0,0,0.3);
+```
+- Use for: Main container, elevated cards
+
+**Metric Card Shadow:**
+```css
+box-shadow: 0 4px 15px rgba(102, 126, 234, 0.3);
+```
+- Use for: Metric cards, smaller elevation
+
+**Subtle Shadow:**
+```css
+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:**
+```css
+/* 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):**
+```css
+@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:**
+```html
+<div class="metric-card">
+    <div class="metric-value">[LARGE NUMBER]</div>
+    <div class="metric-label">[DESCRIPTION]</div>
+</div>
+```
+
+**With Custom Color:**
+```html
+<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:**
+```html
+<div class="code-block">
+<span class="highlight">Key term:</span> Regular code text
+    Indented content
+</div>
+```
+
+**CSS:**
+```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:**
+```html
+<div class="example-box">
+    <div class="example-title">[TITLE]</div>
+    <p>[CONTENT]</p>
+</div>
+```
+
+**CSS:**
+```css
+.example-box {
+    background: #fff;
+    border: 2px solid #667eea;
+    border-radius: 10px;
+    padding: 20px;
+    margin: 20px 0;
+}
+```
+
+### Legends
+
+**Pattern:**
+```html
+<div class="legend">
+    <div class="legend-item">
+        <div class="legend-box" style="background: #4299e1;"></div>
+        <span>[DESCRIPTION]</span>
+    </div>
+    <!-- More items -->
+</div>
+```
+
+**CSS:**
+```css
+.legend {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 20px;
+    padding: 20px;
+    background: #edf2f7;
+    border-radius: 10px;
+}
+```
+
+## SVG Styling
+
+### Default SVG Styles
+
+**Container:**
+```css
+svg {
+    width: 100%;
+    height: auto;
+}
+```
+
+**Text:**
+```css
+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):**
+```html
+<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:**
+```css
+.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:**
+```css
+@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.