Perfect Imperfect

How it works

Perfect Imperfect treats imperfection as a decision, not an accident. Each one is chosen, given a stable key, computed once at build time and painted by the browser. Nothing is random on a visit, nothing waits for JavaScript, and nothing moves once the page has loaded.

The mechanics

Seed, then paint

  1. Key. Every imperfection has a stable string: a slug, a component name, an index.
  2. Hash. The string goes through FNV-1a, a small deterministic hash. The output picks a tilt step, a sign, a variant or a font axis.
  3. Apply. The value becomes a CSS custom property or a class. Tilt sits on a decorative sheet or a paper plate, never on the text.
  4. Paint. The browser draws it. No script runs, no image loads, no layout changes after load.
import { tiltDeg, headingAxesCss } from '@hardik88t/imperfect/seed';

// Same key in, same numbers out. Nothing random, nothing at runtime.
const tilt = tiltDeg('card:pricing');       // a fixed value such as -0.8 (degrees)
const axes = headingAxesCss('card-title');  // '"SOFT" 40, "WONK" 0'

The helper is in the package (seed.js). It has types (seed.d.ts) and no dependencies.

Why it costs nothing

The rule is simple: an imperfection is allowed only if it passes every check below. Each one is measurable, so the claim is a test, not a feeling.

  1. No layout shift (CLS 0). Transforms, paint and absolutely positioned SVG only. Space is reserved before anything paints. How to check: Measure layout-shift entries during load, scroll and any view change. The total is 0.
  2. No contrast loss. Pink and gold are never text colours. Text on a highlight uses the on-highlight ink. Every ratio is printed on the tokens page. How to check: Run the ratio table. Every text pair passes AA.
  3. No JavaScript. Seeds run at build time. The only script is the theme toggle and dialogs, and the page reads fine without them. How to check: Load the page with JavaScript off. Everything is readable and in place.
  4. Works with reduced motion. The print settle and the hover nudges are transitions or animations that switch off under prefers-reduced-motion. How to check: Turn on reduce motion in the OS. Nothing moves.
  5. Keyboard and screen readers unaffected. Decoration is aria-hidden. A struck word is aria-hidden and only its correction is read. Focus rings are straight. How to check: Tab through the page. Read it with a screen reader. The order and names are the same as without the decoration.
  6. No change to the hit target. Imperfection never changes the size or position of a control. Hit targets are at least 44px. How to check: Measure the bounding box of each control before and after its imperfection is applied. They match.

Where the imperfection never goes

Always straight

Some parts of an interface are a promise to the person using it. They stay perfect:

  • Actions: buttons, links that look like buttons, and the primary call to action.
  • Focus: every focus ring is a straight 3px line with a 3px gap.
  • Forms and fields, and their labels and errors.
  • Navigation and the page's own structure: headings, lists, landmarks.
  • Dialogs, and their close buttons.
  • Content: text is never rotated, and the numbers and dates are plain.

Decoration is everything else, and it is aria-hidden where it carries no meaning.

The psychology, briefly

Two ideas

The isolation effect (Von Restorff). In the older memory research, an item that differs from its surroundings is more likely to be remembered. The system uses this by keeping one solid, straight element per screen: the one a person should press.

The pratfall effect. A competent person who makes a small, honest mistake can seem more likeable than one who never does. Kintsugi, the gold repair, is the picture of that idea. Replications of this effect are mixed, and it depends on context, so treat it as a design hypothesis rather than a result.

Neither idea is a reason to add imperfection. The checklist decides that. The ideas only explain why a human touch can help when it is kept small.

The budget

Calm by default

At most about three noticeable imperfections per viewport. Edit corrections, prints, hand marks and a hairline that stops short all count. More than that is noise, and the straight parts stop standing out.

Read the rules for the do and don't list, or see the components for each one in use.