userinterface-wiki is a living manual for interface design, written as a Next.js site

A wiki about interfaces, not a component library

userinterface-wiki describes itself as a living manual for better interfaces, and the README states the premise directly: knowledge should be shared.

The content is described as a collection of articles, patterns and best practices for designing and building user interfaces, in a wiki that evolves with the field, incorporating new insights and techniques as they emerge, all for free.

The distinction from a component library matters, because they solve different problems and fail differently. A design system ships code you install and depend on, and its cost is version skew and an API you cannot change. This project ships knowledge and examples, and its cost is that nothing here is a dependency you can add to your project. There is no npm package to adopt, which also means there is no upgrade path to plan for.

The audience is therefore people who want to understand interface decisions. A developer who has heard that a certain pattern is better than another and wants to know why, or a designer who wants to point at a specific article. The homepage is userinterface.wiki, and the site is the product; the repository is how that site is built and how content gets into it.

The project is MIT licensed with a license.md at the root, and the repository is not archived, with the last push on 2026-07-29.

Articles are MDX files in content/, each with an index.mdx

The writing model is the part of the README that tells you how to contribute, and it is short.

Articles live in content/ as MDX files. Each article has its own folder with an index.mdx and an optional demos/ folder for interactive examples. So the unit of content is a directory per article, and the interactive example is a sibling of the article rather than something hosted elsewhere.

The site is built with Fumadocs, which the README describes as a framework for creating documentation sites using Next.js and MDX. The repository confirms the stack in its layout: next.config.mjs, mdx-components.tsx, source.config.ts, app/, components/, content/, lib/, styles/ and a .source/ directory, which is where Fumadocs writes the generated content index.

The scripts show how the pieces are wired together in development.

"dev": "concurrently \"pnpm:dev:*\" --prefix-colors \"cyan,magenta\"",
"dev:next": "next dev",
"dev:playgrounds": "pnpm generate playgrounds --watch",
"dev:demos": "pnpm generate demos --watch"

One process runs the Next.js dev server and, in parallel, two watchers that regenerate playgrounds and demos as files change. That is why the content lives in MDX rather than in a CMS: the demos are code in the repository, and the site compiles them the same way it compiles everything else.

The contribution rule is stated plainly. If you would like to contribute an article, open a pull request with your content, and the maintainer says he is happy to review and merge contributions that align with the goals of the wiki.

Base UI supplies the components, with a stated opinion about it

The README names Base UI as the basis for most if not all components, and then adds a personal judgement: in the author's opinion it is the best design system for building modern web applications with React.

The manifest backs the claim structurally. @base-ui/react is pinned at version 1.2.0, and it sits alongside @radix-ui/colors, @floating-ui/react and clsx rather than replacing them, so the site composes unstyled primitives with its own styling layer in styles/.

That choice has a consequence for anyone reading the code. Because the components are unstyled and headless, the visual result on the site is the author's own work, which is exactly what you want in a wiki about interface design: the examples demonstrate taste rather than a vendor's default look. It also means the code you copy from the articles is Base UI code, so adopting a pattern means adopting that dependency in your own project.

The other components are chosen for specific jobs rather than for a house style. @codesandbox/sandpack-react and html-to-image point at code playgrounds and image export. @react-three/fiber and @react-three/drei mean there are 3D scenes on the site, which for an interface wiki is a strong signal that spatial interaction is treated as a topic rather than a curiosity. @tanstack/react-query and @tanstack/react-db handle data, and chroma-js with color-hash and calligraph handle colour work, while fuse.js provides the client side search.

The site also installs @vercel/analytics, @vercel/speed-insights and @vercel/blob, and the presence of blob storage suggests that generated assets are stored rather than committed.

The build runs four generators before next build

The production build script is the clearest description of the site's pipeline.

