Architecture

Source layout

The framework is vendored in scss/ at the repository root (origin: katanakit-css@0.12.5) and ships inside the katanakit-js package, so consumers can compose it module by module:

scss/
├── main.scss          # Entry: reset + tokens + every utility class generator
├── _reset.scss        # Preflight (Tailwind-style)
├── _variables.scss    # Design tokens: fonts, spacing, radius, shadows, palettes
├── _functions.scss    # Pure functions (unit, color, fluid)
├── _mixins.scss       # Breakpoints, grid, flex, @apply and generators
├── _utilities.scss    # Utility maps + class generators
├── demo.scss          # Demo entry (main + example components)
└── components/
    └── _index.scss    # Example components built with @apply

Module	Documented in
main.scss	Getting Started
_variables.scss	Design Tokens · Colors · Breakpoints · Dark Mode
_functions.scss	Functions
_mixins.scss	@apply · Grid · Flexbox · API Reference
_utilities.scss	Utilities
_reset.scss	Preflight only — covered by Getting Started.

Design philosophy

1. Map-driven — all values come from !default maps that consumers can override
2. Opt-in generation — utility classes are generated by explicit mixins, not magic
3. Zero runtime — pure SCSS compilation, no JavaScript
4. Composable — import what you need, leave what you don't

Build pipeline

@katanakit/ui compiles the framework and the component styles, then concatenates both into the published artifact:

bun run build:ui
# packages/ui/dist/base.css        ← scss/main.scss
# packages/ui/dist/components.css  ← component classes (inside @layer katana)
# packages/ui/dist/styles.css      ← base + components (exported as katanakit-js/styles.css)

The docs site consumes packages/ui/dist/styles.css through a Vite alias, so every demo is styled by the same artifact users install.