@cruciblelab/crucible

v1.1.0

Published

22 days ago

Crucible — Code Generation Engine that generates style system/spec-based components for React, Vue, and Angular. No runtime dependencies. You own every file generated.

⚗️ Crucible — Code Generation Engine

Generated once. Yours forever.
A code generation engine that scaffolds production-ready, style system/spec-based components into your project. No wrappers, no black-box libraries. You own every file generated.

Crucible is not a component library — it's a code generation engine. It produces source files that live in your project, not a package that sits in node_modules.

Why Crucible?

| Aspect | Component Library | Crucible | | ------------- | ---------------------- | ----------------------- | | Output | Compiled package | Source files you own | | API | Limited to package API | Edit any generated line | | Updates | npm update | Regenerate or merge | | Bundle | Part of your bundle | Zero runtime footprint | | Customization | CSS overrides only | Full code access |

Crucible generates pure source code that lives in your project. Once generated, Crucible has zero runtime footprint. You read, edit, and extend every line.

# Generate a Button component
npx crucible add Button

# Output: Button/Button.tsx, Button/Button.module.css, Button/README.md
# That's it. No runtime dependencies. Pure code you own.

Features

| Feature | Description | | ------------------------- | ------------------------------------------------------- | | Multi-Framework | React, Vue 3, and Angular with full feature parity | | Style Systems | CSS Modules, SCSS Modules, or Tailwind CSS v4 | | Theme Presets | Built-in minimal and soft with deep merge | | Dark Mode | Automatic OKLCH-based perceptually uniform derivation | | Accessibility | WCAG 2.1 AA-compliant with ARIA, focus rings | | Component Patterns | Professional patterns with variants, sizes, states | | Compound Components | React static props, Vue named slots, Angular projection | | User Ownership | Hash-based protection for user edits | | Dependency Resolution | Auto-scaffolds Button for Select/Dialog | | Interactive CLI | Guided setup with @inquirer/prompts | | Prettier Integration | Auto-format all generated code | | Test Coverage | 448 unit tests + 238 E2E phases |

Installation

Crucible is published on npm as @cruciblelab/crucible and ships a single CLI binary, crucible. There are two ways to run it.

Option 1 — Run with `npx` (no install)

Best for a quick try or one-off generation. npx fetches and runs the latest published version on demand; nothing is added to your project:

npx @cruciblelab/crucible@latest init
npx @cruciblelab/crucible@latest add Button

Option 2 — Add to your project (recommended)

Install Crucible as a project-local dev dependency (not a global package). This pins the version in your package.json / lockfile, so every contributor and CI run generates with the exact same engine:

npm i -D @cruciblelab/crucible
# yarn add -D @cruciblelab/crucible
# pnpm add -D @cruciblelab/crucible

Then invoke the local binary with npx crucible — npx resolves it from node_modules/.bin (no network round-trip, no global install):

npx crucible init
npx crucible add Button

Why not -g (global)? A global install drifts from your project and isn't captured in your lockfile, so different machines can scaffold with different versions. A project-local dev dependency keeps generation reproducible. All examples below assume Option 2 and use npx crucible …; if you prefer the no-install route, swap crucible for @cruciblelab/crucible@latest.

Quick Start

1. Initialize

npx crucible init

Creates a crucible.config.json with your theme, tokens, and style system preferences.

2. Add Components

npx crucible add Button                    # Single component
npx crucible add Button Input Card         # Multiple components
npx crucible add -a                        # Add all components
npx crucible add Button -s tailwind        # Override style
npx crucible add Button -t soft            # Override theme

3. Customize

Update crucible.config.json and regenerate, or edit generated files directly — they're yours.

Available Components

