Lexsys

Audience: Users, contributors, and evaluators

Lexsys is an early-stage registry-first React UI framework built on Base UI, Tailwind CSS, and a design-token system.

Lexsys installs editable component source code directly into your project instead of requiring you to import black-box runtime components. You own the code — edit it, delete it, style it however you want.

Current MVP

The current implementation focuses on supported consumer starters:

• Vite React setup through lexsys init vite
• Next.js App Router setup through lexsys init next (pinned Next.js 15.3.3)
• Tailwind v4 wiring for Vite and Next.js consumers
• token and theme CSS installation
• a growing Base UI-backed installable catalog — 49 items (42 primitives, 6 blocks, 1 template) — see docs/reference/ui/UI_CATALOG.md
• conflict-aware installs with no silent overwrites
• local playground for package/export/style verification

Additional framework starters, remote registry trust policy (signatures / allowlists), and richer migration tooling are planned but not complete yet. Remote registry manifest fetch over HTTPS is supported with local fallback.

Quick Start

Early preview install from npm (@next dist-tag):

npx @dalexto/lexsys@next init vite my-app
cd my-app

Or a new Next.js App Router consumer:

npx @dalexto/lexsys@next init next my-app
cd my-app

Or initialize Lexsys inside an existing supported Vite app from that app's root (auto-detects scaffold):

npx @dalexto/lexsys@next init

Monorepo development (after pnpm cli:build from this repository) uses the lexsys binary directly:

lexsys init vite my-app
cd my-app

Then add components:

lexsys add button
lexsys add input
lexsys add card
lexsys add select
lexsys add dialog
lexsys add dashboard-shell   # template + transitive deps (Sidebar, primitives, …)
lexsys list                  # grouped by layer: Primitives, Blocks, Templates

Most commands have short aliases: a (add), up (update), ls (list), st (status), dr (doctor), rm (uninstall), reg (registry), cfg (config), create (init). Run any command with --help for per-command usage.

All layers install flat under paths.components (default src/components/ui/). The CLI rewrites cross-layer imports to sibling paths on install.

Component files are installed as editable source code. Shared utilities go under src/lib and token/theme CSS goes under styles:

src/components/ui/Button/
├── Button.tsx
├── Button.types.ts
└── Button.variants.ts

src/components/ui/Sidebar/          ← block (same flat root as primitives)
src/components/ui/DashboardShell/   ← template

src/lib/utils.ts
styles/tokens.css
styles/theme.css
lexsys.config.json

The generated config tracks paths, aliases, Tailwind v4 entrypoint, selected CLI style alias, installed component names, and an optional remote registry URL:

{
  "style": "default",
  "paths": {
    "components": "src/components/ui",
    "utilities": "src/lib",
    "styles": "styles"
  },
  "aliases": {
    "components": "@/components/ui",
    "ui": "@/components/ui",
    "utils": "@/lib/utils",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "tailwind": {
    "version": "v4",
    "css": "src/style.css"
  },
  "installed": [],
  "registryUrl": null
}

Styling Model

Lexsys is designed to work directly with Tailwind utilities:

import { Button } from "@/components/ui/Button/Button"

export function App() {
  return <Button className="w-full">Save</Button>
}

The default component variants consume semantic Lexsys tokens under the hood:

<Button variant="primary" size="md">
  Create
</Button>

Users can style locally with Tailwind classes or theme globally by overriding the CSS variables generated by @dalexto/lexsys-tokens. Variable names follow the pattern --lex-<token-path>, for example:

/* override the primary action base color */
--lex-action-primary-base: #16a34a;

Architecture

The install flow is:

packages/tokens   →  generated CSS (tokens.css, theme.css)
packages/ui       →  reference primitives, blocks, templates
packages/registry →  installable templates + metadata
packages/cli      →  reads registry, installs into consumer project
                           ↓
                   consumer project (user-owned code, flat ui/ install)

Package responsibilities:

• packages/tokens — token source, generated CSS outputs, and DTCG artifacts
• packages/ui — reference primitives, blocks, and templates (not what the CLI ships to users)
• packages/registry — installable templates and metadata
• packages/cli — installs registry items into user projects
• apps/playground — optional monorepo smoke (maintenance-only); consumer validation uses external sandbox — see docs/operations/TESTING.md

See docs/ARCHITECTURE.md and docs/reference/ui/UI_COMPOSITION.md for the full system design.

CLI

Common commands:

lexsys init
lexsys init vite [directory]
lexsys init next [directory]
lexsys add [components...]
lexsys update [components...] | --all
lexsys list [--json]
lexsys status
lexsys doctor
lexsys uninstall [components...] [--with-deps]
lexsys registry [--summary | --source | --local | --remote]
lexsys config [--path | --exists | --set-registry-url <url> | --clear-registry-url]
lexsys version

See docs/reference/cli/CLI.md for the full command reference.

Stability

Stable enough to build against in the MVP:

• lexsys init vite [directory] and lexsys init next [directory]
• lexsys init inside supported Vite apps
• lexsys add <component> for bundled local registry items (primitives, pilot blocks/templates)
• lexsys list grouped by install layer (Primitives, Blocks, Templates)
• lexsys uninstall --with-deps to remove registry orphans after uninstall
• lexsys update, lexsys update --all, and lexsys update --sync / --utilities / --styles for tracked components and shared resources
• default config paths and aliases
• Tailwind v4 CSS entrypoint wiring
• installed component ownership under paths.components (default src/components/ui)
• token/theme CSS install under styles/tokens.css and styles/theme.css

Internal or still evolving:

• token authoring internals in packages/tokens
• registry item generation internals
• update conflict resolution and migration tooling
• blocks/templates pilot quality and mobile composition QA — see docs/REVIEW_TODO.md
• remote registry hosting and version policy
• additional CLI style aliases or token presets beyond default / lexsys

Planned but not current API:

• additional framework starters beyond Vite and Next.js App Router
• predefined theme/style preset selection beyond default / lexsys
• richer migration workflows and remote registry trust policy

Maintainers

Start at docs/INDEX.md for the full documentation map.

Doc	Purpose
docs/INDEX.md	Documentation routing hub
docs/reference/ui/UI_CATALOG.md	Installable inventory — compound vs leaf, exports, registry item name
docs/reference/ui/UI_COMPOSITION.md	Composition rules and install layers
docs/ROADMAP.md	Long-term direction and monorepo optimization phases (M1–M11)
docs/REVIEW_TODO.md	Active execution queue and known gaps
docs/operations/SCRIPTS.md	Monorepo pnpm script names and CI reference
docs/operations/TESTING.md	Test coverage and verification workflows
docs/contributors/CONTRIBUTING.md	Branch, check, and commit expectations
AGENTS.md	Agent routing and repo skills index

Development

Install dependencies:

pnpm install

Run the main gate before merging:

pnpm check

For the full script reference (per-package shortcuts, sync workflows, CI), see docs/operations/SCRIPTS.md.

Run the playground (optional monorepo smoke — category nav for quick component scans):

pnpm playground:dev

For CLI/registry install verification, use an external consumer sandbox — see docs/operations/TESTING.md.

Status

Lexsys is not production-ready yet. Vite and Next.js install flows are working; the installable catalog is documented in docs/reference/ui/UI_CATALOG.md. Blocks/templates are installable but not yet marked stable — see docs/REVIEW_TODO.md.

License

MIT