# Expressive forms

> The Everything Button did buttons. This one does the field: what it says
> while you type, how it tells you something's wrong, and what happens when
> you press send. Inputs first, then whole forms, and the subscribe form is
> where it ships.

**Part of:** [Ubiquitous elements](../UBIQUITOUS-ELEMENTS.md), a series on the
parts of an interface everyone uses and nobody looks at.

**Status:** the direction is the border (from the sketch, 2026-11-12). The lab
([`index.html`](index.html), `/lab/expressive-forms/`) opens on a playground
where the outline itself is the state, with two or three options for each:
typing (jiggle, ripple), loading (wave, spinner), error (jagged, pulse), and
success (sunburst, confetti, both). Below it, every option plays on a loop on
its own field. The earlier work, the ladder from plain to blow-up, emoji,
strokes, his face as an icon, and the underline, is kept as past exploration
in a closed section at the bottom. Emoji are out for the real form.

---

## The post

The joke, in your words (2026-11-12): there's only one input on the whole
site, and it's the subscribe field. So it gets all of this. It isn't a trick
to make people subscribe: anyone who wants to play with it gets the
[sandbox](sandbox.html), and "Open in CodePen" there hands them the whole
thing (the field, its CSS, the engine, and their settings). The field on the
site is just the nudge.

Checked before the post: it isn't literally the only input. The chat's
message field (`CustomChatUI.vue`) and the line you write in each Still
yourself session (`SessionReader.vue`, a textarea) are text fields too. The
library search is built but switched off (`v-if="false"`), and the filters are
radio buttons. So the honest version is "the only form on the site", or the
only place that asks for anything, or the chat gets named as the exception.

## How it's built

JavaScript, in [`border-field.js`](border-field.js), about 300 lines with no
libraries, shared by the lab and the sandbox. The outline is an SVG path
sampled every 2.5px round a rounded rectangle, and every frame each point is
pushed out along its normal by whatever the field is doing. CSS can't do this
on its own: it can animate a border's colour, width and radius, but not bend
the line. CSS does the colours, the icon, the shake and the pop. On the site
it would become one Vue component wrapping the same engine.

**CSS only** (2026-11-12): [`css-only.html`](css-only.html) and
[`border-field.css`](border-field.css), generated by `pnpm forms:css`
(`scripts/border-field-css.mjs`), with no script on the page. The shapes are
computed once and morphed with transitions on `d` (Chrome, Edge, Firefox;
Safari cross-fades). Typing and error come from the input (`:focus-within`,
`:placeholder-shown`, `:user-invalid`), and loading and sent from
`data-state` or `:target` after a plain submit. It can't follow the caret,
react to each key, or know when a send starts or ends.

**The npm package**, `@jacquesramphal/border-field` (0.1.0, not published).
It's worked on here and synced to `packages/border-field`, the same split as
Counter Fill: `pnpm forms:sync`, `pnpm forms:check`, and `pnpm forms:publish`
(add `--dry-run` to stop before publishing). It ships `border-field.js`, types,
`example.html` and `README.md`. `BorderField.enhance(form, { onSubmit })`
upgrades any real form and keeps its native validation; `create()` is the
engine on its own.

**Pens in one click**, the same way as CounterFill: presets live in
[`CODEPENS.md`](CODEPENS.md), and `pnpm forms:pens` builds
[`pens.html`](pens.html), one button per pen that opens CodePen with the
field, CSS, engine, and that pen's settings filled in. Sign in, Save, and put
the pen id back in `CODEPENS.md`. `--external` loads the engine from
ramphal.design instead, once the lab is deployed.

## The subscribe form first

It's the one form on the site people actually fill in, and it's on every page,
in the footer (`SubscribeForm.vue`, the field with the round arrow) and on the
home page (`NewsletterSubscription.vue`, field plus a Subscribe button). Both
share `src/utils/useSubscribe.js`, so one change reaches both.

What the code says today, and what it means for the design:

- **Success can't actually be known.** The post to Buttondown is `no-cors`, so
  the response is opaque and the form treats any send as delivered. The real
  confirmation happens later, in the inbox. So the celebration belongs to "it's
  on its way", not "you're in". 🎉 is a lie here; ✉️ isn't.
- **Validation only runs on submit**, with `/\S+@\S+\.\S+/`. Nothing happens
  while you type.
- **The error colour is a fallback.** The forms use `var(--color-error, red)`,
  and `--color-error` doesn't exist (the token is `--color-danger`), so errors
  render in browser red, not the palette's.
