Installation
Take the design layer as a package and the components from the registry.
ziiz ships in two pieces because they change at different rates. The theme is one stylesheet that defines the ramp, the type roles, the materials and the prose layer. It is versioned, and an app takes updates by bumping a dependency. The components are source files that an app owns and edits. They come from a registry and never update on their own.
Quick start
Start from a shadcn project.
Skip this if components.json already exists. The Vega preset is the one ziiz components are built on.
npx shadcn@latest init --preset vegainit writes a stock theme block into app/globals.css. Delete everything below the imports except @custom-variant dark: the next step supplies the theme, and the stock block's own font and color variables would sit on top of it.
Point components.json at the registry.
The registry is served straight from the repository, so there is no deploy between a merge and an install.
{
"registries": {
"@ziiz": "https://raw.githubusercontent.com/nafisazizir/ziiz/main/apps/www/public/r/{name}.json"
}
}Add the theme.
npx shadcn@latest add @ziiz/theme --overwriteOne item does the setup. It installs the @nafisazizir/ziiz package, tw-animate-css and shadcn, adds their three imports to the Tailwind entry in the right order, and replaces lib/utils.ts with a cn that understands the type roles. --overwrite is what lets it replace that file; without the flag the CLI stops to ask.
Set the fonts.
The theme reads --font-sans and --font-mono from html or :root. With next/font that is the variable option; ziiz uses Inter with ss03 and Geist Mono. An app that sets neither gets Tailwind's default stacks, not a broken page.
const inter = Inter({ subsets: ["latin"], variable: "--font-sans" })
const mono = Geist_Mono({ subsets: ["latin"], variable: "--font-mono" })
<html className={`${inter.variable} ${mono.variable}`}>Set up dark mode.
Dark mode is the .dark class on html. With next-themes (npm install next-themes), that is attribute="class" on the provider, plus suppressHydrationWarning on html because the class is set before React hydrates. Without it, toggle the class yourself.
<html suppressHydrationWarning>
<body>
<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
{children}
</ThemeProvider>
</body>
</html>Add components.
Every item lists what it imports, so one command pulls in a component, the components it composes and the packages they need.
npx shadcn@latest add @ziiz/buttonAfter that, every Tailwind utility speaks the ramp (bg-gray-100, text-gray-1000, border-gray-alpha-400), the 31 type roles are single classes (text-heading-32, text-copy-16, text-label-13), the eight materials are too (material-menu, material-modal), and typeset sets prose. The stock Tailwind palette is disabled on purpose; only the ramp compiles.
Type roles are single utilities, so the stock cn does not know that
text-label-14 and text-copy-16 conflict. It keeps both, and stylesheet
order decides which one paints, so a className override on a component works
or fails by accident. @nafisazizir/ziiz/cn builds on the cn package with
the roles as one font-size group and the materials as another. The utils
item is a one-line re-export of it, and every component depends on it.
Manual setup
The theme item is a shortcut for four edits. Doing them by hand gives the same result.
Install the packages.
npm install @nafisazizir/ziiz tw-animate-css shadcntw-animate-css provides the enter and exit animations (animate-in, fade-in-0) that overlays use; shadcn/tailwind.css provides the data-open: and data-closed: variants and the accordion keyframes. Both are required, not optional.
Import the stylesheets, in this order.
@import "tailwindcss";
@import "tw-animate-css";
@import "shadcn/tailwind.css";
@import "@nafisazizir/ziiz/theme.css";Re-export cn.
export { cn } from "@nafisazizir/ziiz/cn"Fonts and dark mode, as above.
Add a fifth import, @nafisazizir/ziiz/shadcn.css. It maps shadcn's slot
names (bg-background, text-muted-foreground, border-input) onto the ramp
so components written against that vocabulary render on it unchanged. ziiz
components speak the ramp directly and do not need it.
Components
The registry publishes every component on this site plus the documentation primitives it is written with (callout, steps, code-block, code-tabs, component-preview, component-source), which install into components/docs/. Search it from the CLI:
npx shadcn@latest search @ziiz
npx shadcn@latest view @ziiz/buttonProse
Long-form content needs no components. Add typeset to the container and every heading, paragraph, list, code span and table inside binds to a type role. See Prose for the full element set.
<article className="typeset">{children}</article>Agents
The system is written down for coding agents as well as people. Three pieces:
npx shadcn@latest add @ziiz/skillThe skill item installs the ziiz skill into .agents/skills/ziiz/: the vocabulary, the rules a component must follow, and the greps that check them. Claude Code, Codex and Cursor read that folder.
npx shadcn@latest mcp init --client claudeThe shadcn MCP reads the @ziiz entry from components.json, so an agent can search, view and add registry items as tools. --client also takes cursor, vscode and codex.
Every page on this site is also markdown. /llms.txt lists them with descriptions, /llms-full.txt is the guide, the foundation and every component page in one file, and any page is at /llms.mdx/ followed by its path, such as /llms.mdx/components/button.