@fluid-theme/core 0.4.3

package/fluid-agent-kit/skills/css-conventions.md

@@ -0,0 +1,51 @@
+# Fluid Theme — CSS Conventions
+
+When writing or modifying CSS for a site built with The Fluid Theme, follow these rules.
+
+## Layer Order (never violate)
+
+```css
+@layer reset, tokens, base, layouts, components, themes, utilities;
+```
+
+## Required Patterns
+
+- **All values from tokens**: `var(--space-4)` not `16px`, `var(--color-text)` not `#333`
+- **Logical properties only**: `margin-block-start` not `margin-top`, `inline-size` not `width`
+- **Data attributes for variants**: `data-variant="danger"` not `.btn--danger`
+- **Component-scoped private properties**: prefix with underscore `--_card-padding`
+- **All components** wrapped in `@layer components { }`
+
+## Token Quick Reference
+
+| Category | Examples |
+|----------|---------|
+| Spacing | `--space-0` through `--space-24` |
+| Typography | `--font-size-xs` through `--font-size-5xl` |
+| Colors | `--color-text`, `--color-surface`, `--accent`, `--color-success/warning/error/info` |
+| Borders | `--radius-sm` through `--radius-full`, `--border-width` |
+| Shadows | `--shadow-xs` through `--shadow-xl` |
+| Motion | `--duration-instant` through `--duration-slowest` |
+
+## Component File Pattern
+
+Every component CSS file should include:
+1. Header comment with usage examples
+2. Base styles
+3. Variants via `data-*` attributes
+4. Responsive behavior (container queries preferred over media queries)
+5. Reduced motion: `@media (prefers-reduced-motion: reduce) { }`
+
+## File Locations
+
+- Components: `src/components/[name].css`
+- Sections: `src/sections/[name].css`
+- After creating a new component, add `@import` to `src/fluid.css`
+
+## Never Do
+
+- `padding: 16px` — use a token
+- `margin-top: 1rem` — use logical property (`margin-block-start`)
+- `.card--elevated` — use `data-variant="elevated"`
+- `:focus { outline: none }` — never remove focus outlines
+- Vendor prefixes — modern browsers only

package/fluid-agent-kit/skills/image-optimization.md

