Styling

Goal: Customize colors, fonts, and design tokens.

Learn about the powerful styling system in Astro Swiss Theme.

Styling Architecture

The theme uses a layered CSS architecture for maximum flexibility:

global.css (entry point)
├── starwind.css        ← Starwind UI component styles
├── tokens.css          ← Design tokens (colors, spacing, shadows)
├── themes/
│   ├── light.css      ← Light mode overrides
│   └── dark.css       ← Dark mode overrides
└── utilities.css       ← Custom utility classes

Note

Import order matters! This cascade ensures proper styling hierarchy from base components to custom utilities.

---

Design Tokens

File: src/styles/tokens.css

Design tokens are CSS variables that define your brand’s visual identity.

Brand Colors

src/styles/tokens.css

:root {
  /* Primary accent color */
  --accent: #fc4a1a;
  --accent-dark: #f7b733;
  --accent-rgb: 252, 74, 26;

  /* Secondary color */
  --secondary: #FFB36B;
}

Usage:

.button {
  background: var(--accent);
  color: var(--primary-foreground);
}

Neutral Colors

Defined as RGB values for flexibility with opacity:

:root {
  --black: 15, 18, 25;
  --gray: 96, 115, 159;
  --gray-light: 229, 233, 240;
  --gray-dark: 34, 41, 57;
}

Usage with opacity:

.overlay {
  background: rgba(var(--black), 0.5);  /* 50% opacity */
}

Semantic Tokens

Semantic tokens provide meaning-based naming:

src/styles/tokens.css

:root {
  /* Text colors */
  --color-text-primary: rgb(var(--black));
  --color-text-secondary: rgb(var(--gray-dark));
  --color-text-muted: rgb(var(--gray));

  /* Background colors */
  --color-bg-primary: var(--background);
  --color-bg-secondary: rgba(0, 0, 0, 0.03);
  --color-bg-tertiary: rgba(0, 0, 0, 0.05);

  /* Borders */
  --color-border: rgba(0, 0, 0, 0.12);
  --color-border-light: rgba(0, 0, 0, 0.08);
}

---

Theme System

The theme supports automatic light/dark mode switching based on user preference.

Light Theme

File: src/styles/themes/light.css

src/styles/themes/light.css

[data-theme="light"] {
  --accent: #FF7A1A;
  --background: #ffffff;
  --foreground: #0f1219;
  --card: #ffffff;
  /* ... more overrides */
}

Dark Theme

File: src/styles/themes/dark.css

src/styles/themes/dark.css

[data-theme="dark"],
.dark {
  --accent: #f7b733;
  --background: #050505;
  --foreground: rgb(243, 244, 246);
  --card: rgba(255, 255, 255, 0.04);  /* Translucent */
  /* ... more overrides */
}

Theme Initialization

The BaseLayout.astro includes an inline script to prevent FOUC (Flash of Unstyled Content):

const isDark =
  localStorage.theme === "dark" ||
  (!("theme" in localStorage) &&
    window.matchMedia("(prefers-color-scheme: dark)").matches);

document.documentElement.classList.toggle("dark", isDark);
document.documentElement.setAttribute("data-theme", isDark ? "dark" : "light");

This runs before page render to apply the correct theme immediately.

---

Customizing Colors

Note

