@reapit/elemental

A complementary React design system for Reapit, built on ShadCN/ui with Tailwind CSS v4. Full DS alignment with the official Reapit Elements design system — 70+ themed components, 12 page patterns, and full ShadCN registry support.

Elemental works alongside @reapit/elements — both packages can be installed side-by-side. Elemental is designed for new projects and greenfield features; existing code using Elements continues to work without changes.

Quick Start (Consumers)

Option 1: NPM Package

yarn add @reapit/elemental

/* In your global CSS */
@import '@reapit/elemental/globals.css';

import { Button, Card, Input, DataTable } from '@reapit/elemental'

Option 2: ShadCN Registry (copy-paste)

// components.json
{
  "registries": {
    "@reapit": "https://elemental.prod.paas.reapit.cloud/r/{name}.json"
  }
}

npx shadcn add @reapit/button
npx shadcn add @reapit/data-table
npx shadcn add @reapit/login-01

Relationship to @reapit/elements

| Aspect | @reapit/elements | @reapit/elemental | | ------------- | -------------------------- | ---------------------------- | | Status | Production (v4), beta (v5) | New package (v1) | | Styling | Custom CSS / CSS modules | Tailwind CSS v4 + CSS vars | | AI tooling | None | MCP Server, Skills, llms.txt | | Page patterns | None | 12 ShadCN Blocks (themed) | | Can co-exist? | Yes | Yes |

Teams can adopt Elemental incrementally — import components from @reapit/elemental for new features while existing pages continue using @reapit/elements.

Adopting from Elements v5

| Elements v5 | Elemental | Notes | | ------------------------------------------------ | ------------------------------------------------------------------------------ | ----------------------------------------- | | import { Button } from '@reapit/elements' | import { Button } from '@reapit/elemental' | Same named export pattern | | import { TextInput } from '@reapit/elements' | import { Input } from '@reapit/elemental' | Renamed to match ShadCN | | import { Divider } from '@reapit/elements' | import { Separator } from '@reapit/elemental' | Renamed to match ShadCN | | import { PrimaryTabs } from '@reapit/elements' | import { Tabs, TabsList, TabsTrigger, TabsContent } from '@reapit/elemental' | Composition pattern | | Linaria CSS-in-JS | Tailwind CSS v4 | @import "@reapit/elemental/globals.css" | | data-variant props | variant prop (CVA) | Same visual result | | ButtonNamespace.Props | Button.Props | Namespace pattern preserved |

Key Differences from Elements

• Styling: Tailwind CSS v4 instead of Linaria. Import globals.css for the theme.
• Compound components: Sub-components are separate named exports (e.g., DialogContent, DialogTitle) instead of namespace members (Dialog.Content).
• Select: Rebuilt on Base UI Select primitives. Different API surface but equivalent functionality.
• Badge: Generic variants (default, secondary, destructive) replace semantic v5 variants (success, pending, danger).

Items to Revisit

• Elements v5 Badge semantic variants: Now resolved — Badge supports success, pending, warning, danger, inactive, accent-1, accent-2 via CVA (v1.1.0+).
• Elements v5 Input rich features: isBusy, leadingIcon, prefix, suffix — need composing on top of ShadCN Input.
• Elements v5 Checkbox baked-in label: ShadCN Checkbox is bare primitive — labels composed via <Label> + <Field>.
• Codemods: Elements→Elemental adoption codemods not yet written. Reference v4→v5 codemods at reference/elements-v5/codemods/.
• Dark mode validation: Warning alert dark mode (olive-brown background, low contrast) and Inactive badge visibility deferred to a follow-up release.
• Playwright visual baseline: Phase 4 QA screenshots captured manually in plan/screenshots/phase-4-final/. Automated visual regression baseline not yet committed to the repo.
• MCP server: ShadCN MCP resolution of @reapit registry items not yet validated.

Development (Contributors)

Prerequisites

Before starting execution, ensure the following are in place:

• Node.js: v22 LTS (>=22.18.0)
• Package manager: Yarn 4 (Berry). The repo includes .yarnrc.yml. Run corepack enable to use the bundled Yarn version.
• Reference codebase: Cloned automatically into reference/elements-v5/ when you run yarn install (via the prepare script). Requires GitHub access to reapit-global/gbl-ds-elements.
• Figma access: You need edit/view access to the Reapit Design System file
• Figma MCP server: Required for design token extraction and design review. Set up with:

  claude mcp add --transport http figma https://mcp.figma.com/mcp

  After adding, authenticate via the browser prompt when first invoked.

How to Use These Files

This plan is structured for import into Claude Code. Each file serves a specific purpose and can be referenced by agents during execution.

File Structure