@@ -0,0 +1,115 @@
+# Image Optimization — Fluid Theme
+
+This skill covers responsive images, performance optimization, and image utilities available in The Fluid Theme.
+
+For the full guide with code examples, see `_docs/images-guide.md`.
+
+## Quick Reference
+
+### Format Priority
+
+AVIF > WebP > JPEG > PNG. Use `<picture>` for format fallbacks:
+
+```html
+<div class="hero__background" data-focus="top">
+  <picture>
+    <source srcset="hero.avif" type="image/avif">
+    <source srcset="hero.webp" type="image/webp">
+    <img src="hero.jpg" alt="Description" width="1920" height="1080">
+  </picture>
+</div>
+```
+
+### Lazy Loading
+
+Add `loading="lazy"` to ALL images except the first/hero image on each page:
+
+```html
+<!-- First image: above the fold, load eagerly -->
+<img src="hero.jpg" alt="Hero" width="1920" height="1080">
+
+<!-- All other images: lazy load -->
+<img src="card.jpg" alt="Card" loading="lazy" width="1920" height="1080">
+```
+
+### Always Include Dimensions
+
+Every `<img>` must have `width` and `height` attributes to prevent layout shift (CLS):
+
+| Aspect Ratio | Dimensions |
+|-------------|------------|
+| 16:9 (video) | `width="1920" height="1080"` |
+| 1:1 (square) | `width="800" height="800"` |
+| 3:4 (portrait) | `width="800" height="1067"` |
+| 21:9 (wide) | `width="1920" height="823"` |
+| Avatar | `width="96" height="96"` |
+
+### Focal Point Control
+
+Use `data-focus` on `.hero__background` or directly on `.card__media`:
+
+```html
+<!-- Preset positions -->
+<div class="hero__background" data-focus="top">
+<img class="card__media" data-focus="left">
+
+<!-- Custom position -->
+<div class="hero__background" style="--focus-x: 30%; --focus-y: 20%;">
+```
+
+Available presets: `top`, `bottom`, `left`, `right`, `center`
+
+### Aspect Ratios
+
+Use `data-aspect` on `.card__media`:
+
+```html
+<img class="card__media" data-aspect="video">    <!-- 16:9 -->
+<img class="card__media" data-aspect="square">   <!-- 1:1 -->
+<img class="card__media" data-aspect="portrait">  <!-- 3:4 -->
+<img class="card__media" data-aspect="wide">      <!-- 21:9 -->
+```
+
+### Image Protection
+
+Add `data-protected` to discourage casual right-click saving (not DRM):
+
+```html
+<div data-protected>
+  <img src="portfolio.jpg" alt="My work">
+</div>
+```
+
+Limitations: Does NOT prevent screenshots, dev tools, or determined users.
+
+### Orientation-Aware Images
+
+Show different images based on viewport orientation:
+
+```html
+<img data-orientation="landscape" src="wide-shot.jpg" alt="Scene">
+<img data-orientation="portrait" src="tall-crop.jpg" alt="Scene">
+```
+
+### Responsive Images Pattern
+
+```html
+<img
+  srcset="photo-640.webp 640w, photo-1024.webp 1024w, photo-1920.webp 1920w"
+  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw"
+  src="photo-1024.webp"
+  alt="Description"
+  loading="lazy"
+  width="1920" height="1080"
+>
+```
+
+## Checklist for New Pages
+
+- [ ] First/hero image: no `loading="lazy"`, consider `fetchpriority="high"`
+- [ ] All other images: `loading="lazy"`
+- [ ] All images: `width` and `height` attributes set
+- [ ] All images: meaningful `alt` text
+- [ ] Hero backgrounds: consider `data-focus` for focal point control
+- [ ] Card media: `data-aspect` set appropriately
+- [ ] Images served in WebP or AVIF with fallbacks

package/fluid-agent-kit/skills/ux-rules.md

