release

docs/README.md

@@ -0,0 +1,142 @@
+# Blueprint Documentation
+
+Blueprint is a modern, declarative UI framework for building beautiful web interfaces. It provides a simple, intuitive syntax for creating responsive, dark-themed web applications with consistent styling and behavior.
+
+## Core Features
+
+- **Declarative Syntax**: Write UI components using a clean, intuitive syntax
+- **Dark Theme**: Beautiful dark theme with consistent styling
+- **Responsive Design**: Built-in responsive design system
+- **Component-Based**: Rich set of reusable components
+- **Type-Safe**: Catch errors before they reach the browser
+- **Custom Properties**: Direct control over styling when needed
+- **Live Preview**: Changes appear instantly in your browser
+
+## Documentation Structure
+
+1. [Getting Started](getting-started.md)
+   - Installation
+   - Basic Usage
+   - Project Structure
+   - Property Types
+   - Page Configuration
+   - Error Handling
+   - Best Practices
+
+2. [Components](components.md)
+   - Layout Components (Section, Grid, Horizontal, Vertical)
+   - Typography (Title, Text)
+   - Navigation (Navbar, Links)
+   - Form Elements (Input, Textarea, Select, Checkbox, Radio, Switch)
+   - Interactive Components (Button, Card, Badge, Alert, Tooltip)
+   - Container Components (List, Table, Progress, Slider)
+
+3. [Styling](styling.md)
+   - Layout Properties
+   - Typography Properties
+   - Component Styles
+   - Interactive States
+   - Responsive Design
+   - Custom Properties
+   - Theme Variables
+   - Best Practices
+
+4. [Examples](examples.md)
+   - Basic Examples
+   - Layout Examples
+   - Form Examples
+   - Navigation Examples
+   - Complete Page Examples
+
+## Quick Start
+
+```blueprint
+page {
+    title { "My First Blueprint Page" }
+    description { "A simple Blueprint page example" }
+    meta-viewport { "width=device-width, initial-scale=1" }
+}
+
+navbar {
+    horizontal(spaced) {
+        text(bold) { "My App" }
+        links {
+            link(href:/) { "Home" }
+            link(href:/about) { "About" }
+        }
+    }
+}
+
+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" }
+        }
+    }
+}
+```
+
+## Key Concepts
+
+1. **Elements**
+   - Basic building blocks of Blueprint
+   - Each element maps to an HTML tag
+   - Elements can have properties and children
+   - Elements follow semantic naming
+
+2. **Properties**
+   - Flag properties (e.g., `centered`, `bold`)
+   - Key-value properties (e.g., `type:email`)
+   - Numeric properties (e.g., `width:80`)
+   - Color properties (e.g., `color:#ff0000`)
+
+3. **Styling**
+   - Consistent dark theme
+   - Built-in responsive design
+   - Direct style properties
+   - Theme variables
+   - Interactive states
+
+4. **Components**
+   - Layout components
+   - Form elements
+   - Interactive components
+   - Container components
+   - Typography elements
+
+## Best Practices
+
+1. **Organization**
+   - Group related elements
+   - Use consistent spacing
+   - Keep files focused
+   - Split into components
+
+2. **Styling**
+   - Use predefined properties
+   - Maintain consistency
+   - Leverage built-in features
+   - Custom styles sparingly
+
+3. **Performance**
+   - Small, focused files
+   - Optimize assets
+   - Use responsive features
+   - Minimize custom styles
+
+4. **Accessibility**
+   - Semantic elements
+   - Color contrast
+   - Focus states
+   - Screen reader support
+
+## Need Help?
+
+- Check the [examples](examples.md) for common patterns
+- Read the [components guide](components.md) for detailed documentation
+- Learn about styling in the [styling guide](styling.md)
+- Start with the [getting started guide](getting-started.md) for basics 

docs/components.md

