Guide Styling Standards

This document outlines the shared styling approach for all guides in the Linchpin Blocks plugin.

Philosophy

All guides in the plugin should have a consistent, polished appearance using WordPress's native Guide component with enhanced styling for better UX.

Current Guides

1. Animation Block Guide (blocks/src/animation/components/guide/)
   • Class: .linchpin-animation-guide
   • Styles: blocks/src/animation/scss/guide.scss
2. Animation Features Guide (src/animation-controls/components/guide/)
   • Class: .linchpin-animation-features-guide
   • Styles: src/animation-controls/editor-styles.scss

Shared Styling Approach

Both guides use identical SCSS patterns to ensure visual consistency:

1. Modal Sizing

.components-modal__frame {
	min-width: 600px;  // Prevents resize between pages
	max-width: 700px;  // Comfortable reading width
}

Why: The min-width prevents jarring resize animations when navigating between steps with different content lengths.

2. Content Padding

.components-modal__content {
	padding: 32px;  // Generous breathing room
}

Why: Adequate padding makes the content feel less cramped and more professional.

3. Page Container

&__page {
	min-width: 500px;
	max-width: 600px;
	margin: 0 auto;
}

Why: Centers content and ensures consistent width regardless of step content.

4. Typography

h3 {
	margin-bottom: 16px;
	font-size: 20px;
	font-weight: 600;
}

p {
	line-height: 1.6;
	margin-bottom: 12px;
}

ul, ol {
	margin: 12px 0;
	padding-left: 24px;

	li {
		margin-bottom: 8px;
		line-height: 1.6;
	}
}

Why: Improved readability and visual hierarchy.

5. Skip Button Enhancement

.components-button.is-tertiary {
	margin-top: 16px;
	padding: 8px 16px;
	font-weight: 500;
	border: 1px solid #ddd;
	border-radius: 4px;
	transition: all 0.2s ease;

	&:hover {
		background-color: #f0f0f0;
		border-color: #999;
	}
}

Why: Makes the skip button more prominent and discoverable, giving users a clear exit option.

6. Tip Boxes

> p[style*="background"] {
	background-color: #f0f0f1 !important;
	padding: 16px;
	border-radius: 4px;
	border-left: 4px solid #2271b1;
	margin: 16px 0;
}

Why: Highlights important tips with WordPress's primary blue accent color.

Adding a New Guide

When creating a new guide, follow these steps:

1. Structure

your-feature/
├── components/
│   └── guide/
│       ├── index.js              # Main guide component
│       ├── step-wrapper.js       # Use StepWrapper pattern
│       └── steps/
│           ├── step-1.js
│           ├── step-2.js
│           └── ...

2. CSS Class Naming

Use the pattern: .linchpin-[feature]-guide

Example:

• .linchpin-animation-guide
• .linchpin-animation-features-guide
• .linchpin-layout-guide (hypothetical)

3. Copy Shared Styles

Copy the shared SCSS pattern from either:

• blocks/src/animation/scss/guide.scss
• src/animation-controls/editor-styles.scss (search for .linchpin-animation-features-guide)

Update only the class name to match your guide.

4. StepWrapper Component

import {
	__experimentalVStack as VStack,
	__experimentalHeading as Heading,
} from '@wordpress/components';

export const StepWrapper = ( { title, children, maxWidth } ) => {
	return (
		<VStack
			className="linchpin-[your-feature]-guide__page"
			style={ { maxWidth: maxWidth || '600px' } }
		>
			<Heading level={ 3 }>{ title }</Heading>
			{ children }
		</VStack>
	);
};

5. Step Structure

import { __ } from '@wordpress/i18n';
import { Button } from '@wordpress/components';
import { StepWrapper } from '../step-wrapper';

export const YourStep = ( { onDismiss } ) => {
	return (
		<StepWrapper title={ __( 'Step Title', 'linchpin-blocks' ) }>
			<p>
				{ __( 'Your content here...', 'linchpin-blocks' ) }
			</p>
			
			{/* Optional: Skip button on non-final steps */}
			<Button variant="tertiary" onClick={ onDismiss }>
				{ __( 'Skip this guide', 'linchpin-blocks' ) }
			</Button>
		</StepWrapper>
	);
};

6. Final Step Pattern

The last step should have:

• Summary of key points
• Link to documentation
• Tip box about reopening the guide
• Prominent dismiss button

<div style={ { marginTop: '24px', paddingTop: '16px', borderTop: '1px solid #ddd' } }>
	<Button variant="tertiary" onClick={ onDismiss }>
		{ __( 'Dismiss this guide permanently', 'linchpin-blocks' ) }
	</Button>
</div>

Design Tokens

Spacing

• Small gap: 8px
• Medium gap: 12px
• Large gap: 16px
• Section gap: 24px
• Modal padding: 32px

Colors

• Border: #ddd
• Border hover: #999
• Background light: #f0f0f0
• Background subtle: #f0f0f1
• Accent (tips): #2271b1 (WordPress blue)

Typography

• Heading size: 20px
• Heading weight: 600
• Body line-height: 1.6
• Button font-weight: 500

Borders

• Standard: 1px solid
• Accent left border: 4px solid
• Border radius: 4px

UX Principles

1. Consistent Sizing: All guides should feel the same width and never resize between steps
2. Generous Spacing: Use padding and margins liberally – white space aids comprehension
3. Clear Hierarchy: Headings, body text, and buttons should have distinct visual weights
4. Prominent Actions: Skip buttons should be obvious – users should never feel trapped
5. Visual Feedback: Hover states on interactive elements
6. Accessibility: Maintain WordPress's accessible Guide component defaults

Testing Checklist

When implementing a new guide, verify:

• Modal doesn't resize when navigating between steps
• Content has adequate padding (not cramped)
• Skip button is visible and styled consistently
• Tip boxes have blue accent border
• Lists have proper indentation (24px)
• Typography is consistent (line-height 1.6)
• Hover states work on buttons
• Guide opens/closes smoothly
• Works with both light and dark WordPress themes
• Content is readable at all viewport sizes

Future Improvements

Potential enhancements to consider:

1. Shared SCSS Partial: Extract common styles into _guide-base.scss
2. Theme Variables: Use CSS custom properties for easier theming
3. Animation: Subtle transitions between steps
4. Mobile Optimization: Responsive styles for smaller screens
5. Dark Mode: Enhanced contrast for dark WordPress themes

Related Files

• Animation Block Guide: blocks/src/animation/scss/guide.scss
• Animation Features Guide: src/animation-controls/editor-styles.scss
• WordPress Guide Component: @wordpress/components

Support

For questions about guide styling:

1. Review this document
2. Check existing guide implementations
3. Test changes in both guides to ensure consistency
4. Update this document if you discover better patterns