@@ -0,0 +1,43 @@
+# UX Behavior Rules — Quick Reference
+
+Full specification: `_docs/UX-BEHAVIOR-SPEC.md` (18 sections, 1031 lines).
+
+Read the full spec before building interactive components. This is the condensed version.
+
+## The 12 Rules
+
+1. **Destructive Actions**: Confirmation modal required. Title names the specific item. Body explains consequences. Buttons: [Cancel] [Delete Specific Thing]. Add `autofocus` to Cancel. Use `[data-destructive]` on modal.
+
+2. **Action Consistency**: Search entire project for similar patterns before implementing. Same display mode, same order, same styling everywhere.
+
+3. **Modal Strategy**: Toast > inline alert > modal. Use minimum interruption. No nested modals. Use native `<dialog>` with `.showModal()`. Focus trapping is automatic — do NOT add manual focus trap JS.
+
+4. **Feedback**: Every action gets feedback. Save -> toast. Delete -> toast with undo. Error -> inline alert. Silence after action = bug.
+
+5. **Forms**: Validate on blur first, then keystroke after error shown. Specific error messages ("Email must include @" not "Invalid input"). Never reload page on error.
+
+6. **Empty States**: Every list/table needs an empty state with explanation + CTA. Never just "No items found."
+
+7. **Buttons**: Specific labels only. Never "Submit" / "OK" / "Yes" / "Click Here". One primary CTA per viewport. Destructive = `data-variant="danger"`, always last.
+
+8. **Loading**: Feedback after 300ms. Skeleton for page loads, spinner for actions. Never blank screen.
+
+9. **Responsive**: Modal -> bottom sheet on mobile. Table -> stacked rows. 44px minimum touch targets.
+
+10. **Keyboard**: Every mouse interaction works via keyboard. Never remove focus outlines. Escape closes overlays.
+
+11. **Tables**: Row actions consistent across all tables. `.table-wrap` wrapper required. `data-responsive` + `td[data-label]` for mobile.
+
+12. **Consistency**: After ANY pattern implementation, search the entire project for other instances and update them to match.
+
+## When to Read the Full Spec
+
+| Task | Read Sections |
+|------|--------------|
+| Building modal/dialog | Sections 1, 3, 12 |
+| Building form | Sections 5, 9, 12 |
+| Adding action buttons | Sections 1, 2, 9 |
+| Building table with actions | Sections 2, 13, 11 |
+| Search or filters | Sections 14, 7 |
+| Starting new project | Section 17 first |
+| Full UX audit | Entire spec |

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@fluid-theme/core",
+  "version": "0.4.3",
+  "description": "A modern, semantic CSS design system built on physics principles — not utility classes",
+  "main": "dist/fluid.min.css",
+  "style": "dist/fluid.min.css",
+  "exports": {
+    ".": "./dist/fluid.min.css",
+    "./src": "./src/fluid.css"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "fluid-agent-kit/",
+    "CLAUDE.md",
+    "AGENTS.md",
+    "GEMINI.md",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "serve": "npx http-server . -o /index.html",
+    "build": "node scripts/build-css.mjs",
+    "prepublishOnly": "npm run build",
+    "optimize-images": "node scripts/optimize-images.js",
+    "test": "echo \"Visual testing only - open examples/foundation.html in browser\""
+  },
+  "keywords": [
+    "css",
+    "design-system",
+    "theme",
+    "framework",
+    "semantic",
+    "css-layers",
+    "custom-properties",
+    "logical-properties",
+    "oklch",
+    "no-build"
+  ],
+  "author": "Neil White <dev+packages@agilemedia.agency>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Agile-Media-Agency/the-fluid-theme.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Agile-Media-Agency/the-fluid-theme/issues"
+  },
+  "homepage": "https://thefluidtheme.com",
+  "engines": {
+    "browsers": [
+      "last 2 Chrome versions",
+      "last 2 Firefox versions",
+      "last 2 Safari versions",
+      "last 2 Edge versions"
+    ]
+  },
+  "browserslist": [
+    "supports css-cascade-layers",
+    "supports css-container-queries",
+    "supports css-logical-properties"
+  ],
+  "devDependencies": {
+    "lightningcss": "^1.32.0",
+    "sharp": "^0.34.5"
+  }
+}

package/src/animations/scroll-reveal.css

