npm package: @grxkun/formia
Description: Formia — One file. Design engine + motion layer. 11 themes, GSAP, Three.js, PWA. No build step.
Author: grxkun
Latest version: 1.0.0

<div align="center">

<img src="https://raw.githubusercontent.com/grxkun/formia/main/banner.svg" alt="Formia" width="100%">

<br/>

[![License: MIT](https://img.shields.io/badge/license-MIT-8fe05e?style=flat-square)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.0.0-8fe05e?style=flat-square)](package.json)
[![No build step](https://img.shields.io/badge/build%20step-none-8fe05e?style=flat-square)](#)
[![Zero dependencies](https://img.shields.io/badge/dependencies-zero-8fe05e?style=flat-square)](#)
[![GitHub Pages](https://img.shields.io/badge/demo-live-8fe05e?style=flat-square)](https://grxkun.github.io/formia/)

<br/>

**One file. Design engine + motion layer. Build differently.**

</div>

---

## The Problem

Every vibecoded site looks the same. Not because AI is bad at code — because AI has no taste.

Ask any AI to build a landing page and you get this, every time:

```
Purple gradient hero → Inter font → centered H1 → two equal CTAs
Three icon cards → testimonials → pricing table → footer
```

It's not wrong. It's just invisible. And invisible is worse than wrong.

**The vibecoder pain points:**

| What you get | What you wanted |
|---|---|
| `Inter` + violet gradient | A typeface with a point of view |
| `scale(1.05)` on hover | Motion that means something |
| Three equal-weight columns | Hierarchy that guides the eye |
| Screenshot placed on background | Product living inside the scene |
| One layout, every project | A perspective that's yours |

The top 1% of sites share one trait: **a single signature element** the rest don't have. A typeface pushed to 18vw. A product card that floats. A section that wipes in with clip-path. A background that reacts to the cursor.

None of that is hard to build. It's just never in the prompt.

**Formia encodes those decisions.** 11 design systems, each with its own typeface, palette, and motion signature. Drop one in and your site immediately reads like someone made a choice — because someone did.

---

**formia.css** — Layout primitives, design tokens, fluid type scale, motion utilities.  
**formia.js** — Everything else: scroll reveals, parallax, magnetic, cursor, counters, split text, 11 themes, accent system, dark/light mode, viewport preview, GSAP choreography, Three.js hero scene, PWA manager.

No build step. Zero config.

---

## Install

```bash
npm install formia
```

Or drop files directly into your project:

```html
<link rel="stylesheet" href="formia.css">

<!-- Motion only (no GSAP/Three.js needed) -->
<script src="formia.js" defer></script>

<!-- Full engine (themes, Three.js, GSAP) -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollTrigger.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script>
<script src="formia.js" defer></script>
```

---

## formia.css — Design Tokens

Override the tokens in your project:

```css
:root {
  --bg:     #0d0c0b;
  --fg:     #f0ede8;
  --accent: #d4a04a;
}
```

### Layout Primitives

```html
<!-- Stack — vertical rhythm -->
<div class="stack" data-gap="6">
  <h2>Title</h2>
  <p>Body</p>
</div>

<!-- Grid — responsive columns -->
<div class="grid" data-cols="3">
  <div class="card">...</div>
</div>

<!-- Cover — full viewport, centered -->
<section class="cover">
  <h1 class="h1">Hero</h1>
</section>
```

---

## Motion Attributes (data-*)

All features are driven by HTML `data-` attributes.

| Attribute | Effect |
|-----------|--------|
| `data-reveal` | Fade + translateY on scroll |
| `data-reveal="left"` | Slide from left |
| `data-reveal="right"` | Slide from right |
| `data-reveal="scale"` | Scale up from 95% |
| `data-reveal="clip"` | Clip-path wipe |
| `data-stagger` | Stagger children on reveal |
| `data-parallax="0.3"` | Parallax scroll (0–1 speed) |
| `data-magnetic` | Element follows cursor |
| `data-cursor` | Enable custom cursor |
| `data-counter` | Animate number from 0 to `data-value` |
| `data-split-text` | Split words/chars for animation |

```html
<h1 data-reveal="clip">Build differently.</h1>
<div data-stagger>
  <p>Animates</p>
  <p>With</p>
  <p>Stagger</p>
</div>
<div data-parallax="0.4">Background layer</div>
<button data-magnetic>Magnetic CTA</button>
```

---

## formia.js — Design Engine

Handles themes, accents, color mode, viewport preview, GSAP animations, Three.js scene, and PWA.

### JavaScript API

```js
// Apply a theme
FORMIA.applyTheme('cobalt');

// Change accent color
FORMIA.setAccent('#ff00ff');

// Toggle color mode
FORMIA.setColorMode('dark'); // 'light' | 'dark' | 'system'

// Viewport preview
FORMIA.setViewport('phone'); // 'phone' | 'tablet' | 'desktop'

// Read current state
console.log(FORMIA.currentTheme);
console.log(FORMIA.currentAccent);
```

### URL Theme Override

```
yoursite.html?theme=cobalt
yoursite.html?theme=terminal
```

### Available Themes

| ID | Font | Palette |
|----|------|---------|
| `earth` | Fraunces | limestone + lime |
| `amber` | Cormorant Garamond | black + gold |
| `terminal` | JetBrains Mono | black + green |
| `editorial` | Playfair Display | ivory + crimson |
| `cobalt` | Unbounded | dark + electric blue |
| `professional` | Libre Baskerville | white + navy |
| `kindergarten` | Fredoka | pastel + pink |
| `beach` | Pacifico | ocean + coral |
| `forest` | Fraunces | dark green + sage |
| `digital` | JetBrains Mono | CRT cyan + magenta |
| `manufacturing` | Bebas Neue | dark + amber |

### Studio Panel

Add these elements to your HTML to get the live theme studio:

```html
<button id="studio-btn"><span class="spip"></span>FORMA Studio</button>
<div id="studio"><!-- panel markup from index.html --></div>
```

Press **T** to toggle the studio panel from any page.

---

## Files

| File | Size | Purpose |
|------|------|---------|
| `formia.css` | ~8KB | Design tokens + layout primitives |
| `formia.js` | ~15KB | Design engine + motion layer (one file) |

---

## License

MIT © [grxkun](https://github.com/grxkun)