The Fluid Theme Framework

Superseded (2026-10-23, Pass 0). Most of this README describes the preset/palette system, which was removed. What the theme is now, and its knobs: _docs/STATUS.md; every default, why, and how to change it: _docs/defaults.md. Kept as history.

TheFluidTheme.com | Live Components | Live Foundation | Templates

A Physics-Based Design System

A modern approach to web theming built on fluid dynamics principles. Every animation, transition, and interaction is governed by real physics — viscosity, displacement, surface tension, momentum, and friction.

"There HAS to be a better way..." — And now there is.

What Makes This Different

Most design systems pick arbitrary animation timings. We use Reynolds numbers — the same physics that determines whether water flows smoothly or turbulently:

Starter Kits

Installation

CDN (recommended for quick start)

jsDelivr (recommended):

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fluid-theme/core/dist/fluid.min.css">

unpkg:

<link rel="stylesheet" href="https://unpkg.com/@fluid-theme/core/dist/fluid.min.css">

npm

npm install @fluid-theme/core

Then in your HTML:

<!-- Production (minified) -->
<link rel="stylesheet" href="node_modules/@fluid-theme/core/dist/fluid.min.css">

<!-- Source (readable, for customisation) -->
<link rel="stylesheet" href="node_modules/@fluid-theme/core/src/fluid.css">

Or in a bundler (Vite, Webpack, etc.):

import '@fluid-theme/core';

Download

Grab the latest release from the GitHub Releases page.

Quick Start

<!-- Link the CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fluid-theme/core/dist/fluid.min.css">

<!-- Set your preferences -->
<body data-theme="dark" data-preset="cascade" data-palette="fluid" data-accent="1">

<!-- Use semantic HTML -->
<article class="card">
  <div class="card__content">
    <h2 class="card__title">Clean and Semantic</h2>
    <p class="card__description">No utility class soup needed.</p>
  </div>
</article>

# Local development
npm run serve    # Opens at localhost:8080

Core Features

Motion System

Seven physics-based animation styles:

• Still — Reduced motion, instant transitions
• Serene — Slow, meditative Ken Burns (1200ms)
• Stream — Smooth, laminar animations (800ms)
• Flowing — Organic ease-in-out (600ms)
• Cascade — Gentle waterfall effects (500ms)
• Rapids — Turbulent with friction and drag (300ms)
• Tsunami — Dramatic rise, crest, and crash (400ms)

23 Components

Buttons, Cards, Navigation, Forms, Heroes, Indicators, Scroll Progress, Settings Panel, Themed Images, Modal/Dialog, Tooltip/Popover, Accordion, Alert/Toast, Table, Avatar, Loading/Skeleton, Dropdown

Color Palettes

Ten curated palettes, each with 6 accent colors:

Theme Modes

• Light — Clean, high contrast
• Dark — Easy on the eyes
• Auto — Follows system preference
• Subdued — Low contrast for any mode (OKLCH-based)

Layout System

• Flex utilities — Direction, wrap, grow/shrink, basis
• Grid utilities — 2/3/4 columns, auto-fit responsive, span
• Layout patterns — Sidebar, holy grail, dashboard
• Position utilities — Sticky, z-index, overflow, responsive visibility

Image Optimization

Built-in CSS utilities for responsive, performant images:

• Focal point control — data-focus="top|bottom|left|right|center" on hero backgrounds and card media
• Custom focal points — --focus-x / --focus-y CSS custom properties
• Aspect ratios — data-aspect="square|video|portrait|wide" on .card__media
• Image protection — data-protected blocks casual right-click saving (not DRM)
• Orientation-aware — data-orientation="landscape|portrait" shows/hides based on viewport
• Lazy loading — all templates use loading="lazy" on below-fold images
• Dimensions — all <img> tags include width/height for CLS prevention

See _docs/images-guide.md for the full guide including <picture> patterns, srcset, format recommendations (AVIF > WebP > JPEG), and stack-specific solutions.

