Steez UI
GitHubnpm

Authoring model

Add a component, document it, and generate its install files.

Source of truth

Author once in the canonical packages. This Next app is documentation and discovery only — not a second component tree.

  • packages/ui

    React primitives (.tsx + .module.css).

  • packages/theme

    Design tokens and Tailwind preset. Consumers import @steez-ui/theme/tokens.css.

  • packages/icons

    Icons and shared size and stroke settings.

  • packages/react

    Legacy Tailwind/CVA bundle — maintenance only. Do not author new primitives here.

Three install paths

Every published primitive is generated from the same canonical source and can be used as an npm dependency, a source-level registry install, or a standalone file copy. Choose packages for shared updates, the registry for source ownership with automatic dependency wiring, or a standalone copy for a one-file paste into a React app.

  • npm packages

    Shared updates across apps (Phantasy, etc.). Install the canonical stack:

    pnpm add @steez-ui/theme @steez-ui/icons @steez-ui/ui

    Import tokens once at the app root, then import components from the package:

    import "@steez-ui/theme/tokens.css"; import { CyberpunkTile } from "@steez-ui/ui";
  • shadcn registry (/r-steez)

    Source-level install via JSON under public/r-steez/ (served as /r-steez/*.json). Example:

    pnpm dlx shadcn@latest add https://steez-ui-6v5.pages.dev/r-steez/cyberpunk-tile.json

    Import the copied styles/steez/tokens.css once and use local imports from components/steez. Registry installs do not require Steez npm packages. Legacy Boston / motion demo blocks live under /r/*.json only — do not mix them with package primitives.

  • standalone copy (/copy/steez)

    Open a component's generated .tsxfile, copy the entire file, and paste it into your project. CSS, local helpers, icons, and theme fallbacks are embedded; no Steez packages are needed.

    https://steez-ui-6v5.pages.dev/copy/steez/cyberpunk-tile.tsx

    Generated copies should be customized locally; edit the canonical package source when publishing an update.

Component presets

Install a group of related components with a preset: surfaces, motion, or app-shell. Use an individual item URL when you need one component.

Add a primitive (checklist)

Update the package, catalog, preview, and generated files together.

  • 1. Component + CSS module

    Add packages/ui/src/components/MyThing.tsx and MyThing.module.css. Prefer CSS modules and design tokens over hard-coded palette values. Export the component and its props type from the TSX file.

  • 2. Package export

    Re-export from packages/ui/src/index.ts (named export + props type), matching the existing pattern:

    export { MyThing, type MyThingProps } from "./components/MyThing.js";
  • 3. Catalog entry

    Add metadata to COMPONENT_MANIFEST in lib/docs/component-manifest.mjs: slug, title, description, category, package entrypoint and exports, registry files, dependencies, and preview loader. The slug names the component route and registry item. Add summary, usage, related components, and tags to COMPONENT_DOC_DETAILS in lib/docs/component-catalog.ts.

  • 4. Docs preview

    Wire a preview loader in components/docs/component-preview.tsx (PREVIEW_MAP). Lightweight demos go in components/docs/previews/preview-*.tsx; give heavy WebGL/canvas demos a dedicated file under components/docs/previews/ and a dynamic import so they stay code-split.

  • 5. Generate install files

    The generator reads component definitions from the manifest. Generate the registry payloads in public/r-steez/ and standalone files in public/copy/steez/:

    pnpm registry:generate

    Verify that generated install files resolve:

    pnpm test:registry-smoke
  • 6. Build packages + verify the page

    Build the canonical package graph, then open the component page:

    pnpm build:packages

    With pnpm dev, visit /components/my-thing and confirm preview, usage, package install, and /r-steez/my-thing.json all look correct.

  • 7. Tokens in consumer apps

    Package consumers import @steez-ui/theme/tokens.css. Registry consumers import the copied styles/steez/tokens.css. Load tokens once in the root layout or global stylesheet so CSS module variables resolve. Do not bundle tokens inside each primitive.

Verification commands

Use the root scripts from package.json after changing packages, catalog, or registry:

  • pnpm typecheck

    Checks the canonical packages and docs app without building (tsc -p tsconfig.json --noEmit).

  • pnpm test

    Vitest suite (catalog shape, registry parity, package unit tests).

  • pnpm registry:generate

    Writes registry JSON and standalone TSX files from scripts/generate-registry.mjs.

  • pnpm test:registry-smoke

    Smoke-checks generated registry install payloads (scripts/registry-install-smoke.mjs).

  • pnpm lint

    Runs ESLint across the repository.

  • pnpm registry:build

    Legacy Boston surface only (shadcn build → public/r). Not the package-primitive path.

Site map