Your AI tool builds the app.
Formic makes sure it looks yours.
One command, then just prompt.
Opinionated where it matters
Five rules do most of the work. Every component follows them.
New component every week
The system grows with your product. Every week a new component ships, tested across light, dark, and all palettes, with AA contrast and the gates already passing.
Tokens only
No hardcoded colors, sizes, radii, shadows, or easings. Every component reads CSS variables, so themes and palettes come for free.
WCAG AA, everywhere
Every text and UI pair is contrast-checked across light, dark, and all five palettes, automatically, on every change.
One type ramp
Twelve integer steps on a 14px base, set in Urbanist. Medium is the working weight; semibold is the ceiling; bold never appears.
Nothing on a screen
without a reason.
Quick start
One command, then your first prompt. The same command for a new project and an existing one; needs Node 20 or newer. The core is MIT and stays that way.
-
Install and run
In the terminal, run
npx formicai init --new my-app, thencd my-app && npm run dev; it scaffolds the app and the browser opens a page that says Formic is working.From the root of your Tailwind v4 app, run the command below. It does all of this for you and never overwrites your own files;
npx formicai add <name>then adds one component and only what it needs,npx formicai doctorchecks the setup, andnpx formicai updaterefreshes Formic while keeping your edits:- puts the system into
src/formic/: styles, the scripts behind the config and the two gates, and the base components; your AI tool adds each component as it needs it withnpx formicai add <name>(or through the Formic MCP server the installer registers), and--allinstalls every one up front - writes
src/formic/formic.config.jsonand applies it: accent, palette, radius, rail - adds the three CSS imports to your global stylesheet and installs the icon and avatar packages
- writes the rules your AI tool reads:
AGENTS.md,CLAUDE.md,.cursor/rules/,.github/copilot-instructions.md,.claude/skills/ - adds
npm run formicand a pre-commit hook so the gates run before every commit
Terminal · inside your project foldernpx formicai init && npm run dev
The one thing it may ask of you: if it cannot find your global stylesheet, it says so, and you add these three lines yourself, in this order.
src/index.css · only if the installer asks@import "./formic/styles/fonts.css"; @import "tailwindcss"; @import "./formic/styles/formic.css";
- puts the system into
-
Point your AI tool at that folder and paste a test prompt
In the same terminal type
claude, or open that folder in Cursor or VS Code. The page it opened holds three test prompts, each a different screen; open one here to read it, pick the one closest to your product. What it builds is what Formic looks like.Test prompt 1: Studio dashboardFigures, two charts and a table; the classic first screen
Use Formic (src/formic), read AGENTS.md, then replace the welcome page (App.tsx is yours to change; keep main.tsx and CustomizeNudge.tsx as they are) with Formic Studio's dashboard, composed the way AGENTS.md (Composition intelligence, Dashboard) says: an AppShell with the rail from the config; a page header with a caption whose actions hold a segmented Tabs time range (7 days, 30 days, 90 days) that changes every figure and chart below, plus two buttons (Export, New report; the label is the verb only, the icon goes in the `icon` prop, `icon="download"` and `icon="plus"`, never as a word in the label); no filter row under the header; four StatCards in one row built like the gallery's headline tiles: `display={<CountUp value={…} />}`, a delta with its tone, an icon (one tile `iconTone="accent"`, the rest neutral) and a `trend` sparkline with `trendSmooth` and `trendAnimate`; then a two-thirds Panel holding a LineChart of revenue by month (`guides`, two series where one has values below zero, a ChartLegend) beside a one-third Panel holding a DonutChart of revenue by city with `segments` (name, value, detail with the client count) and a `format` for ETB, the leading city named in the centre until another is hovered or focused from the legend rows under the ring (not `legend="list"`, no Gauge); then a recent invoices DataTable on its own, filling the full width, built like the gallery's Invoices table: a toolbar with a page-size Select, the one accent action (New invoice), and at the right end the search Input and a status Select (all, paid, due, overdue) that filters the rows; columns with widths (id 120px muted, status 110px as a StatusCell, client as a PersonCell with the contact and the company, amount `align: "end"` tabular, date muted) so only the client column stretches and rows stay one line high; selectable rows with the mixed header box, RowActions per row, and the paged footer. The theme switch beside the profile flips and the rail collapses. Everything must work, not look like it works. Use the demo data the components ship (Formic Studio, ETB); no empty states, no placeholders. Everything you need is in src/formic and AGENTS.md; do not fetch formicai.dev. Only the base is installed: every component this prompt names that is not yet in src/formic/components, add with npx formicai add followed by its name (npx formicai add --list shows the names); never write a stand-in.Test prompt 2: Course registrationA stepper form with a header image and a confirmation
Use Formic (src/formic), read AGENTS.md, then replace the welcome page (App.tsx is yours to change; keep main.tsx and CustomizeNudge.tsx as they are) with a course registration page for a student, composed the way AGENTS.md (Composition intelligence, App shell) says: it stands alone, so an AppShell with `rail="none"`, the title Course registration and the caption for the term; the content one centred column (`max-w-3xl`); at the top a Card whose CardMedia is a header image (`src="https://formicai.dev/assets/live-bg-1280.webp"` with `aspect="banner"`, the short 4:1 band, not the tall video shape) with a CardTitle for the programme and a CardDescription for the dates; under it a Panel holding a Steps stepper with four steps (Student, Courses, Schedule, Review) and the form of the current step: Student is Fields with Inputs for full name, email and phone and a Select for the programme, all required with real validation; Courses is a CardGroup of at least six course Cards (title, credits, seats left) each with a CardButton that toggles it chosen, at least one required; Schedule is a DatePicker for the start date and segmented Tabs for morning or evening; Review lists every answer and ends with a Register accent button; Back and Next move between steps and the completed steps in the stepper can be clicked to go back; Register shows a Toast and turns the panel into a confirmation: a success Alert with the student's name and the chosen courses, and one secondary button (Register another) that resets the stepper. No table on this page. The theme switch at the right of the header strip flips. Everything must work, not look like it works. Use the demo data the components ship (Formic Studio, ETB); no empty states, no placeholders. Everything you need is in src/formic and AGENTS.md; do not fetch formicai.dev. Only the base is installed: every component this prompt names that is not yet in src/formic/components, add with npx formicai add followed by its name (npx formicai add --list shows the names); never write a stand-in.
Test prompt 3: Workspace settingsSettings under a top bar: forms, a team list, an integrations gallery and a danger zone
Use Formic (src/formic), read AGENTS.md, then replace the welcome page (App.tsx is yours to change; keep main.tsx and CustomizeNudge.tsx as they are) with Formic Studio's workspace settings, composed the way AGENTS.md (Composition intelligence, App shell) says, in the Text register (no figures, no charts): an AppShell with `rail="topbar"` (the rail plus the TopBar with search, theme, notifications and the account menu), the page title Settings, and underline Tabs for Profile, Team, Integrations and Billing that switch the content. Profile: a Panel with Fields (Input for studio name and email, Textarea for the address, Select for the timezone, an Avatar with a Change photo button) and one accent Save button that shows a Toast. Team: a CardGroup with `orientation="inline"` listing six people with Avatar, name, role Badge and a DropdownMenu of actions, plus an Invite button that opens a Drawer with an email TagInput and a role Select. Integrations: the Visual register, a CardGroup of eight services each with its real BrandLogo from brand-logos.tsx (Slack, Google Drive, Notion, Figma, GitHub, Stripe, Asana, Dropbox), a one-line description, and a Switch that connects or disconnects it, with a FilterBar above (search and a connected-only toggle). Billing: the current plan as a Card with a Progress bar of seats used, a payment method row, and a danger zone at the bottom where Delete workspace is a destructive Button that opens a confirm Modal (type the name to enable Delete). Wire useCommandPalette so ⌘K opens a CommandPalette that jumps between the four tabs. The theme switch in the TopBar flips. Everything must work, not look like it works. Use the demo data the components ship (Formic Studio, ETB); no empty states, no placeholders. Everything you need is in src/formic and AGENTS.md; do not fetch formicai.dev. Only the base is installed: every component this prompt names that is not yet in src/formic/components, add with npx formicai add followed by its name (npx formicai add --list shows the names); never write a stand-in.
Every prompt after that starts the same way, then says what you want:
Every later promptUse Formic (src/formic), read AGENTS.md, then add your own prompt
After the first page
Your own look
Pick the accent, palette, font, radius and rail in the customizer, press Copy for your AI tool, paste it into the same chat. Every page follows. Skip it and the stock look ships.
Open the customizerBefore every commit
The check
Two gates refuse generic UI and screens without a reason. They run on every commit, or any time you ask. If they fail, paste the output to your AI tool and say fix every line.
npm run formic
In the project folder type claude and paste a test prompt. It finds the Formic rules on its own; nothing to set up.
Open the folder, switch the chat to Agent mode, paste a test prompt. The rules are already in the project.
Open the folder and paste a test prompt. Every tool that reads AGENTS.md is covered; if yours does not, paste that file into its rules once.
Drop the skill file into a chat and click Save skill. Agents that read skills can install the same one with npx skills add eyosiyasketema1/formic-design-system.
