Developer Documentation

Framework & Styling Guide

Professional documentation for Astro 5+, TailwindCSS 4+, and DaisyUI 5+. Showcasing the latest features and implementation patterns with modern web development best practices.

Astro 5+
TailwindCSS 4+
DaisyUI 5+

Styleguide

NEW

Design System & Standards

UltimateAstroTemplate Styleguide

Table of Contents

  1. Introduction
  2. Core Principles
  3. Technology Stack
  4. Theme System
  5. Component Guidelines
  6. Layout System
  7. Typography
  8. CSS Best Practices
  9. Responsive Design
  10. Accessibility
  11. References

Introduction

This styleguide serves as the canonical reference for all styling, layout, and typography decisions in the UltimateAstroTemplate project. It outlines the technical standards, best practices, and implementation guidelines that should be followed when modifying or extending the project’s UI components.

Core Principles

KISS (Keep It Simple, Stupid)

  • Prefer simple solutions over complex ones
  • Use built-in daisyUI components instead of creating custom ones
  • Minimize dependencies and custom code

DRY (Don’t Repeat Yourself)

  • Avoid duplicating functionality that already exists in daisyUI
  • Create reusable components only when necessary
  • Leverage Astro’s component system for code organization

Consistency

  • Maintain consistent styling across all pages
  • Use the theme system for all colors and styling
  • Follow established patterns for new components

Technology Stack

The UltimateAstroTemplate uses the following technologies for styling:

  1. Tailwind CSS - Utility-first CSS framework
  2. daisyUI - Component library built on top of Tailwind CSS
  3. Astro - Frontend framework with component-based architecture

Theme System

daisyUI Themes

The project uses daisyUI’s theming system to manage colors and styling. Themes are defined in the global CSS file and can be switched using the data-theme attribute.

/* Example from src/styles/global.css */
@plugin "daisyui/theme" {
  name: "light";
  default: true;
  prefersdark: false;
  color-scheme: "light";
  --color-base-100: oklch(100% 0 0);
  --color-base-200: oklch(98% 0 0);
  --color-base-300: oklch(95% 0 0);
  /* ... other color variables ... */
}

Theme Variables

Always use daisyUI’s theme variables instead of hardcoding colors:

✅ DO:

<div class="bg-primary text-primary-content">
  Themed content
</div>

❌ DON’T:

<div style="background-color: #3b82f6; color: white;">
  Hardcoded colors
</div>

Applying Themes

Themes can be applied globally or to specific sections:

<!-- Apply theme to entire page -->
<html data-theme="dark">
  <!-- page content -->
</html>


<!-- Apply theme to specific section -->
<div data-theme="light">
  <!-- this section will use light theme -->
</div>

Component Guidelines

Using daisyUI Components

Always use native daisyUI components instead of creating custom ones. The project strictly prohibits duplicating functionality that already exists in daisyUI.

✅ DO:

<div class="card bg-base-100 shadow-xl">
  <div class="card-body">
    <h2 class="card-title">Card title</h2>
    <p>Card content</p>
  </div>
</div>

❌ DON’T:

<div class="custom-card">
  <div class="custom-card-body">
    <h2 class="custom-card-title">Card title</h2>
    <p>Card content</p>
  </div>
</div>

Component Modification

When modifying components, follow these guidelines:

  1. Use Tailwind utility classes for adjustments
  2. Use daisyUI’s modifier classes when available
  3. Avoid inline styles completely
  4. Avoid custom CSS classes unless absolutely necessary

Layout System

Container System

Use Tailwind’s container system for layout:

<div class="container mx-auto px-4">
  <!-- Content here -->
</div>

For responsive containers, use the utility class defined in global.css:

<div class="container-responsive">
  <!-- Content here will have responsive padding -->
</div>

Grid System

Use Tailwind’s grid system for complex layouts:

<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  <div>Column 1</div>
  <div>Column 2</div>
  <div>Column 3</div>
</div>

Spacing

Use Tailwind’s spacing utilities consistently:

<div class="p-4 my-6 space-y-4">
  <!-- Content with consistent spacing -->
</div>

Typography

Font System

The project uses the following font stack:

font-family: 'Inter', system-ui, -apple-system, sans-serif;

For headings and special text, we use Cal Sans:

.font-cal {
  font-family: 'Cal Sans', 'Inter', system-ui, -apple-system, sans-serif;
}

Text Styling

Use Tailwind’s typography utilities for text styling:

<h1 class="text-3xl font-bold text-primary font-cal">Heading</h1>
<p class="text-base text-base-content/80">
  Paragraph with slightly reduced opacity
