# @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

```bash
yarn add @reapit/elemental
```

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

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

### Option 2: ShadCN Registry (copy-paste)

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

```bash
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](https://www.figma.com/design/6CaivqdlTX0UkFYJkpBKDu/Reapit-DS) file
- **Figma MCP server**: Required for design token extraction and design review. Set up with:
  ```bash
  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/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