@@ -0,0 +1,365 @@
+# Blueprint Components
+
+Blueprint provides a rich set of components for building modern web interfaces. Each component is designed to be responsive, accessible, and consistent with the dark theme.
+
+## Layout Components
+
+### Section
+Container for page sections:
+```blueprint
+section(wide, centered) {
+    // Content
+}
+```
+Properties:
+- `wide`: Full width with max-width constraint (1200px)
+- `centered`: Center content horizontally and vertically
+- `alternate`: Alternate background color
+- `padding`: Custom padding in pixels
+- `margin`: Custom margin in pixels
+
+### Grid
+Responsive grid layout:
+```blueprint
+grid(columns:3) {
+    // Grid items
+}
+```
+Properties:
+- `columns`: Number of columns (default: auto-fit)
+- `responsive`: Enable responsive behavior
+- `gap`: Custom gap size between items
+- `width`: Custom width in percentage
+
+### Horizontal
+Horizontal flex container:
+```blueprint
+horizontal(centered, spaced) {
+    // Horizontal items
+}
+```
+Properties:
+- `centered`: Center items vertically
+- `spaced`: Space between items
+- `gap`: Custom gap size
+- `width`: Custom width in percentage
+- `responsive`: Wrap items on small screens
+
+### Vertical
+Vertical flex container:
+```blueprint
+vertical(centered) {
+    // Vertical items
+}
+```
+Properties:
+- `centered`: Center items horizontally
+- `spaced`: Space between items
+- `gap`: Custom gap size
+- `width`: Custom width in percentage
+
+## Typography
+
+### Title
+Page or section titles:
+```blueprint
+title(huge) { "Main Title" }
+title(large) { "Section Title" }
+```
+Properties:
+- `huge`: Very large size (4rem)
+- `large`: Large size (2rem)
+- `bold`: Bold weight
+- `centered`: Center align
+- `color`: Custom text color
+
+### Text
+Regular text content:
+```blueprint
+text(large) { "Large text" }
+text(subtle) { "Subtle text" }
+```
+Properties:
+- `large`: Larger size
+- `small`: Smaller size (0.875rem)
+- `subtle`: Muted color
+- `bold`: Bold weight
+- `color`: Custom text color
+
+## Navigation
+
+### Navbar
+Fixed navigation bar:
+```blueprint
+navbar {
+    horizontal {
+        text(bold) { "Brand" }
+        links {
+            link(href:home) { "Home" }
+            link(href:about) { "About" }
+        }
+    }
+}
+```
+Properties:
+- `sticky`: Fixed to top
+- `transparent`: Transparent background
+- `backgroundColor`: Custom background color
+
+### Links
+Navigation link group:
+```blueprint
+links {
+    link(href:page1) { "Link 1" }
+    link(href:page2) { "Link 2" }
+}
+```
+Properties:
+- `spaced`: Add spacing between links
+- `vertical`: Vertical orientation
+- `gap`: Custom gap size
+
+### Link
+Individual link:
+```blueprint
+link(href:page, text:"Click here") { }
+link(href:https://example.com) { "External Link" }
+```
+Properties:
+- `href`: Target URL or page
+- `text`: Link text (optional)
+- `external`: Open in new tab (automatic for http/https URLs)
+- `color`: Custom text color
+
+## Interactive Components
+
+### Button
+Various button styles:
+```blueprint
+button { "Primary" }
+button-secondary { "Secondary" }
+button-light { "Light" }
+button-compact { "Compact" }
+```
+Properties:
+- `disabled`: Disabled state
+- `width`: Custom width in percentage
+- `backgroundColor`: Custom background color
+- `color`: Custom text color
+
+### Card
+Content container with hover effect:
+```blueprint
+card {
+    title { "Card Title" }
+    text { "Card content" }
+    button { "Action" }
+}
+```
+Properties:
+- `raised`: Add shadow and hover effect
+- `width`: Custom width in percentage
+- `padding`: Custom padding in pixels
+- `backgroundColor`: Custom background color
+
+### Badge
+Status indicators:
+```blueprint
+badge { "New" }
+badge(color:blue) { "Status" }
+```
+Properties:
+- `color`: Custom badge color
+- `backgroundColor`: Custom background color
+- `width`: Custom width in percentage
+
+### Alert
+Notification messages:
+```blueprint
+alert(type:info) { "Information message" }
+```
+Properties:
+- `type`: info, success, warning, error
+- `backgroundColor`: Custom background color
+- `color`: Custom text color
+- `width`: Custom width in percentage
+
+### Tooltip
+Hover tooltips:
+```blueprint
+tooltip(text:"More info") {
+    text { "Hover me" }
+}
+```
+Properties:
+- `text`: Tooltip text
+- `position`: top, right, bottom, left
+- `backgroundColor`: Custom background color
+- `color`: Custom text color
+
+## Form Elements
+
+### Input
+Text input field:
+```blueprint
+input(placeholder:"Type here") { }
+```
+Properties:
+- `placeholder`: Placeholder text
+- `type`: Input type (text, email, password, etc.)
+- `required`: Required field
+- `disabled`: Disabled state
+- `width`: Custom width in percentage
+
+### Textarea
+Multi-line text input:
+```blueprint
+textarea(placeholder:"Enter message") { }
+```
+Properties:
+- `placeholder`: Placeholder text
+- `rows`: Number of visible rows
+- `required`: Required field
+- `width`: Custom width in percentage
+
+### Select
+Dropdown selection:
+```blueprint
+select {
+    option { "Option 1" }
+    option { "Option 2" }
+}
+```
+Properties:
+- `placeholder`: Placeholder text
+- `required`: Required field
+- `disabled`: Disabled state
+- `width`: Custom width in percentage
+
+### Checkbox
+Checkbox input:
+```blueprint
+horizontal {
+    checkbox { }
+    text { "Accept terms" }
+}
+```
+Properties:
+- `checked`: Default checked state
+- `required`: Required field
+- `disabled`: Disabled state
+- `width`: Custom width in percentage
+
+### Radio
+Radio button input:
+```blueprint
+vertical {
+    horizontal {
+        radio(name:"choice") { }
+        text { "Option 1" }
+    }
+    horizontal {
+        radio(name:"choice") { }
+        text { "Option 2" }
+    }
+}
+```
+Properties:
+- `name`: Group name
+- `checked`: Default checked state
+- `disabled`: Disabled state
+- `width`: Custom width in percentage
+
+### Switch
+Toggle switch:
+```blueprint
+horizontal {
+    switch { }
+    text { "Enable feature" }
+}
+```
+Properties:
+- `checked`: Default checked state
+- `disabled`: Disabled state
+- `width`: Custom width in percentage
+
+## Container Components
+
+### List
+Ordered or unordered lists:
+```blueprint
+list {
+    text { "Item 1" }
+    text { "Item 2" }
+}
+```
+Properties:
+- `ordered`: Use ordered list
+- `bullet`: Show bullets
+- `spaced`: Add spacing
+- `width`: Custom width in percentage
+
+### Table
+Data tables:
+```blueprint
+table {
+    row {
+        cell { "Header 1" }
+        cell { "Header 2" }
+    }
+    row {
+        cell { "Data 1" }
+        cell { "Data 2" }
+    }
+}
+```
+Properties:
+- `striped`: Alternate row colors
+- `bordered`: Add borders
+- `compact`: Reduced padding
+- `width`: Custom width in percentage
+
+### Progress
+Progress indicators:
+```blueprint
+progress(value:75, max:100) { }
+```
+Properties:
+- `value`: Current value
+- `max`: Maximum value
+- `indeterminate`: Loading state
+- `width`: Custom width in percentage
+
+### Slider
+Range input:
+```blueprint
+slider(min:0, max:100, value:50) { }
+```
+Properties:
+- `min`: Minimum value
+- `max`: Maximum value
+- `step`: Step increment
+- `disabled`: Disabled state
+- `width`: Custom width in percentage
+
+### Media
+Images and videos with responsive behavior:
+```blueprint
+media(src:/path/to/image.jpg) { "Image description" }
+media(src:https://example.com/video.mp4, type:video) { "Video description" }
+```
+Properties:
+- `src`: URL or path to the media file (required)
+- `type`: Media type (`img` or `video`, defaults to `img`)
+- `width`: Custom width in percentage
+- `height`: Custom height in percentage
+- `padding`: Custom padding in pixels
+- `margin`: Custom margin in pixels
+
+The media component automatically:
+- Scales images/videos responsively (max-width: 100%)
+- Maintains aspect ratio (height: auto)
+- Adds rounded corners
+- Includes a subtle hover effect
+- Uses the content as alt text for images
+- Adds video controls when type is video 

