Quick link	Description
Web Demo	Web Demo
API	API Server on Railway
Renovate	Package dependency management dashboard
Chromatic	TODO: Storybook component demos & visual regression testing
Bundlemon	TODO: Bundle size monitoring dashboard

Features

	props	configurable	dynamic values	arbitrary values	modes
colors	✅	✅	✅	✅	🏗️
states	🏗️	🏗️	🏗️	🏗️	🏗️
elevation	🏗️	🏗️	🏗️	🏗️	🏗️
typography	✅	✅	✅	🏗️	🏗️
layout	✅	✅	✅	🏗️	🏗️
border	✅	✅	✅	🏗️	🏗️
spacing	✅	✅	✅	🏗️	🏗️
sizing	✅	🏗️	✅	✅	🏗️

Decisions

• No build tooling integrations needed bc no one wants to do that. it never works. hard to keep up with ecosystem.
• CLI + package.json imports buildtime stylesheet.
• Typescript, typescript, typescript.
• Bun first.
• ESM only.
• Tailwind inspired. Carry over the good parts, but with prop driven angle.
• Don't add complex components. Show recipes. Make it easy to pull in examples, shadcn style.

Inspiration

• shadcn
• frogui
• open-props
• mastercss

Prop driven system, zero runtime + purged css output

Build time stylesheets

The output stylesheet should only include utility classnames which are used based on source code.

Tip

This command should be run at the root of your workspace, where your tsconfig.json lives.

katcn css --outFile ./styles.css

CSS variables

Should treeshake to include only the CSS variables used based on utility classnames present. For example, given the following snippet:

import { VStack } from 'katcn';

<VStack bg="accent" />

Should output the following (excluding CSS reset for brevity):

layer theme {
  :where(html) {
    --hue-blue: 261;
    --hue-lightness-9: 49%;
    --hue-chroma-9: 0.19;
    --color-blue-9: oklch(var(--hue-lightness-9) var(--hue-chroma-9) var(--hue-blue));
    --palette-core-accent: var(--color-blue-9);
  }
}

@layer utilities {
  .backgroundColor-accent {
    background-color: var(--palette-core-accent);
  }
  .display-flex {
    display: flex;
  }
  .flexDirection-vertical {
    flex-direction: column;
  }
}

Conditional expressions

Should treeshake output to include backgroundColor-accent and backgroundColor-secondary classnames.

import { VStack } from 'katcn';

function Example({active}: {active: boolean}) {
  const backgroundColor = active ? 'accent' : 'secondary';
  return (
    <VStack bg={backgroundColor} style={{ width: 120, height: 120 }} />
  )
}

@layer theme {
  :where(html) {
    --hue-blue: 261;
    --hue-lightness-9: 49%;
    --hue-chroma-9: 0.19;
    --color-blue-9: oklch(var(--hue-lightness-9) var(--hue-chroma-9) var(--hue-blue));
    --color-gray-2: lab(86.0704% -2.10407 -6.31995);
    --palette-core-accent: var(--color-blue-9);
    --palette-background-secondary: var(--color-gray-2);
  }
}
@layer utilities {
  .backgroundColor-accent {
    background-color: var(--palette-core-accent);
  }
  .backgroundColor-secondary {
    background-color: var(--palette-background-secondary);
  }
  .flexDirection-vertical {
    flex-direction: column;
  }
  .display-flex {
    display: flex;
  }
}

Dynamic values

Should treeshake stylesheet output to include backgroundColor-accent, width-1/3, width-1/2 and width-1/3 classnames.

import { VStack } from 'katcn';

function Example({column}: {column: 1 | 2 | 3}) {
  const width = `${column}/3` as const;
  return (
    <VStack bg="accent" width={width} style={{ height: 120 }} />
  )
}

@layer theme {
  :where(html) {
    --hue-blue: 261;
    --hue-lightness-9: 49%;
    --hue-chroma-9: 0.19;
    --color-blue-9: oklch(var(--hue-lightness-9) var(--hue-chroma-9) var(--hue-blue));
    --palette-core-accent: var(--color-blue-9);
  }
}
@layer utilities {
  .backgroundColor-accent {
    background-color: var(--palette-core-accent);
  }
  .flexDirection-vertical {
    flex-direction: column;
  }
  .width-1\/3 {
    width: 33.33%;
  }
  .width-2\/3 {
    width: 66.67%;
  }
  .width-3\/3 {
    width: 100%;
  }
  .display-flex {
    display: flex;
  }
}

Arbitrary values

Should treeshake stylesheet output to include backgroundColor-accent, height-[120px] and width-[120px] classnames.

import { VStack } from 'katcn';

function Example() {
  return (
    <VStack bg="accent" height={120} width={120} />
  )
}

Install bun

curl -fsSL https://bun.sh/install | bash

bun install

Setup Web

touch apps/web-demo/.env

Update env vars required for web-demo live playground

NEXT_SOCKET_URL=ws://localhost:3001/ws

Setup Websocket Server

touch apps/server/.env

Update env vars for server

SERVER_PORT=3001

Run dev

bun run dev

Setup Mobile

TODO: This might be outdated.

touch apps/mobile-demo/.env

Update env vars

EXPO_TOKEN=GRAB FROM EXPO ACCOUNT SETTINGS
EXPO_PROJECT_ID=GRAB FROM EXPO PROJECT

TODOS

• token only usage
• system
  • states
  • elevation
• assets
  • icons
  • illustrations
• education
  • live playground
    • offer editor setup as consumable package. like react-live
  • palette generator
    • lightness, chroma, hue configuration
  • docgen CLI for API doc generation. is consumable for anyone to use for their own docs
  • sample project
• codemods
  • tailwind codemod for migration
• purger
  • only include icons used
  • vars with same value should be consolidated to single var to reduce css size (i.e. font size for body1 and headline1)
• configuration
  • createSystem function / type safety for components
  • configurable icon set and types
  • purger still works
• modes
  • dark mode
  • hight contrast mode
  • scale mode
• flexiblity
  • arbitrary values
  • dynamic values
  • group selectors?
• motion
  • motion tokens
  • framer motion integration
• figma
  • plugin
  • create system from config
  • dev mode snippets
• react native

Palette Generator

• https://developer.chrome.com/blog/css-relative-color-syntax
• https://developer.chrome.com/docs/css-ui/high-definition-css-color-guide#checking_for_gamut_and_color_space_support
• https://nikhgupta.com/tools/palette-generator
• https://alivault.github.io/color-palette-maker/
• Distnace between hues (i.e. 30). palette size (how many colors 360/number of hues)
• min and max chroma based on lightness and hue