- **Success clears the field**, which is right, and the success line says
  "Almost there — check your inbox to confirm."

The subscribe version of everything below:

1. **An email has three parts, so the border draws in thirds.** A third when
   there's something before the @, two thirds with a domain, closed when
   there's a dot and an ending. Progress you can read without a word of text.
2. **The typo nudge on the domain.** "gmial.com" gets 🤔 and "Did you mean
   gmail.com?" with a tap to fix.
3. **The arrow leans in when the address is valid**, a few degrees toward
   send, the way Mailchimp's chimp finger hovers over the button (below).
4. **On send, the arrow becomes an envelope and leaves.** It flies up and out
   of the round button, and the line under the field says it's on its way and
   to check the inbox. A ✉️ settles into the button.
5. **The character carries it.** Where he's on the page, he takes the envelope
   and walks off the edge with it, and comes back empty-handed.
6. **Failure keeps the address**, says so, and the arrow comes back.

---

## Where the inputs are today

Read before building, because some of the hooks are already there.

- **`src/components/form/MyInput.vue`** is the field. Text, email, and
  password, a small size, and an optional round submit button with an up
  arrow inside the field (the chat and the newsletter use it).
- **The border is reserved but invisible.** Fields draw
  `var(--control-border-width) solid transparent` so they line up with
  buttons. That means the border can light up for a state without anything
  moving by a pixel.
- **The fill already means focus.** With a submit button, the whole field
  turns white on `:focus-within` (`--field-active`), and a tint of the page in
  dark mode.
- **Validation is stubbed and empty.** `form.scss` has
  `input:required:invalid { /* border-color: red; */ }` and an empty
  `:optional` rule. Nobody finished them.
- **`required` defaults to `true` on MyInput**, so every field is invalid the
  moment the page loads. Anything built on `:invalid` would shout before
  anyone has typed. Use `:user-invalid`, which waits until the person has
  touched the field.
- **The contact form gives no feedback at all.** `MyForm.vue` sends through
  emailjs with two empty handlers, `() => {}` for success and for failure, and
  an inline `alert('submit!')`. Whatever happens after send, the person can't
  tell. That's the first thing a deep dive fixes, delight or not.
- **TextArea and MySelect** have no states beyond the global focus outline.

**The emoji field was real, and it's in the history.** In April 2021
(`783baa2b`, "icons, contact form styles") every required field showed Font
Awesome's `smile-wink` on `:focus:valid` and `frown` on `:focus:invalid`. A
month later (`29ee4414`, "forms", May 2021) they became emoji images, the
thinking face and the wink, as background images at the right of the field,
with a smile on `:valid` once you'd left. The rules were commented out on Feb
22, 2026 when the chat field got its submit button (`f3ce7851`) and deleted
the same day in the token pass (`a1f4b0af`). The images are still in
`src/assets/images/emoji/`, and the lab's level 2 uses them.

---

## Four channels

A field has four places it can speak. (Reading the note as label, border,
fill, and text feedback.)

| Channel | What it's good for | Watch out for |
|---|---|---|
| **Label** | Naming the field, and a short status at the end of it ("Email ✅") | Changing the label's words changes what a screen reader announces |
| **Border** | State at a glance, and progress, since it can draw itself in | Colour alone fails WCAG 1.4.1, so pair it with text or a glyph |
| **Fill** | Focus (already taken), strength, how full the field is | Contrast of the typed text against every fill |
| **Text feedback** | The actual message: what's wrong, how to fix it | It's the only one that has to be there; the other three decorate it |

One rule to test against: **one state changes at most two channels.** Error
might be border plus text. Valid might be the label's emoji alone. If every
channel moves at once, nothing reads as the important one.

### States across the channels

A first pass to argue with.

| State | Label | Border | Fill | Text |
|---|---|---|---|---|
| Rest | plain | invisible | page tint | hint, if any |
| Focus | — | — | white (as now) | — |
| Typing | — | draws in as it nears valid | — | live count, if it matters |
| Valid | ✅ pops in | settles to ink | — | — |
| Almost | 🤔 | — | — | "Did you mean gmail.com?" |
| Invalid (after blur) | — | `--color-danger` | — | what to fix, in plain words |
| Checking | ⏳ | runs (marching line) | — | — |
| Sent | 🎉 | — | — | "Got it. I'll write back." |
| Failed to send | 😬 | `--color-danger` | — | "Didn't go through. Your message is still here." |
| Disabled | 💤 | dashed | flat | why it's off |

---

## Emoji as state

