@j2-health/design-system 0.1.0

package/README.md

@@ -0,0 +1,113 @@
+# Design System
+
+> ⚠️ **This repository is public, and holds UI components only.** No business
+> logic, no customer data, and no details of the private applications that
+> consume it — a component may accept domain data as props, but must not know
+> what that data means. Everything committed here is permanently world-readable,
+> including git history, so a mistake cannot be undone by deleting the file
+> later. See [CLAUDE.md](CLAUDE.md) for the full rules.
+
+## Contributing
+
+### Installation
+
+Make sure to install our pre-commit hooks. They are also verified by CI, but if
+you want to be notified early of linting or type errors, you have to install
+`pre-commit` and run its install step. To do this, run the following:
+
+```bash
+$ PIP_REQUIRE_VIRTUALENV=false pip install pre-commit
+$ pre-commit install
+```
+
+### Usage
+
+#### Storybook
+
+In order to run the storybook, make sure to install node modules with
+`npm install`, and run the following command:
+
+```bash
+$ npm start
+```
+
+#### In-app
+
+There are two ways to consume the design system in a React application.
+
+##### As an npm package (preferred)
+
+The library is published to npm as `@j2-health/design-system`:
+
+```bash
+$ npm install @j2-health/design-system
+```
+
+The package ships a prebuilt bundle plus type declarations, and expects the
+consuming app to provide the peer dependencies listed in `package.json`
+(react, antd, formik, highcharts, tailwindcss, ...).
+
+Wire it up in three places:
+
+1. **Components** — import from the package root:
+
+   ```tsx
+   import { Button, AppConfigProvider } from '@j2-health/design-system'
+   ```
+
+2. **Styles** — import the compiled component styles once (e.g. in your app
+   entry), and pull the base stylesheet (design tokens, `@tailwind`
+   directives, base element styles) into your own CSS pipeline:
+
+   ```tsx
+   // app entry
+   import '@j2-health/design-system/style.css'
+   ```
+
+   ```css
+   /* your root stylesheet — processed by YOUR Tailwind/PostCSS build */
+   @import '@j2-health/design-system/stylesheets/index.css';
+   ```
+
+3. **Tailwind** — use the preset and scan the package's compiled output so
+   utility classes used inside components are generated by your build:
+
+   ```ts
+   // tailwind.config.ts
+   import { tailwindPreset } from '@j2-health/design-system/tailwind'
+
+   export default {
+     presets: [tailwindPreset],
+     content: [
+       './src/**/*.tsx',
+       './node_modules/@j2-health/design-system/dist/**/*.{js,cjs,css}',
+     ],
+   }
+   ```
+
+##### As a git submodule (legacy)
+
+Include this repo as a git submodule and compile its raw TypeScript source with
+your own toolchain (vite alias + tsconfig paths + tailwind content globs
+pointing into the submodule). The npm entry point for this mode is `index.ts`
+at the repo root; submodule consumers should alias `design-system` to that file
+explicitly, since the package.json `exports` map points at `dist/`, which only
+exists in the published package.
+
+### Publishing to npm
+
+The package is published publicly (the source is public anyway). Publishing is
+tag-driven via
+[.github/workflows/publish-workflow.yml](.github/workflows/publish-workflow.yml)
+and requires the `NPM_TOKEN` repository secret (an npm automation token with
+publish rights on the `@j2-health` org).
+
+To release a new version from `main`:
+
+```bash
+$ npm version minor        # or patch / major — bumps package.json and creates the vX.Y.Z tag
+$ git push origin main --follow-tags
+```
+
+The workflow verifies the tag matches `package.json`, runs lint and tests,
+builds the library, and publishes.