Weave CSS

The Weave CSS system provides a consistent, themeable foundation for building blocks. This guide covers the core components, naming conventions, and theming capabilities of the system.

Core Components

Block Container (.w--block-container)

A wrapper component that provides consistent spacing and width constraints.

<div class="w--block-container">
  <!-- Block content -->
</div>

Customization:

• --block-container-max-width: Maximum width (default: 1200px)
• --block-container-padding-block: Vertical padding (default: 5rem)
• --block-container-padding-inline: Horizontal padding (default: 2rem)

Heading (.w--heading)

Consistent typography for headings with balanced text wrapping.

<h1 class="w--heading">Page Title</h1>

Customization:

• --heading-font-family: Font family
• --heading-font-size: Font size (default: 2.5rem)
• --heading-line-height: Line height (default: 1)
• --heading-font-weight: Font weight (default: 600)
• --heading-color: Text color

Button (.w--button)

Versatile button component with solid and outline styles.

<button class="w--button">Click Me</button>
<a class="w--button -outline">Outline Button</a>

Customization:

• --button-gap: Content spacing (default: 0.5rem)
• --button-color: Text color
• --button-background: Background color
• --button-border: Border style
• --button-border-radius: Border radius
• --button-padding-block: Vertical padding
• --button-padding-inline: Horizontal padding

Prose (.w--prose)

Rich text container with consistent typography and spacing.

<div class="w--prose">
  <h1>Article Title</h1>
  <p>Content...</p>
</div>

Customization includes variables for:

• Paragraphs
• Headings (h1-h6)
• Lists
• Blockquotes
• Code blocks
• Horizontal rules

CSS Naming Conventions

Component Structure

<div class="card -large">
    <div class="_content">
        <div class="_header">
            <h1 class="_title">Title</h1>
        </div>
    </div>
</div>

Rules

1. Root Components

• No prefix: card, button-group
• Can use modifiers
• Represent main UI elements

1. Child Elements

• Underscore prefix: _content, _header
• Must be nested within parent
• Represent component parts

1. Modifiers

• Hyphen prefix: -large, -outline
• Only on root components
• Represent variants

CSS Structure

.card {
    /* Base styles */

    &.-large {
        /* Modifier styles */

        ._header {
            /* Nested element styles when modified */
        }
    }

    ._header {
        /* Element styles */
    }
}

Theming

Site-Level Customization

:root {
    /* Design Tokens */
    --primary-color: #ff6b6b;
    --radius: 8px;
    --shadow: 0 2px 4px rgba(0,0,0,0.1);
    --heading-font: 'Playfair Display';
    --body-font: 'Inter';

    /* Component Themes */
    --button-border-radius: 9999px;
    --prose-blockquote-border: 2px solid var(--primary-color);
}

Responsive Theming

:root {
    --block-container-max-width: 800px;
    --block-container-padding-inline: 1rem;
}

@media (min-width: 768px) {
    :root {
        --block-container-max-width: 1000px;
        --block-container-padding-inline: 2rem;
    }
}

Dark Mode

:root {
    --primary-color: #6c5ce7;
    --prose-p-color: #2d3436;
}

@media (prefers-color-scheme: dark) {
    :root {
        --primary-color: #a29bfe;
        --prose-p-color: #dfe6e9;
    }
}

Best Practices

Using CSS Variables

• Use variables for themeable properties
• Reference design system tokens where appropriate
• Consider responsive adjustments
• Plan for dark mode support

Component Integration

• Use Weave components for consistent styling
• Follow naming conventions for custom components
• Maintain proper nesting structure
• Consider component evolution

Responsive Design

• Use CSS variables for breakpoint adjustments
• Plan mobile-first layouts
• Test across device sizes
• Consider container queries where appropriate

Tips and Techniques

Component Evolution

As components grow, consider breaking out complex sections:

<!-- Before -->
<div class="card">
    <div class="_header">
        <h1 class="_title">Title</h1>
    </div>
</div>

<!-- After -->
<div class="card">
    <div class="card-header">
        <h1 class="_title">Title</h1>
    </div>
</div>

Context-Specific Styling

Use CSS variables for different contexts:

/* Global styles */
:root {
    --button-background: var(--primary-color);
}

/* Section-specific */
.hero-section {
    --button-background: white;
    --button-color: black;
}