Styling Architecture

Learn about the CSS architecture, global styles, and CSS variables that power Chapinismos

Overview

Chapinismos uses a modern CSS architecture built on Tailwind CSS v4 with CSS variables for theme customization. The styling system supports dark/light modes and provides consistent design tokens across the entire application.

CSS Architecture

The project follows a layered CSS approach:

1. Global styles - Base styles and CSS variables (src/styles/global.css)
2. Tailwind utilities - Utility-first classes via Tailwind v4
3. Custom utilities - Project-specific utility classes
4. Component styles - Scoped Astro component styles

File Structure

src/styles/
└── global.css          # Global styles, CSS variables, theme definitions

CSS Variables

Chapinismos uses CSS variables extensively for theming. Variables are defined at two levels:

Tailwind Theme Variables

Defined in the @theme block for use with Tailwind utilities:

src/styles/global.css

@theme {
  /* Primary brand color - vibrant blue */
  --color-primary: #60a5fa;
  --color-primary-light: #5fa8dc;
  --color-primary-dark: #3885bd;

  /* Dark mode colors */
  --color-bg-dark: #0a0e13;
  --color-bg-accent-dark: #0f1419;
  --color-card-dark: #16202a;
  --color-text-dark: #e8f2ff;
  --color-border-dark: #1e2937;

  /* Light mode colors */
  --color-bg-light: #f8fafc;
  --color-bg-accent-light: #eff6fc;
  --color-card-light: #ffffff;
  --color-text-light: #0f172a;
  --color-border-light: #e2e8f0;

  /* Typography */
  --font-sans: "Baloo 2 Variable", sans-serif;
  --font-title: "Alice", "Baloo 2 Variable", sans-serif;
}

Runtime CSS Variables

Theme-aware variables that change based on light/dark mode:

src/styles/global.css

:root {
  /* Colors - Default dark mode */
  --bg: #0a0e13;
  --bg-accent: #0f1419;
  --card: #16202a;
  --card-hover: #1c2832;
  --text: #e8f2ff;
  --text-secondary: #d1e3f5;
  --muted: #a0b8d1;
  --border: #1e2937;

  /* Primary colors */
  --primary: #4997d0;
  --primary-light: #5fa8dc;
  --primary-dark: #3885bd;

  /* Shadows & effects */
  --shadow-sm: rgba(0, 0, 0, 0.1);
  --shadow-md: rgba(0, 0, 0, 0.15);
  --shadow-lg: rgba(0, 0, 0, 0.2);
  --glow-primary: rgba(73, 151, 208, 0.08);

  /* Button colors */
  --btn-primary-bg: #1f5e9c;
  --btn-primary-bg-hover: #2973c1;
  --btn-primary-text: #ffffff;
  --btn-primary-shadow: rgba(31, 94, 156, 0.35);

  /* Links */
  --link-primary: #60a5fa;

  /* Border radius */
  --radius-sm: 8px;
  --radius-md: 12px;
  --radius-lg: 16px;
  --radius-xl: 20px;
  --radius-full: 9999px;
}

html[data-theme="light"] {
  /* Override colors for light mode */
  --bg: #f8fafc;
  --bg-accent: #eff6fc;
  --card: #ffffff;
  --text: #0f172a;
  --link-primary: #1f5e9c;
  /* ... */
}

Typography

The project uses two custom fonts loaded via @fontsource:

Font Configuration

src/styles/global.css

@import "@fontsource-variable/baloo-2/wght.css";
@import "@fontsource/alice/400.css";

/* Optimize with font-display: swap */
@font-face {
  font-family: "Baloo 2 Variable";
  font-display: swap;
}

@font-face {
  font-family: "Alice";
  font-display: swap;
}

Font Usage

• Sans serif (body): Baloo 2 Variable - Friendly, rounded, variable font
• Serif (titles): Alice - Classic serif for headings (<h1>)

Customizing Colors

Change Primary Brand Color

Edit src/styles/global.css:

src/styles/global.css