Emoji are the cheapest way to give a state a face. They're also the riskiest,
so a few rules come with them.

- **Where they sit.** At the end of the label is the quietest spot. Inside the
  field, on the right where the submit arrow lives, is louder. In the helper
  text, they lead the message.
- **A set to start from.** 👀 focused, ✍️ typing, ✅ valid, 🤔 almost, 😬
  invalid, ⏳ checking, 🎉 sent, 💤 disabled. Password gets 🙈 hidden and 🐵
  shown on the reveal toggle.
- **They change with a pop.** Scale from 0.6 to 1.1 to 1 over about 200 ms,
  so a swap looks like a reaction, not a redraw.
- **They never carry the meaning alone.** Mark the emoji `aria-hidden`, and
  put the words in an `aria-live="polite"` region tied to the field with
  `aria-describedby`.
- **They look different everywhere.** Apple, Google, and Windows draw ✅ three
  ways, and none of them in the site's palette. Options worth trying:
  `font-variant-emoji: text` for a monochrome glyph in the ink colour, the
  existing `Icon.vue` (which already renders a unicode character at a size),
  or small drawn glyphs in the character's style.
- **Mood instead of a number.** A message box with a minimum could show 😶
  when empty, 🙂 once it says something, 😄 at a good length, and 😅 when it's
  close to `maxlength`. The count is still there for anyone who wants it.

---

## Field validation

- **Reward early, correct late.** Show ✅ the moment a field becomes valid,
  but hold errors until blur. Once an error is showing, clear it live as soon
  as it's fixed, so the fix gets the reward.
- **The border draws in.** As an email or a message heads toward valid, the
  border traces around the field (an SVG stroke with `stroke-dashoffset`, or a
  `conic-gradient` mask), and closes when it's valid. The reserved transparent
  border is what makes this free.
- **The typo nudge.** "Did you mean gmail.com?" with 🤔, and a click accepts
  it. It's the most useful item on this list.
- **A head shake on a bad submit.** Three or four pixels, side to side, twice.
  It's literally a person saying no. None at all under
  `prefers-reduced-motion`.
- **The label becomes the error.** "Email" turns into "Email needs an @" in
  place, so the eye doesn't have to travel to a message below.
- **Caret colour follows state** (`caret-color`). Nobody will notice
  consciously, and that's why it's nice.
- **Autofill gets a thank you.** "✨ filled in for you" for a second when the
  browser fills a field. MyInput already detects autofill to hide Chrome's
  blue, so the hook exists.
- **Paste gets a nod.** 📋 in the label for a moment.
- **The name field says hi back.** After blur, the hint becomes "Hi, Jacques
  👋". Uses only what they just typed.
- **Password strength fills the field** from the left, behind the text, and
  the 🙈 / 🐵 toggle sits where the submit arrow would.
- **Risky, probably not.** A 💤 on a field that's been abandoned halfway. It
  could read as nagging. Worth one prototype to find out.

---

## Submit animations

- **The arrow launches.** The up arrow in the round button flies up and out,
  and a ✅ drops back in where it was. The button already exists in the chat
  and the newsletter.
- **The field folds into the button.** On send, the field shrinks into the
  round button, the button turns into a ✅, then the field opens again with
  "You're in 🎉".
- **The border is the loader.** While it sends, a line runs around the field's
  border at `--line-drawn` instead of a spinner. Same channel as validation,
  so the field has one language.
- **Confetti, small and local.** A handful of pieces from the button, not the
  whole screen, and only for the first send. A second subscribe gets a quieter
  ✅.
- **Failure keeps the words.** Never clear what someone typed when it fails.
  😬, the message, a retry, and the text still in the box.
- **The contact form folds into a paper plane** and flies off the edge. Fun
  once, so it's the contact form's and nothing else's.

---

## The character

The character from #665 already stands on the ink of headlines, walks, jumps,
sits, and dances. A field has a top border, which is a ledge.

- **He stands on the field** like he stands on a headline, and sits on it
  when nothing's happening.
- **He watches you type.** His `facing` follows the caret left and right.
- **Valid gets a hop**, the send gets the dance.
- **Invalid gets a shrug**, or he points down at the field. Never in the way
  of the error text.
- **On send he picks up the message and walks off the edge with it**, the same
  walk-off as the Nov 11 GIF, then comes back empty-handed.
- **Password: he covers his eyes.** Darin Senneff's yeti login did this, and
  it's been rebuilt so many times it belongs to the yeti now (see below).
  Leave it.

He's opt-in. The field works the same with him gone.

