Getting Started

Welcome to Dragonfly UI, a modern CSS framework designed to help you build beautiful, accessible, and responsive user interfaces. This guide will walk you through the core concepts and help you get started quickly.

What is Dragonfly UI?

Dragonfly UI is a comprehensive CSS framework that provides:

🧱 UI Components: A complete set of pre-built, accessible components
📐 Layout System: Flexible grid, flexbox, and container systems
🎨 Design Tokens: Consistent design variables for colors, spacing, typography
✨ Effects: Visual effects, animations, and transitions
🌙 Theming: Multiple themes and easy customization
🔧 Utilities: Helper classes for rapid development

Key Features

Modern CSS Architecture

Dragonfly UI is built with cutting-edge CSS features:

css

/* Layer-based architecture for predictable specificity */
@layer reset, tokens, core, layout, typography,
       utilities, components, effects, themes;

/* Container queries for component-based responsiveness */
@container (min-width: 30rem) {
  .card { grid-template-columns: 1fr 1fr; }
}

/* CSS custom properties for easy theming */
:root {
  --color-primary: #e72779;
  --space-4: 1rem;
  --radius-md: 0.375rem;
}

Lightning CSS Optimized

The framework is optimized for Lightning CSS (formerly Parcel CSS), providing:

Faster build times
Better CSS optimization
Automatic vendor prefixing
Advanced CSS feature support

Accessibility First

Every component is built with accessibility in mind:

WCAG 2.1 AA compliance
Proper ARIA attributes
Keyboard navigation support
Screen reader optimization
High contrast support

Installation

Choose your preferred package manager:

npmyarnpnpm

bash

npm install @casoon/dragonfly

bash

yarn add @casoon/dragonfly

bash

pnpm add @casoon/dragonfly

Basic Usage

Import Styles

The simplest way to get started is to import the core styles:

css

/* Import the complete framework */
@import '@casoon/dragonfly/core.css';

/* Add a theme */
@import '@casoon/dragonfly/themes/day.css';

HTML Structure

Apply the theme class to your root element:

html

<!DOCTYPE html>
<html class="theme-day">
<head>
  <link rel="stylesheet" href="path/to/dragonfly/core.css">
  <title>My App</title>
</head>
<body>
  <div class="container">
    <h1>Welcome to Dragonfly UI</h1>
    <button class="button button--primary">Get Started</button>
  </div>
</body>
</html>

Framework Integration

React

jsx

// App.jsx
import '@casoon/dragonfly/core.css';
import '@casoon/dragonfly/themes/day.css';

function App() {
  return (
    <div className="theme-day">
      <div className="container">
        <h1 className="text-3xl font-bold mb-4">
          Welcome to Dragonfly UI
        </h1>
        <button className="button button--primary">
          Get Started
        </button>
      </div>
    </div>
  );
}

export default App;

Vue.js

vue

<template>
  <div class="theme-day">
    <div class="container">
      <h1 class="text-3xl font-bold mb-4">
        Welcome to Dragonfly UI
      </h1>
      <button class="button button--primary">
        Get Started
      </button>
    </div>
  </div>
</template>

<script setup>
import '@casoon/dragonfly/core.css';
import '@casoon/dragonfly/themes/day.css';
</script>

Astro

astro

---
// Layout.astro
import '@casoon/dragonfly/core.css';
import '@casoon/dragonfly/themes/day.css';
---

<html class="theme-day">
  <head>
    <title>My Astro Site</title>
  </head>
  <body>
    <div class="container">
      <h1 class="text-3xl font-bold mb-4">
        Welcome to Dragonfly UI
      </h1>
      <button class="button button--primary">
        Get Started
      </button>
    </div>
  </body>
</html>

Core Concepts

1. Design Tokens

Dragonfly UI uses CSS custom properties for consistent design:

css

:root {
  /* Colors */
  --color-primary: #e72779;
  --color-secondary: #6366f1;

  /* Spacing */
  --space-1: 0.25rem;
  --space-4: 1rem;
  --space-8: 2rem;

  /* Typography */
  --text-sm: 0.875rem;
  --text-lg: 1.125rem;

  /* Borders */
  --radius-sm: 0.25rem;
  --radius-md: 0.375rem;
}

Learn more about Design Tokens →

2. Layer System

CSS layers ensure predictable specificity:

css

@layer reset {
  /* Browser reset styles */
}

@layer tokens {
  /* Design token definitions */
}

@layer components {
  /* Component styles */
}

@layer utilities {
  /* Utility classes */
}

Explore the Layer System →

3. Responsive Design

Multiple approaches to responsive design:

css

/* Traditional media queries */
@media (min-width: 768px) {
  .card { grid-template-columns: 1fr 1fr; }
}

/* Container queries (modern approach) */
@container (min-width: 30rem) {
  .card { grid-template-columns: 1fr 1fr; }
}

Master Responsive Design →

4. Component System

Components follow BEM methodology:

html

<!-- Button component -->
<button class="button button--primary button--large">
  Primary Button
</button>

<!-- Card component -->
<div class="card card--elevated">
  <div class="card__header">
    <h3 class="card__title">Card Title</h3>
  </div>
  <div class="card__body">
    <p>Card content goes here.</p>
  </div>
  <div class="card__footer">
    <button class="button button--secondary">Action</button>
  </div>
</div>

Browse All Components →

What's Next?

Now that you understand the basics, explore these areas:

📦 Installation

Detailed installation instructions for different environments and build tools.

Setup Guide →

🎨 Themes

Learn about the theming system and how to customize colors and appearance.

Theming Guide →

🧱 Components

Explore our comprehensive library of accessible UI components.

Component Library →

📐 Layout

Master the layout system with grids, flexbox, and container queries.

Layout System →

✨ Effects

Add polish with visual effects, animations, and transitions.

Effects Library →

🔧 Utilities

Speed up development with utility classes for common styling needs.

Utility Classes →

Need Help?

📖 Documentation: Browse our comprehensive documentation
🐛 Issues: Report bugs on GitHub Issues
💬 Discussions: Join the conversation on GitHub Discussions
🤝 Contributing: Check out our contribution guidelines

Browser Support

Dragonfly UI supports all modern browsers:

Browser	Version
Chrome	88+
Firefox	89+
Safari	14+
Edge	88+

For older browsers, graceful fallbacks ensure your content remains accessible and functional.

Pro Tip

Start with the Installation Guide to set up Dragonfly UI in your project, then explore the Component Library to see what's available.

Beta Notice

Dragonfly UI is currently in beta. While the core functionality is stable, the API may change before the 1.0 release. We recommend thorough testing before using in production.

Getting Started ​

What is Dragonfly UI? ​

Key Features ​

Modern CSS Architecture ​

Lightning CSS Optimized ​

Accessibility First ​

Installation ​

Basic Usage ​

Import Styles ​

HTML Structure ​

Framework Integration ​

React ​

Vue.js ​

Astro ​

Core Concepts ​

1. Design Tokens ​

2. Layer System ​

3. Responsive Design ​

4. Component System ​

What's Next? ​

📦 Installation

🎨 Themes

🧱 Components

📐 Layout

✨ Effects

🔧 Utilities

Need Help? ​

Browser Support ​

Getting Started

What is Dragonfly UI?

Key Features

Modern CSS Architecture

Lightning CSS Optimized

Accessibility First

Installation

Basic Usage

Import Styles

HTML Structure

Framework Integration

React

Vue.js

Astro

Core Concepts

1. Design Tokens

2. Layer System

3. Responsive Design

4. Component System

What's Next?

Need Help?

Browser Support