npm.io
1.2.4 • Published 5 months ago

@reapit/elemental

Licence
MIT
Version
1.2.4
Deps
11
Size
2.1 MB
Vulns
0
Weekly
0

@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
  1. 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.
  2. Read: plan/01-architecture.md — understand the target repo structure
  3. 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
  4. Invoke DevOps Agent: Hand off agents/devops-agent.md context and ask it to create the CI/CD pipelines and CDK stack
  5. Execute as Principal FE: Create globals.css with the Reapit theme mapping (using tokens from step 2a)
  6. Invoke Product/Design Agent: Ask it to review the theme for brand alignment (uses Figma MCP to compare against source)
  7. 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/elemental@1.0.0 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