</p>

Markdown Content

For markdown content, use the .markdown-content class which applies the Tailwind Typography plugin styles:

<article class="markdown-content">
  <!-- Markdown content here -->
</article>

CSS Best Practices

Global CSS

All global styles are defined in src/styles/global.css. This file includes:

  1. Tailwind directives
  2. daisyUI theme configurations
  3. Base styles
  4. Component styles
  5. Utility classes

CSS Organization

CSS is organized using Tailwind’s layer system:

@layer base {
  /* Base styles */
}


@layer components {
  /* Component styles */
}


@layer utilities {
  /* Utility styles */
}

Avoiding Inline Styles

Inline styles are strictly prohibited. Always use Tailwind utility classes or daisyUI components.

✅ DO:

<div class="bg-base-200 p-4 rounded-lg">
  <!-- Content -->
</div>

❌ DON’T:

<div style="background-color: #f3f4f6; padding: 1rem; border-radius: 0.5rem;">
  <!-- Content -->
</div>

Responsive Design

Breakpoints

Follow Tailwind’s responsive breakpoint system:

  • sm: 640px and up
  • md: 768px and up
  • lg: 1024px and up
  • xl: 1280px and up
  • 2xl: 1536px and up

Example:

<div class="text-sm md:text-base lg:text-lg">
  Responsive text size
</div>

Mobile-First Approach

Always design with a mobile-first approach:

<div class="flex flex-col md:flex-row">
  <!-- Stacked on mobile, side-by-side on md screens and up -->
</div>

Accessibility

Color Contrast

Ensure all text has sufficient contrast with its background. Use daisyUI’s content colors which are designed to maintain proper contrast:

<div class="bg-primary">
  <p class="text-primary-content">
    This text will always have good contrast with the primary background
  </p>
</div>

Semantic HTML

Use semantic HTML elements whenever possible:

<article>
  <header>
    <h1>Article Title</h1>
  </header>
  <section>
    <h2>Section Heading</h2>
    <p>Content</p>
  </section>
  <footer>
    <p>Article footer</p>
  </footer>
</article>

References

AstroJS

v4.0

Modern Static Site Generator

Supercharge Your Website with Astro.js

In today’s competitive digital landscape, a slow and clunky website can mean lost customers and revenue. That’s where Astro.js comes in. Astro is a revolutionary web framework designed to build content-rich websites that are incredibly fast, SEO-friendly, and a joy for users to interact with.

Key Features & Benefits for Your Business:

  • Unmatched Performance: Astro’s “server-first” approach means your website loads at lightning speed. By rendering content on the server and sending minimal JavaScript to the browser, Astro sites can be up to 40% faster than those built with other popular frameworks. This translates to a better user experience, higher engagement, and improved conversion rates.

  • The “Islands” Advantage: Astro’s unique “Islands Architecture” allows for interactive components to be loaded independently on a page that is otherwise static. This means you get the best of both worlds: the performance of a static site with the rich interactivity of a dynamic application, without the bloat.

  • Dominate Search Rankings: Astro is built for SEO. It generates static HTML files that are easily crawled and indexed by search engines, giving you a significant advantage in search visibility.

  • Flexibility for the Future: Astro is framework-agnostic, meaning it can be used with your favorite UI libraries like React, Vue, and Svelte. This flexibility ensures that your website is not locked into a single technology and can easily adapt to future trends.

  • Perfect for Content-Driven Sites: Whether you have a blog, a marketing website, or an e-commerce platform, Astro is the ideal choice. It’s designed to deliver content to your users as quickly as possible and integrates seamlessly with headless CMS platforms for easy content management.

In short, Astro.js offers a powerful combination of speed, SEO, and flexibility that can give your business a serious competitive edge. If you’re looking to build a high-performing website that delivers a world-class user experience, Astro is the answer.

Tailwind CSS

v4.0

Utility-First CSS Framework

TailwindCSS 4+ with Astro 5+: Modern Setup Guide

TailwindCSS 4+ introduces a new architecture with improved performance and a CSS-first configuration approach. This guide shows you how to properly integrate TailwindCSS 4+ with Astro 5+ using the new @tailwindcss/vite plugin.

Quick Setup

1. Install TailwindCSS 4+ and Vite Plugin

Terminal window
# Install TailwindCSS 4+ and the official Vite plugin
npm install tailwindcss @tailwindcss/vite

Documentation Reference: TailwindCSS Installation Guide for Astro

2. Configure Astro with TailwindCSS Vite Plugin

Update your astro.config.mjs to use the new Vite plugin:

astro.config.mjs
// @ts-check
import { defineConfig } from "astro/config";
import tailwindcss from "@tailwindcss/vite";


// https://astro.build/config
export default defineConfig({
  vite: {
    plugins: [tailwindcss()],
  },
});

Documentation Reference: Astro Styling Guide

3. Create Global CSS File

Create src/styles/global.css and import TailwindCSS:

src/styles/global.css
@import "tailwindcss";

4. Import CSS in Your Layout

Import the global stylesheet in your main layout:

src/layouts/Layout.astro
---
import "../styles/global.css";
---

Key Differences from TailwindCSS 3.x

Configuration Changes

TailwindCSS 4+ introduces significant changes:

  • No more tailwind.config.js: TailwindCSS 4+ uses CSS-based configuration instead of JavaScript config files
  • Vite Plugin: Use @tailwindcss/vite instead of @astrojs/tailwind integration
  • CSS-First: Configuration is done directly in CSS files using @theme directive

Documentation Reference: https://tailwindcss.com/docs/upgrade-guide

Legacy Configuration Support

If you need to use a legacy JavaScript config file, use the @config directive:

/* Load legacy config if needed */
@config "../../tailwind.config.js";
@import "tailwindcss";

Advanced Configuration

Custom Theme Configuration

Use the @theme directive in your CSS for custom configurations:

@import "tailwindcss";


@theme {
  --color-primary: oklch(55% 0.3 240);
  --color-secondary: oklch(70% 0.25 200);
  --breakpoint-3xl: 120rem;
  --font-sans: 'Inter', 'sans-serif';
}

Documentation Reference: https://tailwindcss.com/docs/theme

Custom Utilities

Define custom utilities using @utility:

@import "tailwindcss";


@utility container {
  margin-inline: auto;
  padding-inline: 2rem;
}

Performance Benefits

  • Faster builds: New Vite plugin provides better performance
  • Smaller bundles: Improved tree-shaking and optimization
  • Better DX: Enhanced development experience with faster HMR

Migration from TailwindCSS 3.x

If upgrading from TailwindCSS 3.x:

  1. Remove old integration:

    Terminal window
    npm uninstall @astrojs/tailwind

  2. Remove from astro.config.mjs:

    // Remove this line
    integrations: [tailwind()],

  3. Install new setup:

    Terminal window
    npm install tailwindcss @tailwindcss/vite

  4. Update configuration:

    • Move theme customizations from tailwind.config.js to CSS using @theme
    • Replace JavaScript config with CSS-based configuration

Troubleshooting

Common Issues

  • Build errors: Ensure you’re using @tailwindcss/vite plugin, not the old integration
  • Styles not loading: Check that global CSS is imported in your layout
  • Config not working: Use @config directive for legacy JavaScript configs

Best Practices

  • Keep CSS configuration in your main stylesheet
  • Use the new @theme directive for custom values
  • Leverage the Vite plugin for optimal performance

Documentation References:

DaisyUI

v5.0

Component Library for Tailwind CSS

DaisyUI 5+ with TailwindCSS 4+ Setup Guide

DaisyUI 5+ is designed specifically for TailwindCSS 4+ and introduces a new CSS-based plugin system. This guide shows you how to properly integrate DaisyUI 5+ with TailwindCSS 4+ in Astro 5+.

Documentation Reference: https://daisyui.com/docs/install/

Requirements

  • TailwindCSS 4+: DaisyUI 5 requires TailwindCSS 4
  • No tailwind.config.js: TailwindCSS v4 only needs @import "tailwindcss"; in the CSS file
  • CSS Plugin System: DaisyUI 5 uses @plugin "daisyui"; in CSS instead of JavaScript config

Quick Setup

1. Install DaisyUI 5+

Terminal window
# Install DaisyUI 5+ as a development dependency
npm install -D daisyui@latest

Documentation Reference: DaisyUI Installation Guide

2. Add DaisyUI Plugin to CSS

Update your src/styles/global.css to include DaisyUI:

src/styles/global.css
@import "tailwindcss";
@plugin "daisyui";

Documentation Reference: DaisyUI CSS Integration

3. Basic Configuration

For basic usage with default settings:

/* Basic DaisyUI setup with default themes */
@import "tailwindcss";
@plugin "daisyui";

Advanced Configuration

Custom Theme Configuration

Configure DaisyUI with specific themes and settings:

@import "tailwindcss";
@plugin "daisyui" {
  themes: light --default, dark --prefersdark;
  root: ":root";
  include: ;
  exclude: ;
  prefix: ;
  logs: true;
}

Multiple Themes Setup

