Initial commit

skills/pixel-pusher/references/style-guide-template.md

@@ -0,0 +1,607 @@
+# Style Guide Template
+
+Visual reference document for design system. Use this template to create comprehensive style guides.
+
+## Style Guide Structure
+
+### Cover Page
+- Project/Product name
+- Design system version
+- Last updated date
+- Team/designer names
+
+### Table of Contents
+1. Brand Identity
+2. Color Palette
+3. Typography
+4. Spacing & Layout
+5. Components
+6. Iconography
+7. Imagery
+8. Voice & Tone
+9. Usage Guidelines
+
+---
+
+## 1. Brand Identity
+
+### Brand Values
+- **Value 1:** Brief description
+- **Value 2:** Brief description
+- **Value 3:** Brief description
+
+### Brand Personality
+- **Adjective 1:** How this shows in design
+- **Adjective 2:** How this shows in design
+- **Adjective 3:** How this shows in design
+
+### Logo Usage
+**Primary logo:**
+- Full color version
+- Minimum size
+- Clear space requirements
+- Acceptable variations
+
+**Don'ts:**
+- Don't stretch or distort
+- Don't change colors
+- Don't add effects
+- Don't place on busy backgrounds
+
+---
+
+## 2. Color Palette
+
+### Primary Colors
+
+**[Primary Color Name] (#HEX)**
+- **Usage:** Primary actions, headers, brand elements
+- **Shades:** 50, 100, 200, 300, 400, 500 (base), 600, 700, 800, 900
+- **Contrast:** #FFFFFF text passes WCAG AA on 600+
+
+**Visual swatch showing:**
+```
+50  100  200  300  400  500  600  700  800  900
+░░░  ░░   ▒▒   ▓▓   ▓▓   ███  ███  ███  ███  ███
+```
+
+### Secondary Colors
+
+**[Secondary Color Name] (#HEX)**
+- **Usage:** Secondary actions, accents, variety
+- **Shades:** [Same structure as primary]
+
+### Neutral Colors
+
+**Grays (#HEX)**
+- **Usage:** Text, borders, backgrounds, shadows
+- **Shades:** 50 (lightest) to 900 (darkest)
+
+### Semantic Colors
+
+**Success (#HEX)**
+- Usage: Success messages, confirmations, positive actions
+- Accessibility: Passes WCAG AA
+
+**Warning (#HEX)**
+- Usage: Warning messages, caution states
+- Accessibility: Passes WCAG AA
+
+**Error (#HEX)**
+- Usage: Error messages, destructive actions
+- Accessibility: Passes WCAG AA
+
+**Info (#HEX)**
+- Usage: Informational messages, help text
+- Accessibility: Passes WCAG AA
+
+### Color Combinations
+
+**Approved combinations:**
+- Primary 600 on White
+- White on Primary 700
+- Neutral 900 on Primary 50
+- Neutral 700 on Neutral 100
+
+**Avoid:**
+- Low contrast combinations
+- Primary on Secondary (insufficient contrast)
+- Pure black (#000) on anything (too harsh)
+
+---
+
+## 3. Typography
+
+### Font Families
+
+**Heading Font: [Font Name]**
+- Source: Google Fonts / Custom / System
+- Weights available: 400, 600, 700
+- Fallback: -apple-system, BlinkMacSystemFont, sans-serif
+
+**Body Font: [Font Name]**
+- Source: Google Fonts / Custom / System
+- Weights available: 400, 500, 600
+- Fallback: -apple-system, BlinkMacSystemFont, sans-serif
+
+**Monospace Font: [Font Name]**
+- Source: System
+- Usage: Code, technical content
+- Fallback: 'Courier New', monospace
+
+### Type Scale
+
+**Heading 1**
+- Size: 3.5rem (56px)
+- Weight: 700 (Bold)
+- Line height: 1.2
+- Letter spacing: -0.02em
+- Usage: Page titles, hero headlines
+
+**Heading 2**
+- Size: 2.5rem (40px)
+- Weight: 700 (Bold)
+- Line height: 1.3
+- Letter spacing: -0.01em
+- Usage: Section headings
+
+**Heading 3**
+- Size: 2rem (32px)
+- Weight: 600 (Semibold)
+- Line height: 1.4
+- Letter spacing: 0
+- Usage: Subsection headings
+
+**Heading 4**
+- Size: 1.5rem (24px)
+- Weight: 600 (Semibold)
+- Line height: 1.4
+- Usage: Card headings, component titles
+
+**Heading 5**
+- Size: 1.25rem (20px)
+- Weight: 500 (Medium)
+- Line height: 1.5
+- Usage: Small headings
+
+**Body Large**
+- Size: 1.125rem (18px)
+- Weight: 400 (Regular)
+- Line height: 1.6
+- Usage: Emphasis paragraphs, introductions
+
+**Body**
+- Size: 1rem (16px)
+- Weight: 400 (Regular)
+- Line height: 1.6
+- Usage: Default body text
+
+**Body Small**
+- Size: 0.875rem (14px)
+- Weight: 400 (Regular)
+- Line height: 1.5
+- Usage: Supporting text, captions
+
+**Caption**
+- Size: 0.75rem (12px)
+- Weight: 400 (Regular)
+- Line height: 1.4
+- Letter spacing: 0.01em
+- Usage: Metadata, labels
+
+### Text Colors
+
+- **Primary text:** Neutral 900 (#18181b)
+- **Secondary text:** Neutral 600 (#52525b)
+- **Disabled text:** Neutral 400 (#a1a1aa)
+- **Link text:** Primary 600 (#0284c7)
+- **Link hover:** Primary 700 (#0369a1)
+
+### Formatting Guidelines
+
+**Emphasis:**
+- **Bold** for strong emphasis
+- *Italic* for subtle emphasis
+- Underline for links only
+
+**Paragraphs:**
+- Max width: 65-75 characters
+- Spacing: 1.5em between paragraphs
+- First line: No indent (web convention)
+
+**Lists:**
+- Bullet points: Circle bullets
+- Numbered lists: Numbers with period
+- Spacing: 0.5em between items
+
+---
+
+## 4. Spacing & Layout
+
+### Spacing Scale
+
+Based on 8px base unit:
+
+| Token | Value | Pixels | Usage |
+|-------|-------|--------|-------|
+| 0 | 0 | 0px | Reset/None |
+| 1 | 0.25rem | 4px | Icon spacing |
+| 2 | 0.5rem | 8px | Tight spacing |
+| 3 | 0.75rem | 12px | Component padding |
+| 4 | 1rem | 16px | Default spacing |
+| 6 | 1.5rem | 24px | Card padding |
+| 8 | 2rem | 32px | Section spacing |
+| 12 | 3rem | 48px | Large spacing |
+| 16 | 4rem | 64px | Hero spacing |
+| 24 | 6rem | 96px | XL spacing |
+
+### Grid System
+
+**Container:**
+- Max width: 1280px (desktop)
+- Horizontal padding: 24px (mobile), 32px (desktop)
+- Centered with auto margins
+
+**Grid:**
+- Columns: 12
+- Gutter: 24px
+- Responsive breakpoints
+
+**Breakpoints:**
+- Mobile: 320px - 767px (full width, single column)
+- Tablet: 768px - 1023px (80% width, 2-3 columns)
+- Desktop: 1024px - 1439px (max 1280px, multi-column)
+- Wide: 1440px+ (max 1280px, multi-column)
+
+### Layout Patterns
+
+**Single column (Mobile):**
+- Full width sections
+- Stacked components
+- Minimal horizontal spacing
+
+**Two column (Tablet):**
+- 8-4 column split (main-sidebar)
+- 6-6 column split (equal)
+- Responsive card grids
+
+**Multi-column (Desktop):**
+- 3-6-3 (sidebar-main-sidebar)
+- 4-4-4 (three equal)
+- Flexible grid layouts
+
+---
+
+## 5. Components
+
+### Buttons
+
+**Primary Button**
+- Background: Primary 600
+- Text: White
+- Padding: 12px 24px
+- Border radius: 8px
+- Font weight: 500
+
+**States:**
+- Hover: Primary 700 background
+- Active: Primary 800 background
+- Focus: 2px outline, Primary 500
+- Disabled: Neutral 200 background, Neutral 400 text
+
+**Secondary Button**
+- Background: Neutral 200
+- Text: Neutral 900
+- [Same measurements as primary]
+
+**Ghost Button**
+- Background: Transparent
+- Text: Primary 600
+- [Same measurements as primary]
+
+### Input Fields
+
+**Text Input**
+- Height: 44px
+- Padding: 12px 16px
+- Border: 1px solid Neutral 300
+- Border radius: 8px
+- Font size: 16px
+
+**States:**
+- Focus: Primary 500 border, 2px outline
+- Error: Error 500 border, error icon
+- Success: Success 500 border, check icon
+- Disabled: Neutral 100 background
+
+### Cards
+
+**Standard Card**
+- Background: White
+- Border: 1px solid Neutral 200
+- Border radius: 12px
+- Padding: 24px
+- Shadow: 0 4px 6px rgba(0,0,0,0.1)
+
+**Interactive Card**
+- Hover: Shadow increases, slight lift
+- Active: Shadow reduces
+- Cursor: Pointer
+
+### Navigation
+
+**Navbar**
+- Height: 64px
+- Background: White
+- Border bottom: 1px solid Neutral 200
+- Padding: 0 32px
+- Sticky positioning
+
+**Nav Items**
+- Font size: 16px
+- Font weight: 500
+- Spacing: 24px between items
+- Active: Primary 600 color, underline
+
+---
+
+## 6. Iconography
+
+### Icon Style
+- **Style:** Outline
+- **Stroke width:** 2px
+- **Corner radius:** 2px
+- **Optical balance:** Centered in viewBox
+
+### Icon Sizes
+- **Small:** 16px (inline with text)
+- **Medium:** 24px (default, most common)
+- **Large:** 32px (feature icons)
+- **XL:** 48px+ (hero sections)
+
+### Icon Colors
+- **Primary:** Neutral 700 (default)
+- **Secondary:** Neutral 500
+- **Accent:** Primary 600
+- **Success:** Success 600
+- **Error:** Error 600
+
+### Icon Library
+List of commonly used icons:
+- Home, Search, Menu, Close
+- User, Settings, Notifications
+- Arrow (up, down, left, right)
+- Check, X, Info, Warning
+- Plus, Minus, Edit, Delete
+- Calendar, Clock, Location
+
+---
+
+## 7. Imagery
+
+### Photography Style
+
+**Characteristics:**
+- Bright, natural lighting
+- Authentic, not overly staged
+- Diverse subjects
+- Clean backgrounds
+
+**Aspect ratios:**
+- Hero: 21:9 or 16:9
+- Portrait: 3:4
+- Square: 1:1
+- Thumbnail: 4:3
+
+**Treatments:**
+- Border radius: 12px for cards
+- Overlay for text: 40% black gradient
+- No filters except brand-approved
+- Minimum resolution: 2x display size
+
+### Illustrations
+
+**Style:**
+- Flat design
+- Brand colors only
+- Simple geometric shapes
+- Consistent stroke width
+
+**Usage:**
+- Empty states
+- Error messages
+- Onboarding
+- Feature explanations
+
+---
+
+## 8. Voice & Tone
+
+### Brand Voice
+
+**Characteristics:**
+- Professional but approachable
+- Clear and concise
+- Helpful and encouraging
+- Confident without arrogance
+
+**We are:**
+- Knowledgeable experts
+- Supportive partners
+- Clear communicators
+
+**We are not:**
+- Overly casual or jokey
+- Condescending or robotic
+- Vague or uncertain
+
+### Tone Variations
+
+**Marketing:**
+- Energetic and inspiring
+- Benefit-focused
+- Action-oriented
+
+**Product UI:**
+- Clear and direct
+- Task-focused
+- Minimal and efficient
+
+**Support:**
+- Patient and helpful
+- Solution-oriented
+- Empathetic
+
+### Writing Guidelines
+
+**Button labels:**
+- Start with verb
+- Be specific
+- Keep short (1-3 words)
+- Examples: "Get Started", "Save Changes", "Download Report"
+
+**Error messages:**
+- Explain what went wrong
+- Suggest how to fix
+- Be empathetic
+- Example: "We couldn't process your payment. Please check your card details and try again."
+
+**Empty states:**
+- Explain why empty
+- Guide next action
+- Stay positive
+- Example: "No projects yet. Create your first project to get started."
+
+---
+
+## 9. Usage Guidelines
+
+### Do's and Don'ts
+
+**Colors:**
+✓ Use colors from defined palette
+✓ Maintain contrast ratios
+✓ Use semantic colors appropriately
+✗ Don't invent new brand colors
+✗ Don't use color alone to convey meaning
+✗ Don't use low-contrast combinations
+
+**Typography:**
+✓ Use defined type scale
+✓ Maintain hierarchy
+✓ Keep line length readable
+✗ Don't use too many font families
+✗ Don't skip heading levels
+✗ Don't use tiny font sizes (<14px)
+
+**Spacing:**
+✓ Use spacing scale values
+✓ Be consistent
+✓ Align to 8px grid
+✗ Don't use arbitrary spacing
+✗ Don't cram elements together
+✗ Don't create uneven rhythms
+
+**Components:**
+✓ Use existing components
+✓ Follow state patterns
+✓ Maintain consistency
+✗ Don't reinvent components
+✗ Don't customize without reason
+✗ Don't ignore accessibility
+
+### Accessibility Requirements
+
+**Minimum standards:**
+- Color contrast: WCAG AA (4.5:1)
+- Touch targets: 44x44px
+- Focus indicators: Visible
+- Alt text: All images
+- Keyboard navigation: Full support
+
+### Maintenance
+
+**Versioning:**
+- Major: Breaking changes
+- Minor: New components
+- Patch: Bug fixes, tweaks
+
+**Updates:**
+- Review quarterly
+- Document all changes
+- Communicate to team
+- Update all instances
+
+**Feedback:**
+- Designers submit proposals
+- Team reviews monthly
+- Consensus required
+- Document rationale
+
+---
+
+## Visual Examples
+
+### Example Page Layouts
+[Include mockups showing:]
+- Landing page
+- Dashboard
+- Form page
+- Content page
+- Mobile views
+
+### Component Gallery
+[Include visuals showing:]
+- All button variants
+- Form components
+- Cards
+- Navigation
+- Modals
+- Common patterns
+
+### Color Swatches
+[Include actual color samples]
+
+### Typography Specimens
+[Show each text style with sample content]
+
+---
+
+## File Formats
+
+**Design files:**
+- Figma/Sketch source files
+- Component library
+- Design tokens (JSON)
+
+**Development:**
+- CSS/SCSS variables
+- Tailwind config
+- Component code examples
+
+**Documentation:**
+- PDF version of style guide
+- Interactive HTML version
+- Markdown documentation
+
+---
+
+## Credits & Contact
+
+**Design team:**
+- Lead Designer: [Name]
+- UI Designer: [Name]
+- UX Researcher: [Name]
+
+**Contact:**
+- Questions: design-team@company.com
+- Contributions: Submit via [process]
+- Feedback: [feedback channel]
+
+**Resources:**
+- Design files: [Link]
+- Code repository: [Link]
+- Documentation: [Link]
+
+**Last updated:** [Date]
+**Version:** [Number]