---

## The distraction test

doc_92 asks whether the character is a distraction. In a form the question has
teeth, because someone is trying to finish something. A first draft of the
test each idea has to pass:

1. It never delays the task. No animation blocks typing or submitting.
2. It never hides state. The text message is always there; delight decorates
   it.
3. Nothing moves the field or shifts the layout.
4. It respects `prefers-reduced-motion`, and the reduced version is still
   complete.
5. It happens once, or rarely. The fifth confetti isn't a reward.

Running the list above through it is part of the deep dive.

---

## What others have done

Read before building, so nothing here turns out to be someone else's idea
with the serial numbers filed off.

**A character in the form**

- **Darin Senneff's yeti login.** The reference for a form with a face. The
  yeti's head follows the text as you type an email, and it covers its eyes
  with its hands when you check "show password". It's been rebuilt in plain
  CSS, Lottie, Webflow, and as a Bubble plugin, which tells you how far it
  travelled. Take: a character's attention can follow the caret. Leave: the
  eye-covering, which is his.
- **Mailchimp's Freddie.** Before you send a campaign, the chimp's hand hovers
  over the big red button, sweating. After, you get a high five. Click the high
  five again and the hand gets redder, and eventually it launches you into a
  game, Fast Fives. Their style guide says Freddie smiles, winks, and high
  fives, and never talks. Take: the nerves before send and the reward after,
  and a character who doesn't speak. Leave: the game.

**Fields that move**

- **Codrops, Inspiration for Text Input Effects (Manoela Ilic, 2015, and a
  second set).** A gallery of label and border effects built from CSS
  transitions and pseudo-elements; one is based on Andrej Radisic's
  "Jawbreaker" field on Dribbble. MIT licensed. The best catalogue of what a
  label and a border can do, and also the reason not to spend the series on
  label animations alone: it's been done thoroughly.
- **Tilting validation** (a DEV post and CodePen): an invalid field rotates a
  few degrees while you're in it. Funny, and it's the head-shake idea held
  still.
- **The validation shake.** Common enough to be a snippet: shake the bad input,
  give the good one a quieter border. The quiet border for good is the half
  worth keeping.
- **Rauno Freiberg, Invisible Details of Interaction Design (2023).** Timing,
  physics, and predictable gestures, and how they make an interface feel like
  part of you. The other end from confetti, and the standard for the details
  here.
- **Josh W. Comeau** on whimsy, whose like button has animation and sound. His
  line that whimsy can be a confetti explosion, but can also just be thoughtful
  interactions and smooth, organic animation, is the range this series wants.

**Subscribe forms**

- A button that bounces on submit (CodyHouse), a mailbox animation on success
  (Colorlib), a Subscribe button that opens into the field (Framer), and a
  gift box that jumps to catch the eye (Marketing Examples). Mostly templates.
  None of them is honest about not knowing whether it worked, which is the
  opening here.

**The opposite**

- **r/badUIbattles**, which grew out of a 2017 challenge to make the worst
  volume slider. The most popular theme is terrible ways to enter personal
  details, like a slider that scrolls through every possible phone number.
  It's the same instinct pointed the other way: their delight is the
  frustration. Useful as a check. If an idea here would get upvotes there, it
  fails the distraction test.

Not read yet, because the session's network blocked the sites: jh3y's "Add a
little whimsy to your forms" (DEV), the tilting-validation post itself, Rauno's
essay in full, and The Next Web's piece on the chimp finger. Worth a read
before the deep dive.

---

## Build notes

- Start as a self-contained page in `public/lab/expressive-forms/` (plain
  HTML, CSS, JS, no imports from `src/`), the same way as the Everything
  Button. Add a `type: "lab"` entry in `library.json` with
  `published: false` when there's something to see.
- The lab is the first prototype: levels 0 to 7 from plain to blowing up,
  then levels 3, 4 and 5 together, with and without the character. Nothing
  sends; tick "make sends fail" to see failure. The character's markup is
  copied from `FullBodyCharacter.vue`, so copy it again if the drawing
  changes.
- What survives moves into MyInput as props (`state`, `message`), fills the
  empty stubs in `form.scss`, and gives `MyForm.vue` real success and failure
  states.
- `aria-invalid`, `aria-describedby`, and one polite live region per form.

---

## Open questions for the deep dive

- Native emoji, monochrome glyphs, or drawn ones?
- How far does the character go: one field on one page, or every form?
- The footer form, the home band, or both at once? They share one composable.
- Where are the old emoji forms, and what did they get right?