gbl-elemental/
├── plan/                              # Strategy & roadmap (read by humans + AI)
│   ├── 00-executive-summary.md        # CTO/CPO presentation material
│   ├── 01-architecture.md             # Technical decisions, repo structure, theming
│   ├── 02-roadmap.md                  # Phased milestones with task checklists
│   └── 03-component-workflow.md       # Per-component pipeline and quality gates
│
├── agents/                            # Agent role definitions (read by Claude Code)
│   ├── principal-fe-agent.md          # Lead engineer orchestration instructions
│   ├── product-design-agent.md        # Design review sub-agent
│   ├── documentation-agent.md         # Storybook story writer sub-agent
│   ├── automation-agent.md            # Test writer sub-agent (Vitest + Playwright)
│   └── devops-agent.md                # CI/CD + AWS infrastructure sub-agent
│
├── reference/                         # Read-only reference material
│   ├── README.md                      # Guide to key paths in the Elements v5 codebase
│   └── elements-v5/                   # Auto-cloned: current Elements v5 codebase (gitignored)
│
└── README.md                          # This file

Execution Sequence

Phase 0: Foundation

0. Registry Validation Spike: Scaffold a minimal ShadCN custom registry (one dummy component), run npx shadcn build, and verify npx shadcn add can consume it from localhost and S3. This is a decision gate — if the custom registry mechanism doesn't work, the plan needs revision before proceeding.
1. Read: plan/01-architecture.md — understand the target repo structure
2. Execute as Principal FE: Scaffold the repository following the architecture doc
   • 2a. Figma MCP extraction: Use get_variable_defs against the Reapit DS file to extract real oklch colour tokens and populate globals.css
3. Invoke DevOps Agent: Hand off agents/devops-agent.md context and ask it to create the CI/CD pipelines and CDK stack
4. Execute as Principal FE: Create globals.css with the Reapit theme mapping (using tokens from step 2a)
5. Invoke Product/Design Agent: Ask it to review the theme for brand alignment (uses Figma MCP to compare against source)
6. End-to-End Smoke Test: Verify all 9 checkpoints from plan/02-roadmap.md Task 0.5 (Storybook builds, NPM beta publishes, registry resolves, Tailwind v4 compiles, etc.)

Phase 1-2: Components

For each batch in plan/02-roadmap.md:

1. Execute as Principal FE: Add components using npx shadcn add
2. Invoke Product/Design Agent: Review each component with the themed output
3. Implement feedback: Apply sensible suggestions
4. Invoke Documentation Agent: Generate stories for each component
5. Invoke Automation Agent: Generate tests for each component
6. Execute as Principal FE: Review all output, fix issues, merge

Phase 3: Blocks

Same flow as components, but:

• Blocks are composed from multiple components
• Product/Design review focuses on full-page UX
• Visual tests use full-page screenshots at multiple viewports

Phase 4: AI Tooling

1. Execute as Principal FE: Create CLAUDE.md skills file
2. Execute as Principal FE: Create llms.txt
3. Test: Verify MCP server, Skills, and llms.txt work with Claude Code

Phase 5: Launch

1. Execute as Principal FE: Write adoption guides and optional codemods
2. Execute as DevOps Agent: Verify production pipeline
3. Checkpoint: Final review gate with VPE/CTO/CPO sign-off
4. Execute: Publish @reapit/[email protected] to NPM and deploy production Storybook

Prompt Patterns for Claude Code

Starting a Phase

I'm working on Elemental, a ShadCN-based design system for Reapit
(complementary to @reapit/elements).
Read the plan files in /plan/ and the agent instructions in /agents/.
We are currently in Phase [N]. Execute the tasks for this phase
following the principal-fe-agent.md instructions.

Invoking a Sub-Agent

Acting as the [product-design / documentation / automation / devops] sub-agent
(see agents/[name]-agent.md for your full instructions), please:
[specific task description]

Component Workflow Prompt

Following the component workflow in plan/03-component-workflow.md,
add the following ShadCN components with the Reapit theme:
- Button
- Input
- Label
Execute Steps 1-3 (add, review, refine), then generate Step 4 (stories)
and Step 5 (tests) output.

Review Gate Prompt

We have completed Phase [N]. Please review against the milestone
checklist in plan/02-roadmap.md Phase [N] section.
Report any items that are not yet complete.

Key Principles

1. Theme over customisation: Always prefer CSS variable changes over component code changes
2. Upstream compatibility: Never modify ShadCN component internals in ways that prevent merging upstream updates
3. Zero custom CSS goal: CSS modules are a last resort, documented when used
4. Test everything: No component merges without unit + visual tests
5. Document everything: No component merges without complete Storybook stories
6. AI-first DX: The design system should be as easy for an LLM to use as a human developer
7. Complementary, not competitive: Elemental enhances the Reapit DS ecosystem — it does not replace Elements