Perfect Imperfect

A design system where every imperfection is deliberate, seeded at build time, and free. Perfection is reserved for what matters: actions, focus, forms, navigation, dialogs and content stay straight.

Showcase and docs: https://hardik88t.github.io/imperfect/

How it works

Each imperfection comes from a stable string (a slug or an index), computed at build time with a small hash, and painted by the browser with transforms, paint and inline SVG. Nothing is random on a visit, nothing waits for JavaScript, and nothing moves after load. An imperfection is allowed only if it passes the free checklist: no layout shift, no contrast loss, no JavaScript, reduced motion respected, keyboard and screen readers unaffected, no change to the hit target.

Quick start

Copy the CSS, or install from GitHub:

pnpm add github:hardik88t/imperfect

The package is in packages/imperfect. Link fonts.css, tokens.css and imperfect.css in that order. The Use it page has a minimal HTML example and how to seed your own strings.

Repository layout

• packages/imperfect/: the CSS package, @hardik88t/imperfect 0.1.0. Not published to npm.
  • tokens.css: inks, type stacks, spacing, tilt, nudge, wobble, light and dark.
  • imperfect.css: the utilities and components.
  • fonts.css and fonts/: the self-hosted, subset variable fonts (Fraunces, Recursive) and their OFL licences.
  • seed.js and seed.d.ts: the deterministic seed helper.
• site/: the Astro 5 static site (TypeScript, no UI framework). Pages: home, how it works, tokens, components, rules, use it. It imports the package from the workspace.
• .github/workflows/deploy.yml: builds site/dist and deploys it to GitHub Pages.

Development

Requires Node 22 and pnpm 10.28.0.

pnpm install
pnpm dev      # http://127.0.0.1:4321/imperfect/
pnpm build    # type check and static build to site/dist
pnpm check    # type check only

Licence

The code and the documentation are MIT, see LICENSE. Copyright (c) 2026 Hardik Thanth.

The fonts are licensed under the SIL Open Font License 1.1. The licence texts are in packages/imperfect/fonts/OFL-Fraunces.txt and packages/imperfect/fonts/OFL-Recursive.txt.