@fluid-theme/core 0.4.3

package/AGENTS.md

@@ -0,0 +1,32 @@
+# AI Agent Instructions
+
+This project uses **The Fluid Theme** — a semantic CSS design system. If you are an AI coding assistant, read the following files to understand project conventions:
+
+## Essential Reading
+
+1. **`fluid-agent-kit/skills/css-conventions.md`** — CSS layer order, design tokens, logical properties, data attributes
+2. **`fluid-agent-kit/skills/accessibility.md`** — Non-negotiable accessibility standards
+3. **`fluid-agent-kit/skills/ux-rules.md`** — 12 behavioral rules for interactive components
+4. **`fluid-agent-kit/skills/image-optimization.md`** — Responsive images, lazy loading, focal points
+
+## Key Rules
+
+- Use **semantic HTML** with data attributes — not utility classes
+- Use **CSS custom properties** (tokens) for all values — never hardcode `16px` or `#333`
+- Use **logical properties** — `margin-block-start` not `margin-top`
+- Use **`<dialog>`** for modals — not `<div role="dialog">`
+- **Never remove focus outlines** — restyle if needed
+- **Respect `prefers-reduced-motion`** in all animations
+- Every `<img>` needs `alt`, `width`, `height`, and `loading="lazy"` (except above-fold)
+
+## Full Documentation
+
+- `_docs/DEVELOPMENT.md` — Master development guide
+- `_docs/UX-BEHAVIOR-SPEC.md` — Complete UX specification (18 sections)
+- `_docs/images-guide.md` — Image optimization guide
+- `_docs/reference/components.md` — Component API reference
+- `_docs/reference/tokens.md` — Design token reference
+
+## Framework Version
+
+0.4.0

package/CHANGELOG.md