docs/examples.md

@@ -0,0 +1,375 @@
+# Blueprint Examples
+
+This guide provides comprehensive examples of common UI patterns and layouts using Blueprint.
+
+## Basic Examples
+
+### Page Setup
+```blueprint
+page {
+    title { "My Blueprint Page" }
+    description { "A comprehensive example page" }
+    keywords { "blueprint, example, ui" }
+    author { "Blueprint Team" }
+}
+
+navbar {
+    horizontal {
+        text(bold) { "My App" }
+        links {
+            link(href:home) { "Home" }
+            link(href:about) { "About" }
+            link(href:contact) { "Contact" }
+        }
+    }
+}
+
+section(wide, centered) {
+    title(huge) { "Welcome" }
+    text(subtle) { "Start building beautiful UIs" }
+}
+```
+
+### Basic Card
+```blueprint
+card {
+    title { "Simple Card" }
+    text { "This is a basic card with some content." }
+    button { "Learn More" }
+}
+```
+
+### Alert Messages
+```blueprint
+vertical(gap:2) {
+    alert(type:info) { "This is an information message" }
+    alert(type:success) { "Operation completed successfully" }
+    alert(type:warning) { "Please review your input" }
+    alert(type:error) { "An error occurred" }
+}
+```
+
+## Layout Examples
+
+### Grid Layout
+```blueprint
+section(wide) {
+    title { "Our Features" }
+    
+    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" }
+        }
+    }
+}
+```
+
+### Responsive Layout
+```blueprint
+section(wide) {
+    horizontal(mobile-stack) {
+        vertical(width:40) {
+            title { "Left Column" }
+            text { "This column takes 40% width on desktop" }
+        }
+        vertical(width:60) {
+            title { "Right Column" }
+            text { "This column takes 60% width on desktop" }
+        }
+    }
+}
+```
+
+### Nested Layout
+```blueprint
+section(wide) {
+    vertical(centered) {
+        title(huge) { "Nested Layout" }
+        
+        horizontal(centered, gap:4) {
+            vertical(centered) {
+                title { "Column 1" }
+                text { "Content" }
+            }
+            vertical(centered) {
+                title { "Column 2" }
+                text { "Content" }
+            }
+        }
+    }
+}
+```
+
+## Form Examples
+
+### Login Form
+```blueprint
+section(wide, centered) {
+    card {
+        title { "Login" }
+        vertical(gap:2) {
+            vertical {
+                text(bold) { "Email" }
+                input(type:email, placeholder:"Enter your email") { }
+            }
+            vertical {
+                text(bold) { "Password" }
+                input(type:password, placeholder:"Enter your password") { }
+            }
+            horizontal {
+                checkbox { }
+                text { "Remember me" }
+            }
+            button { "Sign In" }
+            text(small, centered) { "Forgot password?" }
+        }
+    }
+}
+```
+
+### Contact Form
+```blueprint
+section(wide) {
+    card {
+        title { "Contact Us" }
+        vertical(gap:2) {
+            horizontal(gap:2) {
+                vertical {
+                    text(bold) { "First Name" }
+                    input(placeholder:"John") { }
+                }
+                vertical {
+                    text(bold) { "Last Name" }
+                    input(placeholder:"Doe") { }
+                }
+            }
+            vertical {
+                text(bold) { "Email" }
+                input(type:email, placeholder:"john@example.com") { }
+            }
+            vertical {
+                text(bold) { "Message" }
+                textarea(placeholder:"Your message here...") { }
+            }
+            button { "Send Message" }
+        }
+    }
+}
+```
+
+### Settings Form
+```blueprint
+section(wide) {
+    card {
+        title { "Settings" }
+        vertical(gap:3) {
+            horizontal {
+                vertical(width:70) {
+                    title(small) { "Notifications" }
+                    text(subtle) { "Manage your notification preferences" }
+                }
+                switch { }
+            }
+            horizontal {
+                vertical(width:70) {
+                    title(small) { "Dark Mode" }
+                    text(subtle) { "Toggle dark/light theme" }
+                }
+                switch { }
+            }
+            horizontal {
+                vertical(width:70) {
+                    title(small) { "Email Updates" }
+                    text(subtle) { "Receive email updates about your account" }
+                }
+                switch { }
+            }
+        }
+    }
+}
+```
+
+## Navigation Examples
+
+### Complex Navbar
+```blueprint
+navbar {
+    horizontal {
+        horizontal(gap:2) {
+            text(bold) { "Logo" }
+            links {
+                link(href:home) { "Home" }
+                link(href:products) { "Products" }
+                link(href:pricing) { "Pricing" }
+                link(href:about) { "About" }
+            }
+        }
+        horizontal(gap:2) {
+            button-light { "Sign In" }
+            button { "Get Started" }
+        }
+    }
+}
+```
+
+### Sidebar Navigation
+```blueprint
+horizontal {
+    vertical(width:20) {
+        title { "Dashboard" }
+        links(vertical) {
+            link(href:home) { "Home" }
+            link(href:profile) { "Profile" }
+            link(href:settings) { "Settings" }
+            link(href:help) { "Help" }
+        }
+    }
+    vertical(width:80) {
+        title { "Main Content" }
+        text { "Your content here" }
+    }
+}
+```
+
+### Breadcrumb Navigation
+```blueprint
+horizontal(gap:1) {
+    link(href:home) { "Home" }
+    text { ">" }
+    link(href:products) { "Products" }
+    text { ">" }
+    text(bold) { "Current Page" }
+}
+```
+
+## Complete Page Examples
+
+### Landing Page
+```blueprint
+page {
+    title { "Blueprint - Modern UI Framework" }
+    description { "Build beautiful web interfaces with Blueprint" }
+}
+
+navbar {
+    horizontal {
+        text(bold) { "Blueprint" }
+        links {
+            link(href:features) { "Features" }
+            link(href:docs) { "Docs" }
+            link(href:pricing) { "Pricing" }
+            button { "Get Started" }
+        }
+    }
+}
+
+section(wide, centered) {
+    vertical(centered) {
+        title(huge) { "Build Beautiful UIs" }
+        text(large, subtle) { "Create modern web interfaces with ease" }
+        horizontal(centered, gap:2) {
+            button { "Get Started" }
+            button-light { "Learn More" }
+        }
+    }
+}
+
+section(wide) {
+    grid(columns:3) {
+        card {
+            title { "Easy to Use" }
+            text { "Simple, declarative syntax for building UIs" }
+            button-secondary { "Learn More" }
+        }
+        card {
+            title { "Modern Design" }
+            text { "Beautiful dark theme with consistent styling" }
+            button-secondary { "View Examples" }
+        }
+        card {
+            title { "Responsive" }
+            text { "Looks great on all devices out of the box" }
+            button-secondary { "See Details" }
+        }
+    }
+}
+```
+
+### Dashboard Page
+```blueprint
+page {
+    title { "Dashboard - My App" }
+}
+
+navbar {
+    horizontal {
+        text(bold) { "Dashboard" }
+        horizontal {
+            text { "Welcome back, " }
+            text(bold) { "John" }
+        }
+    }
+}
+
+section(wide) {
+    grid(columns:4) {
+        card {
+            title { "Total Users" }
+            text(huge) { "1,234" }
+            text(subtle) { "+12% this month" }
+        }
+        card {
+            title { "Revenue" }
+            text(huge) { "$5,678" }
+            text(subtle) { "+8% this month" }
+        }
+        card {
+            title { "Active Users" }
+            text(huge) { "892" }
+            text(subtle) { "Currently online" }
+        }
+        card {
+            title { "Conversion" }
+            text(huge) { "3.2%" }
+            text(subtle) { "+0.8% this month" }
+        }
+    }
+    
+    horizontal(gap:4) {
+        vertical(width:60) {
+            card {
+                title { "Recent Activity" }
+                list {
+                    text { "User signup: John Doe" }
+                    text { "New order: #12345" }
+                    text { "Payment received: $99" }
+                }
+            }
+        }
+        vertical(width:40) {
+            card {
+                title { "Quick Actions" }
+                vertical(gap:2) {
+                    button { "Create User" }
+                    button-secondary { "View Reports" }
+                    button-light { "Export Data" }
+                }
+            }
+        }
+    }
+}
+```
+
+These examples demonstrate common UI patterns and how to implement them using Blueprint. Use them as a starting point for your own projects and customize them to match your needs. 

