Tailwind Architecture Documentation

Document Information

Status: Mandatory
Target Audience: Frontend Engineering & Design Implementation
Version: 2.0 (Expanded)

1. Architectural Philosophy

This design system is built upon a CSS-Variable-Driven Tokenization strategy. Unlike standard Tailwind configurations that "hard-code" values at build time (e.g., red-500 = #ef4444), this architecture uses Tailwind classes as proxies that reference runtime CSS variables.

Core Objectives

• Runtime Theming: Enable instant theme switching (e.g., changing branding colors or Dark Mode) by modifying CSS variables in the DOM, without requiring a rebuild.
• Opacity Support: By storing color channels (R G B) separately from the alpha channel, we ensure Tailwind's opacity modifiers (e.g., bg-primary/50) function correctly.
• Density Independence: Spacing and sizing are relative to a base-gutter, allowing for "Compact" or "Comfortable" density modes by changing a single variable.

2. Color Palette System

The configuration utilizes a sophisticated generation function (generateTailwindColors) that maps a base set of keys to 19 distinct tonal variations.

The CSS Contract (Crucial)

For the Tailwind classes to function, the CSS variables MUST be defined as space-separated RGB channels without the rgb() wrapper or # symbol.

Invalid Format

/* ❌ Incorrect */
--primary: #3b82f6;
--primary: rgb(59, 130, 246);

Correct Format

/* ✅ Correct */
--primary: 59 130 246;

Generated Keys

The configuration expects the following root keys in the colors object. Each key automatically generates levels from 1 to 100.

Key	Purpose
base	Neutral background/foreground
primary	Main brand color
secondary	Accents
tertiary	Highlight/Alternative
black	Pure shades
success	State indication
warning	State indication
danger	State indication

Usage Examples

<!-- Base color -->
<div class="bg-primary text-white">...</div>

<!-- With Opacity (Possible due to RGB structure) -->
<div class="bg-primary/50">...</div>

<!-- Specific Tonal Level -->
<div class="bg-primary-80 text-primary-10">...</div>

3. CSS Variables Reference

Ensure these are defined in your global CSS (:root or body). This acts as the configuration layer for the entire application.

A. Color Definitions

Dark Mode Implementation

To implement Dark Mode, simply override these variables within a .dark class scope.

:root {
    /* Format: Red Green Blue */
    --primary: 59 130 246;
    
    /* Tonal Levels (Generated for 100, 95, 90... down to 1) */
    --primary-100: 30 58 138;
    --primary-95: 35 65 145;
    /* ... intermediate levels ... */
    --primary-10: 239 246 255;
    
    --success: 34 197 94;
    --danger: 239 68 68;
    /* Repeat for all keys listed in Section 2 */
}

B. Spatial & Sizing System (Density Control)

Important Principle

We do not use fixed pixels for layout spacing. We use the Base Gutter system.

:root {
    /* The fundamental unit of space. Change this to scale the whole UI. */
    --base-gutter: 1rem;       /* 16px default */
    
    /* Derivatives */
    --base-gutter-half: calc(var(--base-gutter) / 2);
    --base-gutter-xs: calc(var(--base-gutter) / 4);
    /* ... up to 4xl ... */

    /* Input & Interactive Elements */
    --input-height-base: 3rem;
    --input-height-sm: 2.5rem;
    --input-height-lg: 3.5rem;
    
    /* Border Radii */
    --radius-input: 0.5rem;
    --radius-button: 0.5rem;
    --radius-card: 1rem;
}

Tailwind Mapping

Utility Class	CSS Output
p-base	padding: var(--base-gutter)
gap-base-half	gap: var(--base-gutter-half)
h-input-base	height: var(--input-height-base)

C. Typography

Font families are abstracted to allow for quick typeface swapping.

:root {
    --base-font: 'Inter', system-ui, -apple-system, sans-serif;
}

Tailwind Mapping: font-base

4. Extended Utilities & Custom Classes

The configuration extends standard Tailwind with highly specific utilities designed for this project's visual language.

A. Layout Helpers

Fractional Flex Basis

• flex-1/10 through flex-9/10: Precise percentage-based layout divisions (10% to 90%).

Fractional Max-Widths

• max-w-1/4, max-w-1/2, max-w-3/4: For constraining container widths fluidly.

Line Heights

• leading-spaced: Sets line-height to 1.75 for improved readability in text-heavy sections.

B. Depth & Elevation (Shadows)

Shadows are also tied to the base gutter system for consistent "lift".

• shadow-base-half
• shadow-base-xs
• shadow-base-md
• shadow-base-xl

C. Visual Patterns

bg-mosaic-pattern

A complex, CSS-gradient-based checkerboard pattern.

Requirement

It uses var(--color) to define the stroke/fill color. You must set this variable on the element or its parent.

Usage:

<div class="bg-mosaic-pattern" style="--color: rgba(0,0,0,0.1)"></div>

5. Animation System

The architecture includes custom keyframes and animation utilities for interactive polish.

Available Animations

Class	Behavior	Use Case
animate-float	Gentle vertical/horizontal floating (6s duration)	Hero images, decorative icons
animate-float-slow	Slower floating (8s duration)	Background elements
animate-float-delayed	Floating with a 3s delay	Staggered animations
animate-pulse-slow	Opacity pulse (3s duration)	Loading skeletons, subtle attention grabbers
animate-spin-slow	Linear spin (10s duration)	Loading indicators, decorative gears
animate-color-switch	Alternates colors (3s duration)	Attention buttons, status indicators

Specialized: Color Switch Animation

The animate-color-switch utility transitions background, fill, and stroke between two variables.

Required Variables:

• --color-from
• --color-to

Usage:

<button class="animate-color-switch" style="--color-from: #3b82f6; --color-to: #ec4899;">
   Click Me
</button>

6. Z-Index Strategy

Strict Adherence Required

To prevent "z-index wars", strictly adhere to the defined scale. Do not use arbitrary values like z-[9999].

Z-Index	Purpose
z-75	Dropdowns, Tooltips within context
z-100	Sticky Headers
z-200	Drawers / Sidebars
z-300	Modals
z-400	Toasts / Notifications
z-500	Critical Overlays (Loading screens)

7. Developer Workflow & Best Practices

Best Practices Summary

1. Never Hardcode Colors: Do not use text-[#123456]. Always define the color in the CSS variables and use the generated utility class.

2. Use base for Layout: Avoid p-4 or m-8 for main structural components. Use p-base or m-base-md to ensure the layout respects the global density settings.

3. Review the Alpha: When adding new colors to CSS, verify that they are strictly numbers (255 0 0). If you include commas or rgb(), the opacity modifiers in Tailwind will break silently.

---

Additional Resources & References

Related Documentation

• Design Tokens Implementation
• Theme Configuration Guide
• Component Library Standards

External Links

• Tailwind CSS Documentation
• CSS Custom Properties Guide