@@ -0,0 +1,159 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.3] - 2026-03-24
+
+### Fixed
+- feat: npm package setup — @fluid-theme/core v0.4.2
+
+
+## [0.4.2] - 2026-03-21
+
+### Added
+- **npm package** configured as `@fluid-theme/core` (scoped, leaving room for `@fluid-theme/react`, `@fluid-theme/vue`, etc.)
+- **CSS build pipeline**: `npm run build` bundles all `@import` statements and minifies to `dist/fluid.min.css` via lightningcss
+- **`dist/fluid.min.css`**: production-ready minified build (196 kB) for CDN and npm consumers
+- **CDN links**: jsDelivr and unpkg will serve the minified build automatically once published
+- **Package exports**: `@fluid-theme/core` resolves to minified build; `@fluid-theme/core/src` gives access to raw source
+- **`PUBLISHING.md`**: step-by-step guide for completing the npm publish (create account, create org, login, publish)
+
+### Changed
+- Package renamed from `the-fluid-theme` → `@fluid-theme/core`
+- `package.json` `main` and `style` fields now point to `dist/fluid.min.css`
+- `prepublishOnly` hook ensures dist is always rebuilt before publishing
+- README installation instructions updated with correct CDN links and npm install command
+
+### Fixed
+- Removed internal `.agent/` and `.claude/` directories from git tracking
+
+## [0.4.1] - 2026-03-20
+
+### Added
+- **Image optimization pipeline**: `npm run optimize-images` generates WebP (640w, 1024w) and AVIF (full-width) variants via sharp
+- **`<picture>` elements**: all 62 template images wrapped with AVIF + WebP sources and `srcset`/`sizes` for responsive delivery
+- **Build scripts**: `scripts/optimize-images.js` (image conversion) and `scripts/update-html-picture.js` (HTML template updates)
+
+### Changed
+- **Image payload reduced 77.5%**: 33.6MB PNG originals → 7.6MB optimized WebP/AVIF variants
+- All hero/full-width images use `sizes="100vw"`, card images use responsive sizes
+- Avatar images intentionally excluded from `<picture>` wrapping (too small for srcset)
+- PNG originals preserved as fallbacks inside `<picture>` elements
+
+## [0.4.0] - 2026-03-20
+
+### Added
+- **Image utilities** in CSS framework:
+  - Focal point control via `data-focus` attribute on `.hero__background` and `.card__media` (top, bottom, left, right, center)
+  - Custom focal point via `--focus-x` / `--focus-y` CSS custom properties
+  - Image protection utility via `[data-protected]` (casual right-click deterrent, not DRM)
+  - Orientation-aware images via `[data-orientation="landscape|portrait"]`
+- **Lazy loading** (`loading="lazy"`) added to 70 below-fold images across all templates and examples
+- **Image dimensions** (`width`/`height`) added to all `<img>` tags for CLS prevention
+- **Image optimization guide** (`_docs/images-guide.md`) — format recommendations, responsive patterns, focal points, lazy loading, stack-specific solutions
+- **The Fluid Agent Kit** (`fluid-agent-kit/`) — AI coding assistant support with 4 skills:
+  - CSS conventions, UX rules, accessibility standards, image optimization
+- **AI pointer files**: `AGENTS.md` (agent-agnostic), `GEMINI.md` (Google Gemini)
+- **Updated `CLAUDE.md`** to reference Fluid Agent Kit instead of internal tools
+
+### Fixed
+- **Heading order** on homepage: h4 under h2 "Features" changed to h3
+- **Customizer 404**: nav link changed from broken `<a>` to `<button>` that opens settings panel
+- **Lint script**: added `.unlighthouse/` exclusion to prevent false positives from third-party tool output
+
+### Changed
+- Internal development tools (`.agent/`, `.claude/`) are now gitignored — not shipped publicly
+- Version bump from 0.3.5 to 0.4.0
+
+## [0.3.5] - 2026-03-20
+
+### Fixed
+- **`--color-primary` phantom token**: replaced 40+ references across 8 HTML files with `--accent` — all were rendering nothing
+- **Duplicate `<main>` in dashboard.html**: changed inner `<main>` to `<div role="region">`
+- **Missing `prefers-reduced-motion`** in `form.css` (6 transitions) and `themed-images.css` (2 transitions)
+- **`outline: none` in reset.css**: changed to `outline: 2px solid transparent` for high-contrast mode
+- **`--gray-12` typo in footer.css**: token doesn't exist, changed to `--gray-15`
+- **Duplicate `.progress__track` selector** in indicator.css: merged into single rule
+- **Dead `max-inline-size` rule** in footer.css `.site-footer__brand`: removed duplicate
+- **Print styles**: now hide all `.nav` (not just sticky), use token for `pre/code` background
+- **Missing `<h1>` in search-results.html**: added heading
+- **Generic `alt="Team member"`** on about.html: changed to actual names
+- **Documentation phantom API**: `tokens.md` documented non-existent `--color-primary` family, changed to `--accent`
+- **Stale documentation**: getting-started (v0.3.2, 17 components, 9 templates, old repo URL), _start-here (v0.3.2, 17/16), README (17/9), installation (17) — all corrected to v0.3.5 / 23 / 18
+
+### Added
+- **Pre-release audit report** (`_docs/PRE-RELEASE-AUDIT.md`): 13-phase comprehensive audit covering CSS validity, browser compat, accessibility, HTML validation, token consistency, responsive, dark mode, print, documentation, npm readiness, cross-file consistency, security, performance
+
+## [0.3.4] - 2026-03-20
+
+### Added
+- **Version badge** documented in components reference
+- **Claude Code skills**: CSS conventions, UX rules, accessibility, Agile Kit reference
+- **Lint script** for convention checking (`.claude/scripts/lint-conventions.sh`)
+
+### Fixed
+- All `outline: none` violations replaced with `outline: 2px solid transparent` for high-contrast mode accessibility (7 files)
+- Added `prefers-reduced-motion` handling to `base.css` progress bar animation
+- UX audit report updated — all 17 critical items now marked as resolved
+- Footer consistency: added missing footer to blog-post, dashboard, login, register, search-results templates
+- Hero consistency: added missing `data-size="full"` to services.html hero
+- Landing page version badges now use `{{ site.version }}` instead of hardcoded values
+
+## [0.3.3] - 2026-03-20
+
+### Added
+- **Section components** (6): features, testimonials, CTA, footer, team, stats
+- **Version badge component**: fixed-position version display, toggled via `data-show-version`
+- **Page templates** (8): blog post, SaaS landing, agency landing, product landing, login, register, dashboard, search results
+- **Integration guides**: React/Next.js, Vue/Nuxt, Svelte/SvelteKit
+- **Migration guides**: Bootstrap, Tailwind
+- **Documentation**: installation, first-component tutorial, theming guide, layout guide
+- **GitHub infrastructure**: CI workflow, release workflow, issue templates, PR template, contributing guide, code of conduct
+- New components: empty state, steps, search input, chip
+
+### Fixed
+- Contact form validation with `aria-invalid`, `.form-error`, and submission feedback
+- All critical UX audit items resolved (17 critical, 25 warnings addressed)
+- Remaining physical properties converted to logical properties
+- Token consistency across all components
+- Deep accessibility improvements — focus management, landmarks, motion safety
+- Print styles, dark mode shadows, switch documentation
+- Destructive modal specificity (action-specific labels)
+- Responsive tables with `data-responsive` + `td[data-label]`
+- `prefers-reduced-motion` in button, card, nav components
+- Hardcoded color overrides replaced with token-based values
+- Browser support requirements documentation
+
+## [0.3.2] - 2026-03-15
+
+### Added
+- Badge component
+- Scroll reveal animations
+- Layout positioning utilities (flex, grid, sidebar, holy grail, dashboard)
+- Container query support throughout components
+
+### Fixed
+- Dark mode uses deep palette colors instead of black
+- Subdued contrast mode with proper muted palettes
+- Fluid typography scaling
+
+## [0.3.0] - 2026-03-14
+
+### Added
+- 17 UI components (buttons, cards, nav, forms, heroes, indicators, settings panel, scroll progress, themed images, modal, tooltip, accordion, alert, table, avatar, loading, dropdown)
+- 10 color palettes with 6 accent colors each
+- 7 physics-based motion styles
+- CSS layer architecture
+- Dark mode, light mode, auto mode, subdued contrast
+- OKLCH color system with color-mix()
+
+[0.3.5]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.3.4...v0.3.5
+[0.3.4]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.3.3...v0.3.4
+[0.3.3]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.3.0...v0.3.2
+[0.3.0]: https://github.com/Agile-Media-Agency/the-fluid-theme/releases/tag/v0.3.0
+[0.4.2]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.4.1...v0.4.2
+[0.4.3]: https://github.com/Agile-Media-Agency/the-fluid-theme/compare/v0.4.2...v0.4.3