@@ -0,0 +1,224 @@
+/**
+ * Scroll Reveal Animations
+ *
+ * Add [data-reveal] attribute to elements you want to animate in on scroll.
+ * Works with the scroll-reveal.js script or CSS-only with animation-timeline.
+ *
+ * Variants:
+ *   data-reveal="fade"      - Fade in
+ *   data-reveal="fade-up"   - Fade in from below
+ *   data-reveal="fade-down" - Fade in from above
+ *   data-reveal="fade-left" - Fade in from right
+ *   data-reveal="fade-right"- Fade in from left
+ *   data-reveal="scale"     - Scale up
+ *   data-reveal="blur"      - Blur to focus
+ *
+ * Timing:
+ *   data-reveal-delay="100" - Delay in ms (100, 200, 300, 400, 500)
+ *   data-reveal-duration="slow" - Duration (fast, normal, slow)
+ */
+
+@layer components {
+  /* Base reveal state - hidden by default */
+  [data-reveal] {
+    opacity: 0;
+    transition:
+      opacity var(--reveal-duration, var(--duration-slow)) var(--reveal-easing, cubic-bezier(0.16, 1, 0.3, 1)),
+      transform var(--reveal-duration, var(--duration-slow)) var(--reveal-easing, cubic-bezier(0.16, 1, 0.3, 1)),
+      filter var(--reveal-duration, var(--duration-slow)) var(--reveal-easing, cubic-bezier(0.16, 1, 0.3, 1));
+    will-change: opacity, transform;
+  }
+
+  /* Revealed state */
+  [data-reveal].revealed,
+  [data-reveal][data-revealed] {
+    opacity: 1;
+    transform: none;
+    filter: none;
+  }
+
+  /* Fade variants - starting positions */
+  [data-reveal="fade-up"] {
+    transform: translateY(2rem);
+  }
+
+  [data-reveal="fade-down"] {
+    transform: translateY(-2rem);
+  }
+
+  [data-reveal="fade-left"] {
+    transform: translateX(2rem);
+  }
+
+  [data-reveal="fade-right"] {
+    transform: translateX(-2rem);
+  }
+
+  [data-reveal="scale"] {
+    transform: scale(0.95);
+  }
+
+  [data-reveal="blur"] {
+    filter: blur(8px);
+  }
+
+  /* Delays */
+  [data-reveal-delay="100"] { transition-delay: 100ms; }
+  [data-reveal-delay="200"] { transition-delay: 200ms; }
+  [data-reveal-delay="300"] { transition-delay: 300ms; }
+  [data-reveal-delay="400"] { transition-delay: 400ms; }
+  [data-reveal-delay="500"] { transition-delay: 500ms; }
+
+  /* Durations */
+  [data-reveal-duration="fast"] { --reveal-duration: var(--duration-fast); }
+  [data-reveal-duration="normal"] { --reveal-duration: var(--duration-slow); }
+  [data-reveal-duration="slow"] { --reveal-duration: var(--duration-slower); }
+
+  /* Stagger children - useful for grids and lists */
+  [data-reveal-stagger] > [data-reveal]:nth-child(1) { transition-delay: calc(var(--reveal-stagger, 100ms) * 0); }
+  [data-reveal-stagger] > [data-reveal]:nth-child(2) { transition-delay: calc(var(--reveal-stagger, 100ms) * 1); }
+  [data-reveal-stagger] > [data-reveal]:nth-child(3) { transition-delay: calc(var(--reveal-stagger, 100ms) * 2); }
+  [data-reveal-stagger] > [data-reveal]:nth-child(4) { transition-delay: calc(var(--reveal-stagger, 100ms) * 3); }
+  [data-reveal-stagger] > [data-reveal]:nth-child(5) { transition-delay: calc(var(--reveal-stagger, 100ms) * 4); }
+  [data-reveal-stagger] > [data-reveal]:nth-child(6) { transition-delay: calc(var(--reveal-stagger, 100ms) * 5); }
+  [data-reveal-stagger] > [data-reveal]:nth-child(7) { transition-delay: calc(var(--reveal-stagger, 100ms) * 6); }
+  [data-reveal-stagger] > [data-reveal]:nth-child(8) { transition-delay: calc(var(--reveal-stagger, 100ms) * 7); }
+
+  /* ========================================
+     AUTO-REVEAL BY MOTION STYLE
+     Sections auto-animate based on theme motion setting
+     ======================================== */
+
+  /* Still: No animations */
+  [data-motion="still"] [data-reveal] {
+    opacity: 1;
+    transform: none;
+    filter: none;
+    transition: none;
+  }
+
+  /* Serene: Very slow, gentle fade */
+  [data-motion="serene"] [data-reveal] {
+    --reveal-duration: var(--duration-slower);
+    --reveal-easing: cubic-bezier(0.25, 0.1, 0.25, 1);
+  }
+
+  [data-motion="serene"] .section:not([data-reveal]) {
+    opacity: 0;
+    transform: scale(1.02);
+    transition:
+      opacity var(--duration-slowest) cubic-bezier(0.25, 0.1, 0.25, 1),
+      transform var(--duration-slowest) cubic-bezier(0.25, 0.1, 0.25, 1);
+  }
+
+  [data-motion="serene"] .section:not([data-reveal]).revealed {
+    opacity: 1;
+    transform: none;
+  }
+
+  /* Stream: Gentle horizontal flow */
+  [data-motion="stream"] [data-reveal] {
+    --reveal-duration: var(--duration-slow);
+    --reveal-easing: cubic-bezier(0.22, 1, 0.36, 1);
+  }
+
+  [data-motion="stream"] .section:not([data-reveal]) {
+    opacity: 0;
+    transform: translateX(-1rem);
+    transition:
+      opacity var(--duration-slow) cubic-bezier(0.22, 1, 0.36, 1),
+      transform var(--duration-slow) cubic-bezier(0.22, 1, 0.36, 1);
+  }
+
+  [data-motion="stream"] .section:not([data-reveal]).revealed {
+    opacity: 1;
+    transform: none;
+  }
+
+  /* Flowing: Smooth ease-in-out, organic */
+  [data-motion="flowing"] [data-reveal] {
+    --reveal-duration: var(--duration-slow);
+    --reveal-easing: cubic-bezier(0.16, 1, 0.3, 1);
+  }
+
+  [data-motion="flowing"] .section:not([data-reveal]) {
+    opacity: 0;
+    transform: translateY(1.5rem);
+    transition:
+      opacity var(--duration-slow) cubic-bezier(0.16, 1, 0.3, 1),
+      transform var(--duration-slow) cubic-bezier(0.16, 1, 0.3, 1);
+  }
+
+  [data-motion="flowing"] .section:not([data-reveal]).revealed {
+    opacity: 1;
+    transform: none;
+  }
+
+  /* Cascade: Medium energy, waterfall effect */
+  [data-motion="cascade"] [data-reveal] {
+    --reveal-duration: var(--duration-normal);
+    --reveal-easing: cubic-bezier(0.34, 1.56, 0.64, 1);
+  }
+
+  [data-motion="cascade"] .section:not([data-reveal]) {
+    opacity: 0;
+    transform: translateY(2rem);
+    transition:
+      opacity var(--duration-normal) cubic-bezier(0.34, 1.56, 0.64, 1),
+      transform var(--duration-normal) cubic-bezier(0.34, 1.56, 0.64, 1);
+  }
+
+  [data-motion="cascade"] .section:not([data-reveal]).revealed {
+    opacity: 1;
+    transform: none;
+  }
+
+  /* Rapids: Fast, direct */
+  [data-motion="rapids"] [data-reveal] {
+    --reveal-duration: var(--duration-fast);
+    --reveal-easing: cubic-bezier(0.25, 0.46, 0.45, 0.94);
+  }
+
+  [data-motion="rapids"] .section:not([data-reveal]) {
+    opacity: 0;
+    transform: scale(0.98);
+    transition:
+      opacity var(--duration-fast) cubic-bezier(0.25, 0.46, 0.45, 0.94),
+      transform var(--duration-fast) cubic-bezier(0.25, 0.46, 0.45, 0.94);
+  }
+
+  [data-motion="rapids"] .section:not([data-reveal]).revealed {
+    opacity: 1;
+    transform: none;
+  }
+
+  /* Tsunami: Dramatic, bold sweep */
+  [data-motion="tsunami"] [data-reveal] {
+    --reveal-duration: var(--duration-normal);
+    --reveal-easing: cubic-bezier(0.68, -0.2, 0.32, 1.2);
+  }
+
+  [data-motion="tsunami"] .section:not([data-reveal]) {
+    opacity: 0;
+    transform: translateY(3rem) scale(0.97);
+    transition:
+      opacity var(--duration-normal) cubic-bezier(0.68, -0.2, 0.32, 1.2),
+      transform var(--duration-normal) cubic-bezier(0.68, -0.2, 0.32, 1.2);
+  }
+
+  [data-motion="tsunami"] .section:not([data-reveal]).revealed {
+    opacity: 1;
+    transform: none;
+  }
+
+  /* Reduced motion preference */
+  @media (prefers-reduced-motion: reduce) {
+    [data-reveal],
+    .section {
+      opacity: 1 !important;
+      transform: none !important;
+      filter: none !important;
+      transition: none !important;
+    }
+  }
+}