Enable multiple built-in themes:

@import "tailwindcss";
@plugin "daisyui" {
  themes: light, dark, cupcake, bumblebee --default, emerald, corporate,
          synthwave --prefersdark, retro, cyberpunk, valentine, halloween,
          garden, forest, aqua, lofi, pastel, fantasy, wireframe, black,
          luxury, dracula, cmyk, autumn, business, acid, lemonade, night,
          coffee, winter, dim, nord, sunset;
  root: ":root";
  prefix: daisy-;
  logs: false;
}

Documentation Reference: DaisyUI Themes Configuration

Theme Switching

Method 1: Theme Controller Component

Use DaisyUI’s theme controller for automatic theme switching:

<!-- Theme selector checkbox -->
<input type="checkbox" value="dark" class="theme-controller" />


<!-- Theme selector radio buttons -->
<input type="radio" name="theme" value="light" class="theme-controller" />
<input type="radio" name="theme" value="dark" class="theme-controller" />

Method 2: Data Attribute

Set theme directly on HTML element:

<html data-theme="dark">
<!-- Your content -->
</html>

Documentation Reference: DaisyUI Theme Controller

Component Usage

Basic Components

<!-- Button variants -->
<button class="btn">Default</button>
<button class="btn btn-primary">Primary</button>
<button class="btn btn-secondary">Secondary</button>
<button class="btn btn-accent">Accent</button>


<!-- Card component -->
<div class="card w-96 bg-base-100 shadow-xl">
  <figure><img src="image.jpg" alt="Example" /></figure>
  <div class="card-body">
    <h2 class="card-title">Card Title</h2>
    <p>Card description content.</p>
    <div class="card-actions justify-end">
      <button class="btn btn-primary">Action</button>
    </div>
  </div>
</div>


<!-- Alert component -->
<div role="alert" class="alert alert-success">
  <span>Your purchase has been confirmed!</span>
</div>

Form Components

<!-- Input field -->
<input type="text" placeholder="Type here" class="input input-bordered w-full max-w-xs" />


<!-- Select dropdown -->
<select class="select select-bordered w-full max-w-xs">
  <option disabled selected>Pick one</option>
  <option>Option 1</option>
  <option>Option 2</option>
</select>


<!-- Checkbox -->
<input type="checkbox" class="checkbox checkbox-primary" />


<!-- Toggle -->
<input type="checkbox" class="toggle toggle-primary" />

Color System

DaisyUI Semantic Colors

DaisyUI provides semantic color names that automatically adapt to themes:

  • primary - Primary brand color
  • secondary - Secondary brand color
  • accent - Accent color
  • neutral - Neutral color
  • base-100, base-200, base-300 - Base surface colors
  • info, success, warning, error - Status colors

Usage Examples

<!-- Using semantic colors -->
<div class="bg-primary text-primary-content p-4">Primary section</div>
<div class="bg-base-200 text-base-content p-4">Base section</div>
<button class="btn btn-success">Success button</button>

Documentation Reference: DaisyUI Colors

Custom Themes

Creating Custom Themes

@import "tailwindcss";
@plugin "daisyui";
@plugin "daisyui/theme" {
  name: "mytheme";
  default: true;
  prefersdark: false;
  color-scheme: light;


  --color-base-100: oklch(98% 0.02 240);
  --color-base-200: oklch(95% 0.03 240);
  --color-base-300: oklch(92% 0.04 240);
  --color-base-content: oklch(20% 0.05 240);
  --color-primary: oklch(55% 0.3 240);
  --color-primary-content: oklch(98% 0.01 240);
  --color-secondary: oklch(70% 0.25 200);
  --color-secondary-content: oklch(98% 0.01 200);


  --radius-selector: 1rem;
  --radius-field: 0.25rem;
  --radius-box: 0.5rem;
  --size-selector: 0.25rem;
  --size-field: 0.25rem;
  --border: 1px;
  --depth: 1;
  --noise: 0;
}

Documentation Reference: DaisyUI Theme Generator

CDN Alternative

If you prefer using CDN instead of npm:

<link href="https://cdn.jsdelivr.net/npm/daisyui@5" rel="stylesheet" type="text/css" />
<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>

Best Practices

Component Naming Convention

DaisyUI 5 uses semantic class naming:

  • component: Main component class (e.g., btn, card)
  • part: Child parts of components (e.g., card-body, card-title)
  • style: Style variations (e.g., btn-outline, alert-soft)
  • color: Color variants (e.g., btn-primary, badge-success)
  • size: Size variants (e.g., btn-lg, input-sm)
  • modifier: Behavioral modifiers (e.g., btn-active, collapse-open)