package/CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+> **Fluid Framework** — A modern, semantic CSS design system built on physics principles, not utility classes.
+
+## Before Doing Anything
+
+1. Read `fluid-agent-kit/skills/` — 4 skill files covering CSS conventions, UX rules, accessibility, and image optimization
+2. Read `_docs/DEVELOPMENT.md` — master development guide
+3. Read `_docs/UX-BEHAVIOR-SPEC.md` — 18-section behavioral specification (skim first, deep-read relevant sections)
+
+## Quick Reference
+
+```bash
+npm run serve    # Open examples in browser at localhost:8080
+```
+
+## What This Is
+
+A CSS framework that proves modern CSS can replace the utility-class approach of Tailwind/Bootstrap:
+
+- **Semantic HTML** over `<div class="flex flex-col p-4">` soup
+- **CSS Custom Properties** for runtime theming (no rebuild needed)
+- **Complete presets** that change typography, colors, motion, AND layout
+- **Dark mode uses deep palette colors**, not just black
+- **No build step** — link one CSS file and go
+
+## Core Principles
+
+1. **Semantic HTML** — Use meaningful elements, not div soup
+2. **CSS Custom Properties** — All values via tokens (`var(--space-5)`)
+3. **Logical Properties** — `margin-block`, `padding-inline` (not `-top`, `-left`)
+4. **No Build Step** — Works directly in browsers
+5. **Progressive Enhancement** — Works without JavaScript
+6. **Presets are complete experiences** — Not just color swaps
+7. **Accessibility is non-negotiable** — Connected to disabled and autism communities
+
+## Layer Order
+
+```css
+@layer reset, tokens, base, layouts, components, themes, utilities;
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/fluid.css` | Main entry point (imports everything) |
+| `src/core/tokens.css` | Design tokens, palettes, presets |
+| `src/components/` | 23 component CSS files |
+| `src/sections/` | 6 section CSS files |
+| `templates/` | 18 HTML templates |
+| `examples/` | Live component demos |
+| `_docs/UX-BEHAVIOR-SPEC.md` | UX behavioral rules (18 sections) |
+| `_docs/images-guide.md` | Image optimization best practices |
+| `fluid-agent-kit/` | AI agent skills and conventions |
+
+## The Fluid Agent Kit
+
+This project includes the **Fluid Agent Kit** (`fluid-agent-kit/`) with skill files for AI coding assistants. See `fluid-agent-kit/README.md` for details.
+
+**Available skills:**
+- `fluid-agent-kit/skills/css-conventions.md` — Layer order, tokens, logical properties
+- `fluid-agent-kit/skills/ux-rules.md` — 12 behavioral rules for interactive components
+- `fluid-agent-kit/skills/accessibility.md` — HTML, keyboard, motion, color standards
+- `fluid-agent-kit/skills/image-optimization.md` — Responsive images, lazy loading, focal points
+
+## UX Behavior Spec
+
+Full spec at `_docs/UX-BEHAVIOR-SPEC.md`. Quick reference at `fluid-agent-kit/skills/ux-rules.md`.
+
+**The non-negotiables:**
+- Every destructive action requires a confirmation modal with specific title and consequence body
+- Every user action requires visible feedback (toast, alert, or state change)
+- Every button requires a specific label ("Save Changes" not "Submit")
+- Every pattern must be consistent across all screens (search and update all instances)
+- Every interactive element must be keyboard accessible with visible focus
+- Every animation must respect `prefers-reduced-motion`
+
+## Image Optimization
+
+Full guide at `_docs/images-guide.md`. Quick reference at `fluid-agent-kit/skills/image-optimization.md`.
+
+**The non-negotiables:**
+- Every `<img>` must have `width` and `height` attributes (prevents CLS)
+- Every below-fold image must have `loading="lazy"`
+- Every image must have meaningful `alt` text
+- Use `data-focus` for focal point control on hero backgrounds and card media
+- Use `data-aspect` for consistent aspect ratios on card media
+- Serve modern formats (WebP/AVIF) with `<picture>` fallbacks
+
+## Documentation
+
+| Document | What It Covers |
+|----------|----------------|
+| [DEVELOPMENT.md](_docs/DEVELOPMENT.md) | Master guide — read first |
+| [UX-BEHAVIOR-SPEC.md](_docs/UX-BEHAVIOR-SPEC.md) | Behavioral rules — 18 sections |
+| [images-guide.md](_docs/images-guide.md) | Image optimization best practices |
+| [architecture.md](_docs/architecture.md) | Technical decisions |
+| [reference/components.md](_docs/reference/components.md) | Component API |
+| [reference/tokens.md](_docs/reference/tokens.md) | Design token reference |
+
+## Version
+
+**Current: 0.4.1** — Update in package.json, PROJECT_STATUS.md, CHANGELOG.md, _config.yml, and version badges on every session that modifies files.