| Component | Variants | Sizes | States | Description | | --------- | -------------------------------------------------------------- | -------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Button | default, primary, secondary, outline, ghost, link, destructive | xs, sm, md, lg, icon | disabled, loading | Compound components, loading spinner | | Input | default, error | sm, md, lg | disabled, error | Password toggle, validation states | | Card | default, hoverable, clickable | sm, md, lg | — | Container with title, onClick, href | | Dialog | default, confirm | sm, md, lg | open, closed | Focus trap, scroll lock, closeable | | Select | default, error | sm, md, lg | disabled, error, open | Keyboard navigation, combobox pattern | | Popover | default, minimal | sm, md, lg | open, closed, modal | Floating-UI positioning, focus trap (modal), click/hover trigger, arrow | | Table | default, striped, bordered, compact | sm, md, lg | loading, empty | Client/server pagination, sorting, single/multi selection, virtualization (5k+ rows), optional caption | | Toast | default, success, error, warning, info, loading | sm, md, lg | enter, visible, exit | Sonner-style notifications: global toast() + <Toaster>, 6 positions, auto-dismiss, action button, rich colors, pause-on-hide | | Form | default, inline | sm, md, lg | disabled, error, submitting | Dependency-free validation engine, react-hook-form adapter, compound (Root/Field/Item/Label/Control/Description/Message/Submit) + schema-driven modes, aria wiring | | Tabs | default, underline, pills | sm, md, lg | disabled | WAI-ARIA tabs pattern: compound (Root/List/Trigger/Content) + schema-driven, controlled/uncontrolled, manual/automatic activation, horizontal/vertical, roving tabindex; per-tab custom rendering (React ReactNode · Vue named slots · Angular TabTemplateDirective) | | Tooltip | default, minimal | sm, md, lg | open, closed | Floating-UI label, role="tooltip" + aria-describedby, hover/focus/click triggers, compound (Root/Trigger/Portal/Content/Arrow), no focus trap, Escape to dismiss | | Label | — | sm, md, lg | disabled | Form label with required marker and htmlFor association | | Separator | — | — | — | Horizontal/vertical divider, role="separator", optional centered label, decorative mode | | Badge | default, primary, secondary, outline, success, warning, destructive | sm, md, lg | — | Status/category label; Tailwind variant classes sourced from the manifest | | Skeleton | default, text, circle, rect | — | — | Loading placeholder with pulse animation, aria-busy, custom width/height | | Avatar | circle, square | xs, sm, md, lg | — | Image with initials fallback on load error, role="img" | | Textarea | default, error | sm, md, lg | disabled, error | Multi-line field with label/hint/error wiring, rows, maxLength, aria-invalid | | Checkbox | default, error | sm, md, lg | disabled, checked, error | Native checkbox with indeterminate (ref/property-bound), label, error | | Switch | — | sm, md, lg | disabled, checked | role="switch" toggle (track + thumb), controlled/uncontrolled | | Alert | default, info, success, warning, destructive | — | — | Inline role="alert" message with severity tint, icon, optional dismiss | | Progress | linear, circular | sm, md, lg | indeterminate | role="progressbar" bar or SVG ring; determinate value or continuous loader | | Breadcrumb | — | sm, md, lg | — | Items-driven nav trail, aria-current="page", custom separator, maxItems collapse | | RadioGroup | — | sm, md, lg | disabled | WAI-ARIA radiogroup, roving tabindex, arrow-to-select; compound (Root/Item) | | Accordion | default, bordered, separated | sm, md, lg | disabled | Collapsible disclosure, single/multiple, aria-expanded + role="region"; compound (Root/Item/Trigger/Content) | | DropdownMenu | default, minimal | sm, md, lg | open, closed | Floating-UI menu with roving items + typeahead, role="menu"; compound (Root/Trigger/Content/Item/Separator/Label) |

Documentation

Documentation — Official docs site
ARCHITECTURE.md — System design and data flow
CONTRIBUTING.md — Contribution guidelines
ROADMAP.md — Future plans

CLI Reference

Note: Commands marked [dev only] are for Crucible development. They show a warning when used in production installations.