@theme {
  /* Change from blue to purple */
  --color-primary: #a78bfa;          /* was #60a5fa */
  --color-primary-light: #c4b5fd;    /* was #5fa8dc */
  --color-primary-dark: #7c3aed;     /* was #3885bd */
}

:root {
  --primary: #8b5cf6;                /* was #4997d0 */
  --primary-light: #a78bfa;          /* was #5fa8dc */
  --primary-dark: #7c3aed;           /* was #3885bd */
  --link-primary: #a78bfa;           /* was #60a5fa */
}

html[data-theme="light"] {
  --link-primary: #7c3aed;           /* was #1f5e9c */
}

Before:

--color-primary: #60a5fa;  /* Blue */

After:

--color-primary: #a78bfa;  /* Purple */

Customize Dark Mode Colors

src/styles/global.css

:root {
  /* Darker, higher contrast background */
  --bg: #000000;              /* was #0a0e13 */
  --bg-accent: #0a0a0a;       /* was #0f1419 */
  --card: #1a1a1a;            /* was #16202a */
  --text: #ffffff;            /* was #e8f2ff */
}

Customize Light Mode Colors

src/styles/global.css

html[data-theme="light"] {
  /* Warmer light theme */
  --bg: #fef9f3;              /* was #f8fafc */
  --card: #fffbf5;            /* was #ffffff */
  --text: #1f1f1f;            /* was #0f172a */
  --border: #e7dfd4;          /* was #e2e8f0 */
}

Customizing Fonts

Change to Different Fonts

1. Install new fonts:

npm install @fontsource-variable/inter @fontsource/merriweather

2. Update global.css:

src/styles/global.css

/* Replace existing imports */
@import "@fontsource-variable/inter/wght.css";
@import "@fontsource/merriweather/400.css";
@import "@fontsource/merriweather/700.css";

@theme {
  --font-sans: "Inter Variable", sans-serif;
  --font-title: "Merriweather", serif;
}

3. Update font-display optimization:

src/styles/global.css

@font-face {
  font-family: "Inter Variable";
  font-display: swap;
}

@font-face {
  font-family: "Merriweather";
  font-display: swap;
}

Adjust Font Sizes

Font sizes use Tailwind’s default scale, but you can customize in components:

<!-- Before: Default Tailwind sizes -->
<h1 class="text-4xl">Title</h1>
<p class="text-base">Body text</p>

<!-- After: Custom sizes -->
<h1 class="text-6xl">Larger title</h1>
<p class="text-lg">Larger body text</p>

Global Background

The background uses a radial gradient with a decorative image overlay:

src/styles/global.css

body {
  background: radial-gradient(
    ellipse 100% 70% at 50% 0%,
    var(--bg-accent) 0%,
    var(--bg) 50%,
    var(--bg) 100%
  );
}

/* Decorative background image */
body::before {
  content: "";
  position: absolute;
  background: url("/images/bg.webp") center top / 100% auto repeat-y;
  opacity: 0.04;  /* Very subtle in dark mode */
}

html[data-theme="light"] body::before {
  opacity: 0.05;  /* Slightly more visible in light mode */
}

Customize Background

src/styles/global.css

/* Solid color instead of gradient */
body {
  background: var(--bg);
}

/* Different gradient */
body {
  background: linear-gradient(
    180deg,
    var(--bg-accent) 0%,
    var(--bg) 100%
  );
}

/* Remove background image */
body::before {
  display: none;
}

View Transitions

The site uses CSS View Transitions for smooth page navigation:

src/styles/global.css

@view-transition {
  navigation: auto;
}

/* Fade transition */
::view-transition-old(root),
::view-transition-new(root) {
  animation-duration: 0.3s;
}

/* Slide transition for content */
::view-transition-old(slide) {
  animation-name: slide-out;
}

::view-transition-new(slide) {
  animation-name: slide-in;
}

Customize Transition Speed

src/styles/global.css

::view-transition-old(root),
::view-transition-new(root) {
  animation-duration: 0.5s;  /* Slower transition (was 0.3s) */
}

Next Steps

Tailwind Configuration

Learn about custom Tailwind utilities and configuration

Design System

Explore the complete design token system