docs/getting-started.md

@@ -0,0 +1,213 @@
+# Getting Started with Blueprint
+
+## Installation
+
+1. Clone the repository:
+```bash
+git clone https://github.com/yourusername/blueprint.git
+cd blueprint
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Create your first Blueprint file:
+```bash
+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:
+
+```blueprint
+element(flag1, key:value) {
+    child-element {
+        // Content
+    }
+}
+```
+
+### Property Types
+
+Blueprint supports several types of properties:
+
+1. **Flag Properties**
+   ```blueprint
+   button(bold, centered) { "Text" }
+   ```
+
+2. **Key-Value Properties**
+   ```blueprint
+   input(type:email, placeholder:"Enter email")
+   ```
+
+3. **Numeric Properties**
+   ```blueprint
+   section(width:80, padding:20)
+   ```
+
+4. **Color Properties**
+   ```blueprint
+   text(color:#ff0000) { "Red text" }
+   ```
+
+### Page Configuration
+
+Every Blueprint page can have metadata defined using the `page` element:
+
+```blueprint
+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:
+
+```blueprint
+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](components.md)
+- Learn about [styling](styling.md)
+- Check out [examples](examples.md)
+- Read about advanced features in the component documentation 

docs/styling.md

@@ -0,0 +1,233 @@
+# Blueprint Styling Guide
+
+Blueprint provides a comprehensive styling system that ensures consistent, beautiful dark-themed UIs. This guide covers all available styling properties and how to use them effectively.
+
+## Style Properties
+
+### Layout Properties
+
+#### Spacing and Sizing
+- `wide`: Full width with max-width constraint (1200px)
+- `compact`: Reduced padding (0.75rem)
+- `spaced`: Space between items (gap: 1.5rem)
+- `gap`: Custom gap size between items
+- `width`: Custom width in percentage
+- `height`: Custom height in percentage
+- `padding`: Custom padding in pixels
+- `margin`: Custom margin in pixels
+
+#### Positioning
+- `centered`: Center content horizontally and vertically
+- `sticky`: Fixed position at top with blur backdrop
+- `fixed`: Fixed position
+- `relative`: Relative positioning
+- `absolute`: Absolute positioning
+
+#### Display and Flex
+- `horizontal`: Horizontal flex layout with 1.5rem gap
+- `vertical`: Vertical flex layout with 1.5rem gap
+- `grid`: Grid layout with auto-fit columns
+- `responsive`: Enable responsive wrapping
+- `hidden`: Hide element
+- `visible`: Show element
+
+### Typography Properties
+
+#### Text Size
+- `huge`: Very large text (clamp(2.5rem, 5vw, 4rem))
+- `large`: Large text (clamp(1.5rem, 3vw, 2rem))
+- `small`: Small text (0.875rem)
+- `tiny`: Very small text (0.75rem)
+
+#### Text Weight
+- `bold`: Bold weight (600)
+- `light`: Light weight
+- `normal`: Normal weight
+
+#### Text Style
+- `italic`: Italic text
+- `underline`: Underlined text
+- `strike`: Strikethrough text
+- `uppercase`: All uppercase
+- `lowercase`: All lowercase
+- `capitalize`: Capitalize first letter
+
+#### Text Color
+- `subtle`: Muted text color (#8b949e)
+- `accent`: Accent color text (#3b82f6)
+- `error`: Error color text
+- `success`: Success color text
+- `warning`: Warning color text
+- Custom colors using `color:value`
+
+### Component Styles
+
+#### Button Styles
+- `prominent`: Primary button style
+  - Background: #3b82f6
+  - Hover: Scale up and glow
+- `secondary`: Secondary button style
+  - Background: #1f2937
+  - Hover: Slight raise
+- `light`: Light button style
+  - Background: Transparent
+  - Border: 1px solid rgba(48, 54, 61, 0.6)
+- `compact`: Compact button style
+  - Padding: 0.75rem
+  - Border-radius: 12px
+
+#### Card Styles
+- `raised`: Card with hover effect
+  - Background: #111827
+  - Border: 1px solid rgba(48, 54, 61, 0.6)
+  - Hover: Raise and glow
+- `interactive`: Interactive card style
+  - Hover: Scale and border color change
+
+#### Input Styles
+- `input`: Standard input style
+  - Background: #111827
+  - Border: 1px solid rgba(48, 54, 61, 0.6)
+  - Focus: Blue glow
+- `textarea`: Textarea style
+  - Min-height: 120px
+  - Resize: vertical
+- `select`: Select input style
+  - Custom dropdown arrow
+  - Focus: Blue glow
+- `checkbox`: Checkbox style
+  - Custom checkmark
+  - Hover: Blue border
+- `radio`: Radio button style
+  - Custom radio dot
+  - Hover: Blue border
+- `switch`: Toggle switch style
+  - Animated toggle
+  - Checked: Blue background
+
+### Interactive States
+
+#### Hover Effects
+```blueprint
+button(hover-scale) { "Scale on Hover" }
+link(hover-underline) { "Underline on Hover" }
+card(hover-raise) { "Raise on Hover" }
+```
+
+Available hover properties:
+- `hover-scale`: Scale up on hover (1.1)
+- `hover-raise`: Raise with shadow
+- `hover-glow`: Glow effect
+- `hover-underline`: Underline on hover
+- `hover-fade`: Fade effect
+
+#### Focus States
+```blueprint
+input(focus-glow) { }
+button(focus-outline) { "Click me" }
+```
+
+Available focus properties:
+- `focus-glow`: Blue glow effect
+- `focus-outline`: Blue outline
+- `focus-scale`: Scale effect
+
+#### Active States
+```blueprint
+button(active-scale) { "Click me" }
+link(active-color) { "Click me" }
+```
+
+Available active properties:
+- `active-scale`: Scale down
+- `active-color`: Color change
+- `active-raise`: Raise effect
+
+### Responsive Design
+
+#### Breakpoints
+Blueprint automatically handles responsive design, but you can use specific properties:
+
+```blueprint
+section(mobile-stack) {
+    horizontal(tablet-wrap) {
+        card(desktop-wide) { }
+        card(desktop-wide) { }
+    }
+}
+```
+
+Available responsive properties:
+- `mobile-stack`: Stack elements on mobile
+- `mobile-hide`: Hide on mobile
+- `tablet-wrap`: Wrap on tablet
+- `tablet-hide`: Hide on tablet
+- `desktop-wide`: Full width on desktop
+- `desktop-hide`: Hide on desktop
+
+#### Grid System
+The grid system automatically adjusts based on screen size:
+
+```blueprint
+grid(columns:3, responsive) {
+    card { }
+    card { }
+    card { }
+}
+```
+
+### Custom Properties
+
+#### Direct Style Properties
+You can use these properties directly:
+- `width`: Set width in percentage (e.g., width:80)
+- `height`: Set height in percentage (e.g., height:50)
+- `padding`: Set padding in pixels (e.g., padding:20)
+- `margin`: Set margin in pixels (e.g., margin:10)
+- `color`: Set text color (e.g., color:#ffffff)
+- `backgroundColor`: Set background color (e.g., backgroundColor:#000000)
+
+### Theme Variables
+
+Blueprint uses CSS variables for consistent theming:
+
+```css
+:root {
+    --navbar-height: 4rem;
+    --primary-color: #3b82f6;
+    --secondary-color: #1f2937;
+    --text-color: #e6edf3;
+    --subtle-color: #8b949e;
+    --border-color: rgba(48, 54, 61, 0.6);
+    --background-color: #0d1117;
+    --hover-color: rgba(255, 255, 255, 0.1);
+}
+```
+
+### Best Practices
+
+1. **Consistency**
+   - Use predefined properties when possible
+   - Maintain consistent spacing
+   - Follow the color theme
+   - Use semantic styles
+
+2. **Responsive Design**
+   - Test at all breakpoints
+   - Use relative units
+   - Consider mobile-first
+   - Use grid and flex layouts
+
+3. **Performance**
+   - Minimize custom styles
+   - Use system properties
+   - Avoid deep nesting
+   - Optimize animations
+
+4. **Accessibility**
+   - Maintain color contrast
+   - Use semantic markup
+   - Consider focus states
+   - Test with screen readers
+``` 
+</rewritten_file>