blueprint/docs/getting-started.md

Getting Started with Blueprint

Installation

1. Clone the repository:

git clone https://github.com/yourusername/blueprint.git
cd blueprint

2. Install dependencies:

npm install

3. Create your first Blueprint file:

mkdir src
touch src/index.bp

Basic Usage

Blueprint uses a declarative syntax to define UI components. Each file with a .bp extension will be compiled into HTML and CSS.

Basic Structure

A Blueprint file consists of elements, which can have properties and children. Properties can be flags or key-value pairs:

element(flag1, key:value) {
    child-element {
        // Content
    }
}

Property Types

Blueprint supports several types of properties:

1. Flag Properties

   button(bold, centered) { "Text" }
   

2. Key-Value Properties

   input(type:email, placeholder:"Enter email")
   

3. Numeric Properties

   section(width:80, padding:20)
   

4. Color Properties

   text(color:#ff0000) { "Red text" }
   

Page Configuration

Every Blueprint page can have metadata defined using the page element:

page {
    title { "My Page Title" }
    description { "Page description for SEO" }
    keywords { "keyword1, keyword2, keyword3" }
    author { "Author Name" }
    meta-viewport { "width=device-width, initial-scale=1" }
}

Available page metadata:

• title: Page title (appears in browser tab)
• description: Meta description for SEO
• keywords: Meta keywords for SEO
• author: Page author
• meta-*: Custom meta tags (e.g., meta-viewport, meta-robots)

Basic Layout

A typical page structure:

page {
    title { "My First Page" }
    description { "A simple Blueprint page" }
    meta-viewport { "width=device-width, initial-scale=1" }
}

navbar {
    horizontal(spaced) {
        text(bold) { "My App" }
        links {
            link(href:/) { "Home" }
            link(href:/about) { "About" }
            link(href:/contact) { "Contact" }
        }
    }
}

section(wide, centered) {
    vertical(gap:2) {
        title(huge) { "Welcome to Blueprint" }
        text(subtle) { "Start building beautiful UIs with Blueprint" }
        
        horizontal(centered, gap:2) {
            button { "Get Started" }
            button-light { "Learn More" }
        }
    }
}

section(wide) {
    grid(columns:3) {
        card {
            title { "Feature 1" }
            text { "Description of feature 1" }
            button-secondary { "Learn More" }
        }
        card {
            title { "Feature 2" }
            text { "Description of feature 2" }
            button-secondary { "Learn More" }
        }
        card {
            title { "Feature 3" }
            text { "Description of feature 3" }
            button-secondary { "Learn More" }
        }
    }
}

Project Structure

A typical Blueprint project has the following structure:

my-blueprint-project/
├── src/                  # Source Blueprint files
│   ├── index.bp         # Main page
│   ├── about.bp         # About page
│   └── contact.bp       # Contact page
├── public/              # Static assets
│   ├── images/          # Image files
│   ├── fonts/           # Font files
│   └── favicon.ico      # Favicon
├── dist/                # Generated files (auto-generated)
│   ├── index.html       # Compiled HTML
│   ├── index.css        # Generated CSS
│   └── ...
└── package.json         # Project configuration

Error Handling

Blueprint provides helpful error messages when something goes wrong:

BlueprintError at line 5, column 10:
Unknown element type: invalid-element

Common errors include:

• Missing closing braces
• Unknown element types
• Invalid property values
• Unterminated strings
• Missing required properties
• Invalid color values
• Invalid numeric values

Best Practices

1. Organization

   • Group related elements logically
   • Use consistent spacing and indentation
   • Keep files focused on a single purpose
   • Split large files into components

2. Naming

   • Use descriptive names for links and sections
   • Follow a consistent naming convention
   • Use semantic element names

3. Layout

   • Use semantic elements (section, navbar, etc.)
   • Leverage the grid system for responsive layouts
   • Use appropriate spacing with gap property
   • Use width and padding for fine-tuned control

4. Styling

   • Use predefined style properties when possible
   • Group related styles together
   • Keep styling consistent across pages
   • Use custom properties sparingly

5. Performance

   • Keep files small and focused
   • Use appropriate image formats and sizes
   • Minimize custom styles
   • Leverage built-in responsive features

Next Steps

• Explore available components
• Learn about styling
• Check out examples
• Read about advanced features in the component documentation