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 vega

init 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.

components.json
{
  "registries": {
    "@ziiz": "https://raw.githubusercontent.com/nafisazizir/ziiz/main/apps/www/public/r/{name}.json"
  }
}

Add the theme.

npx shadcn@latest add @ziiz/theme --overwrite

One 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.

app/layout.tsx
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.

app/layout.tsx
<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/button

After 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.

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 shadcn

tw-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.

app/globals.css
@import "tailwindcss";
@import "tw-animate-css";
@import "shadcn/tailwind.css";
@import "@nafisazizir/ziiz/theme.css";

Re-export cn.

lib/utils.ts
export { cn } from "@nafisazizir/ziiz/cn"

Fonts and dark mode, as above.

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/button

Prose

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/skill

The 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 claude

The 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.

Go to a page

Search every page in the navigation.