"build": "pnpm generate icons opengraph playgrounds demos && next build",
"build:icons": "pnpm generate icons",
"build:opengraph": "pnpm generate opengraph",
"build:playgrounds": "pnpm generate playgrounds",
"build:demos": "pnpm generate demos",
"generate": "tsx scripts/generate.ts"

Four generators run before the Next.js build, and all of them are variations on the same entry point, a script at scripts/generate.ts executed with tsx. Icons and Open Graph images are generated, then playgrounds and demos are generated.

The ordering matters for a reader who wants to contribute an article with an interactive example. The demos folder is not a place where you drop a file and expect it to render. Something has to turn that folder into the artifact the page loads, and the generator does that. The README does not document the input format for those generators, so that is a question for the maintainer or for the source.

Other parts of the pipeline are conventional. The lint script is biome check --fix --unsafe ., which applies fixes automatically including the unsafe ones, and there is a biome.json configuration. Husky is installed in a prepare script for git hooks, and postinstall runs fumadocs-mdx, which generates the content index the app reads from the .source/ directory. That postinstall step matters for anyone forking the project, because without it the site has no source index to build against.

Voiceovers are transcribed with Eleven Labs, and the API limits shape contributions

Every article is narrated. The README states that articles are transcribed using Eleven Labs, described as a text-to-speech service that produces natural-sounding voiceovers, and the dependency list includes @elevenlabs/elevenlabs-js.

That choice has an operational consequence that the README is unusually direct about. It repeats the point in the writing section: due to API limitations, if you wish to transcribe new or updated articles, please reach out to the maintainer directly, who will be happy to assist with the transcription process.

So the pipeline for a contributed article has a manual gate in it. You can write the MDX and the demos and open a pull request, but the narrated version of your article depends on the author spending an API key on it. That is a real constraint on the throughput of contributions and it also means the narration is not fully automated for anyone.

The narrated format is also an accessibility and consumption decision rather than a novelty. A wiki about interfaces that ships an audio version of each article treats listening as a first-class way to read, which is unusual for a documentation site and consistent with the project's audience of people who want to understand something.

The repository also holds a skills/ directory, which is a convention used by some agent assisted workflows, and an AGENTS.md file at the root, so there is guidance for tooling and for automated contributors alongside the human one.

Feedback goes through issues, and the project credits one early reader

The README separates the two ways to help. If you have feedback, suggestions for new articles, or improvements to existing content or the website, open an issue. If you want to contribute an article, open a pull request with your content.

That split is sensible for a wiki, since a suggestion for a topic is not the same artefact as a finished article, and it keeps the issue tracker for the roadmap rather than for drafts.

The Credits section is short. It thanks Jace, with a link to a profile, for early feedback and encouragement to start the project. That single credit line tells you something about the shape of the project: it began as one person's idea, it was encouraged by someone else, and the maintenance is currently one person's review queue.

That is the honest limitation to weigh. The maintainer states plainly that contributions that align with the goals of the wiki will be reviewed and merged, which is an invitation, but there is no stated review turnaround, no second maintainer and no code of conduct or governance file visible in the repository listing. The repository does contain .github/, .husky/ and .vscode/ directories, and scripts and skills folders, so there is tooling around contributions even if the decision making is not distributed.

There are no GitHub releases either, which for a documentation site matters less than it would for a library, but it does mean there is no version to point at when you want to say which version of the wiki you read.

Editorial conclusion

userinterface-wiki suits a designer or front-end engineer who wants written interface guidance with runnable examples rather than a component package to install, and the MDX plus demos structure makes the examples part of the article rather than a separate sandbox. It does not suit a team looking for a production design system to depend on, since nothing here is published as a library, and it does not suit anyone who needs to add narrated content without waiting on the maintainer. Before contributing, read the writing section of the README, because articles are MDX files under content/ with an index.mdx and an optional demos/ folder, and remember that transcription goes through Eleven Labs and therefore through the author.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. raphaelsalaja/userinterface-wiki on GitHub
5. README