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

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

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

kmartinezmedia / katcn