Example Colors: The orange colors (#fc4a1a, #f7b733) shown throughout this guide are example placeholders. You should customize these to match your brand identity.

Changing Brand Colors

Edit src/styles/tokens.css:

src/styles/tokens.css

:root {
  /* Change your primary brand color */
  --accent: #3b82f6;  /* Blue instead of orange */
  --accent-rgb: 59, 130, 246;

  /* Change secondary color */
  --secondary: #8b5cf6;  /* Purple */
}

Per-Theme Color Adjustments

For different colors in light vs. dark mode:

Light Theme

src/styles/themes/light.css

[data-theme="light"] {
  --accent: #3b82f6;  /* Bright blue */
}

Dark Theme

src/styles/themes/dark.css

[data-theme="dark"] {
  --accent: #60a5fa;  /* Lighter blue for dark backgrounds */
}

Creating Color Variants

Add new color tokens:

src/styles/tokens.css

:root {
  --brand-purple: #8b5cf6;
  --brand-green: #10b981;
  --brand-pink: #ec4899;
}

Use in components:

.special-button {
  background: var(--brand-purple);
}

---

Complete Brand Color Setup

When customizing your brand colors, follow this comprehensive checklist to ensure all color references are updated consistently across your site.

Caution

Important: Brand colors may be hardcoded in multiple locations. Updating only tokens.css may not be sufficient for a complete rebrand.

Color Customization Checklist

Use this checklist to ensure you’ve updated all color references:

✅ Step 1: Update Design Tokens

File: src/styles/tokens.css

src/styles/tokens.css

:root {
  /* Update your primary brand color */
  --accent: #YOUR_BRAND_COLOR;
  --accent-rgb: R, G, B;  /* RGB values of your brand color */

  /* Update secondary color */
  --secondary: #YOUR_SECONDARY_COLOR;
}

✅ Step 2: Update Theme Files

Update colors for both light and dark modes:

File: src/styles/themes/light.css

src/styles/themes/light.css

[data-theme="light"] {
  --accent: #YOUR_BRAND_COLOR;
  --background: #ffffff;
  --foreground: #0f1219;
}

File: src/styles/themes/dark.css

src/styles/themes/dark.css

[data-theme="dark"] {
  --accent: #YOUR_BRAND_COLOR_DARK;  /* Often lighter for dark backgrounds */
  --background: #050505;
  --foreground: rgb(243, 244, 246);
}

✅ Step 3: Check for Hardcoded Colors

Caution

Critical: Some components may contain hardcoded gradient colors or hex values that won’t automatically update when you change --accent.

Search your codebase for hardcoded colors:

Use your code editor’s search function to find hex color values:

• Search for #fc4a1a (default orange)
• Search for #f7b733 (default gradient color)
• Search for any other hex colors you’re replacing

Common locations to check:

• Component files (src/components/**/*.astro)
• Page files (src/pages/**/*.astro)
• Any custom layouts or templates

Example - Hardcoded gradient:

<!-- ❌ Before: Hardcoded colors -->
<div style="background: linear-gradient(135deg, #fc4a1a 0%, #f7b733 100%);">

<!-- ✅ After: Using CSS variables -->
<div style="background: linear-gradient(135deg, var(--accent) 0%, var(--accent-dark) 100%);">

✅ Step 4: Verify Semantic Token Alignment

Ensure semantic tokens reference the correct base tokens:

src/styles/tokens.css

:root {
  /* ✅ Good: Semantic tokens reference base tokens */
  --color-text-primary: var(--foreground);
  --color-bg-primary: var(--background);

  /* ❌ Bad: Hardcoded values */
  --color-text-primary: #0f1219;
}

Accessibility & Contrast Guidelines

Caution

WCAG Compliance: Ensure your color combinations meet accessibility standards.

Contrast Ratio Requirements

• Normal text (< 18px): Minimum 4.5:1 contrast ratio
• Large text (≥ 18px or ≥ 14px bold): Minimum 3:1 contrast ratio
• UI components & graphics: Minimum 3:1 contrast ratio

Testing Your Colors

Use these tools to verify contrast ratios:

1. WebAIM Contrast Checker - Quick online tool
2. Coolors Contrast Checker - With color palette integration
3. Browser DevTools - Chrome/Edge have built-in contrast checkers

Example - Good vs. Bad Contrast:

/* ✅ Good: High contrast (7.5:1) */
--foreground: #0f1219;
--background: #ffffff;

/* ⚠️ Caution: Borderline (4.6:1) */
--foreground: #666666;
--background: #ffffff;

/* ❌ Bad: Fails WCAG AA (2.8:1) */
--foreground: #999999;
--background: #ffffff;

Dark Mode Contrast Considerations

Dark mode often requires different color adjustments:

/* Light mode - darker accent works */
[data-theme="light"] {
  --accent: #3b82f6;  /* Blue */
}

/* Dark mode - lighter accent for better contrast */
[data-theme="dark"] {
  --accent: #60a5fa;  /* Lighter blue */
}

Before/After Rebrand Example

Here’s a complete example of rebranding from orange to blue:

Before (Orange)

tokens.css

--accent: #fc4a1a;
--accent-dark: #f7b733;
--accent-rgb: 252, 74, 26;
--secondary: #FFB36B;

After (Blue)

tokens.css

--accent: #3b82f6;
--accent-dark: #1d4ed8;
--accent-rgb: 59, 130, 246;
--secondary: #8b5cf6;

/* themes/light.css */
[data-theme="light"] {
  --accent: #3b82f6;
}

/* themes/dark.css */
[data-theme="dark"] {
  --accent: #60a5fa;  /* Lighter for dark backgrounds */
}

Quick Verification

After updating your colors, verify the changes:

1. Visual Check: Browse your site in both light and dark modes
2. Search for Hardcoded Colors: Run a search for hex colors (e.g., #fc4a1a, #f7b733) in your codebase
3. Test Contrast: Use browser DevTools to check text contrast ratios
4. Check Gradients: Verify any gradient backgrounds use CSS variables

---

Typography

Font Family

File: src/styles/global.css

The theme uses Poppins font:

src/styles/global.css

@font-face {
  font-family: "Poppins";
  src: url("/fonts/Poppins-Regular.ttf") format("ttf");
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

body {
  font-family: "Poppins", sans-serif;
  font-size: 20px;
  line-height: 1.7;
}

Changing Fonts

Example - Using Inter:

src/styles/global.css

@font-face {
  font-family: "Inter";
  src: url("/fonts/Inter-Regular.woff2") format("woff2");
  font-weight: 400;
  font-display: swap;
}

body {
  font-family: "Inter", system-ui, sans-serif;
}

---

Shadows & Effects

Shadow Tokens

Defined in tokens.css:

src/styles/tokens.css

:root {
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.08);
  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
  --shadow-lg: 0 8px 15px rgba(0, 0, 0, 0.12);
  --shadow-xl: 0 12px 25px rgba(0, 0, 0, 0.16);
  --shadow-2xl: 0 25px 50px rgba(0, 0, 0, 0.2);
}

Dark mode uses heavier shadows for better depth perception:

[data-theme="dark"] {
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.18);
  --shadow-md: 0 6px 14px rgba(0, 0, 0, 0.28);
  --shadow-lg: 0 10px 28px rgba(0, 0, 0, 0.35);
}

Border Radius

:root {
  --radius: 0.75rem;  /* 12px */
}

Tailwind also provides radius utilities: rounded-sm, rounded-md, rounded-lg, rounded-xl, rounded-2xl.

---

Tailwind CSS Integration

The theme uses Tailwind CSS v4 with CSS variables for theming.

Using Tailwind Utilities

<div class="p-4 bg-primary text-primary-foreground rounded-lg shadow-md">
  Styled with Tailwind
</div>

Extending Tailwind

Tailwind v4 uses @theme directive in CSS. Edit src/styles/starwind.css to extend:

src/styles/starwind.css

@theme inline {
  --color-brand: var(--accent);
  --spacing-huge: 5rem;
}

Use in HTML:

<div class="bg-brand p-huge">Custom utilities</div>

---

Best Practices

✅ Do

• Use CSS variables for all colors and spacing
• Define tokens first, then use them in components
• Test both themes when changing colors
• Use semantic naming (--color-text-primary not --dark-gray)
• Leverage Tailwind for layout and spacing
• Search for hardcoded colors in template files when rebranding
• Verify contrast ratios using accessibility tools

❌ Don’t

• Hardcode colors in components or templates
• Skip theme testing - always check light and dark modes
• Override Starwind styles directly - use tokens instead
• Forget accessibility - maintain sufficient color contrast
• Assume example colors are final - #fc4a1a is just a placeholder for your brand color
• Update only tokens.css - check theme files and templates too

Tip

Pro Tip: After changing brand colors, search your entire codebase for the old hex values (e.g., #fc4a1a) to find any hardcoded references you might have missed.

Color Contrast

Ensure WCAG AA compliance (4.5:1 for normal text):

/* ✅ Good - high contrast */
--foreground: #0f1219;
--background: #ffffff;

/* ❌ Bad - low contrast */
--foreground: #cccccc;
--background: #ffffff;

Tip

Use tools like WebAIM Contrast Checker to verify.

---

Quick Reference

What to Customize	File	Variable
Primary brand color	tokens.css	--accent
Secondary color	tokens.css	--secondary
Background color	themes/light.css or dark.css	--background
Text color	themes/light.css or dark.css	--foreground
Border radius	tokens.css	--radius
Shadows	tokens.css	--shadow-*
Font family	global.css	font-family in body
Font size	global.css	font-size in body

---

Next Steps

Configuration

Configure your site settings.

Configuration Guide →

Add Languages

Add multilingual support.

Adding Languages →

Deploy

Deploy your styled site to production.

Deployment Guide →