Customization with Tailwind

<!-- Extend DaisyUI components with Tailwind utilities -->
<button class="btn btn-primary px-8 py-4">Extended Button</button>


<!-- Force override with ! if needed (use sparingly) -->
<button class="btn bg-red-500!">Force Red Background</button>

Troubleshooting

Common Issues

  • Styles not applying: Ensure you’re using @plugin "daisyui"; not @tailwindcss/plugin
  • Themes not working: Check that data-theme attribute is set correctly
  • Build errors: Ensure you’re using TailwindCSS 4+ with DaisyUI 5+

Migration from DaisyUI 4.x

  1. Update to TailwindCSS 4+: Remove tailwind.config.js
  2. Update CSS imports: Replace JavaScript config with CSS @plugin
  3. Check theme names: Some theme names may have changed
  4. Update component usage: Review component class names for changes

Documentation References:

Sections

Styleguide

Design System & Standards

Astro 5+

Modern Static Site Generator

TailwindCSS 4+

Utility-First CSS Framework

DaisyUI 5+

Tailwind Component Library

AstroJS Demo

🚀

AstroJS Integration

The web framework that scales with you. Astro combines the power of a modern component-based architecture with the performance of static HTML generation.

Documentation

Key Features

🏝️

Islands Architecture

Ship less JavaScript with Astro's component islands. Load UI components only when needed and improve performance with automatic partial hydration.

⚡

Server-First API Design

Move expensive hydration off the main thread for faster page loads. Then enhance with client-side JavaScript as needed.

🚫

Zero JS By Default

Astro renders HTML on the server and strips away any unused JavaScript automatically, making every page fast by default.

🌐

Edge-Ready Deployments

Deploy anywhere with adapter-based deployments, including Netlify, Vercel, Cloudflare, and more.

🧩

UI-Agnostic

Bring your own UI framework - React, Preact, Svelte, Vue, Solid, Lit and more.

Astro Component Example

---
// src/components/Example.astro
import { getCollection } from 'astro:content';
import Layout from '../layouts/Layout.astro';

// Type definitions for blog posts
interface Post {
  data: {
    title: string;
    description: string;
  };
  slug: string;
}

// Fetch posts at build time with type annotation
const posts = (await getCollection('blog')) as unknown as Post[];
---

<Layout title="Welcome to Astro">
  <main>
    <h1>Welcome to Astro</h1>
    <div class="grid">
      {posts.map((post: Post) => (
        <article class="card">
          <h2>{post.data.title}</h2>
          <p>{post.data.description}</p>
          <a href={"/blog/" + post.slug}>Read more</a>
        </article>
      ))}
    </div>
  </main>
</Layout>

Framework Integrations

React
Vue
Svelte
Solid
Preact
Alpine
Lit
Qwik

Tailwind CSS Demo

🎨

Tailwind CSS Integration

A utility-first CSS framework packed with classes that can be composed to build any design, directly in your markup.

Documentation

Key Features

🚀

Rapid Development

Build modern websites without leaving your HTML. Tailwind's utility classes help you work within the constraints of a system instead of littering your stylesheets with arbitrary values.

🎨

A Design That's Uniquely Yours

Unlike other frameworks that dictate how your site looks, Tailwind provides low-level utility classes that let you build completely custom designs without ever leaving your HTML.

✨

Pixel-Perfect Consistency

Every utility class in Tailwind is part of a carefully crafted design system, ensuring your projects maintain consistent spacing, sizing, colors, and more.

⚡

Optimized for Performance and SEO

Tailwind automatically removes all unused CSS when building for production, which means your final CSS bundle is the smallest it could possibly be.

🧩

Effortless Maintenance and Scalability

Tailwind's utility-first approach promotes reusability and consistency, making it easier to maintain and scale your projects as they grow.

Try Tailwind CSS

Example Code

<!-- Example using Tailwind CSS -->
<button class="btn btn-primary">
  <svg class="w-5 h-5 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" 
      d="M13 10V3L4 14h7v7l9-11h-7z" />
  </svg>
  Click me
</button>

Preview

Utility Examples

Spacing Utilities

p-2
p-4
p-6
px-4 py-2
m-2
mx-auto

Paragraph text with bold and italic styles.

Flex & Grid

flex-1
flex-1
1
2
3

DaisyUI Demo

🎨

DaisyUI Integration

The most popular component library for Tailwind CSS. DaisyUI adds component classes to Tailwind CSS so you can build websites faster with less classes.

Component Showcase

Buttons

Alerts

This is an info alert
This is a success alert