package/GEMINI.md

@@ -0,0 +1,48 @@
+# Gemini Instructions — The Fluid Theme
+
+You are working with **The Fluid Theme**, a semantic CSS design system built on physics principles.
+
+## Read These First
+
+1. `fluid-agent-kit/skills/css-conventions.md` — CSS rules and token system
+2. `fluid-agent-kit/skills/accessibility.md` — Accessibility standards
+3. `fluid-agent-kit/skills/ux-rules.md` — UX behavioral rules
+4. `fluid-agent-kit/skills/image-optimization.md` — Image best practices
+
+## Core Rules
+
+### CSS
+- Layer order: `@layer reset, tokens, base, layouts, components, themes, utilities;`
+- All values from design tokens: `var(--space-4)` not `16px`
+- Logical properties only: `margin-block-start` not `margin-top`
+- Variants via data attributes: `data-variant="danger"` not `.btn--danger`
+- Components in `@layer components { }`
+
+### HTML
+- Semantic elements: `<article class="card">` not `<div class="flex flex-col">`
+- Native `<dialog>` for modals (automatic focus trapping via `.showModal()`)
+- Every `<img>` needs `alt`, `width`, `height`
+- `loading="lazy"` on all below-fold images
+- Use `data-focus` for image focal points, `data-aspect` for aspect ratios
+
+### Accessibility (Non-Negotiable)
+- Never remove `:focus-visible` outlines
+- `prefers-reduced-motion: reduce` in every animated component
+- 44x44px minimum touch targets
+- Color alone never conveys information
+
+### UX Behavior
+- Destructive actions require confirmation modals
+- Every action produces visible feedback
+- Specific button labels only ("Save Changes" not "Submit")
+- Validate forms on blur, then keystroke after first error
+
+## Documentation
+
+- `_docs/DEVELOPMENT.md` — Master guide
+- `_docs/UX-BEHAVIOR-SPEC.md` — Full UX specification
+- `_docs/images-guide.md` — Image optimization guide
+- `_docs/reference/components.md` — Component API
+- `_docs/reference/tokens.md` — Token reference
+
+## Version: 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agile Media Agency
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# The Fluid Theme Framework
+
+**[TheFluidTheme.com](https://thefluidtheme.com)** | [Live Components](https://thefluidtheme.com/examples/components.html) | [Live Foundation](https://thefluidtheme.com/examples/foundation.html) | [Templates](https://thefluidtheme.com/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:
+
+| Motion Style | Reynolds | Behavior |
+|-------------|----------|----------|
+| **Still** | 0 | No motion, instant state changes |
+| **Serene** | ~10 | Slow, meditative, Ken Burns |
+| **Stream** | ~100 | Laminar flow, smooth and predictable |
+| **Flowing** | ~500 | Organic ease-in-out |
+| **Cascade** | ~1000 | Transitional, gentle waterfalls |
+| **Rapids** | ~5000 | Turbulent, energetic with resistance |
+| **Tsunami** | ~50000 | Massive force, dramatic displacement |
+
+## Installation
+
+### CDN (recommended for quick start)
+
+**jsDelivr** (recommended):
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fluid-theme/core/dist/fluid.min.css">
+```
+
+**unpkg:**
+```html
+<link rel="stylesheet" href="https://unpkg.com/@fluid-theme/core/dist/fluid.min.css">
+```
+
+### npm
+
+```bash
+npm install @fluid-theme/core
+```
+
+Then in your HTML:
+```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.):
+```js
+import '@fluid-theme/core';
+```
+
+### Download
+
+Grab the latest release from the [GitHub Releases](https://github.com/Agile-Media-Agency/the-fluid-theme/releases) page.
+
+## Quick Start
+
+```html
+<!-- 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-motion="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>
+```
+
+```bash
+# 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:
+
+| Palette | Vibe |
+|---------|------|
+| **Fluid** | Water-themed, auto-links to motion style |
+| **Morandi** | Muted, sophisticated Italian aesthetics |
+| **Bold** | High saturation, confident primaries |
+| **Pastel** | Soft, approachable pastels |
+| **Earth** | Natural, organic tones |
+| **Mono** | Grayscale with subtle warmth |
+| **80s** | Neon retrowave |
+| **Matrix** | Cyberpunk greens |
+| **Subtle** | Nearly neutral, whisper quiet |
+| **Tsunami** | Deep ocean palette (Hokusai-inspired) |
+
+### 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
+```css
+@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.
+
+| Skill | What It Covers |
+|-------|----------------|
+| CSS Conventions | Layer order, tokens, logical properties, data attributes |
+| UX Rules | 12 behavioral rules for interactive components |
+| Accessibility | HTML, keyboard, motion, touch, color standards |
+| Image Optimization | Responsive images, lazy loading, focal points, formats |
+
+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
+│   ├── _start-here.md        # Full documentation
+│   ├── 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:
+
+```html
+<body
+  data-theme="dark"      <!-- light | dark | auto -->
+  data-motion="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
+
+- [x] **Phase 1: Foundation** — Reset, tokens, base styles
+- [x] **Phase 2: Core Components** — Buttons, cards, nav, forms, heroes, indicators (9 components)
+- [x] **Phase 3: Extended Components + Layouts** — Modal, tooltip, accordion, alert, table, avatar, loading, dropdown + flex/grid utilities (17 total)
+- [x] **Phase 4: Documentation** — Getting started guide, installation, tutorials, image optimization guide
+- [x] **Phase 5: Distribution** — npm publish, CDN, Fluid Agent Kit for AI assistants
+
+**Current**: v0.4.2 — See [PROJECT_STATUS.md](PROJECT_STATUS.md) for details.
+
+## Browser Support
+
+Modern browsers: Chrome 120+, Firefox 120+, Safari 16.4+, Edge 120+
+
+## Documentation
+
+- **[TheFluidTheme.com](https://thefluidtheme.com)** — Live demo site
+- **[Getting Started](_docs/getting-started.md)** — Installation and first steps
+- **[Full Documentation](_docs/_start-here.md)** — Complete guide
+- **[Component Reference](_docs/reference/components.md)** — All 23 components
+- **[Positioning Reference](_docs/reference/positioning.md)** — Layout system
+- **[Tokens Reference](_docs/reference/tokens.md)** — Design tokens
+- **[Public Readiness Roadmap](FRAMEWORK_READINESS.md)** — Launch plan
+- **[Executive Summary](SUMMARY.md)** — Quick overview
+
+## License
+
+MIT — Use it, modify it, make it yours.
+
+---
+
+**Version 0.4.2** | **[TheFluidTheme.com](https://thefluidtheme.com)** | Built with physics and 32 years of design experience.