CSS Architecture

@layer reset, tokens, base, layouts, components, themes, utilities;

Modern CSS features throughout:

• OKLCH colors with color-mix() for derived shades
• Logical properties (margin-block, padding-inline)
• Container queries for component-level responsiveness
• View Transitions API for page transitions
• CSS Custom Properties for runtime theming

The Fluid Agent Kit

This project ships with the Fluid Agent Kit (fluid-agent-kit/) — skill files that help AI coding assistants produce correct Fluid Theme code.

Works automatically with Claude Code (reads CLAUDE.md), Gemini (reads GEMINI.md), and any AI assistant that reads project-level instructions (reads AGENTS.md).

Project Structure

the-fluid-theme/
├── fluid-agent-kit/          # AI coding assistant skills
│   ├── README.md             # Kit overview
│   └── skills/               # CSS, UX, a11y, image skills
├── _docs/                    # Documentation
│   ├── STATUS.md             # What the theme is now (start here)
│   ├── archive/              # Superseded docs, kept as history
│   ├── images-guide.md       # Image optimization guide
│   └── reference/            # Component + layout API docs
├── _includes/                # Jekyll includes
├── src/
│   ├── core/
│   │   ├── reset.css         # Modern reset
│   │   ├── tokens.css        # Design tokens + motion + palettes
│   │   └── base.css          # Base element styles
│   ├── components/           # 23 UI components
│   ├── layouts/              # Layout patterns + utilities
│   ├── animations/           # Scroll reveal system
│   └── fluid.css             # Main entry point
├── examples/                 # 7 demo pages
├── templates/                # 18 page templates
├── CLAUDE.md                 # Claude Code instructions
├── GEMINI.md                 # Google Gemini instructions
└── AGENTS.md                 # Agent-agnostic instructions

Data Attributes

Control everything via HTML attributes:

<body
  data-theme="dark"      <!-- light | dark | auto -->
  data-preset="cascade"  <!-- still | serene | stream | flowing | cascade | rapids | tsunami -->
  data-palette="fluid"   <!-- fluid | morandi | bold | pastel | earth | mono | 80s | matrix | subtle | tsunami -->
  data-accent="1"        <!-- 1-6, selects from current palette -->
  data-contrast="normal" <!-- normal | subdued -->
>

Philosophy

Semantic First — Use <article class="card"> not <div class="flex flex-col p-4 m-2 rounded-lg shadow-md">

Progressive Enhancement — Everything works without JavaScript, then enhances gracefully

Zero Build Step — No compilation needed, works directly in browsers

Physics-Based — Animations feel natural because they follow natural laws

Accessibility Built-In — prefers-reduced-motion respected, WCAG 2.1 AA focused

Development Status

• Phase 1: Foundation — Reset, tokens, base styles
• Phase 2: Core Components — Buttons, cards, nav, forms, heroes, indicators (9 components)
• Phase 3: Extended Components + Layouts — Modal, tooltip, accordion, alert, table, avatar, loading, dropdown + flex/grid utilities (17 total)
• Phase 4: Documentation — Getting started guide, installation, tutorials, image optimization guide
• Phase 5: Distribution — npm publish, CDN, Fluid Agent Kit for AI assistants

Current: the latest git tag (git describe --tags --abbrev=0, also package.json); never written here. What the theme is now: _docs/STATUS.md.

Browser Support

Modern browsers: Chrome 120+, Firefox 120+, Safari 16.4+, Edge 120+

Documentation

• TheFluidTheme.com — Live demo site
• Getting Started — Installation and first steps
• What the theme is now — Start here
• Component Reference — All 23 components
• Positioning Reference — Layout system
• Tokens Reference — Design tokens
• Archive — Superseded docs (readiness roadmap, summary, old status), kept as history

License

MIT — Use it, modify it, make it yours.

Version: the latest git tag | TheFluidTheme.com | Built with physics and 32 years of design experience.