VES - Visual Element Styling Language

⚠️ WARNING: EXPERIMENTAL - DO NOT USE IN PRODUCTION
This package is in early development and contains bugs. It is not ready for use by anyone. Use at your own risk. Breaking changes will occur frequently without notice.

A modern styling language that compiles to CSS, designed for the era of AI-assisted development and modern design systems.

Why VES?

• 🤖 AI-Friendly: Designed for LLMs - semantic syntax with built-in design guidelines

  • Clear constraints (@spacing(), @contrast()) guide AI to generate good code
  • Semantic tokens (@primary not #3B82F6) help LLMs understand intent
  • Built-in validation prevents common mistakes
  • See LLM Guide and System Prompt

• 🎨 Design-First: Built-in design tokens, golden ratios, and spacing systems

  • Golden ratio & Fibonacci spacing scales
  • Type scales based on modular scale theory
  • Color functions with WCAG compliance

• ♿ Accessible by Default: Accessibility features built into the language

  • @accessible directive for touch targets
  • @contrast() ensures readable text
  • @reduced-motion respects user preferences

• 📦 Package Ecosystem: Import and share design components

  • Coming: Package registry for sharing components

• ⚛️ Framework Ready: Seamless integration with React

  • Import .ves files like CSS Modules
  • Webpack & Vite loaders included

Features

🎨 Modern Design Patterns

• Golden ratio and Fibonacci spacing scales
• Type scales based on modular scale theory
• Responsive design tokens
• Color palette generation with accessibility checks

♿ Accessibility First

• Automatic WCAG contrast checking
• Focus state management
• Screen reader utilities
• Reduced motion support

📦 Package System

• Import design components from the VES registry
• Share and reuse styling patterns
• Version-controlled design tokens

🚀 Framework Integration

• React hooks and components
• Scoped styles
• Dynamic theming
• SSR support

Quick Start

Installation

npm install vestra

Option 1: React with CSS Modules (Recommended)

Import .ves files directly in your React components:

Button.ves

:root {
  @theme {
    primary: #3B82F6;
    spacing: golden-ratio;
  }
}

.button {
  padding: @spacing(2) @spacing(3);
  background: @primary;
  color: @contrast(@primary);
  border-radius: @spacing(1);
  
  @accessible {
    min-height: 44px;
  }
  
  &:hover {
    background: lighten(@primary, 10%);
  }
}

Button.tsx

import React from 'react';
import styles from './Button.ves';

export function Button({ children }) {
  return <button className={styles.button}>{children}</button>;
}

See CSS Modules Guide for setup instructions.

Option 2: Compile to CSS

# Install globally
npm install -g vestra

# Compile
ves compile styles.ves -o styles.css

Getting Started

New Project

# Create a new VES project
ves init my-project
cd my-project
npm install
npm run build

Existing Next.js/Vite Project

# Run in your project root
cd my-nextjs-app
ves init

# VES will:
# ✓ Detect your framework
# ✓ Add vestra to package.json
# ✓ Create example .ves files
# ✓ Set up config (Vite) or provide instructions (Next.js)
# ✓ Add TypeScript definitions

npm install
# Start using .ves files in your components!

Language Overview

VES combines the best of SCSS, modern CSS, and design system thinking into a coherent language.

React Integration

VES works seamlessly with React using the CSS Modules pattern:

// Button.tsx
import styles from './Button.ves';

export function Button({ children }) {
  return <button className={styles.button}>{children}</button>;
}

Benefits:

• ✅ Simple and intuitive
• ✅ TypeScript autocomplete
• ✅ Zero runtime overhead
• ✅ Works with Webpack, Vite, etc.

See CSS Modules Guide for details.

VS Code Extension

Syntax highlighting for .ves files is available!

# Install the extension manually
cp -r vscode-extension ~/.vscode/extensions/vestra-vscode
# Then restart VS Code

See vscode-extension/INSTALL.md for details.

AI/LLM Features

Automatic Cursor AI Setup

When you run ves init in your project, it automatically creates .cursorrules with VES guidelines:

cd my-nextjs-app
ves init

# Creates:
# ✓ .cursorrules (Cursor AI knows VES syntax!)
# ✓ src/styles/main.ves
# ✓ src/ves-modules.d.ts

Now Cursor AI will automatically:

• Generate VES code with @spacing() instead of px
• Use theme colors (@primary) instead of hex codes
• Add @accessible directives
• Follow design best practices
• Create accessible, responsive components

Natural Language Component Descriptions

Describe components in plain English:

Component: Hero CTA Button
Purpose: Primary call-to-action button for conversions
Style: modern, bold
Mood: confident, trustworthy
Features: large, high contrast, gradient, accessible

Then ask your AI to generate the VES code! See examples/natural-language/

LLM-Friendly Design

VES is designed to make it easy for AI to generate beautiful, consistent UIs:

// LLMs naturally follow VES constraints:
.button {
  padding: @spacing(2) @spacing(3);  // Consistent spacing ✓
  background: @primary;               // Theme colors ✓
  color: @contrast(@primary);         // Accessible contrast ✓
  
  @accessible;                        // Touch targets ✓
  
  &:hover {
    background: lighten(@primary, 10%); // Proper states ✓
  }
  
  @reduced-motion {                   // Respects preferences ✓
    transition: none;
  }
}

For LLMs: See LLM System Prompt for guidelines to generate correct VES code.

Benefits:

• ✅ LLMs can't generate inaccessible UIs (built-in constraints)
• ✅ Consistent spacing and colors (enforced by functions)
• ✅ Follows design best practices automatically
• ✅ Self-documenting semantic code

See AI Features Guide and LLM Guide for more.

Project Status

⚠️ EXPERIMENTAL / UNSTABLE / DO NOT USE

This is an early-stage experimental project with:

• ❌ Known bugs and issues
• ❌ Incomplete features
• ❌ No stability guarantees
• ❌ Breaking changes without notice
• ❌ Not suitable for any production use
• ❌ Not recommended for development use

Seriously, don't use this. It's not ready.

If you choose to experiment with it anyway (against this advice):

• Core compiler exists but has bugs
• React integration is experimental
• Package system is incomplete
• Documentation may be inaccurate

License

MIT