Generate Components

crucible add Button                    # Single component (alias: a)
crucible add Button Input Card         # Multiple components
crucible add -a                        # Add all components (alias: a -a)
crucible add Button --stories          # With Storybook story
crucible add Button --framework vue    # Vue framework
crucible add Button --dev             # Output to playground
crucible add Button -s tailwind        # Override style (css, tailwind, scss)
crucible add Button -t soft            # Override theme (minimal, soft)
crucible add Button --force            # Overwrite even if edited
crucible add Button --dry-run          # Preview without writing
crucible add Button --yes             # Skip all prompts (CI mode)
crucible add Button --verbose          # Detailed logging

Setup & Configuration

crucible init              # Scaffold config file (alias: i)
crucible init --yes       # Use defaults (no prompts)
crucible doctor           # Validate setup (alias: d)
crucible list             # Show available components (alias: l)
crucible eject            # Copy preset to config (alias: e)
crucible config           # Show current config (alias: cfg)
crucible config --json    # Raw JSON output

Tokens

crucible tokens            # Regenerate tokens.css (alias: t)
crucible tokens --force    # Force overwrite (alias: t -f)
crucible tokens --dry-run  # Preview without writing

Playground (dev only)

crucible pg:gen           # Generate all 3 framework playgrounds (alias: pg) [dev only]
crucible pg:gen --force   # Clean + regenerate (alias: pg -f) [dev only]
crucible pg:open          # Open Storybook (alias: po) [dev only]
crucible pg:dev           # Start dev server (alias: pd) [dev only]
crucible pg:clean         # Clean all playgrounds (alias: pcl) [dev only]

Cleanup

crucible clean            # Remove generated files (alias: c)
crucible clean --all      # Also remove config (alias: c -a)

Architecture

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Config    │───▶│   Tokens    │───▶│    Model    │───▶│  Templates  │───▶│   Writer    │
│   Layer     │    │   Layer     │    │    (IR)     │    │   Engine    │    │             │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
     │                 │                 │                 │                   │
   crucible.         Theme +            Component          Handlebars          File output
   config.json      user tokens       spec + flags        rendering          + hash tracking

Config Layer — User preferences in crucible.config.json with theme presets
Token Resolver — Maps tokens to CSS variables with OKLCH dark mode derivation
Component Model (IR) — Normalizes data for templates; single source of truth
Template Engine — Handlebars-driven generation with logic-free templates
File Writer — Writes files with hash protection and Prettier formatting

See ARCHITECTURE.md for complete technical details.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting PRs.

Requirements:

All tests pass (npm test) — 448 tests across 48 files
Templates pass audit (npm run audit:templates)
No TypeScript errors (npm run build)

Good first contributions:

Adding new components (Tag, Pagination, Tooltip variants)
Improving documentation
Writing missing tests for existing features
Fixing small bugs in CLI commands

License

Project Status

| Version | Status | Description | | ------------ | ------------ | --------------------------------------------------------------------------------------------- | | v1.1.0 | ✅ Stable | App-building kit — added 14 components (Label, Separator, Badge, Skeleton, Avatar, Textarea, Checkbox, Switch, Alert, Progress, Breadcrumb, RadioGroup, Accordion, DropdownMenu) bringing the library to 25; 448 tests / 238 E2E phases | | v1.0.4 | ✅ Stable | Replaced chalk with ansis, fs-extra with native node:fs, added test:bun script | | v1.0.3 | ✅ Stable | Manual dark mode strategy, Vue SCSS template fixes | | v1.0.0 | ✅ Stable | First stable release — 3 frameworks, 3 style systems, 230 tests + 19 E2E phases |

v1.0.4 Features

Replaced chalk with ansis: Modern terminal styling library
Replaced fs-extra with native node:fs: Zero runtime dependencies
Added test:bun script: Run tests with bun via bun run test:bun

See ROADMAP.md for future plans