A Design System That Ships Alongside Its Apps

JOSUI is an AI-native design system and build tooling monorepo. It packages a React component library, shared utilities, and the apps that consume them: a playground, this portfolio, and the awkwardgroup company site.

Library and apps share one workspace, so every change lands against real screens the same day. There is no isolated demo site standing in for production – the surfaces that ship are the test bed.

The agent layer is first-class. An AGENTS.md contract and scoped skills define how to work in each package, so coding agents and I follow the same playbook across the repo.

The Challenge

As a solo builder shipping several products, I needed a consistent UI foundation that stays out of my way. Most off-the-shelf approaches add ceremony I don’t need; bespoke setups tend to drift between projects.

  • One component library, dogfooded by the apps that depend on it
  • Clear package boundaries so framework-agnostic logic stays portable
  • A single toolchain instead of a stack of fragmented configs
  • An explicit contract for AI agents working across packages and apps

The Approach

I structured the repo as layered packages with explicit boundaries – framework-agnostic core, web-only utilities, React components, and a Tailwind v4 preset – co-located with the apps that consume them. Tooling is intentionally minimal: one root toolchain, one release workflow, one agent contract.

  • @josui/core for pure JS helpers (e.g., color via culori) that run anywhere
  • @josui/core-web for browser-side primitives (clsx + tailwind-merge, hotkeys)
  • @josui/react component library on Radix UI and Tailwind CSS v4
  • @josui/tailwind-preset as a CSS-only Tailwind v4 preset, no token build step
  • @josui/typescript-config with base/browser/node/react targets
  • Vite+ (vp) as a unified toolchain for lint, format, test, build, and orchestration
  • Changesets-driven releases; apps in the same repo dogfood every change
  • AGENTS.md and scoped .claude skills so agentic coding follows the repo conventions

Implementation Highlights

React component library
Built on Radix UI primitives and Tailwind CSS v4, with composable building blocks for forms, navigation, overlays, and content layout. Tested with Vitest and Testing Library, and documented in Storybook.

Core and web utilities
@josui/core stays pure JS so the same logic can run in any environment. @josui/core-web layers in browser concerns like className composition and keyboard shortcuts on top of it.

Tailwind v4 preset
@josui/tailwind-preset distributes design decisions as a CSS-only preset using Tailwind v4’s CSS-first config – no separate token pipeline, no build step, consuming apps just import the preset.

Unified toolchain via Vite+
Linting (oxlint), formatting (oxfmt with Tailwind class sorting), testing (Vitest), building, and task orchestration all run through one command. A vp staged pre-commit hook catches lint, format, and type drift before it lands.

AI-native workflow
AGENTS.md defines the cross-agent workflow; scoped skills under .claude/skills/ teach specific tasks (case-study writing, animations, audits). This is the interface agents work against – treated as first-class artefacts, not docs.

Results

The repo is in active development. Outcomes below reflect the current state rather than a final destination.

  • One workspace powers three apps (playground, this portfolio, the awkwardgroup company site) on the same component library
  • Five packages published to npm: @josui/core, @josui/core-web, @josui/react, @josui/tailwind-preset, @josui/typescript-config
  • Single toolchain replaces a stack of per-package configs – one command for lint, format, test, build
  • Agent contract (AGENTS.md + skills) makes cross-package work as cheap to start for an agent as it is for me

Learnings

Co-locating system and apps keeps the system honest.
The components that ship are the ones I use the next day. Dogfooding in the same repo prevents the “library is great in isolation, awkward in real apps” trap.

Less ceremony, more reps.
Token pipelines, multi-framework adapters, and bespoke build setups all looked attractive on paper and slowed me down in practice. Cutting them out – tokens live in a separate repo, the system is React-only here – made it easier to evolve.

The agent contract is part of the architecture.
AGENTS.md and skill files are not documentation; they’re the interface coding agents work against. Designing them deliberately pays off every time I open the repo.

Technical Summary

Stack: pnpm workspaces, Vite+ (oxlint, oxfmt, Vitest), TypeScript, React 19, Tailwind CSS v4, Radix UI, Storybook, Testing Library, Changesets

Scope: Five published packages (@josui/core, @josui/core-web, @josui/react, @josui/tailwind-preset, @josui/typescript-config) and three internal apps (playground, portfolio, awkwardgroup) sharing one toolchain

Repository: github.com/joakimstrandell/josui

Lets connect if you want to talk design systems or AI-native tooling.