@propertechnologies/kimchi

v0.2.5

Published

21 hours ago

Kit for Interactive Modular Components and Human-centered Interfaces

Downloads

1,111

0High
0Medium
0Low

roboshoes

sotoyjuan

andrescampuzanoproper

jmorazano.proper

Kimchi 김치

Kit for Interactive Modular Components and Human-centered Interfaces.

A React component library for Proper Technologies apps, built on shadcn/ui + Tailwind CSS v4, with Microsoft Clarity analytics baked in. Consumed by Next.js apps (sales-portal, proper-portal). The Vue equivalent is Ajiaco.

Kimchi is the packaged home of the Proper design system (ported from theseus @proper/ds): design tokens (light/dark), self-hosted Inter + Newsreader fonts, 21 primitives, and 17 composites. Design docs live in docs/ — start with docs/design-system-skill.md and docs/ux-philosophy.md; raw tokens are in docs/tokens.json.

Docs site (Storybook): kimchi.engineering-95d.workers.dev — components, full-page showcases, and the brand book. npm: @propertechnologies/kimchi Visual regression: Chromatic dashboard

Install

npm install @propertechnologies/kimchi

react and react-dom (v19+) are peer dependencies.

Usage

// app/layout.tsx (Next.js App Router)
import "@propertechnologies/kimchi/styles";
import { ClarityProvider } from "@propertechnologies/kimchi/analytics";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ClarityProvider projectId={process.env.NEXT_PUBLIC_CLARITY_ID}>
          {children}
        </ClarityProvider>
      </body>
    </html>
  );
}

import { Button, Input } from "@propertechnologies/kimchi";

export function Example() {
  return (
    <div>
      <Input placeholder="Email" />
      <Button>Save</Button>
    </div>
  );
}

Dark mode is class-based: add class="dark" to <html> (tokens flip automatically; light is the :root default).

Coding with Claude Code

Kimchi ships a Claude Code plugin so anyone can build on-brand React/Next.js apps just by describing what they want — Claude prioritizes kimchi components, tokens, and the Proper UX philosophy automatically.

/plugin marketplace add propertechnologies/kimchi
/plugin install kimchi

That's it. Open any React/Next.js repo and describe the UI ("build me a metrics dashboard", "add a settings page") — the kimchi skill activates on its own and generates code using this library. The skill lives in plugin/skills/kimchi/SKILL.md and is versioned with the package, so it never drifts from the components it documents.

Components

Primitives (UI/* in Storybook): Avatar, Badge, Button, Card, Checkbox, Dialog, DropdownMenu, Input, Label, ScrollArea, Select, Separator, Sheet, Skeleton, Spinner, Switch, Table, Tabs, Textarea, Tooltip

Composites (Composites/*): AppShell, CodeBlock, DoDont, EditorialHeader, EmptyState, Fade, Logo, MetricCard, Presence, PromptInput, ResourceId, Reveal, SectionHeading, StreamingText, ThinkingIndicator, Timestamp, ToggleGlow

Tokens: Proper palette (--bg-*, --text-*, --border-*, --accent-lavender/--accent-gold, semantic) with a ShadCN alias layer (--primary, --muted, …), spacing/radius/shadow scales, and Tailwind utilities for all of them (bg-bg-surface-1, text-text-secondary, px-md, shadow-focus, …).

Fonts: Inter (400/500/700) and Newsreader italic (400/500) are self-hosted — latin subset woff2 shipped in dist/fonts, @font-face included in the stylesheet. No Google Fonts / fontsource dependency for consumers.

Entry points

| Import | What it is | | --- | --- | | @propertechnologies/kimchi | React components + cn() util | | @propertechnologies/kimchi/styles | Compiled Tailwind stylesheet (import once) | | @propertechnologies/kimchi/analytics | Microsoft Clarity provider + hooks |

Development

npm install
npm run storybook        # component workbench at http://localhost:6006
npm run test             # vitest unit tests (jsdom)
npm run build            # build the publishable package (dist/)
npm run build-storybook  # static Storybook site

Node 22 (see .nvmrc) — vitest's jsdom needs require(ESM) support (Node ≥ 22.12).

Adding shadcn components

npx shadcn@latest add <component>   # drops source into src/components/ui/

Then re-export it from src/index.ts and add a *.stories.tsx alongside it.

Publishing

Publishing is automatic. On push to master, GitHub Actions compares the package.json version against what's on npm; if it changed, it builds and runs npm publish. To release: bump version in package.json and merge to master. PRs into master are gated by the Version check workflow — they fail until the version is ahead of npm (npm version patch|minor|major --no-git-tag-version).

Docs site (Storybook on Cloudflare)

Every push to master also deploys the built Storybook — components, showcase pages, and brand book — to Cloudflare Workers (wrangler.toml, assets-only worker named kimchi on the Proper account, free workers.dev subdomain):

https://kimchi.engineering-95d.workers.dev

Repo secrets required: NPM_TOKEN (publish), CHROMATIC_PROJECT_TOKEN (visual tests), CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID (docs deploy).

Notes

As of 0.2.3, @propertechnologies/kimchi/styles ships the complete token utility surface — every bg-*/text-*/border-* token class, spacing, radius, fonts, and their hover:/focus-visible:/md:/lg:/dark: variants (forced in via @source inline(...)). Consumers can write any token class without their own Tailwind config. Before 0.2.3 the stylesheet was purged to kimchi's internal usage, so consumer classes could silently resolve to nothing.
@propertechnologies/kimchi/styles ships Tailwind's base/preflight. If a consuming app already loads Tailwind preflight, dedupe to avoid double base styles.
Interactive components carry "use client"; the build preserves the directive for Next.js RSC.