@plattar/react-components

Shared Plattar UI React component library + Storybook. Published publicly to npm under the @plattar scope (like the other Plattar packages, e.g. @plattar/plattar-api), for use across Plattar projects.

• Storybook (latest, auto-deployed): https://plattar.github.io/react-components/
• React: 19 (peer dependency) · Styling: Tailwind v4 + CSS-variable design tokens

Workflow at a glance

The full lifecycle, and what's automated vs. manual:

            develop on a branch                 merge to master                 release
  ┌───────────────────────────────┐    ┌─────────────────────────┐    ┌──────────────────────────┐
  │ npm run storybook (HMR)        │    │ CI: lint+test+build     │    │ npm version <bump>       │
  │ edit / add components          │ PR │ Storybook → GitHub Pages │    │ git push --follow-tags   │
  │ write stories + tests          │ ─► │ (docs site updates)     │ ─► │ → publishes to           │
  │ npm run lint / test / build    │    │                         │    │   GitHub Packages        │
  └───────────────────────────────┘    └─────────────────────────┘    └──────────────────────────┘
        you                                   automatic on push            you bump, CI publishes

| Trigger | Workflow | Result | | --- | --- | --- | | Push / PR to master or dev | ci.yml | lint + test + library build + Storybook build | | Push to master | deploy-storybook.yml | Storybook deployed to GitHub Pages | | Push a v* tag | publish.yml | package published to npm |

Components

| Atoms | Molecules | | --- | --- | | Button · Badge · Loader · IconButton · ErrorDisplay · SummaryLineItem · FormInput | Modal · ImageUpload · ProductIcon · ProductListItem · ProductItem |

All components emit stable, namespaced marker classes (pl-button, pl-modal, …) plus is-* state classes for targeting; styling itself is Tailwind utilities.

Local development

git clone [email protected]:Plattar/react-components.git
cd react-components
npm install        # installs deps (also runs a build via the prepare hook)
npm run storybook  # Storybook dev server with HMR at http://localhost:6006

Edit any component under src/components/** and the change hot-reloads in Storybook. Stories live in each component's __docs__/ folder.

Installing this repo's dev deps does not need GitHub Packages auth — only projects that consume the published package do (see below).

Scripts

| Script | What it does | | --- | --- | | npm run storybook | Storybook dev server (HMR) on :6006 | | npm run build | Type-check + build the library to dist/ (es + cjs + d.ts + css) | | npm test | Run the Vitest suite (npm run test-watch for watch mode) | | npm run lint | ESLint (auto-fix) | | npm run format | Prettier write | | npm run build-storybook | Static Storybook build to storybook-static/ |

Branching

• dev — integration branch; do day-to-day work here (or feature branches off it).
• master — release branch; merging/pushing here deploys the docs site and is where releases are tagged from.

Open a PR into dev (or master); CI must pass before merge.

Adding a new component

Each component is a self-contained folder:

src/components/<Name>/
  <Name>.tsx                 # the component (default export + exported prop types)
  index.ts                   # export { default as <Name> } from "./<Name>"; export * from "./<Name>";
  __docs__/<Name>.stories.tsx
  __test__/<Name>.test.tsx

Then add it to the barrel in src/components/index.ts:

export * from "./<Name>";

Guidelines:

• Use design tokens (Tailwind utilities like bg-theme-button, py-sm, rounded-pill, text-error) instead of hard-coded values.
• Give the root element a stable pl-<name> marker class (+ is-* for states).
• Add a "use client" directive if the component uses hooks/portals.
• Write at least one story (per variant) and one test. __docs__ / __test__ are excluded from the published build.

Releasing: versioning & publishing

Publishing is automated and triggered by a version tag — never publish ad-hoc. From an up-to-date master:

npm version minor      # bumps package.json, commits "v1.1.0", creates tag v1.1.0
                       #   patch  → bug fixes / internal changes
                       #   minor  → new components or additive props (backwards compatible)
                       #   major  → breaking API changes
git push --follow-tags # pushes the commit AND the tag

Pushing the v* tag runs publish.yml, which:

1. npm ci
2. npm run lint
3. npm test
4. npm run build
5. npm publish → the public @plattar scope on npm

This uses the NPM_AUTH_TOKEN repository secret — an npm automation token for the @plattar org (one-time setup in repo Settings → Secrets). The package is published publicly to npm.

Tip: check the run under the repo's Actions tab; the new version then appears on npm.

Manual publish (fallback only)

If you ever need to publish from your machine: npm login (as a member of the @plattar npm org with publish rights), then npm version <bump> and npm publish. Prefer the tag-triggered CI flow.

Deploying the docs (Storybook on GitHub Pages)

Every push to master runs deploy-storybook.yml, which builds Storybook and deploys it to GitHub Pages at:

https://plattar.github.io/react-components/

One-time repo setup (already done): Settings → Pages → Source = "GitHub Actions". Pages for a private repo requires a paid GitHub plan. You can also trigger a redeploy manually from the Actions tab (workflow_dispatch).

Using the library (consumers)

It's a public npm package — just install it (no auth/.npmrc needed):

npm install @plattar/react-components

import "@plattar/react-components/styles"; // tokens + utilities + keyframes (once, at app root)
import { Button, Modal, ProductItem } from "@plattar/react-components";

Theming

The stylesheet ships a CSS-variable token layer. Brand/theme colours and fonts are runtime-overridable — set them on <body> (or any ancestor) and components update live:

document.body.style.setProperty("--theme-button-background", "#c0102f");
document.body.style.setProperty("--theme-button-color", "#ffffff");
document.body.style.setProperty("--heading-font", "Poppins, sans-serif");